devrites 4.1.0 → 4.3.0

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

@@ -1,131 +1,92 @@
-# Stop conditions: when autocomplete must pause for a human
-
-On these conditions, write `state.md` (`awaiting_human` or `blocked`), report
-the reason and one resume command when an actual human/safety/access action can
-change the state, notify if configured, and stop. Exhausted agent-owned
-technical recovery is terminal for its unchanged causal fingerprint: record
-`Next step: none` and no runnable recovery command. `--ship` cannot bypass them.
-Closure of a prior fingerprint is progress, not exhaustion. A separately evidenced
-Critical/Important failed invariant starts its own bounded fingerprint; it never
-resets or extends the budget of the one just closed.
-
-An exhausted consumptive-action authorization is not technical-recovery
-exhaustion. It blocks another real action, but retained evidence of a new
-Critical/Important fingerprint must enter offline caller-owned recovery while its
-own no-progress budget remains. After affected Vet is READY, pause for fresh action
-authorization; never execute from the old GO.
-
-## Always stop (irreversible-risk list: from `afk-hitl.md`)
-
-Regardless of `allow_gates` or `--ship`:
-- Destructive data migration (drop column/table, irreversible backfill).
-- Auth / authz boundary change.
-- Public-API break (response shape, removed endpoint, changed status semantics).
-- External-service contract change.
-- Filesystem destruction outside the workspace.
-
-Red checks are hard non-advance gates. Run bounded `devrites-debug-recovery`;
-on exhaustion, stop as a technical blocker unless human-owned.
-
-## Not a stop: agent-owned backtracking
-
-`NEEDS_REPLAN` is not a stop condition under an active Autocomplete caller. It
-blocks forward advancement, persists the return cursor, and immediately routes
-Plan repair plus Recovery Vet. The same applies to any intermediate nested
-`STOP`/`Next step` whose underlying decision is agent-owned.
-
-Agent-owned backtracking is not a stop condition while its causal-fingerprint
-budget remains. The active caller invokes the earlier phase inline, follows Vet
-and any bounded remediation, then resumes the originating phase. Persist
-`Next step` for crash recovery, but do not surface it as a command the human must
-submit. Use the repaired finding's narrow Vet recheck to distinguish resolution,
-the same decisive failure, and a genuinely new Critical/Important invariant.
-Stop only after three no-progress attempts on the exact same fingerprint or when
-the remaining choice is a real human/safety/access gate.
-
-On technical exhaustion, preserve the fingerprint, reproduction, attempts, and
-dead ends, then stop without `$rite-plan unblock` or another phase command.
-Reinvocation with unchanged evidence remains blocked and does not reset the cap.
-Here `unchanged` means the same fingerprint already has three recorded
-no-progress corrections. A retained fingerprint with remaining offline budget is
-not terminal merely because `state.md` was written by the failed action or a prior
-session ended.
-
-A pre-ownership workflow-artifact writer stop is not unchanged evidence when the
-current contract supplies controlling-root materialization. Prior drafter/wright refusals do not count
-as root materialization attempts. Reopen only when exact paths and executable
-behavior passed Vet and there is **no controlling-root materialization attempt**;
-record the routing migration so it cannot reset again. Missing product slices,
-unresolved protocol choices, or a recorded root attempt remain under their normal
-gate/fingerprint rules. The first controlling-root failure is not exhaustion: it
-is the first no-progress result for the materializer fingerprint. If all targets
-still equal their recorded preimages, no real action ran, and only admitted bound
-temporaries remain, reopen an incorrectly persisted one-shot `1/1` terminal,
-preserve its evidence as attempt one, clean/repair/preflight offline, and continue
-within the shared three-attempt cap.
-
-Past evidence being irretrievable is not by itself terminal. When an in-scope
-trusted diagnostic seam can make the next retained fingerprint uniquely
-actionable, Autocomplete must run diagnostic-amplification Plan repair and narrow
-Vet inline, then pause for a fresh GO before the single evidence-acquisition
-attempt. Use `Next: none` only after proving no safe in-scope amplification seam
-exists, a real human/risk/scope gate owns it, or bounded recovery is exhausted.
-
-## 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; stop before reaching seal).
-
-## Stop on strategic-review scope expansion (`$rite-temper`)
-
-- Any `expand` or added acceptance criterion pauses regardless of
-  `allow_gates`/`--ship`. Only `hold-rigor` and `reduce-to-MVP` auto-apply;
-  skipped low-stakes specs and those two modes do 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
-  direction. Do not round NO-GO up to GO.
-- **Spec Drift Guard fires** (`$rite-build` finds the plan is wrong and the change
-  alters product behaviour) → stop; route through `$rite-plan repair`.
-- **Budget exhausted with slices still pending:** any validated root-owned remaining
-  value of zero stops before the next dispatch. Report which bound won (pre-existing
-  remaining value, explicit flag, sentinel cap, or post-vet pending count) and the
-  unbuilt slices. A malformed value also fails closed. Zero with no pending slices is
-  normal completion → continue to `$rite-prove` without pausing.
-- **Resource envelope unavailable or exhausted:** stop before more work when the AFK
-  envelope is missing/malformed/expired; another run overlaps; native agent, token,
-  cost, or wall-time headroom is exhausted/unobservable despite a declared cap; or
-  unresolved review/gate backlog is above its cap. At the review cap, permit only
-  reconciliation that reduces the queue. Record the exact winning limit and observed
-  usage/count. A new activation gets fresh activation-local counters; it does not reset
-  durable slice/recovery budgets, expiry, or the recomputed queue.
-- **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:** bounded recovery exhausts → stop with reproduction.
-
-## The final type-GO
-
-- `--ship` / `--yolo` never authorizes Git. Continue through ship preflight,
-  disclose the exact plan, then stop for literal `GO` and native approval.
-- Without either flag, stop at seal GO with `$rite-ship` as the resume command.
-  Seal GO, AFK, prior approval, and flags never satisfy ship approval.
-
-## How to stop well
-
-State must be enough for a fresh agent to resume cold:
-- `state.md`: `Status`, the blocking reason, and either a single actionable
-  `Next step` command or the terminal `none — technical recovery exhausted`
-  marker.
-- The relevant `questions.md` / `drift.md` / `seal.md` entry that explains the pause.
-- A one-line user-facing message: *what* stopped it and, only when one exists,
-  *what human-owned action* resumes. A terminal technical blocker names no
-  routine Plan/Vet/retry command.
+# Stop conditions: when autocomplete pauses
+
+On a real stop, write `state.md` as `awaiting_human` or `blocked`, persist the
+reason, and include one resume command only when an actual human/safety/access
+action can change it. Exhausted agent-owned recovery records terminal
+`Next step: none` and no runnable recovery command. `--ship` never bypasses a
+stop.
+
+Authority: `.agents/skills/devrites-lib/reference/standards/acceptance-preserving-reslice.md`.
+
+<!-- BEGIN RESLICE ROUTE-TO-ACTION -->
+- `FOLD` → keep Plan repair/affected Vet internal; no stop solely for topology/count.
+- `GUARD_AND_REPAIR` → enter Spec Drift Guard/Clarify; pause only at an existing human-owned gate; resume Plan/Vet internally.
+- `BLOCKED_INPUT` → no planning writes; stop internal branch; exact diagnostic; recover authority; reclassify.
+<!-- END RESLICE ROUTE-TO-ACTION -->
+
+## Always stop
+
+Regardless of flags or AFK ceiling:
+
+- destructive data migration;
+- auth/authz boundary change;
+- public API break;
+- external-service contract change; or
+- filesystem destruction outside the workspace.
+
+Red proof cannot advance. Run bounded Debug Recovery; stop after proven
+exhaustion unless the remaining owner is human.
+
+## Not stops: internal technical routing
+
+`NEEDS_REPLAN` is not a stop condition under active Autocomplete. It blocks
+forward work, persists the return cursor, and invokes Plan repair plus Recovery
+Vet inline. The same applies to nested `STOP`/`Next step` when its decision is
+agent-owned.
+
+Agent-owned backtracking is not a stop condition while the exact causal
+fingerprint has budget. Invoke the earlier phase, affected Vet, remediation, and
+proof; then resume the origin. Stop only after three no-progress corrections of
+that exact fingerprint or a real human/safety/access gate. Preserve reproduction,
+attempts, and dead ends; never offer `$rite-plan unblock` or another routine
+phase command. Reinvocation with unchanged evidence does not reset the cap.
+`unchanged` means the same fingerprint already has three recorded no-progress
+corrections. Closure is progress; a separately evidenced Critical/Important
+invariant starts its own cap and cannot extend the closed one.
+
+Spent consumptive-action authorization is not technical-recovery exhaustion.
+It blocks another execution; retained new Critical/Important evidence still
+enters offline recovery. After affected Vet is READY, pause for fresh action
+authorization and never reuse old GO.
+
+Past evidence being irretrievable is not by itself terminal. If an in-scope
+trusted seam can uniquely discriminate the next failure, run diagnostic-
+amplification Plan repair and narrow Vet inline, then pause for fresh GO before
+one evidence-acquisition attempt. Use terminal none only when no safe in-scope
+seam exists, a real human/risk/scope gate owns it, or bounded recovery is
+exhausted.
+
+<!-- workflow-artifact-adapter: {"module":"devrites-lib/reference/standards/workflow-artifacts.md","entry":"classifier returns owner-busy, exhausted, or existing hard gate","action":"stop on exact WAIT_ACTIVE_OWNER, BLOCKED_EXHAUSTED, or BLOCKED_GATE result","return":"unchanged cursor plus fixed route-owned output"} -->
+## Other stop classes
+
+- **Gate severity:** blocking or escalating gate; any open validating question.
+- **Temper:** any `expand` or added acceptance criterion. `hold-rigor`,
+  `reduce-to-MVP`, and a justified skip do not pause.
+- **Clarify:** material Partial/Missing/unowned decision coverage or a
+  low-confidence high-consequence assumption. Continue the initial interview;
+  never arm AFK early.
+- **Seal:** NO-GO, with every blocker and fix direction. Never round up to GO.
+- **Reslice:** execute its marked action before deciding continue/stop.
+- **Slice budget:** any validated root-owned remaining value of zero stops before the next dispatch
+  when slices remain; malformed state also stops. Report whether the winning
+  bound was the pre-existing remaining value, explicit flag, sentinel cap, or post-vet pending count.
+  Zero with no pending slices is normal completion and proceeds to Prove.
+- **Resource envelope:** missing/malformed/expired AFK, overlapping run,
+  exhausted/unobservable declared agent/token/cost/time headroom, or review queue
+  above cap. At cap, only queue-reducing reconciliation may run. Persist winning
+  bound and observed usage; a new activation does not reset durable budgets or
+  expiry.
+- **Confidence:** intent still cannot become testable acceptance after interview.
+- **Repeated failure:** the exact fingerprint's bounded recovery is exhausted.
+
+## Final GO and durable stop
+
+`--ship`/`--yolo` never authorizes Git. With a flag, complete Ship preflight,
+disclose the exact plan, and stop for literal `GO` plus native approval. Without
+one, stop at Seal GO with `$rite-ship`. Seal GO, AFK, prior approval, and flags
+never satisfy Ship approval.
+
+A cold-resumable stop records `state.md` status, exact reason, and either one
+human-owned resume action or `none — technical recovery exhausted`; the owning
+question/drift/seal entry explains it. The user-facing line says what stopped
+and, only when applicable, what human action resumes it.

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

