devrites 4.7.0 → 5.0.0

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

@@ -0,0 +1,116 @@
+# The autocomplete loop: arm AFK, drive every phase
+
+Autocomplete sequences existing `/rite-*` workflows without pausing between
+routine phases. Acceptance-preserving Reslice authority is
+`.omp/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 -->
+
+## Arm AFK once
+
+```yaml
+allow_gates: [advisory]
+max_slices: 10
+max_agents: 32
+max_minutes: 120
+max_review_queue: 8
+expires_at: "<now + 4 hours>"
+# max_tokens: <N>
+# max_cost_usd: <amount>
+# notify: "<cmd>"
+```
+
+Read an existing sentinel first. Preserve it byte-for-byte when valid; stop if
+its gate ceiling exceeds advisory, required envelope is malformed/expired, or
+`max_slices` conflicts with the invocation. If absent, write it once after
+clarity, replacing the safe slice default only for explicit `--max-slices N`
+and resolving one absolute UTC expiry. It is read-only: never rewrite it after
+Vet or reset it on resume.
+
+### Derive the mutable post-vet budget
+
+After Vet, count pending slices and take the minimum of that count, explicit
+flag, and sentinel cap. Before first Build, seed absent state-owned
+`afk_slices_remaining`; retain the lower valid existing value and never increase
+or reinitialize it. AFK configuration itself stays unchanged.
+
+### Admit each unattended cycle
+
+Before every phase, review fan-out, recovery, or writer dispatch, apply
+`afk-hitl.md#unattended-resource-envelope`: cheapest current-state/readiness
+check first; reject overlap; count unresolved review; check expiry and native
+agent/token/cost/time headroom. Count every leaf result. At the review cap, only
+reconciliation that reduces the queue may run. Any reached or unobservable
+bound stops before more work and persists the winning reason. A new activation
+gets fresh activation-local counters but retains durable slice/recovery state,
+expiry, and recomputed queue.
+
+`allow_gates: [advisory]` means validating gates pause now rather than becoming
+Seal NO-GO. Only explicit human configuration outside Autocomplete may widen it.
+
+## Phase arc
+
+Workspace files carry state; chat does not. Read and execute each phase skill:
+
+| Step | Phase | Completion / edge |
+| --- | --- | --- |
+| 1 | `/rite-spec` | investigate and write testable intent |
+| 2 | `/rite-clarify` | topology-first scan; require `Decision coverage: CLEAR`, then arm AFK |
+| 3 | `/rite-temper` | harden or reduce; expansion and irreversible risk pause |
+| 4 | `/rite-define` | approved plan/tasks/traceability |
+| 5 | `/rite-vet` | every plan; derive mutable budget after READY |
+| 6 | `/rite-build` ×N | one pending slice per wright; charge once only after green built state |
+| 7 | `/rite-prove` | all slices built; approved proof; recovery on red |
+| 8 | `/rite-polish` | re-prove after code edits |
+| 9 | `/rite-review` | in-scope correction then fresh proof |
+| 10 | `/rite-seal` | GO/NO-GO; no Git |
+| 11 | `/rite-ship` | only after GO; `--ship` never authorizes Git; stop at literal-GO/native approval |
+
+Before advancing, check resource admission and
+[stop-conditions.md](stop-conditions.md). After source edits, discard stale pass
+evidence. Re-read the active workspace before each phase.
+
+## Backtrack without handing off
+
+The active Autocomplete root remains caller whenever a later phase exposes an
+agent-owned earlier-phase gap:
+
+1. Save the originating phase/action unless a valid native return cursor exists.
+2. On cold resume, reconcile the terminal cursor against durable fingerprint
+   accounting. Restore `return_next_action` only from the approved
+   `test-plan.md`/evidence action; ambiguity returns to Vet and never licenses
+   execution.
+3. Invoke required Plan repair, affected Vet, remediation, and proof inline.
+   Recovery Vet is a narrow Vet recheck of prior findings, changed paths/criteria,
+   and affected evidence; it never restarts unaffected axes. A nested `STOP`
+   ends that phase only; do not hand the intermediate command to the user.
+4. Re-read state after each nested phase. Reconcile exact causal fingerprints
+   from `drift.md`/`evidence.md`. A closed reproduction is progress. A different
+   Critical/Important invariant gets a separate budget; Suggestion/Nit/FYI does
+   not prolong the chain. Only a no-progress result charges the same fingerprint.
+5. For failed consumptive action, spent authorization blocks only another real
+   execution. Use retained evidence for offline diagnosis, repair, and narrow
+   Vet; after READY, pause for fresh authorization.
+6. Restore and consume the original cursor when prerequisites are green.
+
+<!-- workflow-artifact-adapter: {"module":"devrites-lib/reference/standards/workflow-artifacts.md","entry":"loop tick sees Workflow Artifact trigger/state","action":"invoke classifier once under owner lock; no actor-history migration","return":"same loop cursor; no budget charge for verify/rerun"} -->
+Ask only for a human-owned decision or mandatory safety/access action. Three
+no-progress corrections of one exact fingerprint exhaust; preserve its
+reproduction and dead ends without another Plan/Vet command.
+
+## Continuous caller obligation
+
+No user-facing reply is permitted while durable state contains agent-owned
+`NEEDS_REPLAN`, an intermediate Plan/Vet action, or a distinct retained
+Critical/Important fingerprint below its cap. Invoke the next internal repair
+immediately. A narrow reviewer closing one finding and exposing another
+Critical/Important invariant is progress, not exhaustion.
+
+The number of completed repair/Vet cycles is not a stop condition. Context
+pressure, compaction, session duration, and nested completion do not convert an
+internal checkpoint into a handoff. Persist it and resume until the requested
+rest point or a shared human/safety/access/exhaustion condition.

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

