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	Single authoritative agent behavior guide. It references rules.md, project_context.md, harness validation, and high-risk areas.
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.

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

• The older lowercase agents.md entry has been merged into uppercase AGENTS.md so coding agents and harness tools use one source of truth.
• project_context.md originally included older roadmap assumptions such as Celery, Kafka, TimescaleDB, MinIO, and UE5 as active stack elements. The harness pass updated it to separate active stack facts from future directions; current code and technical docs still remain authoritative when details drift.
• 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.	Merged the lowercase guide into uppercase AGENTS.md; harness doctor now requires AGENTS.md and keeps agents.md absent to prevent split authority.
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.
Agents often miss user-installed Bun or uv in non-interactive shells.	Added scripts/harness/lib.sh to resolve tools from current PATH first and then the user's login interactive shell without hardcoding a dotfile.
Always-loaded security rules had no standalone harness gate.	Added scripts/harness/security-check.sh to block tracked .env / key files and scan for high-confidence committed private keys or provider tokens; quick-check now runs it.
Build success does not prove frontend page usability.	Added static frontend rules/doc checks and a Playwright route smoke for public pages, protected admin fallback, Docs loading and detail interactions, Earth iframe entry, login/register/verification/password-reset interactions, authenticated admin route/section rendering with mocked API data across desktop, mobile, and 125% / 150% zoom, plus manifest-derived desktop/mobile menu navigation and safe search/tab/dialog/Earth News interactions.
Route fallback behavior can regress even when every named page renders.	Extended the frontend smoke to verify / redirects to Earth, unauthenticated unknown routes show the login page, and authenticated unknown routes navigate back to /admin.
Frontend smoke route lists can drift from AdminRoutes and resource-page sections.	Updated the smoke to derive protected route checks and authenticated section deep-link checks from AdminRoutes.tsx and PlainResourcePages.tsx, including redirect-only /alerts.
Docs smoke mocks can drift from the product Docs catalog.	Updated the frontend smoke to derive mocked Docs catalog/content from frontend/src/pages/Docs/docs-content.ts plus backend Gatekeeper access metadata, then open every Chinese Docs catalog slug.
User manuals can miss a real console menu entry after route changes.	Added a docs consistency check that compares the manual console overview tables with frontend/src/admin/routes/manifest.tsx; fixed the missing /docs row in both user manuals.
Rendered pages can still contain broken internal shortcuts.	Added literal internal route-link checks and an interaction smoke for the AI settings shortcut; this caught and fixed a stale /admin/settings link that should point to /settings.
Global search entries can drift because their route targets live in data objects rather than JSX links.	Added a frontend rules check that validates every admin search routePath against the actual frontend route set.
Responsive styling fixes can satisfy one viewport by breaking the no-viewport-font rule.	Added a frontend rules failure for font-size values that use viewport or container query width units, and replaced public auth shell vw font sizing with fixed desktop/mobile sizes.
Typography polish can accidentally reintroduce squeezed non-zero letter spacing.	Normalized active frontend letter-spacing values to 0 and made the frontend rules check fail non-zero letter-spacing / letterSpacing declarations, with only inherit/default-zero forms allowed.
Native buttons can accidentally submit forms or keep controls clickable while loading after a props-spread reorder.	Added a frontend rules failure for TSX <button> elements without explicit type and for buttons whose disabled state can be overridden by a later props spread; fixed the data distribution buttons and auth button disabled ordering.
Admin/docs shell layouts can reintroduce brittle viewport sizing after a responsive fix.	Changed the admin and Docs route shells to use the existing html/body/#root 100% height chain, and added a frontend rules failure for exact 100vh / 100vw shell sizing in those CSS files.
Compact workspaces can drift back into card-in-card layouts or implicit AntD Space wrappers.	Added frontend rules failures for nested Card components, AntD imports, and <Space> layout primitives in active frontend source.
Connection-test controls can drift back into detached toolbar buttons.	Added a shared ConnectionTestInput suffix pattern for AI Provider and WebSearch Base URL fields, disabled WebSearch configuration/test controls when the tool is off, and made the frontend rules check fail detached AI/WebSearch connection-test buttons.
Public docs can reference stale admin section URLs.	Added docs consistency validation for documented ?section= links and rendered smoke coverage for documented AI / collector deep links.
Active plan docs can preserve old admin deep-link assumptions after the technical docs are corrected.	Extended docs consistency checks to active docs/plans/*.md files for stale admin tab-query terms and actual ?section= validity; corrected the docs audience split plan to current section routes.
Top-level README can drift from the actual frontend stack while technical docs stay current.	Updated README from Ant Design Pro to Tactile UI / Radix primitives / lucide-react and added README stale admin-stack terms to docs consistency checks.
Agent background context can reintroduce inactive stack assumptions.	Updated project_context.md and the root agent guide to label current stack facts versus future directions, then added exact stale-stack patterns for them to docs consistency checks.
Docs ?section= validation can drift if the harness owns its own route/section table.	Changed the docs consistency check to derive section keys from AdminRoutes.tsx and PlainResourcePages.tsx resource configs before validating documented deep links.
Public Docs can drift between frontend catalog metadata and backend Gatekeeper authorization metadata.	Added a docs consistency check that compares filename, slug, group, order, and bilingual titles across both metadata sources; aligned existing order drift for toolbar overlay and location pipeline docs.
Non-public technical docs can silently become Chinese-only or English-only.	Added a full docs/technical/{zh,en} filename-pair check so every technical Markdown file has a same-named counterpart before docs consistency passes.
Credentialed collector docs can drift from backend support wiring.	Added docs consistency validation for every built-in collector marked requires_credentials=true and credential_status=supported: it must have a provider, default credential guide, supported connectivity provider, frontend credential UI/guidance, a regression test, and zh/en connectivity documentation.
Backend collectors can leak debug output or credential-adjacent context through stdout.	Replaced SpaceTrack and PeeringDB collector print() calls with structured logger events, removed unreachable duplicate SpaceTrack fetch code, and added scripts/harness/backend-rules-check.sh to block future backend app print(), breakpoint(), or pdb.set_trace() calls.

Rules Coverage Evidence

This matrix records how the current harness checks the rules.md modules that matter for this frontend and documentation pass. "Automated" means the listed command fails when the rule regresses. "Smoke" means the rendered product route or interaction is opened with Playwright. "Manual" means the rule is still a judgment call and must be inspected during review.

rules.md Area	Rule Surface	Harness Evidence	Remaining Review
core	Remove stale transitional paths, duplicated helpers, and naming drift after large changes.	scripts/harness/docs-consistency-check.sh blocks known stale stack terms, old ?tab= links, public Docs metadata drift, and README/project context drift. scripts/harness/frontend-rules-check.sh blocks repeated detached AI/WebSearch connection-test buttons by requiring ConnectionTestInput.	Naming quality, function size, and whether a new abstraction is worth keeping remain manual review items.
core	Keep one source of truth for route, Docs, and section state.	Frontend route, admin manifest, admin search targets, Docs catalog metadata, backend Gatekeeper metadata, manual route tables, and documented ?section= links are all parsed from source and compared by frontend-rules-check.sh, docs-consistency-check.sh, and frontend-smoke.mjs.	Business-state ownership inside feature components still needs focused review when behavior changes.
security	Do not commit secrets, tracked env files, private keys, or exposed tokens.	scripts/harness/security-check.sh fails on tracked .env / private-key files and high-confidence provider tokens. backend-rules-check.sh blocks backend stdout/debugger calls, and frontend-rules-check.sh fails frontend console output that includes token material.	Whether a newly added setting should be masked or stored server-side still requires feature-specific review.
workflow	Frontend package management must stay Bun-only.	scripts/harness/doctor.sh and frontend-rules-check.sh fail forbidden frontend lockfiles and npm / pnpm / yarn script usage. validate.sh uses Bun for install, build, preview, and smoke.	New dependency legitimacy and maintenance quality are manual unless a dependency is actually added.
workflow	Agents should find bun and uv even when non-interactive PATH is incomplete.	scripts/harness/lib.sh checks the current PATH, then asks $SHELL, zsh, and bash login interactive shells for the command path without hardcoding a dotfile. doctor.sh, quick-check.sh, and validate.sh all source it.	System package installation remains outside harness scope and should be reported instead of auto-fixed.
docs	Keep public Docs whitelist-driven and synchronized with backend authorization metadata.	docs-consistency-check.sh compares frontend Docs metadata against backend Gatekeeper metadata, verifies files exist for both languages, checks public link titles, and blocks missing zh/en technical doc pairs. frontend-smoke.mjs opens every Chinese Docs catalog slug plus detail/search/language/theme interactions.	Quality of prose, examples, and whether a doc should be public are still editorial review items.
docs	User manuals must match real console routes and deep links.	docs-consistency-check.sh compares manual console tables with frontend/src/admin/routes/manifest.tsx and validates documented ?section= links from actual AdminRoutes.tsx plus PlainResourcePages.tsx section config.	Screenshots and UI-copy nuance are not exhaustively validated.
uiux	Admin pages are compact single-screen workspaces with explicit overflow ownership.	frontend-rules-check.sh warns on suspicious overflow: hidden, blocks exact 100vh / 100vw shell sizing in admin/Docs CSS, and frontend-smoke.mjs checks every admin route at desktop, mobile, and 125% / 150% zoom. Desktop/mobile smoke also fails global horizontal overflow.	Visual density, hierarchy, and whether a scroll owner feels ergonomic remain manual QA.
uiux	Controls use expected patterns and accessible icon buttons.	frontend-rules-check.sh blocks icon Button without aria-label and title, native <button> without explicit type, nested Cards, AntD imports, <Space>, and detached connection-test buttons. Smoke exercises search, tabs, dialogs, data toggles, and connection-test actions.	Native buttons with visible text are not treated as icon-only by static checks; semantics still need review when adding custom controls.
uiux	Text should fit, avoid viewport-scaled font sizes, and keep letter spacing at zero.	frontend-rules-check.sh fails viewport/container-width font-size units and non-zero letter-spacing / letterSpacing. frontend-smoke.mjs checks rendered routes for global overflow across desktop/mobile.	Per-element text clipping without page-level overflow is not exhaustively detected and needs visual review for changed screens.
frontend	Keep shared behavior in reusable components and existing project patterns.	frontend-rules-check.sh enforces shared ConnectionTestInput, route/link/search consistency, no debug output, native button safety, Tactile/Radix/lucide direction instead of AntD/Space, and whitelist-driven public Docs. bun x tsc --noEmit and bun run build verify TypeScript/build health.	Broad casts, inline styles, and overflow issues are warnings when context may be legitimate; review changed lines before accepting them.
frontend	Responsive adaptations must preserve the primary action path.	frontend-smoke.mjs clicks every visible admin menu entry on desktop and mobile, opens protected routes unauthenticated and authenticated, verifies root/unknown route fallback, and exercises core auth flows.	Deep feature workflows beyond smoke data, such as destructive or long-running actions, require targeted tests before behavior changes.
earth	Earth render work needs real rendering checks.	Full smoke opens /earth and verifies the 3D Earth iframe entry point. Earth News settings routes are included through the admin manifest/menu smoke, mocked /earth/news-* API responses, source test, add/cancel source draft, and manual news group creation checks. The broader Earth-specific layer/depth rules remain in rules.md and Earth docs.	The harness still does not claim full 3D layer visual verification; layer-depth and picking changes need targeted browser/canvas QA.

Harness Files Added

File	Purpose
AGENTS.md	Single authoritative agent guide and coding-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/lib.sh	Shared command lookup and run helpers.
scripts/harness/doctor.sh	Environment and repository-shape check.
scripts/harness/security-check.sh	High-confidence secret and tracked environment/key file check.
scripts/harness/backend-rules-check.sh	Backend app debug-call guard for direct stdout/debugger usage.
scripts/harness/frontend-rules-check.sh	Bun-only, route manifest, literal internal link, admin-search route target, debug-output, native-button safety, icon-button accessibility, Card nesting, AntD/Space avoidance, ConnectionTestInput, admin/docs shell viewport sizing, viewport-font, zero-letter-spacing, and UI rules static check.
scripts/harness/docs-consistency-check.sh	Frontend/backend Docs metadata alignment, public Docs metadata, full technical-doc bilingual pair, link-title, language-scoped technical link, supported credential collector contracts, manual console route coverage, documented route, admin-config-derived section deep-link consistency, and harness rules-coverage note check.
scripts/harness/frontend-smoke.mjs	Playwright route, Docs detail/language/theme/search interaction, public auth form interaction, desktop/mobile/zoom rendering, safe admin navigation/search/tab/dialog/Earth News interactions, and authenticated admin route/section smoke for the built frontend preview.
scripts/harness/quick-check.sh	Fast deterministic local validation.
scripts/harness/validate.sh	Full local validation wrapper with optional delivery smoke.