devrites 3.0.3 → 3.0.5

package/docs/adr/0004-state-schema-phases-sections.md

@@ -3,6 +3,10 @@
 - **Status:** Accepted
 - **Date:** 2026-07-08 (backfilled)
 
+> Artifact filename direction was amended by
+> [ADR-0007](0007-canonical-live-workspace-filenames.md). Phase-relative section
+> completeness remains unchanged.
+
 ## Context
 
 A feature's working state must be legible to both humans and the engine, and
@@ -13,9 +17,8 @@ that don't exist yet (there's no proof during framing).
 
 ## Decision
 
-Model feature state as **six single-concern section files** — `spec`, `plan`,
-`decisions`, `tasks`, `proof`, `status` (with transitional aliases
-`evidence→proof`, `state→status` that `migrate` normalizes). Drive the lifecycle
+Model feature state as **six single-concern sections** — `spec`, `plan`,
+`decisions`, `tasks`, `proof`, `status`. Drive the lifecycle
 through the ordered rite-\* arc:
 `frame → spec → temper → define → plan → vet → build → converge → prove → polish → review → seal → ship → done`.
 Completeness is **phase-relative and additive**: the typed phase registry maps

package/docs/adr/0005-hooks-as-engine-subcommands.md

@@ -0,0 +1,39 @@
+# ADR-0005: Hooks are engine subcommands, not shell scripts
+
+- **Status:** Accepted
+- **Date:** 2026-07-08 (backfilled; see commits porting `reviewer-readonly`,
+  `subagent-orient`, and the guard hooks into the Go engine)
+
+## Context
+
+Lifecycle hooks (orient on session start, readonly-guard for reviewers,
+stop-gate, statusline, redwatch, …) began as standalone `pack/.claude/hooks/*.sh`
+scripts. Shell hooks drift from the engine's own state logic, are hard to test
+in isolation, behave differently across the two hosts, and duplicate parsing the
+engine already does.
+
+## Decision
+
+Hooks are **subcommands of the one Go binary**: `devrites-engine hook <id>`.
+The pack ships only `hooks.json` wiring plus host settings; every hook's logic
+lives in the engine, sharing the `orient`/`gate`/`state` core. A control plane
+selects which hooks fire: `DEVRITES_HOOK_PROFILE` (minimal / standard / strict)
+and `DEVRITES_DISABLED_HOOKS`. Each hook has a golden parity test
+(`tests/parity_*_test.go`) pinning its stdout + exit across both hosts.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Keep hooks as `.sh` scripts | Drift from engine state logic, per-host divergence, poor testability, duplicated parsing. |
+| One monolithic hook entry point | Loses per-hook enable/disable and per-hook golden tests. |
+| Node hook runtime | Reintroduces a runtime dependency ADR-0001 deliberately avoids. |
+
+## Consequences
+
+- Hooks are unit-testable Go with golden parity snapshots, not shell fixtures.
+- One implementation serves both hosts; the harness (ADR-0002) handles edge
+  translation.
+- Profiles make the hook surface tunable without editing wiring.
+- The pack's `hooks/*.sh` files are removed; `hooks.json` is the only pack-side
+  hook artifact.

package/docs/adr/0006-clock-seam-and-engine-ci-gates.md

