devrites 3.0.7 → 3.2.0

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` |
@@ -58,6 +63,7 @@ What each verb does lives once, in the Menu below; this table is the dispatch ma
 | `ship` | `$rite-ship` |
 | `status [slug]` | `$rite-status` |
 | `doctor [--code | --reindex]` | `$rite-doctor` |
+| `upgrade [slug]` | `$rite-upgrade` |
 | `learn [--mine \| "<lesson>"]` | `$rite-learn` |
 | `explain [concept \| diff \| idea \| recap]` | `$rite-explain` |
 | `pov [candidate]` | `$rite-pov` |
@@ -75,17 +81,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 +107,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 +120,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
@@ -127,6 +134,7 @@ SEAL          $rite seal               ≡    $rite-seal        final GO / NO-GO
 SHIP          $rite ship               ≡    $rite-ship        type-GO + commit/push/tag, then archive + clear ACTIVE
 STATUS        $rite status             ≡    $rite-status      active feature, next action, evidence, risks
 DOCTOR        $rite doctor ...         ≡    $rite-doctor      health check; --reindex refreshes structural indexes
+UPGRADE       $rite upgrade ...        ≡    $rite-upgrade     reconcile an active legacy workspace with current contracts
 LEARN         $rite learn ...          ≡    $rite-learn       review captured lessons → promote to project rules / principles
 EXPLAIN       $rite explain ...        ≡    $rite-explain     grounded concept/diff/idea/recap explainer
 POV           $rite pov ...            ≡    $rite-pov         decide adopt / trial / hold / reject for an external option
@@ -143,8 +151,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,33 +7,39 @@ 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. |
 | Status | `$rite-status` | See where the active feature stands. |
 | Doctor | `$rite-doctor` | Health check: install integrity, stale ACTIVE, orphaned gates, hook wiring, merge/rebase state. |
+| Upgrade | `$rite-upgrade` | _Explicit recovery._ Reconcile an active legacy workspace with the installed semantic workflow contract; preserve completed work and history. |
 | Learn | `$rite-learn` | Review the captured learning ledger → promote recurring lessons to project rules / principles. |
 
 ## 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.
-- **Drift mid-build**: stop → drift question → `$rite-plan` (repair) → resume build.
+- **Existing codebase**: `$rite-adopt` → `$rite-clarify` → `$rite-define` → `$rite-vet` → build.
+- **Drift mid-build**: classify → bounded recovery for objective defects, `$rite-plan`
+  repair for a wrong durable plan, or one user decision for real product/risk drift.
+- **Workspace from older DevRites rules**: `$rite-upgrade` → current Clarify/Plan/Vet
+  gates → resume the snapshot's next command. Structural migration alone is not enough.
 - **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:

package/pack/generated/codex/skills/rite-autocomplete/reference/loop.md

@@ -1,8 +1,8 @@
 # The autocomplete loop: arm AFK, drive every phase
 
-Autocomplete is an orchestrator: it runs the existing `/rite-*` skills in order,
-exactly as a human would, but without stopping between them. It owns no workflow of
-its own: the phases do the work; autocomplete sequences them and enforces stops.
+Autocomplete runs the existing `/rite-*` skills in order without stopping between
+routine phases. Each phase keeps its own workflow; autocomplete only sequences phases
+and enforces stop conditions.
 
 ## Arm AFK
 
@@ -16,34 +16,34 @@ allow_gates: [advisory]        # only advisory auto-handles; validating+ pause
 # caps how many run unattended (default = all the plan's slices).
 ```
 
