planet/docs/HARNESS.md

Agent Harness

This harness improves discoverability, repeatability, and agent safety for the existing Planet project. It does not replace current project rules, scripts, CI, or release workflows.

Authority And Conflicts

Existing project rules are authoritative:

1. rules.md
2. AGENTS.md
3. Current implementation docs under docs/technical/
4. Existing scripts, especially planet.sh
5. Existing Gitea workflow files under .gitea/workflows/

When harness guidance conflicts with any of the above, keep the existing rule, do not overwrite the existing workflow, and add a compatibility note here or in docs/harness-audit.md.

For frontend or documentation audits, also read the Rules Coverage Evidence section in docs/harness-audit.md. It maps rules.md clauses to the current static checks, Playwright smoke coverage, and remaining manual review areas, so an agent can distinguish a proved harness pass from a rule that still needs human-quality inspection.

Starting Work

Recommended startup flow:

git status --short
scripts/harness/doctor.sh

Then read only the relevant implementation docs:

• Backend/API/data work: docs/technical/zh/backend-*.md and matching English docs when public docs are affected.
• Frontend/admin work: docs/technical/zh/frontend-admin-frontend-context.md.
• Earth work: docs/technical/zh/earth-frontend-context.md, docs/technical/zh/earth-render-layer-order.md, and style docs when visual semantics change.
• Operations work: docs/technical/zh/ops-runbook.md and docs/technical/zh/ops-planet-sh-startup.md.
• AI Provider work: docs/technical/zh/agents-aiprovider.md.
• Documentation work: docs/documentation-coverage-rules.md.

Use focused inspection commands before broad reads:

rg -n "<symbol-or-term>" <path>
git diff --stat HEAD
git diff --name-only HEAD
git diff --unified=0 HEAD -- <path>

Existing Commands

Purpose	Command
First setup	./planet.sh init
Start local stack	./planet.sh start
Start with LAN access	./planet.sh start --allow-lan
Restart all services	./planet.sh restart
Restart one area	./planet.sh restart -b, -f, -a, or -d
Health check	./planet.sh health
Logs	./planet.sh log, ./planet.sh log -b, -f, -a, or -m
Create local user	./planet.sh createuser
Destructive local reset	./planet.sh destroy
Backend smoke tests	cd backend && uv run --frozen --group dev --project .. python -m pytest -s tests/test_api.py tests/test_realtime_sources.py -q
Frontend build	cd frontend && bun install --frozen-lockfile && bun run build
Mock AIS WebSocket	bun run mock:ais-ws

Harness Commands

Tier	Command	What It Does
Doctor	scripts/harness/doctor.sh	Checks required files, required tools, optional delivery tools, and forbidden frontend lockfiles.
Security	scripts/harness/security-check.sh	Checks that environment/private-key files are not tracked and scans for high-confidence committed secret tokens.
Backend Rules	scripts/harness/backend-rules-check.sh	Checks backend app Python for direct print(), breakpoint(), and pdb.set_trace() debug calls so service code uses structured logging.
Frontend Rules	scripts/harness/frontend-rules-check.sh	Checks Bun-only scripts, admin route manifest coherence, literal internal route links, admin search route targets, frontend debug output, native button safety, icon-button accessibility, no nested Cards, no AntD/Space layout primitives, ConnectionTestInput usage, admin/docs shell height-chain sizing, viewport-scaled font sizes, zero letter spacing, and high-signal UI rule warnings.
Docs Consistency	scripts/harness/docs-consistency-check.sh	Checks frontend Docs metadata against backend Gatekeeper metadata, public Docs registration, full technical-doc bilingual file pairs, public doc links, readable link titles, language-scoped technical links, README/project-context admin stack drift, supported credential collector contracts, manual console route coverage against the actual admin manifest, documented UI route drift, documented ?section= deep-link validity against the actual admin section config in technical docs and active plan docs, and the harness rules-coverage notes.
Quick	scripts/harness/quick-check.sh	Runs doctor, whitespace diff check, shell syntax checks, security scan, backend/frontend/doc consistency checks, and CI backend smoke tests.
Full	scripts/harness/validate.sh	Runs quick check, frontend Bun install/build, Playwright route smoke, optional Helm checks, and opt-in Docker image smoke builds.

Docker image smoke builds are expensive and are off by default:

PLANET_HARNESS_DOCKER_SMOKE=1 scripts/harness/validate.sh

Frontend Playwright smoke runs by default in full validation after the frontend build. It starts a local Vite preview and checks the / to Earth redirect, public pages, unknown-route login fallback, protected admin route login fallback, authenticated unknown-route fallback to /admin, Docs loading with mocked API content, Docs detail page language/theme/search interactions, every Docs catalog slug exposed by the frontend/backend metadata, the Earth iframe entry point, login error handling, register + email verification, password reset, standalone email verification, and authenticated super_admin rendering for every admin route plus core section deep links derived from the actual admin route and section config. Authenticated admin checks run at desktop size, mobile size, and 125% / 150% zoom; desktop and mobile passes also fail on global horizontal overflow so table/detail panels must keep overflow ownership inside their own scroll regions. The smoke also derives the sidebar menu from the actual admin route manifest and clicks every visible super_admin menu entry on both desktop and mobile viewports, then exercises safe interaction paths for admin search, section tabs, the AI settings shortcut, logs view switching, user dialog opening, and data distribution toggles. It also exercises Earth News source testing, add/cancel source draft behavior, and manual news group creation against mocked /earth/news-* APIs. Documented AI and collector deep links such as /ai?section=integrations, /ai?section=playground, and /collection-management?section=collector_credentials are part of the rendered smoke surface:

PLANET_HARNESS_FRONTEND_SMOKE=0 scripts/harness/validate.sh
PLANET_HARNESS_FRONTEND_SMOKE_PORT=4174 scripts/harness/validate.sh

Environment Requirements

Required for normal development:

• zsh for planet.sh
• uv for Python dependency and test execution
• bun for frontend dependency and build execution
• Python resolved by uv from the root pyproject.toml

Harness command lookup first checks the current non-interactive PATH. If a required tool is not visible there, scripts/harness/lib.sh asks the user's login interactive shell ($SHELL, then zsh, then bash) for the command path. This avoids hardcoding a dotfile while still covering agent environments that do not inherit the user's normal shell setup.

Required for full local stack operation:

• Docker and Docker Compose
• PostgreSQL and Redis containers started by planet.sh

Optional for delivery smoke:

• Docker daemon for image builds
• Helm for chart lint/template checks

If a required local tool is missing, do not install system software automatically. Report the gap and point to ./planet.sh init or scripts/bootstrap-dev.sh as the existing bootstrap path.

What Agents Must Not Change Automatically

• Do not replace Bun with npm, pnpm, or yarn.
• Do not migrate CI from .gitea/workflows/ to .github/workflows/.
• Do not rewrite planet.sh lifecycle behavior as a parallel script.
• Do not run ./planet.sh destroy unless explicitly requested.
• Do not commit .env, secrets, private keys, logs, or generated build output.
• Do not add external integrations, hooks, or new dependency managers just to satisfy harness structure.
• Do not publish internal harness docs into the product Docs UI unless a maintainer explicitly asks for it.

Hooks And Reminders

No automatic hooks are installed in this phase. Manual reminders:

• Run scripts/harness/quick-check.sh before handing off small changes.
• Run scripts/harness/validate.sh before larger cross-subsystem changes.
• Run scripts/harness/security-check.sh after touching config, auth, credentials, docs examples, or generated fixtures.
• Run scripts/harness/backend-rules-check.sh after backend service edits to catch direct stdout/debugger calls before they reach runtime logs.
• Run scripts/harness/frontend-rules-check.sh after frontend edits to expose route, package-manager, debug-output, and UI rule warnings.
• Run scripts/harness/docs-consistency-check.sh after docs edits or feature route changes.
• Add focused tests before modifying backend service behavior or frontend workflows.
• For docs changes, run the checks listed in docs/documentation-coverage-rules.md.

Reusable Workflows

Feature Work

1. Read rules.md modules for the touched area.
2. Check CODEMAP.md for entry points and ownership boundaries.
3. Inspect existing tests and docs before editing.
4. Make the smallest behavior-preserving or feature-scoped change.
5. Run scripts/harness/quick-check.sh or a narrower documented command.
6. Update relevant docs when behavior, workflow, or operations change.
7. For rendered frontend changes, verify the affected route with Playwright or the full harness smoke, because bun run build alone does not prove page usability.

Bug Fix

1. Reproduce with a focused test or command.
2. Patch the owning module, not a caller-side workaround.
3. Run the focused regression test.
4. Run scripts/harness/quick-check.sh when the change is safe to validate locally.

Documentation Change

1. Read docs/documentation-coverage-rules.md.
2. Route docs by audience: UI users, operations, or second-party developers.
3. Keep Chinese and English technical docs paired by filename; public Docs also need matching frontend/backend metadata when exposed in the product Docs UI.
4. Run the repository-specific docs checks that match the changed files.

Release Or Delivery Change

Use the existing release skill/workflow and .gitea/workflows/ files. Harness validation can smoke-check Helm and Docker locally, but it must not replace the release process.

Implementation Notes

• docs/harness-audit.md records the discovery pass that led to this harness.
• AGENTS.md is the single authoritative agent guide. The older lowercase agents.md entry has been merged into it and should remain absent.
• CODEMAP.md is intentionally high level; deeper subsystem docs stay in docs/technical/{zh,en}/.
• scripts/harness/frontend-smoke.mjs is a lightweight route/section smoke with mocked API data. It proves route shells, auth guards, and primary admin sections render, but it is not a replacement for feature-specific browser QA against a real backend.
• Frontend smoke prints phase-level progress by default. Use PLANET_FRONTEND_SMOKE_PROGRESS=verbose to print each route/menu/doc item when diagnosing a slow or failing smoke run, or set it to 0 to suppress progress lines.