devrites 4.2.0 → 4.4.0

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

package/pack/.claude/skills/rite-build/reference/parallel-batch.md

@@ -0,0 +1,64 @@
+# Parallel batch (`--parallel N`)
+
+Opt-in only. Default `/rite-build` stays [`one-slice-cycle.md`](one-slice-cycle.md).
+
+## Entry
+
+| Input | Behavior |
+| --- | --- |
+| omitted / `--parallel 1` | Serial one-slice |
+| `--parallel N` (**2≤N≤3**) | Parallel when eligible + host pass |
+| non-integer / `N≤0` / `N>3` | Hard refuse (no silent clamp) |
+
+AFK caps `N` by remaining budget. Charge **only after successful integrate**
+(once per integrated green sibling). Abort / integrate-failed → **0**. Running
+lease blocks another `/rite-build`.
+
+## Path-disjoint
+
+Exact project-relative source/test paths only. Normalize `\`→`/`. Reject `..`,
+duplicates, absolutes, `.devrites/**`. Empty pairwise intersection required.
+
+**SSOT:** `devrites-engine check path-disjoint [--root <dir>] [<json-file>|-]`
+(N≥2 only; pass `--root`). Exit `0` → fan-out; else force serial. Inspect-time
+overlap → sibling **gap** → abort.
+
+## Control vs workers
+
+Control owns `.devrites/work/<slug>/` (`parallel-lease.md` + bookkeeping).
+Workers: `.scratch/parallel-wt/<batch>/<slice>/` on
+`devrites/parallel/<slug>/<batch>/<slice>` @ base `B`. Wrights never write
+`.devrites/**`.
+
+Lease: `batch_id`, `created_at`, `base_sha`, `n`,
+`status` (`running|aborted|integrate-failed|complete`), `control_pid_or_session`,
+`slices[]` (`id`, `paths`, `worktree_path`, `branch`, `wright_status`,
+`transfer_commit`).
+
+## Lifecycle
+
+1. Orient/gate; parse N; select ≤N path-disjoint pending slices.
+2. Write lease; freeze `B=HEAD`; `parallel create` worktrees.
+3. Dispatch ≤3 wrights in parallel (cwd=worktree; allowlist; prove `HEAD==B`).
+4. Inspect + fail-on-red → `green|red|gap`.
+5. Any red/gap → **abort** (no partial integrate). All green → serial integrate.
+6. Integrate: `transfer_commit` descends from `B`; `` `<base>..<transfer>` ``
+   path-exact; apply in plan order. Conflict → reset to `B`, `integrate-failed`.
+7. Success: FF control; union `touched-files.md`; update state/evidence; AFK +1
+   per integrated sibling; optional `check candidate`.
+8. Cleanup: success removes worktrees/branches; abort keeps until acknowledged.
+
+## Engine verbs
+
+```text
+devrites-engine parallel create|record-green|abort|integrate|cleanup|status
+devrites-engine parallel lease-write|lease-read|lease-clear
+```
+
+Go is SSOT. Skill calls the engine — never ad-hoc git/bash orchestration.
+
+## Host
+
+Claude: N concurrent Task wrights (`acceptEdits`, cwd=worktree). Codex: require
+host-explicit concurrent worktree writers + native reconcile; else force serial.
+Never two writers in one worktree; never root-emulated concurrency.

package/pack/.claude/skills/rite-build/reference/phase-contract.md

@@ -2,6 +2,7 @@
 
 See [`one-slice-cycle.md`](one-slice-cycle.md); candidate lifecycle is
 [`candidate-integrity.md`](../../devrites-lib/reference/candidate-integrity.md).
+Opt-in `--parallel N` uses [`parallel-batch.md`](parallel-batch.md) instead of steps 2–8.
 
 1. **Orient and gate.** Read core, `.devrites/ACTIVE`, `state.md`, and required
    slice artifacts. Require `Implementation readiness: READY`, its current
@@ -24,14 +25,14 @@ See [`one-slice-cycle.md`](one-slice-cycle.md); candidate lifecycle is
    dispatch the exact `devrites-slice-wright` fresh. Root never writes those product
    paths, wright never widens, and a missing profile stops.
 <!-- workflow-artifact-adapter: {"module":"devrites-lib/reference/standards/workflow-artifacts.md","entry":"Build gate enters or resumes transaction","action":"invoke canonical operation table; reconcile exact result","return":"same slice/checkpoint cursor or Plan/Vet route"} -->
-4. **Inspect the return.** Wait; compare its file list and `git diff --name-only`
+1. **Inspect the return.** Wait; compare its file list and `git diff --name-only`
    with the contract. Reject stale, partial, malformed, or out-of-scope work.
    Preserve user work; source restoration uses the same bounded wright.
-5. **Challenge stood decisions.** For each stood decision, run exact
+2. **Challenge stood decisions.** For each stood decision, run exact
    `devrites-doubt-reviewer` fresh/read-only and record accepted or resolved-rejected
    in `decisions.md`. A missing verdict, principle breach, scope change, or
    irreversible risk blocks.
-6. **Prove without guessing.** Against the frozen pre-slice candidate, inspect
+3. **Prove without guessing.** Against the frozen pre-slice candidate, inspect
    test hunks for deletion, skipping/focus, tautology, or weaker expectations. Dispatch exact
    `devrites-test-analyst` on that immutable diff; missing account or adverse criterion
    verdict is Critical. Run only `test-plan.md` repository/CI commands, capture output,
@@ -47,14 +48,14 @@ See [`one-slice-cycle.md`](one-slice-cycle.md); candidate lifecycle is
    is progress; a different Critical/Important invariant gets its own fingerprint.
    Ask humans only for product decisions,
    irreversible risk, or genuinely human-only access.
-7. **Record.** After green proof, upsert `touched-files.md`'s authoritative candidate
+4. **Record.** After green proof, upsert `touched-files.md`'s authoritative candidate
    manifest from the actual scoped diff with explicit `present`/`deleted` rows;
    update `state.md`, `evidence.md`, and applicable UI/browser evidence. The manifest
    stays mutable until Polish closes it.
    Record stood decisions/dead ends in `decisions.md`; update checked assumptions'
    status/evidence, never leaving a disproved row live. If code reveals a durable
    project rule, propose a reviewed `AGENTS.md`/nearest-doc update, not a scored ledger.
-8. **AFK and reply.** Under `afk-discipline.md`, root charges
+5. **AFK and reply.** Under `afk-discipline.md`, root charges
    exactly once after each green built slice, never below zero; stop before another dispatch at zero, and fail closed
    on malformed budget. Use the reply contract; name the next pending slice or, only
    when all slices are built, `/rite-prove`. Emit no decorative progress renderer or

package/pack/.claude/skills/rite-build/reference/wright-dispatch.md

@@ -26,8 +26,8 @@ supported. Regardless of host defaults, the wright's first command must prove ac
 `worktree_base`. Mismatch returns a gap with no write before project reads or baseline proof.
 
 The isolated wright returns one local unpushed `transfer_commit`, its `worktree_base`,
-and exact files. Root proves descendant base, exact `git diff --name-only
-<base>..<transfer>`, no `.devrites/**`/submodule/symlink/unrelated delta, unchanged
+and exact files. Root proves descendant base, exact `git diff --name-only`
+`` `<base>..<transfer>` ``, no `.devrites/**`/submodule/symlink/unrelated delta, unchanged
 source base, and no user-work overwrite. Use only host-native explicit reconciliation;
 never ad hoc copy, cherry-pick, or merge from read-only root. Compare transferred bytes,
 run approved proof, record evidence, then let host remove worktree.
@@ -35,7 +35,10 @@ run approved proof, record evidence, then let host remove worktree.
 Conflict, extra/missing commit, moved base, or cleanup failure is `gap`/STOP:
 preserve the worktree and commit. Without explicit reconciliation, use same-worktree serial.
 Parallel writer work remains forbidden until this serial pilot measures transfer,
-conflict, proof, and review outcomes on both hosts.
+conflict, proof, and review outcomes on both hosts. Opt-in `/rite-build --parallel N`
+(2≤N≤3) is the only exception: path-disjoint fan-out, abort-batch, and control
+`parallel-lease.md` under [`parallel-batch.md`](parallel-batch.md). Same-worktree multi-writer / root-emulated
+worktrees stay forbidden.
 
 ## Prepare
 
@@ -60,6 +63,7 @@ conflict, proof, and review outcomes on both hosts.
 Ask the host for the exact writer in fresh context and wait. Use at most one writer
 across all linked worktrees for this workspace. Never run two writers in one worktree,
 run isolated and same-worktree writers concurrently, or substitute a generic agent.
+Opt-in `/rite-build --parallel N` fans out only under [`parallel-batch.md`](parallel-batch.md).
 
 ## Inspect and prove
 

package/pack/.claude/skills/rite-clarify/reference/anti-patterns.md

@@ -0,0 +1,24 @@
+# /rite-clarify anti-patterns
+
+Load this when tempted to skip clarify, assume product choices, or write
+`Decision coverage: CLEAR` before every material row has an owner.
+
+Pack-wide rationalizations: see
+[standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+| --- | --- |
+| "We already discussed this in chat." | Chat is not durable decision coverage. Scan topology and record owners in workspace artifacts. |
+| "The answer is obvious — assume it." | Product, scope, policy, and irreversible-risk choices are human-owned unless already recorded in an accepted decision. |
+| "Most rows are clear — good enough for AFK." | Partial/Missing material rows block CLEAR and block AFK arming. |
+| "Skip clarify for this small change." | Clarify is mandatory and adaptive; it may ask no questions, but it still runs the scan. |
+| "I'll clarify during build if needed." | Unowned decisions discovered in build are expensive drift. Close them before plan/vet. |
+
+## Red flags in your own output
+
+- `Decision coverage: CLEAR` with Partial/Missing material rows still open.
+- Product/policy choices recorded without a human packet or cited prior decision.
+- AFK armed or `/rite-define` started before CLEAR is durable.
+- Clarify skipped because the user said they were "in a hurry".

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

@@ -16,8 +16,9 @@ standalone token occurs in current `$ARGUMENTS`; earlier context cannot activate
 1. Map policy→instruction, reusable work→skill, specialist→agent, external capability→plugin/MCP.
 2. Inspect target/host docs; reuse before copying.
 3. Draft smallest nearest-scope change; do not restate safeguards.
-4. Show path/exact diff; wait.
-5. Write approved artifacts, validate natively, keep no mirror.
+4. For any new or edited skill/agent Markdown, run `devrites-engine check skill-trust <path>` before showing the diff. HIGH findings block; MEDIUM findings need explicit human acknowledgment in the proposal.
+5. Show path/exact diff; wait.
+6. Write approved artifacts, validate natively, keep no mirror.
 
 Here, edit canonical source and generate; never edit derived artifacts.