@oscaner-skills/cdd-engine 4.13.0 → 4.15.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.
@@ -48,6 +48,8 @@
48
48
  //
49
49
  // Module-level exports are types / the declared constant data / the class — zero
50
50
  // behavior-carrying bare functions (the plan's zero-bare-function discipline).
51
+ var _a;
52
+ import { CRITERIA, LENS_QUESTIONS } from "../contract/review-criteria.js";
51
53
  import { DISPATCH } from "../face/host.js";
52
54
  import { TerminationPolicy } from "../face/termination.js";
53
55
  /** The nominal fixed-frame cells shared by every shell (byte-identical words — the
@@ -56,6 +58,15 @@ const FRAME_ITEMS = [
56
58
  "**Fixed contract:** everything above `## Round context` is this mode's fixed text — byte-identical per dispatch. `## Round context` is the only dynamic region; resolve every symbol from it — nothing real rides above.",
57
59
  "**Scope lock:** use only this round's inputs in `## Round context`. No full plan reads. No extra features, no tangential refactors, no scope creep.",
58
60
  ];
61
+ /** The dispatch OUTPUT plane's ONE discipline cell (design spec §5.1) — the same
62
+ * bytes in all four shell texts (`IMPLEMENT_SHELL` · `REVIEW_ITEM` · `FIX_SHELL` ·
63
+ * `DOCS_FIX_SHELL`). It is self-sufficient by construction: the base is the round
64
+ * context's `WORKSPACE_DIR`, `<round-id>` is derived from this round's own
65
+ * `OUTPUT_HANDOFF` stem with its `-a<n>` attempt segment stripped (§5.2), `mkdir -p`
66
+ * is written out (the engine creates no directory, §5.4), and the artifact set is
67
+ * named by pointing at the round context — the shell sits ABOVE it, so "above"
68
+ * would point the wrong way. */
69
+ const SCRATCH_DISCIPLINE = "Anything that is not a round artifact — analysis scripts, one-off scans, intermediate JSON/TSV — goes under the round context's `WORKSPACE_DIR` in `scratch/<round-id>/` (create it with `mkdir -p` before writing), never at the workspace root, where `<round-id>` is the stem your `OUTPUT_HANDOFF` path in that same round context carries with its `-a<n>` attempt segment stripped, nothing there is evidence, nothing there is read back, and this round's artifacts are exactly the `OUTPUT_*` paths that round context lists.";
59
70
  /** The shared work-mode tail cell — the evidence gate (implement/fix carry it;
60
71
  * docs-fix carries no evidence file — zero per-mode duplication, §3.7). The
61
72
  * evidence file's concrete name rides the injected schema's preamble (per-family
@@ -107,6 +118,7 @@ const IMPLEMENT_SHELL = [
107
118
  WORK_CAPABILITY,
108
119
  `**implement:** read \`INPUT_WAVE_BRIEF\` (the complete plan mirror — every \`### Task N:\` of the wave + the plan's \`## Constraints\` section, fresh-extracted at dispatch). \`WAVE\` = this round's wave (the task list); implement ALL tasks of the wave, never a subset. \`CONFIRMED_SEAMS\` in the brief → apply as-is; else propose test boundaries in the report, then invoke **\`${DISPATCH.implement}\`**. Write the handoff draft at \`OUTPUT_HANDOFF\` per \`## Handoff schema\` BEFORE the return block: \`status\` (APPROVED once applied, else BLOCKED + the reason in \`notes\`) and \`artifacts\` (the prescribed \`OUTPUT_REPORT\`/\`OUTPUT_EVIDENCE\` paths from the round context — the \`{family}-{key}-\` canonical names, zero free naming).`,
109
120
  EVIDENCE_ITEM,
121
+ SCRATCH_DISCIPLINE,
110
122
  ...LICENSE_ITEMS,
111
123
  ...SCHEMA_SECTION,
112
124
  ];
@@ -114,7 +126,7 @@ const IMPLEMENT_SHELL = [
114
126
  * names where the orchestrator's rulings live and what they outrank; the SIDECAR PATH
115
127
  * itself rides the round context (`INPUT_RULINGS`), never this sentence. Both fix
116
128
  * shells carry the same words: one reading, one meaning. */
117
- const RULINGS_READING = "**Rulings:** read the orchestrator's ruling file named by `INPUT_RULINGS` before touching a finding — each ruling answers one finding id and overrides that finding's own suggestion (`REJECTED` = do not adopt that finding's fix); the carrier itself is read-only, never rewritten.";
129
+ const RULINGS_READING = "**Rulings:** read the orchestrator's ruling file named by `INPUT_RULINGS` before touching a finding — each ruling answers one finding id and overrides that finding's own suggestion (`REJECTED` = do not adopt that finding's fix); the carrier itself is read-only, never rewritten. `INPUT_RULINGS` is a path, or the literal `none` when this round has no ruling sidecar.";
118
130
  /** The fix row's fixed prefix — header + instructions + the shared work tail. */
