devrites 3.0.6 → 3.1.0

package/docs/orchestration.md

@@ -1,84 +1,112 @@
 # Orchestration patterns
 
-How DevRites coordinates multiple agents: the patterns it uses, the ones it deliberately avoids,
-and where Claude Code's Agent Teams and worktree isolation fit. The rule that governs this lives in
-[`pack/.claude/skills/devrites-lib/reference/standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md); this doc is the map.
-
-## The model
-
-DevRites separates three roles and never blurs them:
-
-- **Orchestrator**: the active `rite-*` skill (chiefly `/rite-build` and `/rite-seal`). It owns
-  the gates and the `.devrites/` workspace, dispatches the other agents, and is the *single
-  canonical writer* of workspace state.
-- **Reviewers**: fresh-context, **read-only** subagents under `.claude/agents/`. Each gets the
-  workspace path + the diff and returns labelled findings. The generated host hooks observe this
-  boundary by default; set the documented strict-enforcement environment switch when a blocking
-  tool-layer boundary is required. Without strict mode, the agent contract and reconciliation gate
-  remain part of the control, rather than a fail-closed sandbox guarantee.
-- **Executor**: `devrites-slice-wright`, the one **write-capable** agent. It implements a single
-  fully-specified slice in a fresh context and returns code + tests; it never writes the `.devrites/`
-  bookkeeping (the orchestrator does).
-
-Fresh, undirected context is the point: an agent gets the contract, not the author's reasoning, so
-its judgment is independent.
-
-## Endorsed patterns
-
-1. **Direct (no orchestration).** Most phases are one skill doing one job. Don't spawn an agent for
-   work the phase can do inline.
-2. **Parallel read-only fan-out.** At `/rite-seal` the relevant reviewers run *in parallel*, then
-   the orchestrator reconciles them by confidence band and reports genuine disagreement
-   rather than averaging it away.
-3. **Single writer.** Exactly one `devrites-slice-wright` works on each slice. DevRites never
-   fans out writers that share a tree because concurrent writers make conflicting implicit decisions
-   that corrupt a coherent design. The one sanctioned exception is a **forge** slice
-   (`Forge: yes`, flagged by `/rite-vet`). Two or three candidate wrights build it with distinct strategies
-   in **isolated** worktrees, `devrites-forge-judge` scores them, and exactly one winner's diff
-   lands. No tree ever has two authors, so the invariant holds
-   ([`rite-build/reference/forge.md`](../pack/.claude/skills/rite-build/reference/forge.md)).
-4. **Lifecycle as user-driven verbs.** Each verb performs one mutation and stops; chaining is
-   explicit (the user types the next command), so there are no hidden side effects between phases.
-   `/rite-autocomplete` is the one deliberate exception: an opt-in unattended driver.
-5. **Adversarial single-claim check.** `devrites-doubt` spawns a fresh reviewer to try to refute one
-   load-bearing decision, rather than asking the author to re-grade their own work.
-
-## Anti-patterns DevRites avoids
-
-- **A persona that paraphrases another.** Passing one agent's summary to the next is lossy telephone;
-  reviewers read the raw diff and contract, not a digest of the author's reasoning.
-- **Parallel writers.** See single-writer above: two agents editing the same feature concurrently
-  is a merge of conflicting decisions, not a speed-up. (Forge is *not* this: its candidates write in
-  **isolated** worktrees and exactly one lands, so no tree is ever co-authored.)
-- **A router that does the work.** `/rite` is a thin dispatcher. It renders the menu, resolves a
-  verb to a skill, and gets out of the way. It holds no phase logic and produces no artifact itself.
-  (This is the distinction that makes a router fine: the anti-pattern is a "meta-orchestrator"
-  persona that paraphrases and re-decides on every call, not a dispatch table.)
-- **Deep persona trees.** Agents do not call agents that call more agents. The
-  orchestrator dispatches reviewers and the wright one level deep, then
-  reconciles the results itself.
-
-## Agent Teams and worktree isolation
-
-Two Claude Code capabilities sit adjacent to DevRites' model; the stance on each is deliberate.
-
-- **Agent Teams.** DevRites does **not** use Agent Teams to run the lifecycle. The on-disk workspace
-  plus fresh-context read-only fan-out already give independent context per agent without the
-  coordination overhead, and the lifecycle is intentionally single-slice / single-writer. Reach for
-  Use Agent Teams outside that discipline for competing-hypothesis debugging or
-  several genuinely different approaches in parallel. Do not use it to parallelize a DevRites build. The one
-  in-lifecycle form of "compete several approaches" is **forge** (a `Forge: yes` slice), and it is
-  deliberately bounded: vet-gated, K≤3, isolated, winner-takes-all.
-- **Worktree isolation.** A single feature is single-writer on one branch by design, so DevRites
-  does not spawn worktrees for ordinary builds. You can still run DevRites inside a git worktree to
-  drive two features in parallel without them colliding (the `.devrites/ACTIVE` sentinel is
-  per-working-tree, so each carries its own active feature). The one place DevRites spawns worktrees
-  itself is a **forge** slice: each candidate build gets an ephemeral worktree, auto-removed after
-  the winner lands.
+DevRites delegates bounded work to agents while keeping authority in the root
+orchestrator. The governing contract is
+[`standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md);
+this page summarizes that model.
+
+## Authority and topology
+
+- The active public `rite-*` skill is the root. It alone owns human questions,
+  decisions, routing, gates, reconciliation, canonical `.devrites/**` writes,
+  phase changes, and irreversible or external actions.
+- Orchestration is flat depth one: only the root dispatches. Leaves never
+  dispatch leaves.
+- Normally at most three read-only leaves run concurrently against one frozen
+  candidate. The root awaits every required return before mutation.
+- There are **17 named roles**: 16 read-only leaves and one source/test writer,
+  `devrites-slice-wright`.
+
+| Group | Roles |
+|---|---|
+| Bounded work leaves | `devrites-evidence-scout`, `devrites-plan-drafter`, `devrites-proof-runner` |
+| Strategic/claim challenge | `devrites-strategy-reviewer`, `devrites-plan-reviewer`, `devrites-doubt-reviewer` |
+| Review/audit | `devrites-spec-reviewer`, `devrites-code-reviewer`, `devrites-test-analyst`, `devrites-frontend-reviewer`, `devrites-security-auditor`, `devrites-performance-reviewer`, `devrites-devex-reviewer`, `devrites-simplifier-reviewer` |
+| Comparison/history | `devrites-forge-judge`, `devrites-retrospector` |
+| Sole writer | `devrites-slice-wright` |
+
+Every dispatch uses file-backed `agent-packet/v1` and `agent-result/v1`
+envelopes. They record exact inputs, scope, budgets, immutable baseline
+identity, side effects, and terminal status. The root rejects malformed, stale,
+or out-of-scope returns before adding anything to canonical state.
+
+## Dispatch and enforcement
+
+Use the first safe option available:
+
+1. the named project role;
+2. a generic `explorer` or `worker` reading the same generated role contract
+   only when the host still enforces read-only or exact wright scope (or
+   isolated staging);
+3. inline execution, labelled `independence: fallback`, when neither safe
+   fresh-context option is callable.
+
+Inline self-review never silently satisfies an independence gate. Declared
+leaf identity is fail-closed: a missing or crashed `devrites-engine` guard
+blocks the tool call. Leaves never ask the human, write `.devrites/**`, change
+phase, commit, push, install, deploy, migrate live data, or perform irreversible
+actions.
+
+## Single-writer build lifecycle
+
+The root derives normalized project-relative source/test paths and writes them,
+one per line, to `.devrites/work/<slug>/.wright-allowlist`. It is an exact
+authorization manifest and permits no directories, globs, traversal,
+duplicates, or `.devrites/**`. The wright's returned file list records what
+changed but cannot grant access.
+
+Each dispatch follows the retained-baseline sequence:
+
+1. `reconcile snapshot` captures the original dirty-tree baseline, private Git
+   objects, exact allowlist, and canonical-state fingerprint.
+2. The sole wright returns code/tests; the root validates its typed identity and
+   exact changed-file set.
+3. `reconcile check` rejects anything outside the root allowlist.
+4. `test-integrity` and `package-existence` run against the same retained
+   baseline.
+5. After proof and decision checks pass, `reconcile close` retires the private
+   window; only then does the root write canonical records.
+
+On retry, the root may add only an accepted still-in-slice path, then runs
+`reconcile snapshot` again. This refreshes the dispatch boundary while
+preserving the original slice baseline. The same objective root cause has a
+durable three-failure budget in `recovery-attempts.jsonl`; exhaustion records a
+technical blocker with reproduction and dead ends, not a retry-approval
+question.
+
+Build asks the human only for product/scope/policy choices, irreversible risk,
+or human-only access/actions. Tests, types, lint, runtime/browser failures,
+missing coverage, and workflow-tool defects stay agent-owned.
+
+## Isolation
+
+Parallel shared-tree writers are forbidden. A vetted `Forge: yes` slice may
+compare two or three complete strategies only through
+`devrites-engine forge`:
+
+1. `plan` validates the scorecard, pins the physical repository/base, writes
+   the sole `devrites-forge/v1` ownership manifest, and creates derived
+   worktrees outside `.devrites` **before** reconciliation snapshots.
+2. A real host adapter declares `manifest-env-v1`. Each candidate is bound
+   all-or-none to the manifest run, candidate, worktree cwd, branch, live
+   worker ID, PID, and the engine's `forge process-token` value.
+3. `record` and `extract` make every terminal full-tree delta immutable; the
+   read-only judge records one winner; `merge` preflights and lands exactly it.
+4. Normal reconcile, integrity, doubt, and proof gates record verification
+   before `cleanup`. The human `forge-report.md` is written afterward and owns
+   nothing.
+
+An ineligible layout returns a typed serial degradation before side effects.
+After planning, errors preserve manifest-owned state for recovery. Cleanup and
+reap enumerate only manifests, preserve live, dirty, mismatched, or ambiguous
+state, and never delete candidate branches. Ordinary features may also run in
+separate user worktrees so their `ACTIVE` cursors and source trees do not
+collide.
 
 ## See also
 
