planet/docs/harness-audit.md

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.