devrites 3.0.7 → 3.2.0

package/docs/cli.md

@@ -7,21 +7,27 @@ deterministic gates from the project root.
 
 ## The `devrites-engine` CLI
 
-Install DevRites normally, then run the engine from the project root:
-
-The examples below are a curated working set. `devrites-engine help` is the
-exhaustive current command and hook inventory.
+Install DevRites normally, then run the engine from the project root. These
+examples cover the common commands; `devrites-engine help` lists every current
+command and hook.
 
 ```bash
 devrites-engine preamble                 # workspace digest for the active feature
 devrites-engine snapshot [slug]          # machine-readable workspace/status snapshot
-devrites-engine build-readiness [slug]   # build-readiness gate      (exit 0 ready)
+devrites-engine build-readiness [slug]   # semantic clarify + vet gate (exit 0 ready)
+devrites-engine readiness-digest coverage|engineering [slug] # canonical input digest
+devrites-engine clarify-return enter|restore [slug] # durable later-phase clarify cursor
+devrites-engine recovery route <class>             # typed owner/action; JSON recovery-route/v1
+devrites-engine recovery check|record|clear ...    # durable three-failure budget; record/clear accept --class
+devrites-engine reconcile snapshot|check|close [slug] # retained writer baseline
+devrites-engine test-integrity [slug]    # reject weakened tests against that baseline
+devrites-engine package-existence [slug] # verify new imports are declared
 devrites-engine evidence-fresh [slug]    # proof freshness gate      (exit 0 fresh · 3 stale)
 devrites-engine check-acceptance <dir>   # acceptance gate           (exit 0 proven · 1 gap)
 devrites-engine ledger sync <dir>        # fold a feature's spec deltas into the living capability ledger
 devrites-engine ledger list|show <cap>   # read the ledger: what the system already does
 devrites-engine context show --json      # report root, active workspace, and host command forms
-devrites-engine timeline log|list        # append/list session events, decisions, and state moves
+devrites-engine timeline log|list|report|purge # local typed trace, bounded report, exact retention
 devrites-engine health run               # run known project checks + record a code-health dashboard
 devrites-engine health record|list       # append/list manual or dashboard health history
 devrites-engine review-fingerprints [slug] # stable IDs for review findings; --write saves JSONL
@@ -41,20 +47,49 @@ directly rather than wrapping human text. Snapshot consumers should read
 `nextCommands.claude` or `nextCommands.codex` for the current host instead of
 hardcoding a `/rite-*` or `$rite-*` command form. `context show --json` and
 `reviewer-stats report --json` are also direct structured reports rather than
-envelopes.
+envelopes. The snapshot wire identifier is separate from the workspace-map
+frontmatter `schemaVersion: 2`: schema v2 is additive, reads legacy layouts and
+aliases, and rejects only declarations newer than the engine supports.
 
 The npm `devrites` shim remains the installer/updater/uninstaller entry point and
 proxies these engine subcommands when `devrites-engine` is installed. Install and
 update DevRites through `npx devrites ...`; DevRites is not distributed through
 Claude or Codex plugin stores.
 
-The exit code is the gate. A non-zero `build-readiness`,
+Callers use the exit code as the gate result. `build-readiness` routes
+objective gaps to their owner:
+
+<!-- authority:readiness-reasons:start -->
+| exit | reason | condition | remediation |
+| --- | --- | --- | --- |
+| `0` | `ready` | Ready to build | *(none)* |
+| `2` | `plan-unapproved` | Plan is not approved | `/rite-define` |
+| `3` | `awaiting-human` | A human-owned question is open | `/rite-resolve` |
+| `4` | `plan-blocked` | Plan is blocked and needs repair | `/rite-plan` |
+| `5` | `workspace-missing` | Workspace or state.md is missing | `/rite-spec` |
+| `6` | `coverage-not-clear` | Decision coverage is not CLEAR and fresh | `/rite-clarify` |
+| `7` | `engineering-not-ready` | Plan is not vetted or implementation readiness is not READY | `/rite-vet` |
+| `8` | `upgrade-required` | Planning artifacts use an older or unknown DevRites contract | `/rite-upgrade` |
+<!-- authority:readiness-reasons:end -->
+
+A non-zero `build-readiness`,
 `evidence-fresh`, or `check-acceptance` result is a hard stop that can be used
 in an agent loop, a local script, or pre-merge CI.
 
+`build-readiness` does not trust `CLEAR` or `READY` text alone. It validates the
+required sections, tables, ownership and test mappings, requires the current
+`devrites.readiness-artifacts.v2` declaration, and compares each artifact's
+SHA-256 field with the digest of its canonical inputs.
+
+`devrites-engine update` refreshes the installed binary and pack.
+`devrites-engine migrate` may upgrade a workspace declaration to structural
+schema v2, but it never creates or blesses clarification, vet, or proof
+evidence. `/rite-upgrade [slug]` is the separate semantic reconciliation route
+for an active unfinished workspace.
+
 ## Why this exists
 
-DevRites workspaces and standards are tool-agnostic data. The CLI lets agent
-loops, local scripts, CI, and humans use that data without rebuilding the
-workflow. CLI verdicts and `rite-*` verdicts agree because both run the same
-engine gates.
+The CLI exposes DevRites workspace data and standards to agent loops, local
+scripts, CI, and human operators without requiring each caller to reimplement
+the workflow. CLI and `rite-*` verdicts match because both use the same engine
+gates.

package/docs/command-map.md

@@ -1,7 +1,7 @@
 # DevRites command map
 
-Reference for every shipped skill and agent: what triggers it, what it reads,
-what it writes, and how the pieces interact.
+This page lists every shipped skill and agent, including its triggers, inputs,
+outputs, and interactions.
 
 DevRites ships through npm (`npx devrites ...`). Claude Code and Codex support
 comes from generated host artifacts copied by the npm installer; DevRites is not
@@ -13,15 +13,16 @@ distributed as a Claude or Codex plugin.
 
 ## Naming convention
 
-`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
-`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`,
-`rite-pressure-test`, `rite-autocomplete`, `rite-explain`, `rite-pov`, `rite-dogfood`,
-`rite-pr-feedback`). `devrites-*` specialists are model-invoked; `devrites-lib` is the
-explicit non-workflow library exception.
+The `devrites-` prefix avoids collisions with bundled Claude Code skill names
+such as `prototype`, `handoff`, `triage`, and `diagnose`. The prefix does not
+mean that a skill is internal; each `SKILL.md` uses `user-invocable:` to set
+visibility. 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`, `rite-pressure-test`,
+`rite-autocomplete`, `rite-explain`, `rite-pov`, `rite-dogfood`, and
+`rite-pr-feedback`, plus the semantic workspace maintenance command
+`rite-upgrade`. The host may invoke `devrites-*` specialists through the model.
+`devrites-lib` is the non-workflow library exception.
 
 ## Surface lifecycle
 
@@ -35,13 +36,13 @@ Only promoted surfaces are shipped by the npm package.
 
 ## Engine command ownership
 
-Engine commands are not all phase steps. Keep each new command in one of these
-lanes so it is either executed automatically or intentionally operator-owned:
+Not every engine command is a phase step. Assign each new command to one of
+these lanes so its owner is clear:
 
 | Lane | Commands | Owner |
 |---|---|---|
-| Workflow gates | `preamble`, `build-readiness`, `spec-skeleton`, `spec-validate`, `check-acceptance`, `evidence-fresh`, `coverage`, `doubt-coverage`, `budget`, `test-integrity`, `mutation-gate`, `package-existence`, `review-integrity`, `footprint`, `reconcile`, `conventions`, `learnings`, `review-fingerprints`, `timeline`, `health`, `progress` | Called by the relevant `rite-*` workflow or shared reply contract. |
-| Workspace utilities | `status`, `snapshot`, `analyze`, `archive-search`, `resolve`, `close-out`, `stuck`, `tick-afk`, `ledger`, `profile` | Called by a specific utility/phase when its condition is met. |
+| Workflow gates | `preamble`, `build-readiness`, `readiness-digest`, `spec-skeleton`, `spec-validate`, `check-acceptance`, `evidence-fresh`, `coverage`, `doubt-coverage`, `budget`, `test-integrity`, `mutation-gate`, `package-existence`, `review-integrity`, `footprint`, `reconcile`, `conventions`, `learnings`, `review-fingerprints`, `timeline`, `health`, `progress` | Called by the relevant `rite-*` workflow or shared reply contract. |
+| Workspace utilities | `status`, `snapshot`, `analyze`, `archive-search`, `clarify-return`, `recovery`, `resolve`, `close-out`, `stuck`, `tick-afk`, `ledger`, `profile` | Called by a specific utility/phase when its condition is met. |
 | Low-level completeness API | `readiness`, `seal` | Available for scripts/CI and documented engine use. Feature rites use stricter phase-specific gates (`build-readiness`, `/rite-seal` phase contract) instead of auto-running these weaker aggregate checks. |
 | Install / operator / CI | `install`, `update`, `uninstall`, `doctor`, `migrate`, `validate-pack`, `harness-matrix`, `extensions`, `overrides`, `reviewers`, `hook`, `version` | Called by `npx devrites ...`, `/rite-doctor`, hooks, CI, or a human operator; do not auto-run during feature work just because the command exists. |
 
@@ -49,24 +50,31 @@ Workflow-owned commands should have a concrete call site in a `rite-*` skill,
 phase contract, shared reply contract, or installed hook. Operator-owned commands
 must say who runs them.
 
+These similarly named operations have separate owners: `devrites-engine update`
+replaces the installed engine and pack, `devrites-engine migrate` normalizes
+workspace layout and structural state schema, and `/rite-upgrade` reconciles an
+active workspace with the current semantic planning contract.
+
 ## Public commands (`user-invocable: true`)
 
 | Command | Phase | Argument | What it does | Reads | Writes |
 |---|---|---|---|---|---|
 | [`/rite`](../pack/.claude/skills/rite/SKILL.md) | menu | `[subcommand]` | Compact menu + suggested next command. Pure router; does **not** read state 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-clarify`](../pack/.claude/skills/rite-clarify/SKILL.md) | clarify | `[slug]` | **Required, adaptive.** Topology-first coverage scan of the written spec; searches facts, closes human-owned decisions, audits assumptions, and takes a zero-question fast path when already clear. Writes a semantic `CLEAR` verdict bound to all decision inputs; later-phase retrofits persist and restore their return cursor when the contract is unchanged. | spec workspace + code/docs/decisions | `decision-coverage.md`, `spec.md`, `decisions.md`, `assumptions.md`, `questions.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-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.** 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-define`](../pack/.claude/skills/rite-define/SKILL.md) | define → plan | `[slug]` | Authors and approves architecture, plan, vertical `SLICE-###` tasks, and traceability, then leaves the workspace at the `plan` checkpoint for `/rite-vet`. | `spec.md` + `decision-coverage.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` and semantic, input-digest-bound `READY` verdict; 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) | repair → plan | `[mode]` | Reslice / repair / re-order / split / unblock an active plan and return to the `plan` checkpoint; `revise` is artifact-only and `/rite-vet` is the normal resume. | 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]` | Orchestrate **exactly one** vertical slice through the sole wright. The root writes an exact `.wright-allowlist`, retains the original slice baseline through snapshot → reconcile check → test/package integrity → close, and refreshes only the dispatch boundary on bounded retries. Objective failures stay agent-owned; only product/scope/policy choices, irreversible risk, or human-only access/actions become questions. | workspace + diff + `.devrites/CHECKPOINT` | code + `.wright-allowlist`, `recovery-attempts.jsonl`, `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.** Compare live code with clarified intent, append each unmet piece as a traceable `SLICE-###`, and invalidate the old vet verdict so changed work returns through `/rite-vet`. `tasks.md` stays byte-identical when already converged. | clarified spec + plan/tasks + principles + live code | `tasks.md` (appended), `traceability.md`, `state.md`, `eng-review.md` (invalidated), `decisions.md` |
