devrites 3.0.4 → 3.0.5

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

package/docs/engine/state-schema.md

@@ -52,7 +52,8 @@ proven contract is shared, not per-clone. Grammar and delta rules:
 
 Backward compatibility: `.devrites/features/<slug>/` remains readable as a legacy
 workspace location. `feature.md` / `index.md` may stand in for `README.md`, and
-`proof.md` may stand in for `evidence.md`.
+`status.md` may stand in for `state.md`, while `proof.md` may stand in for
+`evidence.md`.
 
 ### Workspace maps
 
@@ -128,9 +129,12 @@ result: incomplete (missing: tasks)
   does not gate — gating is issue 04).
 - Unknown or missing slug → non-zero exit with a clear message on stderr.
 
-The engine makes **zero model or network calls**; `status` is a pure read of the
-files under `DEVRITES_ROOT` (or the nearest `.devrites/` above the working
-directory). A hand edit wins immediately because there is no status cache.
+`status` makes no model or network calls; it is a pure read of the files under
+`DEVRITES_ROOT` (or the nearest `.devrites/` above the working directory). A
+hand edit wins immediately because there is no status cache. Other workspace
+control-plane commands share that deterministic boundary; explicit
+install/update/source-cache I/O is isolated under `engine/internal/iohooks` as
+defined by ADR-0008.
 
 `.devrites/` is ignored **except** the capability ledger at `specs/`, which is
 committed shared truth — the recommended pattern is `.devrites/*` +

package/docs/engine/workspace-schema.md

@@ -34,7 +34,7 @@ Canonical live workspace:
       plan.md                   # technical approach and slice strategy
       tasks.md                  # vertical slices
       traceability.md           # AC/REQ -> slices -> tests/evidence/files matrix
-      state.md                  # compact cursor
+      state.md                  # compact cursor; status.md alias allowed
       evidence.md               # command/action proof; proof.md alias allowed
       browser-evidence.md       # optional UI/runtime browser proof
       drift.md                  # optional spec/plan drift register
@@ -49,8 +49,9 @@ Canonical live workspace:
 
 Backward compatibility: `.devrites/features/<slug>/` remains readable as an alias
 for `.devrites/work/<slug>/`; `feature.md` and `index.md` remain valid workspace
-maps; `proof.md` remains a proof alias for `evidence.md`. Migration should add the
-canonical files without deleting aliases.
+maps; `status.md` remains a cursor alias for `state.md`; `proof.md` remains a
+proof alias for `evidence.md`. Migration should add the canonical files without
+deleting aliases.
 
 ## Read Order
 
@@ -80,7 +81,7 @@ canonical files without deleting aliases.
 | `plan.md` | required from plan | `/rite-define` | implementation approach | 220 lines | Approach, Slice strategy, Validation strategy, Rollback | HOW lives here, not in `spec.md`. `Validation strategy` names the Key links — cross-slice wiring `/rite-prove` walks (or `none` for single-slice features). |
 | `tasks.md` | required from plan | `/rite-define` | build one slice | 280 lines | Slice index | Each `SLICE-###` has goal, AC IDs, likely files, tests/proof, mode, gate, dependencies, done condition. |
 | `traceability.md` | required from plan | `/rite-define` | coverage/review/seal | 220 lines | Coverage matrix | Matrix maps AC/REQ ID, slice IDs, test/proof, evidence ID, touched files, status. |
-| `state.md` | required | all phases | current cursor | 120 lines | Cursor | Compact table/key-value cursor; not an append-only narrative. |
+| `state.md` / `status.md` | required | all phases | current cursor | 120 lines | Cursor | `state.md` is canonical; `status.md` is a compatibility alias. Compact table/key-value cursor; not an append-only narrative. |
 | `evidence.md` / `proof.md` | required from prove | `/rite-build`, `/rite-prove` | proof and seal | 280 lines | Evidence log | `EVID-###`, command/action, result, related AC/slice IDs, limitations. Each acceptance criterion carries a proof class — `test` / `command` / `browser` / `judgment` (untagged reads `judgment`; `judgment` needs its one-line why). |
 | `browser-evidence.md` | UI only | `/rite-prove`, `/rite-polish` | UI/browser proof | 220 lines | Browser evidence, Visual Verdict | Must reference real route/viewports/actions and related IDs. |
 | `drift.md` | drift only | Spec Drift Guard | spec/plan reality mismatch | 160 lines | Drift register | `DRIFT-###`, status, evidence found, resolution, related IDs. |

package/docs/flow.md