@@ -1,99 +1,64 @@
 ---
 name: rite-build
-description: Build the next approved vertical slice with evidence. HITL stops after one; explicit AFK may chain bounded green slices.
-argument-hint: "[slice number or name]"
+description: Build the next approved vertical slice with evidence. HITL one-slice default; AFK may chain serially; opt-in `--parallel N` (2≤N≤3) for path-disjoint worktrees.
+argument-hint: "[--parallel N] [slice number or name]"
 user-invocable: true
 ---
 
 # $rite-build: one verified slice
 
 Build and prove one slice. HITL stops; a later user invocation starts the next.
-Explicit `.devrites/AFK` alone lets the controlling root chain pending slices,
-only under existing green-proof, cap, and pause rules. **Read the active workspace
-first**; if none, tell the user to run `$rite-spec <feature>`.
+Explicit `.devrites/AFK` alone lets the controlling root chain pending slices
+serially under green proof, caps, and pause rules. Every wright returns after it.
+**Opt-in:** `$rite-build --parallel N` (2≤N≤3; N=1≡serial) follows
+[`reference/parallel-batch.md`](reference/parallel-batch.md).
 
-The root owns gates/workspace; a
-fresh-context [`devrites-slice-wright`](.codex/agents/devrites-slice-wright.toml)
-writes product source and tests. Exact Vet-ready executable workflow artifacts use
+Root owns gates/bookkeeping. Fresh
+[`devrites-slice-wright`](.codex/agents/devrites-slice-wright.toml) writes product
+source/tests. Workflow Artifact paths use
 [`workflow-artifacts.md`](../devrites-lib/reference/standards/workflow-artifacts.md).
