devrites 3.0.6 → 3.1.0

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

@@ -11,24 +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-spec: investigate deeply, write the spec
+# $rite-spec: investigate and write the spec
 
-The spec phase. Turn a request (even a vague one) into a **fully-covered, correctly-placed
-`spec.md`** by investigating deeply and closing every material gap with the human, so
-`$rite-define` can plan it and nothing is missed. **No plan, tasks, or code here**. Those
-are `$rite-define` and `$rite-build`.
+Turn a request into a **fully covered, correctly placed `spec.md`** by investigating
+the existing system and resolving every material gap found during authoring.
+`$rite-clarify` audits the full topology before `$rite-define` plans it. **Do not write
+a plan, tasks, or code here.** Those belong to `$rite-define` and `$rite-build`.
 
-> **Too small to spec? Use `$rite-quick`.** A typo, copy tweak, config bump, or one-function
-> fix does **not** need a full workspace + lifecycle. Stop and run `$rite-quick <change>`: its
-> express lane (one contract → TDD build → scoped prove → ship) escalates back here the moment
-> the change turns out to touch auth / data / a migration / a public API / more than one slice.
-> Spec is for real features; don't pay its ceremony for a one-off.
+> **Use `$rite-quick` for a small change.** A typo, copy edit, config bump, or
+> one-function fix does not need a full workspace and lifecycle. Run
+> `$rite-quick <change>`. It returns here if the work touches auth, data, a migration, a
+> public API, or more than one slice.
 
 ## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
 Pull `documentation.md` via `Read`
@@ -39,35 +42,34 @@ Pull `spec-grammar.md` and `devrites-lib/reference/workspace-artifact-schema.md`
 acceptance for a behavioral / high-risk requirement (auth,
 data model, state machine, public API, money, migration): the structured `### Requirement:` /
 `#### Scenario:` (SHALL · WHEN/THEN) form, lint-checked by `devrites-engine spec-validate`. Simple criteria
-stay flat `AC-###` bullets; the grammar is opt-in by rigor, never forced.
+stay flat `AC-###` bullets; the grammar is opt-in by rigor, never forced. Use
+[`reference/acceptance-criteria.md`](reference/acceptance-criteria.md) to keep each
+criterion independently observable and binary.
 
 ## Operating rules (DevRites core)
 - No silent assumptions · no guessing through confusion · prefer existing conventions ·
   ask the human when an answer changes scope, placement, data model, UX, security,
   migration risk, or acceptance.
-- **Author section by section, not in one dump.** Draft the spec one section at a time
-  (problem → goal → requirements → acceptance → edge cases), and pause after each: a section
-  that carries real risk (a contested requirement, a boundary, an unstated assumption) can be
-  deepened right there with a fitting technique from
-  [`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) before moving on. A spec
-  written a section at a time is where sharper thinking lands cheaply; a wall-of-text spec hides
-  the weak section.
+- **Root authority:** the controlling chat asks every human question, makes decisions, and
+  writes the workspace. Read-only evidence work follows the fresh-context contract in
+  [`agents.md`](../devrites-lib/reference/standards/agents.md).
+- **Author one section at a time.** Draft problem → goal → requirements → acceptance →
+  edge cases, pausing after each section. If a section contains a contested requirement,
+  boundary, or unstated assumption, apply a relevant technique from
+  [`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) before continuing.
 
 ## Workflow
 0. **Read `.agents/skills/devrites-lib/reference/standards/core.md`:** the always-on operating rules and anti-rationalizations.
    Then run `devrites-engine preamble` for deterministic workspace orientation.
