devrites 7.3.4 → 7.3.5

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 (64) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +1 -1
  3. package/docs/adr/0039-autocomplete-structural-admission.md +87 -0
  4. package/docs/adr/README.md +1 -0
  5. package/docs/cli.md +103 -5
  6. package/docs/engine/commands.md +46 -1
  7. package/engine/internal/lib/claims.go +65 -8
  8. package/engine/internal/lib/continuation.go +6 -1
  9. package/engine/internal/lib/dispatch.go +78 -32
  10. package/engine/internal/lib/frontier.go +103 -47
  11. package/engine/internal/lib/frontier_controller.go +652 -0
  12. package/engine/internal/lib/frontier_roadmap.go +168 -0
  13. package/engine/internal/lib/next.go +9 -0
  14. package/engine/internal/parallel/repository.go +10 -0
  15. package/pack/.claude/skills/devrites-lib/reference/parallel-workspaces.md +106 -115
  16. package/pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  17. package/pack/.claude/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  18. package/pack/.claude/skills/rite-autocomplete/SKILL.md +33 -38
  19. package/pack/.claude/skills/rite-autocomplete/reference/loop.md +46 -52
  20. package/pack/.claude/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  21. package/pack/.claude/skills/rite-build/reference/parallel-batch.md +17 -15
  22. package/pack/generated/claude/skills/devrites-lib/reference/parallel-workspaces.md +106 -115
  23. package/pack/generated/claude/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  24. package/pack/generated/claude/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  25. package/pack/generated/claude/skills/rite-autocomplete/SKILL.md +33 -38
  26. package/pack/generated/claude/skills/rite-autocomplete/reference/loop.md +46 -52
  27. package/pack/generated/claude/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  28. package/pack/generated/claude/skills/rite-build/reference/parallel-batch.md +17 -15
  29. package/pack/generated/codex/skills/devrites-lib/reference/parallel-workspaces.md +106 -115
  30. package/pack/generated/codex/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  31. package/pack/generated/codex/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  32. package/pack/generated/codex/skills/rite-autocomplete/SKILL.md +33 -38
  33. package/pack/generated/codex/skills/rite-autocomplete/reference/loop.md +46 -52
  34. package/pack/generated/codex/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  35. package/pack/generated/codex/skills/rite-build/reference/parallel-batch.md +17 -15
  36. package/pack/generated/devin/skills/devrites-lib/reference/parallel-workspaces.md +106 -115
  37. package/pack/generated/devin/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  38. package/pack/generated/devin/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  39. package/pack/generated/devin/skills/rite-autocomplete/SKILL.md +33 -38
  40. package/pack/generated/devin/skills/rite-autocomplete/reference/loop.md +46 -52
  41. package/pack/generated/devin/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  42. package/pack/generated/devin/skills/rite-build/reference/parallel-batch.md +17 -15
  43. package/pack/generated/dsh/skills/devrites-lib/reference/parallel-workspaces.md +106 -115
  44. package/pack/generated/dsh/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  45. package/pack/generated/dsh/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  46. package/pack/generated/dsh/skills/rite-autocomplete/SKILL.md +33 -38
  47. package/pack/generated/dsh/skills/rite-autocomplete/reference/loop.md +46 -52
  48. package/pack/generated/dsh/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  49. package/pack/generated/dsh/skills/rite-build/reference/parallel-batch.md +17 -15
  50. package/pack/generated/omp/skills/devrites-lib/reference/parallel-workspaces.md +106 -115
  51. package/pack/generated/omp/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  52. package/pack/generated/omp/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  53. package/pack/generated/omp/skills/rite-autocomplete/SKILL.md +33 -38
  54. package/pack/generated/omp/skills/rite-autocomplete/reference/loop.md +46 -52
  55. package/pack/generated/omp/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  56. package/pack/generated/omp/skills/rite-build/reference/parallel-batch.md +17 -15
  57. package/pack/generated/pi/skills/devrites-lib/reference/parallel-workspaces.md +106 -115
  58. package/pack/generated/pi/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  59. package/pack/generated/pi/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  60. package/pack/generated/pi/skills/rite-autocomplete/SKILL.md +33 -38
  61. package/pack/generated/pi/skills/rite-autocomplete/reference/loop.md +46 -52
  62. package/pack/generated/pi/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  63. package/pack/generated/pi/skills/rite-build/reference/parallel-batch.md +17 -15
  64. package/package.json +1 -1
@@ -12,65 +12,45 @@ candidate bindings and proof belong to that source. A missing source artifact
12
12
  routes its prerequisite; it never falls back to another workspace's artifacts.
13
13
  An explicit valid workspace does not require ACTIVE to name it or to exist.
14
14
 