119
131
  const FIX_TYPED_INSTRUCTIONS = [
120
132
  "**Verify-then-apply:** verify each finding against the codebase's actual state before changing anything — apply a finding only when it is technically sound; a finding that does not hold up stays open with a note (never blind adoption). Apply findings one at a time and test each one before moving on.",
@@ -129,10 +141,11 @@ const FIX_SHELL = [
129
141
  ...FRAME_ITEMS,
130
142
  WORK_CAPABILITY,
131
143
  ...FIX_TYPED_INSTRUCTIONS,
132
- "**fix:** read `INPUT_REVIEWS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_PLAN` on the branch line — the plan document; `INPUT_SPEC` on the branch line — the design spec, a conformance reference, never the judged document). Fix ALL findings (blocker/warn/nit), verifying against `INPUT_REVIEWS` none remain open. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
144
+ "**fix:** read `INPUT_REVIEWS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_PLAN` on the branch line — the plan document; `INPUT_SPEC` on the wave and branch lines — the design spec, a conformance reference, never the judged document; `INPUT_OVERALL` on those two lines — that spec's parent charter, a conformance reference too). Fix ALL findings (blocker/warn/nit), verifying against `INPUT_REVIEWS` none remain open. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
133
145
  '**Dispositions:** every requested finding needs a disposition keyed by its `id` exactly as the requesting carrier prints it (`F1`, `F2`, … — the summary is description only), valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` — a missing or mis-keyed disposition fails the round.',
134
146
  RULINGS_READING,
135
147
  EVIDENCE_ITEM,
148
+ SCRATCH_DISCIPLINE,
136
149
  ...LICENSE_ITEMS,
137
150
  // T5 (v0.3) — The work plane's ONE strict-schema sentence: every top-level draft
138
151
  // field comes from the `## Handoff schema` declared properties (the fields'
@@ -159,6 +172,7 @@ const DOCS_FIX_SHELL = [
159
172
  "**Escaped pipes:** a `## Change history` summary cell that needs a literal vertical bar carries `\\|` — a bare `|` splits the cell in two and the row stops matching the declared header.",
160
173
  '**Dispositions:** every requested finding needs a disposition keyed by its `id` exactly as the requesting carrier prints it (`F1`, `F2`, … — the summary is description only), valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` — a missing or mis-keyed disposition fails the round.',
161
174
  RULINGS_READING,
175
+ SCRATCH_DISCIPLINE,
162
176
  ...LICENSE_ITEMS,
163
177
  // The generic strict-schema sentence — the SAME one the work shells carry: the
164
178
  // injected declaration is the draft's single field source, zero per-mode field
@@ -167,93 +181,280 @@ const DOCS_FIX_SHELL = [
167
181
  ...SCHEMA_SECTION,
168
182
  ];
169
183
  /** The review variants' shared instruction text — the review's mode rule (the
170
- * criteria body + the lens vocabulary ride per-type fixed items below). */
171
- const REVIEW_ITEM = "**review:** review the criteria below against the reference face named in the round context. A wave review judges `INPUT_WAVE_BRIEF` (the complete plan mirror); the plan review judges the plan at `INPUT_PLAN`; the branch review judges the live tree against its base branch (`INPUT_PLAN` is its plan-conformance reference); the spec review judges the spec at `INPUT_SPEC`; the overall review judges the charter at `INPUT_OVERALL`; and a face whose spec carries a `program:` also carries the parent charter at `INPUT_OVERALL`. Write findings into the draft at `OUTPUT_HANDOFF` per `## Handoff schema` (never print them); empty `findings` = approved. The engine derives the conclusion from the draft's findings (blocker → CHANGES_REQUESTED · warn/nit → REVIEW_FIX · none → APPROVED) — a review never declares its own status. **Read-only:** never mutate tracked content, the index, HEAD, or branch state — the prescribed `OUTPUT_*` artifacts are a review's only writes, and committing belongs to the orchestrator — read history through `git show` / `git diff` / `git log`, and inspect another revision in a separate directory rather than moving HEAD here; repairs belong to the fix round, never to a review. **Single agent:** do the whole review yourself — never spawn a subagent for part of the diff or for a second opinion; this overrides any dispatched skill's parallel-sub-agent default.";
184
+ * criteria body + the lens vocabulary ride per-type fixed items below). Its tail is
185
+ * the dispatch OUTPUT discipline: the review face has no separate "review body"
186
+ * array — every one of the six rows folds this block in, so one injection reaches
187
+ * all six (§5.1: four shell texts, not four modes). */
188
+ const REVIEW_ITEM_HEAD = "**review:** review the criteria below against the reference face named in the round context. A wave review judges `INPUT_WAVE_BRIEF` (the complete plan mirror); the plan review judges the plan at `INPUT_PLAN`; the branch review judges the live tree against its base branch (`INPUT_PLAN` is its plan-conformance reference); the spec review judges the spec at `INPUT_SPEC`; the overall review judges the charter at `INPUT_OVERALL`; and a face whose spec carries a `program:` also carries the parent charter at `INPUT_OVERALL`. Write findings into the draft at `OUTPUT_HANDOFF` per `## Handoff schema` (never print them); empty `findings` = approved. The engine derives the conclusion from the draft's findings (blocker → CHANGES_REQUESTED · warn/nit → REVIEW_FIX · none → APPROVED) — a review never declares its own status. **Read-only:** never mutate tracked content, the index, HEAD, or branch state — the prescribed `OUTPUT_*` artifacts are a review's only writes, and committing belongs to the orchestrator — read history through `git show` / `git diff` / `git log`, and inspect another revision in a separate directory rather than moving HEAD here; repairs belong to the fix round, never to a review. **Single agent:** do the whole review yourself — never spawn a subagent for part of the diff or for a second opinion; this overrides any dispatched skill's parallel-sub-agent default.";
189
+ const REVIEW_ITEM = `${REVIEW_ITEM_HEAD}\n\n${SCRATCH_DISCIPLINE}`;
190
+ /** The `never` declaration — a cell (or a slot-less line) that is never exigible.
191
+ * §1.3: this is a legal declaration, not an empty one; `absent` stays writable on
192
+ * it, because `never` + drop is a shape a future cell may legitimately need. */
193
+ const NEVER = [{ types: [] }];
172
194
  /** The review mode's shared reduced tail — the only dynamic region of every review
173
195
  * variant (the criteria/lens are fixed-prefix per type, never here). Each review
174
196
  * type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan →
175
197
  * `INPUT_PLAN` as the judged doc, with `INPUT_SPEC` as its plan→spec conformance
176
198
  * reference; branch → the live tree against `BASE_BRANCH`, with `INPUT_PLAN` as its
177
199
  * plan-conformance reference and the same `INPUT_SPEC` design-spec reference; spec →
178
- * `INPUT_SPEC`; overall → `INPUT_OVERALL`); empty slots are dropped by the
179
- * assembler, so a face renders only the anchors it reads. */
200
+ * `INPUT_SPEC`; overall → `INPUT_OVERALL`); a cell away from its `requiredOn` set
201
+ * is dropped (§1.4), so a face renders only the anchors it reads. */
180
202
  const REVIEW_CONTEXT = [
181
- "## Round context",
182
- "",
183
- "- `ROLE`: {{ROLE}}",
184
- "- `TARGET_TYPE`: {{TARGET_TYPE}}",
185
- "- `WAVE`: {{WAVE}}",
186
- "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
187
- "- `INPUT_PLAN`: {{INPUT_PLAN}}",
188
- "- `INPUT_SPEC`: {{INPUT_SPEC}}",
189
- "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
190
- "- `BASE_BRANCH`: {{BASE_BRANCH}}",
191
- "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
192
- "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
193
- "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
194
- "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
203
+ { line: "## Round context", absent: "drop", requiredOn: NEVER },
204
+ { line: "", absent: "drop", requiredOn: NEVER },
205
+ { line: "- `ROLE`: {{ROLE}}", absent: "drop", requiredOn: [{ types: "always" }] },
206
+ {
207
+ line: "- `TARGET_TYPE`: {{TARGET_TYPE}}",
208
+ absent: "drop",
209
+ requiredOn: [{ types: "always" }],
210
+ },
211
+ { line: "- `WAVE`: {{WAVE}}", absent: "drop", requiredOn: [{ types: ["wave"] }] },
212
+ {
213
+ line: "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
214
+ path: true,
215
+ absent: "drop",
216
+ requiredOn: [{ types: ["wave"] }],
217
+ preview: "satisfied",
218
+ },
219
+ {
220
+ line: "- `INPUT_PLAN`: {{INPUT_PLAN}}",
221
+ path: true,
222
+ absent: "drop",
223
+ requiredOn: [{ types: ["plan", "branch"] }],
224
+ },
225
+ {
226
+ line: "- `INPUT_SPEC`: {{INPUT_SPEC}}",
227
+ path: true,
228
+ absent: "drop",
229
+ requiredOn: [
230
+ { types: ["phase-spec", "single-spec"] },
231
+ { types: ["plan", "branch", "wave"], when: "identity" },
232
+ ],
233
+ },
234
+ {
235
+ line: "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
236
+ path: true,
237
+ absent: "drop",
238
+ requiredOn: [
239
+ { types: ["overall"] },
240
+ { types: ["phase-spec", "plan", "branch", "wave"], when: "program" },
241
+ ],
242
+ },
243
+ {
244
+ line: "- `BASE_BRANCH`: {{BASE_BRANCH}}",
245
+ absent: "drop",
246
+ requiredOn: [{ types: ["branch", "wave"] }],
247
+ },
248
+ {
249
+ line: "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
250
+ absent: "drop",
251
+ requiredOn: [{ types: "always" }],
252
+ },
253
+ {
254
+ line: "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
255
+ absent: "drop",
256
+ requiredOn: [{ types: "always" }],
257
+ },
258
+ {
259
+ line: "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
260
+ absent: "drop",
261
+ requiredOn: [{ types: "always" }],
262
+ },
263
+ { line: "- `WORKSPACE_ID`: {{WORKSPACE_ID}}", absent: "drop", requiredOn: [{ types: "always" }] },
195
264
  ];
196
265
  /** The work-mode dispatch rows — implement / fix / docs-fix (§3.5; the review rows
197
- * are REVIEW_VARIANTS). */
266
+ * are REVIEW_VARIANTS). Each row's `serves` is the set its declarations are judged
267
+ * against (§1.1) — the `fix` row serves two types, never the `fix` verb's six-word
268
+ * `--type` set: the four document faces render the `docs-fix` row instead. */
198
269
  const MODE_PROMPTS = {
199
270
  implement: {
200
271
  mode: "implement",
201
272
  shell: IMPLEMENT_SHELL,
273
+ serves: ["wave"],
202
274
  roundContext: [
203
- "## Round context",
204
- "",
205
- "- `ROLE`: {{ROLE}}",
206
- "- `WAVE`: {{WAVE}}",
207
- "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
208
- // find #4 + #5 — the plan's ## Constraints rides the wave brief mirror;
209
- // the OUTPUT_* write paths are prescribed (the {family}-{key}- canonical names)
210
- "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
211
- "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
212
- "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
213
- "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
214
- "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
275
+ { line: "## Round context", absent: "drop", requiredOn: NEVER },
276
+ { line: "", absent: "drop", requiredOn: NEVER },
277
+ { line: "- `ROLE`: {{ROLE}}", absent: "drop", requiredOn: [{ types: "always" }] },
278
+ { line: "- `WAVE`: {{WAVE}}", absent: "drop", requiredOn: [{ types: "always" }] },
279
+ {
280
+ line: "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
281
+ path: true,
282
+ absent: "drop",
283
+ requiredOn: [{ types: "always" }],
284
+ preview: "satisfied",
285
+ },
286
+ {
287
+ line: "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
288
+ absent: "drop",
289
+ requiredOn: [{ types: "always" }],
290
+ },
291
+ {
292
+ line: "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
293
+ absent: "drop",
294
+ requiredOn: [{ types: "always" }],
295
+ },
296
+ {
297
+ line: "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
298
+ absent: "drop",
299
+ requiredOn: [{ types: "always" }],
300
+ },
301
+ {
302
+ line: "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
303
+ absent: "drop",
304
+ requiredOn: [{ types: "always" }],
305
+ },
306
+ {
307
+ line: "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
308
+ absent: "drop",
309
+ requiredOn: [{ types: "always" }],
310
+ },
215
311
  ],
216
312
  },
217
313
  fix: {
218
314
  mode: "fix",
219
315
  shell: FIX_SHELL,
316
+ serves: ["wave", "branch"],
220
317
  roundContext: [
221
- "## Round context",
222
- "",
223
- "- `ROLE`: {{ROLE}}",
224
- "- `TARGET_TYPE`: {{TARGET_TYPE}}",
225
- "- `WAVE`: {{WAVE}}",
226
- "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
227
- "- `INPUT_PLAN`: {{INPUT_PLAN}}",
228
- "- `INPUT_SPEC`: {{INPUT_SPEC}}",
229
- "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
230
- "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
231
- "- `INPUT_RULINGS`: {{INPUT_RULINGS}}",
232
- "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
233
- "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
234
- "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
235
- "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
236
- "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
318
+ { line: "## Round context", absent: "drop", requiredOn: NEVER },
319
+ { line: "", absent: "drop", requiredOn: NEVER },
320
+ { line: "- `ROLE`: {{ROLE}}", absent: "drop", requiredOn: [{ types: "always" }] },
321
+ {
322
+ line: "- `TARGET_TYPE`: {{TARGET_TYPE}}",
323
+ absent: "drop",
324
+ requiredOn: [{ types: "always" }],
325
+ },
326
+ { line: "- `WAVE`: {{WAVE}}", absent: "drop", requiredOn: [{ types: ["wave"] }] },
327
+ {
328
+ line: "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
329
+ path: true,
330
+ absent: "drop",
331
+ requiredOn: [{ types: ["wave"] }],
332
+ preview: "satisfied",
333
+ },
334
+ {
335
+ line: "- `INPUT_PLAN`: {{INPUT_PLAN}}",
336
+ path: true,
337
+ absent: "drop",
338
+ requiredOn: [{ types: ["branch"] }],
339
+ },
340
+ {
341
+ line: "- `INPUT_SPEC`: {{INPUT_SPEC}}",
342
+ path: true,
343
+ absent: "drop",
344
+ requiredOn: [{ types: ["branch", "wave"], when: "identity" }],
345
+ },
346
+ {
347
+ line: "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
348
+ path: true,
349
+ absent: "drop",
350
+ requiredOn: [{ types: ["branch", "wave"], when: "program" }],
351
+ },
352
+ {
353
+ line: "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
354
+ path: true,
355
+ absent: "drop",
356
+ requiredOn: [{ types: "always" }],
357
+ },
358
+ {
359
+ line: "- `INPUT_RULINGS`: {{INPUT_RULINGS}}",
360
+ path: true,
361
+ absent: "none",
362
+ requiredOn: NEVER,
363
+ },
364
+ {
365
+ line: "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
366
+ absent: "drop",
367
+ requiredOn: [{ types: "always" }],
368
+ },
369
+ {
370
+ line: "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
371
+ absent: "drop",
372
+ requiredOn: [{ types: "always" }],
373
+ },
374
+ {
375
+ line: "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
376
+ absent: "drop",
377
+ requiredOn: [{ types: "always" }],
378
+ },
379
+ {
380
+ line: "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
381
+ absent: "drop",
382
+ requiredOn: [{ types: "always" }],
383
+ },
384
+ {
385
+ line: "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
386
+ absent: "drop",
387
+ requiredOn: [{ types: "always" }],
388
+ },
237
389
  ],
238
390
  },
239
391
  "docs-fix": {
240
392
  mode: "docs-fix",
241
393
  shell: DOCS_FIX_SHELL,
394
+ serves: ["phase-spec", "single-spec", "plan", "overall"],
242
395
  roundContext: [
243
- "## Round context",
244
- "",
245
- "- `ROLE`: {{ROLE}}",
246
- "- `TARGET_TYPE`: {{TARGET_TYPE}}",
247
- "- `WAVE`: {{WAVE}}",
248
- "- `INPUT_PLAN`: {{INPUT_PLAN}}",
249
- "- `INPUT_SPEC`: {{INPUT_SPEC}}",
250
- "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
251
- "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
252
- "- `INPUT_RULINGS`: {{INPUT_RULINGS}}",
253
- "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
254
- "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
255
- "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
256
- "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
396
+ { line: "## Round context", absent: "drop", requiredOn: NEVER },
397
+ { line: "", absent: "drop", requiredOn: NEVER },
398
+ { line: "- `ROLE`: {{ROLE}}", absent: "drop", requiredOn: [{ types: "always" }] },
399
+ {
400
+ line: "- `TARGET_TYPE`: {{TARGET_TYPE}}",
401
+ absent: "drop",
402
+ requiredOn: [{ types: "always" }],
403
+ },
404
+ { line: "- `WAVE`: {{WAVE}}", absent: "drop", requiredOn: NEVER },
405
+ {
406
+ line: "- `INPUT_PLAN`: {{INPUT_PLAN}}",
407
+ path: true,
408
+ absent: "drop",
409
+ requiredOn: [{ types: ["plan"] }],
410
+ },
411
+ {
412
+ line: "- `INPUT_SPEC`: {{INPUT_SPEC}}",
413
+ path: true,
414
+ absent: "drop",
415
+ requiredOn: [
416
+ { types: ["phase-spec", "single-spec"] },
417
+ { types: ["plan"], when: "identity" },
418
+ ],
419
+ },
420
+ {
421
+ line: "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
422
+ path: true,
423
+ absent: "drop",
424
+ requiredOn: [{ types: ["overall"] }, { types: ["phase-spec", "plan"], when: "program" }],
425
+ },
426
+ {
427
+ line: "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
428
+ path: true,
429
+ absent: "drop",
430
+ requiredOn: [{ types: "always" }],
431
+ },
432
+ {
433
+ line: "- `INPUT_RULINGS`: {{INPUT_RULINGS}}",
434
+ path: true,
435
+ absent: "none",
436
+ requiredOn: NEVER,
437
+ },
438
+ {
439
+ line: "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
440
+ absent: "drop",
441
+ requiredOn: [{ types: "always" }],
442
+ },
443
+ {
444
+ line: "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
445
+ absent: "drop",
446
+ requiredOn: [{ types: "always" }],
447
+ },
448
+ {
449
+ line: "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
450
+ absent: "drop",
451
+ requiredOn: [{ types: "always" }],
452
+ },
453
+ {
454
+ line: "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
455
+ absent: "drop",
456
+ requiredOn: [{ types: "always" }],
457
+ },
257
458
  ],
258
459
  },
259
460
  };
