devrites 5.2.4 → 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/engine/internal/install/uninstall.go +3 -0
  4. package/engine/internal/lib/resolve.go +7 -0
  5. package/engine/internal/parallel/cli.go +62 -8
  6. package/engine/internal/parallel/git.go +46 -7
  7. package/engine/internal/parallel/lease.go +7 -0
  8. package/engine/internal/parallel/ops.go +256 -72
  9. package/engine/internal/parallel/ops_test.go +223 -6
  10. package/engine/internal/parallel/parallel_test.go +229 -6
  11. package/engine/internal/parallel/pathdisjoint.go +18 -3
  12. package/engine/internal/parallel/pathdisjoint_test.go +21 -0
  13. package/pack/.claude/skills/rite-autocomplete/SKILL.md +2 -3
  14. package/pack/.claude/skills/rite-build/SKILL.md +9 -3
  15. package/pack/.claude/skills/rite-build/reference/checkpoint.md +13 -15
  16. package/pack/.claude/skills/rite-build/reference/one-slice-cycle.md +2 -2
  17. package/pack/.claude/skills/rite-build/reference/parallel-batch.md +87 -20
  18. package/pack/generated/claude/skills/rite-autocomplete/SKILL.md +2 -3
  19. package/pack/generated/claude/skills/rite-build/SKILL.md +9 -3
  20. package/pack/generated/claude/skills/rite-build/reference/checkpoint.md +13 -15
  21. package/pack/generated/claude/skills/rite-build/reference/one-slice-cycle.md +2 -2
  22. package/pack/generated/claude/skills/rite-build/reference/parallel-batch.md +87 -20
  23. package/pack/generated/codex/skills/rite-autocomplete/SKILL.md +2 -3
  24. package/pack/generated/codex/skills/rite-build/SKILL.md +9 -3
  25. package/pack/generated/codex/skills/rite-build/reference/checkpoint.md +13 -15
  26. package/pack/generated/codex/skills/rite-build/reference/one-slice-cycle.md +2 -2
  27. package/pack/generated/codex/skills/rite-build/reference/parallel-batch.md +87 -20
  28. package/pack/generated/omp/skills/rite-autocomplete/SKILL.md +2 -3
  29. package/pack/generated/omp/skills/rite-build/SKILL.md +9 -3
  30. package/pack/generated/omp/skills/rite-build/reference/checkpoint.md +13 -15
  31. package/pack/generated/omp/skills/rite-build/reference/one-slice-cycle.md +2 -2
  32. package/pack/generated/omp/skills/rite-build/reference/parallel-batch.md +87 -20
  33. package/package.json +1 -1
@@ -1,13 +1,8 @@
1
- # Checkpoint: crash-survivable WIP commits (opt-in)
1
+ # Checkpoint: proven slices land as local WIP commits
2
2
 
3
- `.devrites/` markdown survives compaction, but a slice's source normally stays
4
- uncommitted until `/rite-ship`. A crash during unattended Build can lose that source.
5
- Checkpoint mode commits each proven slice as a local `WIP`, so it survives the session.
6
-
7
- ## When it's on
8
- Opt in with `.devrites/CHECKPOINT`, the mirror of `.devrites/AFK`. When absent,
9
- `/rite-build` makes no checkpoint. Autocomplete sets it for long unattended runs.
10
- **Local-only:** never push a checkpoint or let scratch work trigger CI.
3
+ A slice's source never stays uncommitted after its gates are green: at RECORD
4
+ the orchestrator commits the proven slice as a local `WIP`, so the working
5
+ tree stays clean and the work survives a crash or compaction.
11
6
 
12
7
  ## The checkpoint commit: orchestrator, at RECORD, after gates are green
13
8
  A checkpoint records a **proven** slice only after its gates are green. Stage the exact
@@ -16,7 +11,6 @@ Never stage `touched-files.md`, a directory, glob, unrelated path, or user chang
16
11
  Verify the staged set, then commit locally with a `[devrites-context]` body:
17
12
 
18
13
  ```bash
19
- [ -f .devrites/CHECKPOINT ] || exit 0 # sentinel absent → no-op, silent
20
14
  git commit -m "WIP(<slug>): <slice>" -m "$(cat <<'BODY'
21
15
  [devrites-context]
22
16
  decisions: <one-line delta this slice added to decisions.md>
@@ -26,6 +20,10 @@ BODY
26
20
  )"
27
21
  ```
28
22
 
23
+ When host reconciliation already landed the isolated transfer commit, nothing
24
+ is staged and the step no-ops. **Local-only:** never push a checkpoint or let
25
+ scratch work trigger CI.
26
+
29
27
  ## Restore
30
28
  After a crash, a fresh session may read the last `WIP(<slug>)` body as crash context.
31
29
  Authoritative state remains in `.devrites/`: validate the body against that workspace;
