devrites 5.10.2 → 5.12.0

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

@@ -0,0 +1,120 @@
+# Checkpoint protocol: what `/rite-build` does when a slice is HITL
+
+HITL slices pause **pre-action** as a ranked **option set** before any code:
+
+- **Interactive:** `AskUserQuestion`; record to `questions.md`/`decisions.md`; clear gate;
+  continue in place (no `/rite-resolve` round-trip).
+- **Absent / AFK / notify-only:** persist open question + `Awaiting human`, notify, **stop**.
+  Resume via `/rite-resolve` (or `--batch`).
+
+## Render contract
+
+Render the checkpoint in user-facing output **and** persist it for the next session / AFK
+observer.
+
+### User-facing render: the option set
+
+Present as `AskUserQuestion` ranked **option set** ([`afk-hitl.md`](../../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>
+   proposed: <the recommended option restated; matches option 1>
+   raised_at: <iso>
+   ```
+
+2. **`state.md` updates:**
+
+   ```markdown
+   - Status: awaiting_human
+   - Active slice: <N — name>
+   - Slice mode: HITL
+   - Next step: /rite-resolve <qid> "<answer>"
+
+   ## Awaiting human
+   - qid: <q-...-NNN>
+   - gate: <gate>
+   - question: <Checkpoint text>
+   - proposed: <one-paragraph best-guess>
+   - raised_at: <iso>
+   - blocking_slices: [<list, from `Blocked by` lookups>]
+   ```
+
+3. **`notify:` hook (if `.devrites/AFK` defines one):** export all six env vars from the
+   canonical contract in [`afk-discipline.md`](afk-discipline.md) (the `notify:` hook
+   contract table is the source of truth):
+
+   ```bash
+   DEVRITES_QID="$qid" \
+   DEVRITES_GATE="$gate" \
+   DEVRITES_SLICE="$slice_id" \
+   DEVRITES_SLUG="$slug" \
+   DEVRITES_QUESTION="$question" \
+   DEVRITES_PROPOSED="$proposed" \
+   sh -c "$notify_cmd"
+   ```
+
+   Fire after workspace write. Hook failure does **not** roll back the pause (best-effort).
+
+## qid generation
+
+Format: `q-YYYY-MM-DD-NNN`, where `NNN` is the next sequential integer for that date in
+`questions.md`. The controlling root must scan every question header matching
+today's prefix, collect its numeric suffixes, and select one above the highest
+observed suffix (or `001` when none exist), advancing until it is unused. Then
+re-read `questions.md` immediately before the append and repeat the scan. Append only if
+the same candidate is still the next unused id; otherwise recompute. There is no
+reservation or engine command for qids.
+
+## When AFK is active
+
+If `.devrites/AFK` exists and the slice `Gate` is in `allow_gates`, skip this protocol and
+auto-pick recommended option 1:
+
+- `advisory`: log `gate: advisory` + `decisions.md`, then dispatch wright.
+- `validating` (only if allowed): dispatch wright; on return log `gate: validating`, mark
+  `built (pending review)`, continue. Slice states remain `pending|built`; feature
+  acceptance is `/rite-prove`. Open `validating` is NO-GO at seal until `/rite-resolve`.
+
+`blocking` / `escalating` / irreversible-risk always use this protocol (`afk-discipline.md`).
+
+## Multi-question pauses
+
+**One question per pause.** Multiple HITL checkpoints → `/rite-plan reslice`.
+
+## What NOT to do
+
+- Don't write code then pause — pre-action only.
+- Don't render without persisting `state.md` + `questions.md`.
+- Don't self-answer a human pause via `proposed:` — `/rite-resolve` needs an explicit
+  answer (distinct from interactive pick / AFK auto-pick on `allow_gates`).
+- Don't put `notify:` output in chat; don't fire `notify:` on advisory-only entries.

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

@@ -0,0 +1,62 @@
+# Checkpoint: land local WIP only after the check loop is green
+
+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.
+
+## 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 --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.
+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 the commit lands, run `devrites-engine check regression <slug> --update`
+to ratchet the workspace progress baseline — the landed slice, newly checked
+acceptance criteria, and resolved questions become the new floor that later
+checks compare against. A `BLOCKED` compare before that ratchet means durable
+facts were lost this cycle; restore or route them before landing the commit.
+
+## 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/devin/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/devin/skills/rite-build/reference/one-slice-cycle.md

@@ -0,0 +1,51 @@
+# One-slice cycle
+
+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.
+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
+   (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: required build/browser/E2E, then returned-diff/path review; fail-on-red
+            (red/gap → repair wright, then re-review/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      → HITL root reports and stops. AFK with parallel cap>1: return to parallel-batch selection and run the new N_eff; 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/devin/skills/rite-build/reference/output.md

@@ -0,0 +1,33 @@
+# rite-build output
+
+**Slices remain:**
+
+```text
+Done: built slice <n> — <name>.
+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
+Record: .devrites/work/<slug>/evidence.md
+↻ Hygiene: /clear between slices; /rite-handoff if away > a few hours
+```
+
+**All built:**
+
+```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-prove
+Record: .devrites/work/<slug>/evidence.md
+↻ Hygiene: /clear before /rite-prove; /rite-handoff if away > a few hours
+```
+
+HITL returns after one green slice. Only explicit `.devrites/AFK` lets the
+controlling root chain another pending slice after green-proof, cap, and pause
+gates. Every `devrites-slice-wright` returns after exactly one slice.
+
+At all built, Build never enters `/rite-prove` automatically; a higher-level
+orchestrator may invoke it only under its own contract. Awaiting-human or
+stopped states use the shared reply contract.

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

@@ -0,0 +1,223 @@
+# 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≤10**) | N is a **cap**, not a quota: run the largest eligible set ≤ N |
+| non-integer / `N≤0` / `N>10` | Hard refuse (no silent clamp) |
+| Autocomplete `--parallel N` | N is the cap for this run; leftover sentinel `max_parallel` is ignored, then `/rite-autocomplete` writes or replaces only `max_parallel: N` |
+| Autocomplete, no flag | Same path, cap from sentinel `max_parallel` else 10; serial only when ineligible |
+
+AFK caps `N`. Charge green siblings once after integrate; abort /
+integrate-failed → **0**. `parallel create` refuses while a lease exists.
+Reconcile retained repair-round artifacts by exact causal fingerprint before honoring a stored blocked status/verdict. Blocked status, round count, or distinct finding alone cannot stop cold resume: establish missing or stale review coverage under step 4; repair unless a stop condition remains evidenced.
+
+## Dynamic selection and re-batching
+
+Size each batch by what is runnable **now**, never by the requested number:
+
+```text
+N_eff = min(
+  cap                  -- this invocation's --parallel N (wins over leftover sentinel max_parallel)
+                       | else sentinel max_parallel | else 10 (autocomplete default)
+  eligible set         -- dependency-satisfied pending slices, pairwise path-disjoint
+  AFK headroom         -- remaining max_slices, max_agents, max_minutes, review queue
+  host capacity        -- concurrent worktree writers + the runtime isolation table
+)
+```
+
+Select **greedily in plan order**: pass every currently dependency-ready pending slice
+(plan order, `Files likely touched`) to
+`devrites-engine parallel select --cap N [--root <dir>]`. `N_eff ≥ 2` → parallel batch;
+`N_eff = 1` → one serial round; nothing pending → Prove. A cap that cannot be filled
+is normal: take fewer. Serial is this round's size, not the rest of the run.
+
+**Re-batch automatically after every completed round** (parallel integrate+cleanup or
+a serial slice). Re-read `state.md`, pending slices, and the tree, then run
+`parallel select` again: finished work leaves the pending set, and satisfied
+dependencies unlock new slices. Under `.devrites/AFK` and `/rite-autocomplete` the
+repeat is the same run — HITL stops after each batch. `--parallel 5` with one eligible
+slice runs that one; when two to five then become eligible, the next round takes that
+many. **Failing case:** the run stays one-by-one after a serial round even though more
+slices are now eligible under the same cap.
+
+## 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`). Input is `{"slices":[{"id":"SLICE-002","paths":["src/policy.rs","src/policy/mod.rs"]}]}`
+(or a top-level array) built from each candidate's `Files likely touched`.
+Exit `0` proves path disjointness only; fan-out also requires independent
+validation. A shared interface change and its implementers that must compile
+together form one validation unit, even in different files. Repair the slice
+contract into one bounded slice or sequence compatible steps before dispatch;
+do not label coupled siblings independently green. Else force serial. Inspect-time
+overlap → sibling **gap** (a shared path is a contract defect). **Failing
+case:** two parallel wrights share a path and fan-out proceeds without that
+check.
+
+## Control vs workers
+
+Control owns `.devrites/work/<slug>/` (lease + 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 the cap; compute `N_eff` and select the eligible set
+   ([Dynamic selection and re-batching](#dynamic-selection-and-re-batching)) —
+   candidates from `orient` `task_graph.slices` + built list, each candidate's
+   `Files likely touched` via `observe slice`, then
+   `parallel select --cap N` (pairwise disjointness is inside that verb).
+   Preflight each selected slice with `devrites-engine check slice <slug>
+   <id>`; a malformed contract is dropped from the batch and recorded as a
+   gap, not dispatched.
+2. Write lease; freeze `B=HEAD`; `parallel create` worktrees.
+3. Dispatch ≤10 wrights in parallel (cwd=worktree; allowlist; prove `HEAD==B`).
+4. Inspect each returned path list, cumulative diff from `B`, transfer identity,
+   and required result fields against the immutable contract. Reject malformed,
+   stale, or out-of-scope work. Apply
+   [independent Build review](phase-contract.md#independent-build-review): first
+   full inventory, then bounded owning-role rechecks after repairs. Gap or
+   Critical/Important → `gap`; else approved proof → `green|red|gap`.
+   Reviewer fan-out for a batch is itself batched under
+   [`parallel-dispatch.md`](../../devrites-lib/reference/parallel-dispatch.md#scale-limits)
+   (≈4 concurrent read-only reviewers, 8 only with disjoint paths), and `max_agents`
+   headroom bounds the batch size — one batch never assumes unbounded reviewers.
+5. Non-green siblings → **repair round** (below) in the same worktrees; lease
+   stays `running` — no abort while repair budget remains. A green sibling →
+   `parallel record-green`. No partial integrate. All green → integrate.
+   A recoverable RED blocks integration but does not cancel independent safe running siblings.
+   Expected test-first RED is not a terminal gate failure. Cancel only for a shared
+   invalid foundation, safety/access failure, resource boundary, or explicit stop;
+   preserve completed and in-progress recoverable work and classify each result.
+6. `parallel integrate --apply-to-control` **only after steps 4–5 are green**:
+   each `transfer_commit` descends from `B` and diffs path-exact vs
+   `B`; apply each in plan order as its own local `WIP(<slug>):` commit
+   (imperative summary, never a slice id). Staging branch, then FF. Conflict →
+   reset to `B`, `integrate-failed`; classify under repair rounds (siblings stay
+   in place). Never integrate because a wright returned.
+7. Success: FF control (the branch that held `HEAD` when the batch started —
+   often `main`/`master`, otherwise whatever the user was on) to the integrate
+   tip: N local commits, never pushed; union `touched-files.md`; update
+   state/evidence; AFK +1 per integrated sibling; optional `check candidate`.
+8. Cleanup runs only after `integrate` marks the lease `complete` — work
+   landed in control, so `parallel cleanup` removes worktrees/branches.
+   Blocked/human-stopped batches keep lease, worktrees, branches — nothing is
+   removed while the batch may resume. `parallel abort` + `cleanup --force`
+   abandons the batch — the explicit human discard path; the single
+   orchestrator-emitted use is the automatic re-batch under Repair rounds,
+   where it acts as the salvage step only (uncommitted allowlisted changes →
+   slice-branch commit; branches past `B` kept; a failed salvage keeps the
+   worktree) and prints retained refs for the record. `abort` marks the lease
+   only — never rewinds control: a moved HEAD is external work, reported not
+   reset. Never integrate a rejected transfer commit.
+
+## Repair rounds
+
+Repair rejected work in place; never discard/rebuild while budget remains.
+
+- Record each round as `build-parallel-<batch>-repair-<round>.json`: each
+  non-green sibling's status, verbatim findings, transfer_commit/null.
+- Use step 4's initial inventory or affected recheck as appropriate; never start
+  a correction from an early reviewer result while required accounts are pending.
+- Classify the complete inventory: **implementation defect** (review
+  Critical/Important on the diff, red wright/proof) → one repair-all wright in
+  the same worktree with the full inventory. **Durable-plan defect**
+  (falsified contract assumption, AC unchanged) →
+  [`spec-drift-guard.md`](spec-drift-guard.md): batch-sweep contract
+  assumptions, one folded `/rite-plan repair` + one `/rite-vet` recheck
+  inline, resume repair in the same worktrees under the amended contract;
+  never emit `Fix:`. **Frozen-lease scope defect** (correction needs
+  out-of-allowlist paths or re-slicing; lease allowlists are immutable) →
+  **automatic re-batch, no human gate**: `parallel cleanup --force` salvages
+  and records refs; `parallel create` starts from control `HEAD` under the
+  corrected decomposition. Give each new wright its salvaged
+  `devrites/parallel/<slug>/<old-batch>/<slice>` ref. If the inventory proves the accepted
+  approach unsound and no corrected decomposition exists, that is exhaustion
+  → blocked, preserve, STOP. **Reviewer stall/cancel or missing
+  verdict** → reconcile the old host handle under
+  [terminal reconciliation](../../devrites-lib/reference/parallel-dispatch.md#cancellation-and-terminal-reconciliation)
+  before re-dispatching the reviewer, not the wright. **Product/policy/
+  irreversible** → stops for the human.
+- Dispatch one fresh repair-all `devrites-slice-wright` (cwd=worktree; step 3
+  rules) with the original contract + complete inventory +
+  "preserve what works; fix every finding; **then attack your own correction** —
+  probe the changed hunks for defects the fix itself introduced (adjacent cases of
+  the same rule, new observation/ordering windows, alias or boundary escapes) and
+  fold them in before returning; return a new `transfer_commit`". A correction whose
+  own diff is unexamined is not ready: a green writer gate plus an unexamined fix is
+  how the same defect family reappears one case deeper each round. Never reset
+  to `B` — that destroys the work under repair. The commit must still descend
+  from `B` and diff path-exact vs `B`.
+- Budget and exhaustion follow only
+  [the canonical retry contract](../../devrites-lib/reference/standards/afk-hitl.md#retry-cap-no-progress-loops-and-self-resolve).
+  Record one failed invariant, mechanism, reproduction, correction, and decisive
+  recheck per fingerprint; never use an umbrella like "covering" or "review is red again".
+- A distinct post-repair Critical/Important gets a new fingerprint: refresh the
+  inventory and affected owning-role rechecks. It proves neither plan defect nor
+  exhaustion. Use plan path only if inventory proves the approach unsound.
+- Stop under the canonical retry/authority/resource conditions, or when evidence
+  proves the approach unsound and no in-scope corrected decomposition exists.
+- Exhaustion is not abort: record one technical blocker (`Status: blocked`;
+  `Next step: none — technical recovery exhausted; requires new evidence or changed failure conditions`), preserve
+  lease/worktrees/branches, STOP — same fingerprint stays blocked on
+  reinvoke; new evidence resumes repair in place. Human-owned decisions use
+  the drift-guard question and wait.
+
+## Engine verbs
+
+```text
+devrites-engine parallel select --cap <1-10> [--root <dir>] [<json-file>|-]
+devrites-engine parallel create --root <repo> --slug <slug> --batch <id> --base <B> --json <file>|-
+devrites-engine parallel record-green --root <repo> --slug <slug> --slice <id> --commit <sha>
+devrites-engine parallel integrate --root <repo> --slug <slug> --apply-to-control
+devrites-engine parallel status --root <repo> --slug <slug>
+devrites-engine parallel lease-write|lease-read|lease-clear --root <repo> --slug <slug>
+# abandoning the batch is human discard only; a frozen-lease re-batch may emit
+# cleanup --force as its salvage step (see Repair rounds):
+#   parallel abort --root <repo> --slug <slug>
+#   parallel cleanup --root <repo> --slug <slug> --force   (salvages, prints retained refs)
+```
+
+`integrate` without `--apply-to-control` stages the per-sibling commits, leaves
+the lease `running` and control at `B`; cleanup still refuses — the commits
+cannot be lost. `record-green` and `integrate` also accept an `integrate-failed`
+lease, so a failed integrate retries after repair. `--apply-to-control`
+refuses when control moved past `B` or holds uncommitted changes on slice
+paths — commit/stash and retry; the batch is untouched. Go is SSOT; never
+ad-hoc git/bash orchestration.
+
+## Runtime isolation
+
+Each parallel worktree must own isolated runtime resources. Before fan-out,
+assign per-slice env (document in the lease or worktree README):
+
+| Resource | Pattern |
+| --- | --- |
+| HTTP port | `PORT=<base+N>` or `DEVRITES_PARALLEL_PORT_<slice>` |
+| Compose | `COMPOSE_PROJECT_NAME=devrites-<slug>-<batch>-<slice>` |
+| SQLite/DB file | separate path under the worktree or `/tmp` |
+| Dev server | one process per worktree; never share a listener |
+
+Reusing the control worktree's running server, DB, or compose stack across
+siblings causes cross-slice pollution and flaky proof. Force serial if
+isolation cannot be established.
+
+## Host
+
+Devin: N concurrent `run_subagent` 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/generated/devin/skills/rite-build/reference/phase-contract.md

@@ -0,0 +1,93 @@
+# rite-build phase contract
+
+Apply [`one-slice-cycle.md`](one-slice-cycle.md) and
+[`candidate-integrity.md`](../../devrites-lib/reference/candidate-integrity.md).
+Opt-in `--parallel N` replaces steps 2–8 with [`parallel-batch.md`](parallel-batch.md);
+Spec Drift Guard still applies.
+
+1. **Gate.** Read core, `.devrites/ACTIVE`, then `devrites-engine orient <slug>`
+   (`devrites-engine next <slug>` prints the minimal remaining path) and the
+   Build read-next in
+   [`workspace-artifact-schema.md`](../../devrites-lib/reference/workspace-artifact-schema.md#read-next-by-phase):
+   the selected slice via `devrites-engine observe slice <slug> <SLICE-ID>`, not whole
+   `tasks.md`; over-budget or `bulk_files` artifacts are read by anchor only. Require
+   `Implementation readiness: READY`, current `Readiness inputs SHA-256`, exact
+   required accounts, ID/meaning traceability and green proof preflight.
+   Run `devrites-engine check readiness <slug>`; any miss/nonzero blocks.
+2. **Select.** Pick the lowest pending slice whose `depends_on` are all built, using
+   `orient` `task_graph.slices` plus the `state.md` built list — never by scanning
+   `tasks.md`; then `observe slice` it. Restate its goal, ACs, exclusions and exact paths. Include
+   applicable topology/data/integration invariants and failure/recovery/proof cases.
+   Verify relevant assumptions live; falsified acceptance/architecture/scope/proof
+   routes through Spec Drift Guard. Resolve human-owned/irreversible gates before
+   source work; AFK follows its ceiling. Vet-ready Workflow Artifacts use
+   [`workflow-artifacts.md`](../../devrites-lib/reference/standards/workflow-artifacts.md).
+3. **Dispatch.** Apply [`wright-dispatch.md`](wright-dispatch.md). Put the smallest
+   exact project-relative source/test path list directly in the task;
+   dispatch the exact `devrites-slice-wright` fresh. Root never writes product
+   paths; wright cannot widen scope; missing profile blocks.
+<!-- 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.** Wait; run `devrites-engine check diff-scope <slug> --allow
+   <contract-paths>` for the mechanical returned-paths ⊆ contract check **before**
+   any reviewer dispatch — a violation returns through the bounded wright without
+   spending review. Then compare returned paths and `git diff --name-only` with the
+   contract for semantics diff-scope cannot judge (stale/partial/malformed work;
+   preserved user work). Restoration uses the bounded wright.
+5. **Review.** Apply [Independent Build review](#independent-build-review).
+   Missing verdicts, principle breaches and open Critical/Important block acceptance.
+6. **Prove.** Against the frozen pre-slice candidate inspect
+   test hunks for deletion, skipping/focus, tautology, or weaker expectations.
+   Use step 5's exact test-analyst account; missing/adverse criterion verdict is
+   Critical. Run only `test-plan.md` repository/CI commands, record output, recheck
+   `git diff --name-only`. Missing/weakened/red/source-mutating proof cannot pass.
+   Pre-existing/environment-specific claims need a predating same-command,
+   same-environment baseline; otherwise unresolved.
+
+   Technical failure uses `devrites-debug-recovery` and
+   [canonical recovery](../../devrites-lib/reference/standards/afk-hitl.md#retry-cap-no-progress-loops-and-self-resolve).
+   Reapply host admission before correction; affected proof/evidence follows candidate
+   integrity. Human gates remain product/irreversible/access decisions.
+7. **Record green.** Upsert actual scoped `present`/`deleted` rows in `touched-files.md`;
+   update state, evidence and applicable UI/browser proof. Checkpoint per
+   [`checkpoint.md`](checkpoint.md) only after steps 5–6 are green and every
+   repair wright has been re-reviewed and re-proved; never on wright return.
+   Manifest stays mutable until Polish. For a release milestone, after the last slice's rows run
+   `devrites-engine state merge-manifest <slug>` to fold the recorded
+   predecessor chain into the union manifest before Prove. Record stood
+   decisions/dead ends; refresh verified/falsified
+   assumptions. Propose reviewed durable project rules in the nearest guidance.
+8. **Account/reply.** Apply `afk-discipline.md`: charge
+   exactly once after each green built slice; never negative, stop at zero,
+   malformed budget fails closed. Reply names next pending slice or `/rite-prove`
+   only when all built; no decorative renderer/dispatch telemetry.
+
+One contract builds one slice: preserve TDD, exact paths and independent judgment.
+
+## Independent Build review
+
+After inspection, freeze full slice scope and cumulative baseline diff. Initial
+inventory: one full-diff `devrites-code-reviewer`, one `devrites-test-analyst`,
+and one exact `devrites-doubt-reviewer` per stood decision that meets
+`devrites-doubt` § When to use (boundary, data model, auth, public API, migration,
+user flow, assumption tests cannot prove); other stood decisions are recorded in
+`decisions.md` without dispatch. Dispatch fresh,
+read-only under [`parallel-dispatch.md`](../../devrites-lib/reference/parallel-dispatch.md).
+Wait for every required account to become terminal; missing/gap needs a valid result.
+Fold supported in-scope Critical/Important findings by cause into one inventory.
+Dispatch one repair-all wright instructed to fix every finding, then attack its own
+correction for fix-introduced defects before returning; durable contract defects use Spec
+Drift Guard.
+Suggestion/Nit/FYI cannot prolong recovery.
+
+Rechecks use Vet's bounded pattern: each exact responsible reviewer checks
+all open findings owned by that role and affected dependency/regression closure
+in one fresh dispatch. Supply new candidate, inventory, correction diff, tests
+and unchanged-coverage evidence under candidate integrity; include newly triggered
+roles. A changed contract or uncertain impact requires the full inventory.
+Collect all required rechecks before another folded correction. Canonical recovery
+owns fingerprints/budget and the
+[late-finding rule](../../devrites-lib/reference/standards/afk-hitl.md#retry-cap-no-progress-loops-and-self-resolve):
+a recheck's `Late:` rows on hunks unchanged since that role's previous pass go to
+`touched-files.md` `## Review trail` for `/rite-review`, not into another slice
+repair, unless Critical with a failure path. Evidenced scope coverage never
+guarantees no later defect; the feature-level Review and Seal gates still run.