devrites 7.3.4 → 7.3.6

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 (75) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +1 -1
  3. package/docs/adr/0039-autocomplete-structural-admission.md +87 -0
  4. package/docs/adr/0040-early-preparation-admission.md +76 -0
  5. package/docs/adr/README.md +2 -0
  6. package/docs/cli.md +103 -5
  7. package/docs/engine/commands.md +88 -1
  8. package/engine/internal/lib/claims.go +65 -8
  9. package/engine/internal/lib/context.go +50 -2
  10. package/engine/internal/lib/continuation.go +8 -1
  11. package/engine/internal/lib/dispatch.go +147 -46
  12. package/engine/internal/lib/frontier.go +139 -59
  13. package/engine/internal/lib/frontier_controller.go +667 -0
  14. package/engine/internal/lib/frontier_preparation.go +210 -0
  15. package/engine/internal/lib/frontier_roadmap.go +168 -0
  16. package/engine/internal/lib/next.go +14 -2
  17. package/engine/internal/lib/triggers.go +9 -0
  18. package/engine/internal/parallel/repository.go +10 -0
  19. package/pack/.claude/skills/devrites-lib/SKILL.md +2 -0
  20. package/pack/.claude/skills/devrites-lib/reference/parallel-workspaces.md +108 -115
  21. package/pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  22. package/pack/.claude/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  23. package/pack/.claude/skills/rite-autocomplete/SKILL.md +35 -38
  24. package/pack/.claude/skills/rite-autocomplete/reference/loop.md +66 -59
  25. package/pack/.claude/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  26. package/pack/.claude/skills/rite-build/reference/parallel-batch.md +17 -15
  27. package/pack/generated/claude/skills/devrites-lib/SKILL.md +2 -0
  28. package/pack/generated/claude/skills/devrites-lib/reference/parallel-workspaces.md +108 -115
  29. package/pack/generated/claude/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  30. package/pack/generated/claude/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  31. package/pack/generated/claude/skills/rite-autocomplete/SKILL.md +35 -38
  32. package/pack/generated/claude/skills/rite-autocomplete/reference/loop.md +66 -59
  33. package/pack/generated/claude/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  34. package/pack/generated/claude/skills/rite-build/reference/parallel-batch.md +17 -15
  35. package/pack/generated/codex/skills/devrites-lib/SKILL.md +2 -0
  36. package/pack/generated/codex/skills/devrites-lib/reference/parallel-workspaces.md +108 -115
  37. package/pack/generated/codex/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  38. package/pack/generated/codex/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  39. package/pack/generated/codex/skills/rite-autocomplete/SKILL.md +35 -38
  40. package/pack/generated/codex/skills/rite-autocomplete/reference/loop.md +66 -59
  41. package/pack/generated/codex/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  42. package/pack/generated/codex/skills/rite-build/reference/parallel-batch.md +17 -15
  43. package/pack/generated/devin/skills/devrites-lib/SKILL.md +2 -0
  44. package/pack/generated/devin/skills/devrites-lib/reference/parallel-workspaces.md +108 -115
  45. package/pack/generated/devin/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  46. package/pack/generated/devin/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  47. package/pack/generated/devin/skills/rite-autocomplete/SKILL.md +35 -38
  48. package/pack/generated/devin/skills/rite-autocomplete/reference/loop.md +66 -59
  49. package/pack/generated/devin/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  50. package/pack/generated/devin/skills/rite-build/reference/parallel-batch.md +17 -15
  51. package/pack/generated/dsh/skills/devrites-lib/SKILL.md +2 -0
  52. package/pack/generated/dsh/skills/devrites-lib/reference/parallel-workspaces.md +108 -115
  53. package/pack/generated/dsh/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  54. package/pack/generated/dsh/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  55. package/pack/generated/dsh/skills/rite-autocomplete/SKILL.md +35 -38
  56. package/pack/generated/dsh/skills/rite-autocomplete/reference/loop.md +66 -59
  57. package/pack/generated/dsh/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  58. package/pack/generated/dsh/skills/rite-build/reference/parallel-batch.md +17 -15
  59. package/pack/generated/omp/skills/devrites-lib/SKILL.md +2 -0
  60. package/pack/generated/omp/skills/devrites-lib/reference/parallel-workspaces.md +108 -115
  61. package/pack/generated/omp/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  62. package/pack/generated/omp/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  63. package/pack/generated/omp/skills/rite-autocomplete/SKILL.md +35 -38
  64. package/pack/generated/omp/skills/rite-autocomplete/reference/loop.md +66 -59
  65. package/pack/generated/omp/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  66. package/pack/generated/omp/skills/rite-build/reference/parallel-batch.md +17 -15
  67. package/pack/generated/pi/skills/devrites-lib/SKILL.md +2 -0
  68. package/pack/generated/pi/skills/devrites-lib/reference/parallel-workspaces.md +108 -115
  69. package/pack/generated/pi/skills/devrites-lib/reference/standards/afk-hitl.md +18 -17
  70. package/pack/generated/pi/skills/devrites-lib/reference/workspace-artifact-schema.md +41 -38
  71. package/pack/generated/pi/skills/rite-autocomplete/SKILL.md +35 -38
  72. package/pack/generated/pi/skills/rite-autocomplete/reference/loop.md +66 -59
  73. package/pack/generated/pi/skills/rite-autocomplete/reference/stop-conditions.md +28 -28
  74. package/pack/generated/pi/skills/rite-build/reference/parallel-batch.md +17 -15
  75. package/package.json +1 -1