@@ -0,0 +1,92 @@
+# 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: `.omp/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/omp/skills/rite-build/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: rite-build
+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
+serially under green proof, caps, and pause rules. Every wright returns after one slice.
+**Opt-in:** `/rite-build --parallel N` (2≤N≤3; N=1≡serial) follows
+[`reference/parallel-batch.md`](reference/parallel-batch.md)
+([`one-slice-cycle.md`](reference/one-slice-cycle.md)).
+
+Root owns gates/bookkeeping. Fresh
+[`devrites-slice-wright`](.omp/agents/devrites-slice-wright.md) writes product
+source/tests. Workflow Artifact paths use
+[`workflow-artifacts.md`](../devrites-lib/reference/standards/workflow-artifacts.md).
+Execute [`reference/phase-contract.md`](reference/phase-contract.md)
+([`one-slice-cycle.md`](reference/one-slice-cycle.md),
+[`afk-discipline.md`](reference/afk-discipline.md)); dispatch uses
+[`reference/wright-dispatch.md`](reference/wright-dispatch.md).
+
+## Required rules
+
+Read `.omp/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.
+
+## Invariants
+
+- 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).
+- Async readiness waits during slice work follow
+  [`debug-recovery.md`](../devrites-lib/reference/standards/debug-recovery.md)
+  (bounded poll + last-signal artifact; no blind sleep as primary strategy).
+
+## Workflow Artifact branch
+
+<!-- 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)
+
+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.
+
+## Phase exit (observable)
+
+**Complete when:** the dispatched wright returns green proof for the slice,
+`git diff --name-only` ⊆ allowlist, independent test analysis admits no Critical
+gap, and `state.md` cursor advances with recorded evidence paths.
+
+**Failing case:** wright reports "done" but proof command was not executed or
+failed → slice incomplete; do not advance cursor.

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

@@ -0,0 +1,145 @@
+# AFK discipline for unattended `/rite-build`
+
+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.
+
+Load the shared
+[`afk-hitl.md`](../../devrites-lib/reference/standards/afk-hitl.md#the-sentinel-devritesafk)
+contract for the sentinel schema, defaults, gate ceiling, and mutable-counter
+ownership. This file owns only Build's dispatch, charging, and red-path behavior.
+
+Rules: green before `built`; hard `max_slices` cap; gates before the action they
+control; irreversible work (destructive/auth/public API) always pauses.
+
+## Iteration cap
+
+The controlling root owns the cap:
+
+1. **Before every dispatch**, re-read `.devrites/AFK`, `state.md`, and the
+   selected slice. A configured `max_slices` and any existing
+   `afk_slices_remaining` value, including its released bullet form, must each
+   be a decimal nonnegative integer. A missing
+   `state.md` or malformed configured value fails closed; an omitted cap is the
+   documented unlimited default only when no remaining counter exists. If the
+   effective remaining value is zero, stop before dispatching another slice.
+2. **After proof is green**, combine the pending → built record and budget
+   charge in one `state.md` rewrite. If the remaining field is absent, add
+   `afk_slices_remaining` to a cursor table or `AFK slices remaining` to a
+   legacy bullet cursor, seed it from `max_slices`, and write
+   `max_slices - 1`; otherwise preserve its spelling and write `remaining - 1`.
+   The counter is never below zero: a value that would go negative is an invariant failure and
+   stops. A missing `max_slices` means unlimited and no remaining field is
+   created.
+   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.** 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`/`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 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** 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:
+
+1. Continue the same wright under `devrites-debug-recovery`, carrying exact output and dead
+   ends; cap writer + recovery at three no-progress attempts per exact causal fingerprint.
+   A correction that closes the reproduction is progress; a different evidenced
+   Critical/Important invariant starts a separate fingerprint.
+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: none — technical recovery exhausted for <causal fingerprint>; requires new evidence or changed failure conditions`, and STOP without a qid or runnable phase command. Reinvocation with the unchanged fingerprint remains blocked and does not reset the cap.
+4. Fire `notify:` only for an actual `awaiting_human` transition.
+
+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)
+
+Regardless of `allow_gates`, AFK invokes the checkpoint protocol when the slice touches
+any of:
+
+- Destructive data migration (drop column, drop table, irreversible backfill).
+- Auth / authz boundary change (new role, changed permission check, new public auth endpoint).
+- Public API break (response shape change, removed endpoint, changed status code semantics).
+- External-service contract change (webhook payload, partner-facing schema).
+- Filesystem destructive operation outside the workspace (`rm -rf` of project paths,
+  rewriting `.gitignore`-listed paths, deleting fixtures).
+- Anything the slice's `Gate: blocking` plus `tasks.md` `Why HITL:` flags as irreversible.
+
+This is the Claude Code auto-mode transcript classifier list adapted to the DevRites
+workspace.
+
+## The `notify:` hook contract
+
+The hook is a single shell command run on the `awaiting_human` transition. Environment
+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>` |
+| `DEVRITES_SLUG` | active feature slug |
+| `DEVRITES_QUESTION` | the checkpoint text |
+| `DEVRITES_PROPOSED` | the proposed answer |
+
+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:
+
+- `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)
+
+DevRites does not implement notifications; the configured hook does.
+
+## When to leave AFK
+
+Drop the sentinel before:
+
+- A new feature when `/rite-build` has not yet completed successfully on this codebase
+  in HITL.
+- 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 allows routine work to continue automatically. Re-enable it for another batch of
+low-stakes work.
+
+## What AFK does NOT do
+
+- It does not bypass `/rite-prove`, `/rite-review`, or `/rite-seal`. Those gates are
+  feature-scoped and always run when their phase runs.
+- It does not skip `/rite-plan repair` when the Spec Drift Guard finds that the
+  durable plan is wrong. Objective implementation and tool failures stay in
+  bounded recovery instead.
+- It does not skip `devrites-source-driven` checks. Uncertain framework behavior still
+  triggers the doc lookup.
+- It does not skip `evidence.md` writes. AFK runs that don't record evidence are
+  unproven and get rejected at `/rite-prove` regardless.
+
+The sentinel widens *human pauses*, nothing else.

