devrites 3.0.7 → 3.2.0

package/docs/engine/workspace-schema.md

@@ -1,26 +1,49 @@
 # DevRites workspace artifact schema
 
-DevRites workspaces are durable source-of-truth folders for a feature. Chat is
-temporary; the workspace must be enough for a fresh human or AI to resume without
-guessing. The schema follows three rules:
+A DevRites workspace is the durable record for a feature. Chat is temporary,
+so a fresh human or AI must be able to resume from the files alone. The schema
+follows three rules:
 
 - Keep each Markdown file single-purpose and compact.
 - Read the index first, then load only the files needed for the current phase.
 - Trace every acceptance criterion through slices, proof, evidence, and touched files.
 
-Root selection has two axes:
+Root and workspace selection use these inputs:
 
-- `DEVRITES_ROOT` selects the project root or `.devrites/` directory. When unset, the engine walks up
-  from cwd to the nearest `.devrites/`.
+- `DEVRITES_ROOT` selects the project root or `.devrites/` directory and is
+  canonicalized to its physical path.
+- Without an override, the engine walks from cwd only to the current Git
+  top-level. A nested repository, worktree, or submodule never inherits
+  `.devrites/` from its parent or superproject. Outside Git, the filesystem
+  ancestor walk remains available.
 - `.devrites/ACTIVE` selects the active feature workspace.
 - `DEVRITES_WORKSPACE` optionally names an explicit workspace path for CI/agents and overrides
-  `.devrites/ACTIVE` for commands that default to the active feature.
+  `.devrites/ACTIVE` for commands that default to the active feature. Its
+  resolved path must stay inside the selected `.devrites/` root. Setting it
+  without a selectable root is a refusing `DRV-WORKSPACE-WITHOUT-ROOT` hazard.
+
+`devrites-engine context show --json` and `doctor` expose the same canonical
+facts: lexical/physical project and root, selection reason, Git top-level,
+physical Git dir/common dir/superproject, linked-worktree/submodule flags, and
+stable hazards. The engine refuses writes when root selection is unsafe or
+ambiguous. `doctor` reports ordinary absence without treating it as a crash.
+
+The canonical workspace-map frontmatter declares `schemaVersion: 2`. The
+engine reads missing/v1 declarations and legacy aliases additively, refuses a
+version newer than it supports, and keeps the snapshot wire schema separate.
+`devrites-engine migrate` upgrades the declaration and layout metadata; it does
+not manufacture decision coverage, vet readiness, test plans, or proof.
+Semantic planning compatibility uses a separate readiness-artifact contract.
+The current value is `devrites.readiness-artifacts.v2`; `/rite-upgrade [slug]`
+reconciles an active unfinished workspace when build readiness reports an older
+or unknown contract.
 
 Canonical live workspace:
 
 ```text
 .devrites/
   ACTIVE
+  timeline.jsonl              # local metadata-only v1 workflow trace
   work/
     <slug>/
       README.md                 # compact workspace map; feature.md/index.md aliases allowed
@@ -31,10 +54,19 @@ Canonical live workspace:
       decisions.md              # ADR-style decision log
       assumptions.md            # assumptions and validation status
       questions.md              # open/resolved human questions
+      decision-coverage.md       # topology-first clarification verdict
       plan.md                   # technical approach and slice strategy
       tasks.md                  # vertical slices
       traceability.md           # AC/REQ -> slices -> tests/evidence/files matrix
+      eng-review.md              # implementation-readiness verdict
+      test-plan.md               # executable proof target
       state.md                  # compact cursor; status.md alias allowed
+      events.jsonl              # feature-local copy of v1 workflow trace
+      recovery-attempts.jsonl   # durable bounded technical-recovery ledger
+      .git-authority-consumption.jsonl # private one-shot Git grant consumption
+      .wright-allowlist         # root-owned exact source/test write scope
+      .forge/
+        <run-id>/manifest.json  # engine-owned Forge lifecycle and path authority
       evidence.md               # command/action proof; proof.md alias allowed
       browser-evidence.md       # optional UI/runtime browser proof
       drift.md                  # optional spec/plan drift register
@@ -50,17 +82,18 @@ Canonical live workspace:
 Backward compatibility: `.devrites/features/<slug>/` remains readable as an alias
 for `.devrites/work/<slug>/`; `feature.md` and `index.md` remain valid workspace
 maps; `status.md` remains a cursor alias for `state.md`; `proof.md` remains a
-proof alias for `evidence.md`. Migration should add the canonical files without
-deleting aliases.
+proof alias for `evidence.md`. Migration normalizes compatible metadata without
+deleting aliases or inventing evidence.
 
 ## Read order
 
 | Phase / role | Read first | Then read | Usually skip |
 | --- | --- | --- | --- |
 | Spec | `README.md`, `brief.md` | `spec.md`, `references.md`, `questions.md` | `plan.md`, `evidence.md` |
-| Define / plan | `README.md`, `state.md` | `spec.md`, `architecture.md`, `decisions.md`, `assumptions.md` | `evidence.md` |
+| Clarify | `README.md`, `state.md` | `spec.md`, `decisions.md`, `assumptions.md`, `questions.md` | plan/proof artifacts |
+| Define / plan | `README.md`, `state.md` | `spec.md`, `decision-coverage.md`, `architecture.md`, `decisions.md`, `assumptions.md` | `evidence.md` |
 | Vet | `README.md`, `traceability.md` | `plan.md`, `tasks.md`, `architecture.md`, `decisions.md` | browser proof unless UI |
-| Build | `state.md`, `tasks.md` | `plan.md`, `architecture.md`, `traceability.md`, `questions.md` | full evidence history |
+| Build | `state.md`, `tasks.md` | `decision-coverage.md`, `eng-review.md`, `test-plan.md`, `plan.md`, `architecture.md`, `traceability.md`, `questions.md` | full evidence history |
 | Prove | `traceability.md`, `tasks.md` | `evidence.md`, `browser-evidence.md`, `touched-files.md` | long plan rationale |
 | Review / seal | `README.md`, `traceability.md` | `spec.md`, `evidence.md`, `decisions.md`, `drift.md`, `touched-files.md` | raw logs unless needed |
 | Handoff | `README.md`, `state.md` | `handoff.md`, then linked source files | duplicated summaries |
@@ -72,6 +105,7 @@ deleting aliases.
 | `README.md` / `index.md` / `feature.md` | required | `/rite-spec` | always first | 120 lines | current phase, status, next action, artifact map, read-next table, blocking gates, last updated | Must not duplicate full spec/plan/evidence. |
 | `brief.md` | required | `/rite-spec` | clarify objective | 80 lines | Objective, Non-goals, Success definition | One-screen request and scope summary. |
 | `spec.md` | required | `/rite-spec` | product contract | 260 lines | Problem, Goal, Non-goals, Users / actors, Requirements, Acceptance criteria, Edge Coverage, Prohibitions (must-NOT), Edge cases, Measurable success, Scope boundaries | Must use stable `REQ-###` and `AC-###`; no deep implementation details. |