@@ -264,11 +465,21 @@ export const SEVERITY_RUBRIC_SLOTS = {
264
465
  artifact: "{artifact}",
265
466
  audience: "{audience}",
266
467
  };
468
+ /** The rubric's opening calibration line — a stance, not criteria prose: the tier
469
+ * boundaries themselves come from the criteria registry below. */
470
+ const RUBRIC_PREAMBLE = "Calibrate findings by real severity — not everything is a blocker.";
471
+ /** The calibration tail — the same-grade consistency duty, the vision
472
+ * (silence-is-not-permission) sentence with its two slots, the set-aside ledger and
473
+ * the closing acknowledgement. It shares the fragment with every review axes guide,
474
+ * and it is NOT a second copy of the tier criteria: those are rows in
475
+ * `contract/review-criteria.ts`. */
476
+ const CALIBRATION_TAIL = "Within one run, a defect already graded in the same class keeps that grade; crossing grades names its reason in the finding. The reviewed {artifact} is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable {audience} would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust).";
267
477
  /** The severity rubric — the ONE calibration fragment every review axes guide
268
- * shares: the four blocker questions, the warn/nit tiers, the same-grade
269
- * consistency duty, the vision (silence-is-not-permission) sentence with its two
270
- * slots, the set-aside ledger and the closing acknowledgement. */
271
- export const SEVERITY_RUBRIC = "Calibrate findings by real severity — not everything is a blocker. A finding is a blocker when any one of these holds: (a) the declared acceptance gate, contract or prompt is violated; (b) a legal input escapes the declared failure face (a blank input returns 500, an unknown id is not a 404); (c) the gate fails or the suite can never go red (an inert grep · a dead guard · an unconditional skip); (d) a security or privacy defect. Debt inside the contract is a warn (duplicated policy · stale docstring · a missing coverage case). Style, naming and line-wrapping is a nit. Within one run, a defect already graded in the same class keeps that grade; crossing grades names its reason in the finding. The reviewed {artifact} is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable {audience} would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust).";
478
+ * shares. Its tier body is ASSEMBLED from the criteria registry (every row's
479
+ * `body` → `duty` → `counterExample`, tiers in blocker → warn → nit order), so the
480
+ * registry is the only corpus of tier prose; the calibration tail rides here, and
481
+ * `reviewGuideOf` fills the two slots. */
482
+ export const SEVERITY_RUBRIC = `${RUBRIC_PREAMBLE} ${CRITERIA.renderRubric()} ${CALIBRATION_TAIL}`;
272
483
  /** The slot values per criteria body — the ONE registry the filled fragment reads.
273
484
  * `{artifact}` = the reviewed product's name; `{audience}` = the subject whose
274
485
  * expectation judges the artifact's silence. The two spec-shaped targets share the
@@ -289,6 +500,13 @@ export const reviewGuideOf = (key) => {
289
500
  const text = REVIEW_BODY_TEXT[key];
290
501
  return SEVERITY_RUBRIC.replaceAll(SEVERITY_RUBRIC_SLOTS.artifact, text.artifact).replaceAll(SEVERITY_RUBRIC_SLOTS.audience, text.audience);
291
502
  };
503
+ /** One review kind's numbered lens question list (design spec §3.2 · §6.1) — the
504
+ * `LENS_QUESTIONS.forReviewKind` projection rendered as `1. …` lines, appended to
505
+ * that kind's axes guide so the questions ride the `**Criteria —` bytes. The list is
506
+ * the table's projection, never a second copy: deleting a row shortens this list. */
507
+ const lensQuestionBlock = (kind) => LENS_QUESTIONS.forReviewKind(kind)
508
+ .map((row, index) => `${index + 1}. ${row.question}`)
509
+ .join("\n");
292
510
  /** The closed-wave discipline's ONE sentence (P30 §2.7) — the document review axes'
293
511
  * shared body: a finding on an already-closed task block's content face is answered
294
512
  * by the document, never by moving the work. Both document criteria bodies select
@@ -318,24 +536,45 @@ const docCharterAxes = (guide) => `Follow URC: single-cycle, lens-tagged finding
318
536
  * copy. */