@@ -39,8 +37,8 @@ one atomic feature commit before the Conventional-Commit ladder: see the collaps
39
37
  [git-ship.md](../../rite-ship/reference/git-ship.md). Result: one clean commit, bisect
40
38
  stays green.
41
39
 
42
- ## Autocomplete clean-baseline use
43
- `/rite-autocomplete` may arm checkpoints after verifying a clean or accepted baseline.
44
- They authorize neither red-gate continuation nor Ship. Each wright returns after one
45
- slice; HITL stops, while explicit `.devrites/AFK` lets the controlling Build root chain
46
- another green slice only under its cap and pause rules.
40
+ ## Autocomplete
41
+ Checkpoints are unconditional; `/rite-autocomplete` needs no sentinel arming.
42
+ Each wright returns after one slice; HITL stops, while explicit `.devrites/AFK`
43
+ lets the controlling Build root chain another green slice only under its cap
44
+ and pause rules.
@@ -24,8 +24,8 @@ DISPATCH → hand the slice contract to devrites-slice-wright (fresh context).
24
24
  PROVE → root: required build/browser/E2E, then returned-diff/path review; fail-on-red
25
25
  RECORD → orchestrator: after green verification, update state.md/evidence.md and
26
26
  upsert the authoritative candidate manifest from the actual scoped diff
27
- (CHECKPOINT) → orchestrator: if .devrites/CHECKPOINT is set, commit the proven slice
28
- local-only as WIP(<slug>) with a [devrites-context] body → survives a crash (checkpoint.md)
27
+ (CHECKPOINT) → orchestrator: commit the proven slice local-only as WIP(<slug>)
28
+ with a [devrites-context] body → clean tree, survives a crash (checkpoint.md)
29
29
  NEXT → HITL root reports and stops; AFK root may repeat only under afk-discipline.md
