devrites 3.0.7 → 3.1.0

package/pack/generated/codex/skills/rite-clarify/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: rite-clarify
+description: Run the topology-first decision-coverage scan after rite-spec and before strategy or architecture. Audit actors, journeys, states, data, integrations, operations, proof, assumptions, and must-NOT boundaries; close Partial/Missing rows and emit decision-coverage.md CLEAR. Use for missing/stale coverage or a missed pre-build product decision.
+argument-hint: "[feature-slug]"
+user-invocable: true
+---
+
+## Codex compatibility
+
+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.
+- **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.
+
+
+# $rite-clarify: resolve product decisions
+
+Run this required pass between spec and strategy. If the spec covers every material
+decision, ask no questions. Otherwise stay until each material decision has an
+owner. This phase settles behavior and constraints; `$rite-define` settles
+implementation.
+
+Reuse [`devrites-interview`](../devrites-interview/SKILL.md) in `/clarify mode`. Write
+`decision-coverage.md` as scan evidence, not an interview transcript.
+
+## Rules consulted
+
+Read `devrites-lib/reference/standards/core.md`, its `afk-hitl.md`, and
+[`reference/decision-coverage.md`](reference/decision-coverage.md). Fresh evidence
+dispatch uses
+[`agents.md`](../devrites-lib/reference/standards/agents.md).
+
+## Rules
+
+- Search code/docs/contracts first. Facts and reversible implementation/test choices
+  are agent-owned; ask only about product, scope, policy, irreversible risk, or human-only access.
+- Enumerate the full topology before details so no sibling surface is omitted.
+- Ask one coherent human-owned decision packet at a time. One packet may close several rows
+  only when owner and trade-off match; never ask permission for routine repair/retry.
+- One scan may cap at five packets for cognitive load, but readiness has no question cap:
+  re-scan until clear.
+- Material assumptions carry evidence, confidence, owner, validation, and consequence.
+
+## Workflow
+
+0. **Orient.** Run `devrites-engine preamble` and `snapshot`. Require `spec.md` plus
+   `Spec gate: passed`; otherwise STOP → `$rite-spec`. For a later-phase retrofit, run
+   `devrites-engine clarify-return enter <slug>` **before any pause**; this persists the
+   return cursor and enters `Phase: clarify`.
+1. **Enumerate topology** from the spec, references, live code, and prior decisions: actors,
+   journeys/components, states, data lifecycles, interfaces/integrations, operations, and
+   proof. Add omitted surfaces to the spec. **Completion:** every material surface appears
+   once with a source or canonical spec reference.
+2. **Scan coverage** with `devrites-interview /clarify mode` and the reference taxonomy.
+   Mark each surface Clear/Partial/Missing with evidence; include must-NOT and out-of-scope
+   behavior. Unmentioned never means not applicable. **Completion:** the matrix records every
+   surface with evidence.
+3. **Eliminate factual unknowns** through code intelligence, project/decision docs,
+   manifests/lockfiles, and authoritative external docs. Dispatch independent topology/fact
+   questions to `devrites-evidence-scout` (maximum three at once), await the cited dossiers,
+   and reconcile them in the root context. The root folds accepted facts into `spec.md` or
+   `assumptions.md`; the scout never asks or writes. **Completion:** each factual unknown is
+   source-backed or reclassified as an owned decision/assumption.
+4. **Audit assumptions and decisions.** Record the fields required above. For high-cost or
+    hard-to-reverse product/constraint choices, present two or three viable options, recommendation
+   first. A genuinely undecidable behavior may take one bounded `$rite-prototype` detour.
+5. **Close human-owned gaps** using the shared option-set contract: one highest-impact packet
+   per turn. Persist answers immediately in `spec.md` plus `decisions.md`/`questions.md`.
+   AFK remains within its gate ceiling; irreversible risk and principle exceptions pause.
+6. **Re-scan after edits** until each material row is `closed`, `agent-owned`,
+   `not-applicable`, or justified `deferred-nonblocking` with owner and validation gate.
+   Partial/Missing, an unowned material assumption, or an open blocking/escalating question
+   means `NEEDS CLARIFICATION`.
+7. **Write the verdict.** Update `decision-coverage.md`; success requires exactly
+   `Decision coverage: CLEAR`. Normal state is `Phase: clarify`, `Next step: $rite-temper`.
+   A contract-neutral retrofit runs `devrites-engine clarify-return restore <slug>`; a
+   changed behavior/acceptance contract leaves the return cursor unconsumed, writes
+   `drift.md`, and routes `$rite-plan repair`. Normal first-pass flow sets `$rite-temper`.
+8. **STOP.** Run `devrites-engine progress`; hand off only on `CLEAR`.
+
+## Output
+
+Run `devrites-engine progress`, then use the shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)):
+
+```text
+Done: decision coverage closed for <slug>; <n> topology surfaces scanned.
+Changed: decision-coverage.md, spec.md, decisions.md, assumptions.md, questions.md
+Evidence: Decision coverage: CLEAR; human packets <n>; agent-owned facts <n>
+Open: none blocking; deferred-nonblocking <n>
+Next: $rite-temper
+Record: .devrites/work/<slug>/decision-coverage.md
+↻ Hygiene: /clear before $rite-temper
+```
+
+If not clear, name the exact rows and next genuine decision packet. An objective spec defect
+or factual search task never routes through `$rite-resolve`.

