devrites 3.0.6 → 3.1.0

package/pack/generated/codex/skills/devrites-source-driven/SKILL.md

@@ -10,16 +10,20 @@ 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-source-driven: verify, don't guess
 
-A confident wrong assumption about a library is a bug waiting to ship. When behavior
-matters and isn't certain, check the source of truth.
+When library behavior matters and is uncertain, verify it against installed source or
+authoritative documentation before relying on it.
 
 ## When to trigger
 - You're about to rely on an API signature, default, config key, or behavior you're not
@@ -33,32 +37,33 @@ matters and isn't certain, check the source of truth.
    version-specific.
 2. **Consult the source of truth**, in order: the installed package's own source/types
    in `node_modules`/gem/site-packages; context7 if available (`resolve-library-id` →
-   `query-docs`) for current upstream docs; official docs for *that version*; the project's
-   existing usage of the same API.
+   `query-docs`) for current upstream docs; official docs for *that version*.
 3. **Confirm the specific fact:** the signature, the default, the edge behavior, not a
    general impression.
-4. **Record it** in `decisions.md` (or `evidence.md`): the fact, the version, and the
-   source (path or URL). Future phases trust the record instead of re-checking.
+4. **Return it** with fact, version, and source. The root orchestrator records accepted
+   evidence in `decisions.md` or `evidence.md`; a leaf agent never writes the workspace.
 