-0a. **Brownfield check: onboard before speccing onto un-adopted existing code.** If this is an
-   **existing codebase** (real source predating DevRites) that has **never been adopted** (no
+0a. **Check whether existing code needs adoption.** If this is an
+   **existing codebase** that has **never been adopted** (no
    `.devrites/conventions.md`, no prior `.devrites/work`, `.devrites/features`, or `.devrites/archive`) the build has no
-   conventions ledger to follow and the first slice would guess the project's idioms. Route
-   through `$rite-adopt` **first**, carrying `$ARGUMENTS` as its *next objective*: adopt
-   reverse-derives the baseline `spec.md`, **seeds the conventions ledger**, and proposes
-   principles, so this feature is specced on top of an onboarded project (adopt owns the
-   onboarding; `$rite-spec` only detects and routes: no duplicated logic). In **HITL** present a
-   ranked option (recommended: *adopt first, then spec this on top*; escape hatch: *spec-only, skip
-   onboarding*); in **AFK** (adoption allowed) run `$rite-adopt` first automatically. **Greenfield
-   (no pre-existing source) or an already-onboarded project → skip silently**: never block a spec
-   for the absence of adoption (the same no-op discipline as the principles gate). Cheap probe:
+   conventions ledger, route through `$rite-adopt` **first** and pass `$ARGUMENTS` as its
+   next objective. Adopt derives the baseline `spec.md`, seeds conventions, and proposes
+   principles; `$rite-spec` only detects and routes. In **HITL**, present a ranked option:
+   recommend adoption first and include a spec-only escape hatch. In **AFK**, when adoption
+   is allowed, run `$rite-adopt` automatically. **Skip this check silently for greenfield or
+   already-onboarded projects.** Never block a spec only because adoption is absent. Probe:
    ```bash
    if [ ! -f .devrites/conventions.md ] && [ ! -d .devrites/archive ] \
       && [ -z "$(ls .devrites/work .devrites/features 2>/dev/null)" ] \
@@ -75,137 +77,88 @@ stay flat `AC-###` bullets; the grammar is opt-in by rigor, never forced.
      echo "brownfield, not yet adopted → recommend $rite-adopt first (carry this idea as its next objective)"
    else echo "greenfield or already onboarded → continue spec"; fi
    ```
-1. **Understand the request** (`$ARGUMENTS`). Restate the goal and the *real problem
-   behind it* in a sentence or two.
-   **Completion:** one sentence states both requested outcome and underlying problem.
+1. **Understand the request** (`$ARGUMENTS`). State the requested outcome and the
+   underlying problem in one or two sentences.
+   **Completion:** one sentence includes both.
 1a. **Local dedupe.** Search local issues/PRDs and archived specs before creating a new workspace:
    ```bash
    devrites-engine spec-dedupe "$ARGUMENTS"
    ```
    If it finds a close match, ask the user: extend existing / adopt / new spec. Record the choice in
    `decisions.md` once the workspace exists. No match → continue silently.
-2. **Investigate deeply:** [investigation](reference/investigation.md). Produce, and
-   later write into the spec: **current behavior**; **placement** (which module/layer/
-   file/component should own it, the seam, patterns to reuse, and integration points:
-   callers, dependents, data, APIs/events); **what it resolves**; **issues**
-   (conflicts/constraints); **gaps** (unknowns); **blast radius**. Use a code-intelligence
-   index **if available**: `codebase-memory-mcp` first, cross-checked with `codegraph`
-   (`.codegraph/` / `codegraph_*`) + `graphify` (`graphify-out/`), else standard methods
-   (LSP / `Read`/`Grep`/`Glob`); see `.agents/skills/devrites-lib/reference/standards/tooling.md`:
-   for placement/callers/impact instead of broad file reads; fall back to reading files. For
-   uncertain external library/framework facts that bear on placement or feasibility, consult
-   context7 if available. When a material decision turns on a fact outside the codebase: a
-   common UX pattern, a standard, a prevailing best practice, how comparable products solve it:
-   **search the web if available** (brave MCP preferred; see `.agents/skills/devrites-lib/reference/standards/tooling.md`), and
-   carry the cited finding into the option you put to the human at step 4.
-   Also discover the project's **test / build/typecheck/lint** commands and the
-   frontend/backend systems; read `PRODUCT.md` / `DESIGN.md` / `CLAUDE.md` / `AGENTS.md` if
-   present (`AGENTS.md` is the cross-tool agent-conventions standard (treat it as project
-   conventions the build must follow, same standing as `CLAUDE.md`), and read
-   `.devrites/principles.md` if present) the declared invariants the feature must respect.
-   **Consult the capability ledger**: the living record of what the system already does
+2. **Investigate:** follow [investigation](reference/investigation.md) through its
+   complete findings and done-when gate. Also discover the project's **test /
+   build/typecheck/lint** commands, frontend/backend systems, and declared project guidance
+   (`PRODUCT.md`, `DESIGN.md`, `CLAUDE.md`, `AGENTS.md`, and `.devrites/principles.md` when
+   present).
+   **Consult the capability ledger**, which records current system behavior
    ([`ledger.md`](../rite-ship/reference/ledger.md)): `devrites-engine ledger list` for the
    capabilities on record, then `devrites-engine ledger show <capability>` for any this feature
    touches. Also search prior decisions with `devrites-engine decisions search "<2-4 feature nouns>"`
-   before asking the human to re-decide a settled architecture/API/auth choice. Starting from the proven contract (not a cold re-derive) is what makes the spec store
-   compound across features; it also tells you which requirements are new vs a change to existing
-   behavior, which decides the delta kind in step 5.
-3. **Gather design references (optional):** [references-intake](reference/references-intake.md).
-   The human **may** attach screenshots, mockups, a Figma link, a video, or links, or
-   **none at all** (perfectly normal; skip this step then). If any are given: **view/fetch**
+   before asking the human to revisit a settled architecture, API, or auth choice. The
+   ledger shows whether each requirement is new or changes existing behavior, which
+   determines the delta kind in step 5.
+   Identify proof constraints now: human-only credentials, unavailable environments, approval
+   windows, or acceptance not observable through existing test/runtime/browser surfaces.
+   Split independent placement, blast-radius, and external-fact questions into at most three
+   bounded `devrites-evidence-scout` packets on one frozen baseline. Await and reconcile every
+   cited dossier before step 4. The scout supplies facts only; it never asks the human or writes
+   the spec.
+3. **Gather design references when provided:** [references-intake](reference/references-intake.md).
+   The human may attach screenshots, mockups, a Figma link, a video, links, or nothing.
+   Skip this step when none are provided. Otherwise, **view or fetch**
    them, **save local files** into `.devrites/work/<slug>/references/`, and index them in
    `references.md` as target, constraint, or inspiration. Later phases honor that role
    rather than treating every reference as a fidelity target.
    **Completion:** every supplied reference is saved and classified, or absence is explicit.
-3a. **Shape the UX/UI before code (if the feature touches UI)**, when this feature is
-   frontend ([frontend-trigger](../rite-build/reference/frontend-trigger.md)), apply
-   `devrites-ux-shape` **now**, woven into the spec, not as a separate phase. It turns the
-   references + the spec into a feature-level **`design-brief.md`** (design direction, key
+3a. **Shape UX/UI before code when the feature is frontend**
+   ([frontend-trigger](../rite-build/reference/frontend-trigger.md)). Apply
+   `devrites-ux-shape` within the spec phase. It turns the
+   references and spec into a feature-level **`design-brief.md`** (design direction, key
    states, interaction model, optional Figma/image visual-direction probe) that `$rite-build`
-   targets so the UI is built to plan, not guessed. In HITL it pauses for the human to
+   targets for the build. In HITL it pauses for the human to
    confirm the direction; in AFK it asserts the best guess and logs it. Pure
    backend/data/CLI features skip this.
-4. **Close the gaps with the human. You recommend, the human decides.** Every material gap
-   (one that moves **objective · scope · placement · data model · UX · integration ·
-   non-functional · security · migration risk · acceptance**) is **put to the human as a ranked
-   option set**, one gap at a time, via the harness `AskUserQuestion` in HITL: **2-4 concrete
-   options, your recommended one first and marked `(Recommended)`**, each with a one-line
-   rationale + trade-off tagged by the dimensions that matter, plus an escape hatch (*Something
-   else. I'll describe it*). Render contract + AFK behaviour: the **Option set** section of
-   [`afk-hitl.md`](../devrites-lib/reference/standards/afk-hitl.md); spec-phase question discipline:
-   [question-protocol](reference/question-protocol.md). Your job is to **investigate, rank, and
-   recommend**, not to settle a material decision yourself. **Confidence changes the *cost* of
-   the question, not its *owner*:** when you're near-certain, you still present the set (the
-   human just confirms your `(Recommended)` option in one pick) you do **not** silently decide
-   it because you predicted the answer. Only a **genuinely reversible, low-impact** detail is
-   auto-decided and logged to `assumptions.md`; when unsure whether a gap is material, ask.
-   (Vague ask → `devrites-interview`; rough idea → `$rite-pressure-test`.) For a vague ask,
-   load [`reference/interview-patterns.md`](reference/interview-patterns.md), **map the decision
-   tree**, and resolve each branch depth-first; **cover every dimension**:
-   each resolved by a human pick or explicitly deferred (logged, non-blocking), never silently
-   skipped. Aim for **zero blocking gaps**. *If a gap is genuinely undecidable on paper (state
-   machine that may deadlock, data shape ambiguity, "which UX wins") → suggest a
-   scoped detour to `$rite-prototype` to answer that ONE question before
-   continuing.* **Invariant conflict is a blocking gap:** if a requirement or acceptance
-   criterion can only be satisfied by breaking a declared principle (`.devrites/principles.md`),
-   surface it: the principle wins by default; breaking it needs a recorded, scoped exception a
-   human approves, never a spec that silently contradicts an invariant.
-5. **Create the workspace** + set `.devrites/ACTIVE`
-   ([state-workspace](reference/state-workspace.md)). Write compact `README.md`,
-   `brief.md`, and `spec.md` ([spec-template](reference/spec-template.md)). WHAT/WHY,
-   technology-agnostic, with requirements, acceptance, edge cases, scope boundaries, links
-   to future `architecture.md` / `traceability.md`, and measurable acceptance
-   ([acceptance-criteria](reference/acceptance-criteria.md)). For a
-   behavioral / high-risk requirement, write the acceptance as a structured
-   `### Requirement:` (SHALL) + `#### Scenario:` (WHEN/THEN) block per
-   [`spec-grammar.md`](../devrites-lib/reference/standards/spec-grammar.md), nesting the `AC-###` id inside each scenario
-   so `$rite-seal` still grades it; routine criteria stay flat `AC-###` bullets. **When a
-   capability the ledger already holds is changing, write those requirements as deltas**:
-   `## ADDED / MODIFIED / REMOVED Requirements — capability: <c>` (spec-grammar.md § Delta form):
-   so the change, not just the end state, is explicit and `$rite-ship` folds it cleanly; a
-   capability with no ledger entry stays flat (the first sync seeds it). Also
-   write `brief.md`, `references.md`, `questions.md`, `decisions.md`, `assumptions.md`,
-   and an initial compact `state.md` (phase: spec) from
-   [state-workspace](reference/state-workspace.md). When the feature touches
-   UI, `design-brief.md` is written here too (by `devrites-ux-shape`, step 3a).
-   Populate `## Edge Coverage` with the deterministic boundary classes implied by each requirement
-   (empty/huge input, rounding, timezone, ordering, permissions, races, migration) and `## Prohibitions (must-NOT)`
-   only for bespoke constraints. If the feature touches model calls, RAG, agents, evals, or LLM output,
-   also create `ai-spec.md` from [ai-spec-template](reference/ai-spec-template.md). Then refresh any
-   managed project context block so `AGENTS.md` / `CLAUDE.md` point at the new active workspace:
+4. **Resolve human-owned gaps.** Recommend an option and let the human decide. Apply
+   [question-protocol](reference/question-protocol.md), the shared
+   [`afk-hitl.md` option-set and decision-ownership rules](../devrites-lib/reference/standards/afk-hitl.md#decision-ownership-search-before-asking),
+   and [`interview-patterns.md`](reference/interview-patterns.md) for a vague ask. Every
+   material dimension is resolved by a human pick or explicitly deferred as non-blocking;
+   only genuinely reversible, low-impact details go to `assumptions.md`. A paper-only
+   uncertainty may take one scoped `$rite-prototype` detour. A declared-principle conflict
+   remains blocking until the human approves a recorded, scoped exception.
+4a. **Build-interruption forecast.** Search first, then list and close foreseeable human needs:
+   product/acceptance ambiguity, irreversible/external approval, or human-only access. Record
+   owned prerequisites. Keep a build checkpoint only for unavailable pre-code evidence or a
+   mandatory action-time approval. **Completion:** no foreseeable human choice is deferred.
+5. **Create the workspace** + set `.devrites/ACTIVE` from
+   [state-workspace](reference/state-workspace.md). Write every required artifact and
+   conditional annex exactly from [spec-template](reference/spec-template.md), including its
+   grammar/delta, coverage-seed, edge/prohibition, UI, and AI rules. Then refresh any managed
+   project context block so `AGENTS.md` / `CLAUDE.md` point at the new active workspace:
    ```bash
    devrites-engine context sync || true
    ```
-5a. **Score the spec prose: "unit tests for English"** ([spec-checklists](reference/spec-checklists.md)).
-   Emit `.devrites/work/<slug>/checklists/<domain>.md` (one per requirement domain the spec covers:
-   functional · data-model · interaction · non-functional · edge-cases). Each tests the *requirement
-   prose* for completeness / clarity / measurability: "is 'prominent' quantified?", "is every
-   enumeration closed?", **not** the implementation. Fix each CRITICAL fail by editing the spec
-   (not by softening the question); minor fails are logged. The checklists feed the readiness gate.
-6. **Run the spec readiness gate** (bottom of spec-template): no blocking
-   `[NEEDS CLARIFICATION]`, placement decided, all material gaps resolved, any design
-   references provided are saved, **UX/UI shaped into `design-brief.md` if the feature is
-   UI**, requirements testable, success criteria measurable, **one-sentence intent** (the whole
-   change states its intent in a single sentence (if it can't, it is two features: split it or
-   narrow the scope), **every `checklists/<domain>.md` at
-   `Verdict: pass`**, and **any structured requirement blocks are grammar-valid**) run
-   `devrites-engine spec-skeleton` first, then `devrites-engine spec-validate` with
-   `--against .devrites/specs` so any delta sections are also
-   reconciled against the ledger (an ADDED that already exists, or a MODIFIED/REMOVED that doesn't,
-   is a blocking failure to fix, not soften):
+5a. **Check the spec prose** with [spec-checklists](reference/spec-checklists.md).
+   Emit every applicable domain checklist and fix each CRITICAL by correcting the spec,
+   never by softening the question.
+6. **Run the complete readiness gate** at the bottom of
+   [spec-template](reference/spec-template.md), then validate structure and ledger deltas:
    ```bash
    devrites-engine spec-skeleton ".devrites/work/<slug>"
    devrites-engine spec-validate ".devrites/work/<slug>" --against .devrites/specs
    ```
    **Do not run `devrites-engine analyze` in this phase:** `tasks.md` deliberately does not
    exist yet. `$rite-define` owns the first analyze pass after it writes the slices.
-   Treat edge/prohibition findings as blocking just like grammar findings. When it passes, write `Spec gate: passed <iso>` to `state.md`.
-6a. **Review-before-code digest.** Before handing off to planning, render the cheap human review:
+   Any failure blocks. The interruption forecast must be resolved, owned, or a justified
+   action-time gate. Then write `Spec gate: passed <iso>`.
+6a. **Review-before-code digest.** Before planning, render the compact human review:
    `Intent` (one sentence), `Done means` (top acceptance/scenario IDs), `Scope/risk` (what is in/out
    plus the hard gates), and `Build exactly this?` (yes → next phase; no → revise now). The digest
    is a view over `spec.md`, not a new artifact. **Stop** after the digest.
 
-> **Mid-flight discipline.** When tempted to skip investigation depth, gap-closing, or placement decisions: see [`anti-patterns`](reference/anti-patterns.md) (Common Rationalizations + Red Flags). Load it the moment you reach for the excuse.
+> **Mid-flight discipline.** Do not skip investigation, gap resolution, or placement
+> decisions. See [`anti-patterns`](reference/anti-patterns.md).
 
 ## Output
 
@@ -216,12 +169,12 @@ Default success shape:
 Done: spec ready for <slug>; placement decided and gaps closed.
 Changed: spec.md, decisions.md, assumptions.md, questions.md, references/ <updated|n/a>
 Evidence: checklists passed; grammar <valid | n/a flat acceptance>; design brief <path | n/a>
-Open: <none | n non-blocking questions | Alternative: $rite-define for small reversible work>; review digest: intent + done-means + scope/risk rendered
-Next: $rite-temper
+Open: <none | n non-blocking questions | Alternative: $rite-quick if express-lane eligible>; review digest: intent + done-means + scope/risk rendered
+Next: $rite-clarify
 Record: .devrites/work/<slug>/spec.md
-↻ Hygiene: /clear before the next phase; $rite-handoff if away > a few hours
+↻ Hygiene: /clear before $rite-clarify; $rite-handoff if away > a few hours
 ```
-If a workspace with the slug already exists, update its spec rather than overwriting blindly:
+If a workspace with the slug already exists, update its spec rather than overwriting it,
 and **show the human a short diff of what changed** in `spec.md` (acceptance criteria added /
 removed / reworded) before proceeding. A spec edit reviewed as a diff catches silent scope
 drift that a full re-read buries; this is the spec-review view (`$rite-spec --review` renders

package/pack/generated/codex/skills/rite-spec/reference/investigation.md

@@ -1,23 +1,21 @@
-# Investigation: understand deeply before specifying
+# Investigation before specification
 
-The spec is only as good as the investigation behind it. Goal: understand the
-requirement **completely**, decide **where it correctly belongs**, name what it
-**resolves**, and surface every **issue and gap**, then drive the gaps to closure with
-the user so the spec ships fully-covered and correctly-placed. A gap found here is cheap;
-a gap found in `$rite-build` is a drift event.
+Understand the requirement, decide where it belongs, define the outcome, and identify
+every issue and gap. Resolve material gaps with the user before the spec is ready. A
+gap first found during `$rite-build` is a drift event.
 
 Use a code-intelligence index if available (see
-`../../devrites-lib/reference/standards/tooling.md`) for the structural parts below; it answers "where does this
-live / what calls it / what would it break" far more cheaply and accurately than reading files.
-With none present, fall back to Read/Grep/Glob. When a gap turns on a fact the codebase can't
-answer: a standard, a prevailing UX pattern, how comparable products solve it: **search the
-web if available** (brave MCP preferred; `../../devrites-lib/reference/standards/tooling.md`) and cite the finding in
-the option you present, so the human's pick is informed rather than guessed.
+`../../devrites-lib/reference/standards/tooling.md`) for structural questions such as
+where code lives, what calls it, and what it could break. With none present, use
+Read/Grep/Glob. When a gap depends on an external fact, such as a standard, UX pattern,
+or comparable product, **search the web if available** (brave MCP preferred;
+`../../devrites-lib/reference/standards/tooling.md`). Cite the finding in the option
+presented to the human.
 
-## Prior art: check our own archive first (cheap, silent when empty)
-Before investigating outward, check whether we already shipped this. Grep the shipped
-archive for the feature's key nouns: a hit means an extension, a conflict, or a re-spec of
-solved work, and you inherit its decisions instead of re-deriving them:
+## Check the archive first
+Before external research, check whether the project already shipped related work. Search
+the archive for the feature's key nouns. A hit may indicate an extension, conflict, or
+replacement and provides prior decisions:
 ```bash
 devrites-engine archive-search "<key nouns>" 2>/dev/null \
   || grep -rliE '<noun1>|<noun2>' .devrites/archive/*/spec.md 2>/dev/null
@@ -29,18 +27,18 @@ devrites-engine archive-search "<key nouns>" 2>/dev/null \
   brownfield / principles no-op discipline).
 
 ## Produce these findings (write into spec.md)
-1. **The real ask:** restate the goal and the *problem behind the request* (people ask
+1. **The request and problem:** restate the goal and the problem behind it (people ask
    for "a dashboard" when they want an answer to a question). Who hits it, how often,
    what they do today instead.
 2. **Current behavior:** how it works today, or what's absent. Read the actual code and
    flows; don't assume.
-3. **Placement, where it should live** *(so it's correctly placed to be used)*
+3. **Placement**
    - Which module / layer / file / component should own this; the right seam.
    - Existing patterns/components/utilities to **extend or reuse** instead of duplicating.
    - **Integration points**: callers and dependents, the data it reads/writes, the
      APIs/events/contracts it touches (interface analysis: how it interacts with the
      rest of the system).
-4. **What it resolves:** the outcome/value and how we'll *observe* it's resolved (feeds
+4. **Outcome:** the result and how to observe it (feeds
    success + acceptance criteria).
 5. **Issues:** conflicts with existing code/UX/data/permissions, constraints, and
    anything that makes the obvious approach wrong. Each issue gets a disposition.
@@ -48,19 +46,22 @@ devrites-engine archive-search "<key nouns>" 2>/dev/null \
    becomes a question** (next section).
 7. **Blast radius:** what this change could break (use the code graph's impact/callers).
    Informs risks, test strategy, and rollback.
+8. **Human prerequisites:** credentials, accounts, approval windows, or irreversible
+   action-time decisions the acceptance path requires. Separate these from agent-owned
+   implementation and diagnostic work.
 
-Also gather any **design/reference materials** the human supplies (screenshots, Figma,
-links, video): see [references-intake](references-intake.md). They're part of
-understanding the requirement and become the target later phases verify against.
+Gather any design or reference materials the human supplies, including screenshots,
+Figma, links, or video. See [references-intake](references-intake.md). Record whether
+each is a target, constraint, or inspiration for later phases.
 
 ## Gap analysis (present → desired)
-State the **present state** and the **desired state**; the delta is the work, and the
-**unknowns in the delta are the gaps**. Drive the count of open gaps toward zero before
-handing off to `$rite-define`. Mark each gap inline with `[NEEDS CLARIFICATION: question]`.
+State the present and desired states. Their delta defines the work; unknowns in that
+delta are gaps. Resolve them before `$rite-define`. Mark each gap inline with
+`[NEEDS CLARIFICATION: question]`.
 
-## Turn gaps & issues into questions WITH options: you recommend, the human decides
-For each material gap/issue (one that changes scope, placement, data model, UX, security,
-migration risk, or acceptance), **put it to the human**: one gap at a time, as a ranked
+## Present gaps and issues as options
+For each material gap or issue that changes scope, placement, data model, UX, security,
+migration risk, or acceptance, **ask the human** one gap at a time with a ranked
 option set with the recommended option **first and marked `(Recommended)`** plus an escape
 hatch (via `AskUserQuestion` in HITL):
 ```
@@ -70,15 +71,18 @@ hatch (via `AskUserQuestion` in HITL):
 3. <alternative> — <implication>
 4. Something else — I'll describe it
 ```
-Investigate and recommend; don't settle a material decision yourself. Confidence in the answer
-lowers the *cost* of the question (a one-pick confirm), not its owner: present the set anyway.
+Investigate and recommend, but do not settle a material decision. High confidence may
+make the answer a one-pick confirmation; it does not change the decision owner.
 Only a **genuinely reversible, low-impact** gap is decided and recorded in `assumptions.md`
 without asking. Full render contract + AFK behaviour: [`afk-hitl.md`](../../devrites-lib/reference/standards/afk-hitl.md).
 
 ## Done when
 - The shipped archive was checked for prior art; any overlap was surfaced to the human.
-- The real problem, current behavior, placement, and what-it-resolves are written down.
+- The problem, current behavior, placement, and outcome are written down.
 - Every issue has a disposition; every material gap is resolved **by a human pick** from its
   option set (or explicitly deferred as non-blocking), not settled silently on your confidence.
-- No blocking `[NEEDS CLARIFICATION]` remains: the spec is **fully covered and correctly
-  placed**. This is the `$rite-spec` readiness gate before `$rite-define` plans it.
+- Every foreseeable build-time human prerequisite is resolved, assigned, or justified as an
+  action-time gate; objective repair/retry work is not disguised as a question.
+- No blocking `[NEEDS CLARIFICATION]` remains. The spec covers the gaps found during
+  authoring and records correct placement. This is the `$rite-spec` readiness gate
+  before `$rite-clarify` performs the systematic topology scan.

package/pack/generated/codex/skills/rite-spec/reference/question-protocol.md

@@ -17,13 +17,17 @@ deferred** (logged and non-blocking), never silently skipped:
 - [ ] **Integration**: external systems / APIs / contracts (or "none").
 - [ ] **Non-functional**: auth, sensitive data, latency / scale (or "n/a").
 - [ ] **Acceptance**: how each requirement is *proven* (test / observation).
+- [ ] **Human prerequisites**: credentials, approval windows, irreversible action-time gates
+  (or "none").
 
 A blocking gap in any dimension keeps the interview open; a deferred one goes to
 `questions.md` and doesn't block. This feeds the `$rite-spec` readiness gate.
 
 ## Spec question boundary
-- Things the codebase answers (read it first).
-- Reversible implementation details (decide and note as an assumption).
+- Things the codebase, prior decisions, or authoritative docs answer (search them first).
+- Reversible implementation and test details (decide and note as an assumption).
+- Objective tooling/environment failures (record the prerequisite or technical blocker; never
+  ask the human to authorize the agent's repair work).
 - Everything at once "to be thorough." Thoroughness is depth on the few that matter.
 
 ## Record

package/pack/generated/codex/skills/rite-spec/reference/spec-checklists.md

@@ -1,27 +1,26 @@
-# Spec-quality checklists: "unit tests for the English"
+# Spec-quality checklists
 
-Before the spec hands off to `$rite-define`, test the **requirement prose itself** the way you'd
-unit-test code: is each requirement complete, unambiguous, and measurable? These checklists
-interrogate the *writing*, not the implementation. There is no code to run yet. A criterion like
-"the banner is prominent" passes a human skim and fails here ("prominent" is unquantified).
-Catching it now is a one-line spec edit; catching it at `$rite-prove` is a reslice.
+Before `$rite-define`, check that each requirement is complete, unambiguous, and
+measurable. These checklists evaluate the prose, not the implementation. For example,
+"the banner is prominent" fails because "prominent" has no threshold. Fixing that in
+the spec avoids a later reslice.
 
-**Not implementation tests.** A checklist item asks "is *export* defined for an empty dataset?":
-it does **not** ask "does `exportCsv()` handle `[]`?". The first tests the spec; the second is
-`$rite-vet`'s test-plan and `$rite-prove`'s job. These files never name a function, file, or library.
+These are not implementation tests. Ask "is *export* defined for an empty dataset?", not
+"does `exportCsv()` handle `[]`?". Implementation checks belong to `$rite-vet` and
+`$rite-prove`. These files never name a function, file, or library.
 
 ## Output: one file per requirement domain
 
-Emit `.devrites/work/<slug>/checklists/<domain>.md`, one per domain the spec covers (skip
-a domain the spec marks "none"). The domains mirror the interview taxonomy, so a gap here maps to a
-`devrites-interview` dimension:
+Emit `.devrites/work/<slug>/checklists/<domain>.md`, one per domain the spec covers.
+Skip a domain marked "none". The domains match the interview taxonomy, so each gap maps
+to a `devrites-interview` dimension:
 
 | Domain file | Tests the prose of |
 |---|---|
 | `functional.md` | Functional requirements + scenarios: is each capability stated, bounded, testable? |
 | `data-model.md` | Key entities / data model: shapes, fields, lifecycle, relationships (skip if "none"). |
 | `interaction.md` | API / UI impact + UX states: every screen state and contract named (skip if no UI/API). |
-| `non-functional.md` | Constraints, auth / data sensitivity, latency / scale / compatibility budgets. |
+| `non-functional.md` | Constraints, auth / data sensitivity, latency / scale / compatibility budgets, human-only proof prerequisites. |
 | `edge-cases.md` | Empty / boundary / invalid / concurrent / failure paths the requirements imply. |
 
 ## Each item: a question, a verdict, the line it interrogates
@@ -41,11 +40,11 @@ Verdict is `pass` / `fail` / `n/a`. A `fail` carries a severity:
 - **CRITICAL:** the ambiguity would change the build or its acceptance: an unquantified
   acceptance/success criterion, an incomplete enumeration in a requirement, an ambiguous data
   shape, an undefined edge case on a stated flow, a contradictory pair of requirements.
-- **minor:** vague but non-load-bearing prose. Record it; it does not block.
+- **minor:** vague but nonessential prose. Record it; it does not block.
 
-## The question bank (seed: extend per domain)
+## Question bank
 
-Each question tests one of the failure modes of requirement prose:
+Each question checks one requirement-prose failure mode:
 - **Measurability:** every "good / fast / prominent / simple / secure" carries a number, a budget,
   or a named reference. No adjective stands in for a threshold.
 - **Completeness:** every enumeration is closed (no "etc."); every requirement with a precondition
@@ -56,18 +55,20 @@ Each question tests one of the failure modes of requirement prose:
 - **Testability:** each acceptance criterion is binary and names (or clearly implies) its evidence.
   A criterion only provable by reading code is a fail.
 - **Consistency:** no requirement contradicts another, the data model, or a non-goal.
+- **Non-functional:** each NFR names affected REQ/AC IDs or a bounded `global` scope;
+  human-only proof prerequisites name their owner.
 
-## How it feeds the readiness gate
+## Readiness gate
 
-The spec **Readiness gate** (bottom of [`spec-template.md`](spec-template.md)) folds these in: every
+The spec **Readiness gate** at the bottom of
+[`spec-template.md`](spec-template.md) requires every
 emitted `checklists/<domain>.md` must reach `Verdict: pass` (zero CRITICAL fails) before the gate
 passes. Minor fails are logged, not blocking. A single open CRITICAL keeps the spec `Status: Draft`.
-`$rite-define` reads the checklists at its step 0 and **hard-blocks while any CRITICAL is unchecked**;
-a spec that skips the checklists is treated as not-yet-scored: define stops and routes back here.
+`$rite-define` reads the checklists at step 0 and **hard-blocks while any CRITICAL is
+unchecked**. A spec without checklists is not yet checked, so define stops and routes
+back here.
 
 ## Discipline
-- Score honestly. A checklist you pass by softening the *question* instead of the *spec* is the
-  spec-quality version of weakening a test to go green. It defeats the gate.
+- Score honestly. Do not soften a checklist question to pass a weak spec.
 - Don't pad. Five real questions that find one CRITICAL beat thirty rubber-stamped rows.
-- These are *English* tests. The moment a question needs a function name to answer, it belongs in
-  `$rite-vet`'s `test-plan.md`, not here.
+- If a question needs a function name, it belongs in `$rite-vet`'s `test-plan.md`.

package/pack/generated/codex/skills/rite-spec/reference/spec-template.md

@@ -1,13 +1,13 @@
 # `spec.md` template
 
 Write the product contract: WHAT users get, WHY it matters, how success is
-measured, and what is out of scope. Keep HOW in `plan.md`; put topology and
+measured, and what is out of scope. Keep HOW in `plan.md`; put technical topology and
 diagrams in `architecture.md` / `flows.md`; put coverage in `traceability.md`.
 
 Rules:
 
 1. Mark unknowns with `[NEEDS CLARIFICATION: <question>]`; blocking unknowns
-   stop `$rite-define`.
+   stop `$rite-clarify`.
 2. Use stable IDs: `REQ-001` for requirements and `AC-001` for acceptance.
 3. Link to source artifacts instead of duplicating them.
 4. Keep the file compact. If it exceeds the schema budget, add
@@ -84,11 +84,17 @@ Use `resolved/test`, `resolved/judgment`, `dismissed`, or `unresolved`.
 - Does not own: <adjacent area>.
 - Placement summary: <one-line module/layer summary>; full technical map lives in `architecture.md`.
 
+## Coverage seed
+- Actors/journeys/components: <material surfaces discovered while authoring>.
+- States/data/contracts/integrations: <material boundaries discovered>.
+- Operations/proof surfaces: <configuration, observability, rollout/rollback, evidence constraints>.
+
 ## References
 - `brief.md` - request, objective, non-goals, success definition.
 - `architecture.md` - technical placement and integration points.
 - `flows.md` - diagrams when useful.
 - `decisions.md` - ADR-style product/technical decisions.
+- `decision-coverage.md` - topology scan and clarity verdict once `$rite-clarify` runs.
 - `traceability.md` - AC/REQ coverage once `$rite-define` runs.
 - `design-brief.md` - UI direction when UI is in scope.
 
@@ -107,4 +113,5 @@ Use `resolved/test`, `resolved/judgment`, `dismissed`, or `unresolved`.
 - [ ] Non-goals and scope boundaries are explicit.
 - [ ] Architecture/flows/decisions are linked out instead of duplicated here.
 - [ ] UI work has `design-brief.md`; non-UI work states UI is out of scope.
+- [ ] Coverage seed names the material surfaces `$rite-clarify` must scan.
 ```