devrites 5.13.0 → 5.14.0

package/README.md

@@ -1,184 +1,201 @@
 <p align="center">
-  <img src="images/logo.png" alt="DevRites">
+  <a href="https://devrites.com">
+    <img src="images/logo.png" alt="DevRites: AI can write the diff. Make it prove the release. Spec, Clarify, Define, Vet, Build, Prove, Polish, Review, and Seal are checked; Ship waits for a human GO." width="100%">
+  </a>
 </p>
 
-# DevRites
-
-DevRites is a repository-local workflow for building software with Claude Code,
-Codex, omp, pi, or Devin CLI. It turns a feature request into a spec, a sliced
-plan, working code, recorded proof, a release decision, and an explicit ship
-step.
+<p align="center">
+  <a href="https://www.npmjs.com/package/devrites"><img src="https://img.shields.io/npm/v/devrites?style=flat-square&label=npm&labelColor=191816&color=ab4737" alt="npm version"></a>
+  <a href="#hosts"><img src="https://img.shields.io/badge/hosts-Claude_Code_·_Codex_·_omp_·_pi_·_Devin-2d617e?style=flat-square&labelColor=191816" alt="Supported hosts"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A518-504b45?style=flat-square&labelColor=191816" alt="Node.js 18 or later">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-source--available-504b45?style=flat-square&labelColor=191816" alt="Source-available license"></a>
+</p>
 
-The work lives under `.devrites/`, not in chat history. A later session or a
-different agent can read the same plan, decisions, state, and evidence before it
-continues.
+<p align="center">
+  <a href="https://devrites.com"><b>Website</b></a> ·
+  <a href="docs/quick-reference.md"><b>Quick reference</b></a> ·
+  <a href="docs/command-map.md"><b>Command map</b></a> ·
+  <a href="docs/usage.md"><b>Worked examples</b></a> ·
+  <a href="CHANGELOG.md"><b>Changelog</b></a>
+</p>
 
-Executive fast path: **Spec → Build → Prove**. `/rite-spec` writes the
-contract, `/rite-build` implements one slice, `/rite-prove` binds evidence.
-Adaptive Clarify/Vet still run; they ask nothing when the contract is already
-complete. `/rite-quick` covers a small reversible change.
+<br>
 
-The core path is:
+DevRites is a repository-local workflow for AI coding agents. It turns a
+feature request into a spec, a sliced plan, working code, recorded proof, a
+release decision, and an explicit ship step. It runs inside Claude Code, Codex,
+omp, pi, and Devin CLI.
 
-`SPEC -> CLARIFY -> [TEMPER] -> DEFINE -> VET -> BUILD -> PROVE -> POLISH -> REVIEW -> SEAL -> SHIP`
+DevRites keeps that work in `.devrites/` inside your repository, where chat
+history can't lose it. After you clear the conversation, switch hosts, or hand
+the feature to another engineer, the next session reads the same plan,
+decisions, and evidence before it continues.
 