@@ -10,22 +10,26 @@ For the full per-skill table, see [`command-map.md`](command-map.md). For the
 
 The happy path. Every arrow assumes the readiness gate of the previous phase
 passed; failures route through `/rite-plan repair` or `devrites-debug-recovery`.
-HITL slices pause before code is written; `/rite-resolve` is the resume verb.
+`/rite-temper` is the optional strategic branch; `/rite-vet` runs on every
+defined plan, with depth scaled to risk. HITL slices pause before code is
+written; `/rite-resolve` is the resume verb.
 
 ```mermaid
 flowchart LR
     Start([user has an idea]) --> Spec[/rite-spec/]
     Spec -.->|UI detected| Shape[devrites-ux-shape<br/>plan UX/UI → design-brief.md]
     Shape -.->|brief confirmed| Spec
+    Spec -.->|big / risky| Temper[/rite-temper/] -.->|strategy.md| Define
     Spec -->|spec.md ready| Define[/rite-define/]
-    Define -->|plan.md + tasks.md<br/>each slice tagged AFK/HITL| Build[/rite-build/]
+    Define -->|plan.md + tasks.md<br/>each slice tagged AFK/HITL| Vet[/rite-vet/]
+    Vet -->|every plan; light or full<br/>eng-review.md + test-plan.md| Build[/rite-build/]
     Build -->|one slice done<br/>+ evidence| Build
     Build -.->|"Forge: yes slice"| Forge[forge: K candidates<br/>→ devrites-forge-judge → 1 winner]
     Forge -.->|winner lands<br/>forge-report.md| Build
     Build -->|HITL gate fires| Await{{Awaiting human<br/>state.md + questions.md}}
     Await -->|"/rite-resolve &lt;qid&gt; &lt;answer&gt;"| Build
     Build -->|all slices built| Prove[/rite-prove/]
-    Define -.->|resumed / adopted / stalled<br/>code vs intent| Converge[/rite-converge/]
+    Build -.->|resumed / adopted / stalled<br/>code vs intent| Converge[/rite-converge/]
     Converge -.->|appends remaining slices| Build
     Prove -->|evidence captured| Polish[/rite-polish/]
     Polish -->|polish-report.md| Review[/rite-review/]
@@ -45,7 +49,7 @@ flowchart LR
     classDef repair fill:#4c1d95,stroke:#a78bfa,color:#f5f3ff
     classDef gate fill:#4c1d95,stroke:#a78bfa,color:#f5f3ff
     classDef internal fill:#0f172a,stroke:#9ca3af,color:#f9fafb
-    class Spec,Define,Build,Prove,Polish,Review,Seal,Ship2 phase
+    class Spec,Temper,Define,Vet,Build,Prove,Polish,Review,Seal,Ship2 phase
     class Shipped done
     class Repair repair
     class Await gate
@@ -291,11 +295,12 @@ The exact list of files per workspace and what each holds is in
 
 The `devrites-` prefix is collision-avoidance against bundled Claude Code
 skills (`prototype`, `handoff`, `triage`, `diagnose`). Visibility is the
-`user-invocable:` flag, not the prefix.
+`user-invocable:` flag, not the prefix; automatic model loading is controlled
+separately by `disable-model-invocation`.
 
 ```mermaid
 flowchart TB
-    subgraph Public["Public (user-invocable: true) — 24 skills"]
+    subgraph Public["Public (user-invocable: true) — 30 skills"]
         direction TB
         R1[/rite/]
         R2[/rite-spec/]
@@ -304,6 +309,7 @@ flowchart TB
         RV[/rite-vet/]
         R4[/rite-plan/]
         R5[/rite-build/]
+        RC[/rite-converge/]
         R6[/rite-prove/]
         R7[/rite-polish/]
         R8[/rite-review/]
@@ -317,6 +323,11 @@ flowchart TB
         RA[/rite-adopt/]
         RL[/rite-learn/]
         RD[/rite-doctor/]
+        RE[/rite-explain/]
+        RCU[/rite-customize/]
+        RDO[/rite-dogfood/]
+        RPOV[/rite-pov/]
+        RPF[/rite-pr-feedback/]
         IPT[/rite-pressure-test/]
         D1[/rite-zoom-out/]
         D2[/rite-prototype/]
@@ -340,7 +351,7 @@ flowchart TB
 
     classDef pub fill:#064e3b,stroke:#34d399,color:#ecfdf5
     classDef int fill:#1f2937,stroke:#9ca3af,color:#f9fafb
