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.

When the user describes work with product words rather than module names, use the rules.md Agent Discovery Index before deciding which modules to load. It maps Chinese phrases such as 一屏, 高度没控住, 文档, 数据源, 地球, 模型供应商, and 发版 to the required rule modules.

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, same-category style owner warnings, 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. To enforce the existing rules.md uiux one-screen workspace rule, admin shell pages have a hard rendered check: the shell must resolve to the viewport height through the root 100% height chain, #root/document/body must not gain vertical overflow, and the desktop sidebar account/preferences area must remain inside the first viewport while the nav owns any excess scrolling. 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

Visual Evidence And Style Consistency

• Treat user-provided screenshots and images as primary visual evidence. If a screenshot contradicts written text, inspect the image first and explicitly call out the mismatch before deciding what to change.
• Path resolution is part of visual evidence handling. If a referenced screenshot path cannot be opened, try reasonable local equivalents first: WSL/Windows path conversion, workspace-relative paths, absolute paths, current thread attachments, repository files, and obvious local attachment/download locations.
• If the image still cannot be found or opened, report the exact path/access blocker instead of guessing. Do not infer image content from the filename, alt text, surrounding prose, logs, or memory.
• OCR is acceptable evidence for text-only questions or non-multimodal environments; state when OCR was the fallback. Layout, color, spacing, pixel, and rendering issues still require a real visual inspection or an explicit "could not verify visually" note.
• Same-category UI surfaces must use one visual system per product area. Badges, chips, pills, tags, status labels, small buttons, cards, panels, and toolbar controls should reuse the shared component, shared token, or established CSS owner for that area instead of introducing a page-local lookalike.
• scripts/harness/frontend-rules-check.sh warns when semantic badge / chip / pill / tag / status selectors appear outside the approved React and Earth CSS owner files. A warning means the reviewer should either move the style into the shared owner or document why this is a genuinely new visual family.

Earth I18n Harness Rules

Earth i18n work must validate rendered behavior, not only static text lookup. Agents often miss dynamic strings that are created after initial page load, so the smoke treats these as first-class i18n surfaces:

• Visible text and attributes: translated checks must include innerText plus title, aria-label, placeholder, and alt. Tooltips and icon-only buttons are user-facing copy, not implementation details.
• Dynamic detail cards: info cards opened from Earth markers, cruise cards, BGP markers, compute centers, vessels, and news must render field labels, status values, source tags, action buttons, and disabled/tooltips in the active language.
• English content safety: English mode must not fall back to Chinese news titles, summaries, feed names, measure words, or generic status labels. If no English localization exists, hide the item or use a neutral English fallback.
• Brand assets: locale switching must update both text and image assets. The default Earth HUD brand uses title-zh.png for Chinese and title-en.png for English while keeping the same top-left layout and logo position.
• Controls and state: switch/segmented-control visuals must follow the real checked/pressed state after both direct clicks and programmatic panel changes. A control is not valid if the state changes but the thumb, active pill, or aria-* state stays stale.
• Runtime copy entrypoints: dynamic status, loading, startup, and error copy must enter through earthMessage(...) plus the centralized EARTH_MESSAGE_TEMPLATES map. Do not hide direct strings behind showStatusMessage, queueStatusMessage, showGestureStatusMessage, showError, setLoadingMessage, resolveStartupMessage, startupMessage, or earth:status events.
• Capsules and tags: pills, tags, chips, badges, and small buttons must not overflow their panel. Prefer a slightly wider owning panel for important status information; otherwise use min-width: 0, wrapping, or ellipsis with a translated tooltip.

Current frontend smoke explicitly covers the Earth English locale flow: brand image swap, settings language controls, panel switch visual sync, English news filtering, English detail-card text and tooltips, and TV default/source labels.

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

For routine harness validation, do not install missing system software automatically. Report the gap and point to the explicit bootstrap entry points. ./planet.sh init can install missing Docker Engine, Compose v2, and Buildx on Ubuntu / Ubuntu WSL, start the local service, and configure Docker group access. This bootstrap behavior is intentional; do not invoke it merely to make harness checks pass. scripts/bootstrap-dev.sh only prepares application dependencies.

Docker bootstrap regression checks use isolated command stubs and never install packages or modify the host daemon:

uv run --frozen --project . python scripts/harness/test_docker_bootstrap.py
uv run --frozen --project . python scripts/harness/test_database_startup.py

Database startup regressions also run in quick-check. They cover Compose reconciliation of existing containers, visible startup errors, published-port checks, bounded recreation that preserves volumes, and the backend connection gate before schema initialization. Their command stubs and driver mocks do not modify the host Docker environment.

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.