15
- Carry that source through Spec → Clarify → Temper → Define/Plan → Vet and later
16
- Build/Converge/Prove/Polish/Review/Seal/Ship entrypoints. Use existing slug arguments
17
- where supported, including `context <source>` and `handoff <source> --resume`.
18
- For qid-only `state resolve` (including `--drop`/`--batch`), keep its existing argv
19
- and bind the call with `DEVRITES_ROOT=<absolute-control>/.devrites` and
20
- `DEVRITES_WORKSPACE=<absolute-control>/.devrites/work/<source>`. The override is a
21
- workspace path, not a slug. Apply this environment only to that invocation;
22
- neither a fabricated resolver slug argument nor process-global environment
23
- mutation is routing. Use the same source binding for nested recommended answers.
24
-
25
- Preparing or running an admitted future source preserves the ordered owner's
26
- ACTIVE and retained writer/controller. Ordinary standalone Spec still sets ACTIVE;
27
- explicit `--lookahead` still stops at planning/Vet and never becomes a Build root.
15
+ Carry SOURCE through every phase, nested resolution and cold handoff. Use existing
16
+ slug arguments (`context <source>`, `handoff <source> --resume`). Qid-only
17
+ `state resolve` retains its argv: bind only that invocation's `DEVRITES_ROOT` and
18
+ `DEVRITES_WORKSPACE` as above, never a fabricated resolver slug or process-global
19
+ change. Early future work preserves ACTIVE and the retained controller.
20
+ Standalone Spec still sets ACTIVE; `--lookahead` remains planning/Vet-only.
28
21
  Target binding changes neither phase approval nor Ship authority.
29
22
 
30
23
  ## Authority and admission
31
24
 