+| `decision-coverage.md` | required from clarify | `/rite-clarify` | decision/readiness audit | 200 lines | Topology, Coverage matrix, Assumption audit, Residual uncertainty, Readiness verdict | Exactly one semantic `Decision coverage: CLEAR` plus a fresh canonical input digest. Partial, Missing, unowned, open-human-gate, placeholder, or incomplete rows block. |
 | `architecture.md` | required from plan | `/rite-define` | placement/integration work | 180 lines | Owning module / layer, Integration points, Data / API / events, Dependencies, Risks, Affected boundaries | Carries topology and boundaries, not product acceptance. |
 | `flows.md` | optional | `/rite-spec` or `/rite-define` | lifecycle/state/sequence/data flow is hard to infer | 160 lines | diagram-specific headings | Mermaid only when it clarifies behavior; each diagram states why it matters and related IDs. |
 | `decisions.md` | required | all phases | non-trivial product/technical choice | 200 lines | Decision log | Entries use `DEC-###`, status, context, options, decision, consequences, related IDs. |
@@ -81,7 +115,14 @@ deleting aliases.
 | `plan.md` | required from plan | `/rite-define` | implementation approach | 220 lines | Approach, Slice strategy, Validation strategy, Rollback | HOW lives here, not in `spec.md`. `Validation strategy` names the Key links: cross-slice wiring `/rite-prove` walks (or `none` for single-slice features). |
 | `tasks.md` | required from plan | `/rite-define` | build one slice | 280 lines | Slice index | Each `SLICE-###` has goal, AC IDs, likely files, tests/proof, mode, gate, dependencies, done condition. |
 | `traceability.md` | required from plan | `/rite-define` | coverage/review/seal | 220 lines | Coverage matrix | Matrix maps AC/REQ ID, slice IDs, test/proof, evidence ID, touched files, status. |
