devrites 4.2.0 → 4.4.0

package/pack/generated/claude/skills/devrites-lib/reference/visual-playbooks/plan.md

@@ -0,0 +1,49 @@
+# Visual playbook: plan
+
+## use_when
+
+Explain a product or technical plan before implementation — PRD-style approach, technical design, implementation proposal, or pre-build walkthrough that benefits from layout over prose alone.
+
+Use a lighter `comparison` or `diagram` playbook alone when the plan is only one small design choice.
+
+## Structure / landmarks / stable ids
+
+| Landmark | Suggested `id` | Role |
+| --- | --- | --- |
+| Goal | `plan-goal` | Desired outcome |
+| Current state | `plan-current` | What exists today |
+| Desired behavior | `plan-desired` | Target behavior |
+| Approach | `plan-approach` | High-level proposal |
+| Risks | `plan-risks` | Failure modes / migration / compat |
+| Open questions | `plan-questions` | Unresolved; clear when answered |
+| Options (optional) | `plan-options` | Follow [`comparison.md`](comparison.md) |
+
+A plan should be self-contained enough that another developer could implement from it. Verify claims against the codebase before stating them as fact.
+
+When frontend UX matters, prefer a visual mock of the experience under a consistent local design (CSS in-page) over text-only description.
+
+## design_rules
+
+- Portable single-file HTML; self-contained CSS preferred.
+- Cite real repo paths for architecture claims (outline `## Citations`).
+- Update the plan when questions resolve — do not leave stale open questions that are already decided.
+- Nest other playbooks' surfaces (diagram / comparison / table) with their own stable ids.
+- CDN only when nested Mermaid / diff surfaces need it; note in outline.
+- Explicit background / color-scheme; semantic landmarks.
+
+## Pitfalls / anti-patterns
+
+- Focusing only on ambiguous decisions and omitting the actual proposal.
+- Omitting failure modes, migration, or backwards-compatibility concerns.
+- Leaving resolved questions in the artifact as if still open.
+- Treating Lavish annotation as required for plan review.
+- HTML without outline companion.
+
+## DevRites notes
+
+- **Home:** `.devrites/work/<slug>/visual/<name>.html` + `<name>.outline.md`.
+- Does **not** replace workspace `plan.md` / `spec.md` — optional richer presentation beside them.
+- Outline: [`outline-template.md`](outline-template.md); **outline wins** on conflict.
+- Open questions may point into workspace `questions.md` ids; durable answers belong there and/or outline `## Answers` if `input` was used.
+- **No new lifecycle phase.**
+- Router: [`index.md`](index.md).

package/pack/generated/claude/skills/devrites-lib/reference/visual-playbooks/slides.md

@@ -0,0 +1,42 @@
+# Visual playbook: slides
+
+## use_when
+
+**Only** when the user asks for a deck, presentation, talk, or paced walkthrough. Default to a scroll page (`plan`, `diagram`, `comparison`, …) for reference material, detailed review, or dense evidence.
+
+## Structure / landmarks / stable ids
+
+| Landmark | Suggested `id` | Role |
+| --- | --- | --- |
+| Deck root | `slides-root` | Container / scroll-snap or section stack |
+| Slide N | `slide-<n>` | One idea per slide |
+| Deck nav (optional) | `slides-nav` | Prev/next or index |
+| Closing slide | `slide-close` | Decision or next action |
+
+Plan the story before markup: open with the point → context → evidence → decision/next action. Vary composition so consecutive slides do not feel like identical cards unless repetition is intentional.
+
+## design_rules
+
+- Sparse text; let visuals carry explanation.
+- Large type, strong alignment, deliberate whitespace — not dense paragraphs.
+- Make navigation and screen-size assumptions explicit (e.g. "designed for 16:9 presenter view").
+- Prefer self-contained CSS (scroll-snap sections or simple slide panes). CDN only if nested Mermaid/diff needs it; note in outline.
+- Stable `id` on every slide for outline inventory and deep links.
+- Explicit background / color-scheme on the page and each slide.
+
+## Pitfalls / anti-patterns
+
+- Turning every explainer into slides by default.
+- Pasting a scroll-page outline into fixed frames without rewriting the narrative.
+- Dense code review inside slides — use [`code.md`](code.md) on a scroll page instead.
+- Requiring Lavish runtime for advancement or feedback.
+- HTML without outline companion.
+
+## DevRites notes
+
+- **Home:** `.devrites/work/<slug>/visual/<name>.html` + `<name>.outline.md`.
+- Outline: [`outline-template.md`](outline-template.md); list each `slide-<n>` in ID inventory with its one idea.
+- **Outline wins** on conflict.
+- Feedback/choices on a deck still use [`input.md`](input.md) → outline `## Answers` / `questions.md`, not Lavish queue APIs.
+- **No new phase**; optional; not readiness-required.
+- Router: [`index.md`](index.md).

