devrites 3.0.7 → 3.2.0

package/pack/generated/codex/skills/devrites-interview/SKILL.md

@@ -10,33 +10,36 @@ This is the Codex mirror of a DevRites skill. In Codex:
 
 - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
 - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
-- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
-- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
-- Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
+- **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
+- For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
+- If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
+- Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
+- If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
+- Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
+- Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
 - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
 
 
 # devrites-interview: extract intent
 
-Close the gap between what the user said and what they want, at the cheapest moment:
-before a plan, spec, or code exists.
+Resolve the difference between the request and the user's intent before writing a
+spec, plan, or code.
 
 ## Protocol
-- **State a confidence number.** Open with your one-line hypothesis of what the user wants and an
-  explicit **0-100%** confidence in it. The number forces honesty, if you wrote 85% but can't
-  predict how the user reacts to your next three questions, the number is wrong. Below **~70%**,
-  append the single thing still unresolved so the user can close the gap directly.
+- **State a confidence number.** Open with a one-line hypothesis of what the user wants and an
+  explicit **0-100%** confidence. Check the number against the next three questions you would ask:
+  if you cannot predict the user's answers, lower it. Below **~70%**, append the single unresolved
+  point so the user can answer it directly.
 - **One question per turn.** Multiple questions get one answered and the rest ignored.
-- **Attach your best guess** to every question, with the reason:
+- **Attach your best guess** and its reason to every question:
   > "I'm assuming export is CSV only (covers the stated use case). Right, or also XLSX?"
-  This turns an open question into a cheap correction and exposes your model so the user
-  can fix the premise.
+  The user can then correct a concrete premise instead of answering an open-ended question.
 - **Highest-value question first:** order by how much the answer changes the build. A
   question that moves the data model or acceptance criteria beats a cosmetic one.