+| [`/rite-upgrade`](../pack/.claude/skills/rite-upgrade/SKILL.md) | maintenance | `[slug]` | **Conditional recovery.** Bring an active unfinished workspace onto `devrites.readiness-artifacts.v2`. A fresh read-only planner identifies the smallest change; the rite preserves completed source, slices, decisions, and evidence, removes stale engine-proof recipes and machine-local wrappers from active plans, then reruns current readiness gates. Already-current workspaces that pass readiness, completed workspaces, and archives are no-ops. | active workspace + current readiness contract | active unfinished planning artifacts only |
 | [`/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-review`](../pack/.claude/skills/rite-review/SKILL.md) | review | `[scope]` | Feature-scoped multi-axis review. Parallel fresh-context Spec + Standards 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 | 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-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | (orchestrator) | `[idea] [--ship\|--yolo] [--max-slices N]` | Full lifecycle (spec → clarify → … → seal → ship). Spec + clarify form the one interactive window; AFK/checkpoint mode arms only after decision coverage is CLEAR. Pauses for genuine human-owned decisions/actions, NO-GO, or budget exhaustion; objective red checks use bounded technical recovery. Default stops at final type-`GO`; `--ship` (`--yolo`) auto-confirms it. | 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` |
@@ -94,26 +102,31 @@ the shared reference library.
 |---|---|---|---|
 | [`devrites-interview`](../pack/.claude/skills/devrites-interview/SKILL.md) | `/rite-spec`, underspecified ask | One-Q-at-a-time protocol | best-guess + confidence stop |
 | [`devrites-source-driven`](../pack/.claude/skills/devrites-source-driven/SKILL.md) | uncertain framework/library fact | Consult docs/source, record citation | writes `evidence.md` / `decisions.md` |
-| [`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-doubt`](../pack/.claude/skills/devrites-doubt/SKILL.md) | non-trivial decision in build/review | CLAIM → EXTRACT → DOUBT → RECONCILE → STOP | adversarial; the root gates genuine human-owned uncertainty |
 | [`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-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 |