-Clarify is mandatory but adaptive, so it asks no questions when the contract
-is complete. Temper adds an optional strategic review. Vet is the only final
-readiness phase before Build.
+**Status:** [`v5.14.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.14.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
-Seal decides whether the feature is ready without changing git. Ship first runs
-a read-only preflight and discloses the exact Git attempt. A fresh literal `GO`
-then authorizes one attempt to collapse eligible checkpoints, stage and validate
-the exact candidate, commit and reverify it, perform any approved
-project-conventional push, tag, or PR action, and archive the workspace.
-Unattended runs may create local WIP checkpoint commits along the way, but they
-remain local unless Ship's disclosed plan includes an approved remote action.
+This is the latest published release; `main` may contain unreleased work.
 
-**Status:** [`v5.13.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.13.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+## Why DevRites
 
-This is the latest published release; `main` may contain unreleased work.
+| Without a workflow | With DevRites |
+| --- | --- |
+| The plan lives in a chat window and disappears on `/clear`. | Spec, plan, decisions, and questions are Markdown files in `.devrites/work/<slug>/`. |
+| The agent says "tests pass". | Proof must be positive and discriminating, and it is bound to a digest of the exact candidate files. |
+| The agent that wrote the code also reviews it. | Seventeen fresh-context specialist agents plan, review, audit, and prove. Only one of them can write code. |
+| Commits and pushes happen whenever the agent decides. | Seal decides `GO` or `NO-GO`. Ship acts only after you type a fresh, literal `GO`. |
+| Every change gets the same ceremony. | `/rite-quick` handles a small reversible change. The full lifecycle is for features and risky work. |
 
 ## Quick start
 
-### 1. Install DevRites
-
-Run this from the root of your project. Node.js 18 or later is required.
+**1. Install** from the root of your project. Node.js 18 or later is required.
 
 ```bash
 npx devrites@latest
 ```
 
 The installer adds project-local support for Claude Code, Codex, omp, pi, and
-Devin CLI. It does not write skills, agents, or hooks to `~/.claude`, `~/.codex`,
-`~/.pi`, or `~/.config/devin`.
-
-### 2. Choose the smallest route
+Devin CLI. It does not write skills, agents, or hooks to `~/.claude`,
+`~/.codex`, `~/.pi`, or `~/.config/devin`.
 
-DevRites scales the process to the change. Start with the least ceremony that
-still protects the work:
+**2. Pick the smallest route** that still protects the work.
 
-| Need | Claude Code | Codex |
+| You want to… | Claude Code, omp, pi, Devin | Codex |
 | --- | --- | --- |
-| Small, reversible change | `/rite-quick fix the CSV header typo` | `$rite-quick fix the CSV header typo` |
-| New feature or risky behavior | `/rite-spec add-csv-export` | `$rite-spec add-csv-export` |
+| Make a small, reversible change | `/rite-quick fix the CSV header typo` | `$rite-quick fix the CSV header typo` |
+| Build a new feature or risky behavior | `/rite-spec add-csv-export` | `$rite-spec add-csv-export` |
 | Resume an active feature | `/rite-status` | `$rite-status` |
 | Baseline an existing codebase | `/rite-adopt` | `$rite-adopt` |
+| Run the whole lifecycle unattended | `/rite-autocomplete` | `$rite-autocomplete` |
+
+**3. Follow the next recorded step.** `/rite-status` reads the active workspace
+and reports the phase, open questions, evidence, and the next command.
+
+> [!TIP]
+> The shortest path is Spec, Build, Prove. Clarify and Vet still run, but
+> they ask nothing when the contract is already complete.
+
+## The lifecycle
+
+<p align="center">
+  <img src="images/run-order.png" alt="Run order. Shape: 1 /rite-spec, 2 /rite-clarify, optional /rite-temper, 3 /rite-define, 4 /rite-vet. Build: 5 /rite-build, repeated for every slice. Prove: 6 /rite-prove, 7 /rite-polish, 8 /rite-review. Ship: 9 /rite-seal, 10 /rite-ship, then you type GO." width="100%">
+</p>
+
+In the default HITL mode, you run each command yourself, in this order. Each
+one stops when its phase is done and records the next step in the workspace.
+If you lose track, `/rite-status` prints the next command.
+
+```text
+/rite-spec add-csv-export   #  1  answer its questions; writes spec.md
+/rite-clarify               #  2  asks nothing when the spec is complete
+/rite-temper                #     optional: big or risky features only
+/rite-define                #  3  plan + vertical slices in tasks.md
+/rite-vet                   #  4  plan review; nothing builds before READY
+/rite-build                 #  5  builds slice 1, then stops
+/rite-build                 #  5  builds slice 2; repeat until every slice is done
+/rite-prove                 #  6  once, after the last slice
+/rite-polish                #  7  cleans code and touched UI
+/rite-review                #  8  checks the diff against spec and standards
+/rite-seal                  #  9  GO or NO-GO; Git untouched
+/rite-ship                  # 10  shows the exact Git plan, then waits for you to type GO
+```
+
+Every command has four equivalent forms: `/rite <verb>` and `/rite-<verb>` in
+Claude Code, omp, pi, and Devin CLI, and `$rite <verb>` and `$rite-<verb>` in
+Codex. On pi, commands run as prompt templates under `.pi/prompts`; on omp,
+as command stubs under `.omp/commands`. On both, `/skill:rite-<verb>` is
+equivalent.
+
+### Shape (steps 1 to 4): agree on what "done" means
+
+| # | Command | What it does | Leaves behind |
+| :-: | --- | --- | --- |
+| **1** | [`/rite-spec <feature>`](pack/.claude/skills/rite-spec/SKILL.md) | Inspects the request and the codebase, asks about product gaps, and writes a lossless contract with an explicit capability impact. | `spec.md` |
+| **2** | [`/rite-clarify`](pack/.claude/skills/rite-clarify/SKILL.md) | Checks the whole feature for missing decisions. Mandatory, but asks nothing when everything is clear. | `decision-coverage.md` |
+| opt. | [`/rite-temper`](pack/.claude/skills/rite-temper/SKILL.md) | Challenges scope, premise, and failure modes with a pre-mortem. Skip it for small work; Autocomplete always runs it. | `strategy.md` |
+| **3** | [`/rite-define`](pack/.claude/skills/rite-define/SKILL.md) | Turns the approved spec into architecture, traceability, and vertical task slices. | `plan.md`, `tasks.md` |
+| **4** | [`/rite-vet`](pack/.claude/skills/rite-vet/SKILL.md) | Reviews every plan before code, with review depth scaled to risk. Build cannot start until Vet passes. | `eng-review.md`, `test-plan.md` |
+
+### Build (step 5): one slice per run
+
+| # | Command | What it does | Leaves behind |
+| :-: | --- | --- | --- |
+| **5** | [`/rite-build`](pack/.claude/skills/rite-build/SKILL.md) | Implements and verifies the next slice, then stops. Run it again until every slice in `tasks.md` is built. With `.devrites/AFK`, it may chain low-risk slices under a cap. | `touched-files.md`, `evidence.md` |
+| if needed | [`/rite-plan repair`](pack/.claude/skills/rite-plan/SKILL.md) | The plan turned out wrong: reslices, reorders, or unblocks it. Run `/rite-vet` again, then keep building. | `plan.md`, `tasks.md` |
+| if needed | [`/rite-converge`](pack/.claude/skills/rite-converge/SKILL.md) | Resuming a half-built feature: compares live code with recorded intent, adds missing slices, and sends the plan back to Vet. | `convergence-assessment.md`, `tasks.md` |
+
+### Prove (steps 6 to 8): once, after the last slice
+
+| # | Command | What it does | Leaves behind |
+| :-: | --- | --- | --- |
+| **6** | [`/rite-prove`](pack/.claude/skills/rite-prove/SKILL.md) | Runs positive, discriminating tests plus build, runtime, and UI checks, then binds the evidence to the candidate digest. | `evidence.md`, `browser-evidence.md` |
+| **7** | [`/rite-polish`](pack/.claude/skills/rite-polish/SKILL.md) | Cleans up the candidate, normalizes touched UI, completes durable rollups, and refreshes affected proof. | `polish-report.md` |
+| **8** | [`/rite-review`](pack/.claude/skills/rite-review/SKILL.md) | Reviews the closed candidate against its spec and engineering standards. | `review.md` |
+
+### Ship (steps 9 and 10): you decide
+
+| # | Command | What it does | Leaves behind |
+| :-: | --- | --- | --- |
+| **9** | [`/rite-seal`](pack/.claude/skills/rite-seal/SKILL.md) | Rechecks candidate-bound evidence and writes the final `GO` or `NO-GO` without changing Git. | `seal.md` |
+| **10** | [`/rite-ship`](pack/.claude/skills/rite-ship/SKILL.md) | Runs a read-only preflight and shows the exact Git plan. After you type a fresh literal `GO`, it commits, runs any approved push, tag, or PR action, and archives the workspace. | `ship.md`, `archive/<slug>/` |
+
+<details>
+<summary><b>Other routes and utilities</b></summary>
+
+<br>
 
-`rite-quick` keeps a compact contract, focused proof, and scope review without
-creating the full feature workspace; it escalates when the work is no longer
-small, reversible, and unambiguous. `rite-spec` investigates the repository,
-asks about gaps, and writes the full feature contract under
-`.devrites/work/add-csv-export/`.
-
-### 3. Follow the next recorded step
-
-For workspace-backed routes, use `/rite-status` in Claude Code or `$rite-status`
-in Codex. Status reads the active workspace and reports the current phase, open
-questions, evidence, and next command. The quick route reports its own focused
-proof and next action.
-
-## How the lifecycle works
-
-Claude Code supports both `/rite <verb>` and `/rite-<verb>`. Codex uses the same
-forms with `$`: `$rite <verb>` and `$rite-<verb>`. omp, pi, and Devin CLI use the
-Claude slash forms (on pi they run as prompt templates under `.pi/prompts`, with
-`/skill:rite-<verb>` equivalent). The menu and direct forms run the same skill.
-
-| # | Stage | Direct command | What happens |
-| ---: | --- | --- | --- |
-| 1 | Spec | [`/rite-spec <feature>`](pack/.claude/skills/rite-spec/SKILL.md) | Inspects the request and codebase, asks about product gaps, and writes a lossless `spec.md` with an explicit capability impact. |
-| 2 | Clarify | [`/rite-clarify`](pack/.claude/skills/rite-clarify/SKILL.md) | Checks the whole feature for missing decisions before planning. It asks no questions when everything is clear. |
-| 3 | Temper | [`/rite-temper`](pack/.claude/skills/rite-temper/SKILL.md) | Challenges scope and failure modes before Define. It is optional for small work and always runs in `/rite-autocomplete`. |
-| 4 | Define | [`/rite-define`](pack/.claude/skills/rite-define/SKILL.md) | Turns the approved spec into architecture, a plan, traceability, and vertical task slices; changed provider/consumer boundaries name one shared contract and consuming tests on both sides. |
-| 5 | Vet | [`/rite-vet`](pack/.claude/skills/rite-vet/SKILL.md) | Reviews every plan before implementation. The review depth scales with the risk. |
-| 6 | Build | [`/rite-build`](pack/.claude/skills/rite-build/SKILL.md) | In HITL, implements and verifies one product slice, then stops. Run it again for each remaining slice. An explicit `.devrites/AFK` sentinel permits bounded low-risk slice chaining under its cap and pause rules. Exact Vet-ready
-executable workflow artifacts under the active feature workspace are root-materialized
-and excluded from product slice accounting. Their transaction code is proved in a
-disposable same-layout fixture before active writes, and uses normal bounded recovery
-rather than a one-shot budget. |
-| 7 | Converge | [`/rite-converge`](pack/.claude/skills/rite-converge/SKILL.md) | Runs only when recovery is needed. It compares the code with the recorded intent, adds missing slices, and sends the changed plan back to Vet. |
-| 8 | Prove | [`/rite-prove`](pack/.claude/skills/rite-prove/SKILL.md) | Runs positive, discriminating tests, build/runtime checks, and UI proof, then binds the evidence to the exact candidate digest. |
-| 9 | Polish | [`/rite-polish`](pack/.claude/skills/rite-polish/SKILL.md) | Cleans up the candidate, normalizes UI when needed, performs durable capability/design/ADR rollups, and refreshes affected proof before closing it. |
-| 10 | Review | [`/rite-review`](pack/.claude/skills/rite-review/SKILL.md) | Reviews the closed candidate against its spec and engineering standards and binds the result to its digest. |
-| 11 | Seal | [`/rite-seal`](pack/.claude/skills/rite-seal/SKILL.md) | Rechecks candidate-bound evidence and writes the final `GO` or `NO-GO` decision without changing git. |
-| 12 | Ship | [`/rite-ship`](pack/.claude/skills/rite-ship/SKILL.md) | Runs read-only preflight and discloses the exact Git plan. After a fresh literal `GO`, it stages and validates the candidate, commits and reverifies it, performs only optional approved push/tag/PR actions, and archives the workspace. |
-| n/a | Upgrade *(conditional)* | [`/rite-upgrade [slug]`](pack/.claude/skills/rite-upgrade/SKILL.md) | Audits an older active workspace against current contracts, then routes only evidence-backed defects through their normal phase owners. |
-
-Some work needs a different route:
-
-- [`/rite-quick`](pack/.claude/skills/rite-quick/SKILL.md) handles a small,
-  reversible change without creating a full feature workspace.
-- [`/rite-autocomplete`](pack/.claude/skills/rite-autocomplete/SKILL.md) runs
-  the reversible lifecycle unattended. With `--ship`, it continues through
-  Ship preflight, discloses the exact Git plan, and waits for a fresh literal
-  `GO` plus native approval; without that flag, it stops at Seal GO. A failed
-  consumptive proof action never retries blindly. Retained evidence drives
-  offline repair and re-vetting. When retained evidence is ambiguous,
-  Autocomplete first designs a vetted boundary-discriminating diagnostic; only
-  the next real acquisition attempt needs a new GO. After an upgrade introduces
-  a supported workflow-artifact writer, Autocomplete reopens a stale
-  missing-writer stop once instead of preserving the obsolete recovery count.
-  The first real root-materializer failure then counts as attempt one under
-  normal fingerprint recovery — it is not terminal by itself.
-  Likewise, an internal `NEEDS_REPLAN` result stays inside Autocomplete: it runs
-  the next Plan repair and narrow Vet without returning a command to the user.
-- [`/rite-upgrade [slug]`](pack/.claude/skills/rite-upgrade/SKILL.md) is a
-  compatibility route for an older active workspace that cannot resume. Age or
-  cursor form alone never triggers repair; it is not a lifecycle phase.
-- [`/rite`](pack/.claude/skills/rite/SKILL.md) shows the command menu.
-
-Run `devrites-engine update` from an installed project to acquire the latest
-stable release and update both the engine and pack. `npx devrites@latest update`
-and the verified release `install.sh` remain equivalent adapter routes. If an
-older engine instead reports `missing codex/hooks.json` or asks for
-`--source-dir`, use the npm or verified shell route once to cross to a release
-with the self-contained updater.
-`/rite-upgrade` is the separate native, preservation-first route for reconciling
-an unfinished workspace. It proves a current-contract defect before routing
-Clarify, Plan repair, Converge, Vet, Prove, Polish, Review, or Seal; it never
-migrates cursor format or invents historical proof. `devrites-engine migrate`
-owns deterministic v5 schema normalization; see the [CLI contract](docs/cli.md)
-and [ADR-0029](docs/adr/0029-v5-workspace-schema-and-native-migration.md).
-
-The [command map](docs/command-map.md) covers every command, trigger, input, and
-output. The [worked examples](docs/usage.md) show normal features, plan drift,
-UI work, backend work, and mid-flight handoffs.
+| Command | Use it to… |
+| --- | --- |
+| [`/rite`](pack/.claude/skills/rite/SKILL.md) | Show the command menu, or route a verb. |
+| [`/rite-quick`](pack/.claude/skills/rite-quick/SKILL.md) | Ship a small, reversible change with a compact contract, focused proof, and scope review. Escalates to `/rite-spec` when the work stops being small. |
+| [`/rite-autocomplete`](pack/.claude/skills/rite-autocomplete/SKILL.md) | Run the reversible lifecycle unattended and stop at Seal `GO`. With `--ship`, continue through Ship preflight and wait for your literal `GO`. |
+| [`/rite-adopt`](pack/.claude/skills/rite-adopt/SKILL.md) | Reverse-engineer current behavior of an existing codebase into a baseline workspace. |
+| [`/rite-upgrade [slug]`](pack/.claude/skills/rite-upgrade/SKILL.md) | Reconcile an older active workspace with current contracts. Routes only evidence-backed defects to their phase owners. |
+| [`/rite-status`](pack/.claude/skills/rite-status/SKILL.md) | Report phase, active slice, next action, evidence, open questions, and risks. Read-only. |
+| [`/rite-resolve <qid> "<answer>"`](pack/.claude/skills/rite-resolve/SKILL.md) | Answer, drop, or batch-resolve open questions. |
+| [`/rite-handoff`](pack/.claude/skills/rite-handoff/SKILL.md) | Sync chat-only context into `.devrites/` and write a fresh-agent handoff. |
+| [`/rite-frame`](pack/.claude/skills/rite-frame/SKILL.md) | Frame an underspecified ask before coding, then audit the diff. |
+| [`/rite-pressure-test`](pack/.claude/skills/rite-pressure-test/SKILL.md) | Explore three to five radically different approaches to a rough idea before Spec. |
+| [`/rite-prototype`](pack/.claude/skills/rite-prototype/SKILL.md) | Build a throwaway prototype to answer one logic or UI question. |
+| [`/rite-pov`](pack/.claude/skills/rite-pov/SKILL.md) | Get a project-grounded verdict on a library, platform, CVE, or pattern. |
+| [`/rite-zoom-out`](pack/.claude/skills/rite-zoom-out/SKILL.md) | Map unfamiliar code: modules, callers, callees, and relevant decisions. |
+| [`/rite-explain`](pack/.claude/skills/rite-explain/SKILL.md) | Learn one concept, diff, or recent change, with an optional check-in. |
+| [`/rite-dogfood`](pack/.claude/skills/rite-dogfood/SKILL.md) | Run explicit browser QA for the active feature or branch. |
+| [`/rite-pr-feedback`](pack/.claude/skills/rite-pr-feedback/SKILL.md) | Resolve GitHub PR review feedback. |
+| [`/rite-watch-pr`](pack/.claude/skills/rite-watch-pr/SKILL.md) | Watch one PR and its CI state without mutating anything. |
+| [`/rite-learn`](pack/.claude/skills/rite-learn/SKILL.md) | Turn recurring cross-feature evidence into durable project guidance. |
+| [`/rite-customize`](pack/.claude/skills/rite-customize/SKILL.md) | Customize a project instruction, skill, agent, plugin, or legacy import. |
+| [`/rite-doctor`](pack/.claude/skills/rite-doctor/SKILL.md) | Check the DevRites install, pack, or host configuration. |
+| [`/overhaul`](pack/.claude/skills/overhaul/SKILL.md) | Run an approval-gated overhaul of a project, PR, or branch. Works without a DevRites workspace; explicit invocation only. |
+
+</details>
+
+The [command map](docs/command-map.md) covers every command, trigger, input,
+and output. The [worked examples](docs/usage.md) cover normal features, plan
+drift, UI work, backend work, and mid-flight handoffs.
 
 ## What DevRites records
 
 Each feature gets a directory under `.devrites/work/<slug>/`. Shipped
-workspaces move intact to `.devrites/archive/<slug>/` so future work can inspect
-the original decisions and proof.
+workspaces move intact to `.devrites/archive/<slug>/`, so future work can
+inspect the original decisions and proof.
 
 ```text
 .devrites/
-  ACTIVE                 # active feature slug
-  AFK                    # optional unattended-mode configuration
-  CHECKPOINT             # reserved path; not a commit gate
-  principles.md          # project rules that gate the workflow
-  specs/                 # living structured capabilities
-  work/<slug>/
-    brief.md
-    spec.md
-    decision-coverage.md
-    architecture.md
-    plan.md
-    tasks.md
-    eng-review.md
-    test-plan.md
-    state.md
-    decisions.md
-    questions.md
-    traceability.md
-    evidence.md
-    touched-files.md       # strict project-candidate manifest
-    review.md
-    seal.md
-    ship.md
-  archive/<slug>/
+├── ACTIVE                  active feature slug
+├── AFK                     optional unattended-mode configuration
+├── principles.md           project rules that gate the workflow
+├── specs/                  living structured capabilities
+├── work/<slug>/
+│   ├── brief.md  spec.md  decision-coverage.md
+│   ├── architecture.md  plan.md  tasks.md  eng-review.md  test-plan.md
+│   ├── state.md  decisions.md  questions.md  traceability.md
+│   ├── evidence.md  touched-files.md      strict project-candidate manifest
+│   └── review.md  seal.md  ship.md
+└── archive/<slug>/
 ```
 
-Some phases add focused artifacts such as `strategy.md`, `design-brief.md`,
+`.devrites/CHECKPOINT` is a reserved path, not a commit gate. Some phases add
+focused artifacts such as `strategy.md`, `design-brief.md`,
 `browser-evidence.md`, `polish-report.md`, `drift.md`, or `handoff.md`. See the
 [workspace contract](docs/engine/workspace-schema.md) for the full state model
 and [candidate integrity](docs/candidate-integrity.md) for the Build-to-Ship
@@ -189,54 +206,42 @@ content binding.
 - **Settle before code.** Spec and Clarify settle the behavior contract. Define
   and Vet settle the implementation path before Build starts. The active skill
   and exact native reviewers judge `CLEAR`, `READY`, traceability, and test
-  quality from the complete artifacts; the engine checks phase-relative
-  structure and, after Vet, the exact stable Build-input binding.
-- **Bound every Build dispatch.** In HITL, `/rite-build` implements one vertical
-  slice and records its proof before returning control. With an explicit
-  `.devrites/AFK` sentinel it may chain low-risk slices only within the
-  configured cap and pause rules. Before every writer dispatch, the root puts
-  the exact project-relative paths in its task; after return, it rejects any
+  quality; the engine checks phase-relative structure and, after Vet, the exact
+  Build-input binding.
+- **Bound every Build dispatch.** Before each writer dispatch, the root names
+  the exact project-relative paths in the task. After return, it rejects any
   extra path in `git diff --name-only`, reviews test integrity, and runs
   repository proof.
-- **Classify drift before routing.** The Spec Drift Guard records the mismatch
-  in `drift.md`. Build handles objective implementation and tool failures with
-  bounded recovery; it uses
-  [`/rite-plan repair`](pack/.claude/skills/rite-plan/SKILL.md) only when the
-  durable plan is wrong, and asks you only for a real product or risk decision.
-- **Prove claims.** Behavioral proof must be positive and discriminating:
-  skipped, zero-test, assertion-free, tautological, unexecuted, or exit-only
-  results do not prove behavior, and static gates prove only their static
-  criterion. A screenshot path by itself is not proof.
+- **Classify drift before routing.** The Spec Drift Guard records a mismatch in
+  `drift.md`. Build handles objective failures with bounded recovery, uses
+  `/rite-plan repair` only when the durable plan is wrong, and asks you only
+  for a real product or risk decision.
+- **Prove claims.** Skipped, zero-test, assertion-free, tautological,
+  unexecuted, or exit-only results do not prove behavior. Static gates prove
+  only their static criterion. A screenshot path by itself is not proof.
 - **Separate the decision from the action.** Seal makes the release decision.
-  Ship performs the final git actions only after the seal passes and you type
-  `GO`.
+  Ship performs Git actions only after the seal passes and you type `GO`.
 - **Stay inside the feature.** Review, security, simplification, and polish do
   not expand into unrelated project cleanup.
 
 Validated project principles and nearest-scope repository instructions govern
-product and technical choices inside the controlling request. They do not grant
-permission or waive DevRites safety, source-writing, or evidence gates; current
-source/tests describe reality rather than authority. A feature can record a
-deliberate scoped exception instead of silently ignoring a project principle.
-The canonical order is
-[`core.md` § Precedence](pack/.claude/skills/devrites-lib/reference/standards/core.md#precedence).
-
-## HITL and AFK modes
-
-### HITL is the default
-
-When DevRites needs a decision, it presents ranked options, records the chosen
-answer in the workspace, and continues. If the current turn must stop, the
-question remains in `questions.md`; answer it later with
-[`/rite-resolve <qid> "<answer>"`](pack/.claude/skills/rite-resolve/SKILL.md).
-Codex uses the equivalent `$rite-resolve` form.
+product and technical choices. They do not grant permission or waive DevRites
+safety, source-writing, or evidence gates. A feature can record a deliberate,
+scoped exception instead of silently ignoring a principle. The canonical order
+is in [`core.md` § Precedence](pack/.claude/skills/devrites-lib/reference/standards/core.md#precedence).
 
-### AFK runs the safe part unattended
+## HITL and AFK
 
-Create `.devrites/AFK` to let permitted gates select their recommended option
-and continue:
+| | **HITL** (default) | **AFK** (opt-in) |
+| --- | --- | --- |
+| Turn on | Nothing to do. | Create `.devrites/AFK`. Delete it to return to HITL. |
+| Decisions | Ranked options; your answer is recorded in the workspace. | Permitted gates pick the recommended option and continue. |
+| Build | One vertical slice per run. | Chains low-risk slices within `max_slices` and pause rules. |
+| Unanswered question | Stays in `questions.md`; answer later with `/rite-resolve`. | Pauses for product, scope, policy, irreversible risk, or human-only access. |
+| Git | Ship always waits for a fresh literal `GO`. | Same. Local WIP checkpoint commits stay local unless Ship's disclosed plan includes an approved remote action. |
 
 ```yaml
+# .devrites/AFK
 max_slices: 10
 max_agents: 32
 max_minutes: 120
@@ -245,55 +250,39 @@ allow_gates: [advisory]
 ```
 
 The workflow treats this file as configuration and never rewrites it.
-`max_slices` seeds the remaining budget in the active feature's `state.md`; the
-root charges that state exactly once after each green built slice and stops
-before another dispatch at zero. Unattended slice work additionally requires a
-valid `max_agents`, `max_minutes`, and `max_review_queue`;
-sentinels that miss or malform these fail closed. Leftover `expires_at` is
-ignored and never rewritten. Delete `.devrites/AFK` to
-return to HITL.
-
-AFK still pauses for product, scope, or policy choices, irreversible risk,
-and access or actions available only to a human. `/rite-autocomplete` is the
-exception that auto-resolves blocking questions already naming a ranked
-recommended option; escalating, irreversible-risk, access, and blocking with
-no recommended option still pause. Agents use bounded recovery
-for red tests, type or lint errors, runtime failures, and missing technical
-coverage. If that recovery budget runs out, they record a technical blocker
-instead of asking a question. The full pause and gate contract is in
-[`afk-hitl.md`](pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md).
+`max_slices` seeds the remaining budget in the feature's `state.md`; the root
+charges it once per green slice and stops at zero. Unattended slice work also
+requires valid `max_agents`, `max_minutes`, and `max_review_queue`; a missing
+or malformed value fails closed.
 
-## Install, update, and remove
+`/rite-autocomplete` also auto-resolves blocking questions that already name a
+ranked recommended option. Escalating, irreversible-risk, access, and
+no-recommendation questions still pause. When bounded recovery runs out,
+agents record a technical blocker instead of asking you. The full contract is
+in [`afk-hitl.md`](pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md).
 
-### npm
+## Install, update, and remove
 
 ```bash
-# Install in the current project
-npx devrites@latest
-
-# Install elsewhere or preview the changes
+npx devrites@latest                      # install in the current project
 npx devrites@latest --target /path/to/project
-npx devrites@latest --dry-run
+npx devrites@latest --dry-run            # preview file operations
 
-# Update or remove an existing installation
-npx devrites@latest update
+npx devrites@latest update               # update engine and pack
 npx devrites@latest update --check
+devrites-engine update                   # same, from an installed project
+
 npx devrites@latest uninstall
 npx devrites@latest uninstall --keep-binary
-
-# The installed engine can update itself and the project pack directly
-devrites-engine update
-devrites-engine update --check
 ```
 
-Release binaries and installers ship with SHA-256 sidecars and build-provenance
-attestations. Verify a download with `shasum -a 256 -c <file>.sha256` or
-`gh attestation verify <file> -R ViktorsBaikers/DevRites --signer-workflow ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`
-(pinning the signer workflow matters: valid provenance proves where a build
-ran, not that the publishing step was the intended one); see
-[docs/release.md](docs/release.md).
+Run `npx devrites@latest --help` for common flags and
+`npx devrites@latest <command> --help` for command-specific flags.
 
-Useful install flags:
+<details>
+<summary><b>Install flags</b></summary>
+
+<br>
 
 | Flag | Effect |
 | --- | --- |
@@ -301,7 +290,7 @@ Useful install flags:
 | `--dry-run` | Show planned file operations without changing anything. |
 | `--force` | Replace or remove foreign or customized managed files. The installer still rejects symlinks and path escapes. |
 | `--no-codex` | Skip `.agents`, `.codex`, and the Codex `AGENTS.md` block. |
-| `--no-omp` | Skip `.omp` skills and agents. |
+| `--no-omp` | Skip `.omp` skills, agents, and command stubs. |
 | `--no-pi` | Skip `.pi` skills, agents, prompt commands, and the pi `AGENTS.md` block. |
 | `--no-devin` | Skip `.devin` skills, agents, and the Devin `AGENTS.md` block. |
 | `--no-agents` | Skip hook-free native specialist profiles. |
@@ -309,13 +298,15 @@ Useful install flags:
 | `--no-binary` | Do not keep the shared `devrites-engine` binary in a user or system bin directory. |
 | `--short-aliases=all` | Add `/define`, `/build`, `/prove`, and `/seal` aliases. |
 
-Run `npx devrites@latest --help` for common flags and
-`npx devrites@latest <command> --help` for command-specific flags.
+</details>
+
+<details>
+<summary><b>Install without Node.js (verified Bash bootstrap)</b></summary>
 
-### Bash bootstrap
+<br>
 
-If Node.js is not available, download the release-owned installer and its
-checksum before executing it. It needs `curl`, `gzip`, and `tar`.
+Download the release-owned installer and its checksum before executing it. It
+needs `curl`, `gzip`, and `tar`.
 
 ```bash
 bootstrap_dir="$(mktemp -d)"
@@ -360,139 +351,139 @@ bootstrap_dir="$(mktemp -d)"
 To pin a named release, replace `latest/download` with
 `download/v<version>` and run the chosen operation with
 `DEVRITES_REF=v<version>`. Existing local or extracted `install.sh`,
-`update.sh`, and `uninstall.sh` invocations remain compatible. The exact-release
-acquisition guarantee begins with the verified release `install.sh`; mutable
-default-branch scripts are not an installation boundary.
+`update.sh`, and `uninstall.sh` invocations remain compatible. The
+exact-release acquisition guarantee begins with the verified release
+`install.sh`; mutable default-branch scripts are not an installation boundary.
+
+</details>
+
+<details>
+<summary><b>How install, update, and uninstall protect your files</b></summary>
+
+<br>
 
 The installer records every managed project file and its SHA-256 in
 `.claude/devrites.manifest`. Before an update or uninstall changes anything, it
-checks every managed path. It preserves customized files and tells the user to
-retry with `--force` before making any changes; legacy manifests without hashes
-also require `--force`.
+checks every managed path. It preserves customized files and tells you to retry
+with `--force`; legacy manifests without hashes also require `--force`.
 `--force --dry-run` lists the exact destructive actions. Marker-merged files
 keep user content outside the DevRites block, and `.devrites/` runtime state
-remains in place. The installer refuses symlinks, junctions, and paths that
+stays in place. The installer refuses symlinks, junctions, and paths that
 escape the target.
 
 The optional shared `devrites-engine` binary is the only artifact installed
-outside the project. Before replacement, the release binary at its staged path
-must report the requested version. After installation, the binary at its final
-path must report that version in a new process. The installer keeps a backup in
-the same directory until the second check passes. On failure, it restores the
-previous binary or removes a bad first install.
-
-Direct `devrites-engine update` resolves the latest stable release, acquires its
-bundle and platform binary, and hands local paths to the downloaded engine. The
-candidate engine therefore validates its own payload before replacing the
-installed pack and binary. npm and Bash may supply the same local candidate
-paths directly. `update --check` resolves and compares the latest version
-without downloading release assets.
-
-Network acquisition resolves an exact SemVer release, permits HTTPS at every
-redirect hop, requires an exact-filename SHA-256 sidecar, and uses private
-temporary directories plus in-stream bounded downloads. Archive metadata and
-paths pass bounded streaming preflight before extraction. There is no unchecked
-raw, source-archive, tag, or default-branch fallback. See
-[`SECURITY.md`](SECURITY.md) for the representative bounds.
-
-## Host integration
-
-Claude Code receives skills under `.claude/skills/`, agents under
-`.claude/agents/`, and native root permissions merged into
-`.claude/settings.json`. Only Claude's slice-wright profile is writable.
-Existing settings remain in place.
-
-Codex receives the same skills under `.agents/skills/`, custom agents under
-`.codex/agents/`, native permissions under `.codex/config.toml`, and a marked
-guidance block in `AGENTS.md`. All Codex specialists are hook-free and
-only `devrites-slice-wright` is writable; every other specialist is read-only.
-Existing user content remains in place. Codex users invoke skills with `$rite`,
-`$rite-spec`, or `/skills`.
-
-Devin CLI receives the same skills under `.devin/skills/`, custom subagent
-profiles under `.devin/agents/`, and a marked guidance block in `AGENTS.md`.
-Profiles use `allowed-tools` with Devin tool names: only
-`devrites-slice-wright` keeps `edit`, `write`, and `exec`; every other
-specialist is read-only. Dispatch goes through `run_subagent` with the exact
-`devrites-<role>` profile; a missing profile stops for HITL instead of
-substituting `subagent_general`. Profiles load when a session starts, so reopen
-the project after installing.
+outside the project. Before replacement, the staged release binary must report
+the requested version; after installation, the binary at its final path must
+report it again in a new process. The installer keeps a backup until the
+second check passes and restores it on failure.
+
+`devrites-engine update` resolves the latest stable release, acquires its
+bundle and platform binary, and hands local paths to the downloaded engine, so
+the candidate engine validates its own payload before replacing the installed
+pack and binary. `update --check` compares versions without downloading
+release assets. If an older engine reports `missing codex/hooks.json` or asks
+for `--source-dir`, use the npm or verified shell route once to reach a
+release with the self-contained updater.
+
+`/rite-upgrade` is the separate, preservation-first route for reconciling an
+unfinished workspace; it never migrates cursor format or invents historical
+proof. `devrites-engine migrate` owns deterministic v5 schema normalization.
+See the [CLI contract](docs/cli.md) and
+[ADR-0029](docs/adr/0029-v5-workspace-schema-and-native-migration.md).
+
+Release binaries and installers ship with SHA-256 sidecars and
+build-provenance attestations. Verify a download with
+`shasum -a 256 -c <file>.sha256` or
+`gh attestation verify <file> -R ViktorsBaikers/DevRites --signer-workflow ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`.
+Pin the signer workflow, because valid provenance shows where a build ran
+but does not show that the intended publishing step produced it. See
+[docs/release.md](docs/release.md).
+
+</details>
+
+## Hosts
+
+| Host | Skills | Agents | Also installs | Invoke |
+| --- | --- | --- | --- | --- |
+| **Claude Code** | `.claude/skills/` | `.claude/agents/` | Native root permissions merged into `.claude/settings.json` | `/rite-spec` |
+| **Codex** | `.agents/skills/` | `.codex/agents/` | Permissions in `.codex/config.toml`, marked block in `AGENTS.md` | `$rite-spec` or `/skills` |
+| **omp** | `.omp/skills/` | `.omp/agents/` | Command stubs in `.omp/commands/` | `/rite-spec` or `/skill:rite-spec` |
+| **pi** | `.pi/skills/` | `.pi/agents/` | Prompt commands in `.pi/prompts/`, marked block in `AGENTS.md` | `/rite-spec` or `/skill:rite-spec` |
+| **Devin CLI** | `.devin/skills/` | `.devin/agents/` | Marked block in `AGENTS.md` | `/rite-spec` |
+
+On every host, `devrites-slice-wright` is the only writable specialist, and
+every other specialist is read-only and hook-free. Existing
+settings and user content stay in place. On Devin CLI, dispatch goes through
+`run_subagent` with the exact `devrites-<role>` profile, and a missing profile
+stops for HITL instead of substituting `subagent_general`. Profiles load when a
+session starts, so reopen the project after installing.
 
 DevRites is installed through npm or the Bash bootstrap. It is not distributed
 through Claude Code or Codex plugin stores.
 
 ## Skills and agents
 
-The pack ships 45 skills: 34 public and 11 internal. The public surface contains
-the `rite` menu, 32 `rite-*` workflows and utilities, and the standalone,
-explicit-only `/overhaul` (approval-gated project, PR or branch audit with verified
-repairs; it runs without a DevRites workspace). Ten `devrites-*`
-specialists load when a matching task needs them; `devrites-lib` carries the
-shared contracts and engineering standards.
+The pack ships 45 skills: 34 public and 11 internal. The public surface
+contains the `rite` menu, 32 `rite-*` workflows and utilities, and the
+standalone, explicit-only `/overhaul`. Ten `devrites-*` specialists load when a
+matching task needs them; `devrites-lib` carries the shared contracts and
+engineering standards.
 
-Seventeen fresh-context agent profiles ship with the pack. Claude has sixteen
-read-only roles plus the sole source/test writer role,
-`devrites-slice-wright`; Codex, omp, pi, and Devin generate the same
-one-writer/sixteen-reader split.
+Seventeen fresh-context agent profiles ship with the pack: sixteen read-only
+roles plus `devrites-slice-wright`, the sole source and test writer. Codex,
+omp, pi, and Devin generate the same one-writer, sixteen-reader split.
+`/overhaul` adds eight `overhaul-*` agents that only it dispatches; they keep
+every tool ([ADR-0031](docs/adr/0031-overhaul-agents-keep-every-tool.md)).
 
-The authoritative [skills catalogue](docs/skills.md) lists every skill and
-agent. The [flow diagrams](docs/flow.md) show routing, reviewer fan-out, and
-namespace boundaries.
+The [skills catalogue](docs/skills.md) lists every skill and agent. The
+[flow diagrams](docs/flow.md) show routing, reviewer fan-out, and namespace
+boundaries.
 
 ## Engineering standards and UI work
 
-The stack-agnostic standards live under
-`.claude/skills/devrites-lib/reference/standards/`. Workspace-operating
-lifecycle skills load the small core first, while compact utilities keep a
-narrower local contract; each then loads only the standards it needs. Nearest
-project instructions override generic advice, and ratified
-`.devrites/principles.md` are gating invariants. The
+Stack-agnostic standards live under
+`.claude/skills/devrites-lib/reference/standards/`. Lifecycle skills load the
+small core first, then only the standards they need. Nearest project
+instructions override generic advice, and ratified `.devrites/principles.md`
+are gating invariants. The
 [standards index](pack/.claude/skills/devrites-lib/reference/standards/README.md)
 maps each rule file to the phases that use it.
 
 For UI work, Spec records the visual direction and required states in
-`design-brief.md`. Build follows the project's existing design system, while
+`design-brief.md`, Build follows the project's existing design system, and
 Prove collects runtime and browser evidence. The guidance checks WCAG 2.2 AA
-and, when performance is measurable, targets LCP at or below 2.5 seconds, INP
-at or below 200 milliseconds, and CLS at or below 0.1. Full-stack work starts
-with the API and data contract, then builds a vertical slice through the UI.
+and, when performance is measurable, targets LCP ≤ 2.5 s, INP ≤ 200 ms, and
+CLS ≤ 0.1. Full-stack work starts with the API and data contract, then builds
+a vertical slice through the UI.
 
-DevRites works without extra tools. If available, codegraph or graphify can
-answer structural questions, and
+DevRites works without extra tools. When available, codegraph or graphify can
+answer structural questions,
 [Playwright MCP](https://github.com/microsoft/playwright-mcp) can collect
-browser evidence. Chrome DevTools MCP can add Lighthouse and performance
+browser evidence, and Chrome DevTools MCP can add Lighthouse and performance
 traces. DevRites detects these tools but does not install them.
 
 ## Security model
 
-Installed host artifacts stay in the project. The npm shim can use an explicitly
-configured engine, download the exact release binary with its mandatory checksum,
-build a temporary engine from package-local Go source, or use `devrites-engine`
-on `PATH`. Remote fetches are HTTPS-only and bounded. Use
-`--no-binary` or `DEVRITES_NO_BINARY=1` to avoid keeping a shared binary outside
-the project. npm, Bash, and direct engine update all require checksummed release
-assets. Engine network access is isolated to bounded latest-release acquisition;
-the downloaded engine performs the local manifest-owned update. Install, update,
-and uninstall do not inspect target-project Git. Retained safety operations such
-as `secret-scan --staged` intentionally read the exact Git index and staged blobs
-they validate.
-
-Production Git subprocesses remove repository/config/object/ref/pathspec
-retargeting `GIT_*` variables while preserving unrelated Git environment. Seal
-binds proof, review, and verdict to the strict project candidate rather than
-modification times. See [candidate integrity](docs/candidate-integrity.md) and
-[ADR-0026](docs/adr/0026-content-bound-proof-and-bounded-inputs.md).
-
-Skills read workspace Markdown directly. Only retained atomic resolution/close
-and safety mutations go through the engine; root-owned policy edits follow the
-explicit native checklists. The installer never writes
-`defaultMode: bypassPermissions`. Skills use networked research only through
-host tools you invoke or configure.
+- Installed host artifacts stay in the project. Use `--no-binary` or
+  `DEVRITES_NO_BINARY=1` to avoid keeping a shared binary outside it.
+- npm, Bash, and `devrites-engine update` all require checksummed release
+  assets. Remote fetches use HTTPS at every redirect hop, are bounded in size,
+  and never fall back to an unchecked raw file, source archive, tag, or default
+  branch.
+- Install, update, and uninstall do not inspect target-project Git. Retained
+  safety operations such as `secret-scan --staged` read only the exact index
+  and staged blobs they validate.
+- Production Git calls strip `GIT_*` variables that could retarget them. Seal
+  binds proof, review, and verdict to the strict project candidate rather than
+  to modification times
+  ([ADR-0026](docs/adr/0026-content-bound-proof-and-bounded-inputs.md)).
+- The installer never writes `defaultMode: bypassPermissions`. Skills use
+  networked research only through host tools you invoke or configure.
 
 Read [`SECURITY.md`](SECURITY.md) for the threat model, managed deployment
 guidance, and private reporting instructions.
 
-## Repository layout
+## Contributing
 
 ```text
 bin/               npm CLI shim
@@ -505,8 +496,6 @@ docs/              architecture, usage, command, and contributor guides
 evals/             routing and behavioral evaluation fixtures
 ```
 
-For local development:
-
 ```bash
 npm install
 npm run validate
@@ -516,10 +505,15 @@ npm test
 
 Canonical pack changes belong in `pack/.claude/`. Rebuild host payloads with
 `bash scripts/build-host-artifacts.sh` instead of editing `pack/generated/`.
-See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow and review
-requirements.
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow and
+review requirements, and the [code of conduct](CODE_OF_CONDUCT.md) before
+opening a change. Maintainer ownership is in [`CODEOWNERS`](CODEOWNERS);
+third-party notices are in [`NOTICE.md`](NOTICE.md).
+
+<details>
+<summary><b>All documentation</b></summary>
 
-## Documentation
+<br>
 
 - [Quick reference](docs/quick-reference.md)
 - [Worked examples](docs/usage.md)
@@ -536,14 +530,15 @@ requirements.
 - [Changelog](CHANGELOG.md)
 - [Releases](https://github.com/ViktorsBaikers/DevRites/releases)
 
-## Community and license
+</details>
 
-Please read the [contribution guide](CONTRIBUTING.md) and
-[code of conduct](CODE_OF_CONDUCT.md) before opening a change. Maintainer
-ownership is documented in [`CODEOWNERS`](CODEOWNERS), and third-party notices
-are in [`NOTICE.md`](NOTICE.md).
+## License
 
 DevRites is source-available software for personal use with Claude Code and
 Codex. Distribution, modified distribution, fork mirrors, and commercial or
 organizational use require approval. Read [`LICENSE`](LICENSE) for the full
 terms.
+
+<p align="center">
+  <sub>Spec → proof → people → better software.</sub>
+</p>