6krrt/plans/docs-lift-a-pass.md

Docs pass after Lift A (PR #102)

Status: done -- executed on branch docs/lift-a-docs-pass Date: 2026-09-26 This brief is the contract. Keep the plan small: one todo per doc, each with exact section anchors. Do NOT read plans/no-progress-detection.md (reference only).

Goal

Bring the docs in line with what PR #102 shipped and what is running now. The docs describe the code as it is on this branch; where a doc and the code disagree, the code wins, and the todo says which line it checked.

Where the work happens

• Worktree: /home/alee/Sources/6krrt-worktrees/docs-lift-a-pass, branch docs/lift-a-docs-pass, based on origin/main a24de1b plus three commits that already carry North Star #4 in CLAUDE.md, the incident #8 rewrite in docs/incidents.md, and the plans. Build on them; do not rewrite them.
• Docs only. No code, config, test or unit-file changes.
• Do not touch README.md, AGENTS.md, deploy/README.md: the owner has uncommitted edits to them in the main checkout. Anything that belongs in deploy/README.md goes in docs/watchdog.md instead, and the done report lists it for the owner to fold in.

What shipped (verify each against the code before writing it)

• src/progress_detect.py: pure detector. Signals dup, top, slow, coverage; landed gating; read-only agents; canonical (sorted-key) args; bash command normalization (comment lines, cd dir &&, VAR=x prefixes dropped).
• src/watchdog.py + deploy/llm-router-watchdog.{service,timer}: 5-minute oneshot. Judges only sessions with a tool call since the last tick, on their full history, per session; landed counts the session's own descendants only. Alert lifecycle in watchdog_alerts: trigger once, escalate once (LLM yes or 3 ticks), resolve once. Quiet no_opencode tick when opencode is closed. Optional local-model second opinion (does not veto).
• src/notifier.py: desktop channel (notify-send), PagerDuty-Events-v2 shaped AlertEvent, per-channel min_severity, rate limit backed by the DB.
• src/watchdog_store.py: tables watchdog_ticks, watchdog_verdicts, watchdog_alerts, watchdog_channel_settings.
• Admin: Loops panel (index.html#loops), Watchdog card on Controls (last tick, verdicts, channels, Send test alert), per-model stall rollup and Block/Unblock on Models. New availability value blocked, excluded from routing and from pinned requests via _admin_excluded_models.
• Endpoints: GET /admin/api/watchdog/status, POST /admin/api/watchdog/channels, POST /admin/api/watchdog/test-alert; availability endpoint accepts blocked.
• Config: watchdog.* (incl. detector.*, dashboard_base_url), notifications.channels. Watchdog knobs are persisted-only (separate process).
• deploy/opencode-plugin/router-link.js: the parentCache export made opencode 1.18 reject the whole plugin ("Plugin export is not a function" in ~/.local/share/opencode/log/opencode.log), so identity headers never reached the router from #99 until this fix. A loader-contract test now asserts every export is a function.
• scripts/progress_backtest.py (--fixture replays the 15 labelled sessions; expect 8/15 flagged) and scripts/export_progress_fixture.py.
• Operator state 2026-09-26: timer enabled ~15:18 EDT with unit paths repointed from %h/llm-router to %h/Sources/6krrt (production still runs from the dev checkout; see plans/deploy-separation.md); plugin fix installed and opencode restarted 15:19; router restarted 15:19:57.

Todos (one per doc)

1. New docs/watchdog.md: what it catches and does not (steady spend is not waste), signals and thresholds, alert lifecycle, the admin surfaces, knobs, install (the sed repoint + enable --now), how to run --once, backtest, re-exporting the fixture, and known limits: sessions under 40 calls are invisible; the Atlas must-flag case sits exactly at cover_min 4.0; the stale localhost:4096 entry in rc-servers.json logs a harmless probe warning.
2. CLAUDE.md: "What's built and working" (anchor ## What's built and working): add the modules above in the existing one-bullet style, linking docs/watchdog.md; update the tests/ bullet count from the real pytest --collect-only -q total. "Run as a service" (anchor ## Run as a service): one short paragraph on the watchdog timer. Do not edit the North Star section.
3. docs/incidents.md #8: under Status, add that Lift A shipped (PR #102, a24de1b) and the timer is live; add the plugin-loader finding as Evidence (with the log line) and to the Human response timeline; add a symptom-table row "opencode plugin does nothing -> grep opencode.log for failed to load plugin". Keep the Evidence / labelled Theory convention in the file header.
4. docs/admin-portal.md: sections for the Loops panel, the Watchdog card, and the Models rollup with Block/Unblock (where blocked differs from deprecated: an operator's reasoned stop, one click to undo).
5. docs/api.md: the three watchdog endpoints and blocked on the availability endpoint (request/response shapes read from src/admin.py).
6. docs/data-model.md: the four watchdog tables (from config/schema.sql), and blocked in the availability row at the models section (line ~34) and wherever admin_model_overrides is described.
7. docs/clients.md (anchor ## Session-directory attribution (opencode plugin)) and docs/api.md near the X-Router-* table (line ~151): the plugin loader contract (every export must be a function) and how to confirm the plugin loaded.

Rules

• ASCII only; no middle dots. Match each file's existing style and heading depth. Admin-portal docs describe the UI, they do not add prose to it.
• Numbers and names come from the code on this branch, never from this brief.
• Commit per todo, by explicit path. Never git add -A.
• Do not push and do not open a PR. The done report lists commits and the items for deploy/README.md.
• If a worker's context passes ~150k tokens, stop it and start a fresh one.

Write .omo/plans/docs-lift-a-pass.md, then stop and report.