@oscaner-skills/cdd-engine 4.14.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.
package/dist/face/cli.js CHANGED
@@ -768,7 +768,7 @@ export class Cli {
768
768
  scene.briefPath = this.#gate.renderBrief(scene, parsed, text, doc);
769
769
  }
770
770
  const statuses = [];
771
- const { step: dispatch, harness } = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null, artifacts);
771
+ const { step: dispatch, harness } = await this.#dispatchOf(scene, parsed, recovery !== null, artifacts);
772
772
  const run = new Lifecycle({
773
773
  face: scene.face,
774
774
  state: scene.state,
@@ -832,11 +832,20 @@ export class Cli {
832
832
  // derivation), and the early return means no write point below ever runs
833
833
  // (`renderBrief` skipped above, `#bookkeep`/`#reject` never reached).
834
834
  if (parsed.dryRun) {
835
- // The artifact-identity gate is a PURE read (the matrix's names + the strict
836
- // sidecar schema), so the preview asks the SAME judgment the real dispatch
837
- // applies and prints its reason verbatim — a dry run that stayed silent here
838
- // would forecast a dispatch the real run refuses.
839
- const refused = harness === null ? null : harness.artifactRefusal(frame);
835
+ // The three pre-dispatch gates — carrier-integrity, dispatch-input and
836
+ // artifact-identity — are PURE reads (a digest comparison, the layout's supplied
837
+ // cells + the matrix's names + the strict sidecar schema), so the preview asks
838
+ // the SAME judgments the real dispatch applies, in the same order, and prints
839
+ // the first refusal verbatim — a dry run that stayed silent here would forecast
840
+ // a dispatch the real run refuses. `mode: "preview"` is the dispatch-input
841
+ // gate's ONE weaker (permissive) arm: a brief it would render itself is answered
842
+ // by its naming line, never by an existence read; every other cell is judged
843
+ // identically.
844
+ const refused = harness === null
845
+ ? null
846
+ : (harness.carrierRefusal(frame) ??
847
+ harness.inputRefusal(frame, "preview") ??
848
+ harness.artifactRefusal(frame));
840
849
  const preview = new Preview({ scene, words: this.#words });
841
850
  if (refused !== null) {
842
851
  for (const line of preview.artifactBlock(verb, refused))
@@ -921,18 +930,20 @@ export class Cli {
921
930
  async #dispatchOf(scene, parsed, recovered, artifacts) {
922
931
  if (this.#dispatch !== null)
923
932
  return { step: this.#dispatch, harness: null };
924
- const harness = recovered ?? this.#lifecycleOf(scene, parsed, artifacts);
933
+ const harness = this.#lifecycleOf(scene, parsed, artifacts);
925
934
  // The abort fold already ran at the composition root's `--recover` judgment
926
- // (`#recoverRun`) when a harness was handed in; the injected/default face keeps
927
- // its own fold here, so the takeover always precedes this dispatch's own record.
928
- if (recovered === null && !parsed.dryRun && parsed.args.recover === "true") {
935
+ // (`#recoverRun`) when `recovered`; the injected/default face keeps its own fold
936
+ // here, so the takeover always precedes this dispatch's own record.
937
+ if (!recovered && !parsed.dryRun && parsed.args.recover === "true") {
929
938
  await harness.foldAbort();
930
939
  }
931
- // The harness itself rides back so the `--dry-run` branch can ask it the
932
- // artifact-identity gate's PURE read (the same judgment `step()` applies), and
933
- // the preview can print the real run's refusal instead of forecasting a dispatch
934
- // it would refuse. The injected `#dispatch` seam has no harness — a hermetic
935
- // caller already replaced the whole dispatch, so there is no gate to ask.
940
+ // The harness itself rides back so the `--dry-run` branch can ask it the three
941
+ // pre-dispatch gates' PURE reads — the carrier-integrity judgment, then the
942
+ // dispatch-input judgment, then the artifact-identity one, the order this face's own
943
+ // dispatch applies them in (the same judgments `step()` applies), and the preview can
944
+ // print the real run's refusal instead of forecasting a dispatch it would refuse. The
945
+ // injected `#dispatch` seam has no harness — a hermetic caller already replaced the
946
+ // whole dispatch, so there is no gate to ask.
936
947
  return { step: harness.step(), harness };
937
948
  }
938
949
  /** The `--recover` judgment (spec §2.1①–③) — the two legs, judged in order and
@@ -949,13 +960,16 @@ export class Cli {
949
960
  * and `implement --recover` take leg ① only (never a reopen), wave lines likewise
950
961
  * (their reopen face stays P29's brief-drift). */
951
962
  async #recoverRun(verb, type, scene, parsed, inflight, artifacts) {
952
- const harness = this.#lifecycleOf(scene, parsed, artifacts);
963
+ // The fold rides a throwaway harness: this judgment runs BEFORE the wave brief is
964
+ // rendered, and the DISPATCHING harness must be built afterwards (its scene snapshot
965
+ // carries `briefPath` — the dispatch-input gate reads it). `foldAbort` touches only
966
+ // the in-flight record and the ledger, so a pre-brief instance is enough.
953
967
  const stale = (await inflight.staleState()) !== null;
954
968
  if (stale)
955
- await harness.foldAbort();
969
+ await this.#lifecycleOf(scene, parsed, artifacts).foldAbort();
956
970
  const reopened = await this.#reopenLeg(verb, type, scene, inflight);
957
971
  if (stale || reopened)
958
- return { kind: "allowed", harness };
972
+ return { kind: "allowed" };
959
973
  return { kind: "blocked", message: RECOVER_NOTHING };
960
974
  }
961
975
  /** The reopen leg (spec §2.3) — its three conditions judged here, and the stamp
@@ -989,9 +1003,14 @@ export class Cli {
989
1003
  const latest = Math.max(...completed);
990
1004
  return ledger.supersedeReview(identity.key, latest, latest + 1);
991
1005
  }
992
- /** The invocation's lifecycle harness — the production dispatch face, held by the
993
- * composition root so the abort fold can ride the SAME instance that dispatches
994
- * (the takeover precedes the stamp, spec §2.1④). */
1006
+ /** The invocation's lifecycle harness — the production dispatch face, built at the
1007
+ * point of use and never held across the brief render. The scene snapshot it copies
1008
+ * carries `briefPath`, which `CliGate#renderBrief` writes and the dispatch-input gate
1009
+ * reads, so the dispatching instance must be built AFTER the brief lands — building
1010
+ * it earlier snapshots `briefPath: null` and refuses every dispatch. The `--recover`
1011
+ * abort fold (the takeover that precedes the stamp, spec §2.1④) therefore rides its
1012
+ * own throwaway instance in `#recoverRun`: it touches only the in-flight record and
1013
+ * the ledger, so a pre-brief instance is enough. */
995
1014
  #lifecycleOf(scene, parsed, artifacts) {
996
1015
  return new CliLifecycle({
997
1016
  env: process.env,
@@ -1008,6 +1027,8 @@ export class Cli {
1008
1027
  baseBranch: this.#baseBranchOf(scene),
1009
1028
  specLink: scene.specLink,
1010
1029
  overallLink: scene.overallLink,
1030
+ program: scene.program,
1031
+ docType: scene.docType,
1011
1032
  },
1012
1033
  reviews: parsed.paths.reviews,
1013
1034
  // The explicit takeover flag (`--recover`): the ONLY path that displaces a
@@ -1019,8 +1040,13 @@ export class Cli {
1019
1040
  }
1020
1041
  /** The branch scope anchor (BASE_BRANCH) — the base artifact's branch name read
1021
1042
  * from the line's own workspace (`base.json`, the same `base get` source the CLI
1022
- * writes). "" when the artifact is absent or malformed (the slot stays empty and
1023
- * the assembler drops it — the wave/branch review then judges the live tree). */
1043
+ * writes). "" when the artifact is absent or malformed.
1044
+ *
1045
+ * WAS: the empty slot was dropped and the wave / branch review silently fell back
1046
+ * to judging the live tree. NOW: P38 §2.3 reversal ④ — `BASE_BRANCH` is required on
1047
+ * every wave / branch face, so an empty value is `empty-value` at the
1048
+ * dispatch-input gate: the round stops before the child exists (the recovery is
1049
+ * `cdd base set`, the orchestrator's action, never the gate's). */
1024
1050
  #baseBranchOf(scene) {
1025
1051
  const name = this.#matrix.render({ domain: "workspace", tasks: null }, "base");
1026
1052
  const read = scene.workspace.readJson(name);
@@ -1282,6 +1308,12 @@ export class Cli {
1282
1308
  briefPath: null,
1283
1309
  specLink,
1284
1310
  overallLink,
1311
+ // P38 §2.1 — the two DECLARED cells the dispatch-input gate reads instead of
1312
+ // parsing a document at dispatch: the identity document's `program:` literal
1313
+ // and its `doc-type:` shape, taken from the SAME index entry `specLink` and
1314
+ // `overallLink` were resolved from (one read, three facts).
1315
+ program: specDoc?.program ?? null,
1316
+ docType: specDoc?.docType ?? null,
1285
1317
  },
1286
1318
  artifacts,
1287
1319
  };
@@ -168,7 +168,7 @@ export const CLI_COMMANDS = [
168
168
  {
169
169
  name: "fix",
170
170
  description: "fix review findings — wave | branch | phase-spec | overall | plan | single-spec",
171
- example: "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
171
+ example: "cdd fix --type wave --tasks 1 --reviews .kairos/cdd/<slug>/tasks-1-review-1.json",
172
172
  keys: [
173
173
  { key: "type", required: true },
174
174
  { key: "tasks" },
@@ -19,6 +19,7 @@ import path from "node:path";
19
19
  import process from "node:process";
20
20
  import { printParseErrorCode } from "jsonc-parser";
21
21
  import { CompletionCriteria, FixDispositions } from "../contract/completion-criterion.js";
22
+ import { NodeFs } from "../contract/invariants.js";
22
23
  import { PinAudit } from "../contract/pins.js";
23
24
  import { regradeNote } from "../contract/review-criteria.js";
24
25
  import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
@@ -131,6 +132,10 @@ export class CliLifecycle {
131
132
  /** The pin gate of this dispatch (P37 §7.2) — built on first use so the resolution
132
133
  * index is walked once per process, never once per read. */
133
134
  #pinIndex = null;
135
+ /** The existence read of the dispatch-input gate (P38 §2.1) — the ONE fact the
136
+ * `target-absent` reason takes from the filesystem. Injected like `git` / `proc` /
137
+ * `env` so a test judges the gate without touching the real tree. */
138
+ #fs;
134
139
  constructor(opts) {
135
140
  this.#env = opts.env ?? process.env;
136
141
  this.#scene = opts.scene;
@@ -144,6 +149,7 @@ export class CliLifecycle {
144
149
  this.#sync = opts.sync ?? new Terminator();
145
150
  this.#template = opts.template ?? new TemplateAssembler();
146
151
  this.#brief = opts.brief ?? new BriefRenderer();
152
+ this.#fs = opts.fs ?? new NodeFs();
147
153
  this.#words = opts.words ?? new Words();
148
154
  this.#io = opts.io ?? {
149
155
  stdout: (t) => process.stdout.write(t),
@@ -545,8 +551,10 @@ export class CliLifecycle {
545
551
  // the child, so a tampered input never reaches a child (the read-back and the CLI
546
552
  // catch are the fallbacks, never the gate). It runs BEFORE the ruling gate: the
547
553
  // integrity diagnostic is the fact, and a sidecar judged against tampered bytes
548
- // would name a ruling reason for a carrier whose bytes simply changed.
549
- const carrierRefusal = this.#carrierRefusal(frame);
554
+ // would name a ruling reason for a carrier whose bytes simply changed. It also runs
555
+ // before the dispatch-input gate below — the FIRST of the three pre-dispatch
556
+ // judgments, and the order the `--dry-run` face mirrors.
557
+ const carrierRefusal = this.carrierRefusal(frame);
550
558
  if (carrierRefusal !== null) {
551
559
  this.#sealRoundCarriers(frame);
552
560
  this.#blocked(carrierRefusal, false);
@@ -559,13 +567,27 @@ export class CliLifecycle {
559
567
  // round-context cell), so the `misplaced` / `invalid` / `ok` answers can never
560
568
  // disagree between them — not even across a writer that lands mid-dispatch.
561
569
  const artifactCell = this.#artifactCellOf(frame);
570
+ // P38 §2.1 — the dispatch-input gate: does this round stand at all (every required
571
+ // cell supplied, every read path on disk)? It runs BEFORE the artifact gate, which
572
+ // judges the quality of those inputs. The values are composed ONCE here and read by
573
+ // both the gate and the prompt render: one value, two consumers, never two
574
+ // compositions that could answer differently.
575
+ const values = this.#valuesOf(frame, artifactCell);
576
+ const inputRefusal = this.#inputRefusalOf(values, frame, "dispatch");
577
+ if (inputRefusal !== null) {
578
+ // Same exit shape as the two gates beside it: the preflight already opened this
579
+ // round's own two names, so a refusal seals them before it blocks.
580
+ this.#sealRoundCarriers(frame);
581
+ this.#blocked(inputRefusal, false);
582
+ return { status: "BLOCKED", violations: [RoundViolation.hard(inputRefusal)] };
583
+ }
562
584
  const artifactRefusal = this.#artifactRefusalOf(artifactCell);
563
585
  if (artifactRefusal !== null) {
564
586
  this.#sealRoundCarriers(frame);
565
587
  this.#blocked(artifactRefusal, false);
566
588
  return { status: "BLOCKED", violations: [RoundViolation.hard(artifactRefusal)] };
567
589
  }
568
- const prompt = this.#template.render(this.#valuesOf(frame, artifactCell));
590
+ const prompt = this.#template.render(values);
569
591
  const row = HOSTS[host];
570
592
  const cliName = row.cli;
571
593
  const args = [...row.invoke.split(" ").filter((part) => part.length > 0)];
@@ -800,8 +822,10 @@ export class CliLifecycle {
800
822
  * environment · BASE_BRANCH scope anchor). Every declared token supplied — a mode's
801
823
  * non-consumed slots stay empty and are NOT emitted by the assembler
802
824
  * (empty-valued keys are dropped), so each mode's round context carries only the
803
- * facts the mode reads. The review criteria/lens are NOT values — they fold into
804
- * the review type's fixed prefix (§3.7). */
825
+ * facts the mode reads — with the one declared exception: the `INPUT_RULINGS` cell
826
+ * is `absent: "none"`, so its line is always present and an empty value renders the
827
+ * bare literal `none` (§2.3 reversal ③). The review criteria/lens are NOT values —
828
+ * they fold into the review type's fixed prefix (§3.7). */
805
829
  #valuesOf(frame, artifactCell) {
806
830
  const scene = this.#scene;
807
831
  const op = this.#opOf(frame);
@@ -831,8 +855,11 @@ export class CliLifecycle {
831
855
  // from the REVIEWED carrier's identity and the strict schema read composed beside
832
856
  // it (`#artifactReadOf`), handed in as the dispatch's ONE judgment: the gate that
833
857
  // just approved this dispatch and this slot are the same value, never two reads.
834
- // An absent, unattributable or refused sidecar leaves the slot empty and the
835
- // assembler drops the line.
858
+ // WAS: an absent, unattributable or refused sidecar left the slot empty and the
859
+ // assembler dropped the line. NOW: P38 §2.3 reversal ③ — the cell is declared
860
+ // `absent: "none"`, so the line is always present and an empty value renders the
861
+ // bare literal `none` (the round reads "no ruling was recorded" instead of a
862
+ // missing row).
836
863
  INPUT_RULINGS: this.#rulingsInputOf(artifactCell),
837
864
  // The kind-named judged-doc anchors (the semantic retirement of the generic
838
865
  // INPUT_DOC): the plan line carries the plan document as its judged doc
@@ -863,7 +890,11 @@ export class CliLifecycle {
863
890
  // line's ONE charter anchor (the judged charter itself); the phase-spec line
864
891
  // carries its own `program:`; plan / branch / wave carry the same-slug identity
865
892
  // doc's `program:` (the wave arm landed at P37 §4.1); empty off those faces and
866
- // when the named program is absent (the assembler drops the empty slot).
893
+ // when the named program is absent. WAS: that empty value always dropped the
894
+ // slot. NOW: P38 §2.3 reversal ① — where the `program:` arm hits, the empty value
895
+ // is `target-absent` at the dispatch-input gate (the declaration names a charter
896
+ // that did not resolve); the drop remains only on the faces the cell does not
897
+ // serve (the `overall`-only arm).
867
898
  INPUT_OVERALL: frame.type === "overall"
868
899
  ? this.#rel(docPath ?? "")
869
900
  : frame.type === "phase-spec" ||
@@ -1300,10 +1331,13 @@ export class CliLifecycle {
1300
1331
  * same-cycle review record's carrier identity through the ledger's ONE accessor
1301
1332
  * (the recorded path, then the read ladder a pre-P31 row needs), or the ledger's
1302
1333
  * resolved family name when the line records no review for this cycle. A record
1303
- * that resolves no carrier reads `null` — the UNRECORDED face, which the criterion
1304
- * books as a visible skip instead of failing the round on a hard absent-carrier
1305
- * refusal. Record-present means the record's own final wins: a draft sitting beside
1306
- * it never becomes the judged input. */
1334
+ * that resolves no carrier reads `null`. Record-present means the record's own final
1335
+ * wins: a draft sitting beside it never becomes the judged input.
1336
+ *
1337
+ * WAS: a `null` here was the UNRECORDED face, which the criterion booked as a visible
1338
+ * skip and the fix round dispatched without a review input. NOW: P38 §2.3 reversal ② —
1339
+ * `INPUT_REVIEWS` is `always`-required, so that value is `empty-value` at the
1340
+ * dispatch-input gate and the round stops before the child exists. */
1307
1341
  #reviewsPath(frame) {
1308
1342
  if (this.#reviews !== null)
1309
1343
  return this.#reviews;
@@ -1347,8 +1381,15 @@ export class CliLifecycle {
1347
1381
  * sidecar seam (`session/artifact-reads.ts`), BY DESIGN: this one feeds the digest
1348
1382
  * read of the carrier's own bytes, that one feeds the schema's `carrier` comparison
1349
1383
  * and the sidecar's id set. The two are different reads of different files, not two
1350
- * names for one fact. */
1351
- #carrierRefusal(frame) {
1384
+ * names for one fact.
1385
+ *
1386
+ * A PURE read, so it is also the `--dry-run` face's first pre-dispatch entry, beside
1387
+ * `inputRefusal` / `artifactRefusal` and in the order `#runDispatch` applies the three
1388
+ * (carrier-integrity → dispatch-input → artifact-identity): the preview renders the
1389
+ * returned reason verbatim, so a dry run can never forecast a dispatch the real run
1390
+ * would refuse — the tampered carrier included, whichever other gate the frame also
1391
+ * fails. */
1392
+ carrierRefusal(frame) {
1352
1393
  if (this.#opOf(frame) !== "fix")
1353
1394
  return null;
1354
1395
  const carrier = this.#reviewsPath(frame);
@@ -1375,7 +1416,9 @@ export class CliLifecycle {
1375
1416
  }
1376
1417
  /** The fix round's ruling sidecar as the round-context value — the repo-relative
1377
1418
  * sidecar path alone, the empty string otherwise (off the fix face and when the
1378
- * sidecar is absent — the assembler drops the empty line).
1419
+ * sidecar is absent). WAS: the empty value made the assembler drop the whole line.
1420
+ * NOW: P38 §2.3 reversal ③ — the cell is declared `absent: "none"`, so the line is
1421
+ * always present and an empty value renders the bare literal `none`.
1379
1422
  *
1380
1423
  * One input, one reading: the round context names WHERE the rulings live, exactly as
1381
1424
  * `INPUT_REVIEWS` names the carrier it qualifies (spec §2.10). The ruling bodies stay
@@ -1401,6 +1444,89 @@ export class CliLifecycle {
1401
1444
  artifactRefusal(frame) {
1402
1445
  return this.#artifactRefusalOf(this.#artifactCellOf(frame));
1403
1446
  }
1447
+ /** The `dispatch-input` gate as a PURE read (P38 §2.1) — whether THIS round can stand
1448
+ * at all: every cell its layout requires was supplied, and every read path it names
1449
+ * is on disk. It sits beside `artifactRefusal` for the same reason (one judgment, two
1450
+ * consumers): the `--dry-run` face renders this answer verbatim, so a preview can
1451
+ * never forecast a dispatch the real run would refuse. Nothing here writes and no
1452
+ * document is parsed at dispatch — exigibility reads the two DECLARED scene cells.
1453
+ *
1454
+ * `mode` defaults to `dispatch`: the preview's one weaker arm (`preview: satisfied`)
1455
+ * must be asked for by name, so no caller silently takes it. */
1456
+ inputRefusal(frame, mode = "dispatch") {
1457
+ return this.#inputRefusalOf(this.#valuesOf(frame, this.#artifactCellOf(frame)), frame, mode);
1458
+ }
1459
+ /** The dispatch-input judgment over the values about to be rendered (§2.1–§2.3) — the
1460
+ * definition is given by the declaration, never by a second table: the judged cells
1461
+ * are `layoutOf(values)`, the same row selection the renderer reads. Every failing
1462
+ * cell becomes one segment, all of them reported in one pass (`; `-joined), so a
1463
+ * refused round is repaired once instead of one cell per dispatch. */
1464
+ #inputRefusalOf(values, frame, mode) {
1465
+ const row = values.ROLE;
1466
+ const segments = [];
1467
+ for (const decl of this.#template.layoutOf(values)) {
1468
+ const token = TemplateAssembler.slotOf(decl.line);
1469
+ if (token === undefined)
1470
+ continue;
1471
+ const hits = decl.requiredOn.filter((arm) => this.#armHits(arm, frame));
1472
+ if (hits.length === 0)
1473
+ continue;
1474
+ const satisfied = mode === "preview" && this.#answeredByNaming(decl, token, frame);
1475
+ const value = values[token] ?? "";
1476
+ if (value === "") {
1477
+ if (satisfied)
1478
+ continue;
1479
+ segments.push({ row, token, reason: _a.#emptyReasonOf(hits) });
1480
+ continue;
1481
+ }
1482
+ if (decl.path !== true || satisfied)
1483
+ continue;
1484
+ // The value is a repoRoot-relative read path (§1.1) — the ONE erasure point turns
1485
+ // it absolute before the existence read, so a dispatch started from a subdirectory
1486
+ // never reads every landed path as absent.
1487
+ const absolute = this.#repoRootValue().resolve(value);
1488
+ if (!this.#fs.exists(absolute))
1489
+ segments.push({ row, token, reason: "target-absent" });
1490
+ }
1491
+ return segments.length === 0 ? null : this.#words.dispatchInput({ segments });
1492
+ }
1493
+ /** Whether one declared arm is exigible on this frame (§1.3) — the type hit plus, when
1494
+ * the arm carries one, its structural precondition. Both preconditions read the two
1495
+ * DECLARED scene cells (`program` · `docType`), never the resolved links: a declared
1496
+ * program whose charter does not resolve and a program never declared are different
1497
+ * facts, and only the declaration can tell them apart. */
1498
+ #armHits(arm, frame) {
1499
+ const typed = arm.types === "always" || arm.types.includes(frame.type);
1500
+ if (!typed)
1501
+ return false;
1502
+ if (arm.when === "program")
1503
+ return this.#scene.program != null;
1504
+ if (arm.when === "identity")
1505
+ return this.#scene.docType != null;
1506
+ return true;
1507
+ }
1508
+ /** The reason an exigible cell's EMPTY value earns (§2.2's closed set): an arm whose
1509
+ * precondition is the declared `program:` that hit means the charter the declaration
1510
+ * names did not resolve (`target-absent`); every other empty value is the engine's own
1511
+ * omission (`empty-value`). The two `when` legs are told apart by this word alone. */
1512
+ static #emptyReasonOf(hits) {
1513
+ return hits.some((arm) => arm.when === "program") ? "target-absent" : "empty-value";
1514
+ }
1515
+ /** Whether the preview's `satisfied` answer applies to this cell (§2.4) — the ONLY
1516
+ * reader of `preview: "satisfied"`. The naming line that writes this cell's artifact
1517
+ * is the answer's source: the brief is the one cell `renderBrief` writes at dispatch
1518
+ * alone, so a wave that names its task group names its brief, and a wave that names
1519
+ * none falls back to the empty-value arm. The exemption covers the existence leg too:
1520
+ * a preview never asks a file it would not write. The token guard is the second half
1521
+ * of one rule: the assembler refuses any OTHER cell declaring `satisfied` at
1522
+ * construction (#assertPreviewAnswer), so a declaration the naming row cannot answer
1523
+ * never reaches a preview. */
1524
+ #answeredByNaming(decl, token, frame) {
1525
+ if (decl.preview !== "satisfied" || token !== TemplateAssembler.NAMED_BRIEF_CELL)
1526
+ return false;
1527
+ const tasks = frame.params.tasks ?? "";
1528
+ return tasks !== "" && this.#naming.briefName(tasks) !== "";
1529
+ }
1404
1530
  /** The dispatch's artifact judgment — computed ONCE, then consumed by the gate and by
1405
1531
  * the prompt's round-context cell. Off the fix face there is nothing to read (no
1406
1532
  * requesting carrier, no sidecar), so the cell is the no-sidecar value; otherwise the
@@ -1748,11 +1874,15 @@ export class CliLifecycle {
1748
1874
  return `cdd review --type ${frame.type} --spec ${this.#docOf(frame)}`;
1749
1875
  case "fix": {
1750
1876
  // The `--reviews` input is the SAME carrier the fix prompt names (P31 §2.3): one
1751
- // four-layer resolution, never a second family spelling spliced here. The
1752
- // fallback fires only when the recorded face resolves to `null` (a legacy record
1753
- // with no carrier on disk) — the never-null guard keeps a command shape, and
1754
- // `#reviewFamilyPath` is the one home of the cycle-only rule (§2.10): a fix
1755
- // retried at attempt 2 would otherwise ask for a `-a2` name review never wrote.
1877
+ // four-layer resolution, never a second family spelling spliced here. The `??`
1878
+ // arm is a DEFENSIVE never-taken guard that keeps the command a string: the shape
1879
+ // it would cover — a recorded cycle whose carrier resolves to `null` (a legacy
1880
+ // record with no carrier on disk) — is refused by the dispatch-input gate as
1881
+ // `INPUT_REVIEWS · empty-value` before any command exists (P38 §2.3 reversal ②),
1882
+ // and the composed-but-absent sibling is refused there as `target-absent`. If
1883
+ // `#reviewsPath` ever answers `null` again, `#reviewFamilyPath` is the one home of
1884
+ // the cycle-only rule (§2.10): a fix retried at attempt 2 would otherwise ask for
1885
+ // a `-a2` name review never wrote.
1756
1886
  const findings = this.#reviewsPath(frame) ?? this.#reviewFamilyPath(frame);
1757
1887
  const target = frame.target.kind === "plan"
1758
1888
  ? `--plan ${frame.target.doc}`
@@ -78,10 +78,12 @@ export class Preview {
78
78
  lines.push(this.#words.inFlightWords().corruptLocked);
79
79
  return lines;
80
80
  }
81
- /** The read-only artifact-identity block — the dispatch gate REFUSED this dispatch
82
- * (`misplaced` sidecar / unreadable one / a schema violation), so the preview prints
83
- * the gate's OWN reason verbatim: one read, two faces, and a dry run can never
84
- * forecast a dispatch the real run would refuse. Exit 1 at the caller; nothing is
81
+ /** The read-only refusal block for a pre-dispatch gate — one of the three the real
82
+ * dispatch applies before the round exists REFUSED this dispatch (a `carrier-mismatch`
83
+ * on a tampered requesting carrier; a dispatch-input cell the frame requires but left
84
+ * empty or absent; a `misplaced` sidecar / unreadable one / a schema violation), so the
85
+ * preview prints the gate's OWN reason verbatim: one read, two faces, and a dry run can
86
+ * never forecast a dispatch the real run would refuse. Exit 1 at the caller; nothing is
85
87
  * written, moved or deleted (the repair is the orchestrator's). */
86
88
  artifactBlock(verb, reason) {
87
89
  const [head, ...sections] = reason.split("\n");
@@ -129,6 +129,15 @@ export const CAPSULE_WORDS = {
129
129
  * spec §3.3): the round still concludes, and this line names what was booked.
130
130
  * Fill slot: {message}. */
131
131
  softViolation: "round soft violation: {message}",
132
+ /** The `dispatch-input` refusal rows (P38 §2.2) — the station word, the one segment
133
+ * template (`{row} · {token} · {reason}`) and the segment separator. One line names
134
+ * every failing cell, so a refused round is repaired in one pass instead of one
135
+ * cell per dispatch. */
136
+ dispatchInput: {
137
+ station: "dispatch-input",
138
+ segment: "{row} · {token} · {reason}",
139
+ separator: "; ",
140
+ },
132
141
  /** The `misplaced = block` report (spec §2.4) — the reason word plus the four
133
142
  * sections: the rendered name, every name found in its place, the identity itself
134
143
  * and the repair the orchestrator owns. Fill slots: {kind} / {derived} /
@@ -354,6 +363,18 @@ export class Words {
354
363
  softViolation(message) {
355
364
  return CAPSULE_WORDS.softViolation.replace("{message}", message);
356
365
  }
366
+ /** The `dispatch-input` refusal (P38 §2.2) — the station word plus every failing
367
+ * cell's segment, `; ` between segments and ` · ` inside one. The `CDD_BLOCKED: `
368
+ * prefix is the block channel's, never this row's, so a dry-run consumer and a real
369
+ * dispatch read the same bytes. */
370
+ dispatchInput(facts) {
371
+ const row = CAPSULE_WORDS.dispatchInput;
372
+ const segments = facts.segments.map((segment) => row.segment
373
+ .replace("{row}", segment.row)
374
+ .replace("{token}", segment.token)
375
+ .replace("{reason}", segment.reason));
376
+ return [row.station, segments.join(row.separator)].join(CAPSULE_WORDS.separator);
377
+ }
357
378
  /** The `misplaced = block` report (spec §2.4) — the reason word over the four
358
379
  * fact sections. Every candidate is printed (never a first pick) and the identity
359
380
  * section is the SAME identity the rendered name came from, so `derived:` and
@@ -48,6 +48,7 @@
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;
51
52
  import { CRITERIA, LENS_QUESTIONS } from "../contract/review-criteria.js";
52
53
  import { DISPATCH } from "../face/host.js";
53
54
  import { TerminationPolicy } from "../face/termination.js";
@@ -57,6 +58,15 @@ const FRAME_ITEMS = [
57
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.",
58
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.",
59
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.";
60
70
  /** The shared work-mode tail cell — the evidence gate (implement/fix carry it;
61
71
  * docs-fix carries no evidence file — zero per-mode duplication, §3.7). The
62
72
  * evidence file's concrete name rides the injected schema's preamble (per-family
@@ -108,6 +118,7 @@ const IMPLEMENT_SHELL = [
108
118
  WORK_CAPABILITY,
109
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).`,
110
120
  EVIDENCE_ITEM,
121
+ SCRATCH_DISCIPLINE,
111
122
  ...LICENSE_ITEMS,
112
123
  ...SCHEMA_SECTION,
113
124
  ];
@@ -115,7 +126,7 @@ const IMPLEMENT_SHELL = [
115
126
  * names where the orchestrator's rulings live and what they outrank; the SIDECAR PATH
116
127
  * itself rides the round context (`INPUT_RULINGS`), never this sentence. Both fix
117
128
  * shells carry the same words: one reading, one meaning. */
118
- 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.";
119
130
  /** The fix row's fixed prefix — header + instructions + the shared work tail. */
120
131
  const FIX_TYPED_INSTRUCTIONS = [
121
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.",
@@ -134,6 +145,7 @@ const FIX_SHELL = [
134
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.',
135
146
  RULINGS_READING,
136
147
  EVIDENCE_ITEM,
148
+ SCRATCH_DISCIPLINE,
137
149
  ...LICENSE_ITEMS,
138
150
  // T5 (v0.3) — The work plane's ONE strict-schema sentence: every top-level draft
139
151
  // field comes from the `## Handoff schema` declared properties (the fields'
@@ -160,6 +172,7 @@ const DOCS_FIX_SHELL = [
160
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.",
161
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.',
162
174
  RULINGS_READING,
175
+ SCRATCH_DISCIPLINE,
163
176
  ...LICENSE_ITEMS,
164
177
  // The generic strict-schema sentence — the SAME one the work shells carry: the
165
178
  // injected declaration is the draft's single field source, zero per-mode field
@@ -168,93 +181,280 @@ const DOCS_FIX_SHELL = [
168
181
  ...SCHEMA_SECTION,
169
182
  ];
170
183
  /** The review variants' shared instruction text — the review's mode rule (the
171
- * criteria body + the lens vocabulary ride per-type fixed items below). */
172
- 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: [] }];
173
194
  /** The review mode's shared reduced tail — the only dynamic region of every review
174
195
  * variant (the criteria/lens are fixed-prefix per type, never here). Each review
175
196
  * type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan →
176
197
  * `INPUT_PLAN` as the judged doc, with `INPUT_SPEC` as its plan→spec conformance
177
198
  * reference; branch → the live tree against `BASE_BRANCH`, with `INPUT_PLAN` as its
178
199
  * plan-conformance reference and the same `INPUT_SPEC` design-spec reference; spec →
179
- * `INPUT_SPEC`; overall → `INPUT_OVERALL`); empty slots are dropped by the
180
- * 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. */
181
202
  const REVIEW_CONTEXT = [
182
- "## Round context",
183
- "",
184
- "- `ROLE`: {{ROLE}}",
185
- "- `TARGET_TYPE`: {{TARGET_TYPE}}",
186
- "- `WAVE`: {{WAVE}}",
187
- "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
188
- "- `INPUT_PLAN`: {{INPUT_PLAN}}",
189
- "- `INPUT_SPEC`: {{INPUT_SPEC}}",
190
- "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
191
- "- `BASE_BRANCH`: {{BASE_BRANCH}}",
192
- "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
193
- "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
194
- "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
195
- "- `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" }] },
196
264
  ];
197
265
  /** The work-mode dispatch rows — implement / fix / docs-fix (§3.5; the review rows
198
- * 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. */
199
269
  const MODE_PROMPTS = {
200
270
  implement: {
201
271
  mode: "implement",
202
272
  shell: IMPLEMENT_SHELL,
273
+ serves: ["wave"],
203
274
  roundContext: [
204
- "## Round context",
205
- "",
206
- "- `ROLE`: {{ROLE}}",
207
- "- `WAVE`: {{WAVE}}",
208
- "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
209
- // find #4 + #5 — the plan's ## Constraints rides the wave brief mirror;
210
- // the OUTPUT_* write paths are prescribed (the {family}-{key}- canonical names)
211
- "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
212
- "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
213
- "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
214
- "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
215
- "- `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
+ },
216
311
  ],
217
312
  },
218
313
  fix: {
219
314
  mode: "fix",
220
315
  shell: FIX_SHELL,
316
+ serves: ["wave", "branch"],
221
317
  roundContext: [
222
- "## Round context",
223
- "",
224
- "- `ROLE`: {{ROLE}}",
225
- "- `TARGET_TYPE`: {{TARGET_TYPE}}",
226
- "- `WAVE`: {{WAVE}}",
227
- "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
228
- "- `INPUT_PLAN`: {{INPUT_PLAN}}",
229
- "- `INPUT_SPEC`: {{INPUT_SPEC}}",
230
- "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
231
- "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
232
- "- `INPUT_RULINGS`: {{INPUT_RULINGS}}",
233
- "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
234
- "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
235
- "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
236
- "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
237
- "- `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
+ },
238
389
  ],
239
390
  },
240
391
  "docs-fix": {
241
392
  mode: "docs-fix",
242
393
  shell: DOCS_FIX_SHELL,
394
+ serves: ["phase-spec", "single-spec", "plan", "overall"],
243
395
  roundContext: [
244
- "## Round context",
245
- "",
246
- "- `ROLE`: {{ROLE}}",
247
- "- `TARGET_TYPE`: {{TARGET_TYPE}}",
248
- "- `WAVE`: {{WAVE}}",
249
- "- `INPUT_PLAN`: {{INPUT_PLAN}}",
250
- "- `INPUT_SPEC`: {{INPUT_SPEC}}",
251
- "- `INPUT_OVERALL`: {{INPUT_OVERALL}}",
252
- "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
253
- "- `INPUT_RULINGS`: {{INPUT_RULINGS}}",
254
- "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
255
- "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
256
- "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
257
- "- `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
+ },
258
458
  ],
259
459
  },
260
460
  };
@@ -398,6 +598,16 @@ export const pinLensOf = (type, guides = REVIEWS) => {
398
598
  }
399
599
  return row.pinLens;
400
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
+ ];
401
611
  /** One review variant row (§3.7) — the fixed prefix folds the SELECTED criteria
402
612
  * body + its lens INLINE (the `INPUT_CRITERIA`/`INPUT_LENS` round-context tokens
403
613
  * are gone) and shares the REVIEW_CONTEXT dynamic tail. The target word labels the
@@ -419,6 +629,7 @@ const reviewRow = (type) => {
419
629
  ...LICENSE_ITEMS,
420
630
  ...SCHEMA_SECTION,
421
631
  ],
632
+ serves: REVIEW_SERVES,
422
633
  roundContext: REVIEW_CONTEXT,
423
634
  };
424
635
  };
@@ -491,7 +702,16 @@ export const CLAUSES = {
491
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.",
492
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.",
493
704
  };
494
- /** The dispatch-prompt data plane — the typed template-contract surface. $version 24
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
495
715
  * names the wave line in the fix shell's anchor clause (P37 §4.1): the wave line now
496
716
  * carries the same `INPUT_SPEC` conformance reference and the `INPUT_OVERALL` parent
497
717
  * charter as the branch line, so the clause a maintainer reads can no longer
@@ -558,7 +778,7 @@ export const CLAUSES = {
558
778
  * prose return contract (`RETURN_PROSE` — nothing downstream parses the child's
559
779
  * stdout), and the per-type review criterion shells. */
560
780
  export const TEMPLATE_PROMPT = {
561
- $version: 24,
781
+ $version: 25,
562
782
  modes: MODE_PROMPTS,
563
783
  reviews: REVIEW_VARIANTS,
564
784
  return: RETURN_ZONE,
@@ -570,14 +790,26 @@ export const WORK_MODES = ["implement", "fix", "review", "docs-fix"];
570
790
  /**
571
791
  * The template assembler — the ONE renderer over the typed template-prompt data
572
792
  * plane. Construction reads the typed contract (the module's declared data —
573
- * no file reads, no second copy). render(values) selects the row by the ROLE value
574
- * (the review mode by ROLE + TARGET_TYPE) — the row's fixed prefix + the single
575
- * 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.
576
801
  */
577
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";
578
809
  #contract;
579
- constructor() {
580
- this.#contract = TEMPLATE_PROMPT;
810
+ constructor(contract = TEMPLATE_PROMPT) {
811
+ this.#contract = contract;
812
+ this.#assertDeclarations();
581
813
  }
582
814
  /** The tokens the contract declares (the union across every mode — all zones). */
583
815
  declaredTokens() {
@@ -587,18 +819,22 @@ export class TemplateAssembler {
587
819
  workModes() {
588
820
  return WORK_MODES;
589
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
+ }
590
828
  /** Assemble the full dispatch template for a role with the slot values — the
591
- * row's fixed prefix + the single return contract + its reduced round context
592
- * (empty-value keys omitted). */
829
+ * row's fixed prefix + the single return contract + its declared round context. */
593
830
  render(values) {
594
831
  this.#gate(values);
595
- const row = this.#rowOf(values);
596
- const zones = {
597
- shell: this.#joinLines(row.shell),
598
- return: this.#joinLines(this.#contract.return.RETURN_PROSE),
599
- "round-context": this.#contextLines(row, values),
600
- };
601
- 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);
602
838
  }
603
839
  #joinLines(lines) {
604
840
  return lines.join("\n");
@@ -619,23 +855,125 @@ export class TemplateAssembler {
619
855
  }
620
856
  return row;
621
857
  }
622
- /** The reduced round-context section — the row's subset, a key whose value is
623
- * empty omitted (only present facts land in the dynamic region). */
624
- #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) {
625
864
  const lines = [];
626
- for (const line of row.roundContext) {
627
- const slot = line.match(/\{\{([A-Z0-9_]+)\}\}/)?.[1];
628
- if (slot !== undefined && values[slot] === "")
629
- continue;
630
- 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"));
631
873
  }
632
874
  return lines.join("\n");
633
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
+ }
634
972
  /** The hard gates — a known ROLE (+ its TARGET_TYPE for reviews), every declared
635
973
  * token supplied (empty allowed — a mode's non-consumed slots are legitimately
636
- * empty and merely not emitted), no undeclared values, the single return
637
- * contract declared, and every round-context name the mode's shell prose
638
- * 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. */
639
977
  #gate(values) {
640
978
  const role = values.ROLE;
641
979
  const row = role === undefined
@@ -659,26 +997,6 @@ export class TemplateAssembler {
659
997
  throw new Error(`template value provided for undeclared token ${name}`);
660
998
  }
661
999
  }
662
- this.#assertShellLayout(row);
663
- }
664
- /** The shell↔layout consistency assertion (§3.6): every round-context name the
665
- * mode's shell prose references (`INPUT_*` / `OUTPUT_*` / `BASE_BRANCH`) must be
666
- * carried by that mode's round-context layout ∪ the shared return tail — a shell
667
- * claiming a slot its layout never carries is a construction error. This closes
668
- * the "claimed but not carried" blind spot the token gates cannot see (the shell
669
- * prose is not `{{slot}}`-templated). */
670
- #assertShellLayout(row) {
671
- const naming = /\b(?:INPUT_[A-Z0-9_]+|OUTPUT_[A-Z0-9_]+|BASE_BRANCH)\b/g;
672
- const namesOf = (text) => text.match(naming) ?? [];
673
- const allowed = new Set([
674
- ...row.roundContext.flatMap((line) => namesOf(line)),
675
- ...namesOf(this.#joinLines(this.#contract.return.RETURN_PROSE)),
676
- ]);
677
- for (const name of new Set(namesOf(this.#joinLines(row.shell)))) {
678
- if (!allowed.has(name)) {
679
- throw new Error(`template mode ${row.mode} shell references ${name} not carried by its round context`);
680
- }
681
- }
682
1000
  }
683
1001
  /** The review variant of a TARGET_TYPE (verified in the gate). */
684
1002
  #reviewRow(values) {
@@ -709,3 +1027,4 @@ export class TemplateAssembler {
709
1027
  });
710
1028
  }
711
1029
  }
1030
+ _a = TemplateAssembler;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oscaner-skills/cdd-engine",
3
- "version": "4.14.0",
3
+ "version": "4.15.0",
4
4
  "description": "CDD engine CLIs: task runner, docs reviewer, branch reviewer, harness selector.",
5
5
  "type": "module",
6
6
  "engines": {