package/pack/generated/claude/skills/devrites-lib/reference/visual-playbooks/table.md

@@ -0,0 +1,44 @@
+# Visual playbook: table
+
+## use_when
+
+Turn dense records that share the same fields into a scan-friendly review surface (status matrices, coverage grids, inventory with comparable columns).
+
+## Structure / landmarks / stable ids
+
+| Landmark | Suggested `id` | Role |
+| --- | --- | --- |
+| Summary | `table-summary` | What the rows prove or require |
+| Primary table | `table-main` | Semantic `<table>` for comparable rows |
+| Row groups | `table-group-<slug>` | Optional thematic sections |
+| Footer notes | `table-notes` | Caveats, filters, open questions |
+
+Stable ids: put `id` on the table and on important rows (`tr id="row-…"`) when a row is a decision target. Mirror row ids in the outline inventory when they matter.
+
+Column groups should follow the decision they support: identity → evidence → status → action.
+
+## design_rules
+
+- Use semantic `<table>` / `<thead>` / `<tbody>` / `<th scope>` when data is tabular.
+- Lead with a short summary (counts, risk levels, verdicts) above the grid.
+- Protect long paths, symbols, and URLs from overflow (`overflow-wrap`, narrow-viewport friendly).
+- Restrained color for status/severity; never color as the only signal (pair with text).
+- Prefer self-contained CSS; no CDN required for tables.
+- Explicit page background / color-scheme; landmarks with stable ids.
+
+## Pitfalls / anti-patterns
+
+- Pasting a terminal table into HTML unchanged.
+- Hiding the conclusion under a large undifferentiated grid.
+- Using cards when rows share fields (or tables when shapes differ wildly — use cards then).
+- Lavish row-queue / annotation APIs as requirements.
+- HTML without outline companion.
+
+## DevRites notes
+
+- **Home:** `.devrites/work/<slug>/visual/<name>.html` + `<name>.outline.md`.
+- Outline: [`outline-template.md`](outline-template.md); cite this id under Playbooks used.
+- **Outline wins** on HTML/outline conflict.
+- Prefer linking dense evidence from existing artifacts (`traceability.md`, `test-plan.md`) rather than duplicating whole files into the visual.
+- **No new phase**; optional; not readiness-required.
+- Router: [`index.md`](index.md).

package/pack/generated/claude/skills/devrites-lib/reference/workspace-artifact-schema.md

@@ -31,7 +31,7 @@ Readers continue to accept safe legacy basenames; no ordinary phase renames one.
 | vet/build/converge | plan artifacts plus `eng-review.md`, `test-plan.md`; Build creates and maintains `touched-files.md` after its first green slice |
 | prove/polish/review | vetted plan artifacts plus `evidence.md`, `touched-files.md` |
 | seal/ship/done | proof artifacts plus `review.md`, `seal.md` |
-| conditional | `flows.md` when diagrams clarify; `design-brief.md` and `browser-evidence.md` for UI; `drift.md` for drift; `handoff.md` only when requested; `references.md` + `references/` when references exist |
+| conditional | `flows.md` when diagrams clarify; `visual/` HTML+`.outline.md` companions when a richer reviewable visual earns it (optional; never readiness-required); `design-brief.md` and `browser-evidence.md` for UI; `drift.md` for drift; `handoff.md` only when requested; `references.md` + `references/` when references exist |
 
 ## What each file owns
 
@@ -44,6 +44,9 @@ Readers continue to accept safe legacy basenames; no ordinary phase renames one.
 | `strategy.md` | temper verdict, scope mode/deltas, pre-mortem risks, deferred ambition | 180 lines |
 | `architecture.md` | owning layer, integration points, data/API/events, dependencies, risks, affected boundaries | 180 lines |
 | `flows.md` | useful Mermaid sequence/state/data/lifecycle diagrams with why-it-matters text and related IDs | 160 lines |
