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:

```bash
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:

```bash
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, isolated Docker bootstrap/proxy and startup tests, error-catalog consistency tests, 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:

```bash
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:

```bash
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:

```bash
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.