-Apply the readiness, selection, host, HITL/AFK,
-dispatch, doubt, fail-on-red, record, and stop checks. See
+Execute [`reference/phase-contract.md`](reference/phase-contract.md); dispatch uses
 [`reference/wright-dispatch.md`](reference/wright-dispatch.md).
 
-## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
-Read `.agents/skills/devrites-lib/reference/standards/core.md` first. The wright
-reads named on-demand rules while writing; root reads them for doubt/record gates:
-- `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.
-- `repository-topology.md`: when targets span roots/languages/services or touch generated/vendor surfaces.
-- `data-integrity.md`: when the slice writes durable state or changes migration/concurrency/tenant/retention behavior.
-- `integration-reliability.md`: when the slice changes an API/webhook/queue/job/cache/cross-service boundary.
-- `definition-of-done.md`: standing Done bar: acceptance mapped, fresh proof, no open hard gates, scoped edits, rollback/docs where needed.
+## Required rules
 
+Read `.agents/skills/devrites-lib/reference/standards/core.md` first. Load only triggered rules:
+coding/error/testing/[`tdd.md`](reference/tdd.md)/patterns/DoD; binding
+`.devrites/principles.md`; security; topology; data integrity; integration reliability.
+Wright applies anti-slop; root verifies returns and never patches source.
 
-## Operating rules
-- **One slice per wright dispatch.** Every wright returns after it. The controlling
-  root applies the mode rule above before another dispatch. Prefer the guarded serial
-  native-worktree pilot in `wright-dispatch.md` only when its committed-clean
-  preflight and explicit reconciliation path both hold; otherwise use the existing
-  serial same-worktree writer. Never run writers in parallel.
-- Evidence over confidence. Prefer existing conventions. Feature scope only: no
-  drive-by refactors.
-- **Record adjacent issues; do not edit them.** An issue outside the exact paths
-  stated in the dispatch task 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 root rejects a returned diff outside 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 (`.agents/skills/devrites-lib/reference/standards/prose-style.md`; depth in `devrites-prose-craft`): no
-  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
-  principle was broken**; a fresh violation is handled like any irreversible-risk item: a
-  human-approved, scoped exception in the register or a stop, never folded into the slice. No
-  `.devrites/principles.md` → none declared → nothing to honor.
-- **You never edit product source/tests.** You write `.devrites/` bookkeeping and,
-  only through `workflow-artifacts.md`, an exact Vet-ready executable workflow-artifact set.
-  Follow the
-  host gate in `wright-dispatch.md` before every build or recovery dispatch. On a
-  supported host, the wright is the only writer of code and tests. Codex gives
-  the root workspace permission only so that native writer dispatch can execute;
-  never patch code from the root. Put the exact project-relative source/test path
-  list directly in the task, dispatch the exact `devrites-slice-wright`, then
-  compare `git diff --name-only` with those task paths. Any extra source file is
-  a hard STOP.
-- **Executable workflow-artifact branch.** If every implementation target is an
-  exact admitted path under the active `.devrites/work/<slug>/`, the controlling
-  root materializes and proves that atomic set itself. It does not dispatch the wright,
-  decrement/count a product slice, update the candidate manifest, or execute the
-  consumptive action. After narrow Vet, restore the caller cursor.
+## Invariants
 
-## Workflow
+- Default: one slice; writers serial on control. Parallel only via `--parallel N`
+  under [`reference/parallel-batch.md`](reference/parallel-batch.md). Same-worktree
+  multi-writer / root-emulated concurrency forbidden. Native-worktree pilot =
+  single-slice isolation when `wright-dispatch.md` preflight + reconcile hold.
+- Exact feature scope only; reject out-of-allowlist diffs; record adjacent issues.
+- Never rerun an unchanged check; re-prove after edits.
+- Unplanned dependency/design-system/gap/repair → Vet/Spec Drift Guard. Ask only
+  for licensing/cost/security/product or explicit architecture-policy decisions.
+- Root never edits product source/tests (`.devrites/` + Workflow Artifact only).
+  Wright is sole product writer; extras in returned paths/`git diff --name-only` hard-stop.
+- Principles bind; irreversible conflict needs human exception or stop.
+- Evidence beats confidence. Never weaken tests, skip TDD, widen writers, or
+  self-approve. Drift → [`spec-drift-guard.md`](reference/spec-drift-guard.md);
+  checkpoint → [`checkpoint.md`](reference/checkpoint.md).
 
-Run the full execution contract in
-[`reference/phase-contract.md`](reference/phase-contract.md). It is not optional:
-it contains the gated one-slice workflow, including readiness, HITL/AFK handling,
-wright dispatch, doubt, fail-on-red, record gates, and stop behavior.
+## Workflow Artifact branch
 
-## Output
+<!-- workflow-artifact-adapter: {"module":"devrites-lib/reference/standards/workflow-artifacts.md","entry":"Vet-ready admitted bytes require root authorship outside product wright","action":"ROOT_TRANSACTION; root writes only admitted .devrites/** targets","return":"saved Build slice cursor; wright product allowlist unchanged"} -->
+## `--parallel N` (opt-in)
 
-Use [`reference/output.md`](reference/output.md) and the shared
-[`reply contract`](../devrites-lib/reference/reply-contract.md). They keep the
-HITL stop, bounded AFK chaining, and no-automatic-`$rite-prove` boundary explicit.
+Omitted/`1` ≡ serial; `2`/`3` → path-disjoint fan-out when eligible; else hard refuse.
+All-green serial integrate; one red/gap aborts. AFK charges after integrate only.
+Running lease blocks another `$rite-build`. Details: `parallel-batch.md`.
+
+## Execute and reply
+
+Run every step in `reference/phase-contract.md`: readiness, one target, dispatch
+or canonical transaction, return inspection, independent doubt/test analysis,
+approved fail-on-red proof, record, AFK accounting, and stop. Use
+[`reference/output.md`](reference/output.md) plus the shared
+[`reply contract`](../devrites-lib/reference/reply-contract.md). HITL never starts
+the next slice automatically; AFK chains only within its durable remaining
+budget; Prove starts only after all slices are built.

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

@@ -8,16 +8,8 @@ Load the shared
 contract for the sentinel schema, defaults, gate ceiling, and mutable-counter
 ownership. This file owns only Build's dispatch, charging, and red-path behavior.
 
-These rules follow established autonomous-coding loops, including Ralph Wiggum and
-Claude Code auto mode:
-
-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.
+Rules: green before `built`; hard `max_slices` cap; gates before the action they
+control; irreversible work (destructive/auth/public API) always pauses.
 
 ## Iteration cap
 
@@ -41,32 +33,33 @@ The controlling root owns the cap:
    A controlling orchestrator may pre-seed the remaining field from a validated
    post-plan budget before the first dispatch; never increase or reinitialize an
    existing value.
-3. **Charge exactly once after each green built slice.** A slice already marked
-   built is not charged again after retry, resume, or compaction. Re-read the
-   saved cursor; if it is zero, report the cap and stop before the next
-   dispatch.
+3. **Charge exactly once after each green built slice.** On the control tree, a slice
+   already marked built is not charged again after retry, resume, or
+   compaction. Re-read the saved cursor; if it is zero, report the cap and stop
+   before the next dispatch.
+   - **Serial:** charge when fail-on-red is green and the built record is written
+     (same rewrite as step 2).
+   - **Parallel `--parallel`:** charge only after **successful serial integrate**
+     — once per integrated green sibling. Abort / integrate-failed → charge **0**.
+     Do not charge on worktree-green before integrate. See
+     [`parallel-batch.md`](parallel-batch.md).
 
 Use this stop message:
 
-```
+```text
 AFK cap reached. Raise `state.md` `AFK slices remaining` or remove the sentinel to continue.
 ```
 
 `max_slices` itself is read-only and never rewritten. No exit-code command
 enforces this policy.
 