+| `visual/<name>.html` | optional portable human-viewable visualization; pair with sibling `.outline.md`; self-contained preferred | 400 lines |
+| `visual/<name>.outline.md` | required machine dual-read companion for the sibling HTML; outline wins on conflict; never a candidate path | 200 lines |
+| `visual/README.md` | optional index of visuals in the workspace | 80 lines |
 | `decisions.md` | ADR-style `DEC-###` log: status, context, options, decision, consequences, related IDs | 200 lines |
 | `assumptions.md` | assumptions with confidence, owner, validation status | 160 lines |
 | `questions.md` | current `q-YYYY-MM-DD-NNN` (or released `Q-###`) open/resolved questions, gate, answer, impact | 180 lines |
@@ -60,6 +63,11 @@ Readers continue to accept safe legacy basenames; no ordinary phase renames one.
 | `design-brief.md` | UI design direction, states, interaction model | 160 lines |
 | `handoff.md` | cold-resume guide: current objective, last completed slice, next action, blockers, read-next links | 120 lines |
 
+When emitting `visual/` HTML+outline pairs, open matching playbooks via
+[`visual-playbooks/index.md`](visual-playbooks/index.md) (progressive load; do not
+preload all seven). Required outline headings:
+[`visual-playbooks/outline-template.md`](visual-playbooks/outline-template.md).
+
 ## Candidate manifest and bindings
 
 `touched-files.md` contains exactly one `## Touched files` heading and exactly
@@ -88,12 +96,14 @@ candidate scope; only manifest rows do.
 The public candidate limits are a 1 MiB manifest, 4,096 rows, a 4,096-byte
 path, 64 MiB per present file, and 256 MiB across all present files.
 
-Workspace and audit artifacts are not candidate paths. Durable project files
-include `.devrites/specs/**`, `DESIGN.md`, and `docs/adr/**`, plus the exact
-`.devrites/principles.md` owner. Under `.devrites`, only those principles and
-spec owners may be candidates; `ACTIVE`, `AFK`, `CHECKPOINT`, `archive/**`,
-`work/**`, and every other sibling fail closed. Engine owns malformed path,
-type, and size rejection; phases do not reinterpret a rejected manifest.
+Workspace and audit artifacts are not candidate paths. That includes every path
+under `.devrites/work/<slug>/visual/` (HTML, `.outline.md`, and optional
+`visual/README.md`). Durable project files include `.devrites/specs/**`,
+`DESIGN.md`, and `docs/adr/**`, plus the exact `.devrites/principles.md` owner.
+Under `.devrites`, only those principles and spec owners may be candidates;
+`ACTIVE`, `AFK`, `CHECKPOINT`, `archive/**`, `work/**`, and every other sibling
+fail closed. Engine owns malformed path, type, and size rejection; phases do
+not reinterpret a rejected manifest.
 
 `evidence.md`, `review.md`, and `seal.md` each contain exactly one unindented standalone
 binding line; `browser-evidence.md` does too when that file exists:
@@ -122,7 +132,9 @@ The digest binds reviewed bytes; it never substitutes for semantic review. Norma
 checks structure plus that binding, and Seal rechecks it.
 
 Proof commands must be repository-portable: no host wrappers, user-specific absolute paths,
-or temporary proof trees. Evidence records the executed command.
+or temporary proof trees. Evidence records the executed command. Optional `visual/`
+artifacts never inflate readiness: they are not readiness inputs and do not substitute
+for `decision-coverage.md`, `eng-review.md`, or `test-plan.md`.
 
 ## Canonical slice grammar
 
@@ -186,7 +198,9 @@ unless the stated reason makes the boundary irreducible.
 - Do not copy acceptance criteria into `plan.md`; reference `AC-###`.
 - Do not copy full proof into `handoff.md`; link to `evidence.md`.
 - Do not make `state.md` an append-only log; keep only the current cursor.
-- Do not create optional files before their phase; absence is meaningful.
+- Do not create optional files before their phase; absence is meaningful. Do not
+  treat `visual/` as required for readiness; emit HTML+outline only when a writer
+  earns a richer visual, and keep Mermaid in `flows.md` when that is enough.
 
 ## ID contract
 