@@ -0,0 +1,50 @@
+# ADR-0006: Clock seam + Go static-analysis CI gates
+
+- **Status:** Accepted
+- **Date:** 2026-07-08
+
+## Context
+
+Two gaps surfaced while studying a more mature peer system (GSD Core; see
+`docs/research/gsd-core-adoption.md`):
+
+1. **Unwired static analysis.** `engine/Makefile` defined `staticcheck` and
+   `govulncheck` targets, but CI ran only `gofmt` + `go vet`. No `-race`, no
+   custom analysis on the trust-root binary.
+2. **A wall-clock leak.** `resolve next-qid` derived today's date from a raw
+   `time.Now()` with no seam, so its golden snapshot was pinned to the date it
+   was recorded and failed **every other day** — a latent red the peer system's
+   clock-seam lint would have caught at author time.
+
+## Decision
+
+- **Clock seam.** Wall-clock reads in the resolve command flow through one
+  overridable point, `clockNow()`, honoring `DEVRITES_NOW` (RFC-3339 or bare
+  `YYYY-MM-DD`). Date-derived output is deterministic under test; goldens pin the
+  clock instead of tracking the real date.
+- **Engine CI gates.** The `engine` CI job installs pinned `staticcheck`
+  (2025.1.1) + `govulncheck` and runs both as **blocking** steps, and runs the
+  suite with `-race`. `make quality` mirrors this so a green local gate means a
+  green pipeline.
+- **Coverage** is measured (`make cover`) but **not** yet a hard floor: the
+  number is understated because most behaviour is exercised through CLI-level
+  integration tests in `tests/` that don't attribute to per-package coverage.
+  A ratchet-only floor is a follow-up once attribution is meaningful.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Regenerate the date golden and move on | Fixes it for one day; the test rots again at the next date boundary. The seam fixes the class. |
+| Introduce `golangci-lint` | New dependency + config surface; `staticcheck` + `govulncheck` were already defined in the Makefile — wire what exists. |
+| Inject a full `Clock` interface everywhere | Heavier than the one failing path needs; the env seam is the minimal correct fix. A shared clock package is a Proposed generalization. |
+| Hard coverage floor now | Misleading at ~23% aggregate due to integration-test attribution; a floor here would gate on noise. |
+
+## Consequences
+
+- The engine suite is deterministic across dates and race-checked; static
+  analysis and CVE scanning block on the trust-root binary.
+- `DEVRITES_NOW` is a supported test seam; other date-deriving commands
+  (`learnings`, `conventions`, `footprint`, `stuck`) still read `time.Now()`
+  directly and can adopt the same seam when they need deterministic output.
+- Guard test `tests/adr_0006_clock_seam_test.go` locks the seam behaviour.

package/docs/adr/0007-canonical-live-workspace-filenames.md

@@ -0,0 +1,36 @@
+# ADR-0007: Canonical live workspace filenames
+
+- **Status:** Accepted
+- **Date:** 2026-07-20
+
+## Context
+
+ADR-0004 established phase-relative `proof` and `status` sections while the
+live workspace later standardized its human-facing artifacts on `README.md`,
+`state.md`, and `evidence.md`. Shipped skills, validators, the typed workflow
+registry, and user documentation already write those names, but migration and
+some engine comments still normalized in the opposite direction.
+
+## Decision
+
+Use `README.md`, `state.md`, and `evidence.md` as the canonical live workspace
+map, cursor, and proof log. Continue reading `feature.md`/`index.md`, `status.md`,
+and `proof.md` as compatibility aliases. `devrites-engine migrate` adds missing
+canonical files from aliases without deleting or overwriting either form.
+Internal `proof` and `status` section identifiers remain conceptual completeness
+names, not canonical filename declarations.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Restore `feature.md`, `status.md`, and `proof.md` as canonical | Would reverse the shipped workspace contract and require coordinated changes across skills, validators, docs, fixtures, and generated hosts. |
+| Treat both directions as equally canonical | Makes migration non-idempotent and leaves writers without one preferred target. |
+| Delete aliases after migration | Risks data loss and breaks existing workspaces and older installed packs. |
+
+## Consequences
+
+- Migration direction matches the files produced and required by the live pack.
+- Existing aliases remain losslessly readable and are preserved on disk.
+- Schema version remains `1`; this is an additive filename normalization, not a
+  content-schema break.

package/docs/adr/0008-sanctioned-engine-network-boundary.md

@@ -0,0 +1,33 @@
+# ADR-0008: Sanctioned engine network boundary
+
+- **Status:** Accepted
+- **Date:** 2026-07-20
+
+## Context
+
+ADR-0001 described the Go control plane as network-free. The binary now also
+owns explicit installation/update and source-cache operations that require HTTP,
+while deterministic workspace bookkeeping still must not depend on network or
+model responses. The implemented boundary already isolates HTTP in one package.
+
+## Decision
+
+Keep deterministic workspace state, gate, hook, migration, and derivation logic
+network- and model-free. Permit network access only in `internal/iohooks` for
+explicit updater and source-cache operations. No other first-party package may
+import network clients, and no engine package may call a model API.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Forbid all network access in the binary | Would remove the verified updater and source-cache refresh behavior users already rely on. |
+| Allow each consumer its own HTTP client | Expands the audit surface and weakens the executable package boundary. |
+| Ship a second updater binary | Adds packaging, release, and cross-platform complexity without improving the existing package isolation. |
+
+## Consequences
+
+- Workspace verdicts remain deterministic and offline-capable.
+- Network behavior has one auditable package and one guard test.
+- The binary as a whole is not network-free; documentation must distinguish the
+  control-plane core from explicit I/O commands.

