devrites 3.0.4 → 3.0.6

package/docs/command-map.md

@@ -1,6 +1,6 @@
-# DevRites Command Map
+# DevRites command map
 
-Reference for every shipped skill and agent — what triggers it, what it reads,
+Reference for every shipped skill and agent: what triggers it, what it reads,
 what it writes, and how the pieces interact.
 
 DevRites ships through npm (`npx devrites ...`). Claude Code and Codex support
@@ -15,7 +15,7 @@ distributed as a Claude or Codex plugin.
 
 `devrites-` is a **namespace prefix** chosen for collision avoidance against
 bundled Claude Code skill names (`prototype`, `handoff`, `triage`, `diagnose`,
-…). It does **not** signal "internal" — visibility is governed by the
+…). It does **not** signal "internal": visibility is governed by the
 `user-invocable:` flag in each `SKILL.md`. All public utilities use the
 `rite-*` prefix (`rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`,
 `rite-doctor`, `rite-customize`, `rite-zoom-out`, `rite-prototype`, `rite-handoff`,
@@ -53,27 +53,27 @@ must say who runs them.
 
 | Command | Phase | Argument | What it does | Reads | Writes |
 |---|---|---|---|---|---|
-| [`/rite`](../pack/.claude/skills/rite/SKILL.md) | menu | `[subcommand]` | Compact menu + suggested next command. Pure router; does **not** read state — that's `/rite-status`. | — | — |
-| [`/rite-spec`](../pack/.claude/skills/rite-spec/SKILL.md) | spec | `<feature>` | **Start here.** Deep investigation → writes a product-focused `spec.md` (WHAT/WHY, requirements, ACs, boundaries, gaps closed with options, design references). Checks the shipped archive for prior art before speccing. Creates the workspace map. | codebase + codegraph/graphify + shipped archive (`devrites-engine archive-search`) | `README.md`/`feature.md`, `brief.md`, `spec.md`, `references/`, `references.md`, `questions.md`, `decisions.md`, `assumptions.md`, `state.md` |
+| [`/rite`](../pack/.claude/skills/rite/SKILL.md) | menu | `[subcommand]` | Compact menu + suggested next command. Pure router; does **not** read state because `/rite-status` owns that job. | none | none |
+| [`/rite-spec`](../pack/.claude/skills/rite-spec/SKILL.md) | spec | `<feature>` | **New feature.** Deep investigation → writes a product-focused `spec.md` (WHAT/WHY, requirements, ACs, boundaries, gaps closed with options, design references). Checks the shipped archive for prior art before speccing. Creates the workspace map. | codebase + codegraph/graphify + shipped archive (`devrites-engine archive-search`) | `README.md`/`feature.md`, `brief.md`, `spec.md`, `references/`, `references.md`, `questions.md`, `decisions.md`, `assumptions.md`, `state.md` |
 | [`/rite-temper`](../pack/.claude/skills/rite-temper/SKILL.md) | temper | `[slug] [--mode]` | **Optional, before define.** Strategic review of the readied spec: scope mode (expand / selective / hold-rigor / reduce-to-MVP) + pre-mortem + 9-dimension floor-gate; folds decisions into the spec via the Spec Drift Guard. Significance-gated; **mandatory in `/rite-autocomplete`**. Reviewer: `devrites-strategy-reviewer`. | `spec.md` + decisions/assumptions + design-brief | `strategy.md`, `spec.md`, `decisions.md`, `assumptions.md` |
 | [`/rite-define`](../pack/.claude/skills/rite-define/SKILL.md) | plan | `[slug]` | Turns the approved `spec.md` into architecture, plan, vertical `SLICE-###` task slices, traceability, and state. Reads `strategy.md` if present. | `spec.md` (+ `strategy.md`) + references | `architecture.md`, `plan.md`, `tasks.md`, `traceability.md`, `state.md`, `decisions.md` |
-| [`/rite-vet`](../pack/.claude/skills/rite-vet/SKILL.md) | vet | `[slug] [--cross-model] [--full]` | **Before build — every feature.** Engineering review of the defined plan: scope challenge (reuse / minimum-diff / complexity smell) + architecture / plan code-quality / test-coverage design / performance, confidence-banded with a quote-the-source verification gate; failure-mode + parallelization map. Hardens `plan.md` / `tasks.md` in place; writes the build-readable `test-plan.md`; acceptance-changing deltas route via the Spec Drift Guard. Runs on every plan — depth scales to stakes (light pass on simple plans, full on big/risky), never skipped; **always in `/rite-autocomplete`**. Reviewer: `devrites-plan-reviewer` (+ optional `--cross-model`). | `plan.md` + `tasks.md` + `spec.md` (+ `strategy.md`) | `eng-review.md`, `test-plan.md`, `plan.md`, `tasks.md`, `decisions.md`, `state.md` |
+| [`/rite-vet`](../pack/.claude/skills/rite-vet/SKILL.md) | vet | `[slug] [--cross-model] [--full]` | **Before build: every feature.** Engineering review of the defined plan: scope challenge (reuse / minimum-diff / complexity smell) + architecture / plan code-quality / test-coverage design / performance, confidence-banded with a quote-the-source verification gate; failure-mode + parallelization map. Hardens `plan.md` / `tasks.md` in place; writes the build-readable `test-plan.md`; acceptance-changing deltas route via the Spec Drift Guard. Runs on every plan: depth scales to stakes (light pass on simple plans, full on big/risky), never skipped; **always in `/rite-autocomplete`**. Reviewer: `devrites-plan-reviewer` (+ optional `--cross-model`). | `plan.md` + `tasks.md` + `spec.md` (+ `strategy.md`) | `eng-review.md`, `test-plan.md`, `plan.md`, `tasks.md`, `decisions.md`, `state.md` |
 | [`/rite-plan`](../pack/.claude/skills/rite-plan/SKILL.md) | plan | `[mode]` | Decompose / reslice / repair / re-order / split / unblock an active plan; `revise` is artifact-only. | spec/plan/tasks/state/drift + diff | `plan.md`, `tasks.md`, `state.md`, `decisions.md` |
 | [`/rite-build`](../pack/.claude/skills/rite-build/SKILL.md) | build | `[slice]` | Implement **exactly one** vertical slice, then stop. When `.devrites/CHECKPOINT` is set, commits the proven slice local-only as `WIP(<slug>)`. | workspace + diff + `.devrites/CHECKPOINT` | code + `state.md`, `evidence.md`, `traceability.md`, `touched-files.md` (+ local `WIP(<slug>)` commit in checkpoint mode) |
-| [`/rite-converge`](../pack/.claude/skills/rite-converge/SKILL.md) | converge | `[slug]` | **Recovery.** Assess the live codebase against `spec.md`+`plan.md`+`tasks.md` (+ principles) as the sole source of intent — present state, no git/diff — and **append** each unmet piece as a new traceable `SLICE-###` for `/rite-build`. Append-only; `tasks.md` byte-unchanged if the code already converged. For a resumed / `/rite-adopt`'d / stalled feature. | `spec.md` + `plan.md` + `tasks.md` + `.devrites/principles.md` + live code | `tasks.md` (appended), `traceability.md`, `state.md`, `decisions.md` |
+| [`/rite-converge`](../pack/.claude/skills/rite-converge/SKILL.md) | converge | `[slug]` | **Recovery.** Compare the live codebase with `spec.md`, `plan.md`, `tasks.md`, and any principles as the sole source of intent. Use the present state rather than git history or a diff, then **append** each unmet piece as a new traceable `SLICE-###` for `/rite-build`. `tasks.md` stays byte-identical when the code has already converged. Use this for a resumed, adopted, or stalled feature. | `spec.md` + `plan.md` + `tasks.md` + `.devrites/principles.md` + live code | `tasks.md` (appended), `traceability.md`, `state.md`, `decisions.md` |
 | [`/rite-prove`](../pack/.claude/skills/rite-prove/SKILL.md) | prove | `[scope]` | Tests + build + runtime + browser proof of the completed feature. | `traceability.md` + workspace + diff | `evidence.md`, `browser-evidence.md`, `traceability.md`, `state.md` |
 | [`/rite-polish`](../pack/.claude/skills/rite-polish/SKILL.md) | polish | `[target \| mode]` | Orchestrator. Reads `reference/code.md` always (Phase 1 + 2); reads `reference/ui.md` when UI is touched (Phase 3 + 4). Mode tokens: `bolder \| quieter \| distill \| harden \| normalize-only`. | workspace + design system + diff | `polish-report.md`, `browser-evidence.md` |
 | [`/rite-review`](../pack/.claude/skills/rite-review/SKILL.md) | review | `[scope]` | Feature-scoped multi-axis review. Parallel Spec + Standards sub-agents (`devrites-spec-reviewer`, `devrites-code-reviewer`). | workspace + diff | `review.md`, `evidence.md`, `state.md` |
-| [`/rite-seal`](../pack/.claude/skills/rite-seal/SKILL.md) | seal | — | GO / NO-GO **decision**, hands off to `/rite-ship`. Walks acceptance vs evidence, fans out reviewers, writes the verdict. Runs no git; on GO sets `state.md` `Next step: /rite-ship`. Triggers: "GO / NO-GO", "is it safe to merge", "decide if we can ship". | all artifacts + diff | `seal.md`, `state.md` |
+| [`/rite-seal`](../pack/.claude/skills/rite-seal/SKILL.md) | seal | none | GO / NO-GO **decision**, hands off to `/rite-ship`. Walks acceptance vs evidence, fans out reviewers, writes the verdict. Runs no git; on GO sets `state.md` `Next step: /rite-ship`. Triggers: "GO / NO-GO", "is it safe to merge", "decide if we can ship". | all artifacts + diff | `seal.md`, `state.md` |
 | [`/rite-ship`](../pack/.claude/skills/rite-ship/SKILL.md) | ship | `[slug]` | Final phase. Requires a GO in `seal.md` → collapses any `WIP(<slug>)` checkpoints → renders type-`GO` + runs the irreversible git ladder (commit → push → tag/PR) + closes the task (archive workspace → `.devrites/archive/<slug>/`, clear `ACTIVE`, phase `done`). Triggers: "ship it", "ship this", "push it out", "close the task". | `seal.md` + all artifacts + diff | `ship.md`, `state.md`, archive |
 | [`/rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | (orchestrator) | `[idea] [--ship\|--yolo] [--max-slices N]` | Full unattended lifecycle (spec → … → seal → ship), best option at each soft gate, rationale to `decisions.md`. Arms AFK + checkpoint mode for the run. Vague prompt → up-front interview; pauses on hard-risk / blocking / escalating / open-validating / NO-GO / budget-exhausted. Default stops at the final type-`GO`; `--ship` flag (alias `--yolo`) auto-confirms it. Triggers: "autocomplete", "do the whole thing". | idea + workspace | whole workspace (drives every phase) |
-| [`/rite-quick`](../pack/.claude/skills/rite-quick/SKILL.md) | (express) | `<change>` | Express lane for a **small, reversible, unambiguous** change — one-line contract → TDD build → scoped prove → review-lite → ship, no full artifact tree. **Significance gate first**: auth / migration / public-API / destructive / multi-slice / ambiguous → escalates to `/rite-spec`. Triggers: "quick fix", "small change", "tiny tweak", "just do X". | the change + codebase | code + commit (optional `brief.md` / `evidence.md`) |
-| [`/rite-frame`](../pack/.claude/skills/rite-frame/SKILL.md) | lens | `[ask \| diff]` | Pre-flight + self-audit lens for ad-hoc work the lifecycle gates never see — **FRAME** turns an imperative ask into a falsifiable success criterion + verify command before code; **AUDIT** checks a raw diff against the four LLM coding failure modes (silent assumption / overcomplication / out-of-scope edit / unverifiable goal). Top of `/rite-quick` or before a plain "just do X". | the ask / a raw diff | success criterion + verify command (inline) |
-| [`/rite-adopt`](../pack/.claude/skills/rite-adopt/SKILL.md) | onboard | `[path]` | Bring an EXISTING codebase under DevRites — reverse-derive a `spec.md` of current behavior + placement + architecture, seed the conventions ledger from observed idioms, then hand off to the lifecycle. Triggers: "adopt this project", "onboard this codebase", "we already have code". | the codebase | `spec.md`, `.devrites/conventions.md`, `decisions.md`, `state.md` |
-| [`/rite-status`](../pack/.claude/skills/rite-status/SKILL.md) | status | `[slug]` | Active feature: phase, run mode (AFK/HITL), status, next action, evidence, open questions by gate, risks, handoff readiness. Reads via the shared `devrites-lib` preamble (portable). | workspace + `.devrites/AFK` | — |
+| [`/rite-quick`](../pack/.claude/skills/rite-quick/SKILL.md) | (express) | `<change>` | Express lane for a **small, reversible, unambiguous** change: one-line contract → TDD build → scoped prove → review-lite → ship, no full artifact tree. **Significance gate first**: auth / migration / public-API / destructive / multi-slice / ambiguous → escalates to `/rite-spec`. Triggers: "quick fix", "small change", "tiny tweak", "just do X". | the change + codebase | code + commit (optional `brief.md` / `evidence.md`) |
+| [`/rite-frame`](../pack/.claude/skills/rite-frame/SKILL.md) | lens | `[ask \| diff]` | Pre-flight + self-audit lens for ad-hoc work the lifecycle gates never see: **FRAME** turns an imperative ask into a falsifiable success criterion + verify command before code; **AUDIT** checks a raw diff against the four LLM coding failure modes (silent assumption / overcomplication / out-of-scope edit / unverifiable goal). Top of `/rite-quick` or before a plain "just do X". | the ask / a raw diff | success criterion + verify command (inline) |
+| [`/rite-adopt`](../pack/.claude/skills/rite-adopt/SKILL.md) | onboard | `[path]` | Bring an EXISTING codebase under DevRites: reverse-derive a `spec.md` of current behavior + placement + architecture, seed the conventions ledger from observed idioms, then hand off to the lifecycle. Triggers: "adopt this project", "onboard this codebase", "we already have code". | the codebase | `spec.md`, `.devrites/conventions.md`, `decisions.md`, `state.md` |
+| [`/rite-status`](../pack/.claude/skills/rite-status/SKILL.md) | status | `[slug]` | Active feature: phase, run mode (AFK/HITL), status, next action, evidence, open questions by gate, risks, handoff readiness. Reads via the shared `devrites-lib` preamble (portable). | workspace + `.devrites/AFK` | none |
 | [`/rite-resolve`](../pack/.claude/skills/rite-resolve/SKILL.md) | resume | `<qid> "<answer>"` \| `--drop <qid>` \| `--batch <file>` | Answer / drop / batch-resolve open `questions.md` entries; clears `state.md` `Awaiting human` and sets `Status: running`. Canonical writer for `status: open → answered`. | `questions.md` + `state.md` | `questions.md`, `state.md` |
-| [`/rite-zoom-out`](../pack/.claude/skills/rite-zoom-out/SKILL.md) | utility | — | One-pass structural map of an unfamiliar area (modules, in-callers, out-calls, decisions) in project vocabulary. Prefers codegraph/graphify. | codebase + ADRs/CONTEXT.md | — |
-| [`/rite-prototype`](../pack/.claude/skills/rite-prototype/SKILL.md) | utility | `[question]` | Throwaway code answering ONE design question. Logic harness OR 2–4 UI variations on one route. Captures verdict to `decisions.md`. | spec / surrounding code | prototype scratch + `decisions.md` |
+| [`/rite-zoom-out`](../pack/.claude/skills/rite-zoom-out/SKILL.md) | utility | none | One-pass structural map of an unfamiliar area (modules, in-callers, out-calls, decisions) in project vocabulary. Prefers codegraph/graphify. | codebase + ADRs/CONTEXT.md | none |
+| [`/rite-prototype`](../pack/.claude/skills/rite-prototype/SKILL.md) | utility | `[question]` | Throwaway code answering ONE design question. Logic harness OR 2 to 4 UI variations on one route. Captures verdict to `decisions.md`. | spec / surrounding code | prototype scratch + `decisions.md` |
 | [`/rite-handoff`](../pack/.claude/skills/rite-handoff/SKILL.md) | utility | `[next-session-focus]` | Compacts the chat into a handoff doc. Syncs chat-only context into workspace canonical files. References existing artifacts by path. | chat + workspace | `handoff.md` + sync into canonical files |
 | [`/rite-learn`](../pack/.claude/skills/rite-learn/SKILL.md) | utility | `[--mine \| "<lesson>"]` | Mine archived features for recurring mistakes / dismissed-finding classes; propose project-local lessons into `.devrites/learnings.md` (loaded by the review skills before a fan-out). | archive + workspace | `.devrites/learnings.md` |
 | [`/rite-customize`](../pack/.claude/skills/rite-customize/SKILL.md) | utility | `[override <agent> \| extension <name>]` | Guided authoring for project-local reviewer overrides and extensions; writes the smallest artifact, then runs the matching validator. Explicit-only. | `.devrites/overrides`, `.devrites/extensions`, pack agents | `.devrites/overrides/<agent>.md` or `.devrites/extensions/<name>/...` |
@@ -81,10 +81,14 @@ must say who runs them.
 | [`/rite-pov`](../pack/.claude/skills/rite-pov/SKILL.md) | utility | `[candidate/link/question]` | Project-grounded verdict on adopting, switching, rejecting, or ignoring a named external technology/library/platform/pattern. Clears a project floor and external floor before grading. | repo profile + code/docs + external sources | `decisions.md` or ADR only on request |
 | [`/rite-dogfood`](../pack/.claude/skills/rite-dogfood/SKILL.md) | utility | `[feature-slug\|branch] [--port N]` | Diff-scoped browser QA: map changed user journeys, run scenario matrix, fix small obvious breakages, write dogfood report. Explicit-only. | diff + app routes + browser | `.devrites/work/<slug>/dogfood.md` + safe fixes |
 | [`/rite-pr-feedback`](../pack/.claude/skills/rite-pr-feedback/SKILL.md) | utility | `[PR number\|thread URL]` | Resolve GitHub PR review feedback: fetch unresolved threads, judge centrally, fix valid items, reply, resolve. Explicit-only. | PR threads + code | code/tests + PR replies/resolutions |
-| [`/rite-pressure-test`](../pack/.claude/skills/rite-pressure-test/SKILL.md) | utility | `[idea]` | Pressure-test a rough idea: 3–5 genuinely different options → converge on one with trade-off + hinge. | spec / surrounding code | `decisions.md` (optional) |
-| [`/rite-doctor`](../pack/.claude/skills/rite-doctor/SKILL.md) | diagnostic | `[--code \| --reindex]` | Diagnose DevRites install, workspace, and optional index health. `--reindex` explicitly runs the internal synchronous refresh. Triggers: "rite doctor", "is DevRites healthy", "reindex". | install + workspace + optional indexes | — |
+| [`/rite-pressure-test`](../pack/.claude/skills/rite-pressure-test/SKILL.md) | utility | `[idea]` | Pressure-test a rough idea: 3 to 5 genuinely different options → converge on one with trade-off + hinge. | spec / surrounding code | `decisions.md` (optional) |
+| [`/rite-doctor`](../pack/.claude/skills/rite-doctor/SKILL.md) | diagnostic | `[--code \| --reindex]` | Diagnose DevRites install, workspace, and optional index health. `--reindex` explicitly runs the internal synchronous refresh. Triggers: "rite doctor", "is DevRites healthy", "reindex". | install + workspace + optional indexes | none |
 
-## Internal skills (`user-invocable: false`, model-invoked)
+## Internal specialist skills (`user-invocable: false`, model-invoked)
+
+The 11 specialist skills below are model-invoked. `devrites-lib` is the twelfth
+internal skill, but it sets `disable-model-invocation: true` and serves only as
+the shared reference library.
 
 | Skill | Triggered by | Role | Notable |
 |---|---|---|---|
@@ -93,7 +97,7 @@ must say who runs them.
 | [`devrites-doubt`](../pack/.claude/skills/devrites-doubt/SKILL.md) | non-trivial decision in build/review | CLAIM → EXTRACT → DOUBT → RECONCILE → STOP | adversarial; ask user if uncertain |
 | [`devrites-ux-shape`](../pack/.claude/skills/devrites-ux-shape/SKILL.md) | UI detected in `/rite-spec` | Plan UX/UI before code → `design-brief.md` (direction, states, interaction, visual-direction probe) | the build target; refs: brief-template/visual-direction-probe |
 | [`devrites-frontend-craft`](../pack/.claude/skills/devrites-frontend-craft/SKILL.md) | UI detected in build/polish | Build **to** `design-brief.md`: register, refine-per-slice, states, anti-slop | refs: shape/craft/design-references |
-| [`devrites-prose-craft`](../pack/.claude/skills/devrites-prose-craft/SKILL.md) | a phase writes prose; `/rite-polish` Phase 1 catch | Human-voice writing — strip LLM tells, keep precise lists/terms | refs: banned-phrases, structures, examples |
+| [`devrites-prose-craft`](../pack/.claude/skills/devrites-prose-craft/SKILL.md) | a phase writes prose; `/rite-polish` Phase 1 catch | Human-voice writing: strip LLM tells, keep precise lists/terms | refs: banned-phrases, structures, examples |
 | [`devrites-browser-proof`](../pack/.claude/skills/devrites-browser-proof/SKILL.md) | UI in prove/polish | Browser proof ladder + evidence schema + the structured **Visual Verdict** table | harness preferred |
 | [`devrites-refresh-indexes`](../pack/.claude/skills/devrites-refresh-indexes/SKILL.md) | Stop hook or explicit `/rite-doctor --reindex` call | Keep codebase-memory-mcp / codegraph / graphify current after edits | internal synchronous force; no-ops when no index |
 | [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | failing tests/build/runtime | 7-step: loop → reproduce → hypotheses → trace → instrument → fix → cleanup | references split per step |
@@ -101,7 +105,7 @@ must say who runs them.
 | [`devrites-audit simplify`](../pack/.claude/skills/devrites-audit/SKILL.md) | `/rite-polish` Phase 1 | Chesterton's Fence, behavior-preserving simplification | dispatches `devrites-simplifier-reviewer` |
 | [`devrites-audit security`](../pack/.claude/skills/devrites-audit/SKILL.md) | input/auth/data/integration in scope | OWASP Top 10, three-tier boundary | dispatches `devrites-security-auditor` |
 | [`devrites-audit perf`](../pack/.claude/skills/devrites-audit/SKILL.md) | perf relevant or regression risk | Measure-first, CWV targets | dispatches `devrites-performance-reviewer` |
-| [`devrites-lib/reference/parallel-dispatch.md`](../pack/.claude/skills/devrites-lib/reference/parallel-dispatch.md) | loaded inline by `/rite-seal` and `/rite-review` | Reference doc — dispatch shape + reconciliation rules for the parallel reviewer fan-out via the `Task` tool | not a skill — a reference file |
+| [`devrites-lib/reference/parallel-dispatch.md`](../pack/.claude/skills/devrites-lib/reference/parallel-dispatch.md) | loaded inline by `/rite-seal` and `/rite-review` | Reference doc: dispatch shape + reconciliation rules for the parallel reviewer fan-out via the `Task` tool | not a skill: a reference file |
 
 ## Agents (`.claude/agents/devrites-*`, fresh-context subagents)
 
@@ -109,20 +113,20 @@ must say who runs them.
 
 | Agent | Spawned by | Purpose |
 |---|---|---|
-| [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) | `/rite-build` (the build core) | **Write-capable** — turn one slice contract into clean, idiomatic, proven code (orient → TDD → verify, anti-slop); returns a structured artifact, writes no bookkeeping |
+| [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) | `/rite-build` (the build core) | **Write-capable**: turn one slice contract into clean, idiomatic, proven code (orient → TDD → verify, anti-slop); returns a structured artifact, writes no bookkeeping |
 | [`devrites-strategy-reviewer`](../pack/.claude/agents/devrites-strategy-reviewer.md) | `/rite-temper` (pre-plan) | Spec-vs-rubric strategic review (ambition / scope / premise / pre-mortem / YAGNI / testability / irreversibility / cross-cutting / convention); read-only; **not** part of the seal fan-out |
 | [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) | `/rite-vet` (pre-build) | Plan-vs-rubric engineering review (architecture / scope-reuse / plan code-quality / test-coverage design / performance / reversibility / failure-mode coverage), confidence-banded with a quote-the-source verification gate; read-only; **not** part of the seal fan-out |
-| [`devrites-forge-judge`](../pack/.claude/agents/devrites-forge-judge.md) | `/rite-build` on a `Forge: yes` slice | Comparative judge of K=2–3 competing candidate builds (acceptance / test strength / principle fit / simplicity / reuse / anti-slop); picks the single winner to land, names grafts; read-only |
+| [`devrites-forge-judge`](../pack/.claude/agents/devrites-forge-judge.md) | `/rite-build` on a `Forge: yes` slice | Comparative judge of K=2 to 3 competing candidate builds (acceptance / test strength / principle fit / simplicity / reuse / anti-slop); picks the single winner to land, names grafts; read-only |
 | [`devrites-spec-reviewer`](../pack/.claude/agents/devrites-spec-reviewer.md) | `/rite-review` Spec axis; `/rite-seal` | Does the diff implement the spec? Missing/partial/wrong criteria; scope creep |
 | [`devrites-code-reviewer`](../pack/.claude/agents/devrites-code-reviewer.md) | `/rite-review` Standards axis; `/rite-seal` | Correctness / readability / architecture / maintainability |
-| [`devrites-test-analyst`](../pack/.claude/agents/devrites-test-analyst.md) | `/rite-seal` | Do the tests actually prove the acceptance criteria? |
+| [`devrites-test-analyst`](../pack/.claude/agents/devrites-test-analyst.md) | `/rite-seal` | Do the tests prove the acceptance criteria? |
 | [`devrites-frontend-reviewer`](../pack/.claude/agents/devrites-frontend-reviewer.md) | `/rite-seal` on UI features | UX, a11y, responsive, design-system, anti-AI-slop; reads the **Visual Verdict** |
 | [`devrites-security-auditor`](../pack/.claude/agents/devrites-security-auditor.md) | `/rite-seal` when input/auth/data in scope | OWASP Top 10, trust boundary, secrets, deps |
 | [`devrites-performance-reviewer`](../pack/.claude/agents/devrites-performance-reviewer.md) | `/rite-seal` when perf relevant | N+1s, hot paths, payload size |
 | [`devrites-devex-reviewer`](../pack/.claude/agents/devrites-devex-reviewer.md) | `/rite-vet` (predict) + `/rite-seal` (measure) when a developer-facing surface is in scope | Developer-experience scorecard + predict-vs-measure boomerang (TTHW, getting-started, error-message quality, ergonomics, docs) |
 | [`devrites-doubt-reviewer`](../pack/.claude/agents/devrites-doubt-reviewer.md) | `devrites-doubt` loop | Adversarial check of a single claim/decision |
 | [`devrites-simplifier-reviewer`](../pack/.claude/agents/devrites-simplifier-reviewer.md) | `devrites-audit simplify` | Independent simplification judgment |
-| [`devrites-retrospector`](../pack/.claude/agents/devrites-retrospector.md) | `/rite-ship` close (cadence-gated) | Cross-feature retrospective — mines the shipped archive for recurring patterns + trends; **drafts** graduation candidates for `/rite-learn`; read-only |
+| [`devrites-retrospector`](../pack/.claude/agents/devrites-retrospector.md) | `/rite-ship` close (cadence-gated) | Cross-feature retrospective: mines the shipped archive for recurring patterns + trends; **drafts** graduation candidates for `/rite-learn`; read-only |
 
 ## Engineering rules (`pack/.claude/skills/devrites-lib/reference/standards/`)
 
@@ -130,15 +134,15 @@ Progressive-disclosure rules. Workspace-operating lifecycle skills read `core.md
 in step 0; compact utilities load their narrower contract. The rest are referenced on demand. Full index in
 [`pack/.claude/skills/devrites-lib/reference/standards/README.md`](../pack/.claude/skills/devrites-lib/reference/standards/README.md).
 
-- `core.md` (always-on) — operating rules + universal anti-rationalizations + 1-line craft disciplines + persistence-before-stopping summary.
+- `core.md` (always-on): operating rules + universal anti-rationalizations + 1-line craft disciplines + persistence-before-stopping summary.
 - On-demand rules and checklists (read by the phase that needs them): `coding-style.md` · `prose-style.md` · `error-handling.md` · `testing.md` · `spec-grammar.md` · `code-review.md` · `edge-case-trace.md` · `principles.md` · `security.md` · `performance.md` · `observability.md` · `developer-experience.md` · `patterns.md` · `git-workflow.md` · `ci-cd.md` · `hooks.md` · `documentation.md` · `development-workflow.md` · `deprecation.md` · `elicitation.md` · `agents.md` · `context-hygiene.md` · `anti-patterns.md` · `afk-hitl.md` · `tooling.md` · `skill-authoring.md` · `definition-of-done.md` · `review-checklist.md` · `test-proof-checklist.md` · `browser-proof-checklist.md` · `security-checklist.md`
-- `anti-patterns.md` — pack-wide rationalizations + red flags. Loaded by each per-phase `rite-*/reference/anti-patterns.md`; can be loaded directly for cross-phase reluctance.
+- `anti-patterns.md`: pack-wide rationalizations + red flags. Loaded by each per-phase `rite-*/reference/anti-patterns.md`; can be loaded directly for cross-phase reluctance.
 
 ## Trigger conditions (auto-selection)
 
 | Trigger | Routes to |
 |---|---|
-| Frontend/UI detected (TSX/JSX/Vue/Svelte/Astro/Angular/ERB, CSS/Tailwind/tokens, components/forms/states) | `devrites-ux-shape` in spec (writes `design-brief.md` — direction, **calibration** density/motion, states), `devrites-frontend-craft` in build (builds to it; extracts to a supplied Figma/image target), `devrites-browser-proof` in prove, `rite-polish` Phase 3 + 4 (`reference/ui.md`) in polish, UX/a11y axes at review/seal, optional **design-memory** rollup → project `DESIGN.md` at ship |
+| Frontend/UI detected (TSX/JSX/Vue/Svelte/Astro/Angular/ERB, CSS/Tailwind/tokens, components/forms/states) | `devrites-ux-shape` in spec (writes `design-brief.md`: direction, **calibration** density/motion, states), `devrites-frontend-craft` in build (builds to it; extracts to a supplied Figma/image target), `devrites-browser-proof` in prove, `rite-polish` Phase 3 + 4 (`reference/ui.md`) in polish, UX/a11y axes at review/seal, optional **design-memory** rollup → project `DESIGN.md` at ship |
 | Uncertain library / framework behavior | `devrites-source-driven` |
 | Non-trivial decision (boundary, data model, auth, public API, migration, "this scales/safe") | `devrites-doubt` (+ `devrites-doubt-reviewer`) |
 | User input / auth / storage / external integration / secrets / permissions | `devrites-audit security` (+ `devrites-security-auditor`) |
@@ -153,14 +157,14 @@ in step 0; compact utilities load their narrower contract. The rest are referenc
 Skills that prefer a code-intelligence index (`codegraph_*` / `graphify-out/`)
 when available, falling back to file reads otherwise:
 
-- `/rite-spec`, `/rite-define`, `/rite-plan` — placement / impact / callers during investigation
-- `/rite-vet` — reuse-vs-rebuild, blast-radius, and placement-realism checks during the scope challenge + architecture axis
-- `/rite-build` — `touched-files.md` + impact when loading slice context
-- `/rite-review` — blast-radius checks on the diff
-- `/rite-seal` — final blast-radius check
-- `devrites-doubt` — "where does this claim reach" via `codegraph_impact` / `codegraph_callers`
-- `/rite-zoom-out` — `codegraph_context` + `codegraph_explore`
-- `devrites-frontend-craft` — component / token lookups
+- `/rite-spec`, `/rite-define`, `/rite-plan`: placement / impact / callers during investigation
+- `/rite-vet`: reuse-vs-rebuild, blast-radius, and placement-realism checks during the scope challenge + architecture axis
+- `/rite-build`: `touched-files.md` + impact when loading slice context
+- `/rite-review`: blast-radius checks on the diff
+- `/rite-seal`: final blast-radius check
+- `devrites-doubt`: "where does this claim reach" via `codegraph_impact` / `codegraph_callers`
+- `/rite-zoom-out`: `codegraph_context` + `codegraph_explore`
+- `devrites-frontend-craft`: component / token lookups
 
 ## Interactions (typical flow)
 
@@ -183,7 +187,7 @@ See [`flow.md`](flow.md) for the Mermaid diagrams. The text path:
   changes, then `/rite-plan repair` before resuming.
 - `/rite-seal` fans out to `.claude/agents/devrites-*` reviewers **in
   parallel** for independent, fresh-context judgment, then writes the GO /
-  NO-GO verdict — it runs no git. On GO it hands off to `/rite-ship`, which
+  NO-GO verdict: it runs no git. On GO it hands off to `/rite-ship`, which
   renders type-`GO`, runs the irreversible git ladder, and closes the task by
   archiving the workspace to `.devrites/archive/<slug>/` and clearing
   `.devrites/ACTIVE`.

package/docs/engine/agent-contract.md

@@ -1,24 +1,26 @@
 # `devrites-engine` agent contract (`--json`)
 
 An unattended driver (the AFK loop, a CI step, or a local script) needs to read a
-command's result **structurally** — never by scraping prose that may reword. The
+command's result **structurally** instead of scraping prose that may change. The
 AFK-parsed read commands accept `--json` and emit a stable envelope on stdout; the
 command's own logic and exit code are unchanged, so `--json` is a pure add-on.
 
 ## Which commands accept `--json`
 
-The set an unattended run actually branches on:
+An unattended run branches on this set:
 
 `status` · `readiness` · `seal` · `spec-validate` · `evidence-fresh` · `preamble` ·
 `coverage` · `analyze` · `doctor` · `ledger` (`diff` / `validate` / `list` / `show`)
 
 Other subcommands (hooks, `footprint`, `tick-afk`, mutating commands) do not accept
-`--json` — they are not parsed for a decision. This is deliberate scope, not an
+`--json` because no driver parses them for a decision. This is deliberate scope, not an
 oversight; the flag is added where a machine reads the result.
 
-Exception: `snapshot` and `context show --json` are already direct structured reports, not
-envelopes. `context show --json` emits `root`, `project`, `activeWorkspace`, `source`,
-`hostCommands`, and `status` so wrappers can tell where DevRites will act.
+Exception: `snapshot`, `context show --json`, and
+`reviewer-stats report --json` are already direct structured reports, not
+envelopes. `context show --json` emits `root`, `project`, `activeWorkspace`,
+`source`, `hostCommands`, and `status` so wrappers can tell where DevRites will
+act; reviewer stats emits the deterministic per-reviewer dispatch verdicts.
 
 ## Envelope
 
@@ -43,7 +45,7 @@ envelopes. `context show --json` emits `root`, `project`, `activeWorkspace`, `so
 | field | meaning |
 | ----- | ------- |
 | `command` | the subcommand that ran |
-| `ok` | `exitCode == 0` — the one boolean a driver branches on |
+| `ok` | `exitCode == 0`: the one boolean a driver branches on |
 | `exitCode` | the process exit code (authoritative; see the table below) |
 | `data.text` | the command's human-readable stdout, verbatim and lossless (omitted when empty) |
 | `diagnostics[]` | one entry per stderr line, classified (omitted when none) |
@@ -67,9 +69,9 @@ and ignore `data.text`; a human reads `data.text` and ignores the rest.
 | code | meaning |
 | ---- | ------- |
 | `0` | ok / gate passed / valid |
-| `1` | a content violation — a grammar or delta error (`spec-validate`, `ledger validate`) |
+| `1` | a content violation: a grammar or delta error (`spec-validate`, `ledger validate`) |
 | `2` | usage error (bad args, unknown command) |
-| `3` | blocked — a completeness-gate pause or a `doctor` version-skew refuse; a **pause, not a crash** |
+| `3` | blocked: a completeness-gate pause or a `doctor` version-skew refuse; a **pause, not a crash** |
 | `5` | a required input is missing (e.g. no `spec.md`) |
 
 Exit `3` is the AFK pause signal: resolve the reported gap and retry.

package/docs/engine/commands.md

@@ -1,11 +1,14 @@
 # `devrites-engine` commands (engine core)
 
 The `devrites-engine` binary is the deterministic control plane over a project's
-`.devrites/` state. It makes **zero model or network calls** — the in-session
-LLM stays the judgment data plane; the engine only sequences, gates, and reads.
+`.devrites/` state. Workspace state, gate, and derivation commands make no model
+calls and are network-free; explicit install/update/source-cache I/O is isolated under
+`engine/internal/iohooks` (ADR-0008). The in-session LLM remains the judgment
+data plane.
 
-This covers the commands added in issues 03–07, on top of `status`
-(see [state-schema.md](state-schema.md)).
+This page expands selected contracts. Run `devrites-engine help` for the
+exhaustive current command and hook inventory; see
+[state-schema.md](state-schema.md) for `status` and the underlying state model.
 
 ## Exit codes
 
@@ -13,11 +16,11 @@ This covers the commands added in issues 03–07, on top of `status`
 | ---- | ------------------------------------------------------------- |
 | `0`  | ok / gate passed                                              |
 | `2`  | usage error (bad args, unknown command, unknown `--harness`)  |
-| `3`  | blocked — a gate pause or a version-skew refuse (`doctor`)    |
+| `3`  | blocked: a gate pause or a version-skew refuse (`doctor`)    |
 
 Exit `3` is always a **pause, not a crash**: a structured, actionable message
 naming exactly what to resolve, then retry. This keeps enforcement safe under
-AFK — a run pauses rather than hard-failing. Both a completeness gate
+AFK. A run pauses rather than hard-failing. Both a completeness gate
 (`readiness`/`seal`) and a `doctor` refuse (state schema newer than the binary
 supports) use it.
 
@@ -26,11 +29,11 @@ supports) use it.
 Deterministic completeness gates. Enforcement is **phase-relative** and
 **gate-scoped**: a gate checks only the sections it needs, only when run.
 
-- `devrites-engine readiness <slug>` — are the sections required to **leave the
-  feature's current phase** complete? A section that is not yet required (e.g.
+- `devrites-engine readiness <slug>` asks whether the sections required to **leave the
+  feature's current phase** are complete. A section that is not yet required (e.g.
   `proof` during the `spec` phase) never blocks.
-- `devrites-engine seal <slug>` — is the feature complete against the **full seal-phase
-  requirement set**, regardless of its current phase?
+- `devrites-engine seal <slug>` asks whether the feature is complete against the **full seal-phase
+  requirement set**, regardless of its current phase.
 
 ```
 $ devrites-engine readiness auth-tokens
@@ -43,14 +46,14 @@ $ echo $?
 3
 ```
 
-## `doctor` — version triangle
+## `doctor`: version triangle
 
 `devrites-engine doctor` reports the three versions that can drift out of alignment and
 one legible verdict:
 
 ```
-binary: 2.6.1
-pack: 2.6.1
+binary: X.Y.Z
+pack: X.Y.Z
 state-schema: v1 (binary supports v1)
 verdict: ok: binary, pack, and state schema are compatible
 ```
@@ -66,11 +69,11 @@ The pack version is discovered from `.claude/devrites.version` or the project
 asserted. Doctor also warns when project extensions have artifacts but no optional
 `provenance.json`.
 
-## `snapshot` — workspace status JSON
+## `snapshot`: workspace status JSON
 
 `devrites-engine snapshot [slug]` emits the `devrites.workspace.v1` JSON contract.
 
-## `profile` — stable repo facts cache
+## `profile`: stable repo facts cache
 
 `devrites-engine profile get|refresh` caches question-agnostic repo facts for grounding skills: top-level layout, manifests, and digests for root docs, ADRs, CI/deploy files, and `.devrites` principles/conventions. It never calls a model or the network.
 
@@ -79,18 +82,19 @@ asserted. Doctor also warns when project extensions have artifacts but no option
 
 The cache lives under `/tmp/compound-engineering/devrites/repo-profile` by default and is invalidated when profile-input files are dirty or newly added. Skills still re-scan candidate-specific code fresh.
 
-## `migrate` — legacy aliases and old layouts
+## `migrate`: legacy aliases and old layouts
 
 `devrites-engine migrate` preserves old workspaces while the canonical live location is
 `.devrites/work/<slug>/`. Older `.devrites/features/<slug>/` workspaces remain
 readable, and the migration path is:
 
-- **idempotent** — a second run is a no-op (`already up to date`);
-- **backed up** — the pre-migration `work/` and `ACTIVE` are snapshotted to a
+- **idempotent**: a second run is a no-op (`already up to date`);
+- **backed up**: the pre-migration `work/` and `ACTIVE` are snapshotted to a
   timestamped `.migrate-backup-*` directory before anything changes;
-- **lossless** — canonical files are added without deleting aliases. `README.md`
+- **lossless**: canonical files are added without deleting aliases. `README.md`
   is the preferred workspace map while `feature.md` / `index.md` remain readable;
-  `evidence.md` is preferred while `proof.md` remains a proof alias.
+  `state.md` is preferred while `status.md` remains a cursor alias; `evidence.md`
+  is preferred while `proof.md` remains a proof alias.
 
 The phase is derived from the legacy `state.md`, defaulting to `build` when it
 can't be read.
@@ -100,7 +104,7 @@ can't be read.
 One binary serves both Claude Code and Codex through thin per-harness adapters.
 Every hook is **fail-open and read-only unless it explicitly gates**.
 
-- `devrites-engine hook orient --harness=H` — emits the SessionStart orientation for the
+- `devrites-engine hook orient --harness=H` emits the SessionStart orientation for the
   active feature (named by `.devrites/ACTIVE`) as the harness's
   `hookSpecificOutput.additionalContext` envelope. With no active feature (or a
   stale pointer), the first-ever such session instead gets a one-time starting
@@ -108,20 +112,20 @@ Every hook is **fail-open and read-only unless it explicitly gates**.
   brownfield → `/rite-adopt`, …); the `.devrites/.first-run-shown` marker keeps
   it from repeating. Silent (exit `0`, no output) outside a workspace or once
   the marker exists.
-- `devrites-engine hook auq` — PostToolUse capture of an `AskUserQuestion`
-  exchange: appends each question + chosen answer to `.devrites/timeline.jsonl`
+- `devrites-engine hook auq` captures an `AskUserQuestion` exchange after tool use.
+  It appends each question + chosen answer to `.devrites/timeline.jsonl`
   and the feature's `events.jsonl`, so HITL decisions are recorded at the
-  substrate instead of trusted to the model's bookkeeping. Capture only — never
+  substrate instead of trusting the model's bookkeeping. It only captures data and never
   tunes, blocks, or replies; silent outside an active workspace. Claude-only by
-  design: Codex has an equivalent tool (`request_user_input`) but emits no hook
-  event for it — its PostToolUse matches only Bash/`apply_patch`/MCP calls, and
+  design. Codex has an equivalent tool (`request_user_input`) but emits no hook
+  event for it. Codex PostToolUse matches only Bash/`apply_patch`/MCP calls, and
   the user-input-requested event was declined upstream (openai/codex#12524).
-- `devrites-engine hook stop-gate --harness=H` — refuses to end a turn at a provably
-  inconsistent **rest point** (a feature claiming completion — phase `seal`/`ship`
-  — with empty `evidence.md` / `proof.md`). NOT whole-feature completeness, so normal
-  in-progress work is never blocked. **Observe by default** — a would-block is
+- `devrites-engine hook stop-gate --harness=H` refuses to end a turn at a provably
+  inconsistent **rest point**, such as a feature in phase `seal` or `ship` with
+  empty `evidence.md` or `proof.md`. It does not check whole-feature completeness,
+  so normal in-progress work is never blocked. It observes by default: a would-be block is
   appended to the feature's `.stop-gate.log` (mirroring `devrites-engine hook stop-gate`)
-  rather than gating; set `DEVRITES_STOP_GATE=enforce` to actually block.
+rather than gating; set `DEVRITES_STOP_GATE=enforce` to block.
   Loop-guarded by the harness's `stop_hook_active` so it can never wedge a
   session.
 
@@ -135,54 +139,55 @@ blocked):
 command -v devrites-engine >/dev/null 2>&1 && devrites-engine hook orient --harness=claude || exit 0
 ```
 
-## `ledger` — the living capability store
+## `ledger`: the living capability store
 
 `devrites-engine ledger <sub>` maintains `.devrites/specs/<capability>/spec.md`, the cumulative
-record of proven behavior (see [state-schema.md § Capability ledger](state-schema.md#capability-ledger--specs)).
-Feature specs carry deltas (`## ADDED/MODIFIED/REMOVED Requirements — capability: <c>`); the fold
-is a header-identity upsert/delete, so it is **idempotent** — re-syncing a feature is a no-op.
+record of proven behavior (see [state-schema.md § Capability ledger](state-schema.md#capability-ledger-specs)).
+Feature specs carry deltas under an `ADDED`, `MODIFIED`, or `REMOVED`
+Requirements heading tagged with `capability: <c>`. The fold uses header identity
+for upserts and deletes, so re-syncing a feature is a no-op.
 
-- `ledger sync <workspace-dir>` — fold a feature's deltas into every capability they touch (ADDED
+- `ledger sync <workspace-dir>`: fold a feature's deltas into every capability they touch (ADDED
   append, MODIFIED replace, REMOVED delete). Called from `/rite-ship` on GO. Exit `0`.
-- `ledger diff <workspace-dir>` — dry-run the fold (the change preview shown before sync). Exit `0`.
-- `ledger validate` — grammar-lint every ledger spec. Exit `0` clean · `1` on a violation.
-- `ledger list` / `ledger show <capability>` — read the ledger (used by `/rite-spec` and
+- `ledger diff <workspace-dir>`: dry-run the fold (the change preview shown before sync). Exit `0`.
+- `ledger validate`: grammar-lint every ledger spec. Exit `0` clean · `1` on a violation.
+- `ledger list` / `ledger show <capability>`: read the ledger (used by `/rite-spec` and
   `/rite-adopt` to write deltas against the current contract). Exit `0` · `1` unknown capability.
 
 `spec-validate <dir> --against .devrites/specs` cross-checks a spec's delta classification against
 the ledger (ADDED must be new; MODIFIED/REMOVED must already exist) and validates Edge Coverage /
-Prohibitions tables — a blocking spec-gate check.
+Prohibitions tables as a blocking spec-gate check.
 
-## `analyze` — cross-artifact coverage & consistency
+## `analyze`: cross-artifact coverage & consistency
 
 `devrites-engine analyze [slug]` cross-checks a feature's `spec.md` against its `tasks.md` before
 any code is written, so a coverage gap surfaces as a one-line plan edit instead of a reslice
 mid-build. It emits a markdown report with four passes:
 
-- **Coverage** — a spec `AC-###` that no slice `Satisfies:` (**CRITICAL**; legacy `[ACn]` remains supported).
-- **Consistency** — a slice that `Satisfies:` an AC the spec never defines (**CRITICAL**).
-- **Orphan slice** — a slice satisfying no acceptance criterion (warn).
-- **Ambiguity** — an unquantified vague adjective (`fast`, `robust`, `intuitive`, …) or an
+- **Coverage**: a spec `AC-###` that no slice `Satisfies:` (**CRITICAL**; legacy `[ACn]` remains supported).
+- **Consistency**: a slice that `Satisfies:` an AC the spec never defines (**CRITICAL**).
+- **Orphan slice**: a slice satisfying no acceptance criterion (warn).
+- **Ambiguity**: an unquantified vague adjective (`fast`, `robust`, `intuitive`, …) or an
   unresolved placeholder (`TODO`, `TKTK`, `???`) in the spec (warn).
 
 It closes with a **Metrics** line (criteria count, coverage %, orphan + ambiguity counts) so the
-vet gate reports a number, not just a pass/fail. Exit `0` clear · `1` at least one CRITICAL ·
+vet gate reports a number instead of only pass or fail. Exit `0` clear · `1` at least one CRITICAL ·
 `2` no workspace (no active slug, or `spec.md`/`tasks.md` missing). `/rite-vet` runs it in its
-cross-artifact gate (step 2a) and layers the semantic passes the engine can't do — terminology
-drift, duplicated/conflicting requirements — on top of this deterministic floor.
+cross-artifact gate (step 2a) and adds semantic checks for terminology drift and
+duplicated or conflicting requirements on top of this deterministic floor.
 
-## `review-integrity` — the silent-reviewer gate
+## `review-integrity`: the silent-reviewer gate
 
 `devrites-engine review-integrity [slug]` guards the failure opposite to noise: a reviewer that
 returns "looks good, nothing found". It parses `review.md`'s `## Spec` / `## Code review` axis
 sections and flags any that carry neither a bold-labeled finding nor a `No-findings:` justification.
-A zero-count summary line does **not** count as findings — an all-zero tally is the rubber-stamp
+A zero-count summary line does **not** count as a finding. An all-zero tally is the rubber-stamp
 this catches. Exit `0` every axis accounted for (or no/freeform `review.md`) · `1` an axis is silent
 and unjustified. `/rite-review` runs it after writing `review.md`; `/rite-seal` treats `rc=1` as an
 Important on the review's completeness. The honesty contract mirrors `doubt-coverage` and the
-footprint roster — it checks the *account* is present, not its quality.
+footprint roster: it checks the *account* is present, not its quality.
 
-## `timeline` — append-only session trace
+## `timeline`: append-only session trace
 
 `devrites-engine timeline log|list` records compact session events in `.devrites/timeline.jsonl`.
 It is for reconstructing what happened across long agent runs: which rite or skill acted, what
@@ -199,14 +204,22 @@ Records are JSONL, append-only, and safe for concurrent short-lived engine calls
 update DevRites through the npm flow (`npx devrites ...`); this command is part of the installed
 engine, not a Claude/Codex plugin distribution path.
 
-## `health` — compact quality history
+## `health`: code-health dashboard and history
 
-`devrites-engine health record|list` keeps `.devrites/health-history.jsonl`, a small longitudinal
-quality signal for the workspace. The score is intentionally caller-owned: an agent, CI job, or
-human can record the observed health after a review, quality gate, or cleanup pass without the
-engine pretending to infer a universal metric.
+`devrites-engine health`, `health run`, and `health check` run the known project
+checks (available npm test/lint/typecheck/build scripts, `go test`, `pytest`, and
+DevRites scans where present), print a PASS/WARN/FAIL dashboard, and append the
+result to `.devrites/health.jsonl`. These commands execute project checks; they
+are not a substitute for reviewing those scripts before use.
+
+The legacy `health record|list` surface remains available for manual scores.
+`record` appends `.devrites/health-history.jsonl`; `list` tails
+`.devrites/health.jsonl` when dashboard history exists, otherwise the legacy file.
+Manual scores are intentionally caller-owned: name the observed evidence rather
+than asking the engine to infer a universal metric.
 
 ```bash
+devrites-engine health run
 devrites-engine health record 8.5 "tests green; one follow-up" --note "review-fingerprints stable"
 devrites-engine health list --limit 10
 ```
@@ -215,7 +228,7 @@ Scores must be `0..10`. The label should name the evidence, not a vibe. Skill he
 until DevRites records per-skill run outcomes; use `scripts/skill-pruning-audit.mjs` for pruning
 signals instead of inventing telemetry.
 
-## `review-fingerprints` — stable IDs for findings
+## `review-fingerprints`: stable IDs for findings
 
 `devrites-engine review-fingerprints [--write] [slug]` scans `.devrites/work/<slug>/review.md` for
 bold severity labels (`Critical`, `Important`, `Suggestion`, `Nit`, `FYI`) and emits stable
@@ -230,19 +243,20 @@ The IDs make recurring findings, dismissals, and later learning easier to correl
 copying full review text into every downstream surface. `review-integrity` remains the gate; this
 command only records stable references.
 
-## `reviewer-stats` — dispatch outcomes that gate the fan-out
+## `reviewer-stats`: dispatch outcomes that gate the fan-out
 
 `devrites-engine reviewer-stats record <agent> <surviving-findings> [slug]` appends one dispatch
 outcome to `.devrites/reviewer-stats.jsonl` (cross-feature, append-only).
 `devrites-engine reviewer-stats report [--json]` grades each reviewer deterministically:
 
-- `run (always-on)` — the unconditional axes (`spec-reviewer`, `code-reviewer`, `test-analyst`).
-- `run (insurance — never gated)` — `security-auditor` and `doubt-reviewer`: a dry streak is
+- `run (always-on)`: the unconditional axes (`spec-reviewer`, `code-reviewer`, `test-analyst`).
+- `run (insurance; never gated)`: `security-auditor` and `doubt-reviewer`. A dry streak is
   success, never a reason to skip.
-- `gate-candidate` — a conditional reviewer with zero surviving findings in its last 10+
-  dispatches; the fan-out may skip it as a *recorded* skip (see
-  `parallel-dispatch.md § Hit-rate gating`).
-- `run` — everything else.
+- `gate-candidate`: a conditional reviewer with zero surviving findings in its last 10+
+  dispatches; the fan-out may skip it as a *recorded* skip (see the shared
+  `pack/.claude/skills/devrites-lib/reference/parallel-dispatch.md` contract,
+  § Hit-rate gating).
+- `run`: everything else.
 
 ```bash
 devrites-engine reviewer-stats record devrites-performance-reviewer 0 auth-tokens
@@ -252,7 +266,7 @@ devrites-engine reviewer-stats report
 Thresholds live in the engine, not the prompt: the caller reads the verdict, it never re-derives
 or overrides the streak math (a user-requested full panel dispatches everything regardless).
 
-## `reviewers list` — bounded reviewer aliases
+## `reviewers list`: bounded reviewer aliases
 
 `devrites-engine reviewers list` validates same-adapter reviewer aliases from `.devrites/config.json`
 or flat `.devrites/config*` keys. It never executes a reviewer; it only checks the bounded config
@@ -268,19 +282,19 @@ surface (`cli` must be `claude` or `codex`; `model` and `agent` are opaque strin
 }
 ```
 
-## `extensions` / `overrides` — project extensibility
+## `extensions` / `overrides`: project extensibility
 
-Two project-local surfaces let a team extend the pack without forking it — full contract in
-[extensions.md](../extensions.md).
+Two project-local surfaces let a team extend the pack without forking it. The
+full contract is in [extensions.md](../extensions.md).
 
-- `extensions list|validate|sync` — user rites/reviewers under `.devrites/extensions/<name>/`, held
+- `extensions list|validate|sync`: user rites/reviewers under `.devrites/extensions/<name>/`, held
   to the pack's schema (`validate`, exit `1` on a malformed extension) and mirrored into `.claude/`
   (`sync`, validates first, refuses a broken set).
-- `overrides list|validate` — reviewer overrides under `.devrites/overrides/<agent>.md`, advisory
+- `overrides list|validate`: reviewer overrides under `.devrites/overrides/<agent>.md`, advisory
   house rules a shipped reviewer reads after its standards. `validate` exits `1` when an override
-  reads like it waives a gate — an override may add checks, never relax one.
+  reads like it waives a gate. An override may add checks but never relax one.
 
-## `context sync|show` — agent context
+## `context sync|show`: agent context
 
 `devrites-engine context sync [file ...]` upserts only the block delimited by
 `<!-- DEVRITES START -->` / `<!-- DEVRITES END -->` in project context files. With no file args it
@@ -292,7 +306,7 @@ active workspace, the source of that selection (`ACTIVE`, `DEVRITES_WORKSPACE`,
 `none`), and the Claude/Codex menu forms. `--json` emits one direct JSON document for wrappers that
 need to know where a command will act.
 
-## `runbook` — tiny local automation
+## `runbook`: tiny local automation
 
 `devrites-engine runbook list|validate|run|resume` executes flat YAML runbooks from
 `.devrites/runbooks/*.yaml`. Supported step forms are deliberately small:
@@ -315,9 +329,9 @@ replacement lifecycle.
 DevRites fans out reviewer subagents that each spawn the binary, so the real
 contention is between short-lived **processes**. State writes are hardened for it:
 
-- **append-only logs** use `O_APPEND` with small records — parallel writers never
+- **append-only logs** use `O_APPEND` with small records, so parallel writers never
   interleave or lose records;
-- **structured files** are written via temp-file + atomic rename — a reader (or a
+- **structured files** use a temporary file and atomic rename, so a reader (or a
   writer killed mid-write) never sees a half-written file;
-- **read-modify-write** takes a per-feature advisory `flock` (unix) — no lost
-  updates.
+- **read-modify-write** takes a per-feature advisory `flock` on Unix to avoid
+  lost updates.