30
30
  ```
31
31
 
@@ -12,8 +12,8 @@ Opt-in only. Default `/rite-build` stays [`one-slice-cycle.md`](one-slice-cycle.
12
12
 
13
13
  AFK caps `N` by remaining budget. Charge **only after successful integrate**
14
14
  (once per integrated green sibling). Abort / integrate-failed → **0**. A
15
- `running` lease blocks another `/rite-build`. Any present lease blocks
16
- `parallel create` until cleanup.
15
+ present lease is resumable: `/rite-build` continues it (repair rounds or the
16
+ blocked verdict); `parallel create` refuses until cleanup.
17
17
 
18
18
  ## Path-disjoint
19
19
 
@@ -22,8 +22,9 @@ duplicates, absolutes, `.devrites/**`. Empty pairwise intersection required.
22
22
 
23
23
  **SSOT:** `devrites-engine check path-disjoint [--root <dir>] [<json-file>|-]`
24
24
  (N≥2 only; pass `--root`). Exit `0` → fan-out; else force serial. Inspect-time
25
- overlap → sibling **gap** abort. **Failing case:** two parallel wrights share a
26
- path and fan-out proceeds without that check.
25
+ overlap → sibling **gap** (a shared path is a contract defect). **Failing
26
+ case:** two parallel wrights share a path and fan-out proceeds without that
27
+ check.
27
28
 
28
29
  ## Control vs workers
29
30
 
@@ -44,26 +45,92 @@ Lease: `batch_id`, `created_at`, `base_sha`, `n`,
44
45
  3. Dispatch ≤10 wrights in parallel (cwd=worktree; allowlist; prove `HEAD==B`).
45
46
  4. Inspect + fail-on-red → `green|red|gap`. Independent-review Critical is `gap`
46
47
  even when targeted tests are green.
47
- 5. Any red/gap → **abort** (no partial integrate). All green serial integrate.
48
- 6. Integrate: `transfer_commit` descends from `B`; `` `<base>..<transfer>` ``
49
- path-exact; apply in plan order. Conflictreset to `B`, `integrate-failed`.
50
- 7. Success: FF control; union `touched-files.md`; update state/evidence; AFK +1
51
- per integrated sibling; optional `check candidate`.
52
- 8. Cleanup: success removes worktrees/branches. Abort keeps them as repair
53
- inputs until the root consumes them: agent-owned plan gaps (AC unchanged)
54
- follow [`spec-drift-guard.md`](spec-drift-guard.md) — batch-sweep all
55
- siblings' contract assumptions, one folded `/rite-plan repair` + one
56
- `/rite-vet` recheck inline, then cleanup and resume Build. Do not emit
57
- `Fix: /rite-plan repair`. Product/policy/irreversible-risk still stops.
48
+ 5. Non-green siblings → **repair round** (below) in the same worktrees; lease
49
+ stays `running` no abort while repair budget remains. A green sibling →
50
+ `parallel record-green`. No partial integrate. All green → integrate.
51
+ 6. Integrate: each `transfer_commit` descends from `B` and diffs path-exact vs
52
+ `B`; squash-apply all in plan order into one `WIP(<slug>):` commit on the
53
+ staging branch (Ship collapses it). Conflict reset to `B`,
54
+ `integrate-failed`; classify under repair rounds (siblings stay in place).
55
+ 7. Success: FF control to the squash commit the batch lands as one local
56
+ commit, never pushed; union `touched-files.md`; update state/evidence;
57
+ AFK +1 per integrated sibling; optional `check candidate`.
58
+ 8. Cleanup runs only after `integrate` marks the lease `complete` — work
59
+ landed in control, so `parallel cleanup` removes worktrees/branches.
60
+ Blocked/human-stopped batches keep lease, worktrees, branches — nothing is
61
+ removed while the batch may resume. `parallel abort` + `cleanup --force`
62
+ abandons the batch — the explicit human discard path; the single
63
+ orchestrator-emitted use is the automatic re-batch under Repair rounds,
64
+ where it acts as the salvage step only (uncommitted allowlisted changes →
65
+ slice-branch commit; branches past `B` kept; a failed salvage keeps the
66
+ worktree) and prints retained refs for the record. `abort` marks the lease
67
+ only — never rewinds control: a moved HEAD is external work, reported not
68
+ reset. Never integrate a rejected transfer commit.
69
+
70
+ ## Repair rounds
71
+
72
+ Rejected work is repaired in place — never discarded and rebuilt from scratch
73
+ while budget remains.
74
+
75
+ - Record each round as `build-parallel-<batch>-repair-<round>.json`: per
76
+ non-green sibling — status, verbatim findings, transfer_commit or null.
77
+ - Classify first: **implementation defect** (review Critical on the diff, red
78
+ wright/proof) → repair wright in the same worktree. **Durable-plan defect**
79
+ (falsified contract assumption, AC unchanged) →
80
+ [`spec-drift-guard.md`](spec-drift-guard.md): batch-sweep contract
81
+ assumptions, one folded `/rite-plan repair` + one `/rite-vet` recheck
82
+ inline, resume repair in the same worktrees under the amended contract;
83
+ never emit `Fix:`. **Frozen-lease scope defect** — the amended contract or
84
+ a review requirement needs paths outside a slice's allowlist, or re-slices
85
+ the plan (a lease is immutable once written: its allowlists are the
86
+ disjointness guarantee) → **automatic re-batch, no human gate**:
87
+ `parallel cleanup --force` as the salvage step, record the retained refs in
88
+ the repair-round artifact, `parallel create` a fresh batch from control
89
+ `HEAD` under the corrected decomposition. Prior attempts stay reachable —
90
+ hand each new wright the salvaged branch ref
91
+ (`devrites/parallel/<slug>/<old-batch>/<slice>`) so it builds on what worked
92
+ instead of starting blind. If no corrected decomposition exists, that is
93
+ exhaustion → blocked, preserve, STOP. **Reviewer stall/cancel or missing
94
+ verdict** → re-dispatch the reviewer, not the wright. **Product/policy/
95
+ irreversible** → stops for the human.
96
+ - Dispatch a fresh `devrites-slice-wright` (cwd = the sibling's worktree, same
97
+ allowlist and host rules as step 3 — siblings may repair in parallel) with
98
+ the original contract + verbatim findings + "preserve what works; fix the
99
+ named findings; return a new `transfer_commit`". Never reset the worktree
100
+ to `B` — that destroys the work under repair. The commit must still descend
101
+ from `B` and diff path-exact vs `B`.
102
+ - Each repair return re-runs the full gate chain: inspect, fresh doubt +
103
+ test-analysis, approved proof.
104
+ - Budget: the shared causal-fingerprint cap — three total failed attempts per
105
+ sibling per fingerprint (build + repairs count together); a distinct
106
+ Critical is a new fingerprint. Exhaustion is not abort: record one
107
+ technical blocker (`Status: blocked`; `Next step: none — technical recovery
108
+ exhausted for <fingerprint>; requires new evidence or changed failure
109
+ conditions`), preserve lease/worktrees/branches, STOP — same fingerprint
110
+ stays blocked on reinvoke; new evidence resumes repair in place. Human-
111
+ owned decisions use the drift-guard question and wait.
58
112
 
59
113
  ## Engine verbs
60
114
 
61
115
  ```text
62
- devrites-engine parallel create|record-green|abort|integrate|cleanup|status
63
- devrites-engine parallel lease-write|lease-read|lease-clear
116
+ devrites-engine parallel create --root <repo> --slug <slug> --batch <id> --base <B> --json <file>|-
117
+ devrites-engine parallel record-green --root <repo> --slug <slug> --slice <id> --commit <sha>
118
+ devrites-engine parallel integrate --root <repo> --slug <slug> --apply-to-control
119
+ devrites-engine parallel status --root <repo> --slug <slug>
120
+ devrites-engine parallel lease-write|lease-read|lease-clear --root <repo> --slug <slug>
121
+ # abandoning the batch is human discard only; a frozen-lease re-batch may emit
122
+ # cleanup --force as its salvage step (see Repair rounds):
123
+ # parallel abort --root <repo> --slug <slug>
124
+ # parallel cleanup --root <repo> --slug <slug> --force (salvages, prints retained refs)
64
125
  ```
65
126
 
66
- Go is SSOT. Skill calls the engine never ad-hoc git/bash orchestration.
127
+ `integrate` without `--apply-to-control` stages the squash commit, leaves the
128
+ lease `running` and control at `B`; cleanup still refuses — the commit cannot
129
+ be lost. `record-green` and `integrate` also accept an `integrate-failed`
130
+ lease, so a failed integrate retries after repair. `--apply-to-control`
131
+ refuses when control moved past `B` or holds uncommitted changes on slice
132
+ paths — commit/stash and retry; the batch is untouched. Go is SSOT; never
133
+ ad-hoc git/bash orchestration.
67
134
 
68
135
  ## Runtime isolation
69
136
 
@@ -78,8 +145,8 @@ assign per-slice env (document in the lease or worktree README):
78
145
  | Dev server | one process per worktree; never share a listener |
79
146
 
80
147
  Reusing the control worktree's running server, DB, or compose stack across
81
- siblings causes cross-slice pollution and flaky proof. Abort if isolation cannot
82
- be established.
148
+ siblings causes cross-slice pollution and flaky proof. Force serial if
149
+ isolation cannot be established.
83
150
 
84
151
  ## Host
85
152
 
@@ -83,9 +83,8 @@ executable controller/harness/bundle bytes or a missing writer, read
83
83
  3. **Arm AFK once.** Apply the loop's
84
84
  [one-write AFK contract](reference/loop.md#arm-afk-once): preserve valid
85
85
  existing bytes or create the bounded advisory-only sentinel once; never
86
- rewrite it after Vet. Preserve an existing sentinel byte-for-byte. Touch
87
- `.devrites/CHECKPOINT` so proven slices get local crash-survivable WIP
88
- checkpoints for Ship to collapse. **Completion:** valid read-only AFK and checkpoint sentinels exist.
86
+ rewrite it after Vet. Preserve an existing sentinel byte-for-byte.
87
+ **Completion:** a valid read-only AFK sentinel exists.
89
88
  4. **Drive phases.** Follow [the loop](reference/loop.md): `/rite-spec` →
90
89
  `/rite-clarify` → `/rite-temper` → `/rite-define` → `/rite-vet` →
91
90
  `/rite-build` × pending slices → `/rite-prove` → `/rite-polish` →
@@ -58,9 +58,15 @@ Wright applies anti-slop; root verifies returns and never patches source.
58
58
  ## `--parallel N` (opt-in)
59
59
 
60
60
  Omitted/`1` ≡ serial; `2`–`10` → path-disjoint fan-out when eligible; else hard refuse.
61
- All-green serial integrate; one red/gap aborts. Abort with agent-owned plan
62
- gaps continues via Spec Drift Guard (batch sweep, one folded plan repair + one
63
- vet recheck inline); do not emit a human `Fix`. AFK charges after integrate only. Running lease blocks another
61
+ All-green serial integrate; a red/gap sibling gets a bounded repair round in
62
+ its own worktree never rebuilt from scratch while budget remains.
63
+ Plan-owned gaps still route through Spec Drift Guard (batch sweep, one folded
64
+ plan repair + one vet recheck inline); do not emit a human `Fix`. Exhausted
65
+ repair blocks and preserves everything; `cleanup --force` salvages slice
66
+ branches before removing worktrees — human-gated to abandon a batch,
67
+ orchestrator-emitted only as the salvage step of an automatic frozen-lease
68
+ re-batch.
69
+ AFK charges after integrate only. Running lease blocks another
64
70
  `/rite-build`. Details: `parallel-batch.md`.
65
71
 
66
72
  ## Execute and reply
@@ -1,13 +1,8 @@
1
- # Checkpoint: crash-survivable WIP commits (opt-in)
1
+ # Checkpoint: proven slices land as local WIP commits
2
2
 
3
- `.devrites/` markdown survives compaction, but a slice's source normally stays
4
- uncommitted until `/rite-ship`. A crash during unattended Build can lose that source.
5
- Checkpoint mode commits each proven slice as a local `WIP`, so it survives the session.
6
-
7
- ## When it's on
8
- Opt in with `.devrites/CHECKPOINT`, the mirror of `.devrites/AFK`. When absent,
9
- `/rite-build` makes no checkpoint. Autocomplete sets it for long unattended runs.
10
- **Local-only:** never push a checkpoint or let scratch work trigger CI.
3
+ A slice's source never stays uncommitted after its gates are green: at RECORD
4
+ the orchestrator commits the proven slice as a local `WIP`, so the working
5
+ tree stays clean and the work survives a crash or compaction.
11
6
 
12
7
  ## The checkpoint commit: orchestrator, at RECORD, after gates are green
13
8
  A checkpoint records a **proven** slice only after its gates are green. Stage the exact
@@ -16,7 +11,6 @@ Never stage `touched-files.md`, a directory, glob, unrelated path, or user chang
16
11
  Verify the staged set, then commit locally with a `[devrites-context]` body:
17
12
 
18
13
  ```bash
19
- [ -f .devrites/CHECKPOINT ] || exit 0 # sentinel absent → no-op, silent
20
14
  git commit -m "WIP(<slug>): <slice>" -m "$(cat <<'BODY'
21
15
  [devrites-context]
22
16
  decisions: <one-line delta this slice added to decisions.md>
@@ -26,6 +20,10 @@ BODY
26
20
  )"
27
21
  ```
28
22
 
23
+ When host reconciliation already landed the isolated transfer commit, nothing
24
+ is staged and the step no-ops. **Local-only:** never push a checkpoint or let
25
+ scratch work trigger CI.
26
+
29
27
  ## Restore
30
28
  After a crash, a fresh session may read the last `WIP(<slug>)` body as crash context.
31
29
  Authoritative state remains in `.devrites/`: validate the body against that workspace;
@@ -39,8 +37,8 @@ one atomic feature commit before the Conventional-Commit ladder: see the collaps
39
37
  [git-ship.md](../../rite-ship/reference/git-ship.md). Result: one clean commit, bisect
40
38
  stays green.
41
39
 
42
- ## Autocomplete clean-baseline use
43
- `/rite-autocomplete` may arm checkpoints after verifying a clean or accepted baseline.
44
- They authorize neither red-gate continuation nor Ship. Each wright returns after one
45
- slice; HITL stops, while explicit `.devrites/AFK` lets the controlling Build root chain
46
- another green slice only under its cap and pause rules.
40
+ ## Autocomplete
41
+ Checkpoints are unconditional; `/rite-autocomplete` needs no sentinel arming.
42
+ Each wright returns after one slice; HITL stops, while explicit `.devrites/AFK`
43
+ lets the controlling Build root chain another green slice only under its cap
44
+ and pause rules.
@@ -24,8 +24,8 @@ DISPATCH → hand the slice contract to devrites-slice-wright (fresh context).
24
24
  PROVE → root: required build/browser/E2E, then returned-diff/path review; fail-on-red
25
25
  RECORD → orchestrator: after green verification, update state.md/evidence.md and
26
26
  upsert the authoritative candidate manifest from the actual scoped diff
27
- (CHECKPOINT) → orchestrator: if .devrites/CHECKPOINT is set, commit the proven slice
28
- local-only as WIP(<slug>) with a [devrites-context] body → survives a crash (checkpoint.md)
27
+ (CHECKPOINT) → orchestrator: commit the proven slice local-only as WIP(<slug>)
28
+ with a [devrites-context] body → clean tree, survives a crash (checkpoint.md)
29
29
  NEXT → HITL root reports and stops; AFK root may repeat only under afk-discipline.md
30
30
  ```
31
31
 
@@ -12,8 +12,8 @@ Opt-in only. Default `/rite-build` stays [`one-slice-cycle.md`](one-slice-cycle.
12
12
 
13
13
  AFK caps `N` by remaining budget. Charge **only after successful integrate**
14
14
  (once per integrated green sibling). Abort / integrate-failed → **0**. A
15
- `running` lease blocks another `/rite-build`. Any present lease blocks
16
- `parallel create` until cleanup.
15
+ present lease is resumable: `/rite-build` continues it (repair rounds or the
16
+ blocked verdict); `parallel create` refuses until cleanup.
17
17
 
18
18
  ## Path-disjoint
19
19
 
@@ -22,8 +22,9 @@ duplicates, absolutes, `.devrites/**`. Empty pairwise intersection required.
22
22
 
23
23
  **SSOT:** `devrites-engine check path-disjoint [--root <dir>] [<json-file>|-]`
24
24
  (N≥2 only; pass `--root`). Exit `0` → fan-out; else force serial. Inspect-time
25
- overlap → sibling **gap** abort. **Failing case:** two parallel wrights share a
26
- path and fan-out proceeds without that check.
25
+ overlap → sibling **gap** (a shared path is a contract defect). **Failing
26
+ case:** two parallel wrights share a path and fan-out proceeds without that
27
+ check.
27
28
 
28
29
  ## Control vs workers
29
30
 
@@ -44,26 +45,92 @@ Lease: `batch_id`, `created_at`, `base_sha`, `n`,
44
45
  3. Dispatch ≤10 wrights in parallel (cwd=worktree; allowlist; prove `HEAD==B`).
45
46
  4. Inspect + fail-on-red → `green|red|gap`. Independent-review Critical is `gap`
46
47
  even when targeted tests are green.
47
- 5. Any red/gap → **abort** (no partial integrate). All green serial integrate.
48
- 6. Integrate: `transfer_commit` descends from `B`; `` `<base>..<transfer>` ``
49
- path-exact; apply in plan order. Conflictreset to `B`, `integrate-failed`.
50
- 7. Success: FF control; union `touched-files.md`; update state/evidence; AFK +1
51
- per integrated sibling; optional `check candidate`.
52
- 8. Cleanup: success removes worktrees/branches. Abort keeps them as repair
53
- inputs until the root consumes them: agent-owned plan gaps (AC unchanged)
54
- follow [`spec-drift-guard.md`](spec-drift-guard.md) — batch-sweep all
55
- siblings' contract assumptions, one folded `/rite-plan repair` + one
56
- `/rite-vet` recheck inline, then cleanup and resume Build. Do not emit
57
- `Fix: /rite-plan repair`. Product/policy/irreversible-risk still stops.
48
+ 5. Non-green siblings → **repair round** (below) in the same worktrees; lease
49
+ stays `running` no abort while repair budget remains. A green sibling →
50
+ `parallel record-green`. No partial integrate. All green → integrate.
51
+ 6. Integrate: each `transfer_commit` descends from `B` and diffs path-exact vs
52
+ `B`; squash-apply all in plan order into one `WIP(<slug>):` commit on the
53
+ staging branch (Ship collapses it). Conflict reset to `B`,
54
+ `integrate-failed`; classify under repair rounds (siblings stay in place).
55
+ 7. Success: FF control to the squash commit the batch lands as one local
56
+ commit, never pushed; union `touched-files.md`; update state/evidence;
57
+ AFK +1 per integrated sibling; optional `check candidate`.
58
+ 8. Cleanup runs only after `integrate` marks the lease `complete` — work
59
+ landed in control, so `parallel cleanup` removes worktrees/branches.
60
+ Blocked/human-stopped batches keep lease, worktrees, branches — nothing is
61
+ removed while the batch may resume. `parallel abort` + `cleanup --force`
62
+ abandons the batch — the explicit human discard path; the single
63
+ orchestrator-emitted use is the automatic re-batch under Repair rounds,
64
+ where it acts as the salvage step only (uncommitted allowlisted changes →
65
+ slice-branch commit; branches past `B` kept; a failed salvage keeps the
66
+ worktree) and prints retained refs for the record. `abort` marks the lease
67
+ only — never rewinds control: a moved HEAD is external work, reported not
68
+ reset. Never integrate a rejected transfer commit.
69
+
70
+ ## Repair rounds
71
+
72
+ Rejected work is repaired in place — never discarded and rebuilt from scratch
73
+ while budget remains.
74
+
75
+ - Record each round as `build-parallel-<batch>-repair-<round>.json`: per
76
+ non-green sibling — status, verbatim findings, transfer_commit or null.
77
+ - Classify first: **implementation defect** (review Critical on the diff, red
78
+ wright/proof) → repair wright in the same worktree. **Durable-plan defect**
79
+ (falsified contract assumption, AC unchanged) →
80
+ [`spec-drift-guard.md`](spec-drift-guard.md): batch-sweep contract
81
+ assumptions, one folded `/rite-plan repair` + one `/rite-vet` recheck
82
+ inline, resume repair in the same worktrees under the amended contract;
83
+ never emit `Fix:`. **Frozen-lease scope defect** — the amended contract or
84
+ a review requirement needs paths outside a slice's allowlist, or re-slices
85
+ the plan (a lease is immutable once written: its allowlists are the
86
+ disjointness guarantee) → **automatic re-batch, no human gate**:
87
+ `parallel cleanup --force` as the salvage step, record the retained refs in
88
+ the repair-round artifact, `parallel create` a fresh batch from control
89
+ `HEAD` under the corrected decomposition. Prior attempts stay reachable —
90
+ hand each new wright the salvaged branch ref
91
+ (`devrites/parallel/<slug>/<old-batch>/<slice>`) so it builds on what worked
92
+ instead of starting blind. If no corrected decomposition exists, that is
93
+ exhaustion → blocked, preserve, STOP. **Reviewer stall/cancel or missing
94
+ verdict** → re-dispatch the reviewer, not the wright. **Product/policy/
95
+ irreversible** → stops for the human.
96
+ - Dispatch a fresh `devrites-slice-wright` (cwd = the sibling's worktree, same
97
+ allowlist and host rules as step 3 — siblings may repair in parallel) with
98
+ the original contract + verbatim findings + "preserve what works; fix the
99
+ named findings; return a new `transfer_commit`". Never reset the worktree
100
+ to `B` — that destroys the work under repair. The commit must still descend
101
+ from `B` and diff path-exact vs `B`.
102
+ - Each repair return re-runs the full gate chain: inspect, fresh doubt +
103
+ test-analysis, approved proof.
104
+ - Budget: the shared causal-fingerprint cap — three total failed attempts per
105
+ sibling per fingerprint (build + repairs count together); a distinct
106
+ Critical is a new fingerprint. Exhaustion is not abort: record one
107
+ technical blocker (`Status: blocked`; `Next step: none — technical recovery
108
+ exhausted for <fingerprint>; requires new evidence or changed failure
109
+ conditions`), preserve lease/worktrees/branches, STOP — same fingerprint
110
+ stays blocked on reinvoke; new evidence resumes repair in place. Human-
111
+ owned decisions use the drift-guard question and wait.
58
112
 
59
113
  ## Engine verbs
60
114
 
61
115
  ```text
62
- devrites-engine parallel create|record-green|abort|integrate|cleanup|status
63
- devrites-engine parallel lease-write|lease-read|lease-clear
116
+ devrites-engine parallel create --root <repo> --slug <slug> --batch <id> --base <B> --json <file>|-
117
+ devrites-engine parallel record-green --root <repo> --slug <slug> --slice <id> --commit <sha>
118
+ devrites-engine parallel integrate --root <repo> --slug <slug> --apply-to-control
119
+ devrites-engine parallel status --root <repo> --slug <slug>
120
+ devrites-engine parallel lease-write|lease-read|lease-clear --root <repo> --slug <slug>
121
+ # abandoning the batch is human discard only; a frozen-lease re-batch may emit
122
+ # cleanup --force as its salvage step (see Repair rounds):
123
+ # parallel abort --root <repo> --slug <slug>
124
+ # parallel cleanup --root <repo> --slug <slug> --force (salvages, prints retained refs)
64
125
  ```
65
126
 
66
- Go is SSOT. Skill calls the engine never ad-hoc git/bash orchestration.
127
+ `integrate` without `--apply-to-control` stages the squash commit, leaves the
128
+ lease `running` and control at `B`; cleanup still refuses — the commit cannot
129
+ be lost. `record-green` and `integrate` also accept an `integrate-failed`
130
+ lease, so a failed integrate retries after repair. `--apply-to-control`
131
+ refuses when control moved past `B` or holds uncommitted changes on slice
132
+ paths — commit/stash and retry; the batch is untouched. Go is SSOT; never
133
+ ad-hoc git/bash orchestration.
67
134
 
68
135
  ## Runtime isolation
69
136
 
@@ -78,8 +145,8 @@ assign per-slice env (document in the lease or worktree README):
78
145
  | Dev server | one process per worktree; never share a listener |
79
146
 
80
147
  Reusing the control worktree's running server, DB, or compose stack across
81
- siblings causes cross-slice pollution and flaky proof. Abort if isolation cannot
82
- be established.
148
+ siblings causes cross-slice pollution and flaky proof. Force serial if
149
+ isolation cannot be established.
83
150
 
84
151
  ## Host
85
152
 
@@ -83,9 +83,8 @@ executable controller/harness/bundle bytes or a missing writer, read
83
83
  3. **Arm AFK once.** Apply the loop's
84
84
  [one-write AFK contract](reference/loop.md#arm-afk-once): preserve valid
85
85
  existing bytes or create the bounded advisory-only sentinel once; never
86
- rewrite it after Vet. Preserve an existing sentinel byte-for-byte. Touch
87
- `.devrites/CHECKPOINT` so proven slices get local crash-survivable WIP
88
- checkpoints for Ship to collapse. **Completion:** valid read-only AFK and checkpoint sentinels exist.
86
+ rewrite it after Vet. Preserve an existing sentinel byte-for-byte.
87
+ **Completion:** a valid read-only AFK sentinel exists.
89
88
  4. **Drive phases.** Follow [the loop](reference/loop.md): `$rite-spec` →
90
89
  `$rite-clarify` → `$rite-temper` → `$rite-define` → `$rite-vet` →
91
90
  `$rite-build` × pending slices → `$rite-prove` → `$rite-polish` →
@@ -58,9 +58,15 @@ Wright applies anti-slop; root verifies returns and never patches source.
58
58
  ## `--parallel N` (opt-in)
59
59
 
60
60
  Omitted/`1` ≡ serial; `2`–`10` → path-disjoint fan-out when eligible; else hard refuse.
61
- All-green serial integrate; one red/gap aborts. Abort with agent-owned plan
62
- gaps continues via Spec Drift Guard (batch sweep, one folded plan repair + one
63
- vet recheck inline); do not emit a human `Fix`. AFK charges after integrate only. Running lease blocks another
61
+ All-green serial integrate; a red/gap sibling gets a bounded repair round in
62
+ its own worktree never rebuilt from scratch while budget remains.
63
+ Plan-owned gaps still route through Spec Drift Guard (batch sweep, one folded
64
+ plan repair + one vet recheck inline); do not emit a human `Fix`. Exhausted
65
+ repair blocks and preserves everything; `cleanup --force` salvages slice
66
+ branches before removing worktrees — human-gated to abandon a batch,
67
+ orchestrator-emitted only as the salvage step of an automatic frozen-lease
68
+ re-batch.
69
+ AFK charges after integrate only. Running lease blocks another
64
70
  `$rite-build`. Details: `parallel-batch.md`.
65
71
 
66
72
  ## Execute and reply
@@ -1,13 +1,8 @@
1
- # Checkpoint: crash-survivable WIP commits (opt-in)
1
+ # Checkpoint: proven slices land as local WIP commits
2
2
 
3
- `.devrites/` markdown survives compaction, but a slice's source normally stays
4
- uncommitted until `$rite-ship`. A crash during unattended Build can lose that source.
5
- Checkpoint mode commits each proven slice as a local `WIP`, so it survives the session.
6
-
7
- ## When it's on
8
- Opt in with `.devrites/CHECKPOINT`, the mirror of `.devrites/AFK`. When absent,
9
- `$rite-build` makes no checkpoint. Autocomplete sets it for long unattended runs.
10
- **Local-only:** never push a checkpoint or let scratch work trigger CI.
3
+ A slice's source never stays uncommitted after its gates are green: at RECORD
4
+ the orchestrator commits the proven slice as a local `WIP`, so the working
5
+ tree stays clean and the work survives a crash or compaction.
11
6
 
12
7
  ## The checkpoint commit: orchestrator, at RECORD, after gates are green
13
8
  A checkpoint records a **proven** slice only after its gates are green. Stage the exact
@@ -16,7 +11,6 @@ Never stage `touched-files.md`, a directory, glob, unrelated path, or user chang
16
11
  Verify the staged set, then commit locally with a `[devrites-context]` body:
17
12
 
18
13
  ```bash
19
- [ -f .devrites/CHECKPOINT ] || exit 0 # sentinel absent → no-op, silent
20
14
  git commit -m "WIP(<slug>): <slice>" -m "$(cat <<'BODY'
21
15
  [devrites-context]
22
16
  decisions: <one-line delta this slice added to decisions.md>
@@ -26,6 +20,10 @@ BODY
26
20
  )"
27
21
  ```
28
22
 
23
+ When host reconciliation already landed the isolated transfer commit, nothing
24
+ is staged and the step no-ops. **Local-only:** never push a checkpoint or let
25
+ scratch work trigger CI.
26
+
29
27
  ## Restore
30
28
  After a crash, a fresh session may read the last `WIP(<slug>)` body as crash context.
31
29
  Authoritative state remains in `.devrites/`: validate the body against that workspace;
@@ -39,8 +37,8 @@ one atomic feature commit before the Conventional-Commit ladder: see the collaps
39
37
  [git-ship.md](../../rite-ship/reference/git-ship.md). Result: one clean commit, bisect
40
38
  stays green.
41
39
 
42
- ## Autocomplete clean-baseline use
43
- `$rite-autocomplete` may arm checkpoints after verifying a clean or accepted baseline.
44
- They authorize neither red-gate continuation nor Ship. Each wright returns after one
45
- slice; HITL stops, while explicit `.devrites/AFK` lets the controlling Build root chain
46
- another green slice only under its cap and pause rules.
40
+ ## Autocomplete
41
+ Checkpoints are unconditional; `$rite-autocomplete` needs no sentinel arming.
42
+ Each wright returns after one slice; HITL stops, while explicit `.devrites/AFK`
43
+ lets the controlling Build root chain another green slice only under its cap
44
+ and pause rules.
@@ -24,8 +24,8 @@ DISPATCH → hand the slice contract to devrites-slice-wright (fresh context).
24
24
  PROVE → root: required build/browser/E2E, then returned-diff/path review; fail-on-red
25
25
  RECORD → orchestrator: after green verification, update state.md/evidence.md and
26
26
  upsert the authoritative candidate manifest from the actual scoped diff
27
- (CHECKPOINT) → orchestrator: if .devrites/CHECKPOINT is set, commit the proven slice
28
- local-only as WIP(<slug>) with a [devrites-context] body → survives a crash (checkpoint.md)
27
+ (CHECKPOINT) → orchestrator: commit the proven slice local-only as WIP(<slug>)
28
+ with a [devrites-context] body → clean tree, survives a crash (checkpoint.md)
29
29
  NEXT → HITL root reports and stops; AFK root may repeat only under afk-discipline.md
30
30
  ```
31
31