32
- Resolve one controlling root and ordered lifecycle owner. `.devrites/ACTIVE` stays
33
- on that owner until normal sequence handoff; scheduling a future slice does not
34
- advance ACTIVE or create a second Build root. One repository-global lease owns
35
- control-tip mutations. Resume its controller, source identities and retained
36
- handles before admitting more work; status queried via ACTIVE/source reports the
37
- actual retained controller even after ordered handoff. Another retained
38
- controller is not bypassable; no extra cursor pointer is needed.
39
-
40
- The existing `--parallel N` is one global active-writer cap, not a target guarantee:
41
- explicit invocation value, else AFK `max_parallel`, else retained lease capacity
42
- on resume, else 10. Explicit 1 means one writer, not one writer per workspace.
43
- Review queues obey host capacity and existing reviewer caps separately; neither
44
- capacity nor a Reslice cap waiver waives required named-role fanout or proof gates.
45
-
46
- Use the engine frontier below for recorded source-related sequence membership.
47
- Honor `continue_sequence: false`, opening budget and human bounded requests.
48
- Charge each opening once; reuse prepared children and their cursor.
49
- Unrelated directories or user-mentioned slugs are not automatic enrollment.
50
- Respect workspace claims: a live lookahead owner retains its artifacts until
51
- release/terminal reconciliation. Root alone writes workspace artifacts; leaves
52
- never write `.devrites/**`.
53
-
54
- For each future slice, native Plan/Vet must have CURRENT approved readiness,
55
- a complete bound contract and explicit `Workspace dependencies` under
56
- [canonical slice grammar](workspace-artifact-schema.md#canonical-slice-grammar).
57
- Plan/Vet checks assumptions, consumed interfaces, shared runtime resources and
58
- independent slice proof. `none` is a native declaration, never an inference from
59
- path disjointness, local `Dependencies: none`, planning digests or a green branch.
60
- Only durably BUILT/integrated producer checkpoints satisfy qualified dependencies;
61
- validate each producer reference and graph, including safely archived predecessors.
62
- Cycles, unknown/malformed references and shared unisolated runtime withhold unsafe
63
- candidates. A waiting producer withholds only its consumers, not unrelated work.
64
-
65
- Missing declarations in legacy future plans need narrow Plan repair + affected
66
- Vet before early admission; existing local/standalone plans remain valid. Absent,
67
- incomplete, stale or human-blocked future work is a planning/repair/blocked
68
- opportunity, not a fatal pool failure. Retain every readiness reason: fixing stale
69
- bindings does not waive a coexisting human/access/safety gate. Re-Vet affected
70
- predecessor assumptions, then record current bindings; never auto-refresh a digest.
71
- Read archived predecessors in place through the engine's referenced read-only
72
- readiness lookup. Never copy an archive into live `work/` merely to read/hash it:
73
- that can resurrect stale controller leases and claims.
25
+ Keep ACTIVE on the ordered owner until normal handoff. One repository-global
26
+ lease owns control-tip mutations; recover its controller, source identities and
27
+ handles before more admission, including after handoff. No second Build root.
28
+ `--parallel N` caps active writers globally: explicit N, else AFK `max_parallel`,
29
+ else retained capacity on resume, else 10. One means one writer total. Review
30
+ queues retain host/reviewer caps; capacity or Reslice never waives fanout or proof.
31
+
32
+ Only checked source-related sequence membership qualifies; user-mentioned or
33
+ unrelated directories are not enrollment. Current canonical `roadmap.md` follows
34
+ [the grammar](workspace-artifact-schema.md#what-each-file-owns): one related live/
35
+ archived owner, actual chain root, same-owner unique decision and contiguous
36
+ position table. It supersedes historical tables for scheduling without rewriting
37
+ them. Invalid canonical authority fails closed; absence retains conservative
38
+ legacy resolution. Honor opt-out, opening budgets and human bounds; charge each
39
+ opening once. Lookahead claims retain artifacts through terminal reconciliation.
40
+ Root alone writes workspace artifacts; leaves never write `.devrites/**`.
41
+
42
+ Native Plan/Vet must bind CURRENT readiness, contract, producer assumptions and
43
+ explicit future `Workspace dependencies` per [slice grammar](workspace-artifact-schema.md#canonical-slice-grammar).
44
+ `none` is a native declaration, not an inference from paths, local dependencies,
45
+ digests or green branches. Only durable BUILT/integrated checkpoints satisfy
46
+ validated producer references/graphs, including safely archived predecessors.
47
+ Unknown references, cycles and shared unisolated runtime withhold unsafe slices;
48
+ waiting producers withhold consumers, not independent work. Legacy future plans
49
+ need narrow Plan repair/affected Vet; standalone/local plans retain their rules.
50
+ Per-slice withheld diagnostics do not block other returned eligible IDs;
51
+ workspace-wide readiness failures still withhold the source.
52
+ Preserve coexisting stale-readiness and human/access/safety reasons. Re-Vet changed
53
+ assumptions; never auto-refresh digests or copy archives into live `work/`.
74
54
 
75
55
  ## Recover avoidable serialization
76
56
 
@@ -108,66 +88,77 @@ reslicing unchanged work.
108
88
 
109
89
  ## Continuous global frontier
110
90
 
111
- Autocomplete executes this bounded pass at every phase entry (including cold
112
- Prove/Vet/Review), before phase-local recovery, on each landing/planning/review
113
- return, and immediately before a native wait or final reply. A nested phase
114
- returns scheduling to Autocomplete; its source-local phase/recovery return cursor
115
- and pending native reviewer handles remain intact. This is not a second phase
116
- controller or a persistent frontier artifact.
117
-
118
- 1. Run `devrites-engine frontier <source>` before local recovery or selection.
119
- This read-only report names the related pool, preparation/repair actions and
120
- blockers; it neither authorizes work nor changes the source's local cursor.
121
- For `frontier-prepare` and `frontier-workspace` prepare/repair actions, execute
122
- authorized native Spec → Clarify → Temper → Define/Plan → affected Vet now,
123
- not after owner Seal. Check source gates, claims and planning/Build restrictions.
124
- For `frontier-review-sequence`, read the named approved roadmap/artifacts:
125
- native authority normalization must record the exact continuation through its
126
- owning decision/phase before rerunning frontier. Ambiguous legacy prose,
127
- positive remaining budget and path disjointness never imply permission.
128
- Retain unresolved authority blockers; continue independent authorized work.
129
- Owner-local red/human/access gates withhold that owner and actual consumers;
130
- whole-run safety/access/claim constraints still bind. Record actions/blockers
131
- in existing source artifacts under normal write authority.
132
- Yield children at pending reviewer/phase boundaries; reconcile available
133
- parent returns before another pass. Reporting actions or reading phase skills
134
- is not executing preparation/Vet. Wait only after authorized actions across
135
- the pool have run or reached concrete pending handles/blockers.
136
- 2. Reconcile explicit/AFK capacity changes with
137
- `parallel add --root <repo> --slug <controller> --cap N --json -`, stdin `[]`.
138
- This changes capacity only. Below active count, pause admissions, drain and
139
- retry; never cancel workers to meet a lower cap. Recover a pending recorded
140
- landing before admission; unrelated HEAD/ref movement remains blocked.
141
- Rerun frontier after preparation/repair or capacity changes. Execute returned
142
- `frontier-select-command` with only authorized live `--workspaces`: this exact
143
- candidate list includes the `--slug` controller only when eligible. This is
144
- internal, not a new user flag. `frontier: none` retains source-local routing.
145
- Source-local `parallel select --from-plan` notices neither select globally nor
146
- expand picks. Route notices to their source; running slots/paths seed mixed
147
- selection globally. Zero picks with live writers means continue planning/review
148
- or wait, not Prove for unfinished sources.
149
- 3. Preflight selected slices against their SOURCE workspace with Build's normal
150
- slice/readiness/precondition, exact-path and runtime-isolation gates. Early
151
- foreign Build always uses isolated workers. For cap>1 on a capable host,
152
- isolate even the first lone local writer, so later sources can refill. Persist
153
- `--cap N` on create/add. With a retained lease, add even one pick; a complete
154
- retained lease can reopen only at unchanged control tip. After cleanup,
155
- create a new batch from current control. Never start another controller.
156
- Unsupported isolation uses truthful serial owner dispatch and ordinary ordered
157
- handoff, never early same-tree foreign Build or concurrent same-worktree writers.
158
- 4. Launch every selected native writer before waiting on any; keep scheduling
159
- planning and independent review while they run, including while the owner
160
- awaits Prove/Vet/Review accounts. Apply the protected window below before any
161
- landing: defer control mutations while frozen validation is pending. Outside
162
- that window, land each individually green sibling through Build review/proof
163
- and `parallel integrate --slice <key>`; refill immediately from the whole pool.
164
- A red or `integrate-failed` sibling retains its slot/paths for repair; it does
165
- not halt independent safe landings/refill. A pending landing intent still
166
- requires exact recovery above. Only durable integration satisfies producer edges.
167
- After worker-bound review/proof and source bookkeeping finish, prune only
168
- verified clean integrated checkouts with `parallel prune --root <repo>
169
- --slug <controller>`. Retain transfer refs/lease identities; dirty or ignored
170
- data stays with its reported recovery path and does not justify forced deletion.
91
+ Run this pass at phase entry, before local recovery/waits/reply, and after landing
92
+ or planning changes. A persisted `dispatch return` emits fresh scheduling after
93
+ locks release, even when later claim release fails: retain the nonzero failure
94
+ and claim exclusion. Exact successful claim reconciliation also refreshes;
95
+ rejected/unpersisted returns do not. Ordinary status stays read-only. Keep local
96
+ return cursors and native handles: one controller, not another phase or queue.
97
+
98
+ 1. Read `devrites-engine frontier <source>`, then its selected `frontier-authority`
99
+ paths before preparation. Follow the actual owner/decision, including archives;
100
+ local phase context is not a reason to create a second owner. Execute native actions.
101
+ Normalize unresolved legacy sequence authority through its owning decision/
102
+ phase. Positive budget, ambiguous prose or path disjointness grants nothing.
103
+ A current invalid canonical map is an error, never a fallback to history.
104
+ For controller mode at cap>1, before a new Build-wright wave writes claims,
105
+ rounds or history, start preparation of that source's immediate recorded
106
+ successor. Missing targets need native Spec → Clarify → Temper → Define/Plan →
107
+ affected Vet; existing targets need completed native state, actual pending
108
+ planning/review handles, current Build-ready binding, or a human/dependency hold.
109
+ Completed live/archived successors need no reopening; retained actors still bind.
110
+ A placeholder, prose claim, unopened wave or unrelated reviewer is insufficient.
111
+ Pipeline one successor per admitted source; preparing the whole roadmap first
112
+ is unnecessary. Opt-out, zero opening budget or source human/question holds
113
+ prevent new openings, not already-created child planning or independent work.
114
+ If preparation cannot start, retain `frontier-blocked: <successor> — <constraint>`
115
+ in source `evidence.md`. `frontier-blocked: sequence — <constraint>` may defer
116
+ unresolved historical normalization for valid independent local work. Each row
117
+ names one concrete native-reviewed constraint; keep it visible and revisit on
118
+ change. It discharges only that scheduling obligation, not readiness, malformed
119
+ canonical/AFK data, paths, claims, isolation, proof or human gates. It cannot
120
+ waive already-ready foreign picks or certify preparation/normalization.
121
+ 2. Reconcile explicit/AFK capacity via `parallel add --root <repo> --slug
122
+ <controller> --cap N --json -`, stdin `[]`. Below occupied count, freeze every
123
+ new launch, even reserved waves; reconcile/drain and retry without cancelling.
124
+ Recover recorded landing intent; unrelated HEAD/ref movement
125
+ stays blocked. Rerun frontier after changes and execute its exact authorized
126
+ `frontier-select-command`. Local select notices do not broaden picks. Existing
127
+ global slots and paths seed selection; reserve the mixed cohort in create/add
128
+ before separate source-local wave opens. Reservations assemble width, never
129
+ prove actor checkout/start. Ready foreign picks cannot disappear behind local
130
+ `serial:` records. A foreign deferral is exactly
131
+ `serial: child/SLICE-001 — <reason>` in source evidence; bare `SLICE-001` is local.
132
+ Substantive-reason rules apply; native workflow judges the constraint.
133
+ Re-evaluate owning serial rows when constraints change; engine checks exact
134
+ scope, not the truth of a host/resource claim.
135
+ Discharged deferrals are not repeatedly actionable. Foreign work/preparation
136
+ and authority normalization precede local Build; local-only reconciliation,
137
+ repair and picks retain their owning phase, not recursive Autocomplete.
138
+ Zero picks with live writers means planning/wait, not premature Prove.
139
+ 3. Apply SOURCE Build readiness/preconditions, exact paths and runtime isolation.
140
+ Early foreign Build always uses isolated workers. On a capable host at cap>1,
141
+ isolate even the first local writer for later refill; persist `--cap N`.
142
+ Add one pick to a retained lease; reopen a complete lease only at unchanged
143
+ control tip, or create from current control after cleanup. Unsupported
144
+ isolation uses qualified serial deferral, truthful local-owner dispatch and
145
+ ordinary ordered handoff, never early same-tree foreign/concurrent writers.
146
+ New dispatch accounts retain opaque `controller_batch` and immutable per-slice
147
+ normalized `admitted_paths`. Retain only each pending writer's lane; returned/
148
+ integrated siblings may release slots for rolling refill. Missing snapshots or
149
+ changed lease paths require actor reconciliation, never backfill from new tasks.
150
+ Exact claim identity/session still matters; release/expiry does not stop an actor.
151
+ Same-session claims allocate space, not extra write authority. None of these
152
+ records proves actual cwd/profile: verify through the native host.
153
+ 4. Start every selected native writer before waiting; continue independent native
154
+ planning/review while they run. Protected validation defers unsafe landings,
155
+ not independent preparation. Outside that window, land individually green
156
+ siblings through Build review/proof and `parallel integrate --slice <key>`;
157
+ refill globally. Red/integrate-failed siblings keep slots/paths for repair.
158
+ Durable integration alone satisfies producer edges. After worker-bound
159
+ accounts and source bookkeeping settle, `parallel prune --root <repo> --slug
160
+ <controller>` removes only verified clean integrated checkouts, retaining
161
+ transfer refs/lease identities. Dirty/ignored data keeps its recovery path.
171
162
 
172
163
  ## Identity, dispatch and proof
173
164
 
@@ -51,6 +51,7 @@ time. No `state.md` run-mode field can drift out of sync.
51
51
  Presence = AFK active. The file body is optional YAML:
52
52
 
53
53
  ```yaml
54
+ mode: autocomplete # optional controller identity; absent = standalone AFK
54
55
  max_slices: 10 # whole-workspace writer budget; seeds state.md remaining count
55
56
  max_agents: 32 # native agent dispatches in one host activation
56
57
  max_minutes: 120 # min; /rite-autocomplete: not a ceiling
@@ -61,10 +62,13 @@ notify: 'curl -fsS -m 10 -d "$DEVRITES_QID: $DEVRITES_QUESTION" ntfy.sh/my-topic
61
62
  allow_gates: [advisory, validating] # gate severities AFK auto-handles (auto-picks the recommended option)
62
63
  continue_sequence: true # after Seal GO, open the next recorded continuation
63
64
  max_workspaces: 5 # workspaces one armed sequence may open
64
- max_parallel: 10 # unattended default cap; `--parallel N` on this invocation wins and may rewrite only this field
65
+ max_parallel: 10 # global writer cap; explicit --parallel N wins
65
66
  ```
66
67
 
67
- The file is **read-only config**: never rewritten in place, except `/rite-autocomplete --parallel N` writes or replaces only `max_parallel: N`.
68
+ AFK is read-only after entry. Explicit `/rite-autocomplete` upserts only
69
+ `mode: autocomplete` and, with `--parallel N`, `max_parallel: N`; preserve other
70
+ fields. Missing mode keeps standalone behavior; invalid/duplicate mode fails
71
+ closed. Mode identifies scheduling, never grants phase, safety or Git authority.
68
72
 
69
73
  Outside active `/rite-autocomplete`, the following slice-budget rules apply:
70
74
  `max_slices` seeds root-owned `state.md` cursor `afk_slices_remaining`
@@ -103,10 +107,9 @@ malformed values fail closed; `0` opens nothing.
103
107
  candidate manifest to cover the whole recorded chain — run
104
108
  `devrites-engine state merge-manifest <slug>` before Prove.
105
109
 
106
- - Only continuations recorded in the parent's `decisions.md` sequence
107
- ([slicing.md § Continuation workspaces](../../../rite-plan/reference/slicing.md#continuation-workspaces))
108
- qualify; no next entry or exhausted `max_workspaces` stops with that reason. The review-queue bound applies only outside active
109
- `/rite-autocomplete`.
110
+ - Only checked recorded continuations qualify, under the
111
+ [sequence grammar](../workspace-artifact-schema.md#what-each-file-owns).
112
+ No next entry or opening budget stops new openings, not existing child work.
110
113
  - Milestones are **not** shipped: they stay sealed and unarchived in `.devrites/work/`
111
114
  with `Next step: /rite-ship` preserved. Local `WIP(<slug>):` checkpoints still
112
115
  land ([checkpoint.md](../../../rite-build/reference/checkpoint.md)), so the tree
@@ -118,15 +121,13 @@ candidate manifest to cover the whole recorded chain — run
118
121
  `/rite-autocomplete` recovers agent-owned Seal `NO-GO` per
119
122
  [stop-conditions.md](../../../rite-autocomplete/reference/stop-conditions.md), not a handoff.
120
123
 
121
- `max_parallel` is the unattended default writer cap when this invocation omits
122
- `--parallel N`; explicit N wins and Autocomplete writes/replaces only that field.
123
- Build's explicit flag wins without rewriting the sentinel. Never write
124
- `max_slices` from `--max-slices`. Autocomplete uses one cap across all authorized
125
- sources, including explicit 1, under the shared root-only
126
- [`workspace controller`](../parallel-workspaces.md); standalone Build stays local.
127
- Unattended runs recompute after each landing and planning/review return, not only
128
- after a batch completes. **Failing case:** `/rite-autocomplete --parallel 5`
129
- honors leftover `max_parallel: 1`, or grants five writers per workspace.
124
+ `--parallel N` wins over AFK `max_parallel`, else retained lease capacity on
125
+ resume, else 10. Build's flag never rewrites AFK; explicit controller entry may
126
+ update only mode/capacity. One cap covers all admitted sources, even explicit 1;
127
+ standalone Build stays local. Follow the [global pass](../parallel-workspaces.md#continuous-global-frontier)
128
+ for immediate-successor preparation, narrow `frontier-blocked` deferrals,
129
+ qualified foreign `serial:` handoff and automatic dispatch-return scheduling.
130
+ These are scheduling disclosures, never readiness, isolation, proof or Ship waivers.
130
131
 
131
132
  ## Unattended resource envelope
132
133
 
@@ -157,8 +158,8 @@ applicable remaining limit. Agent/time/token/cost counters are per native activa
157
158
  for a new activation. Slice/recovery state and review queue remain durable/recomputed across wakes.
158
159
  Persist stops/checkpoints before notification.
159
160
 
160
- New sentinels omit `expires_at` and notification/token/cost caps. Post-Vet pending
161
- count may lower standalone slices. Never add missing defaults to existing files.
161
+ Fresh AFK omits expiry and notification/token/cost caps. Standalone post-Vet
162
+ counts may lower slices; preserve existing fields except controller entry above.
162
163
 
163
164
  Delete the file to restore HITL on the next invocation.
164
165
 
@@ -1,10 +1,9 @@
1
1
  # Workspace artifact schema
2
2
 
3
3
  Feature truth: `.devrites/work/<slug>/`, discovered by `state.md`; remnants/archives
4
- are inactive. Spec writes optional `README.md`. Use canonical filenames; both released
5
- cursor forms remain readable, but a cursor with no `schema` row needs
6
- `devrites-engine migrate <slug>` before the engine accepts it. `/rite-upgrade` audits
7
- without path/alias/format migration.
4
+ inactive. Spec's `README.md` is optional. Use canonical filenames. Both released
5
+ cursors read; no `schema` requires `devrites-engine migrate <slug>`.
6
+ `/rite-upgrade`: audit only, no path/alias/format migration.
8
7
 
9
8
  ## Contents
10
9
 
@@ -59,6 +58,7 @@ accept safe legacy basenames. Ordinary phases never rename them.
59
58
  | `visual/<name>.outline.md` | required machine dual-read companion for the sibling HTML; outline wins on conflict; never a candidate path | 200 lines (advisory; not gate-checked) |
60
59
  | `visual/README.md` | optional index of visuals in the workspace | 80 lines (advisory; not gate-checked) |
61
60
  | `decisions.md` | ADR-style `DEC-###` log: status, context, options, decision, consequences, related IDs; optional `Files:`/`Tags:` fields make entries queryable by path or theme; Build's `## Carry-forward constraints` lines (rule, source slice, evidence, `Files:`) | 200 lines |
61
+ | `roadmap.md` | optional sequence authority (below); headerless maps stay legacy | — |
62
62
  | `assumptions.md` | assumptions with confidence, owner, validation status | 160 lines |
63
63
  | `questions.md` | current `q-YYYY-MM-DD-NNN` (or released `Q-###`) open/resolved questions, gate, answer, impact | 180 lines |
64
64
  | `plan.md` | technical approach, slice strategy, canonical shared-contract proof, validation strategy, rollback | 220 lines |
@@ -85,6 +85,17 @@ accept safe legacy basenames. Ordinary phases never rename them.
85
85
  For visual pairs load only matching [playbooks](visual-playbooks/index.md); use
86
86
  the [required outline headings](visual-playbooks/outline-template.md).
87
87
 
88
+ Canonical `roadmap.md`: either header claims explicit authority; require both
89
+ `Sequence root: <actual-anchor-slug>` and `Decision: DEC-NNN`, identifying one
90
+ `## DEC-NNN` in owner-local `decisions.md`. One related live/archive owner, one
91
+ `Position`/`Workspace` table: contiguous from 1, unique valid slugs matching all
92
+ related positions/exact successors; no unenrolled nodes. Valid authority supersedes
93
+ history for scheduling; preserve historical bytes. Headerless maps remain legacy.
94
+ Partial/malformed headers, multiple owners, invalid root/decision/table, symlink
95
+ or unreadable maps fail closed, no fallback. Native normalization records approved
96
+ actual identities, preserves history. Engine identity checks grant no semantic
97
+ approval, independence, Build or Ship readiness.
98
+
88
99
  ## Candidate manifest and bindings
89
100
 
90
101
  `touched-files.md` contains exactly one `## Touched files` heading and exactly
@@ -141,40 +152,32 @@ The worktree digest is deterministic but is not an atomic filesystem snapshot
141
152
  against a malicious concurrent same-size rewrite. Ship's exact Git-index scope,
142
153
  byte, binding, and secret checks own the final freeze immediately before commit.
143
154
 
144
- Only a structural `Budget override: <=N lines; <reason>` line (not a fenced example)
145
- permits excess, up to N lines and N×400 bytes with N at most 2× the line budget; a
146
- reason-only override counts as none. Each line budget also bounds bytes at 400 bytes
147
- per budgeted line (`state.md` 120 lines → 48 KiB); long lines do not evade it. `orient`
148
- reports `artifact_budgets` (lines/bytes/over/override) and `bulk_files` (non-canonical
149
- files over 64 KiB) so a phase can decide what to read before loading; phase writers
150
- check these limits before returning, with no repository-local script assumption.
151
-
152
- `check readiness`, `check seal` and `state append` enforce the material band: any present
153
- budgeted artifact (required or not, `drift.md` included) at or above 1.5× its line or
154
- byte budget with no covering override blocks with the exact measurement and three legal
155
- remedies (relocate history losslessly via `/rite-plan revise`, split via `/rite-plan
156
- course-correct`, or record the bounded override). Past 2× only relocation or split remain.
157
- Overshoot below that band stays advisory and is reported by `orient`. Proof ledgers
158
- (`evidence.md`, `browser-evidence.md`, `touched-files.md`) are always advisory: they
159
- scale with proof volume, and `touched-files.md` keeps its own manifest limits.
160
- Because they are never gate-blocked they are also the only artifacts that can grow
161
- unboundedly — so phases read them by index, not whole-file: the standalone binding
162
- line, a `EVID-###`/section-header index (`grep -n`), then bodies only for entries
163
- naming this candidate's AC/slice IDs. An entry naming no in-scope ID is anomaly
164
- evidence to inspect, not skip. A whole-file read is allowed only when `orient`
165
- reports the artifact within budget; completeness for seal is engine-checked
166
- (literal `AC-###` presence), the reader judges quality.
167
-
168
- Two reasons are not durable fixes: slice or acceptance-criteria count (an over-budget
169
- `tasks.md`/`plan.md`/`traceability.md` from decomposition size is a
170
- [feature-sequence split](../../rite-plan/reference/slicing.md#feature-ceiling-split-an-epic-never-override-the-budget)),
171
- and history in `state.md` (checkpoint narrative moves verbatim to
172
- `history/<file>-<YYYYMMDD>.md`, append-only, never a phase read-next, with a one-line
173
- pointer left behind). A legacy reason-only `Budget override:` line no longer clears a
174
- gate; `/rite-upgrade` routes it to relocation or the split, and new writers never create one for those two reasons.
175
- Apply [[`context-hygiene.md`](standards/context-hygiene.md) dispatch packets](standards/context-hygiene.md#dispatch-packets)
176
- for byte-size checks and lossless retrieval; budget overrides neither rewrite protected
177
- history nor require loading it all.
155
+ Only structural `Budget override: <=N lines; <reason>` outside fences permits N
156
+ lines/N×400 bytes, N ≤ 2× budget. Reason-only overrides count as none. Budgets:
157
+ 400 bytes/line (`state.md`: 120 lines/48 KiB); long lines cannot evade them.
158
+ `orient`: `artifact_budgets` (lines/bytes/over/override), `bulk_files` (non-canonical
159
+ files >64 KiB). Writers check limits before returning; no local script assumed.
160
+
161
+ `check readiness`/`check seal`/`state append` block present budgeted artifacts
162
+ (optional/`drift.md` included) at ≥1.5× lines or bytes without covering override.
163
+ Report exact measurement and remedies: lossless relocation (`/rite-plan revise`),
164
+ split (`/rite-plan course-correct`), bounded override. Past 2×: relocation/split
165
+ only; below 1.5×: advisory in `orient`.
166
+ Proof ledgers (`evidence.md`, `browser-evidence.md`, `touched-files.md`) alone may
167
+ grow unbounded, always advisory; manifest limits still apply. Read standalone
168
+ binding, `EVID-###`/section index (`grep -n`), then candidate AC/slice bodies.
169
+ Inspect no-in-scope-ID entries as anomalies. Whole-file reads require `orient`
170
+ within budget; Seal checks literal `AC-###` completeness, reader judges quality.
171
+
172
+ Slice/AC count and cursor history never justify durable overrides. Decomposition
173
+ overflow (`tasks.md`/`plan.md`/`traceability.md`) requires a
174
+ [feature-sequence split](../../rite-plan/reference/slicing.md#feature-ceiling-split-an-epic-never-override-the-budget).
175
+ Move `state.md` narrative verbatim to append-only `history/<file>-<YYYYMMDD>.md`;
176
+ leave a one-line pointer; history never enters phase read-next. Legacy reason-only
177
+ overrides cannot clear gates: `/rite-upgrade` routes relocation/split; new writers
178
+ never override these reasons. Use
179
+ [dispatch packets](standards/context-hygiene.md#dispatch-packets)
180
+ for byte checks/lossless retrieval. Overrides neither rewrite nor require loading protected history.
178
181
 
179
182
  ## Anchored notes
180
183
 
@@ -85,48 +85,43 @@ With `--lookahead` (trigger `lookahead`), follow
85
85
  [`lookahead.md`](reference/lookahead.md) instead of the steps below: plan the
86
86
  next sequence continuation through Vet in a second session, then stop.
87
87
 
88
- 1. **Orient and parse.** Resolve source per [phase target binding](../devrites-lib/reference/parallel-workspaces.md#phase-target-binding); when a workspace exists,
89
- require its `state.md` and read its cursor; a fresh idea starts empty at step 2.
90
- After normalizing arguments below, run `devrites-engine frontier <source>`
91
- before phase-local cold recovery; execute its actions under the shared
92
- [global frontier pass](../devrites-lib/reference/parallel-workspaces.md#continuous-global-frontier).
93
- Before honoring `blocked` with terminal `next_action`,
94
- reconcile retained consumptive evidence and fingerprint attempts from
95
- `drift.md`/`evidence.md`; a retained fingerprint below its cap resumes offline
96
- recovery, and this new invocation reopens each parked fingerprint.
88
+ 1. **Orient and parse.** Resolve source per [phase target binding](../devrites-lib/reference/parallel-workspaces.md#phase-target-binding).
89
+ Read its existing cursor; a fresh idea starts empty at step 2. Normalize this
90
+ invocation to idea, `ship_preflight: yes|no`, `max_slices: unlimited`,
91
+ `parallel: N|default`, `profile: standard|full`, `cross_model: yes|no`.
92
+ Apply the loop's [AFK contract](reference/loop.md#arm-afk-once) to an existing
93
+ sentinel: upsert `mode: autocomplete`, plus capacity only for explicit
94
+ `--parallel N`. Mode identifies this controller, never grants authority.
95
+ Run `devrites-engine frontier <source>` before local recovery; execute the
96
+ [global pass](../devrites-lib/reference/parallel-workspaces.md#continuous-global-frontier).
97
+ Reconcile blocked/terminal cursors against retained action evidence and exact
98
+ fingerprint attempts; resume offline recovery below its cap. This explicit
99
+ invocation reopens parked fingerprints. Reconstruct missing return cursors
100
+ only from the current phase and approved `test-plan.md`/evidence action.
97
101
  <!-- workflow-artifact-adapter: {"module":"devrites-lib/reference/standards/workflow-artifacts.md","entry":"lifecycle cursor encounters admitted set or resumable journal","action":"invoke classifier; execute returned route internally","return":"saved phase/action; zero intermediate reply"} -->
98
- Reconstruct a missing return cursor only from
99
- the current phase and exact approved action in `test-plan.md`/evidence, never
100
- from chat. After compaction or a resumed session, always run `devrites-engine
101
- handoff <source> --resume` first for that selected source and open only the
102
- `read_next` artifacts it names, per [`context-hygiene.md`](../devrites-lib/reference/standards/context-hygiene.md) § Compaction fallback.
103
- Normalize current arguments to idea, `ship_preflight: yes|no`,
104
- `max_slices: unlimited`, `parallel: N|default`, `profile: standard|full`,
105
- and `cross_model: yes|no`.
106
- **Completion:** arguments and source authority are unambiguous; local cursor and pending handles remain intact.
102
+ After compaction/resume, run `devrites-engine handoff <source> --resume`
103
+ and open its `read_next` artifacts per [context hygiene](../devrites-lib/reference/standards/context-hygiene.md).
104
+ **Completion:** arguments/source are unambiguous; local cursor and handles survive.
107
105
  2. **Specify and clarify.** Run `devrites-interview`, `/rite-spec`, and
108
106
  `/rite-clarify` as one window. `open` material coverage never arms
109
107
  AFK. **Completion:** `Decision coverage: CLEAR` is durable.
110
- 3. **Arm AFK once.** Apply the loop's
111
- [one-write AFK contract](reference/loop.md#arm-afk-once): preserve valid
112
- existing bytes or create the sentinel once (`allow_gates: [advisory, validating]`); never
113
- rewrite it after Vet except to write or replace only `max_parallel: N` when
114
- this invocation contains `--parallel N`. Preserve an existing sentinel
115
- byte-for-byte otherwise. **Failing case:** leftover `max_parallel: 1` keeps
116
- the run serial after `--parallel 5`.
117
- **Completion:** a valid read-only AFK sentinel exists.
118
- 4. **Drive phases.** Follow [the loop](reference/loop.md): `/rite-spec` →
119
- `/rite-clarify` → `/rite-temper` → `/rite-define` → `/rite-vet` →
120
- `/rite-build` batch loop → `/rite-prove` → `/rite-polish` →
121
- `/rite-review` → `/rite-seal`. Read and execute each skill; durable files, not
122
- chat, carry state. Apply the mutable post-vet budget before first Build.
123
- Run `devrites-engine frontier <source>` at phase entry, before recovery,
124
- on returns and before native waits; execute the shared
125
- [global frontier pass](../devrites-lib/reference/parallel-workspaces.md#continuous-global-frontier),
126
- not merely its report. Autocomplete retains repository scheduling and local
127
- cursors. Apply its protected validation window and pass resolved `--parallel N`
128
- to Build under the same global cap and admission/isolation gates.
129
- **Completion:** loop reaches Seal GO or persists a valid stop before any later phase.
108
+ 3. **Arm AFK once.** Apply the [one-write AFK contract](reference/loop.md#arm-afk-once):
109
+ create only after clarity; explicit controller entry upserts
110
+ `mode: autocomplete` and, only with `--parallel N`, `max_parallel: N`.
111
+ Preserve all other fields; reject malformed/duplicate mode rather than
112
+ silently becoming standalone AFK. **Completion:** valid controller identity
113
+ and capacity are durable; no gate or Git authority changed.
114
+ **Failing case:** leftover `max_parallel: 1` after explicit `--parallel 5`.
115
+ 4. **Drive phases.** Execute [the loop](reference/loop.md): Spec → Clarify →
116
+ Temper → Define → Vet → Build → Prove → Polish → Review → Seal. Durable files
117
+ carry state. Apply the mutable post-vet budget before Build. Consume fresh scheduling
118
+ emitted by recorded `dispatch return`; rerun frontier after further changes
119
+ and before waits. Start actual immediate-successor preparation before local
120
+ writer admission, or disclose the narrow deferral in the shared global pass.
121
+ A placeholder or report is not preparation; the entire sequence need not be
122
+ prepared at once. Preserve local cursors and protected validation windows;
123
+ pass Build the resolved global cap and retain every admission/isolation gate.
124
+ **Completion:** Seal GO or a durable valid stop precedes later phases.
130
125
  5. **Apply stops.** At every gate use
131
126
  [stop-conditions.md](reference/stop-conditions.md). A `blocked` label alone is not a stop condition:
132
127
  route agent-owned red results through bounded recovery.