devrites 3.2.27 → 4.0.0

package/pack/.claude/skills/rite-build/reference/phase-contract.md

@@ -1,193 +1,54 @@
 # rite-build phase contract
 
-See also [`one-slice-cycle.md`](one-slice-cycle.md).
+See [`one-slice-cycle.md`](one-slice-cycle.md); candidate lifecycle is
+[`candidate-integrity.md`](../../devrites-lib/reference/candidate-integrity.md).
 
-0. **Rules + AFK + readiness check.** Read
-   `.claude/skills/devrites-lib/reference/standards/core.md`, then orient and run the
-   deterministic readiness gate:
-   ```bash
-   devrites-engine preamble
-   devrites-engine snapshot
-   ```
-   Treat the snapshot as canonical machine-readable status and use its host-specific
-   `nextCommands` value:
-   ```bash
-   devrites-engine build-readiness; echo "readiness rc=$?"
-   ```
-   Any non-zero result is a hard STOP at the gate's reported route; `6` → `/rite-clarify`,
-   `7` → `/rite-vet`, and `8` → `/rite-upgrade`. Under AFK, also
-   enforce the mutable `state.md` budget from
-   [`afk-discipline.md`](afk-discipline.md); zero remaining slices forces a HITL stop.
-1. Read `spec.md`, `decision-coverage.md`, `plan.md`, `tasks.md`, `assumptions.md`,
-   `drift.md`, `eng-review.md`, and `test-plan.md`
-   if present (the vetted coverage target from `/rite-vet`: the slice's tests come from
-   here when it exists). `state.md` and the open-`questions.md` tally are already in the
-   preamble digest from step 0: re-read `questions.md` only for the full text of a flagged
-   blocking question.
-   Require `Decision coverage: CLEAR` and `Implementation readiness: READY`. If a
-   **blocking `[NEEDS CLARIFICATION]`** or uncovered decision remains, stop →
-   `/rite-clarify`; if plan readiness does not pass, stop → `/rite-plan` or `/rite-vet`
-   as classified by the gate. Don't build on an unresolved spec or unvetted plan.
-2. Select the next pending slice (or the one in `$ARGUMENTS`). **Restate its goal,
-   acceptance criteria, and scope boundary** in one short block. Confirm it's still the
-   right next slice. Write the slice's `Mode` to `state.md` as `Slice mode: <HITL|AFK>` on
-   **every** selection, including the non-HITL path; `/rite-resolve` clears or updates
-   it on resume.
-2a. **HITL gate (pre-action pause).** Resolve any `HITL` slice checkpoint before code,
-    exactly as [`checkpoint-protocol.md`](checkpoint-protocol.md) defines. An interactive
-    human answers inline and the build continues in place. AFK may auto-pick only allowed
-    gates; otherwise persist the question and awaiting-human cursor, notify, and STOP for
-    `/rite-resolve`. Blocking, escalating, and irreversible-risk gates always take that stop path.
-3. **Authorize exact paths, snapshot, then fresh-context dispatch the build core to
-   `devrites-slice-wright`.** First write the root-owned exact project-relative file list to
-   `.devrites/work/<slug>/.wright-allowlist`; mirror it in the packet's
-   `scope.allowed_repo_writes`. The wright's later `Files changed` report cannot widen it.
-   **Forge branch: only for a fully typed `Forge: yes` slice.** Follow
-   [`forge.md`](forge.md) sections 1 through 3: require the scorecard, strategies, and
-   real `manifest-env-v1` host binding; run `forge plan` before reconciliation; snapshot after a
-   planned result; bind, dispatch, record, and extract every candidate; judge the
-   immutable deltas; record one winner; and merge it. A typed serial degradation has
-   no Forge side effects and uses the default branch below. A later error preserves
-   the manifest-owned run for technical recovery; never degrade silently. After merge,
-   validate the winner envelope and enter the common return check at the end of this
-   step. Do not also dispatch a serial wright.
+1. **Orient and gate.** Read core, `.devrites/ACTIVE`, `state.md`, and required
+   slice artifacts. Require `Implementation readiness: READY`, its current
+   `Readiness inputs SHA-256`, all applicable exact reviewer accounts,
+   ID-and-meaning traceability, and green proof preflight; run
+   `devrites-engine check readiness <slug>`. Any miss/nonzero stops.
+2. **Select one slice.** Restate goal, acceptance criteria, exclusions, and exact
+   source/test paths. Before dispatch, validate relevant `assumptions.md` rows
+   against live evidence. If one is disproved and changes acceptance, architecture,
+   scope, or proof, use the Spec Drift Guard/plan recovery; a human-owned unknown
+   stops. Resolve HITL before source work. AFK answers only permitted gates;
+   human-owned or irreversible risk persists a question and stops for `/rite-resolve`.
+3. **Dispatch the sole writer.** Apply [`wright-dispatch.md`](wright-dispatch.md).
+   Put the smallest exact project-relative source/test path list directly in the task;
+   dispatch the exact `devrites-slice-wright` fresh. Root never writes, wright never
+   widens, and a missing profile stops.
+4. **Inspect the return.** Wait; compare its file list and `git diff --name-only`
+   with the contract. Reject stale, partial, malformed, or out-of-scope work.
+   Preserve user work; source restoration uses the same bounded wright.
+5. **Challenge stood decisions.** For each stood decision, run exact
+   `devrites-doubt-reviewer` fresh/read-only and record accepted or resolved-rejected
+   in `decisions.md`. A missing verdict, principle breach, scope change, or
+   irreversible risk blocks.
+6. **Prove without guessing.** Against the frozen pre-slice candidate, inspect
+   test hunks for deletion, skipping/focus, tautology, or weaker expectations. Dispatch exact
+   `devrites-test-analyst` on that immutable diff; missing account or adverse criterion
+   verdict is Critical. Run only `test-plan.md` repository/CI commands, capture output,
+   and recheck `git diff --name-only`. Missing, weakened, red, or source-mutating proof
+   is not success.
 
-   **Default serial branch.** Follow
-   [`wright-dispatch.md`](wright-dispatch.md) end to end; it owns snapshot timing, stuck
-   logging, the exact packet, conditional skill loading, and return checks. Dispatch through
-   named wright → safely enforced generic fresh worker. If neither is available, stop for
-   HITL; root never writes source. Validate the result before `.devrites`
-   writes; run `reconcile check`. Exit `5` rejects: run standalone
-   `devrites-engine reconcile abort`, then verify its receipt and frozen hashes.
-4. **Doubt every stood decision before accepting the slice.** The writer never grades its
-   own decisions: invoke `devrites-doubt` and its fresh reviewer for each entry. Do not enter
-   step 5 until every entry has a recorded `accept` or resolved `reject` verdict. Log each dispatch:
-   ```bash
-   devrites-engine footprint log <slug> doubt "<decision id>"
-   ```
-   Apply Doubt's AFK exception. Irreversible-risk or blocking escalations pause; scope-changing
-   answers route through the Spec Drift Guard. An irreversible-risk item misfiled under
-   `Decisions stood` is a blocking protocol violation: re-dispatch it as out of bounds,
-   never doubt-and-accept it.
-   **Principle check (same standing):** a wright return that breaks a declared principle
-   (reported in its `Principles` field, or that you detect against `.devrites/principles.md`) is
-   handled here like an irreversible-risk item: block, route to a human-approved scoped
-   exception in the register or stop; never doubt-and-accept a principle violation into the slice.
-5. **Run retained-baseline integrity and every root-owned proof gate, then recover
-   any objective red.**
-   ```bash
-   devrites-engine test-integrity; echo "test-integrity rc=$?"
-   ```
-   Run only root-owned gates already authorized byte-for-byte by the vetted
-   `test-plan.md` and unchanged `agent-packet/v1`, including exact command, cwd,
-   prerequisites, and expected artifact boundary. A wright result may report one
-   of those commands as `not-run`; it cannot invent, rewrite, widen, or authorize a
-   command. Reject any reported command that does not exactly match the frozen
-   plan/packet. Opaque wrapper, build, Playwright, and browser commands are root-owned
-   only when pre-authorized there; this transfers no source/test write authority.
-   A missing approved command is unverifiable proof.
-   After they pass, run `devrites-engine reconcile check` again after the root-owned gates
-   and before close, proving their child processes did not change tracked source:
-   ```bash
-   devrites-engine reconcile check; echo "reconcile rc=$?"
-   ```
-   If a root-owned gate changes source after the clean pre-gate check, run the exact
-   engine-owned rollback and verify the retained tree before recovery:
-   ```bash
-   devrites-engine reconcile restore-check
-   devrites-engine reconcile check; echo "reconcile rc=$?"
-   ```
-   Never manually restore, truncate, resnapshot, or widen an allowlist to hide
-   post-check drift.
+   Technical failure uses bounded `devrites-debug-recovery`: reapply the host gate
+   before an accepted in-slice correction, keep one root cause/three total attempts,
+   and never rerun an unchanged check. Ask humans only for product decisions,
+   irreversible risk, or genuinely human-only access.
+7. **Record.** After green proof, upsert `touched-files.md`'s authoritative candidate
+   manifest from the actual scoped diff with explicit `present`/`deleted` rows;
+   update `state.md`, `evidence.md`, and applicable UI/browser evidence. The manifest
+   stays mutable until Polish closes it.
+   Record stood decisions/dead ends in `decisions.md`; update checked assumptions'
+   status/evidence, never leaving a disproved row live. If code reveals a durable
+   project rule, propose a reviewed `AGENTS.md`/nearest-doc update, not a scored ledger.
+8. **AFK and reply.** Under `afk-discipline.md`, root charges
+   exactly once after each green built slice, never below zero; stop before another dispatch at zero, and fail closed
+   on malformed budget. Use the reply contract; name the next pending slice or, only
+   when all slices are built, `/rite-prove`. Emit no decorative progress renderer or
+   dispatch telemetry.
 
-   If the wright's `Gates` were red (targeted tests / types / lint), `test-integrity`
-   failed, a root-owned gate failed, the final reconcile failed, or proof could not be
-   verified: do **not** mark the slice `built`, and **do not fix the code yourself**.
-   Classify each causal fingerprint through
-   [`cleanup-and-classify.md`](../../devrites-debug-recovery/reference/cleanup-and-classify.md),
-   run `devrites-engine recovery route <class>`, and follow the `recovery-route/v1`
-   owner/action. Only `humanPause: true` or an exact human-only predicate opens a question;
-   technical repair, environment stabilization, and proof reruns remain agent-owned.
-   For an agent-owned defect route, continue the same wright under
-   `devrites-debug-recovery`, carrying command/output, attempt count, and dead ends. Wright
-   plus recovery share **three total attempts per root cause** and never
-   rerun an unchanged check. Persist the initial and retry failures with
-   `devrites-engine recovery record --class <class> "<root cause>" "<exact failure>" <slug>`,
-   run `recovery check` before each retry, and
-   `recovery clear --class <class> "<root cause>" <slug>` only after green. Before every
-   re-dispatch, update the root-owned allowlist only for an accepted in-slice path and run
-   `reconcile snapshot`: after a clean check this refreshes canonical-state scope while
-   retaining the original source baseline. Repeat reconcile and the integrity gate on every
-   return. This owns red gates, missing coverage, browser/runtime failures, and
-   workflow-tool defects.
-   After recovery:
-   - green → continue to record;
-   - product-contract/acceptance ambiguity or irreversible risk → open the genuine human gate
-     (and use `/rite-plan repair` only when the durable plan or contract changes);
-   - human-only access/action → gate with the exact needed input;
-   - exhausted objective failure → preserve reproduction/dead ends, set `Status: blocked` and
-     `Next step: /rite-plan unblock`, then STOP without a question or `/rite-resolve`.
-6. **Close the retained baseline, then record. You are the canonical writer.**
-   Reconciliation ran immediately on return; step 5 ran integrity, root-owned proof,
-   and a final clean reconciliation.
-   **Exit 3 → hard STOP:** a test was deleted, skipped, or de-asserted since the slice base: the
-   slice went green by weakening its tests, a Critical protocol violation. Revert the weakening and
-   re-dispatch the wright; do **not** mark the slice `built`.
-
-   Once every gate and doubt verdict is accepted, a forged slice records successful
-   verification and runs manifest-only cleanup per [`forge.md`](forge.md). Then close the
-   private window:
-   ```bash
-   devrites-engine reconcile close
-   ```
-   Keep it open across a genuine human wait that resumes the same slice; close it before a
-   scope/plan transition.
-
-   Then, from the wright's artifact, update `state.md`,
-   `evidence.md`, `touched-files.md` (and `browser-evidence.md` for UI). For a forged
-   slice, write `forge-report.md` after reconciliation, verification, and cleanup;
-   it records the run but owns nothing. Add a `## Review trail`
-   to `touched-files.md`: group the slice's important `path:line` stops by concern (design intent,
-   not file order), 1-5 concerns, each stop under 15 words. This is for a later human walkthrough;
-   keep it factual and skip invented rationale. **Persist every
-   `Decisions stood` entry from the wright's artifact to a `## Decisions stood` section in
-   `decisions.md`, one line each ending `— doubt: <accept | reject-resolved | MISSING>`**: the
-   verdict from step 4, or `MISSING` if step 4 was skipped for that entry. Write this ledger at
-   record-time **independent of the doubt step**, so a stood decision lands on disk even when it
-   was never doubted: `/rite-seal` cross-checks the ledger, and a `doubt: MISSING` entry is the
-   skipped-doubt finding that would otherwise leave no trace (the per-slice skip the footprint
-   count alone can't catch). If the wright stood no decisions, write `## Decisions stood` with
-   `- none` so the absence is recorded, not assumed. If the wright reported
-   an approach it tried and backed out of, record it under a `## Dead ends` section in
-   `decisions.md` so a retry or the next agent doesn't repeat it.
-   **If the wright's `Conventions` field reports a contradiction** (the live code now
-   disagrees with a held convention), record the drift. You own this bookkeeping:
-   ```bash
-   devrites-engine conventions contradict --key <key> --slug <slug> \
-     --evidence "<what the live code does>" --drift-file .devrites/work/<slug>/drift.md
-   ```
-   It lowers the convention's band (or retires it) and appends a `convention-drift` entry to
-   `drift.md`. The ledger is **promoted only at `/rite-seal` on GO**: build only records
-   contradictions, never new conventions. **Evidence is the
-   wright's real command output, not its say-so.** Capture per
-   [`evidence-standard.md`](evidence-standard.md). Append a footprint record for this
-   slice's wright dispatch (deterministic run-weight bookkeeping the seal reports):
-   ```bash
-   devrites-engine footprint log <slug> wright "<slice id>"
-   ```
-   If `.devrites/AFK` is present, decrement
-   the budget by running `devrites-engine tick-afk <state.md path>`:
-   it decrements `state.md`'s `AFK slices remaining` field, prints the new value, and exits `3`
-   when it hits 0. **Exit 3 → STOP** (forced HITL stop; the cap is exhausted). Never rewrite
-   `.devrites/AFK` `max_slices` in place. It is read-only initial budget.
-7. **STOP.** Render the progress footer, then report and recommend the next step. Run the
-   shared footer (mirror of the step-0 preamble) so the slice meter + flow ribbon are
-   deterministic, not model-typed:
-   ```bash
-   devrites-engine progress
-   ```
-   It reads `state.md` (already updated in step 6), so the meter reflects the slice you
-   just built. **When every slice is built** (`✅ ALL BUILT`) say so explicitly (the build
-   phase is complete, the next phase is `/rite-prove`) don't leave completion implicit.
-
-> **Mid-flight discipline.** The wright must resist doing two slices, skipping TDD, adding a defensive check, or wandering outside `touched-files.md`; you must resist skipping the post-return `devrites-doubt` because the wright "seems confident": see [`anti-patterns.md`](anti-patterns.md). Load it the moment you reach for the excuse.
+> **Mid-flight discipline.** One writer contract builds one slice. Do not skip
+> TDD, widen paths, fold in a second slice, or accept the writer's judgment as
+> independent review.

package/pack/.claude/skills/rite-build/reference/spec-drift-guard.md

@@ -28,7 +28,7 @@ other phases reference it here.
        re-vet, then resume.
      NO, product/policy/irreversible-risk decision → ask the user (format below).
 5. Never continue on a known-wrong durable plan. A repaired active-slice implementation
-   may continue only after the normal recovery, reconciliation, and integrity gates pass.
+   may continue only after bounded recovery, returned-diff review, and proof gates pass.
 ```
 
 ## User question format

package/pack/.claude/skills/rite-build/reference/wright-dispatch.md

@@ -1,135 +1,45 @@
 # Slice-wright dispatch
 
-`/rite-build` delegates one slice or correction to `devrites-slice-wright`.
-The root owns scope, questions, `.devrites/**`, reconciliation, and routing.
-Production builds and browser/E2E runs are root-owned gates only when their exact
-command, cwd, prerequisites, and artifact boundary are already frozen in
-`test-plan.md` and the unchanged packet.
-The wright only writes source/tests, runs writer-safe proof, and never invokes agents.
-
-The universal packet, result, budget, await, retry, and host fallback contract is
-[`standards/agents.md`](../../devrites-lib/reference/standards/agents.md). This file adds
-only the source-write lifecycle.
-
-## Prepare and dispatch
-
-1. Derive the smallest exact file allowlist from the selected slice, current code
-   placement, and accepted correction set. Entries are normalized project-relative file
-   paths: no directories, globs, traversal, symlink escapes, duplicates, or
-   `.devrites/**`.
-2. Write that list, one path per line, to
-   `.devrites/work/<slug>/.wright-allowlist` (or the active compatibility workspace).
-   The root owns this file; the wright's returned `Files changed` is evidence, never
-   authorization. If a necessary unlisted path appears, the wright stops and returns it.
-3. Create `agent-packet/v1` for `devrites-slice-wright`. Put the identical paths in
-   `scope.allowed_repo_writes`; include the slice goal, verbatim acceptance, boundary,
-   exact context paths, test-plan targets, and applicable standards. Do not include the
-   root's implementation reasoning.
-4. Immediately before a serial dispatch:
-
-   ```bash
-   devrites-engine stuck log "$(cat .devrites/ACTIVE 2>/dev/null)" dispatch "<slice id>"
-   devrites-engine reconcile snapshot
-   ```
-
-   A Forge slice runs `forge plan` first, then takes this same snapshot; see
-   [`forge.md`](forge.md). The first snapshot captures the original dirty-tree baseline, private Git objects,
-   allowlist, and canonical-state fingerprint. A later snapshot after a clean check
-   refreshes only the dispatch boundary; it retains the original slice baseline.
-5. Fresh-context dispatch the wright through the capability ladder and await its typed
-   result. Never run two possible writers in one tree.
-
-## Forge candidate binding
-
-[`forge.md`](forge.md) owns the state machine. This file owns the candidate packet:
-use the same project-relative allowlist and slice contract, add only the manifest-recorded
-candidate strategy, and set all five bindings before the first tool call:
-
-```text
-DEVRITES_FORGE_RUN_ID
-DEVRITES_FORGE_CANDIDATE
-DEVRITES_FORGE_WORKER_ID
-DEVRITES_FORGE_WORKER_PID
-DEVRITES_FORGE_PROCESS_START
-```
-
-The candidate cwd must equal its manifest worktree, and the environment is all-or-none.
-Only a real adapter declared as `manifest-env-v1` may supply it. The live PID,
-engine `forge process-token` value, and worker ID must match the prior `forge record ... started`
-transition. A partial or mismatched binding denies the writer; return to the orchestrator
-instead of widening scope. The candidate writes only source/tests in its own tree and
-returns the normal typed artifact.
-
-## Validate the return before accepting it
-
-Validate the `agent-result/v1` identity, baseline, budget, payload type, side effects,
-and exact changed-file set. Before the root writes any canonical record, run:
-
-```bash
-devrites-engine reconcile check; echo "reconcile rc=$?"
-devrites-engine test-integrity; echo "test-integrity rc=$?"
-```
-
-- Reconcile `5`: reject; run standalone `devrites-engine reconcile abort` to restore
-  pre-snapshot source/user work and close with a receipt. Never widen scope.
-- Test integrity `3`: a test was deleted, muted, focused, or de-asserted. Treat it as a
-  Critical protocol failure and correct it through the wright.
-- A setup/corrupt-baseline error blocks acceptance; never fall back silently to `HEAD`.
-
-The clean reconcile check records that source has not changed since inspection. The
-baseline and private object database stay open until every later gate succeeds.
-
-## Decisions, failures, and bounded recovery
-
-After the immediate check, independently doubt every `Decisions stood` item. Human-owned
-product, policy, public-contract, irreversible-risk, or human-only access decisions use
-their real gate. Objective red tests, browser/runtime failures, missing technical
-coverage, package-scanner defects, and review corrections stay agent-owned.
-
-Classify each causal fingerprint through
-[`cleanup-and-classify.md`](../../devrites-debug-recovery/reference/cleanup-and-classify.md).
-The engine route is canonical; technical defects stay agent-owned.
-Each objective root cause then shares one durable three-attempt budget:
-
-```bash
-devrites-engine recovery route <class>
-devrites-engine recovery record --class <class> "<root cause>" "<exact failure>" <slug>
-devrites-engine recovery check "<root cause>" <slug>
-```
-
-Before every retry:
-
-1. update `.wright-allowlist` only for an accepted path still inside the settled slice;
-2. run `devrites-engine reconcile snapshot`.
-
-That refresh requires the prior clean check, re-fingerprints root-owned state, and keeps
-the original source baseline. Re-dispatch with the exact output, attempt count, and dead
-ends. Then repeat reconcile and `test-integrity` from zero. Clear recovery only after
-green with `recovery clear --class <class> "<root cause>" <slug>`. An exhausted objective
-failure becomes a technical blocker with its reproduction, not a `rite-resolve` question.
-
-## Close and record
-
-Run the root gates and final reconciliation from `phase-contract.md` step 5. Then:
-
-```bash
-devrites-engine reconcile close
-```
-
-Only then persist `state.md`, `evidence.md`, `touched-files.md`, decision/doubt records,
-and browser evidence. Keep the retained window across a genuine human wait that will
-resume the same slice. Close it before abandoning the slice for a scope/plan transition.
-
-## Host dispatch
-
-Use the named wright. Hidden V2 `agent_type` is not V1/unavailable: send
-`agent_type=devrites-slice-wright` anyway. Use guarded generic only after explicit
-V1; if V2 rejects the call, stop before generic/default. The rollout proves role,
-wait, and result. Root hooks keep the pending canonical boundary current until spawn, then freeze it apart from the
-retained source baseline: pre-start root recovery records are excluded, while
-post-start canonical changes fail.
-Any generic worker still needs the exact allowlist or an isolated checkout;
-reconciliation alone is insufficient. If no safe fresh-agent rung is available, stop
-for HITL. On Codex, `reconcile check` and `reconcile close` require the completed
-wright receipt bound to the current reconcile snapshot.
-The root never performs wright work.
+`/rite-build` gives one bounded task to exact `devrites-slice-wright`.
+Root owns scope, artifacts, inspection, and routing but never writes source/tests; only
+the wright writes them and invokes no agent.
+
+## Host gate
+
+Follow the canonical [source-writing boundary](../../devrites-lib/reference/standards/agents.md#source-writing-boundary):
+Claude grants only the exact wright `acceptEdits`; Codex uses its workspace root,
+the exact `:workspace` wright, and read-only specialists. Never bypass/substitute
+the wright or recreate an engine bridge.
+
+## Prepare
+
+1. Derive the smallest exact project-relative source/test path list; reject
+   directories/globs, traversal, symlink escapes, duplicates, and `.devrites/**`.
+2. Put it in the task with goal, verbatim acceptance, exclusions, context,
+   `test-plan.md` proof commands, and applicable standards.
+   A new path requires a new bounded contract; the wright cannot widen the task.
+3. Record `git diff --name-only` before dispatch so unrelated work remains
+   distinguishable.
+
+## Run
+
+Ask the host for the exact writer in fresh context and wait. Never run two
+writers in one worktree or substitute a generic agent.
+
+## Inspect and prove
+
+1. Compare the returned file list and `git diff --name-only` with task paths.
+   Reject a result that omits any required key, including empty-or-filled
+   bookkeeping arrays, or adds a path. Restore only through the same bounded
+   wright; root never widens scope or edits source.
+2. Inspect the test diff for deletion, skipping, focus markers, or loosened
+   assertions. Dedicated test analysis treats weakening as Critical.
+3. Run only repository proof already approved by `test-plan.md`, then inspect
+   `git diff --name-only` again in case a proof tool changed source.
+4. Challenge decisions. Human choices return; native diagnosis routes failures.
+   The root counts the wright plus recovery failures by causal fingerprint from
+   the current context and recorded Dead ends/evidence. Three total failed
+   attempts is the limit; persist each and never dispatch a fourth related try.
+5. Reconcile returned reuse, conventions, principles, sources, assumptions,
+   decisions, dead ends, follow-ups, gates, and touched files. Persist the
+   relevant facts in canonical artifacts, not the wholesale report.

package/pack/.claude/skills/rite-clarify/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: rite-clarify
-description: Run the topology-first decision-coverage scan after rite-spec and before strategy or architecture. Audit actors, journeys, states, data, integrations, operations, proof, assumptions, and must-NOT boundaries; close Partial/Missing rows and emit decision-coverage.md CLEAR. Use for missing/stale coverage or a missed pre-build product decision.
+description: Audit a completed spec for missing decisions before strategy or architecture. Use after /rite-spec when coverage is incomplete or stale; not for spec writing.
 argument-hint: "[feature-slug]"
 user-invocable: true
-required-agent-roles: none
 ---
 
 # /rite-clarify: resolve product decisions
@@ -36,46 +35,53 @@ dispatch uses
 
 ## Workflow
 
-0. **Orient.** Run `devrites-engine preamble` and `snapshot`. Require `spec.md` plus
-   `Spec gate: passed`; otherwise STOP → `/rite-spec`. For a later-phase retrofit, run
-   `devrites-engine clarify-return enter <slug>` **before any pause**; this persists the
-   return cursor and enters `Phase: clarify`.
-1. **Enumerate topology** from the spec, references, live code, and prior decisions: actors,
-   journeys/components, states, data lifecycles, interfaces/integrations, operations, and
-   proof. Add omitted surfaces to the spec. **Completion:** every material surface appears
-   once with a source or canonical spec reference.
-2. **Scan coverage** with `devrites-interview /clarify mode` and the reference taxonomy.
-   Mark each surface Clear/Partial/Missing with evidence; include must-NOT and out-of-scope
-   behavior. Unmentioned never means not applicable. **Completion:** the matrix records every
-   surface with evidence.
-3. **Eliminate factual unknowns** through code intelligence, project/decision docs,
-   manifests/lockfiles, and authoritative external docs. Dispatch independent topology/fact
-   questions to `devrites-evidence-scout` (maximum three at once), await the cited dossiers,
-   and reconcile them in the root context. The root folds accepted facts into `spec.md` or
-   `assumptions.md`; the scout never asks or writes. **Completion:** each factual unknown is
-   source-backed or reclassified as an owned decision/assumption.
-4. **Audit assumptions and decisions.** Record the fields required above. For high-cost or
-    hard-to-reverse product/constraint choices, present two or three viable options, recommendation
-   first. A genuinely undecidable behavior may take one bounded `/rite-prototype` detour.
-5. **Close human-owned gaps** using the shared option-set contract: one highest-impact packet
-   per turn. Persist answers immediately in `spec.md` plus `decisions.md`/`questions.md`.
-   AFK remains within its gate ceiling; irreversible risk and principle exceptions pause.
-6. **Re-scan after edits** until each material row is `closed`, `agent-owned`,
-   `not-applicable`, or justified `deferred-nonblocking` with owner and validation gate.
-   Partial/Missing, an unowned material assumption, or an open blocking/escalating question
-   means `NEEDS CLARIFICATION`.
-7. **Write the verdict.** Update `decision-coverage.md`; success requires exactly one
-   `DevRites contract: devrites.readiness-artifacts.v2` field and exactly
-   `Decision coverage: CLEAR`. Normal state is `Phase: clarify`, `Next step: /rite-temper`.
-   A contract-neutral retrofit runs `devrites-engine clarify-return restore <slug>`; a
-   changed behavior/acceptance contract leaves the return cursor unconsumed, writes
-   `drift.md`, and routes `/rite-plan repair`. Normal first-pass flow sets `/rite-temper`.
-8. **STOP.** Run `devrites-engine progress`; hand off only on `CLEAR`.
+1. **Orient.** Read `.devrites/ACTIVE`, `state.md`, and `spec.md`. Require
+   `Spec gate: passed`; otherwise stop at `/rite-spec`. Apply the native cursor
+   protocol below before changing workspace artifacts.
+2. **Enumerate the topology.** From the spec, live code, contracts, references,
+   and recorded decisions, list every material actor, journey/component, state,
+   data lifecycle, integration, operation, proof surface, and must-NOT boundary.
+3. **Scan coverage.** Apply `devrites-interview` in clarify mode and mark each
+   material surface Clear, Partial, Missing, not-applicable, or justified
+   deferred-nonblocking with evidence and an owner. Use native repository search
+   first. Ask the host to run `devrites-evidence-scout` only for a bounded missing
+   fact, then reconcile its cited result.
+4. **Close decisions.** Record facts and reversible technical choices directly.
+   Ask one coherent option packet only for product, scope, policy, irreversible
+   risk, or human-only access. Persist answers in the owning artifacts and repeat
+   the scan until no blocking Partial/Missing row or unowned material assumption
+   remains.
+5. **Write the verdict.** Write `Decision coverage: CLEAR` only after re-reading all inputs and confirming
+   every material row has current evidence and an owner. Normal flow sets `Phase: clarify` and
+   `Next step: /rite-temper`. A contract-neutral later-phase return uses
+   the native restore below; changed behavior or acceptance routes to
+   `/rite-plan repair` instead. Stop without starting the next phase.
 
-## Output
+## Native clarify cursor protocol
+
+The controlling root edits only cursor rows in `state.md`; it must preserve unrelated Markdown and the file's existing table/bullet presentation.
+
+- **Normal entry from Spec:** set `phase=clarify`, `status=running`, and
+  `next_action=/rite-clarify <slug>`; omit both return fields.
+- **Already in Clarify:** no-op. Do not overwrite an existing valid return
+  cursor.
+- **Later-phase entry:** only `temper`, `define`, `plan`, `vet`, `build`,
+  `converge`, `prove`, `polish`, `review`, `seal`, or `ship` may return. First
+  copy the current `phase` and non-empty `next_action` to `return_phase` and
+  `return_next_action`; then set `phase=clarify`, `status=running`, and
+  `next_action=/rite-clarify <slug>`. Missing/unknown cursor values fail closed
+  before any write.
+- **Contract-neutral restore:** after a fresh `Decision coverage: CLEAR`, require
+  `phase=clarify`, both return fields, a recognized later `return_phase`, and a
+  non-empty `return_next_action`. Restore those values to `phase` and
+  `next_action`, set `status=running`, and remove both return fields in the same
+  rewrite. Re-read the cursor and confirm the return rows are absent.
+- **Contract changed:** do not restore the saved cursor. Record drift and route
+  through `/rite-plan repair`, which owns the changed plan and next action.
 
-Run `devrites-engine progress`, then use the shared completion reply contract
-([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)):
+Never normalize or rewrite the rest of `state.md` while applying this protocol.
+
+## Output
 
 ```text
 Done: decision coverage closed for <slug>; <n> topology surfaces scanned.

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

@@ -26,9 +26,7 @@ environment, credentials/approvals, and evidence limits.
 ```markdown
 # Decision coverage
 
-DevRites contract: devrites.readiness-artifacts.v2
 Decision coverage: <CLEAR | NEEDS CLARIFICATION>
-Coverage inputs SHA-256: <exact value from `devrites-engine readiness-digest coverage <slug>`>
 
 ## Topology
 | Surface | Kind | Related IDs | Evidence |
@@ -51,11 +49,7 @@ No Partial, Missing, unowned material assumption, or unresolved blocking/escalat
 question remains.
 ```
 
-Combine rows only when one decision and owner genuinely close them.
-
-Run the digest command only after `brief.md`, `spec.md`, `decisions.md`,
-`assumptions.md`, and `questions.md` are final for this clarification pass, then
-write the current contract field exactly once and copy the digest's complete field line
-verbatim. The build gate recomputes the digest and
-rejects stale coverage. Any open blocking, validating, or escalating question
-also prevents `CLEAR`.
+Combine rows only when one decision and owner genuinely close them. Re-read the current
+`brief.md`, `spec.md`, `decisions.md`, `assumptions.md`, and `questions.md` before writing
+`CLEAR`; the matrix itself is the freshness check. Any open blocking, validating, or
+escalating question prevents `CLEAR`.