devrites 7.1.2 → 7.2.0

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

@@ -0,0 +1,260 @@
+# Parallel batch (`--parallel N`)
+
+> Root-only: not inlined in --role bundles.
+
+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** with
+`devrites-engine parallel select --slug <slug> --cap N --from-plan`: the engine
+reads the ready set (tasks.md dependencies checked `built` in `state.md`, minus
+running-lease slices) and each slice's Writer allowlist (else `Files likely
+touched`), plus its manifest/lockfile when `External dependencies:` is not none;
+`next` prints `eligible_now:`/`batch:`. `n_eff` counts new picks only.
+With a running lease, a single new pick still uses `parallel add`;
+`n_eff=0` with a running lease waits for siblings, not Prove. Without one:
+≥2 → parallel batch, 1 → serial, none pending → Prove.
+Serial is this round only; a cap need not be filled.
+
+**Refill per landing; never wait for the batch.** Each sibling lands alone when
+green ([Lifecycle](#lifecycle) step 6). Re-read state, pending slices, and the
+tree; reselect: unlanded siblings hold
+their slots and paths, landed ones count as built, and only new picks print;
+`parallel add` starts each from the control tip and its wright dispatches at once.
+No lease → plain `select` + `create`. AFK/autocomplete is one run; HITL stops after
+each landing. **Failing case:** three siblings are green, one is repairing, and no
+new slice starts.
+
+## 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.
+
+Before `parallel select`, add each slice's hidden write surfaces (list owner:
+[repository-topology.md § Ownership rules](../../devrites-lib/reference/standards/repository-topology.md#ownership-rules))
+— lockfile/manifest, the generated target of an edited source, migration chain,
+snapshot directory, formatter sweep — and compare paths case-folded
+(`src/Api.ts` = `src/api.ts`); `--from-plan` adds the manifest/lockfile itself.
+Slices colliding on either run serially; the rest
+stay eligible. Record `serial: <ids> — <surface>` in `evidence.md`. Under AFK
+with `max_parallel ≥ 2`, `dispatch open` refuses a first-round build wright wave
+narrower than the from-plan batch (printing batch and command) until the wave
+holds that batch or `serial:` names every skipped pick; repair rounds, lease
+siblings, and HITL runs are never refused. **Failing
+case:** two slices each add a dependency, run in parallel, and integrate fails or
+lands a broken lockfile.
+
+## 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)) —
+   `parallel select --slug <slug> --cap N --from-plan` (ready set, write paths,
+   and pairwise disjointness are inside that verb).
+   Preflight each selected slice with `devrites-engine check slice <slug>
+   <id>`, plus `check preconditions <slug> --slice <id>` when it has a
+   `pre-dispatch <id>` preflight row; a malformed contract or non-zero
+   precondition 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`;
+   one `--slice` per sibling on the wave). A linked worktree has no `.devrites`:
+   tell each wright to run `gates precheck` with `DEVRITES_ROOT=<control>/.devrites`.
+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. Freeze and probe the sibling in its worktree:
+   `candidate freeze <slug> --wave <w> --slice <id> --base <B> --worktree <worktree_path>`,
+   `check perturb ... --worktree <worktree_path> --slice <id>`. Apply
+   [independent Build review](phase-contract.md#independent-build-review): first
+   full inventory, then bounded owning-role rechecks after repairs. Run approved
+   proof in the same window as that review. Gap or Critical/Important → `gap`;
+   else proof → `green|red|gap`.
+
+   A recheck round is one dispatch per changed surface, not one per checklist: the
+   recheck agent carries every open checklist (code, test, doubt) for that diff and
+   answers each by name. Merging cuts dispatches; dropping a checklist does not.
+   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`, then step 6 for it alone.
+   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 --slice <id> --apply-to-control` **only after its steps
+   4–5 are green**: `transfer_commit` descends from the sibling's base and diffs
+   path-exact vs it; apply as its own local `WIP(<slug>):` commit
+   (imperative summary, never a slice id). Staging branch, then FF; the engine
+   refuses (never rewinds) if anything but this lease moved control. Conflict →
+   `integrate-failed`; classify under repair rounds (siblings stay in place).
+   Never integrate because a wright returned.
+7. Each landing: FF control (the branch that held `HEAD` when the batch started —
+   often `main`/`master`, otherwise whatever the user was on) by one local commit,
+   never pushed; union that sibling's paths into `touched-files.md`; update
+   state/evidence; AFK +1; optional `check candidate`. Land every green sibling,
+   refill ([Dynamic selection](#dynamic-selection-and-re-batching)), then run the
+   feature gates once for the train
+   ([Proof tiers](phase-contract.md#proof-tiers)); the next train waits, the
+   refilled wrights do not.
+8. Cleanup runs only after the last landing 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.
+- A spent strategy is not abort: escalate per the canonical retry contract,
+  preserving lease/worktrees/branches; a fully escalated fingerprint parks and
+  the batch keeps its independent members. Repair resumes in place on
+  escalation or reinvocation. Human-owned decisions use the drift-guard
+  question and wait.
+
+## Engine verbs
+
+```text
+devrites-engine parallel select --cap <1-10> [--root <dir>] [--slug <slug>] [--from-plan | <json-file>|-]
+devrites-engine parallel create --root <repo> --slug <slug> --batch <id> --base <B> --json <file>|-
+devrites-engine parallel add --root <repo> --slug <slug> --json <file>|-
+devrites-engine parallel record-green --root <repo> --slug <slug> --slice <id> --commit <sha>
+devrites-engine parallel integrate --root <repo> --slug <slug> --slice <id> --apply-to-control
+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 commits; lease stays `running`,
+control stays at its expected tip, cleanup refuses. `record-green` and `integrate`
+accept `integrate-failed` for retry. Applied landings advance `control_tip`
+(initially `B`), permitting landings/refill. External control movement or
+uncommitted slice-path edits with `--apply-to-control` cause refusal:
+stop for the human (never stash or commit their work); 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
+
+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/generated/dsh/skills/rite-build/reference/phase-contract.md

@@ -0,0 +1,130 @@
+# rite-build phase contract
+
+> Root-only: not inlined in --role bundles.
+
+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.
+   Non-empty `orient` `inflight_waves` is reconciled first: `dispatch return` each
+   role whose account is in hand, else `dispatch abandon --reason` and re-dispatch.
+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> --baseline` (after a pre-dispatch `--snapshot`) 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). Run step 6
+   proof in the same window on the same frozen candidate; both gate step 7, and a
+   repair or source-mutating proof voids both.
+   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.
+   Wait for step 5's exact test-analyst account; missing/adverse criterion verdict is
+   Critical. Run only `test-plan.md` repository/CI commands ([tier](#proof-tiers)),
+   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.
+
+## Proof tiers
+
+With a `test-plan.md` `## Feature gates` section, step 6 runs `Tests/proof` and every
+other row; feature gates run once per landing train, on control, while worktree
+wrights continue: land every green sibling together, run the suite once, and bisect only
+on red. The next train and Prove wait for them; red is a fingerprint against slices
+landed since the last green run. Serial same-worktree mode, and plans
+without the section, run every row each round. Run gate, benchmark and proof commands
+through the host's shell tool, never a code-evaluation subprocess, whose environment
+can lack the owner's exported variables.
+
+Wrights run only the tests their changed paths reach, resolved from the merge base
+against the plan's baseline rather than the last commit; Prove and Seal always run the
+full suite. Resolve that narrow set with
+`devrites-engine check affected <changed path...>`, which expands a changed package to its
+dependent packages and widens on its own when a path is a module manifest, a generated
+artifact, CI config, shared testdata, or one it cannot classify. Widen to the full suite
+inside Build the moment a slice touches `go.mod` or a
+lockfile, generated artifacts, CI config, a shared test harness, or whenever no test can
+be named for a changed path. When selection is uncertain, run the full suite: the narrow
+set is an optimisation, never a substitute.
+
+## Independent Build review
+
+After inspection, freeze full slice scope and cumulative baseline diff with
+`devrites-engine candidate freeze <slug> --wave <w> --slice <SLICE-ID> --base <baseline>`;
+render each reviewer packet with `devrites-engine packet` (never hand-written; a doubt
+reviewer's `--focus` holds its claim, 1-3 rows `- <DEC-ID> decisions.md:<line> <claim>`). 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. Bundles take `--slice <SLICE-ID>`. 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; a
+row `check anchors` leaves Unverified or Deferred never enters it.
+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.
+A bounded recheck bundle adds `--recheck <inventory-file>` (open `Finding:` rows
+plus correction-diff paths) to its `--slice` bundle, and its `packet` adds `--recheck`: inventory and core inline, every
+other triggered standard by anchor index plus each `<file>.md § <heading>` the
+findings cite. First reviews and full-inventory rechecks keep the plain bundle.
+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.

package/pack/generated/dsh/skills/rite-build/reference/spec-drift-guard.md

@@ -0,0 +1,91 @@
+# Spec Drift Guard (build phase)
+
+Canonical Spec Drift Guard, active in `/rite-build` and referenced by other
+phases. Never silently code against a known-wrong plan.
+
+## Drift has occurred when
+- the spec says X but the code makes X impossible/wrong;
+- the plan assumes a file/API/component/route/model/command that doesn't exist;
+- tests show the acceptance criteria are incomplete or wrong;
+- browser evidence shows the intended UX doesn't work as described;
+- an official doc contradicts the planned approach;
+- the design system / existing UX pattern contradicts the planned UI;
+- a missing user decision that affects product behavior surfaces.
+
+A timing gate that fails with no code cause is a protocol or environment defect
+([performance.md § Performance gate protocol](../../devrites-lib/reference/standards/performance.md#performance-gate-protocol)),
+never another wright round.
+
+## Workflow
+```
+1. STOP coding.
+2. Record drift.md (assumed vs observed, when).
+3. Classify: requirement ambiguity | implementation-plan error | codebase reality
+   mismatch | design-system mismatch | test/evidence mismatch | external-doc mismatch
+   | user-decision required.
+4. Local repair that preserves behavior/scope/architecture/data/UX/security/migration?
+     YES, active-slice technical/tool failure → log it and use Build's bounded debug
+       recovery. Do not ask for retry authorization and do not re-plan unless the
+       durable remaining-work instructions are wrong. A Workflow Artifact byte fix
+       that keeps every admission row is this case: `OFFLINE_RECOVERY`, then
+       `/rite-vet`'s bytes-only recheck — never `/rite-plan repair`.
+     YES, durable plan is wrong → run the batch sweep below, log every
+       violation, save the caller's return cursor, then invoke `/rite-plan repair` and `/rite-vet` inline
+       without a question — ONE folded repair for all open entries, ONE
+       recheck for every open fingerprint — and resume.
+     NO, product/policy/irreversible-risk decision → ask the user (format below).
+5. Never continue on a known-wrong durable plan. A repaired active-slice implementation
+   may continue only after bounded recovery, returned-diff review, and proof gates pass.
+```
+
+## Batch sweep (before repair)
+
+Repair durable-plan drift as a folded set:
+
+1. Trace the falsified assumption's full dependency/consumer closure and affected
+   frontier, including dependent future slices. Verify unchecked paths, symbols/APIs/
+   signatures, routes, commands, versions, and artifacts there against live source.
+   Reuse the wright inventory and unchanged evidence; deterministic existence checks
+   need no dispatch. Do not rescan unrelated slices. Broaden unknown closure or shared
+   contract changes until coverage is justified; retain every known gap.
+2. Record each violation as its own `drift.md` entry/fingerprint; one folded
+   repair + one batched recheck resolves the set.
+3. A recheck-surfaced gap is a new fingerprint with its own budget — loop
+   internally, never hand an intermediate command to the human. When
+   consecutive folded repairs keep landing on the same clause set, the
+   repair packet's `convergence_pressure` marking applies (see `/rite-plan`
+   repair): bounded declared residuals may close refinements of
+   already-pinned clauses; a newly surfaced failure mode is never
+   residual-eligible. A suspect seam's declare-limitation-or-continue choice
+   routes to `/rite-clarify` like any human-owned gate — it is not an
+   intermediate command.
+4. Nothing skips or defers silently: every entry ends resolved, human-escalated,
+   or fingerprint-exhausted. Execution-only gaps (tests, UX, evidence) get the
+   identical path when they surface.
+
+## User question format
+```
+I hit spec drift:
+- Spec/plan assumed: ...
+- Code/evidence shows: ...
+- Why it matters: ...
+
+Which direction should DevRites take?
+1. Keep the requirement, change architecture by ...
+2. Adjust the requirement to match existing behavior ...
+3. Split into a follow-up feature ...
+4. Custom: describe the intended behavior
+```
+
+Never turn an objective defect, environment repair, tool bug, or proof rerun into a
+human permission question. Re-plan only when the durable plan changed.
+
+## Inline return contract
+
+The detecting phase owns backtracking and the batch sweep. Save
+`return_phase`/`return_next_action`; consume nested Plan/Vet `STOP` internally, complete
+vetted acceptance-preserving remediation, then restore the cursor and failed step.
+Never hand the human an intermediate command. The shared three-attempt causal-fingerprint
+cap still applies: a spent strategy escalates and a fully escalated fingerprint parks
+under the [retry contract](../../devrites-lib/reference/standards/afk-hitl.md#retry-cap-no-progress-loops-and-self-resolve),
+while a genuinely human-owned decision uses the question format below.

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

@@ -0,0 +1,27 @@
+# TDD / Prove-It pattern
+
+When a slice changes behavior, prove the change with a test that fails first, so you
+know the test can fail, and that your code is what makes it pass.
+
+## Red → Green → Refactor
+1. **Red:** write the smallest test that expresses the new behavior. Run it; watch it
+   fail for the *expected* reason (not a typo/import error).
+2. **Green:** write the minimum code to pass. Resist gold-plating.
+3. **Refactor:** clean up with the test as a safety net. Re-run; stay green.
+
+## Prove-It (when strict TDD doesn't fit)
+For code where a test-first flow is awkward (exploratory glue, config, some UI), still
+produce evidence:
+- Capture the current (wrong/absent) behavior: a failing assertion, a screenshot, a
+  log line.
+- Make the change.
+- Capture the new behavior the same way. The before/after pair *is* the proof.
+
+## Rules
+- Use the project's existing test framework and commands (per the discovery contract
+  [`test-command-discovery.md`](../../rite-prove/reference/test-command-discovery.md)). Don't introduce a new test runner
+  to prove a slice.
+- One behavior per test; name it for the behavior, not the function.
+- A green test you never saw fail proves nothing: always see red first.
+- Don't delete or weaken a failing test to "pass". If it's wrong, that may be drift.
+- Record the test command + result in `evidence.md`.