-| `state.md` / `status.md` | required | all phases | current cursor | 120 lines | Cursor | `state.md` is canonical; `status.md` is a compatibility alias. Compact table/key-value cursor; not an append-only narrative. |
+| `eng-review.md` | required from vet | `/rite-vet` | build readiness | 240 lines | Depth, Scope challenge, Build-entry preflight, Implementation readiness, Completion summary | Exactly one semantic `Implementation readiness: READY` plus a fresh canonical input digest. Non-passing preflight/readiness rows, placeholders, empty tables, or unmapped acceptance block. |
+| `test-plan.md` | required from vet | `/rite-vet` | build/prove coverage target | 260 lines | Build-entry preflight, Coverage diagram, Per-gap test requirements, Acceptance → test map | Commands, cwd, expected signal, prerequisites, and provenance are executable. |
+| `state.md` / `status.md` | required | all phases | current cursor | 120 lines | Cursor | `state.md` is canonical; `status.md` is a compatibility alias. Compact table/key-value cursor; later-phase clarification durably stores `return_phase` and `return_next_action` until fresh coverage restores or replans it. |
+| root `timeline.jsonl` + feature `events.jsonl` | local telemetry only | engine/hooks | bounded report, audit, manual retention | JSONL | n/a | New writes are validated `devrites-event/v1` metadata only. Reports ignore legacy/corrupt rows and never make events lifecycle-authoritative. Exact purge may delete only these telemetry files. |
+| `recovery-attempts.jsonl` | technical recovery only | root orchestrator | retry budget | generated | n/a | Fingerprinted, append-only failed/cleared records cap the same objective root cause at three failed attempts across agents and sessions. |
+| `.git-authority-consumption.jsonl` | destructive Git only | `git-guard` | one-shot replay prevention | generated | n/a | `devrites-git-authority-consumption/v1` JSONL, bounded and mode `0600` where POSIX modes exist; stores only qid, exact digest, classifier reason IDs, and consumption time. |
+| `.wright-allowlist` | build only | root orchestrator | writer scope | generated | n/a | Exact normalized project-relative files only; no directories, globs, traversal, duplicates, or `.devrites/**`. Writer self-report never expands it. |
+| `.forge/<run-id>/manifest.json` | Forge runs only | engine | candidate ownership and lifecycle | generated | n/a | One `devrites-forge/v1` manifest owns the primary baseline, scorecard hashes, candidate paths/branches/states, worker bindings, judge winner, merge, verification, and cleanup. Duplicate, symlinked, escaped, or tampered ownership fails closed. |
 | `evidence.md` / `proof.md` | required from prove | `/rite-build`, `/rite-prove` | proof and seal | 280 lines | Evidence log | `EVID-###`, command/action, result, related AC/slice IDs, limitations. Each acceptance criterion carries a proof class: `test` / `command` / `browser` / `judgment` (untagged reads `judgment`; `judgment` needs its one-line why). |
 | `browser-evidence.md` | UI only | `/rite-prove`, `/rite-polish` | UI/browser proof | 220 lines | Browser evidence, Visual Verdict | Must reference real route/viewports/actions and related IDs. |
 | `drift.md` | drift only | Spec Drift Guard | spec/plan reality mismatch | 160 lines | Drift register | `DRIFT-###`, status, evidence found, resolution, related IDs. |
@@ -90,23 +131,67 @@ deleting aliases.
 | `handoff.md` | optional | `/rite-handoff` | cold resume | 120 lines | Resume, Read next, Next action | Links to source artifacts instead of copying them. |
 | `references.md` + `references/` | optional | `/rite-spec` | external/user-supplied material | 160 lines | Reference index | Links must resolve or be external URLs. |
 
+Telemetry is deliberately outside the correctness contract. Missing or corrupt
+`timeline.jsonl` / `events.jsonl` may degrade `timeline report`, `progress`, or
+the statusline, but can never change a gate, cursor, question, evidence verdict,
+recovery budget, capability decision, or destructive-action authority. Reports
+read a bounded tail; `timeline purge --before ...` and/or `--run ...` rewrites
+only these logs. The engine sends no remote telemetry. Remove old unversioned
+logs manually when their legacy free text should not be retained.
+
 Files may exceed budgets only with a visible `Budget override: <reason>` line.
 
+## Readiness gate binding
+
+The typed verdict is necessary but not sufficient:
+
+- `decision-coverage.md`, `eng-review.md`, and `test-plan.md` declare
+  `DevRites contract: devrites.readiness-artifacts.v2`.
+- `Coverage inputs SHA-256` binds `decision-coverage.md` to `brief.md`,
+  `spec.md`, `decisions.md`, `assumptions.md`, and `questions.md`.
+- `Readiness inputs SHA-256` binds `eng-review.md` to `spec.md`,
+  `decision-coverage.md`, `architecture.md`, `plan.md`, `tasks.md`,
+  `traceability.md`, and `test-plan.md`.
+
+`devrites-engine readiness-digest coverage|engineering [slug]` emits the
+canonical field line. `build-readiness` rejects stale digests, malformed or
+contradictory content, missing markers, and older or unknown semantic contracts.
+Contract failures use code `8` and route to `/rite-upgrade`; missing coverage or
+vet artifacts keep their existing `/rite-clarify` and `/rite-vet` routes. A
+later-phase clarification
+retrofit uses `clarify-return enter|restore`; restore requires fresh `CLEAR`
+coverage, while an acceptance-changing result keeps the cursor for plan repair.
+
 ## Required vs optional
 
 Required at `/rite-spec`: workspace map, `brief.md`, `spec.md`, `state.md`,
 `decisions.md`, `assumptions.md`, `questions.md`.
 
-Required at `/rite-define` and later: all spec files plus `architecture.md`,
+Required at `/rite-clarify` and later: all spec files plus `decision-coverage.md`.
+
+Required at `/rite-define` and later: all clarified spec files plus `architecture.md`,
 `plan.md`, `tasks.md`, and `traceability.md`.
 