319
537
  export const REVIEWS = {
320
538
  wave: {
321
- lensEnum: ["standards", "spec", "buildability"],
322
- axesGuide: `Standards axis (repo coding standards + code-review smell baseline) + Spec axis (wave brief / plan requirements) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — \`tsc --noEmit\`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): run \`git diff origin/<BASE_BRANCH>..HEAD\` yourself (BASE_BRANCH as named in the round context; on a missing artifact judge the working tree) — every changed file must fall within the wave brief's file surface (\`**Files:**\` seams) or be attributable to the plan / reviewed intent; an unattributable changed file is a candidate finding (severity by your judgment). The reviewer is the changed-surface judge — the engine reconciles nothing. ${reviewGuideOf("wave")}`,
539
+ lensEnum: ["standards", "spec", "buildability", "scope"],
540
+ pinLens: "standards",
541
+ axesGuide: `Standards axis (repo coding standards + code-review smell baseline) + Spec axis (wave brief / plan requirements) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — \`tsc --noEmit\`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): run \`git diff origin/<BASE_BRANCH>..HEAD\` yourself (BASE_BRANCH as named in the round context; on a missing artifact judge the working tree) — every changed file must fall within the wave brief's file surface (\`**Files:**\` seams) or be attributable to the plan / reviewed intent; an unattributable changed file is a candidate finding. The reviewer is the changed-surface judge — the engine reconciles nothing. ${reviewGuideOf("wave")}
542
+
543
+ ${lensQuestionBlock("wave")}`,
323
544
  },
324
545
  branch: {
325
- lensEnum: ["standards", "spec", "buildability"],
326
- axesGuide: `Same four axes as the wave review (branch-wide health: run \`git diff origin/<BASE_BRANCH>..HEAD\` + plan conformance) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — \`tsc --noEmit\`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): branch review IS the full diff — every changed file must be attributable to a finding, a plan requirement, or the reviewed intent; unrelated surface = candidate finding (severity by your judgment), normal finding → fix loop. ${reviewGuideOf("branch")} Three things a green run cannot show you: design — does the changed structure fit this codebase and is it the simplest structure that solves the plan's problem (over-engineering is a finding, not a preference); test adequacy — would these tests fail if the code broke (a run that cannot go red is not evidence); migration — does every breaking change name the path a not-yet-migrated consumer takes.`,
546
+ lensEnum: ["standards", "spec", "buildability", "scope"],
547
+ pinLens: "standards",
548
+ axesGuide: `Same four axes as the wave review (branch-wide health: run \`git diff origin/<BASE_BRANCH>..HEAD\` + plan conformance) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — \`tsc --noEmit\`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): branch review IS the full diff — every changed file must be attributable to a finding, a plan requirement, or the reviewed intent; unrelated surface = candidate finding, normal finding → fix loop. ${reviewGuideOf("branch")} Three things a green run cannot show you: design — does the changed structure fit this codebase and is it the simplest structure that solves the plan's problem (over-engineering is a finding, not a preference); test adequacy — would these tests fail if the code broke (a run that cannot go red is not evidence); migration — does every breaking change name the path a not-yet-migrated consumer takes.
549
+
550
+ ${lensQuestionBlock("branch")}`,
327
551
  },
328
552
  spec: {
329
553
  lensEnum: ["completeness", "consistency", "clarity"],
330
- axesGuide: docNarrativeAxes(reviewGuideOf("spec")),
554
+ // §7.2's own word for this corpus: two statements of one fact — the document's
555
+ // claim and the tree — disagree.
556
+ pinLens: "consistency",
557
+ axesGuide: `${docNarrativeAxes(reviewGuideOf("spec"))}
558
+
559
+ ${lensQuestionBlock("spec")}`,
331
560
  },
332
561
  overall: {
333
562
  lensEnum: ["scope", "inventory", "dependency", "acceptance", "boundary"],
334
- axesGuide: docCharterAxes(reviewGuideOf("overall")),
563
+ // The charter's criterion 6 is this row's home: the inventory and the tree
564
+ // disagree, so a pin that resolves nowhere reads as a ledger drift.
565
+ pinLens: "inventory",
566
+ axesGuide: `${docCharterAxes(reviewGuideOf("overall"))}
567
+
568
+ ${lensQuestionBlock("overall")}`,
335
569
  },
336
570
  plan: {
337
571
  lensEnum: ["completeness", "decomposition", "buildability"],
338
- axesGuide: `Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + spec conformance — the plan is judged against its design spec at \`INPUT_SPEC\` (the plan's \`spec\` front-matter target): every spec requirement must map to a task, and a spec requirement with no owning task is a completeness finding + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding. ${CLOSED_WAVE_DISCIPLINE} ${reviewGuideOf("plan")}`,
572
+ // A step naming a coordinate the tree does not have is a step that cannot be
573
+ // executed against the tree as it stands.
574
+ pinLens: "buildability",
575
+ axesGuide: `Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + spec conformance — the plan is judged against its design spec at \`INPUT_SPEC\` (the plan's \`spec\` front-matter target): every spec requirement must map to a task, and a spec requirement with no owning task is a completeness finding + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding. ${CLOSED_WAVE_DISCIPLINE} ${reviewGuideOf("plan")}
576
+
577
+ ${lensQuestionBlock("plan")}`,
339
578
  },
340
579
  };