+| [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | failing tests/build/runtime | 7-step: loop → reproduce → hypotheses → trace → instrument → fix → cleanup | durable three-failure budget per root-cause fingerprint |
 | [`devrites-api-interface`](../pack/.claude/skills/devrites-api-interface/SKILL.md) | cross-boundary slice | Stable API/contract design | FE/BE split |
 | [`devrites-audit simplify`](../pack/.claude/skills/devrites-audit/SKILL.md) | `/rite-polish` Phase 1 | Chesterton's Fence, behavior-preserving simplification | dispatches `devrites-simplifier-reviewer` |
 | [`devrites-audit security`](../pack/.claude/skills/devrites-audit/SKILL.md) | input/auth/data/integration in scope | OWASP Top 10, three-tier boundary | dispatches `devrites-security-auditor` |
 | [`devrites-audit perf`](../pack/.claude/skills/devrites-audit/SKILL.md) | perf relevant or regression risk | Measure-first, CWV targets | dispatches `devrites-performance-reviewer` |
-| [`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: host-neutral fresh-context dispatch + reconciliation rules for parallel reviewer fan-out | not a skill: a reference file |
 
-## Agents (`.claude/agents/devrites-*`, fresh-context subagents)
+## Agents (`.claude/agents/devrites-*`, fresh-context leaves)
 
-**13 read-only** (12 reviewers + the cross-feature `devrites-retrospector`) plus one **write-capable** executor (`devrites-slice-wright`).
+**Eighteen roles:** 17 read-only leaves plus one source/test writer,
+`devrites-slice-wright`.
 
 | 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-evidence-scout`](../pack/.claude/agents/devrites-evidence-scout.md) | `/rite-spec`, `/rite-clarify`, `/rite-converge` | Read-only bounded evidence dossier from live code, project records, or cited external facts |
+| [`devrites-plan-drafter`](../pack/.claude/agents/devrites-plan-drafter.md) | `/rite-define`, `/rite-plan repair` | Read-only planning candidate; the root makes decisions and writes planning artifacts |
+| [`devrites-proof-runner`](../pack/.claude/agents/devrites-proof-runner.md) | `/rite-prove`, affected re-proof | Read-only tree plus non-destructive command execution; returns a proof report, never the verdict |
+| [`devrites-upgrade-planner`](../pack/.claude/agents/devrites-upgrade-planner.md) | `/rite-upgrade` | Fresh read-only assessment of semantic contract gaps; returns a bounded preservation-first upgrade plan |
+| [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) | `/rite-build` (the build core) | **Sole source/test writer**: implement one exact allowlisted slice (orient → TDD → verify); returns a typed artifact and 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 to 3 competing candidate builds (acceptance / test strength / principle fit / simplicity / reuse / anti-slop); picks the single winner to land, names grafts; read-only |
@@ -128,10 +141,19 @@ the shared reference library.
 | [`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 |
 
+Only the root dispatches; leaves never dispatch other leaves. The first
+fallback is a generic `explorer` or `worker` that reads the same role contract,
+but only when the host preserves the required read-only or exact-write
+boundary. If no safe fresh-context option is available, the root runs the work
+inline and labels the result `independence: fallback`. Declared leaf identity
+and scope guards fail closed. A missing or crashed engine blocks the tool call
+instead of granting permission to continue.
+
 ## Engineering rules (`pack/.claude/skills/devrites-lib/reference/standards/`)
 
-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
+Workspace-operating lifecycle skills read `core.md` in step 0, while compact
+utilities load their narrower contract. Other rules load on demand. The full
+index is 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.
@@ -154,10 +176,10 @@ in step 0; compact utilities load their narrower contract. The rest are referenc
 
 ## Code-graph integration
 
-Skills that prefer a code-intelligence index (`codegraph_*` / `graphify-out/`)
-when available, falling back to file reads otherwise:
+These skills prefer a code-intelligence index (`codegraph_*` or
+`graphify-out/`) when available and fall back to file reads:
 
-- `/rite-spec`, `/rite-define`, `/rite-plan`: placement / impact / callers during investigation
+- `/rite-spec`, `/rite-clarify`, `/rite-define`, `/rite-plan`: placement / impact / callers during investigation and decision coverage
 - `/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
@@ -168,10 +190,10 @@ when available, falling back to file reads otherwise:
 
 ## Interactions (typical flow)
 
-See [`flow.md`](flow.md) for the Mermaid diagrams. The text path:
+See [`flow.md`](flow.md) for the Mermaid diagrams. The text form is:
 
 ```
-/rite-frame → /rite-spec → /rite-temper → /rite-define → /rite-vet → /rite-build ×N → /rite-converge → /rite-prove → /rite-polish → /rite-review → /rite-seal → /rite-ship
+/rite-frame → /rite-spec → /rite-clarify → /rite-temper → /rite-define → /rite-vet → /rite-build ×N → /rite-converge → /rite-prove → /rite-polish → /rite-review → /rite-seal → /rite-ship
    │            │                │  ▲              │                          │             (decide)   (execute+close)
    │            │                │  └ Spec Drift Guard → /rite-plan repair ────┘
    │            │                └ devrites-frontend-craft / source-driven / doubt
@@ -182,9 +204,10 @@ See [`flow.md`](flow.md) for the Mermaid diagrams. The text path:
 
 - Every phase **reads the active workspace first**; if none, it stops and tells
   the user to run `/rite-spec <feature>`.
-- **Spec Drift Guard** lives in build/prove/polish/review/seal: on drift,
-  stop, record in `drift.md`, classify, ask the user if product behavior
-  changes, then `/rite-plan repair` before resuming.
+- **Spec Drift Guard** lives in build/prove/polish/review/seal: on drift, stop,
+  record in `drift.md`, and classify. Objective implementation and tool defects
+  use bounded recovery; a wrong durable plan uses `/rite-plan repair`; only a
+  product, policy, or irreversible-risk choice asks the user.
 - `/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

package/docs/engine/agent-contract.md

@@ -1,9 +1,9 @@
 # `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** 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.
+An unattended driver, such as the AFK loop, a CI step, or a local script,
+needs a stable result format instead of prose that may change. The read commands
+used by AFK accept `--json` and write a stable envelope to stdout. The flag does
+not change the command's logic or exit code.
 
 ## Which commands accept `--json`
 
@@ -12,9 +12,9 @@ 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` 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.
+Other subcommands, including hooks, `footprint`, `tick-afk`, and mutating
+commands, do not accept `--json` because drivers do not use their output for a
+decision. Only machine-read decision results expose the flag.
 
 Exception: `snapshot`, `context show --json`, and
 `reviewer-stats report --json` are already direct structured reports, not
@@ -26,6 +26,7 @@ act; reviewer stats emits the deterministic per-reviewer dispatch verdicts.
 
 ```json
 {
+  "schema": "devrites-command/v1",
   "command": "spec-validate",
   "ok": false,
   "exitCode": 1,
@@ -44,17 +45,19 @@ act; reviewer stats emits the deterministic per-reviewer dispatch verdicts.
 
 | field | meaning |
 | ----- | ------- |
+| `schema` | `devrites-command/v1` |
 | `command` | the subcommand that ran |
 | `ok` | `exitCode == 0`: the one boolean a driver branches on |
 | `exitCode` | the process exit code (authoritative; see the table below) |
+| `reason_id` | optional rule-owned outcome ID; currently emitted by lifecycle gates |
 | `data.text` | the command's human-readable stdout, verbatim and lossless (omitted when empty) |
 | `diagnostics[]` | one entry per stderr line, classified (omitted when none) |
 
-`data.text` preserves everything the text mode prints, so nothing is lost by
-choosing `--json`. Structured consumers key on `ok` / `exitCode` / `diagnostics`
-and ignore `data.text`; a human reads `data.text` and ignores the rest.
+`data.text` contains the complete text-mode output. Structured consumers read
+`ok`, `exitCode`, and `diagnostics` and ignore `data.text`; human readers can do
+the reverse.
 
-## Diagnostic
+## Diagnostics and reasons
 
 | field | meaning |
 | ----- | ------- |
@@ -64,6 +67,11 @@ and ignore `data.text`; a human reads `data.text` and ignores the rest.
 | `path` | source path, when the finding named one |
 | `line` | 1-based line, when the finding named one |
 
+`diagnostics[].code` remains compatible with existing consumers. Some older
+codes are coarse or classified from stderr shape. New automation should prefer
+the top-level `reason_id` when present: its value comes from the rule that made
+the decision, so editing human wording cannot change it.
+
 ## Exit-code contract
 
 | code | meaning |
@@ -88,7 +96,76 @@ the prefix while the catalog grows specific kinds:
 | `ledger_grammar` | `ledger validate` | a ledger spec fails the grammar |
 | `<command>_error` / `_warning` / `_info` | any | an unclassified stderr line at that severity |
 
-New specific codes append to this table; the `<command>_<severity>` fallback keeps
-any future stderr line representable without a code change. `engine/tests/json_contract_test.go`
-gauntlets the AFK-parsed commands so every `--json` run stays one parseable JSON document whose
-`exitCode` and `ok` match the process result.
+New specific codes append to this table. The `<command>_<severity>` fallback
+represents future stderr lines without a code change.
+`engine/tests/json_contract_test.go` checks every AFK-parsed command so each
+`--json` run remains one parseable JSON document whose `exitCode` and `ok` match
+the process result.
+
+## Execution provenance: `devrites-event/v1`
+
+The engine appends a compact event to the existing `.devrites/timeline.jsonl`.
+When an active workspace exists, it appends the same event to that workspace's
+`events.jsonl`. There is no second store and no migration: older unversioned
+timeline rows remain readable beside v1 rows.
+
+```json
+{
+  "schema": "devrites-event/v1",
+  "ts": "2026-07-23T12:34:56Z",
+  "run_id": "drv-run-v1:0123456789abcdef0123456789abcdef",
+  "boundary": "lifecycle-gate",
+  "root_source": "DEVRITES_ROOT",
+  "workspace": ".devrites/work/auth-tokens",
+  "phase_before": "build",
+  "event": "readiness",
+  "rule_ids": ["DRV-GATE-READINESS-MISSING"],
+  "evidence_paths": [".devrites/work/auth-tokens/test-plan.md"],
+  "phase_after": "build",
+  "execution_mode": "none",
+  "guard_strength": "n/a",
+  "reason_id": "DRV-GATE-READINESS-MISSING",
+  "outcome": "blocked",
+  "host": "engine"
+}
+```
+
+The v1 validator accepts only:
+
+- `execution_mode`: `named` · `generic` · `inline` · `none`;
+- `guard_strength`: `enforced` · `observed` · `unavailable` · `bypassed` · `n/a`;
+- `host`: `engine` · `claude` · `codex`;
+- registered `DRV-*` reason and rule IDs;
+- canonical phases and project-relative workspace/evidence paths.
+
+Events never contain prompts, commands, tool or source bodies, answers, free
+text, secrets, usernames, or absolute paths. A bad or unwritable event affects
+metrics only. Root, gate, and hook decisions do not depend on the event write.
+
+The first live boundaries are root selection, readiness/seal, hook guards, and
+destructive-Git policy.
+Hook records distinguish an enforced denial from an observe-only finding, an
+unavailable adapter/input, and an intentional bypass. Forge binding denials and
+the opt-in WebFetch ingestion warning use the same schema.
+
+### Reason registry
+
+`engine/internal/reason` is the Go source of truth. Current lifecycle matrix
+reasons are:
+
+| reason ID | owner |
+| --- | --- |
+| `DRV-GATE-READINESS-PASSED` / `DRV-GATE-READINESS-MISSING` | readiness gate |
+| `DRV-GATE-SEAL-PASSED` / `DRV-GATE-SEAL-MISSING` | seal gate |
+| `DRV-HOOK-STOP-*` | Stop rest-point rules and loop/input handling |
+| `DRV-HOOK-REVIEWER-READONLY-*` | reviewer mutation guard |
+| `DRV-HOOK-A1-*` | main-thread build write guard |
+| `DRV-HOOK-WRIGHT-*` | wright scope and forbidden-operation guard |
+| `DRV-HOOK-FORGE-BINDING-DENIED` | Forge manifest/worker binding |
+| `DRV-HOOK-INGEST-WARNING` | opt-in WebFetch warning trial |
+| `DRV-GIT-AMBIGUOUS-*` / `DRV-GIT-INPUT-TOO-LARGE` | direct-literal Git parser boundary |
+| `DRV-GIT-DESTRUCTIVE-*` | destructive-operation classifier |
+| `DRV-GIT-AUTHORITY-*` / `DRV-GIT-WORKSPACE-UNAVAILABLE` | exact one-shot authority and replay gate |
+| `DRV-AGENT-*` | named/generic/inline execution and result reconciliation |
+
+Add a reason to that registry before an emitting rule or eval depends on it.