-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.
+Choose caps deliberately (≈5–10 small, ≈30–50 larger). Avoid `unlimited` until HITL
+has succeeded for the work.
 
 ## Fail-on-red
 
-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 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 step** refuses `built` when targeted tests/types/lint are red. Red means
+wrong contract or proof path — agent-owned recovery; never advance on broken state.
 
 The fail-on-red path:
 
@@ -105,7 +98,7 @@ The hook is a single shell command run on the `awaiting_human` transition. Envir
 the hook receives:
 
 | Var | Value |
-|---|---|
+| --- | --- |
 | `DEVRITES_QID` | the new qid (e.g. `q-2026-05-28-001`) |
 | `DEVRITES_GATE` | `advisory` / `validating` / `blocking` / `escalating` |
 | `DEVRITES_SLICE` | `<N — name>` |
@@ -117,6 +110,7 @@ The hook is best effort: a non-zero exit does **not** roll back the pause. Failu
 logged to `evidence.md` so the user sees them on return.
 
 Example targets:
+
 - `curl -d "$DEVRITES_QID: $DEVRITES_QUESTION" ntfy.sh/my-topic`
 - `osascript -e "display notification \"$DEVRITES_QUESTION\" with title \"DevRites: $DEVRITES_GATE\""`
 - `pb push "$DEVRITES_SLUG: $DEVRITES_QUESTION"` (via pushbullet CLI)