-- [`pack/.claude/skills/devrites-lib/reference/standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md): the reviewer / executor roster
-  and the when-to-fan-out rules.
-- [`architecture.md`](architecture.md): the full layer model.
-- [`flow.md`](flow.md): phase-by-phase flow and the public/internal namespace.
+- [`architecture.md`](architecture.md): full layer model.
+- [`command-map.md`](command-map.md): every role and phase owner.
+- [`flow.md`](flow.md): lifecycle and state diagrams.
+- [`ADR-0010`](adr/0010-agent-first-fresh-context-orchestration.md): decision
+  record and rejected alternatives.

package/docs/quick-reference.md

@@ -1,12 +1,16 @@
 # DevRites quick reference
 
-DevRites installs via `npx devrites ...`; Claude Code and Codex support are generated project-local artifacts, not plugin-store installs.
+Install DevRites with `npx devrites ...`. The installer generates project-local
+Claude Code and Codex artifacts; plugin stores do not distribute them.
 
 ## Lifecycle
 
-`SPEC -> DEFINE -> VET -> BUILD -> PROVE -> POLISH -> REVIEW -> SEAL -> SHIP`
+<!-- authority:lifecycle:start -->
+`FRAME → SPEC → CLARIFY → TEMPER → DEFINE → PLAN → VET → BUILD → CONVERGE → PROVE → POLISH → REVIEW → SEAL → SHIP → DONE`
+<!-- authority:lifecycle:end -->
 
-Seal decides. Ship mutates git. Build one slice. Autocomplete is opt-in.
+Seal makes the release decision, Ship mutates git, Build handles one slice per
+run, and Autocomplete is opt-in.
 
 ## Standing checklists
 

package/docs/release.md

@@ -10,7 +10,7 @@ version and run these steps:
 1. Waits for the workflow's validation, full shell suite, strict Go-engine checks, Linux cross-compile smoke, and Windows Go tests.
 2. Regenerates `CHANGELOG.md` from the commits.
 3. Syncs the new version into `package.json` and the README status line (`scripts/sync-version.sh`).
-4. Builds `dist/devrites-v<version>.tar.gz` plus its SHA-256 sidecar via `scripts/build-release-tarball.sh`. The extractable bundle used by `curl | bash` includes host-native Claude/Codex artifacts regenerated from `pack/.claude/` into `pack/generated/`.
+4. Builds `dist/devrites-v<version>.tar.gz` plus its SHA-256 sidecar via `scripts/build-release-tarball.sh`. A stdlib Go packager sorts member names and normalizes ownership, modes, timestamps, and the gzip header, so identical source trees produce identical archives. `SOURCE_DATE_EPOCH` selects the canonical timestamp and defaults to `0`. The extractable bundle used by `curl | bash` includes host-native Claude/Codex artifacts regenerated from `pack/.claude/` into `pack/generated/`; symlinks and other non-regular payload entries are rejected.
 5. Cross-compiles five `devrites-engine` release binaries (macOS arm64/amd64, Linux arm64/amd64, Windows amd64) plus a SHA-256 sidecar for each.
 6. Publishes the `devrites` package to npm through `@semantic-release/npm`, using `NPM_TOKEN`. This is what `npx devrites@latest` resolves. `npm pack` regenerates the same `pack/generated/` artifacts during `prepack`; there is no `postpack` cleanup step.
 7. Commits the version bump + changelog as `chore(release): <version> [skip ci]`, creates tag `v<version>`, and publishes a GitHub Release with the tarball, checksum, binaries, and binary checksum sidecars attached.
@@ -18,8 +18,9 @@ version and run these steps:
 Run `npm run release:dry` to see the proposed version and notes without
 publishing. Maintainers can also run `bash scripts/release-check.sh` to build an
 evidence packet for generated artifacts, checksums, package smoke tests,
-install/update/uninstall, pack validation, the behavioral eval schema, and npm
-distribution. This manual preflight is not a hidden semantic-release step.
+install/update/uninstall, reproducible release archives, pack validation, the
+behavioral eval schema, and npm distribution. This manual preflight is not a
+hidden semantic-release step.
 DevRites does not ship through Claude or Codex plugin stores. The release job
 waits for CI, so a broken `main` does not ship.
 

package/docs/skills.md

@@ -1,15 +1,15 @@
-# All 42 skills
+# All 43 skills
 
-The pack contains 42 skills: the `rite` menu, 29 user-invocable `rite-*`
+The pack contains 43 skills: the `rite` menu, 30 user-invocable `rite-*`
 workflow and utility skills, 11 model-invoked `devrites-*` specialists, and the
 internal `devrites-lib` library. `devrites-lib` is not a command. It holds shared
 references and the few explicit script exceptions.
 
-Install DevRites through npm with `npx devrites ...`, not through a Claude or
-Codex plugin store. The installer generates the host-specific artifacts, copies
-Codex skill mirrors to `.agents/skills`, mirrors the rules under
-`.agents/skills/devrites-lib/reference/standards`, installs `.codex/agents`, and
-merges the Codex hooks and guidance.
+Install DevRites through npm with `npx devrites ...`. DevRites is not available
+through a Claude or Codex plugin store. The installer generates host-specific
+artifacts, copies Codex skill mirrors to `.agents/skills`, mirrors the rules
+under `.agents/skills/devrites-lib/reference/standards`, installs
+`.codex/agents`, and merges the Codex hooks and guidance.
 
 The installed `devrites-engine` owns orientation, read-only gates, and state
 changes. Claude Code, Codex, CI, and human operators therefore get the same
@@ -18,17 +18,27 @@ only when needed; small utilities keep their narrower contract local. The npm
 `devrites` shim bootstraps or proxies the engine directly (see
 [`cli.md`](cli.md)).
 
-**Naming convention.** `rite-*` is the workflow/utility namespace (lifecycle phases plus utilities: `rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-customize`, `rite-explain`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, `rite-doctor`, `rite-prototype`, `rite-handoff`, `rite-zoom-out`, `rite-pressure-test`). Some niche utilities are explicit-only (`disable-model-invocation: true`) to keep the always-loaded skill surface small. `devrites-*` is the collision-avoiding specialist/library namespace. Prefix alone does not determine visibility: `user-invocable:` and `disable-model-invocation:` are authoritative, as cataloged in [`command-map.md`](command-map.md).
+## Naming convention
+
+`rite-*` is the namespace for lifecycle and utility commands. Its utilities are
+`rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-customize`,
+`rite-explain`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, `rite-doctor`,
+`rite-prototype`, `rite-handoff`, `rite-zoom-out`, and `rite-pressure-test`.
+Some specialized utilities set `disable-model-invocation: true` and run only
+when explicitly invoked, which keeps the always-loaded skill surface small.
+`devrites-*` is the specialist and library namespace used to avoid collisions.
+The `user-invocable:` and `disable-model-invocation:` fields, not the prefix,
+set visibility and invocation policy. [`command-map.md`](command-map.md)
+catalogs the effective values.
 
 ---
 
 ## Failure-mode section convention
 
-Every skill includes a failure-mode section with the mistakes most likely in
-that phase (following Anthropic's skill-authoring guidance to capture the
-model's actual failure points and grow the list over time). The canonical heading is
-**`## Gotchas`**. Existing skills express the same intent under equivalent headings, all
-of which satisfy the convention:
+Every skill documents the mistakes most likely in that phase. This follows
+Anthropic's guidance to record observed model failures and extend the list over
+time. New skills use the heading `## Gotchas`. Existing skills use the
+equivalent headings below, which also satisfy the convention:
 
 - **Lifecycle skills** → a `> **Mid-flight discipline.**` blockquote pointing at
   `reference/anti-patterns.md` (rite-spec, -temper, -define, -vet, -build, -prove,
@@ -40,11 +50,11 @@ of which satisfy the convention:
   (frontend-craft), the numbered rule list (prototype), and `## Gotchas`
   (api-interface, rite, status).
 
-New or materially edited skills SHOULD use `## Gotchas` for two or three traps
-the model reaches for in that phase (specialized from the rationalizations in
-`pack/.claude/skills/devrites-lib/reference/standards/anti-patterns.md`), not a
-restatement of the positive steps. A mechanical rename of the equivalents above to a
-single `## Gotchas` heading is a possible future normalization; the content already holds.
+New or materially edited skills SHOULD use `## Gotchas` for two or three
+phase-specific traps drawn from
+`pack/.claude/skills/devrites-lib/reference/standards/anti-patterns.md`. Do not
+repeat the positive workflow steps there. Existing headings do not need a
+mechanical rename because their content already meets the convention.
 
 ## Command invocation
 
@@ -55,11 +65,11 @@ Every public `rite-<verb>` skill has four equivalent forms: Claude `/rite <verb>
 Workspace-operating `rite-*` skills render `devrites-engine progress` first, then a compact
 completion reply from
 [`reply-contract.md`](../pack/.claude/skills/devrites-lib/reference/reply-contract.md).
-The progress command owns the deterministic header, slice meter, and flow ribbon; the
-chat reply only summarizes status: `Done`, `Changed`, `Evidence`, `Open`, one `Next`
-command, `Record`, and `↻ Hygiene`. Detailed reports stay in durable workspace
-artifacts such as `spec.md`, `plan.md`, `evidence.md`, `review.md`, `seal.md`, and
-`ship.md`.
+The progress command owns the deterministic header, slice meter, and flow
+ribbon. The chat reply summarizes only `Done`, `Changed`, `Evidence`, `Open`,
+one `Next` command, `Record`, and `↻ Hygiene`. Detailed reports stay in durable
+workspace artifacts such as `spec.md`, `plan.md`, `evidence.md`, `review.md`,
+`seal.md`, and `ship.md`.
 
 Typed stop states are standardized too: `Awaiting human`, `Stopped`, `NO-GO`, `GO`,
 and `Shipped`. Utility commands that do not operate on an active workspace declare a
@@ -98,6 +108,12 @@ blocks obvious multi-command `Next:` wording.
 | [`devrites-interview`](../pack/.claude/skills/devrites-interview/SKILL.md) | One-question-at-a-time interview until ~95% confidence. | The ask is underspecified, or user says "interview me" / "grill me". |
 | [`rite-pressure-test`](../pack/.claude/skills/rite-pressure-test/SKILL.md) | Structured divergent → convergent thinking; rough concept → buildable proposal. | The idea itself needs exploration before specifying; users say "ideate", "stress-test my plan", "I have a vague idea". |
 
+### Clarify: close decision coverage before technical planning *(required, adaptive)*
+
+| Skill | What It Does | Use When |
+|---|---|---|
+| [`rite-clarify`](../pack/.claude/skills/rite-clarify/SKILL.md) | Reuses `devrites-interview` to enumerate topology, search facts, audit assumptions, close human-owned decisions, and write a semantic, input-digest-bound `CLEAR` verdict. Later-phase retrofits persist and restore their return cursor when the contract is unchanged. | After every full spec; also retrofits an active workspace missing decision coverage. Complete/small specs take the zero-question path. |
+
 ### Temper: strategic review before planning *(optional; mandatory in `/rite-autocomplete`)*
 
 | Skill | What It Does | Use When |
@@ -108,24 +124,24 @@ blocks obvious multi-command `Next:` wording.
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite-define`](../pack/.claude/skills/rite-define/SKILL.md) | Approved spec → `plan.md` + vertical task slices + `state.md`. | `spec.md` exists and is approved. |
+| [`rite-define`](../pack/.claude/skills/rite-define/SKILL.md) | Approved, clarified spec → architecture alternatives/contracts + `plan.md` + vertical task slices + `state.md`. | `spec.md` is approved and `decision-coverage.md` is `CLEAR`. |
 | [`rite-plan`](../pack/.claude/skills/rite-plan/SKILL.md) | Decompose / reslice / repair an active plan after drift; `revise` updates planning artifacts only. | Spec Drift Guard fires, or you need to repair/revise an existing plan. |
-| [`rite-converge`](../pack/.claude/skills/rite-converge/SKILL.md) | Assess live code vs `spec`/`plan`/`tasks` intent; append the remaining unbuilt work as new traceable slices (append-only, no git). | Resuming a half-built or stalled feature, or after `/rite-adopt` when code drifted from the derived spec. |
+| [`rite-converge`](../pack/.claude/skills/rite-converge/SKILL.md) | Assess live code vs clarified intent; append remaining work as traceable slices, invalidate the prior READY verdict, and return the changed plan through `/rite-vet`. | Resuming a half-built or stalled feature, or after `/rite-adopt` when code drifted from the derived spec. |
 
 ### Vet: lock in the engineering plan before building
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite-vet`](../pack/.claude/skills/rite-vet/SKILL.md) | Engineering review of `plan.md` + `tasks.md`: scope challenge (reuse / minimum-diff / complexity smell), then architecture / plan code-quality / test-coverage design / performance through senior-engineer lenses, every finding confidence-banded with a quote-the-source verification gate. Maps failure modes + parallel lanes, hardens the plan, writes the build-readable `test-plan.md`; acceptance-changing deltas fold back via the Spec Drift Guard. Adversarial fresh-context loop via [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) on the full pass; optional `--cross-model` second opinion. | **Every defined plan, before build.** Depth scales with the stakes: a light pass on a simple, reversible plan; the full pass on a big or risky one (migration · auth · public API · data model · multi-slice · >8 files · new dependency). Never skipped; always in `/rite-autocomplete`. |
+| [`rite-vet`](../pack/.claude/skills/rite-vet/SKILL.md) | Engineering review of `plan.md` + `tasks.md`: scope challenge (reuse / minimum-diff / complexity smell), then architecture / plan code-quality / test-coverage design / performance through senior-engineer lenses, every finding confidence-banded with a quote-the-source verification gate. Maps failure modes + parallel lanes, hardens the plan, and writes `test-plan.md` plus a semantic, input-digest-bound `READY` verdict; acceptance-changing deltas fold back via the Spec Drift Guard. Adversarial fresh-context loop via [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) on the full pass; optional `--cross-model` second opinion. | **Every defined plan, before build.** Depth scales with the stakes: a light pass on a simple, reversible plan; the full pass on a big or risky one (migration · auth · public API · data model · multi-slice · >8 files · new dependency). Never skipped; always in `/rite-autocomplete`. |
 
 ### Build: one verified slice at a time
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite-build`](../pack/.claude/skills/rite-build/SKILL.md) | Orchestrates **exactly one** vertical slice: pre-flight gates, then dispatches a fresh-context [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) for the build core, then doubts / gates / records with evidence. A slice `/rite-vet` flagged `Forge: yes` competes K=2 to 3 isolated candidate builds judged by [`devrites-forge-judge`](../pack/.claude/agents/devrites-forge-judge.md), landing one winner (`forge-report.md`). | A plan exists and the next slice is ready. |
+| [`rite-build`](../pack/.claude/skills/rite-build/SKILL.md) | Orchestrates **exactly one** vertical slice through the sole wright. The root writes an exact `.wright-allowlist`, retains the original baseline through snapshot → reconcile check → test/package integrity → close, and refreshes only the dispatch boundary on retries. Objective failures use bounded agent-owned recovery; only genuine product/risk/access decisions become human gates. A `Forge: yes` slice still isolates candidates and lands one judged winner. | A plan exists and fresh digest-bound `CLEAR` and `READY` gates plus `test-plan.md` pass. |
 | [`devrites-source-driven`](../pack/.claude/skills/devrites-source-driven/SKILL.md) | Consult official docs / source before relying on framework behavior; record the source. | API, config, or framework behavior is assumed rather than known. |
 | [`devrites-api-interface`](../pack/.claude/skills/devrites-api-interface/SKILL.md) | Design stable API / interface contracts: REST/GraphQL, module boundaries, type contracts, FE/BE split. | A slice crosses a boundary or defines a public interface. |