package/pack/generated/codex/skills/rite-clarify/reference/decision-coverage.md

@@ -0,0 +1,59 @@
+# Decision coverage contract
+
+`decision-coverage.md` proves a topology-first scan ran; reference canonical IDs instead of
+duplicating their prose.
+
+## Coverage taxonomy
+
+For each material surface scan: outcome/scope/must-NOT; behavior, permissions, and all states;
+domain/data lifecycle/invariants/order/concurrency; interfaces/integrations and failure
+contracts; security/privacy/compliance/accessibility/performance/reliability/compatibility;
+configuration/observability/support/rollout/rollback; and executable acceptance proof,
+environment, credentials/approvals, and evidence limits.
+
+## Status vocabulary
+
+- `closed`: the canonical artifact records the decision.
+- `agent-owned`: a reversible technical choice is explicitly delegated to define/vet.
+- `not-applicable`: evidence shows the dimension does not apply.
+- `deferred-nonblocking`: pre-code evidence is impossible or the item is an explicit
+  non-goal; owner and validation gate are named.
+
+`Partial`, `Missing`, open, unknown, or ownerless rows never produce `CLEAR`.
+
+## Artifact shape
+
+```markdown
+# Decision coverage
+
+Decision coverage: <CLEAR | NEEDS CLARIFICATION>
+Coverage inputs SHA-256: <exact value from `devrites-engine readiness-digest coverage <slug>`>
+
+## Topology
+| Surface | Kind | Related IDs | Evidence |
+| --- | --- | --- | --- |
+
+## Coverage matrix
+| Surface | Dimension | Status | Canonical reference | Owner / validation gate | Consequence if wrong |
+| --- | --- | --- | --- | --- | --- |
+
+## Assumption audit
+| Assumption | Evidence | Confidence | Owner | Validation | Consequence if wrong |
+| --- | --- | --- | --- | --- | --- |
+
+## Residual uncertainty
+| Item | Why nonblocking | Owner | Validation gate |
+| --- | --- | --- | --- |
+
+## Readiness verdict
+No Partial, Missing, unowned material assumption, or unresolved blocking/escalating
+question remains.
+```
+
+Combine rows only when one decision and owner genuinely close them.
+
+Run the digest command only after `brief.md`, `spec.md`, `decisions.md`,
+`assumptions.md`, and `questions.md` are final for this clarification pass, then
+copy its complete field line verbatim. The build gate recomputes the digest and
+rejects stale coverage. Any open blocking, validating, or escalating question
+also prevents `CLEAR`.

package/pack/generated/codex/skills/rite-converge/SKILL.md

@@ -11,26 +11,29 @@ 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.
 
 
-# $rite-converge: make the code and the intent converge
+# $rite-converge: compare live code with intent
 