@@ -39,6 +39,8 @@ lifecycle state from chat or optional `README.md`.
39
39
  completion states. The host renders the response normally.
40
40
  - [`reference/parallel-workspaces.md`](reference/parallel-workspaces.md): explicit
41
41
  phase targets, one isolated global controller, and source-owned proof.
42
+ - [Autocomplete loop](../rite-autocomplete/reference/loop.md#early-preparation-admission):
43
+ controller-only early preparation, bounded successor routing and normalization research.
42
44
  - [`reference/visual-playbooks/index.md`](reference/visual-playbooks/index.md): progressive
43
45
  visual HTML playbook router (load matching ids only; dual-read outline).
44
46
 
@@ -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,79 @@ 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
+ At controller cap>1, resolve sequence authority and start actual immediate-
105
+ successor preparation before ordinary local Temper/Define/Plan/Vet context or
106
+ dispatch open, and retain the full Build gate before claims/rounds/history.
107
+ Follow [early preparation](../../rite-autocomplete/reference/loop.md#early-preparation-admission)
108
+ for native launch/start, internal markers and bounded preparatory-only routing.
109
+ Missing targets need native Spec → Clarify → Temper → Define/Plan → affected
110
+ Vet; existing targets need current completed/readiness state, registered pending
111
+ native preparation, or an existing human/dependency hold. Completed live/
112
+ archived successors need no reopening; valid finite tails discharge the
113
+ obligation. Placeholders, reports and unopened waves prove nothing.
114
+ Opt-out, zero opening budget or source human/question holds prevent new
115
+ openings, not existing child preparation or independent work.
116
+ If preparation cannot start, retain `frontier-blocked: <successor> — <constraint>`
117
+ in source `evidence.md`. `frontier-blocked: sequence — <constraint>` may defer
118
+ unresolved historical normalization for valid independent local work. Each row
119
+ names one concrete native-reviewed constraint; keep it visible and revisit on
120
+ change. It discharges only that scheduling obligation, not readiness, malformed
121
+ canonical/AFK data, paths, claims, isolation, proof or human gates. It cannot
122
+ waive already-ready foreign picks or certify preparation/normalization.
123
+ 2. Reconcile explicit/AFK capacity via `parallel add --root <repo> --slug
124
+ <controller> --cap N --json -`, stdin `[]`. Below occupied count, freeze every
125
+ new launch, even reserved waves; reconcile/drain and retry without cancelling.
126
+ Recover recorded landing intent; unrelated HEAD/ref movement
127
+ stays blocked. Rerun frontier after changes and execute its exact authorized
128
+ `frontier-select-command`. Local select notices do not broaden picks. Existing
129
+ global slots and paths seed selection; reserve the mixed cohort in create/add
130
+ before separate source-local wave opens. Reservations assemble width, never
131
+ prove actor checkout/start. Ready foreign picks cannot disappear behind local
132
+ `serial:` records. A foreign deferral is exactly
133
+ `serial: child/SLICE-001 — <reason>` in source evidence; bare `SLICE-001` is local.
134
+ Substantive-reason rules apply; native workflow judges the constraint.
135
+ Re-evaluate owning serial rows when constraints change; engine checks exact
136
+ scope, not the truth of a host/resource claim.
137
+ Discharged deferrals are not repeatedly actionable. Foreign work/preparation
138
+ and authority normalization precede local Build; local-only reconciliation,
139
+ repair and picks retain their owning phase, not recursive Autocomplete.
140
+ Zero picks with live writers means planning/wait, not premature Prove.
141
+ 3. Apply SOURCE Build readiness/preconditions, exact paths and runtime isolation.
142
+ Early foreign Build always uses isolated workers. On a capable host at cap>1,
143
+ isolate even the first local writer for later refill; persist `--cap N`.
144
+ Add one pick to a retained lease; reopen a complete lease only at unchanged
145
+ control tip, or create from current control after cleanup. Unsupported
146
+ isolation uses qualified serial deferral, truthful local-owner dispatch and
147
+ ordinary ordered handoff, never early same-tree foreign/concurrent writers.
148
+ New dispatch accounts retain opaque `controller_batch` and immutable per-slice
149
+ normalized `admitted_paths`. Retain only each pending writer's lane; returned/
150
+ integrated siblings may release slots for rolling refill. Missing snapshots or
151
+ changed lease paths require actor reconciliation, never backfill from new tasks.
152
+ Exact claim identity/session still matters; release/expiry does not stop an actor.
153
+ Same-session claims allocate space, not extra write authority. None of these
154
+ records proves actual cwd/profile: verify through the native host.
155
+ 4. Start every selected native writer before waiting; continue independent native
156
+ planning/review while they run. Protected validation defers unsafe landings,
157
+ not independent preparation. Outside that window, land individually green
158
+ siblings through Build review/proof and `parallel integrate --slice <key>`;
159
+ refill globally. Red/integrate-failed siblings keep slots/paths for repair.
160
+ Durable integration alone satisfies producer edges. After worker-bound
161
+ accounts and source bookkeeping settle, `parallel prune --root <repo> --slug
162
+ <controller>` removes only verified clean integrated checkouts, retaining
163
+ transfer refs/lease identities. Dirty/ignored data keeps its recovery path.
171
164
 
172
165
  ## Identity, dispatch and proof
173
166
 
@@ -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
 
@@ -86,48 +86,45 @@ With `--lookahead` (trigger `lookahead`), follow
86
86
  [`lookahead.md`](reference/lookahead.md) instead of the steps below: plan the
87
87
  next sequence continuation through Vet in a second session, then stop.
88
88
 
89
- 1. **Orient and parse.** Resolve source per [phase target binding](../devrites-lib/reference/parallel-workspaces.md#phase-target-binding); when a workspace exists,
90
- require its `state.md` and read its cursor; a fresh idea starts empty at step 2.
91
- After normalizing arguments below, run `devrites-engine frontier <source>`
92
- before phase-local cold recovery; execute its actions under the shared
93
- [global frontier pass](../devrites-lib/reference/parallel-workspaces.md#continuous-global-frontier).
94
- Before honoring `blocked` with terminal `next_action`,
95
- reconcile retained consumptive evidence and fingerprint attempts from
96
- `drift.md`/`evidence.md`; a retained fingerprint below its cap resumes offline
97
- recovery, and this new invocation reopens each parked fingerprint.
89
+ 1. **Orient and parse.** Resolve source per [phase target binding](../devrites-lib/reference/parallel-workspaces.md#phase-target-binding).
90
+ Read its existing cursor; a fresh idea starts empty at step 2. Normalize this
91
+ invocation to idea, `ship_preflight: yes|no`, `max_slices: unlimited`,
92
+ `parallel: N|default`, `profile: standard|full`, `cross_model: yes|no`.
93
+ Apply the loop's [AFK contract](reference/loop.md#arm-afk-once) to an existing
94
+ sentinel: upsert `mode: autocomplete`, plus capacity only for explicit
95
+ `--parallel N`. Mode identifies this controller, never grants authority.
96
+ Run `devrites-engine frontier <source>` before local recovery; execute the
97
+ [global pass](../devrites-lib/reference/parallel-workspaces.md#continuous-global-frontier).
98
+ Reconcile blocked/terminal cursors against retained action evidence and exact
99
+ fingerprint attempts; resume offline recovery below its cap. This explicit
100
+ invocation reopens parked fingerprints. Reconstruct missing return cursors
101
+ only from the current phase and approved `test-plan.md`/evidence action.
98
102
  <!-- 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"} -->
99
- Reconstruct a missing return cursor only from
100
- the current phase and exact approved action in `test-plan.md`/evidence, never
101
- from chat. After compaction or a resumed session, always run `devrites-engine
102
- handoff <source> --resume` first for that selected source and open only the
103
- `read_next` artifacts it names, per [`context-hygiene.md`](../devrites-lib/reference/standards/context-hygiene.md) § Compaction fallback.
104
- Normalize current arguments to idea, `ship_preflight: yes|no`,
105
- `max_slices: unlimited`, `parallel: N|default`, `profile: standard|full`,
106
- and `cross_model: yes|no`.
107
- **Completion:** arguments and source authority are unambiguous; local cursor and pending handles remain intact.
103
+ After compaction/resume, run `devrites-engine handoff <source> --resume`
104
+ and open its `read_next` artifacts per [context hygiene](../devrites-lib/reference/standards/context-hygiene.md).
105
+ **Completion:** arguments/source are unambiguous; local cursor and handles survive.
108
106
  2. **Specify and clarify.** Run `devrites-interview`, `/rite-spec`, and
109
107
  `/rite-clarify` as one window. `open` material coverage never arms
110
108
  AFK. **Completion:** `Decision coverage: CLEAR` is durable.
111
- 3. **Arm AFK once.** Apply the loop's
112
- [one-write AFK contract](reference/loop.md#arm-afk-once): preserve valid
113
- existing bytes or create the sentinel once (`allow_gates: [advisory, validating]`); never
114
- rewrite it after Vet except to write or replace only `max_parallel: N` when
115
- this invocation contains `--parallel N`. Preserve an existing sentinel
116
- byte-for-byte otherwise. **Failing case:** leftover `max_parallel: 1` keeps
117
- the run serial after `--parallel 5`.
118
- **Completion:** a valid read-only AFK sentinel exists.
119
- 4. **Drive phases.** Follow [the loop](reference/loop.md): `/rite-spec` →
120
- `/rite-clarify` → `/rite-temper` → `/rite-define` → `/rite-vet` →
121
- `/rite-build` batch loop → `/rite-prove` → `/rite-polish` →
122
- `/rite-review` → `/rite-seal`. Read and execute each skill; durable files, not
123
- chat, carry state. Apply the mutable post-vet budget before first Build.
124
- Run `devrites-engine frontier <source>` at phase entry, before recovery,
125
- on returns and before native waits; execute the shared
126
- [global frontier pass](../devrites-lib/reference/parallel-workspaces.md#continuous-global-frontier),
127
- not merely its report. Autocomplete retains repository scheduling and local
128
- cursors. Apply its protected validation window and pass resolved `--parallel N`
129
- to Build under the same global cap and admission/isolation gates.
130
- **Completion:** loop reaches Seal GO or persists a valid stop before any later phase.
109
+ 3. **Arm AFK once.** Apply the [one-write AFK contract](reference/loop.md#arm-afk-once):
110
+ create only after clarity; explicit controller entry upserts
111
+ `mode: autocomplete` and, only with `--parallel N`, `max_parallel: N`.
112
+ Preserve all other fields; reject malformed/duplicate mode rather than
113
+ silently becoming standalone AFK. **Completion:** valid controller identity
114
+ and capacity are durable; no gate or Git authority changed.
115
+ **Failing case:** leftover `max_parallel: 1` after explicit `--parallel 5`.
116
+ 4. **Drive phases.** Execute [the loop](reference/loop.md): Spec → Clarify →
117
+ Temper → Define → Vet → Build → Prove → Polish → Review → Seal. Durable files
118
+ carry state. Apply the mutable post-vet budget before Build. Consume fresh scheduling
119
+ emitted by recorded `dispatch return`; rerun frontier after further changes
120
+ and before waits. Before ordinary local Temper/Define/Plan/Vet context/dispatch,
121
+ resolve sequence authority and start actual immediate-successor preparation
122
+ under [early admission](reference/loop.md#early-preparation-admission),
123
+ or retain the global pass's concrete deferral; keep the full Build gate.
124
+ Derive initial preparatory-only routing before any marked wave; do not recurse
125
+ through the roadmap. Preserve local cursors, protected validation windows and
126
+ every admission/isolation gate; pass Build the resolved global cap.
127
+ **Completion:** Seal GO or a durable valid stop precedes later phases.
131
128
  5. **Apply stops.** At every gate use
132
129
  [stop-conditions.md](reference/stop-conditions.md). A `blocked` label alone is not a stop condition:
133
130
  route agent-owned red results through bounded recovery.