-| [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | Reproduce → ranked hypotheses → instrument → fix in scope → regression-test. Stops guess-and-retry. | Tests, builds, or runtime checks fail. |
+| [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | Reproduce → ranked hypotheses → instrument → fix in scope → regression-test. A fingerprinted ledger preserves the three-failure budget across agents and sessions. | Tests, builds, or runtime checks fail. |
 | [`devrites-refresh-indexes`](../pack/.claude/skills/devrites-refresh-indexes/SKILL.md) | Internal synchronous refresh for optional code-intelligence indexes. The Stop hook runs automatically; `/rite-doctor --reindex` owns the user route. | Structural lookup disagrees with live code, or doctor requests a refresh. |
 
 ### Prove: collect evidence, including browser evidence
@@ -147,9 +163,9 @@ blocks obvious multi-command `Next:` wording.
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite-review`](../pack/.claude/skills/rite-review/SKILL.md) | Multi-axis feature-scoped review. Parallel **Spec axis** (`devrites-spec-reviewer`) + **Standards axis** (`devrites-code-reviewer`) sub-agents; severity-labeled findings. | Polish done; ready for a final pass. |
+| [`rite-review`](../pack/.claude/skills/rite-review/SKILL.md) | Multi-axis feature-scoped review. Parallel fresh-context **Spec axis** (`devrites-spec-reviewer`) + **Standards axis** (`devrites-code-reviewer`) agents; severity-labeled findings. | Polish done; ready for a final pass. |
 | [`devrites-doubt`](../pack/.claude/skills/devrites-doubt/SKILL.md) | In-flight adversarial review of risky decisions: branching logic, boundaries, data/auth/API changes, migrations. | About to stand a "this is safe / scales / matches spec" claim. |
-| [`devrites-audit`](../pack/.claude/skills/devrites-audit/SKILL.md) | Read-only audit dispatch: picks the right reviewer subagent on the requested axis (`security` / `perf` / `simplify`). Single-axis only; multi-axis parallel fan-out lives inline in `/rite-seal` (see the [shared dispatch contract](../pack/.claude/skills/devrites-lib/reference/parallel-dispatch.md)). | Polish Phase 1 (`simplify`); review involves user input / auth / data / external integrations / secrets / permissions (`security`); performance is relevant or regression risk visible (`perf`). |
+| [`devrites-audit`](../pack/.claude/skills/devrites-audit/SKILL.md) | Read-only audit dispatch: picks the right fresh-context reviewer on the requested axis (`security` / `perf` / `simplify`). Single-axis only; multi-axis parallel fan-out lives inline in `/rite-seal` (see the [shared dispatch contract](../pack/.claude/skills/devrites-lib/reference/parallel-dispatch.md)). | Polish Phase 1 (`simplify`); review involves user input / auth / data / external integrations / secrets / permissions (`security`); performance is relevant or regression risk visible (`perf`). |
 
 ### Seal: GO / NO-GO decision
 
@@ -167,7 +183,7 @@ blocks obvious multi-command `Next:` wording.
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | Runs the whole lifecycle unattended (spec → … → seal → ship), choosing the best option at each soft gate and recording the rationale in `decisions.md`. A vague prompt triggers an up-front `devrites-interview`; after that it runs without per-phase iteration, pausing only on hard irreversible-risk / blocking / escalating gates, an open validating gate, NO-GO, or budget exhaustion. Default stops at the final type-`GO`; `--ship` (alias `--yolo`) auto-confirms it. | "Autocomplete", "do the whole thing", "run the full cycle", "one-shot this feature". |
+| [`rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | Runs the whole lifecycle unattended (spec → clarify → … → seal → ship), choosing the recommended option at each soft gate and recording the rationale in `decisions.md`. A vague prompt triggers one up-front spec/clarify window; after decision coverage is CLEAR it runs without per-phase iteration, pausing only for genuine product/scope/policy decisions, irreversible risk, human-only access/actions, NO-GO, or budget exhaustion. Objective red checks use bounded technical recovery. Default stops at the final type-`GO`; `--ship` (alias `--yolo`) auto-confirms it. | "Autocomplete", "do the whole thing", "run the full cycle", "one-shot this feature". |
 | [`rite-zoom-out`](../pack/.claude/skills/rite-zoom-out/SKILL.md) | Map the modules, callers, callees, and decisions in an unfamiliar area using the project's domain glossary. | Explicit-only: `/rite-zoom-out` / `/rite zoom-out`. |
 | [`rite-prototype`](../pack/.claude/skills/rite-prototype/SKILL.md) | Throwaway code answering ONE design question: logic harness OR 2 to 4 UI variations on one route. | Explicit-only: `/rite-prototype` / `/rite prototype`. |
 | [`rite-handoff`](../pack/.claude/skills/rite-handoff/SKILL.md) | Compact chat session → handoff doc. References existing `.devrites/work/<slug>/` artifacts by path. | Explicit-only: `/rite-handoff` / `/rite handoff`. |
@@ -185,12 +201,17 @@ blocks obvious multi-command `Next:` wording.
 
 ---
 
-## Review agents: fresh-context reviewers
+## Fresh-context agents
 
-Spawned by `/rite-review`, `/rite-seal` (post-build), `/rite-temper` (pre-plan), `/rite-vet` (pre-build), and `/rite-build` (the forge judge, on a `Forge: yes` slice) for independent judgment. Read-only; given only the artifact + rubric, never the author's reasoning. **13 read-only** in all (12 reviewers + the cross-feature `devrites-retrospector`); plus the one **write-capable** `devrites-slice-wright` below.
+DevRites ships 17 roles at depth one: 16 read-only leaves and one source/test
+writer. Three read-only roles handle bounded work while the root keeps
+authority:
 
 | Agent | Purpose |
 |---|---|
+| [`devrites-evidence-scout`](../pack/.claude/agents/devrites-evidence-scout.md) | Build a bounded evidence dossier for spec, clarify, converge, or cited external facts. |
+| [`devrites-plan-drafter`](../pack/.claude/agents/devrites-plan-drafter.md) | Draft a planning candidate for define or plan repair; the root decides and writes artifacts. |
+| [`devrites-proof-runner`](../pack/.claude/agents/devrites-proof-runner.md) | Run non-destructive proof commands against a read-only tree and return a proof report. |
 | [`devrites-strategy-reviewer`](../pack/.claude/agents/devrites-strategy-reviewer.md) | **Pre-plan** spec-vs-rubric strategic review (ambition / scope / premise / pre-mortem / YAGNI / testability / irreversibility / cross-cutting / convention). Used by `/rite-temper`, not the seal fan-out. |
 | [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) | **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. Used by `/rite-vet`, not the seal fan-out. |
 | [`devrites-forge-judge`](../pack/.claude/agents/devrites-forge-judge.md) | **Build-time** comparative judge of two or three candidate builds of one slice (acceptance / test strength / principle fit / simplicity / reuse / anti-slop). Used by `/rite-build` on a `Forge: yes` slice; picks the single winner to land and names grafts. |
@@ -216,21 +237,26 @@ Seal fan-out diagram: [`flow.md` § /rite-seal fan-out](flow.md#4-rite-seal-fan-
 
 ## Executor agent: fresh-context writer
 
-The system has one write-capable agent, paired with the read-only reviewers
-above. `/rite-build` dispatches it in a clean context with only the slice
-contract.
+The system has one write-capable agent. `/rite-build` dispatches it in a clean
+context with only the slice contract; all other agents are read-only.
 
 | Agent | Purpose |
 |---|---|
-| [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) | Turn ONE slice contract into the smallest complete, idiomatic, proven implementation: orient → TDD → verify, anti-AI-slop, feature scope only. Writes code + tests; returns a structured artifact for the orchestrator to doubt, gate, and record. Writes no `.devrites/` bookkeeping; single-threaded (one per slice). |
+| [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) | Turn ONE exact allowlisted slice into the smallest complete, idiomatic, proven implementation. Writes code + tests only; returns a typed artifact for the root to reconcile, gate, and record. Writes no `.devrites/` bookkeeping; single-threaded per tree. |
 
 Dispatch contract + return shape + fallback: [`rite-build/reference/wright-dispatch.md`](../pack/.claude/skills/rite-build/reference/wright-dispatch.md).
+The shared topology, named → generic → labelled-inline fallback, and fail-closed
+identity rules live in [`standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md).
 
 ---
 
 ## `/rite-polish` orchestrator
 
-`/rite-polish` always runs code polish; it detects UI scope from the diff and runs UI normalize + polish only when needed. Each half lives as a progressive-disclosure reference inside the skill (`reference/code.md`, `reference/ui.md`) so the orchestrator body stays small and each phase loads only when its trigger fires.
+`/rite-polish` always runs code polish. It detects UI scope from the diff and
+runs UI normalization and polish only when needed. The two parts live in
+`reference/code.md` and `reference/ui.md` as progressive-disclosure references,
+so the orchestrator body stays small and loads each reference only when its
+trigger fires.
 
 ```mermaid
 flowchart LR