341
580
  /** The criteria-body selection — the ONE target → criteria map. Four targets select
@@ -343,6 +582,32 @@ export const REVIEWS = {
343
582
  * narrative body (`spec`). Keeping the mapping here (never in the row literals)
344
583
  * means a target cannot silently drift onto another target's criteria. */
345
584
  export const reviewBodyOf = (type) => type === "phase-spec" || type === "single-spec" ? "spec" : type;
585
+ /** The lens an engine-authored pin row carries on one target's face (design spec
586
+ * §7.2) — the ONE derivation the read-back's injection point reads. The value is
587
+ * the face's declared `pinLens`, and it is cross-checked against that face's own
588
+ * `lensEnum` here: the menu and the injected row are written for different readers
589
+ * (the child's prompt vs the carrier), so a drifted pair must throw at its first
590
+ * dispatch instead of reaching a carrier as a label the same round's prompt calls
591
+ * impossible. `guides` is the declared table, injectable so the gate itself is
592
+ * pinnable. */
593
+ export const pinLensOf = (type, guides = REVIEWS) => {
594
+ const key = reviewBodyOf(type);
595
+ const row = guides[key];
596
+ if (!row.lensEnum.includes(row.pinLens)) {
597
+ throw new Error(`the pin lens "${row.pinLens}" is not declared by the ${key} lens menu (${row.lensEnum.join(" | ")})`);
598
+ }
599
+ return row.pinLens;
600
+ };
601
+ /** The six target types every review variant renders — the review row's `serves`
602
+ * set (§1.1): one criteria body per type, one shared dynamic tail. */
603
+ const REVIEW_SERVES = [
604
+ "wave",
605
+ "branch",
606
+ "phase-spec",
607
+ "overall",
608
+ "plan",
609
+ "single-spec",
610
+ ];
346
611
  /** One review variant row (§3.7) — the fixed prefix folds the SELECTED criteria
347
612
  * body + its lens INLINE (the `INPUT_CRITERIA`/`INPUT_LENS` round-context tokens
348
613
  * are gone) and shares the REVIEW_CONTEXT dynamic tail. The target word labels the
@@ -364,6 +629,7 @@ const reviewRow = (type) => {
364
629
  ...LICENSE_ITEMS,
365
630
  ...SCHEMA_SECTION,
366
631
  ],
632
+ serves: REVIEW_SERVES,
367
633
  roundContext: REVIEW_CONTEXT,
368
634
  };
369
635
  };
@@ -436,7 +702,20 @@ export const CLAUSES = {
436
702
  "cl:no-secret-access": "Never read, print, or derive a user secret — no keychain access (`security find-generic-password` / `security dump-keychain` / `login.keychain-db`), no `~/.ssh/*`, `~/.aws/credentials`, `~/.netrc`, no host CLI credential store, and no token-bearing environment variable (`*_TOKEN` / `*_API_KEY` / `*_SECRET`). A missing or failing credential is never yours to obtain: report it as `status: BLOCKED` on a work round or as a finding on a review round, then continue with the rest. A secret that reaches a report, evidence file, handoff draft, commit, or issue body has leaked — if one is already visible in your inputs, redact it as `[REDACTED]` and never echo its value.",
437
703
  "cl:sync-completion": "This dispatch is one-shot and non-interactive: end your turn with anything still running and the process exits — the work and the handoff die with it. So do not end your turn — a background command, a background subagent, or any yield-and-wait path such as `bg_run` / `bg_delegate` — before the handoff draft is written. Finish nested work in this same turn: complete it synchronously in this process turn, then write the handoff and finish.",
438
704
  };
439
- /** The dispatch-prompt data plane — the typed template-contract surface. $version 23
705
+ /** The dispatch-prompt data plane — the typed template-contract surface. $version 25
706
+ * carries the P38 dispatch-contract batch (§2.3 · §3.1 · §3.3 · §5.1), three byte
707
+ * changes over 24: the `scratch/<round-id>/` discipline sentence in all four shell
708
+ * texts (implement · review · fix · docs-fix); the `INPUT_RULINGS` `none`
709
+ * half-sentence in the two fix shells (§3.3); and the fix / docs-fix
710
+ * `INPUT_RULINGS` cell rendering the bare literal `none` instead of vanishing when
711
+ * the round has no ruling sidecar — reversal ③, carried by the line-level
712
+ * declaration (`absent: "none"`) that replaced the old empty-drop (§2.3 · §3.1).
713
+ * The prompt bytes changed here, and this counter is their one mechanical signal.
714
+ * $version 24
715
+ * names the wave line in the fix shell's anchor clause (P37 §4.1): the wave line now
716
+ * carries the same `INPUT_SPEC` conformance reference and the `INPUT_OVERALL` parent
717
+ * charter as the branch line, so the clause a maintainer reads can no longer
718
+ * attribute those anchors to the branch line alone. $version 23
440
719
  * calibrates the shared body's five faces (§2.6 G · H · I · J · K): the freeze
441
720
  * clause limits itself to the round's declared `capability: may.amend` scope and
442
721
  * the commit clause names the read-only round's absent commit; the capability
@@ -499,7 +778,7 @@ export const CLAUSES = {
499
778
  * prose return contract (`RETURN_PROSE` — nothing downstream parses the child's
500
779
  * stdout), and the per-type review criterion shells. */