-    class R1,R2,RT,R3,RV,R4,R5,R6,R7,R8,R9,R12,R13,R10,R11,RQ,RF,RA,RL,RD,IPT,D1,D2,D3 pub
+    class R1,R2,RT,R3,RV,R4,R5,RC,R6,R7,R8,R9,R12,R13,R10,R11,RQ,RF,RA,RL,RD,RE,RCU,RDO,RPOV,RPF,IPT,D1,D2,D3 pub
     class I1,I2,I3,I4,I5,I6,I7,I8,I9,I10,I11,I12 int
 ```
 

package/docs/porting-to-a-new-harness.md

@@ -1,6 +1,8 @@
 # Porting DevRites to a new harness
 
-DevRites is distributed through `npx devrites` and installs project-local artifacts. Do not add a harness through a Claude/Codex plugin or marketplace path.
+DevRites' canonical distribution path is `npx devrites` (with the documented
+Bash bootstrap as a Node-free alternative), and host artifacts install into the
+target project. Do not add a harness through a Claude/Codex plugin or marketplace path.
 
 Before adding a host, add its thin adapter to `engine/internal/harness/harness.go`,
 update the frozen matrix in `compliance.go`, and prove the host can run DevRites
@@ -20,7 +22,9 @@ The harness must invoke DevRites and route to `/rite-spec` (or the host's explic
 - Session/project orientation runs automatically at startup/compact/resume, or the missing surface is recorded in `docs/harness-compliance.md`.
 - `devrites-engine` hooks/gates are wired, or each degraded gate has an honest fallback and confidence label.
 - Subagent support is mapped; if unavailable, reviewers/wrights use the documented inline fallback and label it.
-- Install, update, and uninstall paths stay project-local; no global writes.
+- Skills, agents, standards, hooks, and harness guidance stay project-local;
+  the optional shared `devrites-engine` executable is the sole sanctioned
+  global artifact and must remain skippable with `--no-binary`.
 - Generated artifacts and `docs/harness-compliance.md` are updated from the same source of truth.
 - Routing eval includes the React todo-list acceptance prompt.
 

package/docs/release.md

@@ -1,15 +1,16 @@
 # Release pipeline
 
-Releases are **fully automated** via [semantic-release](https://semantic-release.gitbook.io/): every push to `main` is analyzed; if the merged commits carry a `feat:`, `fix:`, `perf:`, `refactor:`, `build:`, `docs(README):` (or a `BREAKING CHANGE:` footer) the `.github/workflows/release.yml` job determines the next SemVer version and:
+Releases are **fully automated** via [semantic-release](https://semantic-release.gitbook.io/): every push to `main` is analyzed; if the merged commits carry a `feat:`, `fix:`, `perf:`, `refactor:`, `build:`, `docs(README):` (or a `BREAKING CHANGE:` footer), the `release` job in [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) determines the next SemVer version and:
 
-1. Runs `scripts/validate.sh` + install / uninstall smoke tests.
-2. Syncs the new version into `package.json` and the README status line (`scripts/sync-version.sh`).
-3. Builds a `dist/devrites-v<version>.tar.gz` release artifact via `scripts/build-release-tarball.sh` — the extractable bundle end-users get from the `curl | bash` installer. The bundle includes `pack/generated/` host-native Claude/Codex artifacts rendered from the canonical pack.
-4. Regenerates `CHANGELOG.md` from the commits.
-5. Publishes the `devrites` package to the npm registry (`@semantic-release/npm`, needs the `NPM_TOKEN` secret) — this is what `npx devrites@latest` resolves. `npm pack` renders the same `pack/generated/` artifacts during `prepack`; there is no `postpack` cleanup step.
-6. Commits the version bump + changelog as `chore(release): <version> [skip ci]`, creates a git tag `v<version>`, and publishes a GitHub Release with the tarball attached.
+1. Waits for the workflow's validation, full shell suite, strict Go-engine checks, Linux cross-compile smoke, and Windows Go tests.
+2. Regenerates `CHANGELOG.md` from the commits.
+3. Syncs the new version into `package.json` and the README status line (`scripts/sync-version.sh`).
+4. Builds `dist/devrites-v<version>.tar.gz` plus its SHA-256 sidecar via `scripts/build-release-tarball.sh`. The extractable bundle used by `curl | bash` includes host-native Claude/Codex artifacts regenerated from `pack/.claude/` into `pack/generated/`.
+5. Cross-compiles five `devrites-engine` release binaries (macOS arm64/amd64, Linux arm64/amd64, Windows amd64) plus a SHA-256 sidecar for each.
+6. Publishes the `devrites` package to npm (`@semantic-release/npm`, requiring `NPM_TOKEN`) — this is what `npx devrites@latest` resolves. `npm pack` regenerates the same `pack/generated/` artifacts during `prepack`; there is no `postpack` cleanup step.
+7. Commits the version bump + changelog as `chore(release): <version> [skip ci]`, creates tag `v<version>`, and publishes a GitHub Release with the tarball, checksum, binaries, and binary checksum sidecars attached.
 
-Local dry-run: `npm run release:dry` (shows the version bump + draft notes without publishing). Before publishing, `scripts/release-check.sh` builds the evidence packet: generated pack freshness, tarball checksum presence, `npx-pack-smoke`, install/update/uninstall, `validate-pack`, behavioral eval schema, and a README/docs check that install instructions stay `npx devrites ...` only. DevRites is not shipped through Claude or Codex plugin stores. The release job is gated by passing CI — a broken `main` won't ship.
+Local dry-run: `npm run release:dry` (shows the proposed version + notes without publishing). For a manual preflight, `bash scripts/release-check.sh` builds an evidence packet covering generated-pack freshness, tarball checksum presence, `npx-pack-smoke`, install/update/uninstall, `validate-pack`, behavioral-eval schema, and the documented npm distribution path. This preflight is available to maintainers but is not a hidden semantic-release step. DevRites is not shipped through Claude or Codex plugin stores. The release job is gated by passing CI — a broken `main` won't ship.
 
 ## Authoring commits that trigger releases
 
@@ -25,6 +26,6 @@ Husky + commitlint reject non-conventional messages at commit time, so you can't
 
 ## Dependency updates
 
-Dependabot watches the `npm` and `github-actions` ecosystems and opens a **weekly grouped PR** with all patch + minor bumps (see [`.github/dependabot.yml`](../.github/dependabot.yml)). The [`dependabot-auto-merge.yml`](../.github/workflows/dependabot-auto-merge.yml) workflow auto-approves + enables auto-merge (squash) on those PRs so they land the instant CI is green — no manual click. Major-version bumps stay open with a `needs-review` label so a human can scan the changelog before merging.
+Dependabot watches the `npm` and `github-actions` ecosystems and opens **weekly grouped PRs** for routine patch + minor bumps (see [`.github/dependabot.yml`](../.github/dependabot.yml)). The [`dependabot-auto-merge.yml`](../.github/workflows/dependabot-auto-merge.yml) workflow auto-approves + enables auto-merge (squash) on those PRs so they land when required checks are green. Major-version bumps stay open with a `needs-review` label so a human can scan the changelog before merging.
 
 > GitHub does not allow Dependabot to push directly to `main` — a PR is always opened. Auto-merge is the closest equivalent. Required CI checks still gate the merge.

package/docs/skills.md

@@ -132,7 +132,7 @@ blocks obvious multi-command `Next:` wording.
 |---|---|---|
 | [`rite-review`](../pack/.claude/skills/rite-review/SKILL.md) | Multi-axis feature-scoped review. Parallel **Spec axis** (`devrites-spec-reviewer`) + **Standards axis** (`devrites-code-reviewer`) sub-agents; severity-labeled findings. | Polish done; ready for a final pass. |
 | [`devrites-doubt`](../pack/.claude/skills/devrites-doubt/SKILL.md) | In-flight adversarial review of risky decisions — branching logic, boundaries, data/auth/API changes, migrations. | About to stand a "this is safe / scales / matches spec" claim. |
-| [`devrites-audit`](../pack/.claude/skills/devrites-audit/SKILL.md) | Read-only audit dispatch — picks the right reviewer subagent on the requested axis (`security` / `perf` / `simplify`). Single-axis only; multi-axis parallel fan-out lives inline in `/rite-seal` (see `rite-seal/reference/parallel-dispatch.md`). | Polish Phase 1 (`simplify`); review involves user input / auth / data / external integrations / secrets / permissions (`security`); performance is relevant or regression risk visible (`perf`). |
+| [`devrites-audit`](../pack/.claude/skills/devrites-audit/SKILL.md) | Read-only audit dispatch — picks the right reviewer subagent on the requested axis (`security` / `perf` / `simplify`). Single-axis only; multi-axis parallel fan-out lives inline in `/rite-seal` (see the [shared dispatch contract](../pack/.claude/skills/devrites-lib/reference/parallel-dispatch.md)). | Polish Phase 1 (`simplify`); review involves user input / auth / data / external integrations / secrets / permissions (`security`); performance is relevant or regression risk visible (`perf`). |
 
 ### Seal — GO / NO-GO decision