-Read `spec.md` + `plan.md` + `tasks.md` as the **sole source of intent** (with
+Read `spec.md`, `plan.md`, and `tasks.md` as the **sole source of intent** (with
 `.devrites/principles.md` as governing constraints), assess what the **live codebase**
 implements, and **append every unmet piece as a new traceable `SLICE-###`** at the
-bottom of `tasks.md` so `$rite-build` can finish it. The recovery bridge for work that fell
-out of sync with its plan: a half-built feature picked up cold, a `$rite-adopt`'d codebase
-that drifted from its derived spec, or a build that stalled mid-slice. **Read the active
+bottom of `tasks.md` so `$rite-build` can finish it. Use this for a resumed half-built
+feature, an adopted codebase that drifted from its derived spec, or a build that stalled
+mid-slice. **Read the active
 workspace first**; if there's no `spec.md`/`plan.md`/`tasks.md`, tell the user which
 prerequisite skill to run.
 
-> **Not a diff tool.** `$rite-converge` assesses the **present state** of the code against
-> intent: no git, no branch comparison, no history. "What does this codebase do *now* vs
-> what the artifacts asked for", not "what changed since commit X". For a change-scoped
+> **This is not a diff tool.** `$rite-converge` compares current code with intent. It
+> does not use git history or compare branches. For a change-scoped
 > review use `$rite-review`; to prove a finished feature use `$rite-prove`.
 
 ## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
@@ -53,16 +56,20 @@ Pull on demand:
 - **Clean means byte-for-byte unchanged.** When the code already satisfies everything, leave
   `tasks.md` untouched (no empty convergence header) and report a clean result. Recommend
   `$rite-prove`.
-- **Intent is the artifacts, not your memory.** The spec/plan/tasks (+ principles) are the
+- **Use artifacts as intent.** The spec, plan, tasks, and principles are the
   contract. If assessing reveals the *spec* is wrong (the code is right and the requirement is
   stale), that's **Spec Drift**: stop and route it through the Spec Drift Guard
   (`rite-build/reference/spec-drift-guard.md`) + a recorded decision; never paper over a spec
-  bug by appending a task that "fixes" the code to a wrong requirement.
+  bug by appending a task that changes correct code to match a wrong requirement.
 - **Partial is not done.** Code that exists but is untested, half-wired, or covers only the
   happy path is an unmet gap: enqueue the remainder, don't round it up.
 - **Principles are non-negotiable.** A live violation of a declared invariant with no recorded
   exception is the top-severity gap, walked first. Absent/empty principles file → none declared
   → skip the check gracefully, never block for its absence.
+- **Scout observes; root classifies and writes.** Use
+  [`agents.md`](../devrites-lib/reference/standards/agents.md). The evidence scout returns
+  live-code citations only; the controlling chat owns built/partial/absent calls and append-only
+  workspace changes.
 
 ## Workflow
 0. **Read `.agents/skills/devrites-lib/reference/standards/core.md`** first (the always-on
@@ -71,14 +78,16 @@ Pull on demand:
    any is missing, **STOP** and name the prerequisite (`$rite-spec` for a missing spec,
    `$rite-define` for a missing plan/tasks, `$rite-adopt` to onboard existing code). Do not
    produce partial output.
+   Require `decision-coverage.md` with `Decision coverage: CLEAR`; otherwise STOP →
+   `$rite-clarify`.
 2. **Load intent:** [`reference/convergence-assessment.md`](reference/convergence-assessment.md).
    From `spec.md`: buildable `AC-###` / `### Requirement:` scenarios (skip `## Success metrics`);
    from `plan.md`: architecture decisions + named touch-points (files/components the plan says
    get built); from `tasks.md`: existing slices + their `Satisfies:`; from
    `.devrites/principles.md`: the invariants.
    **Completion:** every buildable criterion, touch-point, slice output, and principle is in the assessment inventory.
-3. **Run the mechanical backbone**, then read the code. `devrites-engine analyze` gives coverage +
-   consistency; `devrites-engine coverage` gives the AC→slice→proven matrix. They catch *unmapped*
+3. **Run the mechanical checks**, then read the code. `devrites-engine analyze` gives coverage
+   and consistency; `devrites-engine coverage` gives the AC→slice→proven matrix. They catch *unmapped*
    criteria; they do **not** see whether mapped code is built and correct, for that,
    read the live code (code-intelligence index per `tooling.md`).
    ```bash
@@ -90,7 +99,9 @@ Pull on demand:
    [`reference/convergence-assessment.md`](reference/convergence-assessment.md)): every
    acceptance criterion / scenario, every plan touch-point, and every existing slice's stated
    Produces. A principle violated in the current code is its own top-severity gap.
-   **Completion:** every inventory unit is classified once with live-code evidence.
+   Dispatch up to three independent inventory partitions to `devrites-evidence-scout` on the
+   same frozen candidate, await their dossiers, then reconcile the cited facts in the root
+   context. **Completion:** every inventory unit is classified once with live-code evidence.
 5. **Enqueue the remainder as new slices.** For each *partial* or *absent* unit, append a
    `## SLICE-###` (continue the numbering after the highest existing id) in the `rite-define`
    slice grammar, each with a `Satisfies:` line tracing to the AC/REQ it closes and a
@@ -99,10 +110,14 @@ Pull on demand:
    **Completion:** every partial/absent unit has one traceable appended slice, or the file is byte-for-byte unchanged.
 6. **Write append-only + bookkeeping.** Append the slice batch to `tasks.md` (nothing else in
    that file changes); refresh `traceability.md` (`devrites-engine coverage` → new rows for the
-   appended slices); update `state.md` (`Phase: converge`, `Next step: $rite-build`; or, when
-   nothing was unmet, `Next step: $rite-prove`). Append `decisions.md` for any material call.
+   appended slices). Appending a slice changes the plan input, so invalidate the prior vet:
+   update `state.md` to `Phase: plan`, `Next step: $rite-vet`, and set an existing
+   `eng-review.md` field to `Implementation readiness: NEEDS REPLAN`. When nothing was unmet,
+   leave the plan/vet verdict untouched and set `Next step: $rite-prove`. Append
+   `decisions.md` for any material call.
 7. **STOP.** Report units assessed, built / partial / absent counts, slices appended, and any
-   principle violation found; recommend `$rite-build` (or `$rite-prove` if the code already
+   principle violation found; recommend `$rite-vet` when slices were appended (or
+   `$rite-prove` if the code already
    converged).
 
 ## Appended slice format
@@ -117,11 +132,9 @@ Convergence: 2026-07-07      # marks this as a convergence-appended slice, not a
 <all remaining canonical slice fields>
 ```
 
-> **Mid-flight discipline.** When tempted to rewrite an existing slice instead of appending, to
-> edit the code directly "while you're in there", to mark a happy-path-only implementation as
-> built, or to enqueue a task that bends the code to a spec you suspect is wrong: see
-> [`reference/anti-patterns.md`](reference/anti-patterns.md). Load it the moment you reach for
-> the excuse.
+> **Mid-flight discipline.** Do not rewrite an existing slice, edit source, mark a
+> happy-path-only implementation as built, or add work for a spec you suspect is wrong.
+> See [`reference/anti-patterns.md`](reference/anti-patterns.md).
 
 ## Output
 
@@ -130,14 +143,15 @@ Convergence: 2026-07-07      # marks this as a convergence-appended slice, not a
 Default success shape:
 ```
 Done: convergence assessed for <slug>; <n> slices appended.
-Changed: tasks.md <appended|unchanged>, traceability.md, state.md
+Changed: tasks.md <appended|unchanged>, traceability.md, state.md, eng-review.md <invalidated|unchanged>
 Evidence: units <built>/<total> built · <partial> partial · <absent> absent · principle violations 0
 Open: none
-Next: $rite-build
+Next: $rite-vet
 Record: .devrites/work/<slug>/tasks.md
-↻ Hygiene: /clear before $rite-build
+↻ Hygiene: /clear before $rite-vet
 ```
 When nothing was unmet, render the same green form with `Next: $rite-prove`.
 If spec drift or another blocker remains, use the shared `Stopped / blocked` form
 and route `Fix:` to `$rite-plan`; do not recommend `$rite-build`.
-**DO NOT write application code, rewrite existing slices, or edit spec.md/plan.md here**: convergence assesses and enqueues; `$rite-build` implements.
+**DO NOT write application code, rewrite existing slices, or edit spec.md/plan.md here.**
+This phase assesses and enqueues; `$rite-build` implements.

package/pack/generated/codex/skills/rite-customize/SKILL.md

@@ -12,9 +12,13 @@ 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.
 
 

package/pack/generated/codex/skills/rite-define/SKILL.md

@@ -11,19 +11,23 @@ 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.
 
 
 # $rite-define: plan from the spec
 
-Read the active feature's `spec.md` and turn it into a buildable workspace: feature
-architecture, approach, a dependency-ordered set of **vertical slices**, traceability, and
-the state cursor. The spec is the WHAT/WHY (from `$rite-spec`); this is the HOW. Splitting
-spec, architecture, plan, tasks, and traceability keeps each file small and phase-owned.
-**No code here.**
+Turn the active feature's `spec.md` into a buildable workspace with architecture, an
+implementation approach, dependency-ordered **vertical slices**, traceability, and a
+state cursor. The spec defines what and why; this phase defines how. Keep spec,
+architecture, plan, tasks, and traceability in their phase-owned files. **Do not write
+code here.**
 
 ## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
 Pull these via `Read` when shaping the plan:
@@ -36,14 +40,16 @@ Pull these via `Read` when shaping the plan:
 - **Requires a readied spec.** Read the active workspace first; if `.devrites/ACTIVE` is empty,
   the workspace has no `spec.md`, its readiness gate hasn't passed, or any spec-quality
   `checklists/<domain>.md` has an open CRITICAL → **STOP** and tell the user to run
-  `$rite-spec <feature>` first. **DO NOT plan from a missing or unreadied spec.**
-- Prefer existing conventions; ask before adding a dependency or a second design system.
-- **Author section by section, not in one dump.** Write `architecture.md` / `plan.md` one section
-  at a time and pause after each; a section resting on an open design choice or a shaky estimate can
-  be deepened right there with a technique from
+  `$rite-spec <feature>` first. A missing or non-`CLEAR` `decision-coverage.md` routes to
+  `$rite-clarify`. **DO NOT plan from a missing, unreadied, or unclarified spec.**
+- Apply `afk-hitl.md` decision ownership. Prefer conventions; source-check new dependencies or
+  design systems, asking only about licensing/cost/security or explicit policy.
+- **Author one section at a time.** Write `architecture.md` and `plan.md` section by
+  section, pausing after each. For an open design choice or uncertain estimate, use a
+  relevant technique from
   [`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) (Tournament for two viable
   designs, Delphi for the estimate) before it hardens into slices.
-- **Slice count is derived, never dictated.** The number of slices falls out of the work.
+- **Derive the slice count from the work.**
   One per independently-shippable increment, sized by `slicing.md`, every acceptance
   criterion mapped to ≥1 slice. A user-named count is a hint at most: slice logically and,
   if your honest count differs, present it and why. Never pad or compress to hit a figure.
@@ -52,6 +58,9 @@ Pull these via `Read` when shaping the plan:
   crosses many files, don't fake vertical slices. Add a compatibility/adapter slice, migrate
   small green batches, then remove the old path. If a batch cannot stay green, use an
   integration branch plus a final verify slice.
+- **Root writes; drafter proposes.** Use the file-backed fresh-context contract in
+  [`agents.md`](../devrites-lib/reference/standards/agents.md). The root owns architecture
+  decisions, human questions, approval, and every canonical artifact write.
 
 ## Workflow
 0. **Read `.agents/skills/devrites-lib/reference/standards/core.md`:** the always-on operating rules and anti-rationalizations.
@@ -65,30 +74,46 @@ Pull these via `Read` when shaping the plan:
    ```
    If there is no active workspace, no `spec.md`, `spec-skeleton` blocks, or its readiness gate hasn't passed →
    **STOP** and tell the user to run `$rite-spec <feature>` first.
+   If `decision-coverage.md` is absent or does not say `Decision coverage: CLEAR`,
+   **STOP** → `$rite-clarify`.
 1. **Read the spec:** `spec.md` (objective, requirements, acceptance, **placement**,
    design references, gaps/decisions), plus `references.md`, `decisions.md`,
-   `assumptions.md`, **`strategy.md` if present** (the scope mode, deferred / out-of-scope
+   `assumptions.md`, `decision-coverage.md`, **`strategy.md` if present** (the scope mode, deferred / out-of-scope
    register, and pre-mortem risks from `$rite-temper`: cut slices to mitigate the top risks
    and respect the IN/OUT line; map coverage against the **hardened** spec), and
    **`design-brief.md` if the feature touches UI** (the UX/UI contract `$rite-spec` shaped:
    its key states, interaction model, and proof targets drive how UI slices are cut). If a blocking
-   `[NEEDS CLARIFICATION]` remains, stop → `$rite-spec`.
-2. **Decide the architecture + approach** (the HOW the spec deliberately omitted): write
+   `[NEEDS CLARIFICATION]` remains, stop → `$rite-clarify`.
+1a. **Draft from fresh context.** Freeze the planning inputs and dispatch
+   `devrites-plan-drafter` in `define` mode for one atomic candidate bundle:
+   `architecture.md`, `plan.md`, `tasks.md`, and `traceability.md`, including proof mapping.
+   Await and validate `agent-result/v1`. The drafter does not write or ask; any human-owned
+   choice returns to this root context.
+2. **Reconcile and decide the architecture + approach** (the HOW the spec deliberately
+   omitted). Validate the candidate against live seams and the following rules; the root writes
+   accepted content at step 6. Shape
    `architecture.md` for owning layer, boundaries, integration points, data/API/events,
    dependencies, risks, and affected areas; write only the build strategy in `plan.md`.
    Use a
    code-intelligence index if available (see
    `.agents/skills/devrites-lib/reference/standards/tooling.md`) for structure/impact; for the current API or behaviour of
    an external library/framework the architecture will rely on, consult context7 if available.
-   Record significant options in `decisions.md` as `DEC-###` ADR entries.
-   **Deep-modules check**, while sketching the major modules, look for opportunities
+   Record significant options as `DEC-###`. For high-cost/hard-to-reverse boundaries, data
+   models, public contracts, or dependencies, compare ≥2 viable approaches by drivers,
+   trade-offs, and consequences. Specify cross-boundary interfaces for independent work:
+   invariants, I/O, ordering/idempotency, errors, versioning, config, and relevant budgets.
+   **Deep-module check:** while sketching the major modules, look for opportunities
    to extract a **deep module**: a small, stable interface that hides a meaningful chunk
-   of behavior, and is therefore independently testable. A *shallow* module (interface
-   nearly as complex as its implementation) earns nothing; either deepen it or delete
-   it. Where a slice will produce a deep module, confirm with the user which deep
-   modules they want unit-tested in isolation (this informs the slice's "Tests to
-   write/run" field).
-3. **Slice into vertical tasks:** each delivers one observable capability end-to-end and
+   of behavior and is independently testable. A *shallow* module whose interface is
+   nearly as complex as its implementation adds no value; deepen it or delete
+   it. Put independently testable deep-module behavior in the slice's `Tests/proof`;
+   `$rite-vet` confirms the level.
+2a. **Foreseeable-decision sweep.** Inspect questions, assumptions, architecture, dependencies,
+   proof prerequisites, and proposed checkpoints. Search facts and decide reversible technical
+   calls. New product/acceptance/policy/irreversible-risk gaps return to `$rite-clarify`; a build
+   checkpoint survives only for unavailable pre-code evidence or mandatory action-time approval.
+   **Completion:** no known implementation choice is postponed for build to ask later.
+3. **Create vertical tasks:** each delivers one observable capability end to end and
    is verifiable on its own; the **count emerges from the work, not a target number**;
    first slice = thinnest useful end-to-end path; order by dependency (risk-first within a
    tier). For a broad mechanical refactor, use expand → migrate batches → contract instead
@@ -99,12 +124,14 @@ Pull these via `Read` when shaping the plan:
    first, see `devrites-frontend-craft/reference/fullstack.md`). **For UI slices, name which
    of `design-brief.md`'s key states + interaction the slice delivers, and give it a binary
    **Visual acceptance** target (state × viewport × input + target R-id/brief rule)**, so
-   the design contract maps onto slices, not just acceptance criteria.
-4. **Map coverage:** every `AC-###` spec acceptance criterion maps to ≥1 `SLICE-###`
+   the design contract maps to slices as well as acceptance criteria.
+   `Tests/proof` names exact command, cwd, expected signal, prerequisites, and mutable
+   provenance inputs; `$rite-vet` preflights them.
+4. **Map coverage and wiring:** every `AC-###` spec acceptance criterion maps to ≥1 `SLICE-###`
    (`rite-spec/reference/acceptance-criteria.md`); no orphaned criteria, no slice without a
    criterion. Lift covered/backstop `Edge Coverage` rows and resolved `Prohibitions (must-NOT)`
-   rows into `traceability.md` and `test-plan.md`; unresolved rows go to `assumptions.md` with
-   their gate/owner.
+   rows into `traceability.md` and `test-plan.md`; unresolved rows get a gate/owner. Each
+   cross-slice boundary names producer, consumer, invariant, integration step, and proof.
 4a. **Parallel-lane sanity check**: after drafting `tasks.md` but before asking for plan
    approval, run the advisory lane planner:
    ```bash
@@ -121,7 +148,7 @@ Pull these via `Read` when shaping the plan:
    S="$(cat .devrites/ACTIVE 2>/dev/null)"
    devrites-engine coverage "$S" > ".devrites/work/$S/traceability.md"
    ```
-5. **Complexity & deviations gate:** justify anything off DevRites defaults (new dep,
+5. **Complexity and deviations gate:** justify anything outside DevRites defaults (new dep,
    extra abstraction, second design system) in the plan; if you can't justify it, simplify.
    **Principles conformance:** read `.devrites/principles.md` (if present) and confirm the
    approach honors every declared invariant. A plan that conflicts with one is not "a deviation
@@ -137,11 +164,12 @@ Pull these via `Read` when shaping the plan:
    S="$(cat .devrites/ACTIVE 2>/dev/null)"
    devrites-engine analyze "$S"
    ```
-7. **Readiness gate** (bottom of plan-template): every acceptance criterion covered by a
-   slice, dependency order acyclic + risk-first, no unjustified deviation, rollback for
-   every destructive/migration step. **Stop and confirm** before code. Render the review-before-code
+7. **Readiness gate** (plan-template): require CLEAR coverage, complete acceptance and
+   cross-slice wiring/proof, risk-first acyclic order, justified deviations, rollback, and a
+   closed decision sweep. **Stop and confirm** before code. Render the review-before-code
    digest first: `Intent` (one sentence from the spec), `Done means` (acceptance coverage x/y),
-   `Plan sanity` (slice count + riskiest boundary/gate), and `Build exactly this?` (yes → approve;
+   `Plan sanity` (slice count + riskiest boundary/gate), `Expected build interruptions`
+   (`none` or only justified action-time gates), and `Build exactly this?` (yes → approve;
    no → `$rite-plan revise`). When the human confirms the plan, write `Plan approved: <iso>` to
    `state.md` (see [state-workspace](../rite-spec/reference/state-workspace.md)); `$rite-build`
    checks this exists before building.
@@ -153,7 +181,8 @@ Use the canonical slice grammar in
 Every slice must satisfy that complete field set; phase-specific gate details live in
 [`reference/gates.md`](reference/gates.md).
 
-> **Mid-flight discipline.** When tempted to skip vertical slicing, coverage mapping, or dependency-order discipline: see [`anti-patterns`](reference/anti-patterns.md) (Common Rationalizations + Red Flags). Load it the moment you reach for the excuse.
+> **Mid-flight discipline.** Do not skip vertical slicing, coverage mapping, or
+> dependency ordering. See [`anti-patterns`](reference/anti-patterns.md).
 
 ## Output
 

package/pack/generated/codex/skills/rite-define/reference/gates.md

@@ -1,12 +1,10 @@
 # Gate taxonomy: advisory · validating · blocking · escalating
 
-DevRites uses a four-gate model for HITL pauses, adapted from the regulated-agentic-workflow
-governance pattern. Picking the right gate for each `Mode: HITL` slice is the difference
-between a workflow that catches real risk and one that becomes a review queue.
+DevRites uses four HITL gates, adapted from the regulated-agentic-workflow governance
+pattern. Choose the gate for each `Mode: HITL` slice by its risk and review needs.
 
-> **Default failure mode:** marking every HITL slice as `blocking`. The same reviewer ends
-> up approving low-stakes and high-stakes items at the same priority and the gate becomes
-> a queue. Mix gate types per slice; most plans use 2-3 of the 4.
+> **Do not mark every HITL slice as `blocking`.** That gives low-stakes and high-stakes
+> items the same priority. Most plans use 2 or 3 gate types.
 
 ## The four gates
 
@@ -39,7 +37,7 @@ validating question; the feature does not seal until the entry is resolved. An o
 **Example:** "Schema migration adds a non-null column with a default. Backfill plan is
 recorded; reviewer should confirm the default is the right one for archived rows."
 
-**SLA:** `4h`: the work continues but the validating queue should drain within hours,
+**SLA:** `4h`: the work continues, but the validating queue should clear within hours,
 not days.
 
 ### blocking
@@ -56,8 +54,8 @@ STOPs. The slice is not built until `$rite-resolve` lands.
 - Auth/authz boundary change.
 - Public API break.
 - Spec drift that changes acceptance criteria.
-- Tests / types / lint are red and the agent cannot tell whether the slice's contract is
-  wrong or the failing code is.
+- Bounded debug recovery proved the remaining red test/type/lint failure is a genuine
+  product-contract ambiguity the human must decide.
 
 **SLA:** `15m`: synchronous gates demand fast turnaround; otherwise treat the work as
 genuinely blocked and re-plan around it.
@@ -79,7 +77,9 @@ it's `blocking`.
 
 ## Picking the gate
 
-Apply this decision tree per HITL slice:
+First apply `afk-hitl.md` decision ownership: an objective implementation/tooling failure
+or reversible technical choice is agent work and gets no human gate. Then apply this
+decision tree per HITL slice:
 
 1. **Can the slice ship safely without the answer?**
    - Yes → `advisory`.
@@ -117,8 +117,9 @@ defaults and the always-pause rules:
 | `[advisory, validating]` | log + proceed | build + queue | pause | pause |
 | `[advisory, validating, blocking]` | log + proceed | build + queue | log + proceed* | pause |
 
-\* but **never** for destructive migrations, auth/authz boundary changes, public API
-breaks, or red tests/types/lint. Those always pause. See
+\* but **never** for destructive migrations, auth/authz boundary changes, or public API
+breaks. Red tests/types/lint remain hard build gates and must clear bounded recovery before
+the next slice; only a resulting human-owned ambiguity becomes a pause. See
 [`.agents/skills/devrites-lib/reference/standards/afk-hitl.md`](../../devrites-lib/reference/standards/afk-hitl.md) for the irreversible-risk
 list.
 
@@ -127,8 +128,7 @@ shortcut.
 
 ## Anti-patterns
 
-- **One gate for everything.** Validates becomes a queue, blocks all work behind one
-  reviewer. Pick gates per slice.
+- **One gate for everything.** This puts all work behind one reviewer. Pick gates per slice.
 - **Marking a destructive migration `validating` to "keep the loop moving".** Destructive
   work is `blocking` regardless of the urge to ship.
 - **`advisory` as a synonym for "I'm not sure but I don't want to ask".** If the slice
@@ -143,7 +143,8 @@ shortcut.
 Mode: HITL
 Gate: blocking
 SLA: 15m
-Checkpoint: Confirm (user_id, created_at) composite index choice vs two single-col indexes.
+Checkpoint: Approve irreversible deletion of legacy records after the dry-run count exists;
+that evidence cannot exist before the migration rehearsal.
 Blocked by: SLICE-002
 ...
 ```