-- **Impact-priority + bounded blocking.** Order unknowns **scope > security/privacy > UX >
-  technical**, and cap **blocking** questions at **≤3** per pass: ask the few that gate
-  the spec; **default-and-record** the rest in `assumptions.md` (best-guess + why). A reversible
-  detail never earns a blocking question.
+- **Prioritize impact and limit blockers.** Order unknowns **scope > security/privacy > UX >
+  technical**. Ask at most **3 blocking questions** per pass, choosing only those that gate
+  the spec. Record the rest in `assumptions.md` with the best guess and reason. A reversible
+  detail is never blocking.
 - **Structured options** when the space is enumerable: present them as the standard ranked
   **option set** (`standards/afk-hitl.md` → "Option set"): recommended **first**, labelled
   `(Recommended)`, each with a dimension-tagged rationale (`logic · infra · business ·
@@ -49,38 +52,34 @@ before a plan, spec, or code exists.
   ```
 
 ## Stop condition
-Stop **opening new questions** when **any** holds: don't interrogate past the point of value.
-(Stopping the interview ≠ deciding for the user: a material call still goes back as a ranked
-option set: confidence lowers the question's *cost* to a one-pick confirm, not its *owner*.)
-- **Confidence: the predict-three test.** The 95% bar is checkable, not a feeling: *can you
-  predict the user's reaction to the next three questions you would ask?* If yes, you're done
-  extracting. If several rounds pass and you still can't predict, something foundational is
-  missing: step back and name it, don't grind out more questions.
+Stop **opening new questions** when any condition below holds. This does not transfer a
+material decision to the agent. Present that decision as a ranked option set even when
+high confidence makes it a one-pick confirmation.
+- **Confidence: the predict-three test.** At 95%, you should be able to predict the user's
+  reaction to the next three questions. If so, stop. If several rounds pass without that
+  confidence, name the missing premise instead of asking more narrow questions.
 - **Convergence:** the last 2-3 answers only rubber-stamped your guesses and didn't
   move the spec.
 - **Soft cap:** after ~8 material questions, proceed with your best-guess answers logged
   in `assumptions.md` rather than asking more (hard-stop sooner if the ask is small).
 
-Depth on the few that matter, not breadth for its own sake. If answers stop converging:
-you keep circling one area without progress: **reframe once** (below) instead of asking
-another question.
+Ask fewer, deeper questions. If answers stop converging and the discussion circles one
+area, **reframe once** instead of asking another version of the same question.
 
 ## Want vs. should-want
-People answer with what they think they *should* want (the buzzword, the best practice, the
-convention) not what they want. Watch for tells: abstract virtues ("scalable", "clean",
-"modern"), deferral to what's conventional, an answer that could be pasted into any project. When
-you hear one, ask the unlock question, *"if you didn't have to justify this to anyone, what would
-you want?"*. It often does more than the previous five questions. Extract the real want,
-then record it; don't design to the performed one.
+Users sometimes name the convention or best practice they think they should want instead
+of their actual preference. Signals include abstract virtues ("scalable", "clean",
+"modern"), deference to convention, or an answer that fits any project. Ask: *"if you
+didn't have to justify this to anyone, what would you want?"* Record that answer rather
+than designing to the generic one.
 
 ## What counts as a yes
-Approval is an **explicit** yes, and several common replies aren't one:
-- *"Whatever you think is best"* / *"you decide"*: **delegation, not approval.** Re-ask with two
-  concrete options so the user chooses on the substance, not the deferral.
-- *"Sounds good"* / *"sure, let's go"*: a polite exit; probe once that it's real agreement, not
-  fatigue, on anything material.
-- **Silence:** not consent. Half of misalignment is silent disagreement about what *won't* be
-  built. Make the "out of scope" line explicit and get a yes on it too.
+Approval requires an **explicit** yes. Treat these replies differently:
+- *"Whatever you think is best"* / *"you decide"*: **delegation, not approval.** Offer two
+  concrete options so the user chooses the substance.
+- *"Sounds good"* / *"sure, let's go"*: confirm once for a material decision rather than
+  treating a polite exit as approval.
+- **Silence:** not consent. State what is out of scope and get explicit approval for it.
 
 ## Don't ask
 - Things the codebase answers (read it first).
@@ -88,29 +87,35 @@ Approval is an **explicit** yes, and several common replies aren't one:
 - Everything at once "to be thorough."
 
 ## When the ask is vague: map the decision tree first
-For a one-line or fuzzy ask (`"design a contact page"`), don't fire isolated questions.
-First sketch the **decision tree** (the branches the answer splits into) and resolve
-each branch **depth-first** with the protocol above. Domain branches per area:
+For a short or vague request (`"design a contact page"`), do not ask isolated questions.
+Sketch the **decision tree** first, then resolve each branch **depth-first** with the
+protocol above. Domain branches per area:
 `rite-spec/reference/interview-patterns.md`.
 
 ## Reframe (once, when stuck)
-If the interview isn't converging, spend **one** turn challenging the premise rather than
-refining it: *"is a form even the right answer here, or a mailto / booking link?"* A good
-reframe collapses several open branches. Use it sparingly, then resume the protocol.
+If the interview is not converging, use **one** turn to challenge the premise:
+*"is a form even the right answer here, or a mailto / booking link?"* Then resume the
+protocol with the revised premise.
 
 ## /clarify mode: coverage scan of an existing spec
-When invoked to clarify a written spec (not extract intent from scratch), scan it against the fixed
-taxonomy and mark each **Clear / Partial / Missing**: Functional scope · Data model · Interaction
-(API / UI states) · Non-functional (auth / latency / scale / compliance) · Edge cases (empty /
-boundary / invalid / concurrent / failure). Then ask **≤5 prioritized questions** (impact order
-above), targeting Missing before Partial, one per turn with a best-guess attached. **Integrate each
-answer into the right spec section** as it lands (not just a Q&A log) and append a dated
-**`## Clarifications`** block to `spec.md` (Q + resolution) for durable provenance. Re-run the scan
-after answers; stop when every area is Clear or explicitly deferred, then re-score the affected
+When clarifying a written spec rather than extracting intent from scratch, first enumerate
+its actors, journeys/components, states, data boundaries, interfaces/integrations, and
+operational/proof surfaces. Scan every material surface against the caller's fixed taxonomy and mark
+**Clear / Partial / Missing** with evidence. Ask **≤5 prioritized decision packets per scan**,
+targeting Missing before Partial, one per turn with a best-guess attached. A packet may close
+several cells only when they share one owner and trade-off.
+
+**Integrate each answer into the relevant spec section** immediately. A Q&A log alone is
+insufficient.
+Append a dated **`## Clarifications`** block to `spec.md` with the question and resolution.
+Re-run the scan after answers. The general question caps control cognitive load; they never turn
+a material blocker into a silent assumption. Continue another scan while human-owned blockers
+remain, and stop only when every row is clear, agent-owned, not applicable, or explicitly
+deferred with a nonblocking reason, owner, and validation gate. Then re-score the affected
 `checklists/<domain>.md`.
 
 ## Output
-A short summary the caller can use: objective in one sentence, confirmed decisions,
-still-open (non-blocking) items, recommended next step. If a workspace is active, write
+A short summary for the caller: objective in one sentence, confirmed decisions,
+open non-blocking items, and the recommended next step. If a workspace is active, write
 Q&A to `questions.md`, confirmed calls to `decisions.md`, standing guesses to
 `assumptions.md`. If not, just return the summary: don't create a workspace.

package/pack/generated/codex/skills/devrites-lib/SKILL.md

@@ -11,21 +11,25 @@ This is the Codex mirror of a DevRites skill. In Codex:
 
 - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
 - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
-- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
-- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
-- Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
+- **Invocation and dispatch are different:** invoke means run a skill in this context; dispatch means start a fresh agent with `spawn_agent`, await it, and reconcile its result. Never describe inline skill work as a dispatch.
+- For every DevRites specialist or writer dispatch, first call `spawn_agent` with the named `devrites-<role>` custom role. The matching project contract is `.codex/agents/devrites-<role>.toml`.
+- If `spawn_agent` is callable but a named read-only role is unavailable, use generic `explorer` only when the host proves that run has a runtime-enforced read-only sandbox. Tell it to read `.codex/agents/devrites-<role>.toml`, follow its `developer_instructions`, and execute the unchanged packet. A missing read-only custom role is not evidence that spawning is unavailable.
+- Never dispatch generic `worker` for `devrites-slice-wright` unless the host proves that worker run carries exact DevRites identity and the same `.wright-allowlist` enforcement as the named role. Codex reports a generic run as `agent_type=worker`, so the generated global hooks cannot prove that binding. Reject that unsafe rung and use the documented labelled inline wright path with `.reconcile-inline` plus the full reconcile gate.
+- If the host cannot prove the generic explorer is runtime read-only, reject that rung too. Only when no spawn primitive exists or a higher-priority policy rejects a safe spawn may the root run the documented discipline inline. Label it `independence: fallback`, never call it independent, and apply every fallback risk gate. An unbound generic wright or unconfined generic explorer is such a safety rejection, not evidence that no agents exist.
+- Wait for every required fresh-context dispatch before reconciling or advancing. A backgrounded or lost result is incomplete.
+- Codex project hooks are installed in `.codex/hooks.json`; declared-leaf hooks are scoped inside `.codex/agents/devrites-*.toml`. Review and trust them with `/hooks` before relying on hook enforcement.
 - When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
 
 
 # devrites-lib: internal shared helpers (not a command)
 
-This is **not** a skill you run. It is DevRites' manifest for shared references
-and control-plane operations. Skills call `devrites-engine <command>` from any
-workspace; no pack script path is required.
+Do **not** run this skill directly. It lists shared references and control-plane
+operations. Skills call `devrites-engine <command>` from any workspace without a pack
+script path.
 
 ## Operations
 
-These are selected `devrites-engine` contracts; `devrites-engine help` is exhaustive.
+These are selected `devrites-engine` contracts. Run `devrites-engine help` for the full list.
 
 **Read-only: orient / gate (never mutate the workspace):**
 
@@ -34,13 +38,13 @@ These are selected `devrites-engine` contracts; `devrites-engine help` is exhaus
   open-question tally by gate. Run first (step 0) by every workspace-operating
   `rite-*` skill so the model orients deterministically instead of re-deriving
   state from raw Markdown.
-- `devrites-engine progress`: progress footer; the mirror of `devrites-engine preamble` (which runs
-  first). Run **last** (output step) by every lifecycle `rite-*` skill to render (from
+- `devrites-engine progress`: progress footer and counterpart to the initial
+  `devrites-engine preamble`. Run it **last** in every lifecycle `rite-*` skill to render from
   `state.md`, with zero model drift) the `── rite-<phase> ──` header rule, the **slice
   meter** (`Slice 3/5  ██████░░░░  <last-built> ✓`, or `Slices 5/5  ██████████  ✅ ALL
   BUILT` at completion), and the **flow ribbon** (`spec ✓ define ✓ build ◉ … ship ○`).
   The meter answers "how many slices left"; the `✅ ALL BUILT` marker answers "is the
-  build done". The skill prints its own what-was-done / next-step / hygiene lines beneath
+  build done". The skill prints its own result, next step, and hygiene lines beneath
   it. Read-only; silent (exit 0) when there is no active workspace. Not for the workspace-less
   utilities (`$rite-prototype`, `$rite-zoom-out`, `$rite-pressure-test`, `$rite-handoff`,
   the `$rite` menu). They have no phase/slice state to render.
@@ -55,7 +59,10 @@ These are selected `devrites-engine` contracts; `devrites-engine help` is exhaus
 - `devrites-engine build-readiness`: build-readiness gate. Exits non-zero on `$rite-build`'s
   step-0 stop conditions so they hold by exit code, not by prose the model must
   remember: `2` no `Plan approved` (→ `$rite-define`), `3` `awaiting_human`
-  (→ `$rite-resolve`), `4` `blocked` (→ `$rite-plan`), `5` no workspace, `0` ready.
+  (→ `$rite-resolve`), `4` `blocked` (→ `$rite-plan`), `5` no workspace
+  (→ `$rite-spec`), `6` decision coverage missing/not CLEAR (→ `$rite-clarify`),
+  `7` implementation readiness missing/not READY (→ `$rite-vet`), `8` older or unknown
+  semantic readiness contract (→ `$rite-upgrade`), `0` ready.
 - `devrites-engine evidence-fresh`: evidence-freshness gate for `$rite-seal`. Exits `3`
   when any file in `touched-files.md` is newer than `evidence.md` /
   `browser-evidence.md` (stale proof = NO-GO until re-proven), `0` when fresh.
@@ -76,7 +83,7 @@ These are selected `devrites-engine` contracts; `devrites-engine help` is exhaus
 - `devrites-engine resolve`: backs the `$rite-resolve` contract (answer / drop / batch).
 - `devrites-engine close-out`: archive the workspace + clear `ACTIVE` on `$rite-ship`.
 
-### Canonical footer snippet
+### Canonical footer
 
 Every lifecycle `rite-*` skill prints this as the **first lines of its output**, then its
 own compact fact lines below per [`reply-contract.md`](reference/reply-contract.md):

package/pack/generated/codex/skills/devrites-lib/reference/intent-map.md

@@ -4,9 +4,11 @@ This is an explicit reference, not a session-start autoload. Load it when the us
 
 | User intent | Route | Notes |
 |---|---|---|
-| New feature / vague product idea | `$rite-spec` (Codex: `$rite-spec`) | Investigate first; do not plan from vibes. |
+| New feature / vague product idea | `$rite-spec` (Codex: `$rite-spec`) | Investigate before planning. |
+| Written spec still has unknowns / missing decision coverage | `$rite-clarify` | Required before planning; topology scan, zero-question fast path when clear. |
 | Existing codebase / resume reality | `$rite-adopt` or `$rite-converge` | Adopt derives intent from code; converge appends remaining slices. |
-| Review plan before code | `$rite-vet` | Every defined plan; depth scales to stakes. |
+| Active workspace created under older DevRites rules | `$rite-upgrade` | Explicit-only semantic reconciliation; preserves completed work and history. `devrites-engine migrate` handles structure only. |
+| Review plan before code | `$rite-vet` | Every defined plan; depth scales to stakes and emits the implementation-readiness verdict. |
 | Small safe fix | `$rite-quick` | Escalates on auth, migration, public API, destructive, ambiguous, or multi-slice work. |
 | Prove UI/runtime | `$rite-prove` plus `devrites-browser-proof` | Capture real evidence. |
 | Stuck / unfamiliar area | `$rite-zoom-out` | Map structure before changing code. |

package/pack/generated/codex/skills/devrites-lib/reference/parallel-dispatch.md

@@ -1,165 +1,110 @@
 # Parallel review dispatch
 
-How `$rite-review` and `$rite-seal` fan out the fresh-context review subagents under
-`.codex/agents/`. The **single source** for the dispatch + reconciliation contract: loaded on
-demand by the calling skill (each points here); not a skill itself.
+This file defines reviewer rosters for `$rite-review` and `$rite-seal`. The shared
+packet, result, capability ladder, concurrency limit, retry, and reconciliation rules live in
+[`standards/agents.md`](standards/agents.md); do not restate them here.
 
-The seal/review fan-out **roster** is the seven post-build reviewers in the table below. This
-file is the single source of which reviewer fires when. The seal and the multi-axis review need
-them running **at the same time**, on the same workspace + diff, so the verdicts don't
-contaminate each other. Every other agent under `.codex/agents/` fires from its own phase, not
-here: the roster table below names them under **Not in this fan-out** so the set is unambiguous.
+All reviewers read the same **immutable candidate**, but no more than three run
+concurrently. For a larger panel, use awaited batches of at most three; after resource
+or process errors, reduce the batch or run serially. A batch boundary does not permit a
+write.
 
-Pattern: delegate to specialized agents with isolated context, brief each one precisely, run
-them concurrently, reconcile on return.
+## Roster
 
-## The roster: every reviewer the fan-out accounts for
+`$rite-seal` accounts for all seven roles. `$rite-review` runs the first two.
+Conditional triggers use the listed signals.
 
-These seven are the **roster**. `$rite-seal` accounts for **all** of them: the always-on three
-plus each conditional, either dispatched or skip-recorded; `$rite-review` runs the two always-on
-axes. Each trigger is a *checkable signal*, not a judgement call, so a conditional reviewer is
-either fired or consciously skipped: never silently dropped.
-
-| Reviewer | Fires | Trigger: the checkable signal |
+| Reviewer | Fires | Trigger |
 |---|---|---|
-| `devrites-spec-reviewer` | always | `$rite-review` Spec axis; `$rite-seal` (carry review's verdict forward only if the diff is unchanged) |
-| `devrites-code-reviewer` | always | `$rite-review` Code-review axis; `$rite-seal` (carry forward only if the diff is unchanged) |
-| `devrites-test-analyst` | always | at `$rite-seal` |
-| `devrites-frontend-reviewer` | conditional | the diff touches a UI file: component / template / stylesheet, per the project's UI paths |
-| `devrites-security-auditor` | conditional | the diff touches input handling, auth / authz, data storage or access, an external integration, or a secret |
-| `devrites-performance-reviewer` | conditional | `spec.md` states a perf budget, **OR** the diff adds a query / a loop over a growing set / hot-path or render work |
-| `devrites-devex-reviewer` | conditional | the diff changes a developer-facing surface: public API, CLI, SDK/library export, webhook, config/env contract, error message, or getting-started path |
-
-### Hit-rate gating: consult before dispatching conditionals
-
-Before dispatching, run `devrites-engine reviewer-stats report`. It grades each reviewer from the
-cross-feature dispatch ledger (`.devrites/reviewer-stats.jsonl`):
-
-- `run` / `run (always-on)` / `run (insurance — never gated)`: dispatch per the trigger table above.
-- `gate-candidate`: this **conditional** reviewer produced zero surviving findings in its last 10+
-  dispatches on this project. Skip it as a *recorded* skip:
-  `devrites-engine footprint log <slug> skip devrites-<x>-reviewer` with the reason
-  `gated: zero surviving findings in <N> dispatches`. The roster gate stays satisfied: a gated
-  skip is a conscious skip.
-
-The verdict is engine-owned and deterministic; never gate by your own judgement of a reviewer's
-past usefulness. Two hard bounds: the always-on axes (`spec`, `code-review`, `test-analyst`) and
-the insurance reviewers (`security-auditor`, `doubt-reviewer`) are **never** gated: the engine
-never grades them `gate-candidate`, and a caller must not skip them on hit-rate grounds. The user
-can override gating for one run by asking for a full panel (`--full`): then dispatch every
-triggered reviewer regardless of verdict.
-
-After reconciliation, close the loop: record each **dispatched** reviewer's outcome so the
-ledger stays live:
+| `devrites-spec-reviewer` | always | review Spec axis; seal may carry it forward only on the identical candidate |
+| `devrites-code-reviewer` | always | review Code-review axis; seal may carry it forward only on the identical candidate |
+| `devrites-test-analyst` | always at seal | completed feature |
+| `devrites-frontend-reviewer` | conditional | diff touches a component, template, stylesheet, story, route, screen, or design token |
+| `devrites-security-auditor` | conditional | input, auth/authz, data access/storage, external integration, permission, dependency, or secret |
+| `devrites-performance-reviewer` | conditional | spec has a performance budget, or diff adds a query, growing-set loop, render/hot-path work, or material payload |
+| `devrites-devex-reviewer` | conditional | public API, CLI, SDK/export, webhook, config/env, error message, docs, or getting-started path |
 
-```bash
-devrites-engine reviewer-stats record devrites-<x>-reviewer <surviving Critical+Important count> <slug>
-```
+Not in this roster: `devrites-simplifier-reviewer` (polish), `devrites-doubt-reviewer`
+(doubt), `devrites-strategy-reviewer` (temper), `devrites-plan-reviewer` (vet),
+`devrites-forge-judge` (build), and `devrites-retrospector` (ship).
 
-Surviving means it stood after reconciliation and dismissals: a finding the caller dismissed as a
-false positive does not count. Record `0` honestly; dry streaks are the signal.
+## Hit-rate gating
 
-**Not in this fan-out** (named so the roster is unambiguous): `devrites-simplifier-reviewer` fires
-at `$rite-polish` Phase 1 (via `devrites-audit simplify`) and `devrites-doubt-reviewer` fires from
-`devrites-doubt` when a decision is stood up: neither is a seal reviewer, so neither is part of
-the seal accounting. `devrites-strategy-reviewer` (pre-plan, `$rite-temper`), `devrites-plan-reviewer`
-(pre-build, `$rite-vet`), `devrites-forge-judge` (`$rite-build` forge), and `devrites-retrospector`
-(`$rite-ship` close) are single-agent, phase-locked gates. They fire iff their phase runs, not here.
+Before conditionals, run:
 
-One entity, one name: the `devrites-code-reviewer`'s axis is the **Code-review axis** everywhere
-(at both `$rite-review` and `$rite-seal`): don't rename it per caller.
+```bash
+devrites-engine reviewer-stats report
+```
 
-## Dispatch shape
+- `run`, `run (always-on)`, or `run (insurance — never gated)`: apply the roster.
+- `gate-candidate`: a conditional produced zero surviving findings in its last 10+
+  dispatches. Record a skip with `gated: zero surviving findings in <N> dispatches`.
+- `--full`: dispatch every triggered reviewer despite gating.
 
-For each chosen subagent, the caller uses the harness's subagent primitive (the `Task` tool on
-Claude Code, `spawn_agent` (with the matching `.codex/agents/devrites-*.toml` custom agent) on
-Codex) with this prompt shape:
+Always-on reviewers and insurance reviewers (security and doubt) are never hit-rate
+gated. After reconciliation, record each dispatched reviewer's surviving
+Critical+Important count:
 
-```
-Audit the active DevRites feature.
-
-Workspace: .devrites/work/<slug>/
-Read (yourself, fresh context):
-  - spec.md  (+ acceptance criteria)
-  - touched-files.md
-  - the git diff
-  - <any axis-specific files: decisions.md, evidence.md, references/...>
-
-Before judging the diff, derive the expected behaviour from the spec
-yourself, then compare it against what the code does. Anchor every finding
-to file:line plus the spec criterion or command output that proves it —
-an unanchored finding is a Suggestion at most. The order or length of the
-diff is not evidence.
-
-Apply your documented discipline. Return labeled findings (Critical /
-Important / Suggestion / Nit / FYI) using your documented output format,
-ONE FINDING PER LINE, cite file:line.
-
-Feature scope only. No edits. Do not summarize or re-rank — the caller
-reconciles.
+```bash
+devrites-engine reviewer-stats record devrites-<x>-reviewer <count> <slug>
 ```
 
-Rules:
-
-- **One Task call per subagent, awaited in the same turn.** Send them in a single message with multiple `Task` invocations so the runtime dispatches concurrently. Never background/detach reviewers in `$rite-autocomplete` or AFK; there is no event loop that guarantees a later result is reconciled.
-- **No cross-pollination.** Each subagent gets only its narrow brief and the workspace path. Do not pass another subagent's findings into a sibling's prompt, that recreates the masking problem.
-- **No author context.** Do not include the caller's analysis or the user's framing of the change; the point is a fresh, adversarial read.
-- **Never coach a reviewer.** No "do not flag X", "treat Y as at most Minor", or "the plan
-  chose this" in a dispatch prompt: pre-judging findings is how a known defect sails through.
-  A plan-mandated quirk still gets reported; the caller (or the human) grades it, not the prompt.
-- **Feature scope only.** Each subagent must stay inside `touched-files.md` + the diff.
-- **Can't-verify is a verdict, not a pass.** A reviewer that cannot verify a spec requirement
-  from the diff + its allowed reads returns it as a `CANNOT-VERIFY: <requirement> — <why>` line.
-  The caller resolves each one itself before the gate; an unresolved CANNOT-VERIFY on an
-  acceptance-mapped requirement stands as a gap, not a pass.
+## Reviewer packet
+
+Create `agent-packet/v1` per `standards/agents.md`. In addition to the common fields:
+
+```yaml
+objective: Audit the active feature on <axis>; derive expected behavior independently.
+inputs:
+  - path: .devrites/work/<slug>/spec.md
+    purpose: acceptance contract
+  - path: .devrites/work/<slug>/touched-files.md
+    purpose: feature boundary
+  - path: <scratch_root>/candidate.diff
+    purpose: reviewed candidate
+scope:
+  in: [<axis-specific workspace paths>, <touched source/test paths>]
+  out: [author reasoning, sibling findings, unrelated repository debt]
+  allowed_repo_writes: []
+```
 
-## Account for every reviewer: the roster gate
+Tell the role to apply its documented discipline and return `payload.type:
+review-findings`, one finding per line, labeled Critical / Important / Suggestion /
+Nit / FYI and anchored to `file:line` plus the spec criterion or observed command.
+The exact result `CANNOT-VERIFY: <requirement> — <why>` is never a pass.
 
-The fan-out is done only when **every roster reviewer is accounted for**: dispatched, or
-consciously skipped with a one-line reason. A conditional reviewer that genuinely does not apply
-(no UI in the diff → `frontend-reviewer`) is a *recorded* skip, not a silent no-op. That record
-is the difference between "reviewed" and "declared done after firing three of seven": the silent
-skip is exactly how a needed reviewer never runs.
+Dispatch rules:
 
-Record each decision to the footprint as you make it (via `devrites-engine footprint`, as in `$rite-build`). Log the reviewer's
-**exact agent name**: the `.codex/agents/` stem, e.g. `devrites-frontend-reviewer`; the `roster`
-gate matches on it (stripping the `devrites-` prefix), so a freehand label like `frontend` or
-`Spec axis` will not match and the gate reads that reviewer as unaccounted:
+- Fresh-context dispatch through the capability ladder; one packet per reviewer.
+- No author context, sibling findings, severity coaching, or plan justification.
+- Feature scope is `touched-files.md` plus the frozen diff.
+- Await every required batch before any write or verdict. Never background/detach.
 
-- dispatched → `devrites-engine footprint log <slug> reviewer devrites-<x>-reviewer`  (the dispatch record itself)
-- skipped → `devrites-engine footprint log <slug> skip devrites-<x>-reviewer`  # e.g. `skip devrites-frontend-reviewer`: no UI in the diff
+## Account for every reviewer
 
-Then, **before the verdict**, prove the roster is complete:
+Log exact agent names as decisions are made:
 
 ```bash
-devrites-engine footprint roster <slug>   # rc=0 complete · rc=3 a reviewer was neither dispatched nor skipped · rc=1 an always-on reviewer was skipped
+devrites-engine footprint log <slug> reviewer devrites-<x>-reviewer
+devrites-engine footprint log <slug> skip devrites-<x>-reviewer
+devrites-engine footprint roster <slug>
 ```
 
-`rc=3` is the silent omission the gate exists to catch: resolve it by dispatching the reviewer or
-recording why it does not apply: never by proceeding with it unaccounted. `rc=1` means an
-always-on axis (Spec / Code-review) was skip-recorded; that is legitimate only as a carry-forward
-of `$rite-review`'s verdict on an **unchanged** diff: confirm that, don't wave it through.
+`roster` rc=3 means an unaccounted reviewer: dispatch or record why it does not apply.
+rc=1 means an always-on skip; this is valid only for an unchanged-candidate carry-forward
+or the explicit independence fallback in
+[`../../rite-seal/reference/risk-and-rollback.md`](../../rite-seal/reference/risk-and-rollback.md).
 
 ## Reconciliation
 
-When the subagents return:
-
-1. **Quote verbatim.** Place each subagent's findings under its own `## <axis>` heading in `review.md` / `seal.md`. Do not merge, re-rank, or summarize. `devrites-code-reviewer` runs its **full** documented discipline (tests-first, correctness, readability, architecture, maintainability, standards); the inline lead **reconciles** the returned reports. It does not re-run those same axes itself.
-2. **Surface contradictions explicitly.** "Spec axis says complete, Code-review axis says untestable" is a finding, not noise. The caller decides at the gate.
-3. **Severity is the gate, not a score.** Sum the labels (`Critical / Important / Suggestion / Nit / FYI`) and apply the caller's gate (`$rite-seal` blocks on `Critical == 0`; `$rite-review` reports counts).
-4. **One scale.** All subagents use the same five-label scale (Critical / Important / Suggestion / Nit / FYI). Reject any subagent output that invents its own. **Exception:** `devrites-simplifier-reviewer` deliberately emits only Suggestion / Nit / FYI (it is non-blocking by design), that is a valid subset of the scale, not an invented one; do not reject it during reconciliation.
-5. **Consensus roll-up (after the verbatim per-axis record).** Keep every axis's findings verbatim under its `## <axis>` heading (above), then add one deduped roll-up the gate reads: where **≥2 axes flag the same `file:line`**, raise it to the top and mark it *consensus*: independent corroboration raises confidence. A lone low-confidence finding with no `file:line` or evidence anchor drops out of the roll-up (it stays in its per-axis section). The roll-up reduces noise without hiding any axis: the verbatim sections are the audit trail; the roll-up is the actionable summary the gate acts on.
-
-## Model tier
-
-Every reviewer in this fan-out runs at **ceiling tier**: the orchestrator's own model, inherited
-by declaring no `model:` in the agent definition (see
-[`model-tiers.md`](model-tiers.md)). Adversarial review is exactly where a cheaper model costs the
-most: a missed Critical is far more expensive than the tokens saved. Do not downgrade a reviewer to
-save cost. Extraction-tier savings belong to scouts (archive-search, footprint), not to the panel.
-
-## Fallback
-
-If the harness has **no subagent primitive at all** (neither Claude's `Task` nor Codex's
-`spawn_agent`: an absent tool on one harness while the other's equivalent exists does NOT
-qualify), the caller runs the relevant subagent discipline **inline** in its own context and flags the result as a fallback (not an independent review). The seal weighs the fallback differently: see [`../../rite-seal/reference/risk-and-rollback.md`](../../rite-seal/reference/risk-and-rollback.md). This is the [`model-tiers.md`](model-tiers.md) degradation rule applied to the review panel: no subagent primitive → run inline under the same discipline and budget.
+1. Preserve each valid report verbatim under `## <axis>` in `review.md`/`seal.md`.
+2. Surface contradictions explicitly; the root decides them.
+3. Keep the shared five-label scale. The simplifier's Suggestion/Nit/FYI subset is valid.
+4. Resolve every `CANNOT-VERIFY` before the gate or retain it as a gap.
+5. Add a deduped roll-up only after the verbatim record. Mark matching `file:line`
+   findings from two or more axes as consensus; do not hide lone findings.
+6. Apply the caller's gate; do not invent a composite score.
+
+Every panel reviewer runs at the ceiling or inherited tier. If the named role is
+unavailable, use the universal ladder. Record an inline fallback as non-independent
+under the seal risk rule, never as a fresh-context pass.

package/pack/generated/codex/skills/devrites-lib/reference/reply-contract.md

@@ -9,7 +9,14 @@ Before the final reply, persist the phase event, then render the deterministic
 progress chrome:
 
 ```bash
-devrites-engine timeline log completed --skill <skill> --slug "$(cat .devrites/ACTIVE 2>/dev/null)" --outcome "<ok|blocked|no-go|go>" --decision "<one-line result>"
+devrites-engine timeline log run-finished \
+  --slug "$(cat .devrites/ACTIVE 2>/dev/null)" \
+  --outcome "<passed|blocked>" \
+  --execution-mode named \
+  --guard-strength n/a \
+  --reason-id "<stable DRV-* reason for the result>" \
+  --host "<claude|codex>" \
+  --evidence "<project-relative primary artifact>"
 devrites-engine budget
 devrites-engine progress
 ```