npm - devrites - Versions diffs - 3.0.5 → 3.0.7 - Mend

devrites 3.0.5 → 3.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (744) hide show

package/docs/command-map.md CHANGED Viewed

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

package/docs/engine/agent-contract.md CHANGED Viewed

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

package/docs/engine/commands.md CHANGED Viewed

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