501
780
  export const TEMPLATE_PROMPT = {
502
- $version: 23,
781
+ $version: 25,
503
782
  modes: MODE_PROMPTS,
504
783
  reviews: REVIEW_VARIANTS,
505
784
  return: RETURN_ZONE,
@@ -511,14 +790,26 @@ export const WORK_MODES = ["implement", "fix", "review", "docs-fix"];
511
790
  /**
512
791
  * The template assembler — the ONE renderer over the typed template-prompt data
513
792
  * plane. Construction reads the typed contract (the module's declared data —
514
- * no file reads, no second copy). render(values) selects the row by the ROLE value
515
- * (the review mode by ROLE + TARGET_TYPE) — the row's fixed prefix + the single
516
- * return contract + its reduced round context (empty-value keys not emitted).
793
+ * no file reads, no second copy) and asserts the declarations it carries.
794
+ * render(values) selects the row by the ROLE value (the review mode by ROLE +
795
+ * TARGET_TYPE) — the row's fixed prefix + the single return contract + its
796
+ * declared round context.
797
+ *
798
+ * Class size: the 200-line cap is exceeded by the construction-time declaration
799
+ * criteria living beside the renderer they guard — the P39 split owns the
800
+ * extraction, and a second home for these five criteria would be a second truth.
517
801
  */
518
802
  export class TemplateAssembler {
803
+ /** The ONE cell whose preview answer is its naming line's (§1.1 · §2.4) — the
804
+ * brief, the single artifact `renderBrief` writes at dispatch alone. Any other
805
+ * cell declaring `preview: "satisfied"` has no naming answer in this engine, so
806
+ * the declaration is refused at construction (#assertPreviewAnswer) rather than
807
+ * silently read as `value`. */
808
+ static NAMED_BRIEF_CELL = "INPUT_WAVE_BRIEF";
519
809
  #contract;
520
- constructor() {
521
- this.#contract = TEMPLATE_PROMPT;
810
+ constructor(contract = TEMPLATE_PROMPT) {
811
+ this.#contract = contract;
812
+ this.#assertDeclarations();
522
813
  }
523
814
  /** The tokens the contract declares (the union across every mode — all zones). */
524
815
  declaredTokens() {
@@ -528,18 +819,22 @@ export class TemplateAssembler {
528
819
  workModes() {
529
820
  return WORK_MODES;
530
821
  }
822
+ /** The line selection and the declarations of the selected row — the ONE read
823
+ * surface for "which row is this round, and what does that row declare". The
824
+ * dispatch-input gate reads this and never writes a second row selection. */
825
+ layoutOf(values) {
826
+ return this.#rowOf(values).roundContext;
827
+ }
531
828
  /** Assemble the full dispatch template for a role with the slot values — the
532
- * row's fixed prefix + the single return contract + its reduced round context
533
- * (empty-value keys omitted). */
829
+ * row's fixed prefix + the single return contract + its declared round context. */
534
830
  render(values) {
535
831
  this.#gate(values);
536
- const row = this.#rowOf(values);
537
- const zones = {
538
- shell: this.#joinLines(row.shell),
539
- return: this.#joinLines(this.#contract.return.RETURN_PROSE),
540
- "round-context": this.#contextLines(row, values),
541
- };
542
- return this.#fill([zones.shell, zones.return, zones["round-context"]].join("\n\n"), values);
832
+ const zones = [
833
+ this.#joinLines(this.#rowOf(values).shell),
834
+ this.#joinLines(this.#contract.return.RETURN_PROSE),
835
+ this.#contextLines(this.layoutOf(values), values),
836
+ ];
837
+ return this.#fill(zones.join("\n\n"), values);
543
838
  }
544
839
  #joinLines(lines) {
545
840
  return lines.join("\n");
@@ -560,23 +855,125 @@ export class TemplateAssembler {
560
855
  }
561
856
  return row;
562
857
  }
563
- /** The reduced round-context section — the row's subset, a key whose value is
564
- * empty omitted (only present facts land in the dynamic region). */
565
- #contextLines(row, values) {
858
+ /** The reduced round-context section — each declared line resolved off its own
859
+ * declaration: a non-empty value renders the value, an empty one drops the line
860
+ * (`absent: "drop"`) or renders the bare literal `none` (`absent: "none"`). The
861
+ * rendering layer has THREE states, never a fourth: exigibility is judged upstream
862
+ * by the dispatch-input gate, so no "empty but required" branch exists here. */
863
+ #contextLines(decls, values) {
566
864
  const lines = [];
567
- for (const line of row.roundContext) {
568
- const slot = line.match(/\{\{([A-Z0-9_]+)\}\}/)?.[1];
569
- if (slot !== undefined && values[slot] === "")
570
- continue;
571
- lines.push(line);
865
+ for (const decl of decls) {
866
+ const slot = _a.slotOf(decl.line);
867
+ if (slot === undefined)
868
+ lines.push(decl.line);
869
+ else if (values[slot] !== "")
870
+ lines.push(decl.line);
871
+ else if (decl.absent === "none")
872
+ lines.push(decl.line.replace(/\{\{[A-Z0-9_]+\}\}/, "none"));
572
873
  }
573
874
  return lines.join("\n");
574
875
  }
876
+ /** The construction-time declaration criteria (§1.1 · §1.3 · §4.2) — ONE home, run
877
+ * once per construction over every row: a dead cell (a) · an unregistered slot
878
+ * (b) · a shell naming a cell its layout never carries (c) · a registered
879
+ * round-context token no row carries (d) · a preview answer declared on a cell the
880
+ * naming row cannot answer (e). A violation means the assembler cannot be built, so
881
+ * no dispatch can ever reach it — the per-render re-run is gone. */
882
+ #assertDeclarations() {
883
+ for (const row of this.#rows()) {
884
+ for (const decl of row.roundContext) {
885
+ this.#assertServed(row, decl);
886
+ this.#assertRegistered(row, decl);
887
+ this.#assertPreviewAnswer(row, decl);
888
+ }
889
+ this.#assertShellCarries(row);
890
+ }
891
+ this.#assertEveryCellHasCarrier();
892
+ }
893
+ #rows() {
894
+ return [...Object.values(this.#contract.modes), ...Object.values(this.#contract.reviews)];
895
+ }
896
+ /** (a) the dead cell — an arm naming a type the row never serves. `always` and the
897
+ * `never` form (`{ types: [] }`) declare nothing about a type, so they never die. */
898
+ #assertServed(row, decl) {
899
+ for (const arm of decl.requiredOn) {
900
+ if (arm.types === "always")
901
+ continue;
902
+ for (const type of arm.types) {
903
+ if (row.serves.includes(type))
904
+ continue;
905
+ throw new Error(`template mode ${row.mode} declares requiredOn type ${type} for ${_a.#labelOf(decl)} — a type this row never serves`);
906
+ }
907
+ }
908
+ }
909
+ /** (b) the slot registration — every `{{TOKEN}}` a row carries is a registered
910
+ * round-context token; an unregistered slot points at a value never supplied. */
911
+ #assertRegistered(row, decl) {
912
+ for (const slot of _a.#slotsOf(decl.line)) {
913
+ const declared = this.#contract.tokens.some((token) => token.name === slot && token.zone === "round-context");
914
+ if (declared)
915
+ continue;
916
+ throw new Error(`template mode ${row.mode} round context carries undeclared slot {{${slot}}}`);
917
+ }
918
+ }
919
+ /** (c) shell↔layout — every round-context name the row's shell prose references
920
+ * (`INPUT_*` / `OUTPUT_*` / `BASE_BRANCH`) is carried by that row's layout ∪ the
921
+ * shared return tail. The shell prose is not `{{slot}}`-templated, so this is the
922
+ * only face that can see "claimed but not carried". */
923
+ #assertShellCarries(row) {
924
+ const allowed = new Set([
925
+ ...row.roundContext.flatMap((decl) => _a.#namesIn(decl.line)),
926
+ ..._a.#namesIn(this.#joinLines(this.#contract.return.RETURN_PROSE)),
927
+ ]);
928
+ for (const name of new Set(_a.#namesIn(this.#joinLines(row.shell)))) {
929
+ if (allowed.has(name))
930
+ continue;
931
+ throw new Error(`template mode ${row.mode} shell references ${name} not carried by its round context`);
932
+ }
933
+ }
934
+ /** (e) the preview answer — only the brief cell may declare `preview: "satisfied"`.
935
+ * The exemption synthesises the one cell whose value the naming row writes
936
+ * (`RoundNaming#briefName`), so a second `satisfied` cell would be declared, then
937
+ * silently judged as `value`; refusing it at construction keeps the declaration
938
+ * error at build time instead of on the one path that happens to take it. */
939
+ #assertPreviewAnswer(row, decl) {
940
+ if (decl.preview !== "satisfied")
941
+ return;
942
+ if (_a.slotOf(decl.line) === _a.NAMED_BRIEF_CELL)
943
+ return;
944
+ throw new Error(`template mode ${row.mode} declares preview "satisfied" for ${_a.#labelOf(decl)} — only ${_a.NAMED_BRIEF_CELL} may (the one cell the naming row answers)`);
945
+ }
946
+ /** (d) the zone coverage — every registered round-context token is carried by at
947
+ * least one row's layout; the inverse of (b), and a distinct direction: (b) asks
948
+ * "is the slot registered", (d) asks "has the registered token a carrier". */
949
+ #assertEveryCellHasCarrier() {
950
+ const carried = new Set(this.#rows().flatMap((row) => row.roundContext.flatMap((decl) => _a.#slotsOf(decl.line))));
951
+ for (const token of this.#contract.tokens) {
952
+ if (token.zone !== "round-context" || carried.has(token.name))
953
+ continue;
954
+ throw new Error(`template token ${token.name} (round-context) is carried by no row layout`);
955
+ }
956
+ }
957
+ /** The `{{TOKEN}}` slot a declared line carries — `undefined` for a value-less line
958
+ * (the heading, the separator blank line). The ONE slot-grammar reader: the gate
959
+ * that judges a layout's cells reads it here rather than re-spelling the braces. */
960
+ static slotOf(line) {
961
+ return /\{\{([A-Z0-9_]+)\}\}/.exec(line)?.[1];
962
+ }
963
+ static #slotsOf(line) {
964
+ return [...line.matchAll(/\{\{([A-Z0-9_]+)\}\}/g)].map((match) => match[1]);
965
+ }
966
+ static #namesIn(text) {
967
+ return text.match(/\b(?:INPUT_[A-Z0-9_]+|OUTPUT_[A-Z0-9_]+|BASE_BRANCH)\b/g) ?? [];
968
+ }
969
+ static #labelOf(decl) {
970
+ return _a.slotOf(decl.line) ?? "a value-less line";
971
+ }
575
972
  /** The hard gates — a known ROLE (+ its TARGET_TYPE for reviews), every declared
576
973
  * token supplied (empty allowed — a mode's non-consumed slots are legitimately
577
- * empty and merely not emitted), no undeclared values, the single return
578
- * contract declared, and every round-context name the mode's shell prose
579
- * references carried by that mode's layout (shell↔layout consistency). */
974
+ * empty and merely not emitted on render), no undeclared values, and the single
975
+ * return contract declared. Declaration consistency is a construction-time
976
+ * criterion (§1.1), never a per-render one. */
580
977
  #gate(values) {