package/pack/generated/omp/skills/rite-build/reference/anti-patterns.md

@@ -0,0 +1,23 @@
+# rite-build: anti-patterns
+
+Load when a non-trivial decision stands or stopping, TDD, or doubt discipline
+feels inconvenient.
+
+Pack-wide rationalizations and red flags live in
+[standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "Slices 1 and 2 are related; let me do both." | HITL needs a later user invocation. Explicit `.devrites/AFK` may let the root chain only after green proof and cap/pause gates; each wright still returns after one. |
+| "It's faster to skip `devrites-doubt` for this small change." | Doubt is cheapest *before* the decision is standing. After is debugging. |
+
+## Red Flags
+
+- About to start slice N+1 outside explicit AFK or before its green-proof/cap/pause gates.
+- Skipping `devrites-doubt` on a branching, boundary, data-model, auth, public-API, or migration decision.
+- Adding a dependency or a second design system without recording rationale in `decisions.md`.
+- Writing a `try/catch` block wider than what you handle.
+- A comment that restates what the next line does.
+- Touching files that aren't in `touched-files.md` for "tidiness".

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

@@ -0,0 +1,120 @@
+# Checkpoint protocol: what `/rite-build` does when a slice is HITL
+
+HITL slices pause **pre-action** as a ranked **option set** before any code:
+
+- **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
+
+Render the checkpoint in user-facing output **and** persist it for the next session / AFK
+observer.
+
+### User-facing render: the option set
+
+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>
+
+▸ 1. <recommended>  (Recommended)
+     logic: … · infra: … · business: … · architecture: …   (+ security/UX/risk if in scope)
+  2. <alternative> — <rationale + the trade-off it accepts>
+  3. <alternative> — <rationale>
+  4. Something else — I'll describe it
+```
+
+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
+
+In one bounded root-owned update (one `questions.md` append and one `state.md`
+rewrite; do not claim cross-file atomicity):
+
+1. **`questions.md` append:**
+
+   ```markdown
+   ## q-<YYYY-MM-DD>-<NNN>
+   status: open
+   slice: <N — name>
+   gate: <gate from tasks.md>
+   question: <Checkpoint text from tasks.md>
+   options: |                        # the ranked set, recommended first (matches the render)
+     1. <recommended> (Recommended) — logic: … · infra: … · business: … · architecture: …
+     2. <alternative> — <rationale>
+   proposed: <the recommended option restated; matches option 1>
+   raised_at: <iso>
+   ```
+
+2. **`state.md` updates:**
+
+   ```markdown
+   - Status: awaiting_human
+   - Active slice: <N — name>
+   - Slice mode: HITL
+   - Next step: /rite-resolve <qid> "<answer>"
+
+   ## Awaiting human
+   - qid: <q-...-NNN>
+   - gate: <gate>
+   - question: <Checkpoint text>
+   - proposed: <one-paragraph best-guess>
+   - raised_at: <iso>
+   - blocking_slices: [<list, from `Blocked by` lookups>]
+   ```
+
+3. **`notify:` hook (if `.devrites/AFK` defines one):** export all six env vars from the
+   canonical contract in [`afk-discipline.md`](afk-discipline.md) (the `notify:` hook
+   contract table is the source of truth):
+
+   ```bash
+   DEVRITES_QID="$qid" \
+   DEVRITES_GATE="$gate" \
+   DEVRITES_SLICE="$slice_id" \
+   DEVRITES_SLUG="$slug" \
+   DEVRITES_QUESTION="$question" \
+   DEVRITES_PROPOSED="$proposed" \
+   sh -c "$notify_cmd"
+   ```
+
+   Fire after workspace write. Hook failure does **not** roll back the pause (best-effort).
+
+## qid generation
+
+Format: `q-YYYY-MM-DD-NNN`, where `NNN` is the next sequential integer for that date in
+`questions.md`. The controlling root must scan every question header matching
+today's prefix, collect its numeric suffixes, and select one above the highest
+observed suffix (or `001` when none exist), advancing until it is unused. Then
+re-read `questions.md` immediately before the append and repeat the scan. Append only if
+the same candidate is still the next unused id; otherwise recompute. There is no
+reservation or engine command for qids.
+
+## When AFK is active
+
+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
+
+**One question per pause.** Multiple HITL checkpoints → `/rite-plan reslice`.
+
+## What NOT to do
+
+- 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.

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

@@ -0,0 +1,46 @@
+# Checkpoint: crash-survivable WIP commits (opt-in)
+
+`.devrites/` markdown survives compaction, but a slice's source normally stays
+uncommitted until `/rite-ship`. A crash during unattended Build can lose that source.
+Checkpoint mode commits each proven slice as a local `WIP`, so it survives the session.
+
+## When it's on
+Opt in with `.devrites/CHECKPOINT`, the mirror of `.devrites/AFK`. When absent,
+`/rite-build` makes no checkpoint. Autocomplete sets it for long unattended runs.
+**Local-only:** never push a checkpoint or let scratch work trigger CI.
+
+## The checkpoint commit: orchestrator, at RECORD, after gates are green
+A checkpoint records a **proven** slice only after its gates are green. Stage the exact
+slice-owned candidate paths from the manifest, passing each literal path separately.
+Never stage `touched-files.md`, a directory, glob, unrelated path, or user change.
+Verify the staged set, then commit locally with a `[devrites-context]` body:
+
+```bash
+[ -f .devrites/CHECKPOINT ] || exit 0   # sentinel absent → no-op, silent
+git commit -m "WIP(<slug>): <slice>" -m "$(cat <<'BODY'
+[devrites-context]
+decisions: <one-line delta this slice added to decisions.md>
+remaining: <pending slices — count or names>
+dead-ends: <approaches ruled out this slice, if any>
+BODY
+)"
+```
+
+## Restore
+After a crash, a fresh session may read the last `WIP(<slug>)` body as crash context.
+Authoritative state remains in `.devrites/`: validate the body against that workspace;
+never reconstruct or advance state from the commit body. Reload per
+[`context-hygiene.md`](../../devrites-lib/reference/standards/context-hygiene.md)
+(`.devrites/ACTIVE`, `state.md`, `questions.md`, `decisions.md`, `test-plan.md`/`evidence.md`).
+
+## Collapse at ship
+WIP commits are scratch and never reach shared history. `/rite-ship` folds them into the
+one atomic feature commit before the Conventional-Commit ladder: see the collapse step in
+[git-ship.md](../../rite-ship/reference/git-ship.md). Result: one clean commit, bisect
+stays green.
+
+## Autocomplete clean-baseline use
+`/rite-autocomplete` may arm checkpoints after verifying a clean or accepted baseline.
+They authorize neither red-gate continuation nor Ship. Each wright returns after one
+slice; HITL stops, while explicit `.devrites/AFK` lets the controlling Build root chain
+another green slice only under its cap and pause rules.

package/pack/generated/omp/skills/rite-build/reference/frontend-trigger.md

@@ -0,0 +1,39 @@
+# Frontend trigger
+
+A slice is **frontend/UI** if it touches or plans to touch any of:
+
+- React / TSX / JSX; Vue, Svelte, Astro, Angular;
+- Rails Slim / Haml / ERB views; any server-rendered template;
+- CSS, SCSS, Tailwind, design tokens, theme files;
+- components, forms, layout, navigation, dashboard, landing/marketing page;
+- UI copy, empty states, error states, onboarding, settings;
+- screenshots, mockups, visual direction;
+- browser behavior, responsive behavior, accessibility, frontend performance.
+
+## When triggered
+- `/rite-spec` applies **`devrites-ux-shape`** (spec step 3a) to write the feature-level
+  **`design-brief.md`** before any code: design direction, key states, interaction model,
+  optional Figma/image visual-direction probe.
+- `/rite-build` applies **`devrites-frontend-craft`** to the vetted `design-brief.md`
+  (register, system, states, anti-AI-slop). If missing or materially changed, shape it
+  and return through `/rite-vet` before code.
+- `/rite-prove` applies **`devrites-browser-proof`** (proof ladder + evidence schema).
+- `/rite-polish` runs the full **normalize + polish** workflow.
+- `/rite-review` and `/rite-seal` include frontend UX / a11y / responsive / design-
+  system checks.
+
+## Fullstack (UI slice that also needs backend)
+If the slice spans both layers, it's both a frontend **and** a backend slice. Define the
+**API/data contract first** (`devrites-api-interface`), build it as one **vertical slice**
+(DB → service → API → UI), apply the engineering rules to the backend and
+`devrites-frontend-craft` to the UI, map each contract error to a real UI state, and
+**prove both layers** (contract tests + browser proof). See
+`devrites-frontend-craft/reference/fullstack.md`.
+
+## When NOT triggered
+Pure backend/data/CLI/infra slices skip craft and browser proof, but still get tests
+and evidence. If unsure whether a slice is "UI enough", treat copy/empty/error states
+and any rendered output as UI.
+
+Mark `Frontend craft required: yes/no` and `Browser proof required: yes/no` on the
+slice in `tasks.md` so the trigger is explicit, not rediscovered each cycle.