-The budget is the plan's own slice count, not a fixed number, so the loop builds exactly
-the task's slices and stops when they're done; `--max-slices N` only *lowers* it for a
+The budget is the plan's slice count, so the loop builds the planned slices and stops
+when they are done. `--max-slices N` only lowers that number for a
 partial run. Arm the gate policy at step 3; write `max_slices` / `AFK slices remaining`
 **after `$rite-vet`** (it runs before the build loop and may split or add a slice, so the
 count isn't final until then: vet runs on every plan here, so always set the budget after it).
 
-`allow_gates: [advisory]` is deliberate: an open `gate: validating` is merge-blocking
-at seal (`afk-hitl.md`), so autocomplete must *pause* on it rather than queue it and
-then hit NO-GO. Widen `allow_gates` only if the caller explicitly asked.
+`allow_gates: [advisory]` prevents an open `gate: validating` from being queued until
+seal, where it would force NO-GO under `afk-hitl.md`. Autocomplete pauses on it instead. Widen
+`allow_gates` only when the caller explicitly asks.
 
 ## Drive the phases
 
-Run each by Reading its `SKILL.md` and executing that workflow. State flows through the
-workspace files (`state.md`, `tasks.md`, `evidence.md`, …), so each phase picks up where
-the last left off. There is nothing to thread through chat.
+Read each phase's `SKILL.md` and execute that workflow. Workspace files such as
+`state.md`, `tasks.md`, and `evidence.md` carry state between phases; chat does not.
 
 | Step | Phase | Loop / gate |
 |---|---|---|
-| 1 | `$rite-spec` | feed the interview answers; write `spec.md` |
-| 2 | `$rite-temper` | significance-gated strategic review; harden spec + write `strategy.md`. Skip low-stakes specs in one line. AFK: `hold-rigor` / `reduce-to-MVP` auto-apply; **any `expand` pauses (blocking)**; irreversible-risk pauses |
-| 3 | `$rite-define` | reads `strategy.md`; `plan.md` + `tasks.md`; record `Plan approved` |
-| 4 | `$rite-vet` | engineering plan review on **every** plan (light pass on simple plans, full on big/risky; never skipped); harden `plan.md` / `tasks.md` + write `eng-review.md` + `test-plan.md`. AFK: hardening / coverage findings auto-apply; **any scope-growing / acceptance-changing finding pauses (blocking)**; irreversible-risk pauses. Set the slice budget after this (vet may split a slice) |
-| 5 | `$rite-build` ×N | **loop** while any slice is `pending`; build one (the slice-wright reads `test-plan.md` for coverage), then run `devrites-engine tick-afk state.md`: exit 3 (budget hit) ⇒ STOP |
-| 6 | `$rite-prove` | once all slices `built`; walks `test-plan.md`; on failure → `devrites-debug-recovery` within scope |
-| 7 | `$rite-polish` | re-verify after code edits (evidence must stay fresh) |
-| 8 | `$rite-review` | apply in-scope fixes; re-prove if code changed |
-| 9 | `$rite-seal` | GO/NO-GO decision (no git here) |
-| 10 | `$rite-ship` | only if seal GO; `--ship` auto-confirms type-GO, else stop for human |
+| 1 | `$rite-spec` | interactive window: investigate, feed intent answers, write `spec.md` |
+| 2 | `$rite-clarify` | same interactive window: topology-first scan; write `decision-coverage.md`; proceed only on `CLEAR`, then arm AFK |
+| 3 | `$rite-temper` | significance-gated strategic review; harden spec + write `strategy.md`. Skip low-stakes specs in one line. AFK: `hold-rigor` / `reduce-to-MVP` auto-apply; **any `expand` pauses (blocking)**; irreversible-risk pauses |
+| 4 | `$rite-define` | reads `decision-coverage.md` + `strategy.md`; writes `plan.md` + `tasks.md`; records `Plan approved` |
+| 5 | `$rite-vet` | engineering/readiness review on **every** plan (light pass on simple plans, full on big/risky; never skipped); harden `plan.md` / `tasks.md` + write `eng-review.md` (`Implementation readiness: READY`) + `test-plan.md`. AFK: hardening / coverage findings auto-apply; **any scope-growing / acceptance-changing finding pauses (blocking)**; irreversible-risk pauses. Set the slice budget after this (vet may split a slice) |
+| 6 | `$rite-build` ×N | **loop** while any slice is `pending`; build one (the slice-wright reads `test-plan.md` for coverage), then run `devrites-engine tick-afk state.md`: exit 3 (budget hit) ⇒ STOP |
+| 7 | `$rite-prove` | once all slices `built`; walks `test-plan.md`; on failure → `devrites-debug-recovery` within scope |
+| 8 | `$rite-polish` | re-verify after code edits (evidence must stay fresh) |
+| 9 | `$rite-review` | apply in-scope fixes; re-prove if code changed |
+| 10 | `$rite-seal` | GO/NO-GO decision (no git here) |
+| 11 | `$rite-ship` | only if seal GO; `--ship` auto-confirms type-GO, else stop for human |
 
 ## Between phases
 

package/pack/generated/codex/skills/rite-autocomplete/reference/stop-conditions.md

@@ -1,8 +1,8 @@
 # Stop conditions: when autocomplete must pause for a human
 
-Autonomy covers the routine path. These are the cases where autocomplete writes
-`state.md` (`Status: awaiting_human` or `blocked`), surfaces *why* + the single resume
-command, fires `notify` if set, and **stops**. None are bypassable by `--ship`.
+In the cases below, autocomplete writes `state.md` (`Status: awaiting_human` or
+`blocked`), reports the reason and one resume command, fires `notify` if set, and
+**stops**. `--ship` cannot bypass them.
 
 ## Always stop (irreversible-risk list: from `afk-hitl.md`)
 
@@ -12,14 +12,17 @@ Regardless of `allow_gates` or `--ship`:
 - Public-API break (response shape, removed endpoint, changed status semantics).
 - External-service contract change.
 - Filesystem destruction outside the workspace.
-- Red tests / types / lint at slice end (fail-on-red).
+
+Red tests/types/lint/build/browser proof are hard non-advance gates, not automatically human
+gates. Run bounded `devrites-debug-recovery`; if it exhausts, stop as a technical blocker unless
+the remaining issue is human-owned.
 
 ## Stop on gate severity
 
 - `blocking` gate fires → synchronous pause.
 - `escalating` gate fires → pause, route to the specialist tag.
 - Any `questions.md` entry with `gate: validating` and `status: open` → pause (it is a
-  seal NO-GO by definition; don't sail into a guaranteed NO-GO).
+  seal NO-GO by definition; stop before reaching seal).
 
 ## Stop on strategic-review scope expansion (`$rite-temper`)
 
@@ -29,6 +32,12 @@ Regardless of `allow_gates` or `--ship`:
   never grow the build's scope); **growing scope unattended is never automatic**. A low-stakes
   spec that temper skips, or a `hold-rigor` / `reduce-to-MVP` run, does **not** pause.
 
+## Stop on incomplete decision coverage (`$rite-clarify`)
+
+- Stop on any material Partial/Missing/unowned row or low-confidence, high-consequence
+  assumption. Continue the up-front window with the next genuine decision packet; never arm
+  AFK or carry it into build. Resolve facts and reversible choices automatically.
+
 ## Stop on workflow state
 
 - **NO-GO at seal** → stop; surface every blocker with `file:line` and the fix
@@ -38,7 +47,7 @@ Regardless of `allow_gates` or `--ship`:
 - **Budget exhausted with slices still pending:** `devrites-engine tick-afk` exit 3 while `tasks.md`
   still has unbuilt slices (only when an explicit `--max-slices` capped the run below the
   plan's count) → stop; report slices remaining. Exhausting the default budget = all
-  planned slices built = normal completion → continue to `$rite-prove`, don't pause.
+  planned slices built = normal completion → continue to `$rite-prove` without pausing.
 - **Still low-confidence after the interview:** the idea can't be pinned to testable
   acceptance criteria → stop and ask, rather than guessing the product.
 - **Repeated failure:** a phase fails, `devrites-debug-recovery` can't fix it within