package/pack/generated/codex/skills/rite-build/reference/checkpoint-protocol.md

@@ -1,29 +1,22 @@
 # Checkpoint protocol: what `$rite-build` does when a slice is HITL
 
-When `$rite-build` reaches a slice with `Mode: HITL`, it does **not** start writing code. It
-surfaces the checkpoint as a ranked **option set** and resolves it **before** any code lands:
+HITL slices pause **pre-action** as a ranked **option set** before any code:
 
-- **Human present (interactive):** ask inline via `AskUserQuestion` (the option set below).
-  The human picks; record the pick to `questions.md` (`answered`) + `decisions.md`, clear the
-  gate, and **continue building in place**: no STOP, no `$rite-resolve` round-trip.
-- **Human absent / AFK-pausing / notify-only:** persist the checkpoint (`questions.md` open +
-  `state.md` `Awaiting human`), fire the `notify:` hook, and **stop**. Resume later via
-  `$rite-resolve` (or `--batch`).
-
-Either way the pause is **pre-action**, not post-action: code never lands before the gate.
+- **Interactive:** `AskUserQuestion`; record to `questions.md`/`decisions.md`; clear gate;
+  continue in place (no `$rite-resolve` round-trip).
+- **Absent / AFK / notify-only:** persist open question + `Awaiting human`, notify, **stop**.
+  Resume via `$rite-resolve` (or `--batch`).
 
 ## Render contract
 
