devrites 2.6.1 → 3.0.1

package/docs/command-map.md

@@ -3,6 +3,10 @@
 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
+comes from generated host artifacts copied by the npm installer; DevRites is not
+distributed as a Claude or Codex plugin.
+
 - **Workflow diagram** (top-level flow) → [`flow.md`](flow.md).
 - **Architecture rationale** → [`architecture.md`](architecture.md).
 - **Worked examples** → [`usage.md`](usage.md).
@@ -14,27 +18,55 @@ bundled Claude Code skill names (`prototype`, `handoff`, `triage`, `diagnose`,
 …). 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-zoom-out`, `rite-prototype`, `rite-handoff`,
-`rite-pressure-test`, `rite-autocomplete`); every `devrites-*` skill is
-model-invoked.
+`rite-doctor`, `rite-customize`, `rite-zoom-out`, `rite-prototype`, `rite-handoff`,
+`rite-pressure-test`, `rite-autocomplete`, `rite-explain`, `rite-pov`, `rite-dogfood`,
+`rite-pr-feedback`). `devrites-*` specialists are model-invoked; `devrites-lib` is the
+explicit non-workflow library exception.
+
+## Surface lifecycle
+
+- **Promoted:** shipped `rite-*`, `devrites-*`, generated host artifacts, and docs
+  in this map.
+- **Draft:** research or local experiments that are not copied into `pack/`.
+- **Deprecated:** compatibility shims with a removal note and a replacement path.
+- **Research:** source-intake notes under `docs/research/`; not installed.
+
+Only promoted surfaces are shipped by the npm package.
+
+## Engine command ownership
+
+Engine commands are not all phase steps. Keep each new command in one of these
+lanes so it is either executed automatically or intentionally operator-owned:
+
+| Lane | Commands | Owner |
+|---|---|---|
+| Workflow gates | `preamble`, `build-readiness`, `spec-skeleton`, `spec-validate`, `check-acceptance`, `evidence-fresh`, `coverage`, `doubt-coverage`, `budget`, `test-integrity`, `mutation-gate`, `package-existence`, `review-integrity`, `footprint`, `reconcile`, `conventions`, `learnings`, `review-fingerprints`, `timeline`, `health`, `progress` | Called by the relevant `rite-*` workflow or shared reply contract. |
+| Workspace utilities | `status`, `snapshot`, `analyze`, `archive-search`, `resolve`, `close-out`, `stuck`, `tick-afk`, `ledger`, `profile` | Called by a specific utility/phase when its condition is met. |
+| Low-level completeness API | `readiness`, `seal` | Available for scripts/CI and documented engine use. Feature rites use stricter phase-specific gates (`build-readiness`, `/rite-seal` phase contract) instead of auto-running these weaker aggregate checks. |
+| Install / operator / CI | `install`, `update`, `uninstall`, `doctor`, `migrate`, `validate-pack`, `harness-matrix`, `extensions`, `overrides`, `reviewers`, `hook`, `version` | Called by `npx devrites ...`, `/rite-doctor`, hooks, CI, or a human operator; do not auto-run during feature work just because the command exists. |
+
+Workflow-owned commands should have a concrete call site in a `rite-*` skill,
+phase contract, shared reply contract, or installed hook. Operator-owned commands
+must say who runs them.
 
 ## Public commands (`user-invocable: true`)
 
 | 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 `spec.md` (placement, what-it-resolves, gaps closed with options, design references). Creates the workspace. | codebase + codegraph/graphify | `spec.md`, `references/`, `references.md`, `brief.md`, `questions.md`, `decisions.md`, `assumptions.md`, `state.md` |
+| [`/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-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 plan + vertical task slices + state. Reads `strategy.md` if present. | `spec.md` (+ `strategy.md`) + references | `plan.md`, `tasks.md`, `state.md`, `decisions.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-plan`](../pack/.claude/skills/rite-plan/SKILL.md) | plan | `[mode]` | Decompose / reslice / repair / re-order / split / unblock an active plan. | 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. | workspace + diff | code + `state.md`, `evidence.md`, `touched-files.md` |
-| [`/rite-prove`](../pack/.claude/skills/rite-prove/SKILL.md) | prove | `[scope]` | Tests + build + runtime + browser proof of the completed feature. | workspace + diff | `evidence.md`, `browser-evidence.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-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-ship`](../pack/.claude/skills/rite-ship/SKILL.md) | ship | `[slug]` | Final phase. Requires a GO in `seal.md` → 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`. 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-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` |
@@ -44,8 +76,13 @@ model-invoked.
 | [`/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-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>/...` |
+| [`/rite-explain`](../pack/.claude/skills/rite-explain/SKILL.md) | utility | `[concept \| diff: \| walkthrough: \| since: \| idea]` | The **human** half of the learning loop (complement of `/rite-learn`, which teaches the repo). Turns a concept, diff, idea, or window of the user's own recent work into a dense personal explainer; diff inputs can produce a concern-ordered human review walkthrough. Grounds off `seal.md` / `evidence.md` / the diff / the archive. Read-only against source. | workspace + archive + diff + code | `.devrites/explainers/<date>-<slug>/explainer.md` or `walkthrough.md` |
+| [`/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 | — | Diagnose DevRites install + workspace health — install integrity, stale `.devrites/ACTIVE`, corrupt workspace, orphaned gates, broken hook wiring. Read-only report. Triggers: "rite doctor", "is DevRites healthy", "why isn't the workflow picking up my feature". | install + workspace | — |
+| [`/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 | — |
 
 ## Internal skills (`user-invocable: false`, model-invoked)
 
@@ -58,13 +95,13 @@ model-invoked.
 | [`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-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 (auto) or "reindex" | Keep codebase-memory-mcp / codegraph / graphify current after edits | manual force; no-ops when no index |
-| [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | failing tests/build/runtime | 6-phase: loop → reproduce → hypotheses → instrument → fix → cleanup | references split per phase |
+| [`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 |
 | [`devrites-api-interface`](../pack/.claude/skills/devrites-api-interface/SKILL.md) | cross-boundary slice | Stable API/contract design | FE/BE split |
 | [`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` |
-| [`reference/parallel-dispatch.md`](../pack/.claude/skills/rite-seal/reference/parallel-dispatch.md) (sibling in `rite-review/reference/`) | 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)
 
@@ -87,14 +124,14 @@ model-invoked.
 | [`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 |
 
-## Engineering rules (`pack/.claude/rules/`)
+## Engineering rules (`pack/.claude/skills/devrites-lib/reference/standards/`)
 
-Progressive-disclosure rules. Each `rite-*` skill Reads `core.md` as its
-first step (step 0); the rest are referenced on demand. Full index in
-[`pack/.claude/rules/README.md`](../pack/.claude/rules/README.md).
+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.
-- The other **22 on-demand** (read by the phase that needs them): `coding-style.md` · `prose-style.md` · `error-handling.md` · `testing.md` · `spec-grammar.md` · `code-review.md` · `principles.md` · `security.md` · `performance.md` · `observability.md` · `developer-experience.md` · `patterns.md` · `git-workflow.md` · `hooks.md` · `documentation.md` · `development-workflow.md` · `deprecation.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md` · `tooling.md`
+- 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.
 
 ## Trigger conditions (auto-selection)
@@ -108,7 +145,7 @@ first step (step 0); the rest are referenced on demand. Full index in
 | Performance requirement or suspected regression | `devrites-audit perf` (+ `devrites-performance-reviewer`) |
 | Failing tests / build / runtime / browser checks | `devrites-debug-recovery` |
 | Slice crosses a boundary or defines a public interface | `devrites-api-interface` |
-| Unfamiliar area, "zoom out", "map this" | `/rite-zoom-out` (uses codegraph/graphify) |
+| Explicit `/rite-zoom-out` / `$rite-zoom-out` | read-only structural map (uses codegraph/graphify) |
 | Every defined plan before build; "engineering review", "review the architecture", "lock in the plan", "test coverage check" | `/rite-vet` (+ `devrites-plan-reviewer`; depth scales to stakes, never skipped; always in `/rite-autocomplete`) |
 
 ## Code-graph integration
@@ -121,9 +158,9 @@ when available, falling back to file reads otherwise:
 - `/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`
+- `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
+- `devrites-frontend-craft` — component / token lookups
 
 ## Interactions (typical flow)
 

package/docs/engine/agent-contract.md

@@ -0,0 +1,92 @@
+# `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
+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:
+
+`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
+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.
+
+## Envelope
+
+```json
+{
+  "command": "spec-validate",
+  "ok": false,
+  "exitCode": 1,
+  "data": { "text": "<the command's verbatim stdout>" },
+  "diagnostics": [
+    {
+      "code": "spec_validate_delta_mismatch",
+      "severity": "error",
+      "message": "Requirement \"Dark mode\" (line 2) is marked ADDED but already exists in ledger capability \"theming\"",
+      "path": ".devrites/work/feat/spec.md",
+      "line": 2
+    }
+  ]
+}
+```
+
+| field | meaning |
+| ----- | ------- |
+| `command` | the subcommand that ran |
+| `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) |
+
+`data.text` preserves everything the text mode prints, so nothing is lost by
+choosing `--json`. Structured consumers key on `ok` / `exitCode` / `diagnostics`
+and ignore `data.text`; a human reads `data.text` and ignores the rest.
+
+## Diagnostic
+
+| field | meaning |
+| ----- | ------- |
+| `code` | stable, greppable slug (see catalog) |
+| `severity` | `error` · `warning` · `info` |
+| `message` | the finding, with any `<path>:` prefix and `(line N)` suffix lifted into fields |
+| `path` | source path, when the finding named one |
+| `line` | 1-based line, when the finding named one |
+
+## Exit-code contract
+
+| code | meaning |
+| ---- | ------- |
+| `0` | ok / gate passed / valid |
+| `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** |
+| `5` | a required input is missing (e.g. no `spec.md`) |
+
+Exit `3` is the AFK pause signal: resolve the reported gap and retry.
+
+## Diagnostic-code catalog
+
+Codes are `<command>_<kind>`. v1 is deliberately coarse so consumers can match on
+the prefix while the catalog grows specific kinds:
+
+| code | emitted by | means |
+| ---- | ---------- | ----- |
+| `spec_validate_grammar` | `spec-validate` | a SHALL / WHEN / THEN / Scenario grammar violation |
+| `spec_validate_delta_mismatch` | `spec-validate --against` | an ADDED that already exists, or a MODIFIED/REMOVED that doesn't |
+| `ledger_grammar` | `ledger validate` | a ledger spec fails the grammar |
+| `<command>_error` / `_warning` / `_info` | any | an unclassified stderr line at that severity |
+
+New specific codes append to this table; the `<command>_<severity>` fallback keeps
+any future stderr line representable without a code change. `engine/tests/json_contract_test.go`
+gauntlets the AFK-parsed commands so every `--json` run stays one parseable JSON document whose
+`exitCode` and `ok` match the process result.

package/docs/engine/commands.md

@@ -0,0 +1,323 @@
+# `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.
+
+This covers the commands added in issues 03–07, on top of `status`
+(see [state-schema.md](state-schema.md)).
+
+## Exit codes
+
+| code | meaning                                                       |
+| ---- | ------------------------------------------------------------- |
+| `0`  | ok / gate passed                                              |
+| `2`  | usage error (bad args, unknown command, unknown `--harness`)  |
+| `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
+(`readiness`/`seal`) and a `doctor` refuse (state schema newer than the binary
+supports) use it.
+
+## Gates: `readiness` / `seal`
+
+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.
+  `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 readiness auth-tokens
+gate: readiness
+feature: auth-tokens
+phase: build
+result: blocked (missing to leave "build": tasks)
+next: add real content to tasks.md, then re-run: devrites-engine readiness auth-tokens
+$ echo $?
+3
+```
+
+## `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
+state-schema: v1 (binary supports v1)
+verdict: ok: binary, pack, and state schema are compatible
+```
+
+- **Binary older than the pack** → a `WARN` (exit `0`): an older binary still
+  runs; update it when convenient.
+- **State schema a newer major than the binary supports** → a `REFUSE` (exit
+  `3`): the binary won't silently mis-parse newer state.
+- Additive schema changes (older state read by a newer binary) are always fine.
+
+The pack version is discovered from `.claude/devrites.version` or the project
+`package.json`; when neither exists the pack is reported `unknown` and no skew is
+asserted. Doctor also warns when project extensions have artifacts but no optional
+`provenance.json`.
+
+## `snapshot` — workspace status JSON
+
+`devrites-engine snapshot [slug]` emits the `devrites.workspace.v1` JSON contract.
+
+## `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.
+
+- `profile get` prints `HIT` + JSON, `MISS` + cache path, or `NO-CACHE` outside a git repo.
+- `profile refresh` derives the profile from disk and writes the cache.
+
+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
+
+`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
+  timestamped `.migrate-backup-*` directory before anything changes;
+- **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.
+
+The phase is derived from the legacy `state.md`, defaulting to `build` when it
+can't be read.
+
+## Hooks: `hook <name> --harness=claude|codex`
+
+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
+  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
+  nudge derived from the `first-task` token (greenfield → `/rite-spec`,
+  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`
+  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
+  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
+  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
+  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.
+  Loop-guarded by the harness's `stop_hook_active` so it can never wedge a
+  session.
+
+### Fail-open guard
+
+Hooks are wired behind an inline POSIX guard so a **missing binary is a no-op**
+that never wedges a session (a teammate without `devrites-engine` installed is never
+blocked):
+
+```sh
+command -v devrites-engine >/dev/null 2>&1 && devrites-engine hook orient --harness=claude || exit 0
+```
+
+## `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.
+
+- `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
+  `/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.
+
+## `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
+  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 ·
+`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.
+
+## `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
+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.
+
+## `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
+feature it touched, what decision it made, and whether a state transition happened. It does not
+gate anything; it is durable context for audits, handoffs, and later learning.
+
+```bash
+devrites-engine timeline log completed --skill rite-review --slug auth-tokens --outcome ok --decision "ship"
+devrites-engine timeline log state-change --slug auth-tokens --from build --to review --note "tests green"
+devrites-engine timeline list --limit 20
+```
+
+Records are JSONL, append-only, and safe for concurrent short-lived engine calls. Install and
+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
+
+`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.
+
+```bash
+devrites-engine health record 8.5 "tests green; one follow-up" --note "review-fingerprints stable"
+devrites-engine health list --limit 10
+```
+
+Scores must be `0..10`. The label should name the evidence, not a vibe. Skill health stays static
+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
+
+`devrites-engine review-fingerprints [--write] [slug]` scans `.devrites/work/<slug>/review.md` for
+bold severity labels (`Critical`, `Important`, `Suggestion`, `Nit`, `FYI`) and emits stable
+12-character IDs derived from severity + normalized finding text. With `--write`, it saves
+`.devrites/work/<slug>/review-fingerprints.jsonl`.
+
+```bash
+devrites-engine review-fingerprints --write auth-tokens
+```
+
+The IDs make recurring findings, dismissals, and later learning easier to correlate without
+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
+
+`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
+  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.
+
+```bash
+devrites-engine reviewer-stats record devrites-performance-reviewer 0 auth-tokens
+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
+
+`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
+surface (`cli` must be `claude` or `codex`; `model` and `agent` are opaque strings).
+
+```json
+{
+  "review": {
+    "reviewer_instances": {
+      "codex-deep": { "cli": "codex", "model": "o3" }
+    }
+  }
+}
+```
+
+## `extensions` / `overrides` — project extensibility
+
+Two project-local surfaces let a team extend the pack without forking it — full contract in
+[extensions.md](../extensions.md).
+
+- `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
+  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.
+
+## `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
+reads `.devrites/context.yaml` (`context_file:` or `context_files:`), then falls back to existing
+`AGENTS.md` / `CLAUDE.md`, then `AGENTS.md`. Paths must be project-relative.
+
+`devrites-engine context show [--json]` is read-only. It reports the project root, `.devrites` root,
+active workspace, the source of that selection (`ACTIVE`, `DEVRITES_WORKSPACE`, `DEVRITES_ROOT`, or
+`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
+
+`devrites-engine runbook list|validate|run|resume` executes flat YAML runbooks from
+`.devrites/runbooks/*.yaml`. Supported step forms are deliberately small:
+
+```yaml
+steps:
+  - engine: doctor
+  - rite: status
+  - shell: npm test
+  - gate: review before release
+```
+
+`engine` runs a local `devrites-engine` subcommand, `rite` prints the Claude/Codex dispatch form,
+`shell` runs in the project root, and `gate` writes `.devrites/runs/<id>/state.json` then exits `3`.
+Resume with `devrites-engine runbook resume <id>`. This is for repeatable local runbooks, not a
+replacement lifecycle.
+
+## Concurrency
+
+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
+  interleave or lose records;
+- **structured files** are written via temp-file + atomic rename — 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.