package/docs/adr/README.md

@@ -0,0 +1,58 @@
+# Architecture Decision Records
+
+An ADR captures **one** load-bearing decision: the context that forced it, the
+decision itself, the alternatives that were rejected and *why*, and the
+consequences accepted. The rejected-alternatives table is the point — it keeps
+the "why not X" from being re-litigated every quarter.
+
+`CLAUDE.md` points every agent here (`CONTEXT.md` + `docs/adr/` are the
+single-context domain record). Keep this directory the source of truth for
+architecture; per-feature `decisions.md` files stay scoped to that feature.
+
+## Convention
+
+- Filename: `NNNN-kebab-title.md`, zero-padded, monotonic.
+- Frontmatter fields: **Status** (Proposed / Accepted / Superseded by NNNN),
+  **Date** (YYYY-MM-DD), **Deciders** (optional).
+- Sections: **Context** → **Decision** → **Alternatives considered** (a table:
+  option · why rejected) → **Consequences**.
+- **Guard test:** an accepted ADR that asserts a runtime invariant SHOULD have a
+  named regression test — `engine/tests/adr_NNNN_*_test.go` — so the decision
+  has an executable proof it still holds. Reference the ADR number in the test's
+  doc comment.
+
+## Template
+
+```markdown
+# ADR-NNNN: <title>
+
+- **Status:** Accepted
+- **Date:** YYYY-MM-DD
+
+## Context
+<the forces: what problem, what constraints, what was true at the time>
+
+## Decision
+<what we chose, stated as a present-tense rule>
+
+## Alternatives considered
+| Option | Why not |
+|--------|---------|
+| ... | ... |
+
+## Consequences
+<what this makes easy, what it costs, what follow-up it implies>
+```
+
+## Index
+
+| ADR | Title | Status | Guard test |
+|-----|-------|--------|-----------|
+| [0001](0001-go-engine-as-control-plane.md) | Go engine as deterministic control plane | Accepted | — |
+| [0002](0002-dual-host-harness.md) | Dual-host harness (Claude + Codex) | Accepted | `tests/parity_*_test.go` |
+| [0003](0003-gate-model-hitl-pause.md) | Gates block as HITL pause, never crash | Accepted | `tests/adr_0003_gate_exit_code_test.go` |
+| [0004](0004-state-schema-phases-sections.md) | Phase-relative section completeness | Accepted | `tests/adr_0004_required_by_phase_test.go` |
+| [0005](0005-hooks-as-engine-subcommands.md) | Hooks are engine subcommands, not shell scripts | Accepted | `tests/parity_*_test.go` |
+| [0006](0006-clock-seam-and-engine-ci-gates.md) | Clock seam + Go static-analysis CI gates | Accepted | `tests/adr_0006_clock_seam_test.go` |
+| [0007](0007-canonical-live-workspace-filenames.md) | Canonical live workspace filenames | Accepted | `internal/migrate/migrate_test.go`, `tests/migrate_cli_test.go` |
+| [0008](0008-sanctioned-engine-network-boundary.md) | Sanctioned engine network boundary | Accepted | `tests/meta_test.go` |

package/docs/agents/issue-driven-rites.md

@@ -4,8 +4,8 @@ Local issue files are the source of truth; external trackers are references only
 
 ## Flow
 
-1. Create `.scratch/<slug>/issue.md` for the problem and optional `.scratch/<slug>/prd.md` for product detail.
-2. Start `/rite-spec <slug>` from those files; copy decisions into `.devrites/work/<slug>/`, not back to the tracker.
-3. Run the normal lifecycle: `/rite-define` → `/rite-vet` → `/rite-build` → `/rite-prove` → `/rite-review` → `/rite-seal`.
-4. `/rite-ship` may include `Closes #NNN` only after a recorded type-GO.
-5. Follow-ups go to a new local `.scratch/<next-slug>/issue.md` first; external auto-posting is out of scope.
+1. Create `.scratch/<slug>/PRD.md` when product detail is needed and one or more numbered implementation issues under `.scratch/<slug>/issues/<NN>-<issue-slug>.md`, starting at `01`.
+2. Start `/rite-spec <slug>` from the relevant PRD/issues; copy lifecycle decisions into `.devrites/work/<slug>/`, while tracker status/comments remain in the local issue files.
+3. Run the normal lifecycle: `/rite-define` → `/rite-vet` → `/rite-build` → `/rite-prove` → `/rite-polish` → `/rite-review` → `/rite-seal` → `/rite-ship`.
+4. After a recorded type-GO, mark completed local issues `Status: resolved` and append the ship evidence; include `Closes #NNN` only when an external issue reference actually exists.
+5. Follow-ups become the next numbered local issue under `.scratch/<slug>/issues/` (or a new feature directory when scope differs); external auto-posting is out of scope.