581
978
  const role = values.ROLE;
582
979
  const row = role === undefined
@@ -600,26 +997,6 @@ export class TemplateAssembler {
600
997
  throw new Error(`template value provided for undeclared token ${name}`);
601
998
  }
602
999
  }
603
- this.#assertShellLayout(row);
604
- }
605
- /** The shell↔layout consistency assertion (§3.6): every round-context name the
606
- * mode's shell prose references (`INPUT_*` / `OUTPUT_*` / `BASE_BRANCH`) must be
607
- * carried by that mode's round-context layout ∪ the shared return tail — a shell
608
- * claiming a slot its layout never carries is a construction error. This closes
609
- * the "claimed but not carried" blind spot the token gates cannot see (the shell
610
- * prose is not `{{slot}}`-templated). */
611
- #assertShellLayout(row) {
612
- const naming = /\b(?:INPUT_[A-Z0-9_]+|OUTPUT_[A-Z0-9_]+|BASE_BRANCH)\b/g;
613
- const namesOf = (text) => text.match(naming) ?? [];
614
- const allowed = new Set([
615
- ...row.roundContext.flatMap((line) => namesOf(line)),
616
- ...namesOf(this.#joinLines(this.#contract.return.RETURN_PROSE)),
617
- ]);
618
- for (const name of new Set(namesOf(this.#joinLines(row.shell)))) {
619
- if (!allowed.has(name)) {
620
- throw new Error(`template mode ${row.mode} shell references ${name} not carried by its round context`);
621
- }
622
- }
623
1000
  }
624
1001
  /** The review variant of a TARGET_TYPE (verified in the gate). */
625
1002
  #reviewRow(values) {
@@ -650,3 +1027,4 @@ export class TemplateAssembler {
650
1027
  });
651
1028
  }
652
1029
  }
1030
+ _a = TemplateAssembler;