release: bump version to 0.71.1

docs/harness-audit.md

@@ -0,0 +1,102 @@
+# Harness Audit
+
+Last audited: 2026-06-26
+
+This audit records the repository state used to add the agent harness. It is a
+compatibility note, not a replacement for existing rules or architecture docs.
+
+## Existing Commands
+
+| Area | Existing Command | Notes |
+| --- | --- | --- |
+| Bootstrap | `./planet.sh init` | Syncs uv/Bun dependencies, creates missing env files, starts data services, seeds defaults. |
+| Start | `./planet.sh start` | Starts backend, frontend, AI Provider, PostgreSQL/Redis, and Motion Agent when available. |
+| LAN start | `./planet.sh start --allow-lan` | Opens frontend/backend/AI Provider ports and requests Windows firewall/port cleanup when needed. |
+| Restart | `./planet.sh restart` | Supports scoped restart flags for backend, frontend, AI Provider, database, and Motion Agent. |
+| Health | `./planet.sh health` | Checks containers, backend `/health`, AI Provider `/health`, frontend, and Motion Agent state. |
+| Logs | `./planet.sh log` | Supports backend, frontend, AI Provider, and Motion Agent log views. |
+| User fallback | `./planet.sh createuser` | Interactive emergency/local account creation. |
+| Destructive reset | `./planet.sh destroy` | Requires confirmation and removes Planet-owned Docker/build/runtime state. Not a validation command. |
+| Backend CI smoke | `cd backend && uv run --frozen --group dev --project .. python -m pytest -s tests/test_api.py tests/test_realtime_sources.py -q` | Mirrors `.gitea/workflows/ci.yaml`. |
+| Frontend build | `cd frontend && bun install --frozen-lockfile && bun run build` | Bun-only workflow. |
+| Root helper | `bun run mock:ais-ws` | Runs `scripts/mock-ais-ws-server.ts` from the root package. |
+
+## Existing Agent Instructions
+
+| File | Status | Notes |
+| --- | --- | --- |
+| `agents.md` | Present | Existing root agent behavior guide. It references `rules.md` and `project_context.md`. |
+| `rules.md` | Present | Mandatory modular rules. Always load `core`, `security`, and `workflow`; load topic modules as needed. |
+| `project_context.md` | Present | Static context. Some roadmap-era stack details are older than the current README/docs. |
+| `.claude/commands/*.md` | Present | Existing command docs for cleanup, docs, goal-driven, and release workflows. |
+| `.codex/skills/*.md` | Present | Existing local skills for cleanup, docs, goal-driven, and release. |
+| `AGENTS.md` | Added by harness | Compatibility entry point that points to existing rules and harness docs. |
+
+## Existing CI Gates
+
+The repository uses `.gitea/workflows/`, not `.github/workflows/`.
+
+| Workflow | Gate |
+| --- | --- |
+| `.gitea/workflows/ci.yaml` | Backend smoke tests, frontend Bun build, Docker build smoke, Helm lint/template. |
+| `.gitea/workflows/release.yaml` | Builds and pushes frontend, backend, and AI Provider images on main/tag/manual release events. |
+| `.gitea/workflows/deploy-staging.yaml` | Deploys Helm release to staging and runs curl smoke tests inside the cluster. |
+
+## Existing Docs And Architecture Maps
+
+| Area | Docs |
+| --- | --- |
+| Current architecture and startup | `README.md` |
+| Technical docs index | `docs/technical/zh/README.md`, `docs/technical/en/README.md` |
+| Documentation rules | `docs/documentation-coverage-rules.md` |
+| Operations | `docs/technical/zh/ops-runbook.md`, `docs/technical/en/ops-runbook.md` |
+| Startup internals | `docs/technical/zh/ops-planet-sh-startup.md`, `docs/technical/en/ops-planet-sh-startup.md` |
+| AI Provider | `docs/technical/zh/agents-aiprovider.md`, `docs/technical/en/agents-aiprovider.md` |
+| Frontend admin | `docs/technical/zh/frontend-admin-frontend-context.md`, `docs/technical/en/frontend-admin-frontend-context.md` |
+| Earth rendering | `docs/technical/zh/earth-frontend-context.md`, `docs/technical/zh/earth-render-layer-order.md`, `docs/technical/zh/earth-layer-style-reference.md` |
+| Plans and history | `docs/plans/README.md`, `docs/deprecated/README.md` |
+
+## Release And Deploy Process
+
+- Release workflow is documented in `.codex/skills/release/SKILL.md` and
+  `.claude/commands/release.md`.
+- Version-bearing files include `VERSION`, `frontend/package.json`,
+  `pyproject.toml`, `uv.lock`, `docs/CHANGELOG.md`, and
+  `docs/version-history.md`.
+- Delivery automation lives in `.gitea/workflows/release.yaml` and
+  `.gitea/workflows/deploy-staging.yaml`.
+- Helm chart entry point is `deploy/helm/planet/Chart.yaml`.
+
+## Missing Or Unclear Areas
+
+- README previously listed `AGENTS.md` in the project tree while only lowercase
+  `agents.md` existed. The harness adds uppercase `AGENTS.md` as a compatibility
+  wrapper and preserves `agents.md`.
+- `project_context.md` includes older roadmap assumptions such as Celery, Kafka,
+  TimescaleDB, MinIO, and UE5 as active stack elements. The current README and
+  technical docs describe Web Earth, React admin, FastAPI, PostgreSQL/Redis, and
+  `aiprovider` as the active local development shape.
+- No safe automatic hook system was already configured. This phase documents
+  manual reminders instead of adding hooks.
+- `.github/workflows/` is absent by design; CI is under `.gitea/workflows/`.
+
+## Conflicts And Preserved Rules
+
+| Conflict Or Tension | Resolution |
+| --- | --- |
+| Prompt suggested `AGENTS.md`; repository already had `agents.md`. | Added a minimal uppercase compatibility entry and preserved the existing lowercase guide. |
+| Harness validation could duplicate CI. | Added wrapper scripts that call existing commands and mirror current CI gates where practical. |
+| Full Docker smoke builds are expensive locally. | Kept them opt-in with `PLANET_HARNESS_DOCKER_SMOKE=1`. |
+| Internal harness docs could clutter public Docs UI. | Kept `docs/HARNESS.md` and `docs/harness-audit.md` as repository docs, not product Docs entries. |
+| Existing frontend toolchain is Bun-only. | Harness scripts and docs use Bun only and flag npm/pnpm/yarn lockfiles as failures. |
+
+## Harness Files Added
+
+| File | Purpose |
+| --- | --- |
+| `AGENTS.md` | Compatibility agent entry point. |
+| `docs/HARNESS.md` | Harness workflow, validation tiers, conflict policy, and manual reminders. |
+| `CODEMAP.md` | High-level codebase map and validation references. |
+| `scripts/harness/doctor.sh` | Environment and repository-shape check. |
+| `scripts/harness/quick-check.sh` | Fast deterministic local validation. |
+| `scripts/harness/validate.sh` | Full local validation wrapper with optional delivery smoke. |