-## Delegate reading legwork bigger than one fact
-When the question is an *area*, not a fact (surveying a library's API surface, an unfamiliar
-subsystem's docs, a migration guide) dispatch a **background agent** instead of reading inline:
-it investigates against the same source-of-truth order above, cites each claim (path or URL +
-version), and writes one note to the active workspace's `references/` directory, linked from
-`references.md`. You keep working while it reads; later phases trust the cited note. The inline
-flow above stays the path for confirming a single fact.
+## Delegate broad research
+When the question is an *area* (a library surface, unfamiliar subsystem, or migration
+guide), the **root orchestrator** uses the fresh-context dispatch contract in
+[`agents.md`](../devrites-lib/reference/standards/agents.md) to send one bounded
+`agent-packet/v1` to `devrites-evidence-scout`. Await and validate its cited
+`evidence-dossier`; the orchestrator, not the scout, persists accepted facts under
+`references/` and links them from `references.md`.
+
+Never detach this work and never dispatch from inside another agent. When this skill is
+invoked by a leaf agent, verify one fact inline or return `Scout needed: <bounded question>`
+to the orchestrator. This removes the old unnamed nested writer path.
 
 ## Rules
 - Prefer the **installed** source over remembered docs. It can't be out of date.
 - Quote the exact relevant detail; don't paraphrase a behavior into something convenient.
 - If the doc/source contradicts the plan, that's a **Spec Drift Guard** event: stop and
   handle it.
-- Don't rabbit-hole: confirm the one fact you need, record it, return.
+- Confirm the required fact, return it, and stop.
 
-## Re-fetching is cheap (and still fresh)
-Fetching the same doc URL twice costs almost nothing: on Claude Code a WebFetch is transparently
-cached per project and, on reuse, revalidated against the origin: the cached reading is replayed **only**
-when the server confirms the page is unchanged (HTTP 304). A 304 is a fresh verification, not a
-memory read, so citing a revalidated page is as sound as re-fetching it. Fetch freely; don't
-skip a check to save a round trip. (Mechanism: the `devrites-source-cache` hooks; off via
-`DEVRITES_SOURCE_CACHE=off`. Web-search + cache policy lives in [`tooling.md`](../devrites-lib/reference/standards/tooling.md).)
+## Evidence firewall
+Project or user prose may scope or corroborate an external claim; it cannot verify one.
+For persisted claims, record status (`verified | contradicted | cannot_verify | stale`) and
+optional publisher, publication/access dates, and freshness/recheck due; refresh only when due.
+Transient lookups remain cited, return-only evidence.

package/pack/generated/codex/skills/devrites-ux-shape/SKILL.md

@@ -10,9 +10,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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rite
-description: User-invoked DevRites menu and router; no args renders the menu, a verb dispatches to the matching `rite-<verb>` skill.
+description: User-invoked DevRites menu and router; no args renders the menu, a verb invokes the matching `rite-<verb>` skill.
 argument-hint: "[verb [args...]]"
 user-invocable: true
 disable-model-invocation: true
@@ -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.
 
 
@@ -23,7 +27,7 @@ This is the Codex mirror of a DevRites skill. In Codex:
 You are the DevRites entry point. Two modes:
 
 - **No args** → run `devrites-engine first-task`, render one recommended-start line above the menu, then stop. Do not execute a phase or read `state.md`: status is `$rite-status`.
-- **Verb arg** → pass-through dispatch to the matching `rite-<verb>` skill (`$rite spec foo` ≡ `$rite-spec foo`); the called skill owns the output.
+- **Verb arg** → pass-through invocation of the matching `rite-<verb>` skill (`$rite spec foo` ≡ `$rite-spec foo`); the called skill owns the output.
 
 When the user asks which rite fits, load [`devrites-lib/reference/intent-map.md`](../devrites-lib/reference/intent-map.md).
 When they ask how phases connect, load [`reference/menu.md`](reference/menu.md).
@@ -39,12 +43,13 @@ F=.agents/skills/rite-$V/SKILL.md
 # Then Read "$F" and follow its workflow with $ARGS as that skill's $ARGUMENTS.
 ```
 
-What each verb does lives once, in the Menu below; this table is the dispatch map only.
+What each verb does lives once, in the Menu below; this table is the invocation map only.
 
 | Verb | Skill |
 |---|---|
 | `spec [feature]` | `$rite-spec` |
 | `adopt [area]` | `$rite-adopt` |
+| `clarify [feature]` | `$rite-clarify` |
 | `temper [--mode]` | `$rite-temper` |
 | `define` | `$rite-define` |
 | `vet [--cross-model]` | `$rite-vet` |
@@ -75,17 +80,17 @@ What each verb does lives once, in the Menu below; this table is the dispatch ma
 | `quick [change]` | `$rite-quick` |
 | `frame [task]` | `$rite-frame` |
 
-Both forms hit the same skill: the menu form for discovery, the `/rite-<verb>` shortcut for muscle memory.
+Both forms call the same skill. The menu supports discovery; `/rite-<verb>` is the direct form.
 
 `use <slug>` is handled **inline**. There is no `rite-use` skill. Confirm
 `.devrites/work/<slug>/` exists, then re-point `.devrites/ACTIVE` to `<slug>` and report
 the now-active feature. It is cheap context-switching only: no re-spec, no phase run. If
 the workspace is missing, list the slugs under `.devrites/work/` and stop.
 
-`guide` is an inline first-feature walkthrough. Agree on one **real, genuinely small**
-change, then run spec → temper → define → vet → build → prove → polish → review → seal →
+`guide` is an inline walkthrough for the first feature. Agree on one **real, small**
+change, then run spec → clarify → temper → define → vet → build → prove → polish → review → seal →
 ship. Before each phase, say what it decides; after, name what it wrote and why. Pause at
-every boundary. Teach without lecturing.
+every boundary and explain only what the user needs for the next decision.
 
 Specialist triggers (model-invoked inside the above):
 `devrites-frontend-craft` (UI) · `devrites-browser-proof` (UI verify) ·
@@ -101,7 +106,7 @@ Reply-contract exception: `$rite` is the menu/router, not a workspace completion
 Called phase skills own the shared completion reply contract
 ([`reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
 
-1. **Verb in `$ARGUMENTS`** → dispatch per the table above.
+1. **Verb in `$ARGUMENTS`** → invoke the matching skill per the table above.
 2. **No args** → menu mode, as above.
 3. **Unrecognized first token** → tell the user the known verbs and stop. Don't guess.
 4. **No active feature** and the user asked "where am I" or named no verb → point at `$rite spec <feature>` (or `$rite-spec`). Don't summarize state yourself: `$rite status` (or `$rite-status`) owns that.
@@ -114,6 +119,7 @@ Recommended start: <greenfield: $rite spec <feature> | brownfield-unadopted: $ri
                               menu form           direct shortcut
 SPEC          $rite spec               ≡    $rite-spec        investigate deeply → write spec.md
 ADOPT         $rite adopt              ≡    $rite-adopt       onboard existing code → reverse-derive spec.md + seed conventions
+CLARIFY       $rite clarify            ≡    $rite-clarify     close the complete decision surface before planning
 TEMPER        $rite temper             ≡    $rite-temper      optional — strategic review: scope mode + pre-mortem, harden the spec
 PLAN          $rite define             ≡    $rite-define      turn the spec into plan + task slices + state
 VET           $rite vet                ≡    $rite-vet         mandatory every plan — light/full engineering review by stakes
@@ -143,8 +149,8 @@ UTILITY       $rite frame | prototype | handoff | zoom-out | pressure-test  (or
 
 > **Small one-off change?** A typo, copy tweak, config bump, or one-function fix → **`$rite-quick`**
 > (express lane: one contract → build → prove → ship, no full workspace). It escalates to
-> `$rite-spec` the instant the change grows past small / reversible / unambiguous. The full
-> lifecycle above is for real features: don't pay its ceremony for a one-off.
+> `$rite-spec` when the change is no longer small, reversible, and unambiguous. Use the
+> full lifecycle above for features.
 
 ## Core operating rules (every DevRites skill enforces)
 

package/pack/generated/codex/skills/rite/reference/menu.md

@@ -7,16 +7,17 @@ what each command does or how phases connect.
 
 | Phase | Command | Use when |
 |---|---|---|
-| Spec | `$rite-spec <feature>` | **New feature.** Investigate deeply → write spec.md. Asks with options; gathers attached design references (optional). |
+| Spec | `$rite-spec <feature>` | **New feature.** Investigate → write spec.md. Asks with options; gathers attached design references (optional). |
 | Adopt | `$rite-adopt` | Onboard an existing codebase instead of starting fresh: reverse-derive spec.md + seed the conventions ledger. |
+| Clarify | `$rite-clarify` | _Required after spec._ Topology-first decision-coverage scan; zero-question fast path when already clear. |
 | Temper | `$rite-temper` | _Optional, before define._ Strategic review of the spec: scope mode (expand/selective/hold-rigor/reduce) + pre-mortem; hardens the spec. Best on big/risky features; mandatory in `$rite-autocomplete`. |
 | Plan | `$rite-define` | Turn the approved spec into plan + vertical task slices + state. |
 | Vet | `$rite-vet` | _Required before build._ Review every plan: scope · architecture · tests · perf; light for simple/reversible, full for high stakes. |
 | Re-plan | `$rite-plan` | The active plan is too big, wrong, stale, ambiguous, or blocked. |
 | Build | `$rite-build` | Implement the next single vertical slice. Stops after one slice. |
-| Converge | `$rite-converge` | _Recovery._ Code drifted from / falls short of intent (resumed cold, adopted, stalled build): assess live code vs spec/plan/tasks and append the remaining work as new slices for `$rite-build`. |
+| Converge | `$rite-converge` | _Recovery._ Code drifted from or falls short of intent after a resume, adoption, or stalled build: compare live code with spec/plan/tasks and append remaining work as new slices for `$rite-build`. |
 | Prove | `$rite-prove` | Prove the current scope: tests, build, runtime, browser evidence. |
-| Polish | `$rite-polish` | Code polish always; UI normalize + ship-quality polish if UI is in scope. Modes: `bolder/quieter/distill/harden/normalize-only`. |
+| Polish | `$rite-polish` | Code polish always; normalize and polish UI when in scope. Modes: `bolder/quieter/distill/harden/normalize-only`. |
 | Review | `$rite-review` | Feature-scoped review before sealing. |
 | Seal | `$rite-seal` | Final GO / NO-GO decision (no git). |
 | Ship | `$rite-ship` | Type-GO → commit/push/tag, then archive the task + clear ACTIVE. |
@@ -26,14 +27,15 @@ what each command does or how phases connect.
 
 ## Typical orderings
 
-- **Every feature**: `$rite-spec` (spec) → *(big feature? `$rite-temper`: strategic review)* →
+- **Every feature**: `$rite-spec` (spec) → `$rite-clarify` (decision coverage) →
+  *(big feature? `$rite-temper`: strategic review)* →
   `$rite-define` (plan) → `$rite-vet` (engineering review; light or full) →
   `$rite-build` ×N (all slices) → `$rite-prove` (once all built) →
   `$rite-polish` (always: code + UI if UI) → `$rite-review` → `$rite-seal` → `$rite-ship`.
-- **Existing codebase**: `$rite-adopt` → `$rite-define` → `$rite-vet` → build.
+- **Existing codebase**: `$rite-adopt` → `$rite-clarify` → `$rite-define` → `$rite-vet` → build.
 - **Drift mid-build**: stop → drift question → `$rite-plan` (repair) → resume build.
 - **Resumed / adopted / stalled**: `$rite-converge` (assess live code vs intent → append the
-  remaining slices) → `$rite-build` ×N → continue at `$rite-prove`.
+  remaining slices) → `$rite-vet` → `$rite-build` ×N → continue at `$rite-prove`.
 
 ## Rules this menu obeys
 

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

@@ -11,26 +11,27 @@ 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-adopt: brownfield on-ramp
+# $rite-adopt: onboard existing code
 
-The **reverse** of `$rite-spec`. `$rite-spec` goes idea → spec; `$rite-adopt` goes
-**existing code → spec + seeded conventions**, so an already-built project can enter the
-DevRites lifecycle without hand-writing a spec from nothing. It produces the same
-`spec.md` the rest of the lifecycle expects, plus a head start in the conventions ledger
-so the very first new slice already knows the project's idioms.
+`$rite-adopt` derives a spec and initial conventions from existing code. It produces the
+same `spec.md` used by the rest of the lifecycle and seeds the conventions ledger with
+observed project idioms.
 
-Use it once, at the start, to onboard a repo (or a sub-area of one). After it, the normal
-lifecycle (`$rite-temper` → `$rite-define` → `$rite-build` …) takes over.
+Use it once when onboarding a repository or one of its sub-areas. Continue with
+`$rite-clarify`, `$rite-temper`, `$rite-define`, and `$rite-build`.
 
-> **Just want a map, not an onboarding?** `$rite-zoom-out` returns a structural map of
-> unfamiliar code without creating a workspace or ledger. `$rite-adopt` is the heavier move:
-> it *commits the project to the lifecycle*. Pick zoom-out to look, adopt to begin.
+> **Need only a code map?** `$rite-zoom-out` maps unfamiliar code without creating a
+> workspace or ledger. Use `$rite-adopt` when the project should enter the lifecycle.
 
 ## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
 Pull `documentation.md` when recording the adoption decisions (why-not-what) in
@@ -49,7 +50,7 @@ upholds invariants worth proposing as project principles (step 4a).
    if stated: what the user wants to build *next* on top of it. If the next-build objective
    is missing, ask once (it shapes the spec's acceptance); if the area is ambiguous, confirm
    before investigating the whole tree.
-2. **Reverse-investigate the existing code:** the durable shape of the project. Use a
+2. **Inspect the existing code** to establish the project's current structure. Use a
    code-intelligence index if available (codebase-memory-mcp first (its `get_architecture`
    gives a fast overview), cross-checked with codegraph + graphify, else standard methods
    (LSP / Read/Grep/Glob); see `.agents/skills/devrites-lib/reference/standards/tooling.md`) for
@@ -64,10 +65,10 @@ upholds invariants worth proposing as project principles (step 4a).
    **current behavior as the baseline** and the **next objective** (what adoption is for) with
    measurable acceptance. Also write `decisions.md`, `assumptions.md`, `questions.md`, and
    `state.md` (phase: spec).
-3a. **Seed the capability ledger** from the baseline. If the reverse-derived `spec.md` carries
+3a. **Seed the capability ledger** from the baseline. If the derived `spec.md` carries
    structured `### Requirement:` blocks, fold them into the living
-   `.devrites/specs/<capability>/spec.md` ledger so the project's *current* proven behavior is on
-   record before the first new feature: the ledger the next `$rite-spec` writes deltas against
+   `.devrites/specs/<capability>/spec.md` ledger so the project's current proven behavior is
+   recorded before the first new feature. The next `$rite-spec` writes deltas against this ledger
    ([ledger.md](../rite-ship/reference/ledger.md)). A flat baseline folds as all-ADDED into the
    feature slug's capability; tag capabilities in the spec first if you want finer granularity.
    ```bash
@@ -75,29 +76,28 @@ upholds invariants worth proposing as project principles (step 4a).
    devrites-engine ledger sync .devrites/work/<slug>   # seed
    ```
    Skip when the baseline records no structured requirements (nothing to seed).
-4. **Seed the conventions ledger** from what the investigation *observed*:
-   [adoption § seeding](reference/adoption.md). This is the deliberate bootstrap exception to
-   evidence-gated promotion: the seeds start at the base band and are provenance-tagged as
-   onboarding observations, not sealed-slice proofs, so real slices later corroborate or
-   (fresh-wins) contradict them.
+4. **Seed the conventions ledger** from observed behavior:
+   [adoption § seeding](reference/adoption.md). This is the bootstrap exception to
+   evidence-gated promotion. Seeds start at the base band with onboarding provenance;
+   later sealed slices may confirm or contradict them, and fresh evidence wins.
    **Completion:** every seed names observed evidence, provenance, and the base band.
-4a. **Propose candidate principles** (human-ratified; optional). Where the investigation found an
-   invariant the code *consistently and deliberately* upholds (money always in integer cents, PII
-   always redacted from logs, every v1 endpoint preserved) surface it as a **candidate
-   principle**, not a seeded convention. Principles are prescriptive and gating, so they are
-   **ratified by the human, never auto-seeded** the way conventions are: present the candidates via
-   `AskUserQuestion` with the evidence (where the code upholds it), and write the ones the human
-   ratifies to `.devrites/principles.md` with a dated Governance entry
-   ([`principles.md`](../devrites-lib/reference/standards/principles.md)). Propose, don't impose: an unratified candidate
-   stays a convention, not a gate. Skip cleanly when nothing rises to an invariant (common: a
-   fresh adopt may declare zero principles, and that's valid).
-5. **Hand off.** Spec and ledger are ready. Next: `$rite-temper` if big/risky,
-   else `$rite-define`; every plan then runs `$rite-vet` before build. Do not plan/build here.
+4a. **Propose candidate principles** (optional and human-ratified). When the code
+   consistently enforces an invariant, such as integer cents for money, redacted PII in
+   logs, or preserved v1 endpoints, propose it as a **candidate principle** rather than a
+   convention. Principles are prescriptive gates, so **never seed them automatically**.
+   Present each candidate through `AskUserQuestion` with evidence, and write human-ratified
+   candidates to `.devrites/principles.md` with a dated Governance entry
+   ([`principles.md`](../devrites-lib/reference/standards/principles.md)). An unratified
+   candidate remains a convention, not a gate. If no invariant qualifies, declare no
+   principles.
+5. **Hand off.** Continue with `$rite-clarify`. Its topology scan asks no questions when
+   the derived contract is already clear. Every plan then runs `$rite-vet` before build.
+   Do not plan or build here.
    **Completion:** one next rite is reported and no plan or application code was written.
 
-> **Mid-flight discipline.** Don't invent conventions the code doesn't follow, don't
-> seed an idiom you only assumed, and don't expand scope into a rewrite: adoption documents
-> what exists; the *next* feature changes it. See [`anti-patterns`](reference/anti-patterns.md).
+> **Mid-flight discipline.** Do not invent conventions, seed an assumed idiom, or turn
+> adoption into a rewrite. Adoption records existing behavior; a later feature changes it.
+> See [`anti-patterns`](reference/anti-patterns.md).
 
 ## Output
 
@@ -108,8 +108,8 @@ Default success shape:
 Done: adopted existing behavior into <slug>; baseline spec and placement recorded.
 Changed: spec.md, decisions.md, conventions ledger, principles proposals <updated|none>
 Evidence: not applicable; reverse-derived behavior is recorded for review
-Open: <none | adoption questions | Alternative: $rite-define for straightforward follow-up>
-Next: $rite-temper
+Open: <none | adoption questions>
+Next: $rite-clarify
 Record: .devrites/work/<slug>/spec.md
 ↻ Hygiene: /clear before the next phase
 ```

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

@@ -11,41 +11,48 @@ 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-autocomplete: full lifecycle, unattended
 
-Drives every DevRites phase in order without stopping for discretionary input. The
-prompt may be vague: autocomplete asks its clarifying questions **up front**, then
-runs to completion. It does **not** disable the safety gates: hard irreversible-risk,<!-- pack-scan-ignore: negated statement: gates are NOT disabled -->
+Runs every DevRites phase in order without pausing for discretionary input. It asks
+clarifying questions **before** unattended work begins. Safety gates remain active:
+hard irreversible-risk,<!-- pack-scan-ignore: negated statement: gates are NOT disabled -->
 blocking / escalating gates, and any NO-GO still pause.
 
 ## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
 **Step 0:** Read `.agents/skills/devrites-lib/reference/standards/core.md` and `.agents/skills/devrites-lib/reference/standards/afk-hitl.md` first.
 
 ## Operating rules
-- **One human window.** Clarifying questions are batched up front via
-  `devrites-interview`. After that, discretionary decisions are made automatically and
-  recorded in `decisions.md`, not asked. See [reference/decision-policy.md](reference/decision-policy.md).
+- **Use one initial human window.** Run spec and topology-first clarify; arm AFK only after
+  `Decision coverage: CLEAR`. Later discretionary calls are recorded, not asked
+  ([decision policy](reference/decision-policy.md)).
 - **Safety gates are not bypassable.** AFK never auto-passes destructive migration /
-  auth-authz change / public-API break / external-contract change / red tests; blocking
+  auth-authz change / public-API break / external-contract change; blocking
   and escalating gates and any open `gate: validating` always pause. `--ship` auto-confirms
   the **final** type-GO only: nothing else. A change that violates a declared project
   principle (`.devrites/principles.md`) with no recorded exception pauses too: autocomplete
   never grants a principle exception on its own (`principles.md`: that's a human decision).
-- **Loop budget = the plan's own slice count, not a fixed number.** After `$rite-vet`
+  Red checks never advance the loop: autocomplete runs the shared bounded debug recovery, then
+  stops as `blocked` if the objective failure remains; it asks only if recovery exposes a
+  human-owned decision.
+- **Set the loop budget from the plan's slice count.** After `$rite-vet`
   (not `$rite-define`: vet may split or add slices, so the count isn't final until then),
   set the AFK budget to however many slices the plan has, so the loop builds exactly the
-  task's slices and stops when they're done. `--max-slices N` is an OPTIONAL *lower* safety
-  cap (partial / babysat run); omit it to run the whole plan. The budget is finite
-  (= planned slices), so a runaway is still bounded.
-- **Best option, recorded.** For each discretionary choice, pick the option the relevant
-  specialist / reviewer favours and record the rationale. Never silently coin-flip.
-- **Strategic review runs, but never auto-grows scope.** After `$rite-spec`, run `$rite-temper`
+  planned slices and stops when they are done. `--max-slices N` is an optional lower
+  safety cap for a partial run; omit it to run the whole plan. The planned slice count
+  keeps the default run finite.
+- **Record each discretionary choice.** Pick the option recommended by the relevant
+  specialist or reviewer and record the rationale. Do not choose arbitrarily.
+- **Strategic review runs, but never auto-grows scope.** After `$rite-clarify`, run `$rite-temper`
   (significance-gated; it skips low-stakes specs in one line). Unattended it auto-applies only
   `hold-rigor` + `reduce-to-MVP` (these never grow acceptance); **any `expand` is a blocking
   pause**, and irreversible-risk findings always pause. Autocomplete hardens and may *prune* the
@@ -61,19 +68,22 @@ blocking / escalating gates, and any NO-GO still pause.
 ## Workflow
 1. **Orient + parse args.** Run `devrites-engine preamble` for deterministic workspace orientation.
    The idea + flags: `--ship` / `--yolo` (auto-confirm the final
-   type-GO), `--max-slices N` (OPTIONAL *lower* safety cap for a partial run; default =
+   type-GO), `--max-slices N` (optional lower safety cap for a partial run; default =
    the plan's slice count, i.e. run all planned slices).
-2. **Clarify up front.** If the idea is underspecified, run `devrites-interview` to
-   ~95% confidence: the only interactive window. If already clear, skip.
-3. **Arm AFK.** Write `.devrites/AFK` with `allow_gates: [advisory]`; set the slice budget
+2. **Specify and clarify up front.** Use `devrites-interview`, `$rite-spec`, and
+   `$rite-clarify` as one interactive window. Clear specs ask zero questions; Partial/Missing
+   coverage never arms AFK. **Completion:** `decision-coverage.md` records `CLEAR`.
+3. **Arm AFK after clarity.** Require `Decision coverage: CLEAR`, then write `.devrites/AFK`
+   with `allow_gates: [advisory]`; set the slice budget
    from the plan's count after `$rite-vet` (the slice count is only final post-vet), or from
    an explicit `--max-slices` ([reference/loop.md](reference/loop.md)). validating / blocking / escalating +
-   irreversible-risk still pause. Also `touch .devrites/CHECKPOINT`: an unattended run is the
-   case checkpoint mode earns its keep, so each proven slice is committed local-only as
-   crash-survivable `WIP` ([rite-build/reference/checkpoint.md](../rite-build/reference/checkpoint.md));
+   irreversible-risk still pause. Also `touch .devrites/CHECKPOINT`: unattended runs use
+   checkpoint mode so each proven slice is committed locally as a crash-survivable `WIP`
+   ([rite-build/reference/checkpoint.md](../rite-build/reference/checkpoint.md));
    `$rite-ship` collapses them into the one feature commit.
-4. **Drive the phases** ([reference/loop.md](reference/loop.md)): `$rite-spec` →
-   **`$rite-temper`** → `$rite-define` → **`$rite-vet`** → `$rite-build` (loop until all slices
+4. **Drive the phases** ([reference/loop.md](reference/loop.md)). The canonical arc is
+   `$rite-spec` → **`$rite-clarify`** → **`$rite-temper`** → `$rite-define` →
+   **`$rite-vet`** → `$rite-build` (repeat until all slices
    built; `devrites-engine tick-afk` each) → `$rite-prove` → `$rite-polish` → `$rite-review` → `$rite-seal`.
    Run each by Reading its `SKILL.md` and executing its workflow; state is carried by the
    workspace files, not chat.
@@ -83,12 +93,11 @@ blocking / escalating gates, and any NO-GO still pause.
 6. **Seal GO → ship.** With `--ship`, proceed to `$rite-ship` and auto-confirm the
    type-GO. Without it, render the type-GO prompt and stop for the human.
 
-> **Mid-flight discipline.** When tempted to auto-pass a blocking gate "to keep moving",
-> answer a material question yourself instead of pausing, or run past red tests: stop.
-> Autonomy is for the routine path; the gates exist for everything else.
+> **Mid-flight discipline.** Stop rather than auto-passing a blocking gate, answering a
+> human-owned material question, or continuing past red tests.
 
 ## Output
-A compact phase-by-phase log, then the final status. **Progress first for the final
+A compact phase log followed by the final status. **Progress first for the final
 status**: run `devrites-engine progress`, then use the shared typed states from
 [`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md):
 `Shipped`, `Stopped`, `Awaiting human`, `NO-GO`, or `GO`.
@@ -96,7 +105,7 @@ status**: run `devrites-engine progress`, then use the shared typed states from
 Keep the log terse:
 ```
 Autocomplete: <slug>
-spec <done|stopped> · temper <done|skipped|stopped> · define <done|stopped> · vet <done|stopped> · build <n/N|stopped> · prove <done|stopped> · polish <done|stopped> · review <done|stopped> · seal <GO|NO-GO|stopped>
+spec <done|stopped> · clarify <clear|stopped> · temper <done|skipped|stopped> · define <done|stopped> · vet <ready|stopped> · build <n/N|stopped> · prove <done|stopped> · polish <done|stopped> · review <done|stopped> · seal <GO|NO-GO|stopped>
 ```
 
 Final state examples: `Shipped: <feature>`, `Stopped: <reason>`, `Awaiting human: