devrites 3.0.7 → 3.1.0

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

@@ -5,20 +5,17 @@ argument-hint: "[path or area to adopt] [+ what you want to build next]"
 user-invocable: true
 ---
 
-# /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 `.claude/skills/devrites-lib/reference/standards/`)
 Pull `documentation.md` when recording the adoption decisions (why-not-what) in
@@ -37,7 +34,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 `.claude/skills/devrites-lib/reference/standards/tooling.md`) for
@@ -52,10 +49,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
@@ -63,29 +60,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
 
@@ -96,8 +92,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/.claude/skills/rite-autocomplete/SKILL.md

@@ -7,33 +7,36 @@ user-invocable: true
 
 # /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 `.claude/skills/devrites-lib/reference/standards/`)
 **Step 0:** Read `.claude/skills/devrites-lib/reference/standards/core.md` and `.claude/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
@@ -49,19 +52,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.
@@ -71,12 +77,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`.
@@ -84,7 +89,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/.claude/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/.claude/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

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

@@ -7,13 +7,13 @@ user-invocable: true
 
 # /rite-build: one verified slice
 
-Build the next single slice, leave it working and proven, then **stop**. **Read the
-active workspace first**; if none, tell the user to run `/rite-spec <feature>`.
+Build and prove one slice, then **stop**. **Read the active workspace first**; if none,
+tell the user to run `/rite-spec <feature>`.
 
-This skill is the **orchestrator**: it owns the gates and the workspace; a fresh-context
-[`devrites-slice-wright`](../../agents/devrites-slice-wright.md) owns the **writing**. You run
-pre-flight (readiness, slice select, HITL pause), dispatch the wright for the build core, then
-run the post-return gates (doubt, fail-on-red, record, stop). See
+This skill owns the gates and workspace. A fresh-context
+[`devrites-slice-wright`](../../agents/devrites-slice-wright.md) writes source and tests.
+Run the readiness, slice-selection, and HITL checks; dispatch the wright; then run the
+doubt, fail-on-red, recording, and stop checks. See
 [`reference/wright-dispatch.md`](reference/wright-dispatch.md).
 
 ## Rules consulted (read on demand from `.claude/skills/devrites-lib/reference/standards/`)
@@ -23,6 +23,8 @@ writes; read them yourself for the doubt/record gates or in the inline fallback:
 - `coding-style.md`: naming, function shape, guard clauses, comments, reuse-first.
 - `error-handling.md`: fail fast, no silent catches, fail closed.
 - `testing.md`: pyramid, behaviour over implementation, see-it-fail-first.
+- [`reference/tdd.md`](reference/tdd.md): the slice-level Red → Green → Refactor
+  and Prove-It contract.
 - `patterns.md`: composition over inheritance, avoid premature abstraction.
 - `principles.md`: the project invariants (`.devrites/principles.md`) the slice must honor; the wright reads them as **binding**, not priors.
 - `security.md`: when the slice touches user input, auth, data, or external integrations.
@@ -33,23 +35,24 @@ writes; read them yourself for the doubt/record gates or in the inline fallback:
 - **One slice at a time. DO NOT** start the next slice without the user asking.
 - Evidence over confidence. Prefer existing conventions. Feature scope only: no
   drive-by refactors.
-- **Noticed, not touched.** An adjacent smell the wright sees outside `touched-files.md` is
-  recorded as an FYI follow-up in `decisions.md`, never fixed inline: the slice's change summary
-  states what it *deliberately left alone* ([`git-workflow.md`](../devrites-lib/reference/standards/git-workflow.md) "Things
-  I didn't touch"), so the reviewer reads a feature-scoped diff, not a renovation. The `devrites-engine reconcile`
-  gate (step 6) enforces this by exit code.
-- **Don't re-run an unchanged check.** Re-running the same build/test command on code that hasn't
-  changed since proves nothing new. It's motion, not evidence. Re-verify after an edit, not before.
-- Surface material assumptions; ask before adding dependencies or a second design
-  system. The [Spec Drift Guard](reference/spec-drift-guard.md) is active throughout.
-- **Avoid AI slop while writing.** `devrites-slice-wright` enforces the anti-slop charter **at
-  the source**: the canonical do-not list is `rite-polish/reference/anti-ai-slop.md` (the
-  wright reads it; don't restate it here). It writes the code the *project* would write, in its
-  idiom, reusing before building; **you verify the charter held on return**. You do not re-list
-  it and you do not fix slop by editing source. Polish catches what slips; build prevents.
+- **Record adjacent issues; do not edit them.** An issue outside the captured
+  `.wright-allowlist` becomes an FYI follow-up in `decisions.md`. The slice summary states
+  what it deliberately left alone ([`git-workflow.md`](../devrites-lib/reference/standards/git-workflow.md)
+  "Things I didn't touch"). The `devrites-engine reconcile` gate enforces this boundary.
+- **Don't re-run an unchanged check.** The same build or test on unchanged code provides
+  no new evidence. Re-verify after an edit.
+- Surface material assumptions. Do not introduce an unplanned dependency or second design
+  system: route the objective plan gap to `/rite-vet` (or bounded recovery), not to a human.
+  Ask only if the newly exposed choice changes licensing/cost/security, product behavior,
+  or an explicit architecture policy. The
+  [Spec Drift Guard](reference/spec-drift-guard.md) is active throughout.
+- **Avoid AI slop while writing.** `devrites-slice-wright` applies the anti-slop charter
+  while writing. The canonical list is `rite-polish/reference/anti-ai-slop.md`; do not
+  duplicate it here. The wright follows project idioms and reuses existing code first.
+  **Verify the charter on return.** Do not correct source from the orchestrator.
   The **prose you write yourself** (`evidence.md`, `decisions.md`, the slice report) follows
   the human-voice charter (`.claude/skills/devrites-lib/reference/standards/prose-style.md`; depth in `devrites-prose-craft`): no
-  filler openers, no marketing adjectives, exact commands and identifiers kept verbatim.
+  filler openers or marketing adjectives; preserve exact commands and identifiers.
 - **Honor declared project principles.** The wright reads `.devrites/principles.md` and treats
   each invariant as **binding** (not a prior to weigh like a convention): a slice it cannot build
   without breaking one is an **Escalation**, not a silent violation. On return **you verify no
@@ -58,15 +61,17 @@ writes; read them yourself for the doubt/record gates or in the inline fallback:
   `.devrites/principles.md` → none declared → nothing to honor.
 - **You never edit source: the wright is the only writer of code + tests.** You write only
   `.devrites/` bookkeeping. On any red gate, doubt finding, or coverage gap your only remedies
-  are **continue the same wright once** (it fixes in its own context) or **stop + escalate**:
-  never patch the code yourself. The `devrites-engine reconcile` gate (step 6) enforces this by exit code:
-  any source file changed outside the wright's claimed set is a hard STOP.
-- **A `Forge: yes` slice competes candidates: one author still lands.** When `/rite-vet`
-  flagged the slice a genuine architecture fork, step 3 runs K=2-3 candidate wrights in
-  **isolated worktrees** and lands exactly one winner's diff; the single-writer invariant holds
-  because no tree ever has two authors and only the winner reaches the working tree. You still
-  never edit source, and reconcile runs against the winner's claimed set. The default slice is
-  single-path: forge is the rare exception ([`reference/forge.md`](reference/forge.md)).
+  are to continue the same wright under bounded `devrites-debug-recovery` (three total attempts
+  per root cause) or stop with the correctly classified blocker: never patch the code yourself
+  and never ask the human to authorize agent-owned repair work. The `devrites-engine reconcile`
+  gate enforces this against the root-owned pre-dispatch allowlist: any source file changed
+  outside that exact set is a hard STOP.
+- **Forge is manifest-owned, winner-takes-all.** For a fully typed `Forge: yes`
+  slice, follow [`reference/forge.md`](reference/forge.md): `forge plan` precedes
+  reconciliation; every candidate is bound to its isolated worktree and live worker;
+  the judge records one winner; normal reconciliation and proof pass before manifest-only
+  cleanup and the human report. Any stale/ineligible flag uses one serial wright before
+  Forge creates state.
 
 ## Workflow
 

package/pack/.claude/skills/rite-build/reference/afk-discipline.md

@@ -1,19 +1,18 @@
-# AFK discipline: running `/rite-build` unattended without burning the trunk
+# AFK discipline for unattended `/rite-build`
 
-AFK mode is `.devrites/AFK` present. It lets `/rite-build` chain slices without per-slice
-user input. The discipline below is what keeps an AFK loop from drifting into damage.
+AFK mode is active when `.devrites/AFK` exists. It lets `/rite-build` chain slices
+without per-slice user input. The rules below limit that unattended work.
 
-The core principles are borrowed from established autonomous-coding loops (Ralph Wiggum,
-Claude Code auto mode):
+These rules follow established autonomous-coding loops, including Ralph Wiggum and
+Claude Code auto mode:
 
-1. **Feedback loops are the trust substrate.** No green tests / types / lint → no
-   "built" status. The loop can't declare victory if the lights are red.
-2. **Always cap iterations.** Stochastic systems + infinite loops = unsafe. `max_slices`
-   is the hard counter.
-3. **Promote pre-action gates, demote post-action gates.** Code that lands without a
-   gate is a finding; gates after the fact are review queues.
-4. **AFK widens what's automatic, never what's irreversible.** Destructive work, auth
-   boundaries, public API breaks always pause regardless of the sentinel.
+1. **Require green feedback.** Tests, types, and lint must pass before a slice is
+   marked `built`.
+2. **Cap iterations.** `max_slices` is the hard limit.
+3. **Run gates before the action they control.** A post-action gate is only a review
+   queue.
+4. **Keep irreversible work manual.** Destructive work, auth boundaries, and public
+   API breaks always pause regardless of the sentinel.
 
 ## The sentinel file
 
@@ -35,8 +34,7 @@ Defaults when keys are omitted:
 - `notify`: none.
 - `allow_gates`: `[advisory]`.
 
-To disable AFK temporarily, delete the file. The next `/rite-build` boots straight back
-into HITL.
+To disable AFK, delete the file. The next `/rite-build` runs in HITL.
 
 ## Iteration cap
 
@@ -55,29 +53,31 @@ The cap is enforced by `devrites-engine tick-afk`, not by prose, when it exits 3
 Step 0 re-derives the remaining budget from `state.md` (seeding it from `.devrites/AFK`
 `max_slices` on the first AFK build); `max_slices` itself is read-only and never rewritten.
 
-The cap is intentional: a missing or large cap **must be a conscious choice**. Ralph's
-rule: 5-10 iterations for small tasks, 30-50 for larger ones. Don't ship "unlimited" as
-the default for a job you haven't observed running once HITL.
+Choose a missing or large cap deliberately. Ralph's rule is 5-10 iterations for small
+tasks and 30-50 for larger ones. Do not use `unlimited` for work that has not completed
+successfully in HITL.
 
 ## Fail-on-red
 
-The **fail-on-red step** (workflow step 5) refuses to mark a slice `built` if targeted tests /
-types / lint are red. The reasoning:
+The **fail-on-red step** (workflow step 5) refuses to mark a slice `built` if targeted
+tests, types, or lint are red:
 
-- A red signal means either the slice's contract is wrong or the failing code is. Neither
-  is something AFK can resolve.
-- Marking it `built` and letting the AFK loop chain to the next slice burns the trunk:
-  the next slice builds on broken state.
+- A red signal means either the slice's contract is wrong or the implementation/proof path is.
+  The slice cannot advance, but an objective root cause is agent-owned recovery work.
+- Marking it `built` would let the next slice build on broken state.
 
 The fail-on-red path:
 
-1. Append a question to `questions.md` with `gate: blocking`, the SLA of the slice, and a
-   crisp `question:` field naming what failed.
-2. Set `state.md` `Status: awaiting_human` and the `Awaiting human` block.
-3. Fire the `notify:` hook if defined.
-4. STOP.
+1. Continue the same wright under `devrites-debug-recovery`, carrying exact output and dead
+   ends; cap writer + recovery at three total attempts per root cause.
+2. Green → record the slice. Product-contract/irreversible ambiguity → write the genuine
+   human gate. Missing human-only credential/permission → write a human-intervention gate.
+3. Any other exhausted objective failure → set `Status: blocked`, preserve the reproduction,
+   set `Next step: /rite-plan unblock`, and STOP without a qid.
+4. Fire `notify:` only for an actual `awaiting_human` transition.
 
-The user resolves via `/rite-resolve` after diagnosing or re-planning.
+AFK never starts the next slice while checks are red and never asks the human to approve
+agent-owned diagnosis or parser/test repair.
 
 ## Irreversible-risk list (always pause)
 
@@ -92,8 +92,8 @@ any of:
   rewriting `.gitignore`-listed paths, deleting fixtures).
 - Anything the slice's `Gate: blocking` plus `tasks.md` `Why HITL:` flags as irreversible.
 
-The list is the same one Claude Code auto-mode's transcript classifier protects: adapted
-to DevRites's workspace shape.
+This is the Claude Code auto-mode transcript classifier list adapted to the DevRites
+workspace.
 
 ## The `notify:` hook contract
 
@@ -109,7 +109,7 @@ the hook receives:
 | `DEVRITES_QUESTION` | the checkpoint text |
 | `DEVRITES_PROPOSED` | the proposed answer |
 
-The hook is best-effort: non-zero exit does **not** roll back the pause. Failures are
+The hook is best effort: a non-zero exit does **not** roll back the pause. Failures are
 logged to `evidence.md` so the user sees them on return.
 
 Example targets:
@@ -117,20 +117,20 @@ Example targets:
 - `osascript -e "display notification \"$DEVRITES_QUESTION\" with title \"DevRites: $DEVRITES_GATE\""`
 - `pb push "$DEVRITES_SLUG: $DEVRITES_QUESTION"` (via pushbullet CLI)
 
-DevRites owns no notification logic: the hook is a seam, not a feature.
+DevRites does not implement notifications; the configured hook does.
 
 ## When to leave AFK
 
 Drop the sentinel before:
 
-- A novel feature where you have not yet seen `/rite-build` work on this codebase HITL:
-  Ralph's progression: HITL first → refine prompt → AFK once trusted.
+- A new feature when `/rite-build` has not yet completed successfully on this codebase
+  in HITL. Ralph's progression is HITL first → refine prompt → AFK after validation.
 - A risky slice you marked `Mode: HITL` and want to walk through interactively even if
   the gate is technically `validating`.
 - Any time you'd rather review per-slice than batch-resolve afterwards.
 
-AFK is a **bias toward continuing**, not a vow. Re-enter it whenever the next stretch of
-work is bulk + low-stakes.
+AFK allows routine work to continue automatically. Re-enable it for another batch of
+low-stakes work.
 
 ## What AFK does NOT do