-The checkpoint must be rendered in user-facing output **and** persisted to the workspace.
-Both are required: the output is for the human in the room (or the notification target),
-the persisted form is for the next session or the AFK observer.
+Render the checkpoint in user-facing output **and** persist it for the next session / AFK
+observer.
 
 ### User-facing render: the option set
 
-Present the checkpoint as an `AskUserQuestion` with a ranked **option set**
-(`afk-hitl.md` → "Option set"): 2-4 options, **recommended first** + labelled `(Recommended)`,
-each option's description carrying the dimension-tagged rationale + the trade-off it accepts,
-plus the escape hatch. The header names the slice + gate:
+Present as `AskUserQuestion` ranked **option set** (`afk-hitl.md`): 2–4 options,
+recommended first + `(Recommended)`, dimension-tagged trade-offs, plus escape hatch.
+Header names slice + gate:
 
 ```
 Slice <N — name> — HITL (<gate>, SLA <SLA>). <Checkpoint text from tasks.md>
@@ -35,12 +28,9 @@ Slice <N — name> — HITL (<gate>, SLA <SLA>). <Checkpoint text from tasks.md>
   4. Something else — I'll describe it
 ```
 
-The recommended option (#1) is **required**: a checkpoint without a recommendation is a worse
-interrupt than one with shape; the human reacts to a ranked draft faster than to a blank prompt
-(the "give the human something to approve" rule). The recommendation reflects *this* project
-(its conventions, stack, scale), not a generic default. On an interactive pick, resolve in
-place; when persisting a pause instead, the same set is written to `questions.md` `options:`
-and the resume line is `$rite-resolve <qid> "<answer>"` (or `--drop <qid> "<reason>"`).
+Option #1 (recommended) is **required** and must reflect *this* project. Interactive pick →
+resolve in place; pause → persist the same set to `questions.md` `options:` with resume
+`$rite-resolve <qid> "<answer>"` (or `--drop <qid> "<reason>"`).
 
 ### Workspace mutations
 
@@ -93,9 +83,7 @@ rewrite; do not claim cross-file atomicity):
    sh -c "$notify_cmd"
    ```
 
-   The hook fires after the workspace write so the notification target sees a workspace
-   that already records the pause. Failures in the hook **do not** roll back the pause:
-   the gate is authoritative; the notification is best-effort.
+   Fire after workspace write. Hook failure does **not** roll back the pause (best-effort).
 
 ## qid generation
 
@@ -109,42 +97,24 @@ reservation or engine command for qids.
 
 ## When AFK is active
 
-If `.devrites/AFK` exists and the slice's `Gate` is in `allow_gates`, `$rite-build` does
-**not** invoke the checkpoint protocol. Instead:
-
-- For `advisory`: log a `gate: advisory` entry to `questions.md`, record the trade-off in
-  `decisions.md`, and **dispatch the wright** to build the slice (workflow step 3).
-- For `validating` (only when `allow_gates` includes it): **dispatch the wright** (step 3); on
-  return, write a `gate: validating` entry to `questions.md`, mark the slice
-  `built (pending review)` in `state.md`, and continue. A slice's only states are `pending` and `built`:
-  acceptance is proven at the **feature** level by `$rite-prove` (recorded in
-  `evidence.md`), not per slice. The `built (pending review)` slice is not done until the
-  open `validating` gate resolves via `$rite-resolve`; an open `validating` gate is a
-  NO-GO at seal.
-
-For gates in `allow_gates`, AFK **auto-picks the recommended option** (option 1 of the set)
-instead of pausing, recording it as above. For `blocking` and `escalating` (and every
-irreversible-risk item), AFK **always** invokes the checkpoint protocol: the sentinel does
-not unlock these gates and no AFK key can override them. See `afk-discipline.md`
-for the irreversible-risk list.
+If `.devrites/AFK` exists and the slice `Gate` is in `allow_gates`, skip this protocol and
+auto-pick recommended option 1:
+
+- `advisory`: log `gate: advisory` + `decisions.md`, then dispatch wright.
+- `validating` (only if allowed): dispatch wright; on return log `gate: validating`, mark
+  `built (pending review)`, continue. Slice states remain `pending|built`; feature
+  acceptance is `$rite-prove`. Open `validating` is NO-GO at seal until `$rite-resolve`.
+
+`blocking` / `escalating` / irreversible-risk always use this protocol (`afk-discipline.md`).
 
 ## Multi-question pauses
 
-The current protocol is **one question per pause**. If a slice has multiple HITL
-checkpoints, split it into sub-slices via `$rite-plan reslice` so each pause is
-single-question. Multi-question pauses are reserved future shape; `Awaiting human` is
-written as a single block.
+**One question per pause.** Multiple HITL checkpoints → `$rite-plan reslice`.
 
 ## What NOT to do
 
-- **Don't write code first and pause after.** The pre-action rule is the whole point.
-- **Don't render the checkpoint without persisting.** Output without `state.md` + `questions.md`
-  updates means the workspace lies on `/clear`.
-- **Don't self-answer a question that *paused* for a human.** When a gate stopped the session
-  (an AFK queue, or a HITL pause the human walked away from), `$rite-resolve` requires an
-  explicit answer: the agent doesn't confirm its own `proposed:` on resume. This is distinct
-  from the two legitimate auto-resolutions: an interactive `AskUserQuestion` pick the human
-  just made, and an AFK auto-pick of the recommended option on a gate `allow_gates` permits.
-- **Don't bundle the `notify:` hook output into chat.** Fire-and-forget; the chat already
-  has the user-facing render.
-- **Don't fire `notify:` on `advisory`-downgraded entries.** It's reserved for true pauses.
+- Don't write code then pause — pre-action only.
+- Don't render without persisting `state.md` + `questions.md`.
+- Don't self-answer a human pause via `proposed:` — `$rite-resolve` needs an explicit
+  answer (distinct from interactive pick / AFK auto-pick on `allow_gates`).
+- Don't put `notify:` output in chat; don't fire `notify:` on advisory-only entries.