devrites 7.1.1 → 7.2.0

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

@@ -0,0 +1,126 @@
+---
+name: rite-build
+description: Build the next approved vertical slice with evidence. HITL one-slice default; AFK/autocomplete chain serially or in eligible path-disjoint batches (dynamic size, cap 10); `--parallel N` caps a batch.
+argument-hint: "[--parallel N] [slice number or name]"
+user-invocable: true
+---
+
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md","devrites-lib/reference/standards/code-navigation.md","devrites-lib/reference/standards/code-index.md","devrites-lib/reference/standards/agents.md","rite-build/reference/phase-contract.md","rite-build/reference/one-slice-cycle.md","rite-build/reference/wright-dispatch.md","rite-build/reference/checkpoint.md","rite-build/reference/spec-drift-guard.md","rite-build/reference/output.md","rite-build/reference/anti-patterns.md"],"rootOnly":["devrites-lib/reference/standards/code-index.md","rite-build/reference/phase-contract.md","rite-build/reference/wright-dispatch.md","rite-build/reference/checkpoint.md","rite-build/reference/output.md","rite-build/reference/afk-discipline.md","rite-build/reference/checkpoint-protocol.md","rite-build/reference/parallel-batch.md","devrites-lib/reference/standards/afk-hitl.md","devrites-lib/reference/standards/workflow-artifacts.md"],"triggers":{"afk":["rite-build/reference/afk-discipline.md","devrites-lib/reference/standards/afk-hitl.md","rite-build/reference/checkpoint-protocol.md"],"applicability":["devrites-lib/reference/standards/repository-topology.md","devrites-lib/reference/standards/data-integrity.md","devrites-lib/reference/standards/integration-reliability.md"],"coding":["devrites-lib/reference/standards/coding-style.md"],"debug-recovery":["devrites-lib/reference/standards/debug-recovery.md"],"dod":["devrites-lib/reference/standards/definition-of-done.md"],"errors":["devrites-lib/reference/standards/error-handling.md"],"frontend":["rite-build/reference/frontend-trigger.md"],"parallel":["rite-build/reference/parallel-batch.md"],"patterns":["devrites-lib/reference/standards/patterns.md"],"principles":["devrites-lib/reference/standards/principles.md"],"security":["devrites-lib/reference/standards/security.md"],"tdd":["rite-build/reference/tdd.md","devrites-lib/reference/standards/testing.md"],"workflow-artifacts":["devrites-lib/reference/standards/workflow-artifacts.md"]},"workspace":["brief.md","spec.md","state.md","decisions.md","assumptions.md","questions.md","decision-coverage.md","architecture.md","plan.md","tasks.md","traceability.md","eng-review.md","test-plan.md","gates.md","strategy.md"],"workspaceByRole":{"code-reviewer":["spec.md","plan.md","tasks.md","test-plan.md","architecture.md","decisions.md","state.md"],"doubt-reviewer":["spec.md","plan.md","tasks.md","state.md","decisions.md"],"slice-wright":["brief.md","spec.md","architecture.md","plan.md","tasks.md","test-plan.md","state.md","decisions.md","assumptions.md","questions.md"],"test-analyst":["spec.md","tasks.md","test-plan.md","state.md"]}} -->
+> Read-set manifest: `devrites-engine context --skills-root .dsh/skills <slug> --phase build` bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
+
+
+# /rite-build: one verified slice
+
+Active caller takes precedence per [output.md](reference/output.md#caller-owned-continuation).
+Standalone HITL stops; standalone AFK chains under green proof, caps and pause
+rules. Every wright returns after one slice.
+**HITL:** `/rite-build --parallel N` (2≤N≤10; 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`](../../agents/devrites-slice-wright.md) writes source/tests.
+Workflow Artifacts use
+[`workflow-artifacts.md`](../devrites-lib/reference/standards/workflow-artifacts.md)
+(trigger `workflow-artifacts` — only when the plan declares them).
+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).
+Every wright contract names the writer-safe checks the wright runs (syntax/type/lint,
+unit and self-check suites, a narrow local smoke) and never forbids them; only
+artifact-producing, consumptive, or full canonical gates stay root-owned, and a
+`RUN: writer` gate adds `gates precheck` to them;
+`dispatch open --contract` refuses a contract that breaks this. Prior contracts in `evidence.md` are not a template for this. **Failing case:** the
+contract says "skip tests mid-flight; root runs them after return", and the wright
+returns three unit failures that a 20 s `go test` would have caught in-round.
+
+## Required rules
+
+Read `.dsh/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. Refuse the rationalizations in
+[`anti-patterns`](reference/anti-patterns.md).
+
+## Invariants
+
+- Standalone HITL default: serial on control (core.md #5). AFK/`--parallel N`
+  uses [`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 (core.md #7); reject out-of-allowlist diffs
+  (`devrites-engine check diff-scope <slug> --allow <contract-paths>`); record
+  adjacent issues. An adjacent issue or non-obvious rationale bound to specific
+  code anchors as a note — `devrites-engine note add <slug> <file> "<verbatim
+  quote>" <title>` — so refactors regrade it instead of losing it
+  ([`notes.md`](../devrites-lib/reference/workspace-artifact-schema.md#anchored-notes)).
+- Re-prove affected behavior after edits (core.md #6); reuse observations only
+  under [evidence validity](../devrites-lib/reference/candidate-integrity.md#evidence-validity).
+- Unplanned dependency/design-system/gap/repair → Vet/Spec Drift Guard batch
+  sweep: every contract-assumption violation recorded before one folded
+  repair+vet. Ask only for licensing/cost/security/product or explicit
+  architecture-policy decisions (core.md #8).
+- Root never edits product source/tests (`.devrites/` + Workflow Artifact only;
+  [agents.md](../devrites-lib/reference/standards/agents.md) source-writing
+  boundary). Wright is sole product writer; extras in returned paths/`git diff
+  --name-only` hard-stop via `check diff-scope`.
+- Principles bind; irreversible conflict needs human exception or stop.
+- Evidence beats confidence (core.md #6). 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)
+
+HITL default/explicit `1` ≡ serial; AFK inherits cap.
+`2`–`10` is a **cap** — the root runs an eligible
+path-disjoint set it can start now (`N_eff`, from `parallel select --from-plan`), takes fewer when the cap cannot be
+filled, and refills a slot per landing (serial slice or one sibling) until
+no pending slice remains
+([`parallel-batch.md` § Dynamic selection](reference/parallel-batch.md#dynamic-selection-and-re-batching)).
+Unattended runs (`/rite-autocomplete`, `.devrites/AFK` `max_parallel`) refill
+inside the same run; HITL stops after each landing. This invocation's `--parallel N`
+is the cap: leftover sentinel `max_parallel` is not consulted. Autocomplete with
+that flag also writes or replaces only `max_parallel: N`. Non-integer/`N≤0`/`N>10` hard refuse.
+Each sibling lands alone when its review + proof are green (`integrate --slice`):
+one local `WIP(<slug>):` commit onto the control branch (never pushed). Do not
+integrate a sibling because the wright returned. A red/gap sibling gets a bounded repair
+round in its own worktree — never rebuilt from scratch while budget remains.
+Post-writer inventory and affected rechecks follow `phase-contract.md` § Independent
+Build review; fold accounts before one repair-all wright.
+Plan-owned gaps still route through Spec Drift Guard
+(batch sweep, one folded plan repair + one vet recheck inline); do not emit
+a human `Fix`. Exhausted repair blocks and preserves everything;
+`cleanup --force` salvages slice branches before removing worktrees —
+human-gated to abandon a batch, orchestrator-emitted only as the salvage
+step of an automatic frozen-lease re-batch.
+AFK charges per landed sibling 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 code/doubt/test analysis,
+approved fail-on-red proof, record, and applicable accounting. Continue/reply via
+[`reference/output.md`](reference/output.md) plus the shared
+[`reply contract`](../devrites-lib/reference/reply-contract.md). Standalone AFK obeys remaining budget; Prove requires every slice built except a
+[deferred slice](../rite-plan/reference/slicing.md#deferred-slice).
+
+## Phase exit
+
+**Complete when:** Independent Build review and fail-on-red proof are green,
+`git diff --name-only` ⊆ allowlist, no open Critical/Important, `state.md` cursor
+advances with recorded evidence, and the control-branch checkpoint has landed
+per [`checkpoint.md`](reference/checkpoint.md).
+
+**Failing case:** wright reports "done" but independent review or proof was
+skipped, red, or followed by an uncommitted repair → slice incomplete; do not
+advance cursor or commit on control.

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

@@ -0,0 +1,153 @@
+# AFK discipline for unattended `/rite-build`
+
+> Root-only: not inlined in --role bundles.
+
+`.devrites/AFK` enables unattended slice chaining. Load the shared
+[`afk-hitl.md`](../../devrites-lib/reference/standards/afk-hitl.md#the-sentinel-devritesafk)
+for sentinel schema, defaults, gate ceiling, and mutable-counter ownership.
+This file owns Build dispatch, charging, and red paths.
+
+Rules: green before `built`; gates before their action; irreversible work
+(destructive/auth/public API) pauses; no tick ends with an open/sealed wave —
+wait for returns or `dispatch abandon --reason`.
+
+## Iteration cap
+
+Under active `/rite-autocomplete`, skip the slice-cap checks, charges, and cap-stop message below;
+use its [admission rules](../../rite-autocomplete/reference/loop.md#admit-each-unattended-cycle).
+Otherwise root owns cap:
+
+1. **Before every dispatch**, re-read `.devrites/AFK`, `state.md`, and the
+   selected slice. This invocation's `--parallel N` is the cap when present;
+   leftover sentinel `max_parallel` is not consulted in that case. When that
+   flag or sentinel `max_parallel` is greater than 1, recompute `N_eff` via
+   `parallel select` before the next dispatch — a prior one-slice round does not keep the run serial. 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 integrate**
+     — once per landed 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
+   and strategy.
+   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 spent strategy → escalate inline to the next correction class; after three
+   escalations park the fingerprint and build every slice that does not depend on it,
+   per the [retry contract](../../devrites-lib/reference/standards/afk-hitl.md#retry-cap-no-progress-loops-and-self-resolve).
+   Never ask a qid or permission to retry; never hand back a routine phase command.
+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 its `Checkpoint:` line in `tasks.md` 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 -fsS -m 10 -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/dsh/skills/rite-build/reference/anti-patterns.md

@@ -0,0 +1,27 @@
+# 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." | Caller first: [output.md](output.md#caller-owned-continuation). Standalone HITL stops; standalone AFK chains after green proof and cap/pause gates; each wright 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
+
+- Next slice violates caller/standalone routing or 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".
+- A comment, filename, test name, or commit subject that mentions `SLICE-###`,
+  a slice number, or "this slice".
+- Committing onto control when the wright returns, or before Independent Build
+  review and fail-on-red proof are green.

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

@@ -0,0 +1,115 @@
+# Checkpoint protocol: what `/rite-build` does when a slice is HITL
+
+> Root-only: not inlined in --role bundles.
+
+HITL slices pause **pre-action** as a ranked **option set** before any code:
+
+- **Interactive:** `ask_user_question`; 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 `ask_user_question` ranked **option set** ([`afk-hitl.md`](../../devrites-lib/reference/standards/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>
+     3. Something else — describe it
+   proposed: <the recommended option restated; matches option 1>
+   raised_at: <full RFC 3339 timestamp, e.g. 2026-10-19T08:17:08Z>
+   ```
+
+2. **`state.md` updates:** cursor `status` = `awaiting_human`, `active_slice` =
+   `<N — name>`, `slice_mode` = `HITL`, `next_action` = `/rite-resolve <qid> "<answer>"`;
+   then the `Awaiting human` table (`question_id`, `gate`, `blocking_slices` from
+   `Blocked by` lookups) per its owner,
+   [`state-workspace.md`](../../rite-spec/reference/state-workspace.md#statemd-template) § state.md template.
+   Question text, `proposed`, and `raised_at` stay in the step 1 entry. Legacy
+   `- Status:`/`- Next step:`/`- qid:` bullets are engine-accepted aliases, not the
+   authoring format.
+
+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 under a bounded tool timeout (e.g. 30 s). Hook failure does **not** roll back the pause (best-effort); append the exit code to `evidence.md`.
+
+## 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/dsh/skills/rite-build/reference/checkpoint.md

@@ -0,0 +1,79 @@
+# Checkpoint: land local WIP only after the check loop is green
+
+> Root-only: not inlined in --role bundles.
+
+The wright does not commit onto the control/primary branch. Independent review
+and fail-on-red proof run first; a red or gap finding dispatches another wright.
+Only when that loop is green does the orchestrator land the local unpushed
+`WIP(<slug>):` commit. Same rule for `/rite-build`, `/rite-prove`, `/rite-polish`,
+`/rite-review`, and `/rite-autocomplete`. Never push. `.devrites/CHECKPOINT` is
+not a gate.
+
+The checkpoint stays local, unpushed scratch folded at `/rite-ship`; where the
+host repository's own agent contract requires approval before commits — an
+ask-first rule such as this repository's `AGENTS.md` — that contract wins, and
+the orchestrator pauses for approval before landing it. The DevRites-generated
+`AGENTS.md` block is not such a rule: under it the checkpoint lands without a
+prompt, AFK or HITL. Push, tag, PR, and the ship commit stay human-gated.
+
+## When (and when not)
+
+- **Do:** after Independent Build review (or the phase's independent validators)
+  and fail-on-red proof are green, with no open Critical/Important and no repair
+  wright still in flight. Serial: git recipe below (skip empty index) or isolated
+  FF of a matching `transfer_commit`. Parallel: `devrites-engine parallel
+  integrate --slice <id> --apply-to-control` (no second control `git commit`).
+- **Do not:** when a wright returns; before review/proof; with red/gap findings;
+  fast-forward an isolated transfer onto control before those checks.
+
+A native-worktree `transfer_commit` is transport on the worker branch only.
+
+## The commit
+Stage the exact candidate paths from the manifest, each as its own argv.
+Never stage `touched-files.md`, a directory, glob, unrelated path, or user change.
+Before planning, run `git check-ignore -v --no-index -- <paths>`: every match, tracked
+or not, goes in the `git add -f --` list, because `git add` exits 1 on a named ignored
+path even after staging it. Keep each command's stderr. Verify the staged set, then
+commit locally.
+
+Subject: `WIP(<slug>):` plus an imperative summary of the change (from the
+goal). Never a slice id, `SLICE-###`, a slice number, or "this slice"
+(`WIP(admin-report): add CSV export for usage rows`, not `SLICE-003` or
+`complete slice 3`). Product source, tests, comments, and filenames omit the
+same marks; they stay in `.devrites/` only.
+
+```bash
+git commit -m "WIP(<slug>): <imperative summary>" -m "$(cat <<'BODY'
+[devrites-context]
+decisions: <one-line delta this work added to decisions.md>
+remaining: <pending count>
+dead-ends: <approaches ruled out, if any>
+BODY
+)"
+```
+
+**Local-only:** never push or let scratch work trigger CI.
+
+After green landing (parallel: successful integrate), check `state.md`
+outside fences before reselecting:
+
+```text
+- [x] SLICE-004 built — <proof/checkpoint reference>
+```
+
+A cursor `built_slices` value or a tasks.md `Status: built` field is not a substitute.
+After landing: `devrites-engine check regression <slug> --update`. Before landing,
+restore or route `BLOCKED` lost facts.
+
+## 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.

package/pack/generated/dsh/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
+[`fullstack.md`](../../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.

package/pack/generated/dsh/skills/rite-build/reference/one-slice-cycle.md

@@ -0,0 +1,57 @@
+# One-slice cycle
+
+Each wright returns after one proven slice. Root follows
+[`output.md`](output.md#caller-owned-continuation); standalone AFK uses
+`afk-discipline.md`.
+This serial cycle is the default `/rite-build`. Opt-in fan-out: [`parallel-batch.md`](parallel-batch.md) (`--parallel N`).
+
+## The cycle
+
+The orchestrator (`/rite-build`) gates and records; the **wright** writes. See
+[`wright-dispatch.md`](wright-dispatch.md).
+
+```text
+SELECT    → orchestrator: restate slice goal + acceptance + scope boundary; HITL gate (pause pre-code)
+(SHAPE)   → orchestrator: missing UI design-brief.md → shape it, then /rite-vet before dispatch
+DISPATCH  → hand the slice contract to devrites-slice-wright (fresh context). Inside the wright:
+   ORIENT    → load only the files this slice touches; learn the project's idiom; reuse-first; affected set via `trace_path` (`../../devrites-lib/reference/standards/code-navigation.md`)
+   (RED)     → if behavior change: write the failing test first
+   IMPLEMENT → smallest complete version; match conventions; devrites-frontend-craft for UI
+   VERIFY    → writer-safe tests/types/lint; return code + tests (no control-branch commit)
+(DOUBT)   → orchestrator, on return: devrites-doubt each non-trivial decision the wright stood up
+            — dispatch the initial read-only reviews of distinct decisions in parallel
+            (independent claims, fresh contexts); wright fixes stay serial — writers share files
+PROVE     → root, concurrent with the reviews on the same frozen candidate:
+            required build/browser/E2E (narrow self-check/smoke first, full gate only
+            after it is green, long runs in the background; cancel one still running once
+            review or proof sends the candidate back, keeping its partial output as
+            diagnostics), then returned-diff/path recheck; fail-on-red
+            (red/gap → repair wright, then re-review and re-prove; do not commit yet)
+RECORD    → orchestrator: after green verification, update state.md/evidence.md and
+            upsert the authoritative candidate manifest from the actual scoped diff
+(CHECKPOINT) → only now, with review+proof green: local WIP(<slug>): <imperative summary>
+            on the control branch (no slice id) → checkpoint.md
+NEXT → controlling caller first: return internally via output.md; no user-facing reply.
+       HITL stops. Standalone AFK with parallel cap>1:
+       return to parallel-batch selection to refill; otherwise repeat under afk-discipline.md
+```
+
+## Why the boundary matters
+
+Reviewable diffs, early drift signal, HITL decision point, no unproven pile-ups.
+
+## Restate the scope boundary
+
+Before coding, write what this slice will and will **not** touch. This is the contract
+you check yourself against: anything outside it is scope creep or a drift event.
+
+## When the slice can't be completed cleanly
+
+- Discovered the plan is wrong → **Spec Drift Guard** (record, classify;
+  sweep every remaining contract assumption, then one folded repair+vet inline;
+  ask only for product/policy/irreversible-risk).
+- Slice is bigger than one cycle → `/rite-plan reslice` inline when AC is
+  preserved; do not emit a human Fix.
+- Blocked on a failing dependency → record in `state.md`, `/rite-plan unblock`
+  inline when the reroute is technical.
+Never power through by guessing.

package/pack/generated/dsh/skills/rite-build/reference/output.md

@@ -0,0 +1,29 @@
+# rite-build output
+
+> Root-only: not inlined in --role bundles.
+
+## Caller-owned continuation
+
+Before standalone replies, return internally to active `/rite-autocomplete` or
+another controlling rite after green proof, checkpoint, and accounting:
+- Slices remain: re-read durable state and reselect/refill; no user-facing reply.
+- All built: return internally to the caller to invoke `/rite-prove` under its own contract.
+
+Human/safety/access/Git stops still use the shared reply contract.
+
+## Standalone response
+
+HITL returns after one green slice; AFK chains per `afk-discipline.md`.
+Every wright returns after one slice. Build alone never invokes Prove.
+
+```text
+Done: built slice <n> — <name>[; all slices built].
+Changed: <files>; state.md, touched-files.md, evidence.md
+Evidence: acceptance met; tests <cmd> → pass; browser <summary|n/a>; drift <none|handled>
+Open: <none|blockers|questions>
+Next: /rite-build [all built: /rite-prove]
+Record: .devrites/work/<slug>/evidence.md
+↻ Hygiene: /clear between slices (none in `orient` `inflight_waves`); /rite-handoff if away > a few hours
+```
+
+Awaiting-human or stopped states use the shared reply contract.