package/docs/architecture.md

@@ -1,9 +1,11 @@
 # DevRites Architecture
 
-DevRites is a **distributed but coordinated** set of project-local Claude Code skills
-that make an AI coding agent behave like a disciplined senior engineer: clarify →
-spec+plan → build one verified slice → prove with evidence → polish → review → seal →
-ship.
+DevRites is a **distributed but coordinated** set of project-local Claude Code
+and Codex skill surfaces backed by one Go control plane. It makes an AI coding
+agent behave like a disciplined senior engineer: frame → spec → optional temper
+→ define → mandatory vet → build one verified slice → prove with evidence →
+polish → review → seal → ship. `converge` is the recovery state when live code
+and recorded intent need to meet again.
 
 For the `.devrites/` load order, file budgets, artifact schema, aliases,
 traceability rules, and phase-relative completeness model, see
@@ -11,20 +13,25 @@ traceability rules, and phase-relative completeness model, see
 
 ## Layers
 
-1. **Public workflow skills** — `.claude/skills/rite-*`, `user-invocable: true`. Each
-   owns exactly one phase and reads/writes the `.devrites/` workspace.
-   Sequence: `rite-spec`, `rite-define`, `rite-plan`, `rite-build`,
-   `rite-prove`, `rite-polish`, `rite-review`, `rite-seal`, `rite-ship`,
-   plus the read-only `rite-status`, the resume verb `rite-resolve` (answer
-   a HITL gate and clear `Awaiting human`), and the thin `/rite` menu.
+1. **Public lifecycle and workspace skills** — `.claude/skills/rite-*`,
+   `user-invocable: true`. Each owns one bounded phase or workspace transition.
+   Sequence: `rite-spec`, optional `rite-temper`, `rite-define`, mandatory
+   `rite-vet`, `rite-build`, recovery `rite-converge`, `rite-prove`,
+   `rite-polish`, `rite-review`, `rite-seal`, `rite-ship`; `rite-plan` repairs
+   or reslices an active plan,
+   plus the resume verb `rite-resolve` (answer a HITL gate and clear
+   `Awaiting human`). The thin `/rite` menu and read-only `rite-status` live in
+   the public utility layer below.
    `/rite-seal` **decides** GO/NO-GO and writes the verdict to `seal.md`;
-   `/rite-ship` is the eighth lifecycle phase that **executes** the
+   `/rite-ship` is the eighth core lifecycle rite that **executes** the
    irreversible git ladder and **closes** the task (archives the workspace,
    clears `ACTIVE`). Keeping the decision and the irreversible action as two
    separately-auditable steps is the point.
-2. **Public utility skills** — `.claude/skills/rite-zoom-out`,
-   `rite-prototype`, `rite-handoff`, `rite-pressure-test`, `rite-pov`,
-   `rite-dogfood`, `rite-pr-feedback`, and `rite-autocomplete` — public commands. `rite-autocomplete` is the
+2. **Public utility and on-ramp skills** — `rite-adopt`, `rite-quick`,
+   `rite-frame`, `rite-status`, `rite-doctor`, `rite-learn`, `rite-explain`,
+   `rite-customize`, `rite-zoom-out`, `rite-prototype`, `rite-handoff`,
+   `rite-pressure-test`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, and
+   `rite-autocomplete` — public commands. `rite-autocomplete` is the
    unattended orchestrator: it drives the whole lifecycle (spec → … → seal →
    ship) end-to-end, choosing the best option at each soft gate, pausing only
    on hard irreversible-risk / blocking / escalating gates or a NO-GO. The