@@ -209,3 +223,4 @@ append-only identities, not display positions:
 Old `AC1` and `Slice 1` forms are legacy and should not be generated for new
 workspaces. Preserve released legacy forms unless an explicit upgrade owns the
 migration; never renumber them incidentally.
+

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

@@ -1,7 +1,7 @@
 ---
 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
 ---
 
@@ -9,8 +9,9 @@ user-invocable: true
 
 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
-under green proof, caps, and pause rules. Every wright returns after it. Read the
-active workspace first; without one, route `/rite-spec <feature>`.
+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).
 
 Root owns gates/bookkeeping. Fresh
 [`devrites-slice-wright`](../../agents/devrites-slice-wright.md) writes product
@@ -21,45 +22,37 @@ Execute [`reference/phase-contract.md`](reference/phase-contract.md); dispatch u
 
 ## Required rules
 
-Read `.claude/skills/devrites-lib/reference/standards/core.md` first. Load only
-rules triggered by the slice:
-
-- coding style, error handling, testing, [`reference/tdd.md`](reference/tdd.md),
-  patterns, and definition of done;
-- binding `.devrites/principles.md` invariants when present;
-- security for input/auth/data/integrations;
-- repository topology for multiple roots/languages or generated/vendor surfaces;
-- data integrity for durable state, migration, concurrency, tenancy, or retention;
-- integration reliability for API/webhook/queue/job/cache/service boundaries.
-
-The wright also applies the canonical anti-slop list. Root verifies its return;
-it never patches source itself.
+Read `.claude/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
 
-- One slice per wright dispatch; writers are serial. Use the native-worktree pilot
-  only when `wright-dispatch.md`'s clean preflight and reconciliation both hold,
-  otherwise serial same-worktree writing.
-- Exact feature scope only. Record adjacent issues and Things I didn't touch;
-  reject any returned diff outside the task's explicit source/test paths.
-- Never rerun an unchanged check. Re-prove after edits.
-- Unplanned dependency, design system, objective technical gap, or repair stays
-  inside Vet/Spec Drift Guard. Ask only for licensing/cost/security/product or
-  explicit architecture-policy decisions.
-- Root never edits product source/tests. It writes canonical `.devrites/`
-  bookkeeping and applies the Workflow Artifact route only. The supported host's
-  wright is sole product writer. Put exact project-relative paths directly in the
-  task; compare returned file list and `git diff --name-only`; extras hard-stop.
-- Project principles are binding. An unavoidable conflict or irreversible risk
-  needs a human-approved scoped exception or stop, never silent balancing.
-- Evidence beats confidence. Never weaken a failing test, skip TDD, widen a
-  writer, or self-approve a wright return. Route drift through
-  [`reference/spec-drift-guard.md`](reference/spec-drift-guard.md); checkpoint
-  mode follows [`reference/checkpoint.md`](reference/checkpoint.md).
+- 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).
 
 ## 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

package/pack/generated/claude/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/claude/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.

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

@@ -3,11 +3,14 @@
 One wright dispatch builds one thin, proven slice. HITL stops; only explicit
 `.devrites/AFK` lets the controlling root chain another pending slice under the
 green-proof, cap, and pause rules. Each wright returns after exactly one slice.
+Opt-in fan-out: [`parallel-batch.md`](parallel-batch.md) (`--parallel N`); this is default.
 
 ## 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:
@@ -25,14 +28,16 @@ NEXT      → HITL root reports and stops; AFK root may repeat only under afk-di
 ```
 
 ## Why the boundary matters
-- Keeps diffs reviewable and reveals integration or drift early.
-- Preserves a HITL decision point and prevents unproven pile-ups.
+
+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** (stop, record, classify, maybe
   ask, `/rite-plan` repair).
 - Slice is bigger than one cycle → stop and `/rite-plan reslice`.

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

@@ -1,6 +1,7 @@
 # rite-build output
 
 **Slices remain:**
+
 ```text
 Done: built slice <n> — <name>.
 Changed: <files>; state.md, touched-files.md, evidence.md
@@ -12,6 +13,7 @@ Record: .devrites/work/<slug>/evidence.md
 ```
 
 **All built:**
+
 ```text
 Done: built slice <n> — <name>; all slices built.
 Changed: <files>; state.md, touched-files.md, evidence.md