-Required at `/rite-prove` and later: all plan files plus `evidence.md` (or
+Required at `/rite-vet` and later: all plan files plus `eng-review.md` and `test-plan.md`.
+
+Required at `/rite-prove` and later: all vetted plan files plus `evidence.md` (or
 `proof.md`) and `touched-files.md`.
 
 Optional/conditional files are generated only by their producing phase:
 `flows.md` when diagrams clarify behavior, `design-brief.md` and
 `browser-evidence.md` for UI, `drift.md` for drift, `handoff.md` for handoff,
-and `references.md` / `references/` when references exist.
+and `references.md` / `references/` when references exist. The build runtime
+creates `.wright-allowlist` and, only when needed, `recovery-attempts.jsonl`.
+Forge creates `.forge/<run-id>/manifest.json` only after a clean, bound
+parallel plan passes. A serial degradation creates no Forge state.
+
+Forge candidate worktrees do not live inside `.devrites`. The manifest binds
+them to the sibling
+`.<repo>.devrites-forge/<run-id>/candidate-<a|b|c>` paths before Git creates
+them. Every later extract, merge, cleanup, and reap command reloads the unique
+manifest instead of accepting a caller-supplied path or branch. Cleanup
+requires a landed winner and recorded successful verification, and it
+preserves dirty, live, foreign, or ambiguous state.
 
 ## Compactness rules
 
@@ -132,6 +217,7 @@ Use these forms in generated artifacts:
 | Question | `Q-001` | `questions.md` |
 | Drift event | `DRIFT-001` | `drift.md` |
 | Evidence | `EVID-001` | `evidence.md`, `browser-evidence.md` |
+| Forge run | `forge-` plus 24 lowercase hex characters | `.forge/<run-id>/manifest.json` |
 
 ## Validation
 
@@ -141,6 +227,8 @@ project-wide validation path runs it against representative fixtures.
 The validator checks:
 
 - required files and headings for the current phase;
+- supported workspace `schemaVersion` and additive legacy aliases;
+- semantic, fresh digest-bound `CLEAR` and `READY` readiness artifacts;
 - stable IDs and old `AC1` / `Slice 1` style regressions;
 - acceptance criteria referenced by at least one slice;
 - completed slices referenced by evidence;

package/docs/extensions.md

@@ -66,7 +66,7 @@ devrites-engine extensions sync        # mirror valid extensions into .claude/ f
 Public schemas live in [`../schemas/`](../schemas/): `extension-component.schema.json` and
 `provenance.schema.json` for extension metadata, plus workspace/hook schemas for editor tooling.
 
-`component.yaml` is the DevRites-native answer to Spec Kit-style extension/preset/bundle metadata.
+`component.yaml` is DevRites' native extension, preset, and bundle metadata.
 It is **not** a plugin package descriptor; it documents what the npm-installed engine may copy or
 validate inside the current project.
 

package/docs/flow.md

@@ -1,43 +1,55 @@
 # DevRites flow diagrams
 
-Visual reference for how the skills, agents, and rules fit together. GitHub
-renders Mermaid natively: open this file on the repo to see the graphs.
+These diagrams show how the skills, agents, and rules interact. GitHub renders
+the Mermaid blocks when you open this file in the repository.
 
 For the full per-skill table, see [`command-map.md`](command-map.md). For the
 "why" behind each piece, see [`architecture.md`](architecture.md).
 
 ## 1. Feature lifecycle
 
-The happy path. Every arrow assumes the readiness gate of the previous phase
-passed; failures route through `/rite-plan repair` or `devrites-debug-recovery`.
-`/rite-temper` is the optional strategic branch; `/rite-vet` runs on every
-defined plan, with depth scaled to risk. HITL slices pause before code is
-written; `/rite-resolve` is the resume verb.
+This diagram shows the normal path. Each arrow assumes that the previous
+phase's readiness gate passed. Failures route through `/rite-clarify`,
+`/rite-plan repair`, `/rite-upgrade`, or `devrites-debug-recovery`.
+`/rite-upgrade` is conditional maintenance rather than a lifecycle phase: build
+readiness uses it only when existing semantic artifacts are stale.
+`/rite-clarify` always runs but may ask zero questions; `/rite-temper` is the
+optional strategic branch; `/rite-vet` runs on every defined plan, with depth
+scaled to risk. Build asks the human only for genuine
+product/scope/policy decisions, irreversible risk, or human-only access/actions;
+`/rite-resolve` is the resume verb.
 
 ```mermaid
 flowchart LR
     Start([user has an idea]) --> Spec[/rite-spec/]
     Spec -.->|UI detected| Shape[devrites-ux-shape<br/>plan UX/UI → design-brief.md]
     Shape -.->|brief confirmed| Spec
-    Spec -.->|big / risky| Temper[/rite-temper/] -.->|strategy.md| Define
-    Spec -->|spec.md ready| Define[/rite-define/]
-    Define -->|plan.md + tasks.md<br/>each slice tagged AFK/HITL| Vet[/rite-vet/]
-    Vet -->|every plan; light or full<br/>eng-review.md + test-plan.md| Build[/rite-build/]
+    Spec -->|spec.md ready| Clarify[/rite-clarify/]
+    Clarify -->|fresh digest-bound CLEAR<br/>big / risky| Temper[/rite-temper/] -.->|strategy.md| Define
+    Clarify -->|fresh digest-bound CLEAR<br/>low stakes| Define[/rite-define/]
+    Define -->|plan.md + tasks.md<br/>approved| Plan[(plan checkpoint)]
+    Plan -->|normal resume| Vet[/rite-vet/]
+    Vet -->|fresh digest-bound READY<br/>+ test-plan.md| Build[/rite-build/]
+    Build -.->|build-readiness code 8<br/>stale semantic contract| Upgrade[/rite-upgrade/]
+    Upgrade -.->|contract v2<br/>current gates pass| Build
+    Build -.->|exact .wright-allowlist<br/>retained baseline| Wright[devrites-slice-wright]
+    Wright -.->|typed result| Build
     Build -->|one slice done<br/>+ evidence| Build
     Build -.->|"Forge: yes slice"| Forge[forge: K candidates<br/>→ devrites-forge-judge → 1 winner]
     Forge -.->|winner lands<br/>forge-report.md| Build
-    Build -->|HITL gate fires| Await{{Awaiting human<br/>state.md + questions.md}}
+    Build -->|product / risk / access gate| Await{{Awaiting human<br/>state.md + questions.md}}
     Await -->|"/rite-resolve &lt;qid&gt; &lt;answer&gt;"| Build
     Build -->|all slices built| Prove[/rite-prove/]
     Build -.->|resumed / adopted / stalled<br/>code vs intent| Converge[/rite-converge/]
-    Converge -.->|appends remaining slices| Build
+    Converge -.->|appends remaining slices<br/>invalidates old READY| Vet
+    Converge -.->|already converged| Prove
     Prove -->|evidence captured| Polish[/rite-polish/]
     Polish -->|polish-report.md| Review[/rite-review/]
     Review -->|review.md<br/>Critical == 0| Seal[/rite-seal/]
     Seal -->|GO| Ship2[/rite-ship/]
     Ship2 -->|type-GO| Shipped([commit · push · tag · archive])
     Seal -->|NO-GO| Repair[/rite-plan repair/]
-    Repair --> Build
+    Repair --> Plan
 
     Build -.->|Spec Drift Guard| Repair
     Prove -.->|drift / failure| Repair
@@ -49,11 +61,11 @@ flowchart LR
     classDef repair fill:#4c1d95,stroke:#a78bfa,color:#f5f3ff
     classDef gate fill:#4c1d95,stroke:#a78bfa,color:#f5f3ff
     classDef internal fill:#0f172a,stroke:#9ca3af,color:#f9fafb
-    class Spec,Temper,Define,Vet,Build,Prove,Polish,Review,Seal,Ship2 phase
+    class Spec,Clarify,Temper,Define,Plan,Vet,Build,Prove,Polish,Review,Seal,Ship2 phase
     class Shipped done
-    class Repair repair
+    class Repair,Upgrade repair
     class Await gate
-    class Shape,Forge internal
+    class Shape,Forge,Wright internal
 ```
 
 ## 2. `/rite-polish` orchestrator
@@ -85,13 +97,14 @@ emphasis dials. `normalize-only` stops after Phase 3.
 
 ## 3. `/rite-review` parallel axes
 
-Review runs Spec coverage and Standards compliance in parallel sub-agents so
-neither masks the other.
+Review assigns Spec coverage and Standards compliance to separate
+fresh-context agents and runs them in parallel. This prevents one axis from
+masking the other.
 
 ```mermaid
 flowchart LR
-    R[/rite-review/] -->|spawn parallel<br/>via Task tool| S[devrites-spec-reviewer<br/>**Spec axis**]
-    R -->|spawn parallel<br/>via Task tool| C[devrites-code-reviewer<br/>**Standards axis**]
+    R[/rite-review/] -->|fresh-context dispatch<br/>in parallel| S[devrites-spec-reviewer<br/>**Spec axis**]
+    R -->|fresh-context dispatch<br/>in parallel| C[devrites-code-reviewer<br/>**Standards axis**]
     S -->|missing / partial / wrong /<br/>scope-creep findings| Combine
     C -->|standards violations<br/>cite rule + file| Combine
     R --> Sec[devrites-audit security]
@@ -110,10 +123,11 @@ flowchart LR
 
 ## 4. `/rite-seal` fan-out
 
-The seal fans out **all** relevant reviewers in parallel and reconciles their
-findings, then **decides** GO / NO-GO and stops. It no longer runs git: on GO
-it hands off to `/rite-ship`, which renders the type-GO prompt and runs the
-irreversible commit · push · tag · archive. The old advisory score has been removed: the gate is severity + acceptance + drift.
+The seal runs all relevant reviewers in parallel, reconciles their findings,
+decides GO or NO-GO, and stops without running git. On GO, `/rite-ship` renders
+the type-GO prompt and runs the irreversible commit · push · tag · archive
+sequence. The gate uses severity, acceptance, and drift rather than an advisory
+score.
 
 ```mermaid
 flowchart TB
@@ -156,36 +170,45 @@ flowchart TB
 
 ## 5. `devrites-debug-recovery` seven-step loop
 
-Failure recovery: the loop construction in Phase 1 is the load-bearing piece.
+Failure recovery starts by routing the faulty layer. `recovery route <class>`
+returns its owner, action, and whether a human decision is actually needed.
+The root-cause fingerprint and three-failure budget persist across agents and
+sessions in `recovery-attempts.jsonl`; typed entries keep independent defects
+on independent budgets.
 
 ```mermaid
 flowchart LR
-    F([failing test /<br/>build / runtime]) --> L1[Step 1<br/>Build the loop]
+    F([failing test /<br/>build / runtime]) --> Route{Route faulty layer}
+    Route -->|technical class<br/>humanPause: false| L1[Step 1<br/>Build the loop]
+    Route -->|intent / missing decision| Clarify([Clarify with the human])
     L1 -->|fast deterministic signal| R[Step 2<br/>Reproduce]
     R -->|exact error text| H[Step 3<br/>Ranked hypotheses 3-5]
     H --> T[Step 4<br/>Trace when ambiguous]
     T -->|discriminating probe| I[Step 5<br/>Instrument]
     I -->|change one variable| Fix[Step 6<br/>Fix + regression test]
     Fix --> C[Step 7<br/>Cleanup + classify]
-    L1 -.->|can't build loop| Ask([STOP: ask user])
+    C -->|green: recovery clear --class| Done([verified])
+    C -->|same root cause red:<br/>recovery record --class| Budget{3 failures<br/>used?}
+    Budget -->|no: recovery check<br/>+ exact failure| L1
+    Budget -->|yes| Block([technical blocker<br/>reproduction + dead ends])
 
     classDef phase fill:#1f2937,stroke:#60a5fa,color:#f9fafb
     classDef stop fill:#7f1d1d,stroke:#f87171,color:#fee2e2
     class L1,R,H,T,I,Fix,C phase
-    class Ask stop
+    class Block,Clarify stop
 ```
 
-Each step's detail lives in a separate reference file under
-`pack/.claude/skills/devrites-debug-recovery/reference/` so the SKILL.md body
-stays small.
+A separate file under
+`pack/.claude/skills/devrites-debug-recovery/reference/` documents each step.
+This keeps the `SKILL.md` body small.
 
 ## 6. Engineering-rules carrier
 
 Workspace-operating lifecycle skills read
 `.claude/skills/devrites-lib/reference/standards/core.md` in step 0; compact utilities
-keep their narrower contract local. The other rule files load on demand. Per-phase
-skills pull additional rule files via plain `Read` as their workflow
-demands. No carrier skill, no session-start autoload.
+keep their narrower contract local. The other rule files load on demand.
+Per-phase skills use plain `Read` calls to load any additional rule files their
+workflows need. There is no carrier skill or session-start autoload.
 
 ```mermaid
 flowchart TD
@@ -229,9 +252,9 @@ flowchart TD
 
 ## 7. Workspace state model
 
-`.devrites/work/<feature-slug>/` is the durable memory each phase reads
-before doing anything. **Every** rite-* skill reads the workspace first; if
-no `ACTIVE` is set, it tells the user to run `/rite-spec`. The optional
+Each phase reads its durable state from `.devrites/work/<feature-slug>/` before
+acting. Every `rite-*` skill checks the workspace first; if `ACTIVE` is unset,
+it tells the user to run `/rite-spec`. The optional
 `.devrites/AFK` sentinel sits beside `ACTIVE` and toggles the session-level
 run mode for all skills.
 
@@ -242,10 +265,11 @@ erDiagram
     WORKSPACE ||--|| state : has
     WORKSPACE ||--|| brief : has
     WORKSPACE ||--|| spec : has
+    WORKSPACE ||--o| decision-coverage : "has (semantic + digest-bound CLEAR before planning)"
     WORKSPACE ||--o| strategy : "has (optional: from /rite-temper)"
     WORKSPACE ||--|| plan : "has (from /rite-define)"
     WORKSPACE ||--|| tasks : "has: slices tagged Mode + Gate"
-    WORKSPACE ||--o| eng-review : "has (from /rite-vet: every plan, light or full)"
+    WORKSPACE ||--o| eng-review : "has (semantic + digest-bound READY from /rite-vet)"
     WORKSPACE ||--o| test-plan : "has (from /rite-vet; build + prove read it)"
     WORKSPACE ||--o{ references : "has (design refs)"
     WORKSPACE ||--o| design-brief : "has (UI features: from /rite-spec via devrites-ux-shape; the build target)"
@@ -260,6 +284,8 @@ erDiagram
     WORKSPACE ||--o| review : "has (from /rite-review)"
     WORKSPACE ||--o| seal : "has (from /rite-seal)"
     WORKSPACE ||--o| ship : "has (from /rite-ship; archived on close)"
+    WORKSPACE ||--o| recovery_attempts : "durable three-failure budget per root cause"
+    WORKSPACE ||--o| wright_allowlist : "root-owned exact source/test paths"
 
     ACTIVE {
         string slug "names the current workspace"
@@ -272,12 +298,15 @@ erDiagram
     }
     WORKSPACE {
         string slug PK ".devrites/work/<slug>/"
+        int schemaVersion "2; older additive layouts remain readable"
     }
     state {
-        string phase "frame | spec | temper | define | plan | vet | build | converge | prove | polish | review | seal | ship | done"
+        string phase "frame | spec | clarify | temper | define | plan | vet | build | converge | prove | polish | review | seal | ship | done"
         string status "running | awaiting_human | blocked | done"
         string active_slice "N: name"
         int afk_slices_remaining "from .devrites/AFK max_slices on first AFK build"
+        string return_phase "durable later-phase clarify return"
+        string return_next_action "restored only after fresh CLEAR"
         block awaiting_human "qid, gate, question, proposed, raised_at (only when paused)"
     }
     questions {
@@ -300,10 +329,11 @@ separately by `disable-model-invocation`.
 
 ```mermaid
 flowchart TB
-    subgraph Public["Public (user-invocable: true): 30 skills"]
+    subgraph Public["Public (user-invocable: true): 32 skills"]
         direction TB
         R1[/rite/]
         R2[/rite-spec/]
+        RCL[/rite-clarify/]
         RT[/rite-temper/]
         R3[/rite-define/]
         RV[/rite-vet/]
@@ -323,6 +353,7 @@ flowchart TB
         RA[/rite-adopt/]
         RL[/rite-learn/]
         RD[/rite-doctor/]
+        RU[/rite-upgrade/]
         RE[/rite-explain/]
         RCU[/rite-customize/]
         RDO[/rite-dogfood/]
@@ -351,23 +382,25 @@ flowchart TB
 
     classDef pub fill:#064e3b,stroke:#34d399,color:#ecfdf5
     classDef int fill:#1f2937,stroke:#9ca3af,color:#f9fafb
-    class R1,R2,RT,R3,RV,R4,R5,RC,R6,R7,R8,R9,R12,R13,R10,R11,RQ,RF,RA,RL,RD,RE,RCU,RDO,RPOV,RPF,IPT,D1,D2,D3 pub
+    class R1,R2,RCL,RT,R3,RV,R4,R5,RC,R6,R7,R8,R9,R12,R13,R10,R11,RQ,RF,RA,RL,RD,RU,RE,RCU,RDO,RPOV,RPF,IPT,D1,D2,D3 pub
     class I1,I2,I3,I4,I5,I6,I7,I8,I9,I10,I11,I12 int
 ```
 
 ## 9. AFK & HITL state machine
 
-The pause/resume primitive for HITL gates and the AFK loop discipline. The
-gate firing on `/rite-build` is the only writer of `Awaiting human`;
-`/rite-resolve` is the only canonical clearer.
+This state machine shows pauses for HITL gates and the AFK loop. Only the root
+`/rite-build` orchestrator writes `Awaiting human`, and only `/rite-resolve`
+clears it.
 
 ```mermaid
 stateDiagram-v2
     [*] --> running: /rite-build starts
     running --> running: AFK slice + advisory finding<br/>(log to questions.md, proceed)
-    running --> awaiting_human: HITL gate fires<br/>(blocking / escalating / out-of-gate)
-    running --> awaiting_human: Fail-on-red<br/>(tests/types/lint)
-    running --> awaiting_human: Irreversible risk<br/>(destructive · auth · public API)
+    running --> recovery: objective red<br/>(tests · types · lint · runtime · coverage)
+    recovery --> running: green<br/>recovery clear --class
+    recovery --> blocked: 3 failed attempts<br/>reproduction + dead ends; no question
+    running --> awaiting_human: product / scope / policy choice
+    running --> awaiting_human: irreversible risk or<br/>human-only access / action
     awaiting_human --> running: /rite-resolve qid "<answer>"
     awaiting_human --> running: /rite-resolve --drop qid
     awaiting_human --> blocked: /rite-plan repair (scope change)
@@ -383,6 +416,8 @@ stateDiagram-v2
     end note
 ```
 
-`AFK` mode (`.devrites/AFK` present) widens which transitions stay in
-`running` via `allow_gates`, but `blocking`, `escalating`, fail-on-red, and
-the irreversible-risk list always transition to `awaiting_human` regardless.
+`AFK` mode (`.devrites/AFK` present) widens which advisory/validating
+transitions stay in `running`. It never turns objective technical failures into
+human questions: bounded recovery either returns green or records a technical
+blocker. Genuine human-owned decisions and actions still transition to
+`awaiting_human`.

package/docs/harness-compliance.md

@@ -1,10 +1,10 @@
 # Harness adapter compliance
 
-DevRites drives more than one agent runtime from a single `devrites-engine`
-binary, but the runtimes do not expose identical enforcement surfaces. This page
-states, for each surface, whether a supported harness enforces it natively,
-through an adapter, or only by instruction the model may ignore. It is the honest
-answer to "does DevRites work the same on Codex as on Claude Code?"
+A single `devrites-engine` binary supports multiple agent runtimes, but those
+runtimes expose different enforcement surfaces. For each surface, this page
+states whether a supported harness provides native enforcement, uses an
+adapter, or relies on instructions that the model may ignore. The matrix shows
+where Codex and Claude Code behavior differs.
 
 Host support is enumerated in `engine/internal/harness/harness.go`, with the
 frozen capability matrix in `compliance.go`. New hosts must pass
@@ -15,6 +15,8 @@ The table below is **generated**. Its tiers describe whether the host exposes an
 event surface; they do not by themselves mean that every hook blocks. `a1-guard`,
 `reviewer-readonly`, `wright-scope`, and `stop-gate` are observe-only by default and become
 blocking only when the documented strict-enforcement environment switch is enabled.
+`git-guard` is different: standard and strict profiles enforce it; only minimal
+profile or its explicit kill-list entry disables it.
 
 The single source of truth is the frozen matrix
 in `engine/internal/harness/compliance.go`; regenerate this block with:
@@ -32,7 +34,9 @@ the table and the code can never silently drift apart.
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | SessionStart orientation | Native | Native | all phases | manual preamble/snapshot | yes | high | Both wire the orient hook; identical additionalContext envelope. |
 | PreToolUse policy (allow, a1-guard, reviewer-readonly, wright-scope) | Conditional | Conditional | build/review safety | observe-only findings + human review | yes | high | Both deliver the event, but these policies are non-blocking by default; DEVRITES_HOOK_PROFILE=strict enables every guard, or each guard can be enabled through its documented specific variable. |
+| Destructive Git authority | Conditional | Conditional | all shell tool calls | human permission review; no exact one-shot proof | yes | high | Both wire git-guard at PreToolUse. Standard and strict profiles enforce exact 15-minute one-shot authority; minimal profile or the explicit kill list disables the hook. |
 | PostToolUse sentinel (redwatch) | Native | Native | prove/build rest points | manual red/green check | yes | high | Fail-on-red sentinel wired on both. |
+| WebFetch ingestion warning trial | Conditional | Instruction-backed | external research | inspect retrieved content as untrusted data | no | medium | Claude WebFetch PostToolUse can emit an opt-in metadata-only warning with DEVRITES_INGEST_WARNING=warn; a flagged result remains in context and is omitted from the local source cache. Codex has no matching result event, so this trial is unavailable and silent. |
 | Stop gate | Conditional | Conditional | all rest points | observe-only finding + manual host-specific rite-status | yes | high | Both deliver Stop; stop-gate blocks with DEVRITES_STOP_GATE=enforce or DEVRITES_HOOK_PROFILE=strict. |
 | SubagentStart discipline injection | Native | Native | review/build fan-out | agent file preamble | yes | high | subagent-orient wired on both. |
 | Skill invocation | Native | Adapter-backed | all public rites | explicit file read | yes | high | Claude: native /rite. Codex: $rite over the mirrored .agents/skills tree. |
@@ -43,3 +47,23 @@ the table and the code can never silently drift apart.
 Tiers: **Native** (the harness exposes and delivers the surface directly; policy notes state whether it blocks) · **Adapter-backed** (supported through a translation shim) · **Instruction-backed** (no runtime surface: rides on a directive the model may under-fire) · **Conditional** (native but gated on an operator precondition).
 
 <!-- END harness-matrix -->
+
+## Contract evidence
+
+The matrix above records what each host can support. The agent-contract eval
+checks whether the complete dispatch path behaves as claimed. Its 12 scenarios
+cover named reviewer and wright runs, generic and inline fallbacks, denial
+paths, stale or malformed results, session orientation, interruption, and
+post-compaction recovery. Every scenario runs once on Claude and once on
+Codex, for 24 isolated cells.
+
+```bash
+python3 scripts/run-agent-contract-evals.py --fake
+```
+
+Fake mode is the only project gate. It uses hermetic host wrappers without a
+network, model, or credential. The matrix verifies transport, isolation,
+fallback, and scoring behavior, but it does not prove behavior on a real Claude
+or Codex host. DevRites records that limit instead of running provider-backed
+sessions. See [the eval guide](../evals/README.md) for the deterministic
+commands.