@@ -37,16 +44,17 @@ traceability rules, and phase-relative completeness model, see
    `-doubt`, `-ux-shape` (plans UX/UI into `design-brief.md` at `/rite-spec`),
    `-frontend-craft`, `-browser-proof`, `-debug-recovery`,
    `-api-interface`, `-audit` (dispatches the security / perf / simplify
-   reviewer subagent on an axis argument). Model-invoked by public skills
-   or Claude's auto-selection; not menu noise. Whether a skill is public or
+   reviewer subagent on an axis argument), `-prose-craft`, and
+   `-refresh-indexes`. These 11 specialists are model-invoked by public skills
+   or host auto-selection; not menu noise. Whether a skill is public or
    internal is governed by the `user-invocable:` flag, not by the name
    prefix.
 
    Engineering rules live at `.claude/skills/devrites-lib/reference/standards/`.
    Workspace-operating lifecycle rites load `core.md` first and disclose phase-specific
-   files on demand; compact utilities keep a narrower local contract. Parallel reviewer fan-out at
-   `/rite-seal` is a reference file
-   (`rite-seal/reference/parallel-dispatch.md`), not a skill.
+   files on demand; compact utilities keep a narrower local contract. Parallel
+   reviewer fan-out at `/rite-seal` is the shared reference file
+   `devrites-lib/reference/parallel-dispatch.md`, not a skill.
 4. **Supporting references** — `reference/*.md` inside each skill. Long checklists,
    templates, and anti-rationalization tables loaded on demand (progressive
    disclosure) so `SKILL.md` bodies stay small.
@@ -131,17 +139,19 @@ Built-in / bundled Claude Code commands include `/plan`, `/review`, `/run`, `/ve
 `rite-` prefix avoids all of them. (Collision audit: `research/claude-code-skills-notes.md`.)
 
 ### Why a thin menu skill, not a mega-router
-`/rite` is **only** an entrypoint: it shows a compact phase-grouped menu, prints live
-`.devrites/ACTIVE` status via `` !`cmd` `` injection, and suggests the next command.
-It deliberately does **not** execute workflows or duplicate skill logic — that would
-recreate the mega-command problem. DevRites keeps selection thin and lets each phase
-own its context, rather than centralizing every workflow behind one command.
+`/rite` is **only** an entrypoint: it shows a compact phase-grouped menu, prints
+recommended-start guidance from `devrites-engine first-task`, and dispatches a
+named verb to its owning skill. Menu mode does not read raw workspace state;
+`/rite-status` owns detailed status. `/rite` deliberately does **not** duplicate
+workflow logic — that would recreate the mega-command problem. DevRites keeps
+selection thin and lets each phase own its context.
 
 ### Why internal skills exist
 Specialist processes (doubt, source-driven, frontend craft, browser proof, audits)
-are **disciplines**, not user commands. As `user-invocable: false` skills they:
+are **disciplines**, not user commands. As `user-invocable: false` specialist
+skills they:
 - stay out of the command menu (less cognitive load);
-- are invoked automatically by Claude or explicitly by a public skill when their
+- are invoked automatically by the host model or explicitly by a public skill when their
   trigger conditions hit;
 - keep each public `SKILL.md` small by housing the heavy process elsewhere.
 
@@ -165,8 +175,8 @@ and `rite-polish-ui` sub-skills, but a skill-on-skill dispatch is fragile
 (the caller has to re-discover the callee by description) and the two halves
 share the same operating rules. They now live as `reference/code.md` and
 `reference/ui.md` inside the same skill, loaded only when their phase
-trigger fires — the canonical progressive-disclosure pattern from
-<https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices>.
+trigger fires — the supporting-files pattern from Claude Code's current
+[skills reference](https://code.claude.com/docs/en/slash-commands#add-supporting-files).
 `/rite-polish` is the orchestrator: always reads `reference/code.md`
 (Phase 1 + 2), detects UI scope from the diff and reads `reference/ui.md`
 (Phase 3 + 4) when needed. The orchestrator accepts mode tokens (`bolder`,
@@ -182,7 +192,7 @@ Deciding "is this safe to ship" and *actually shipping* are different acts with
 different blast radii. `/rite-seal` is a **pure decision gate**: it walks acceptance
 against evidence, fans out the fresh-context reviewers, and writes the GO / NO-GO
 verdict to `seal.md` — it runs no git. On GO it sets `state.md` `Next step:
-/rite-ship` and stops. `/rite-ship` is the eighth lifecycle phase: it refuses to run
+/rite-ship` and stops. `/rite-ship` is the eighth core lifecycle rite: it refuses to run
 without a GO recorded in `seal.md`, renders the type-`GO` prompt, runs the irreversible
 git ladder (commit → push → tag/PR per the project's convention), writes `ship.md`,
 then **closes the task** — sets phase `done` and archives `.devrites/work/<slug>/` →
@@ -192,8 +202,9 @@ decision and the irreversible action as two separately-auditable steps is the po
 
 ### Why `/rite-autocomplete` exists (the unattended orchestrator)
 Some features are routine enough to run end-to-end without per-phase human iteration.
-`/rite-autocomplete` drives the whole lifecycle (spec → define → build×N → prove →
-polish → review → seal → ship) by reading each phase's `SKILL.md` and executing its
+`/rite-autocomplete` drives the whole lifecycle (spec → temper → define → vet →
+build×N → prove → polish → review → seal → ship) by reading each phase's
+`SKILL.md` and executing its
 workflow, carrying state through the workspace files rather than chat. A vague prompt
 triggers an up-front `devrites-interview` — the only interactive window — after which it
 runs unattended, choosing the best option at each soft gate and recording the rationale
@@ -247,15 +258,18 @@ contract.
   lens + `rite-adopt` (onboard an existing codebase) + `rite-learn` (cross-feature
   lessons) + `rite-status` + `rite-doctor` (install health) +
   `rite-customize` (project-local overrides/extensions) +
+  `rite-explain` (grounded concept/diff/idea/recap explanation) +
   `rite-pov` (external-option verdicts) + `rite-dogfood` (browser QA) +
   `rite-pr-feedback` (review-thread closure) +
-  the `rite-plan` replan verb + the `rite-resolve` resume verb + 4 ideation /
+  the `rite-plan` replan verb + `rite-converge` recovery + the `rite-resolve`
+  resume verb + 4 ideation /
   handoff utilities (`rite-zoom-out`, `rite-prototype`, `rite-handoff`,
   `rite-pressure-test`) + `rite-autocomplete` (the unattended full-lifecycle
   orchestrator) — plus 11 internal model-invoked `devrites-*` specialists and the
   `devrites-lib` library, not one mega-command. The `devrites-` prefix is a
   namespace (collision avoidance), not a public/internal marker —
-  `user-invocable:` is. All `devrites-*` skills are model-invoked.
+  `user-invocable:` is. The 11 specialists are model-invoked;
+  `devrites-lib` explicitly disables model invocation.
 - **Selection**: the `/rite` menu skill carries the routing table; every
   workflow skill enforces a "right skill, right time" rule in its body.
 - **State**: durable `.devrites/` Markdown that survives compaction and new sessions.
@@ -267,21 +281,22 @@ contract.
 - **Slice rule**: build **one vertical slice, then stop** — no auto-continue.
 - **Drift**: an explicit **Spec Drift Guard** in build/prove/polish/review/seal.
 - **Design**: `devrites-frontend-craft` + a four-phase `/rite-polish` orchestrator (code + backend always; UI normalize + polish when UI is in scope).
-- **Review**: **feature-scoped** five-axis review with severity labels + fresh-context
-  subagents at the seal.
+- **Review**: **feature-scoped** multi-axis review with severity labels +
+  fresh-context subagents at the seal.
 - **Scope**: clarify → seal (decide) → ship (the irreversible git ladder —
   commit → push → tag/PR — per the project's own convention) → close; the CI
   pipeline stays with the project.
-- **Install**: project-local, manifest-managed; ships DevRites' own engineering rules.
+- **Install**: project-local, manifest-managed host artifacts; the optional
+  shared engine binary is the sole sanctioned global artifact.
 
 ## Deviations from the original build brief (and why)
 
-1. **`user-invocable` semantics corrected from the docs.** The brief said set
-   `user-invocable: true` for public and `false` for internal. That is exactly right
-   for internal skills. For public skills we keep them model-invocable (no
-   `disable-model-invocation`) so phases can hand off and the selector can route;
-   per-phase side-effect discipline (e.g. "stop after one slice") is enforced in the
-   skill **body**, which is the correct mechanism (invocation flags can't express it).
+1. **Invocation semantics are explicit in frontmatter.** `user-invocable`
+   controls whether a skill is a public command; `disable-model-invocation`
+   independently marks explicit-only public utilities and the internal
+   `devrites-lib` library. Model-invocable phases can still hand off and route;
+   per-phase side-effect discipline (for example, "stop after one slice") is
+   enforced in the skill **body**, because invocation flags cannot express it.
 2. **`context: fork` used selectively.** Verified it is a real field (isolated
    subagent, body-as-prompt, no conversation history). It is applied only to the three
    self-contained read-only audit skills (`devrites-audit simplify`,
@@ -298,6 +313,7 @@ acceptance criteria.
 ## Repository layout
 
 See the top-level tree in `README.md` and the installed-target tree in `usage.md`.
-Source pack lives under `pack/.claude/` (skills, agents, and rules); the installer copies
-it into a target project's `.claude/`, including DevRites' engineering rules in
-`.claude/skills/devrites-lib/reference/standards/`.
+The canonical source pack lives under `pack/.claude/` (skills, agents, rules,
+and Claude hook wiring). The build renders `pack/generated/` host artifacts;
+the installer writes Claude assets under project `.claude/` and Codex assets
+under `.agents/`, `.codex/`, and the managed `AGENTS.md` block.

package/docs/capability-surface-selection.md

@@ -12,7 +12,9 @@ Pick the smallest surface that keeps the behavior deterministic:
 
 Rules:
 
-- Install and update through npm: `npx devrites ...`. No Claude/Codex plugin path.
+- npm (`npx devrites ...`) is the canonical distribution path. The supported
+  `curl | bash` bootstrap exists for environments without Node; neither path is
+  a Claude/Codex plugin or marketplace install.
 - Prefer the engine for gates; prompts may call gates, not reimplement them.
 - Prefer scripts for repo-local release/build glue that is not part of the user contract.
 - Do not add a dependency for what the Go engine or shell can do in a few lines.

package/docs/cli.md

@@ -9,6 +9,9 @@ project root.
 
 Install DevRites normally, then run the engine from the project root:
 
+The examples below are a curated working set. `devrites-engine help` is the
+exhaustive current command and hook inventory.
+
 ```bash
 devrites-engine preamble                 # workspace digest for the active feature
 devrites-engine snapshot [slug]          # machine-readable workspace/status snapshot
@@ -19,8 +22,10 @@ devrites-engine ledger sync <dir>        # fold a feature's spec deltas into the
 devrites-engine ledger list|show <cap>   # read the ledger — what the system already does
 devrites-engine context show --json      # report root, active workspace, and host command forms
 devrites-engine timeline log|list        # append/list session events, decisions, and state moves
-devrites-engine health record|list       # append/list compact workspace health history
+devrites-engine health run               # run known project checks + record a code-health dashboard
+devrites-engine health record|list       # append/list manual or dashboard health history
 devrites-engine review-fingerprints [slug] # stable IDs for review findings; --write saves JSONL
+devrites-engine reviewer-stats report --json # direct structured reviewer-dispatch verdicts
 devrites-engine progress [slug]          # compact phase/slice footer
 devrites-engine resolve <qid> "<answer>" # answer a HITL gate
 devrites-engine close-out <slug>         # archive a shipped feature and clear ACTIVE
@@ -34,7 +39,9 @@ The AFK-parsed read commands (`status`, `readiness`, `seal`, `spec-validate`,
 structured JSON contract and emits `schemaVersion: devrites.workspace.v1`
 directly rather than wrapping human text. Snapshot consumers should read
 `nextCommands.claude` or `nextCommands.codex` for the current host instead of
-hardcoding a `/rite-*` or `$rite-*` command form.
+hardcoding a `/rite-*` or `$rite-*` command form. `context show --json` and
+`reviewer-stats report --json` are also direct structured reports rather than
+envelopes.
 
 The npm `devrites` shim remains the installer/updater/uninstaller entry point and
 proxies these engine subcommands when `devrites-engine` is installed. Install and

package/docs/command-map.md

@@ -54,7 +54,7 @@ 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-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` |
@@ -84,7 +84,11 @@ must say who runs them.
 | [`/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 | — |
 
-## 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 |
 |---|---|---|---|

package/docs/engine/agent-contract.md

@@ -16,9 +16,11 @@ Other subcommands (hooks, `footprint`, `tick-afk`, mutating commands) do not acc
 `--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.
+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
 

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
 
@@ -49,8 +52,8 @@ $ echo $?
 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
 ```
@@ -90,7 +93,8 @@ readable, and the migration path is:
   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.
+  `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.
@@ -199,14 +203,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
 ```
@@ -240,8 +252,9 @@ outcome to `.devrites/reviewer-stats.jsonl` (cross-feature, append-only).
 - `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`).
+  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