@oscaner-skills/cdd-engine 4.10.0 → 4.12.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.
@@ -62,17 +62,21 @@ const FRAME_ITEMS = [
62
62
  * prefix), never this fixed text. */
63
63
  const EVIDENCE_ITEM = "**Evidence gate:** write the test-evidence file at the prescribed `OUTPUT_EVIDENCE` path per the `test-evidence` schema in `## Handoff schema` — `command`/`exit_code`/`passed`/`warnings_count` + `typecheck` (`command`/`exit_code`/`passed`); `behavior_change` when applicable. Update the round's report after verification. Missing or schema-violating evidence → the engine rewrites the draft to `status: BLOCKED`. Reports, test output, diffs: files only, never the return.";
64
64
  /** The work plane's ONE capability declaration (design spec §7.3) — a dispatched
65
- * implement / fix / docs-fix round may amend the spec and plan CONTENT face,
65
+ * implement / fix / docs-fix round may amend the CONTENT face of the judged
66
+ * document — the phase-spec / single-spec / overall charter / plan families —
66
67
  * because the document authoring right is a prompt slot, never a carrier slot (it
67
68
  * is not in `CARRIER`, not in `PLANE_REQUIRED`, not in the frame and not in
68
69
  * `progress.json` — the gate judges the result, never the declaration). The
69
- * structure face (the plan's Task id set and any task's `DependsOn` set) belongs to
70
+ * declaration names the families in their own words: the freeze clause limits
71
+ * itself to this declared scope, so a docs-fix round on the charter can never read
72
+ * "amend the charter" beside "freeze the spec". The structure face (the plan's Task
73
+ * id set and any task's `DependsOn` set) belongs to
70
74
  * the orchestrator: the engine snapshots both faces at dispatch and compares them at
71
75
  * the close, so a round-internal structure edit judges the round hard. The docs-fix
72
76
  * row carries it too — a fix round on a spec / plan line IS docs-fix, so this is the
73
77
  * row the authorization has to reach. The review variants declare nothing — a review
74
78
  * is read-only. */
75
- const WORK_CAPABILITY = "**Capability — `capability: may.amend = content`:** this round may amend the spec's and the plan's content face (facts, file lists, steps, acceptance detail, cited line numbers). The structure face — the plan's Task id set and any task's `DependsOn` set — belongs to the orchestrator: the engine snapshots it at dispatch and compares it at the close, so changing it inside this round judges the round hard.";
79
+ const WORK_CAPABILITY = "**Capability — `capability: may.amend = content`:** this round may amend the judged document's content face — the phase-spec, single-spec, overall charter and plan families (facts, file lists, steps, acceptance detail, cited line numbers). The structure face — the plan's Task id set and any task's `DependsOn` set — belongs to the orchestrator: the engine snapshots it at dispatch and compares it at the close, so changing it inside this round judges the round hard.";
76
80
  /** The discipline-clause cells shared by every shell (the `{{> cl:…}}` partials
77
81
  * resolve from the single clause container — the same bytes, one per shell). */
78
82
  const LICENSE_ITEMS = [
@@ -120,7 +124,7 @@ const FIX_SHELL = [
120
124
  ...FRAME_ITEMS,
121
125
  WORK_CAPABILITY,
122
126
  ...FIX_TYPED_INSTRUCTIONS,
123
- "**fix:** read `INPUT_REVIEWS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_PLAN` on the plan/branch lines — the plan document; `INPUT_SPEC` on the spec line — the spec 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).",
127
+ "**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).",
124
128
  '**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.',
125
129
  EVIDENCE_ITEM,
126
130
  ...LICENSE_ITEMS,
@@ -143,7 +147,7 @@ const DOCS_FIX_SHELL = [
143
147
  "",
144
148
  ...FRAME_ITEMS,
145
149
  WORK_CAPABILITY,
146
- "**docs-fix:** apply `INPUT_REVIEWS` (all severities) directly to the judged doc — `INPUT_PLAN` on a plan-doc line, `INPUT_SPEC` on a spec-doc line — removing fixed findings; record the path in `artifacts.doc` and report the round in `status` (APPROVED once every finding is applied, else BLOCKED + the reason in `notes`). Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; retry = full re-run (idempotent).",
150
+ "**docs-fix:** apply `INPUT_REVIEWS` (all severities) directly to the judged doc — `INPUT_PLAN` on a plan-doc line (where `INPUT_SPEC` is the design reference, never edited here), `INPUT_SPEC` on a spec-doc line, `INPUT_OVERALL` on the overall line — removing fixed findings; record the path in `artifacts.doc` and report the round in `status` (APPROVED once every finding is applied, else BLOCKED + the reason in `notes`). Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; retry = full re-run (idempotent).",
147
151
  "**Change-history rows:** a new `## Change history` row bumps the front-matter `version:` in the same edit — the header version is the lineage's newest numeric version, and the two can never disagree.",
148
152
  "**Table cells:** never hard-wrap a table cell — a wrapped continuation parses as a row whose cell count disagrees with the header, and the lineage row it was meant to be stops registering.",
149
153
  "**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.",
@@ -157,16 +161,20 @@ const DOCS_FIX_SHELL = [
157
161
  ];
158
162
  /** The review variants' shared instruction text — the review's mode rule (the
159
163
  * criteria body + the lens vocabulary ride per-type fixed items below). */
160
- const REVIEW_ITEM = "**review:** review the criteria below against the reference face named in the round context. Wave reviews judge `INPUT_WAVE_BRIEF` (the complete plan mirror); the plan/branch reviews judge the plan at `INPUT_PLAN`, the spec review judges the spec at `INPUT_SPEC`, 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.";
164
+ 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.";
161
165
  /** The review mode's shared reduced tail — the only dynamic region of every review
162
166
  * variant (the criteria/lens are fixed-prefix per type, never here). Each review
163
- * type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan/branch
164
- * → `INPUT_PLAN`; spec → `INPUT_SPEC`); the branch review additionally carries
165
- * `BASE_BRANCH` (the scope anchor). Empty slots are dropped by the assembler. */
167
+ * type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan →
168
+ * `INPUT_PLAN` as the judged doc, with `INPUT_SPEC` as its plan→spec conformance
169
+ * reference; branch → the live tree against `BASE_BRANCH`, with `INPUT_PLAN` as its
170
+ * plan-conformance reference and the same `INPUT_SPEC` design-spec reference; spec →
171
+ * `INPUT_SPEC`; overall → `INPUT_OVERALL`); empty slots are dropped by the
172
+ * assembler, so a face renders only the anchors it reads. */
166
173
  const REVIEW_CONTEXT = [
167
174
  "## Round context",
168
175
  "",
169
176
  "- `ROLE`: {{ROLE}}",
177
+ "- `TARGET_TYPE`: {{TARGET_TYPE}}",
170
178
  "- `WAVE`: {{WAVE}}",
171
179
  "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
172
180
  "- `INPUT_PLAN`: {{INPUT_PLAN}}",
@@ -206,6 +214,7 @@ const MODE_PROMPTS = {
206
214
  "## Round context",
207
215
  "",
208
216
  "- `ROLE`: {{ROLE}}",
217
+ "- `TARGET_TYPE`: {{TARGET_TYPE}}",
209
218
  "- `WAVE`: {{WAVE}}",
210
219
  "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
211
220
  "- `INPUT_PLAN`: {{INPUT_PLAN}}",
@@ -227,6 +236,7 @@ const MODE_PROMPTS = {
227
236
  "## Round context",
228
237
  "",
229
238
  "- `ROLE`: {{ROLE}}",
239
+ "- `TARGET_TYPE`: {{TARGET_TYPE}}",
230
240
  "- `WAVE`: {{WAVE}}",
231
241
  "- `INPUT_PLAN`: {{INPUT_PLAN}}",
232
242
  "- `INPUT_SPEC`: {{INPUT_SPEC}}",
@@ -256,14 +266,14 @@ export const SEVERITY_RUBRIC = "Calibrate findings by real severity — not ever
256
266
  * `{artifact}` = the reviewed product's name; `{audience}` = the subject whose
257
267
  * expectation judges the artifact's silence. The two spec-shaped targets share the
258
268
  * ONE `spec` row, so their shared narrative body can never fork its vocabulary;
259
- * the charter's own wording rides its criteria body (the `REVIEWS.overall` row),
260
- * never a second vocabulary minted here. */
269
+ * the charter's own row reads charter / phase author — the completion of the P17
270
+ * `overall-spec` → `overall` rename, never a copy of the spec's vocabulary. */
261
271
  export const REVIEW_BODY_TEXT = {
262
272
  wave: { artifact: "artifact", audience: "user" },
263
273
  branch: { artifact: "artifact", audience: "user" },
264
274
  spec: { artifact: "spec", audience: "downstream author" },
265
275
  plan: { artifact: "plan", audience: "implementer" },
266
- overall: { artifact: "spec", audience: "downstream author" },
276
+ overall: { artifact: "charter", audience: "phase author" },
267
277
  };
268
278
  /** The filled severity rubric of one criteria body — the shared fragment with that
269
279
  * body's two slot values substituted. The parameter domain IS the `REVIEWS` key
@@ -288,7 +298,7 @@ export const CLOSED_WAVE_DISCIPLINE = "Closed waves are history: a finding on th
288
298
  * today's tree happens to have: a line number is not a pin, a prose count is the
289
299
  * guard's business, and a present-tense description of today's shape belongs to the
290
300
  * plan. Nothing gates the writing moment — the review is where a violation surfaces. */
291
- const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + 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 by module path + symbol name — a line number is not a pin; a count ("N places" · "N rows" · "N modules") must be stated as pinned by the named guard or test; a present-tense description of today's shape belongs to the plan — in a design spec a measurement input is a lens-tagged finding unless restated as a condition that must hold — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${CLOSED_WAVE_DISCIPLINE} ${guide}`;
301
+ const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + 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 by module path + symbol name — a line number is not a pin; a count ("N places" · "N rows" · "N modules") must be stated as pinned by the named guard or test; a present-tense description of today's shape belongs to the plan — in a design spec a measurement input is a lens-tagged finding unless restated as a condition that must hold — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance (phase-spec only — a single-spec carries no \`program:\` and no \`INPUT_OVERALL\`, and is not a phase) — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${CLOSED_WAVE_DISCIPLINE} ${guide}`;
292
302
  /** The charter's criteria body — the six things a program charter owns, and only
293
303
  * those. It carries none of the implementation-face evidence duty the narrative
294
304
  * body carries (running the repository's commands, pinning every claim): a charter
@@ -306,7 +316,7 @@ export const REVIEWS = {
306
316
  },
307
317
  branch: {
308
318
  lensEnum: ["standards", "spec", "buildability"],
309
- axesGuide: `Same four axes as task (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.`,
319
+ 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.`,
310
320
  },
311
321
  spec: {
312
322
  lensEnum: ["completeness", "consistency", "clarity"],
@@ -377,8 +387,8 @@ const RETURN_ZONE = {
377
387
  /** The token registry — the union across every mode's round context + the shell's
378
388
  * schema slot (the v1.8 normalized vocabulary; the assembly face supplies every
379
389
  * declared slot, empty where the mode does not consume it — the round-context
380
- * renderer drops the empty-valued lines). REVIEW_TYPE is the review-mode row
381
- * selector (supplied but never rendered). */
390
+ * renderer drops the empty-valued lines). TARGET_TYPE is the target discriminant:
391
+ * it selects the review row AND renders on every targeted face. */
382
392
  const TOKENS = [
383
393
  { name: "BASE_BRANCH", zone: "round-context" },
384
394
  { name: "HANDOFF_SCHEMA", zone: "shell" },
@@ -395,8 +405,11 @@ const TOKENS = [
395
405
  { name: "OUTPUT_REPORT", zone: "round-context" },
396
406
  { name: "OUTPUT_EVIDENCE", zone: "round-context" },
397
407
  { name: "OUTPUT_HANDOFF", zone: "round-context" },
398
- { name: "REVIEW_TYPE", zone: "round-context" },
399
408
  { name: "ROLE", zone: "round-context" },
409
+ // P33 T1 — the target discriminant RENDERS, immediately below ROLE: the child
410
+ // reads the target word the CLI `--type` declared. Implement is the one role
411
+ // without a target, so its layout carries no such line and its value is empty.
412
+ { name: "TARGET_TYPE", zone: "round-context" },
400
413
  { name: "WAVE", zone: "round-context" },
401
414
  { name: "WORKSPACE_DIR", zone: "round-context" },
402
415
  { name: "WORKSPACE_ID", zone: "round-context" },
@@ -408,13 +421,34 @@ export const CLAUSES = {
408
421
  "cl:no-full-tree-find": "Never run an unbounded full-tree `find` over a large directory and never bare-read a large file — constrain to explicit paths with `maxdepth`/`-path`, or read only the needed range.",
409
422
  "cl:bash-stall-limit": `Put a \`timeout\` on every Bash command — no single invocation may run longer than ${TerminationPolicy.CHILD_BASH_TIMEOUT_MS / 60_000} minutes; a command that stalls without progress is terminated and replaced with an equivalent, lighter command.`,
410
423
  "cl:no-infinite-loop": "Never run an unbounded loop — no `while True: pass`, no `while true; do …; done`, no spin-wait or tail-follow that only a human can stop. A wait must carry a bounded exit condition (a timeout, a max-attempt counter, or a terminating predicate) that ends the loop on its own.",
411
- "cl:plan-freeze": "Approved plan/spec files are frozen — zero modification authority; any change needed is reported to the orchestrator through findings, never edited in place.",
412
- "cl:atomic-commit": "Commit each round's change as one atomic conventional commit scoped to the round — no mixed or out-of-scope content, no AI-generation trailers.",
424
+ "cl:plan-freeze": "Approved plan/spec files are frozen beyond the round's declared `capability: may.amend` scope — without that declaration a needed change goes out through findings, never an in-place edit; the structure face is outside amending authority in every round.",
425
+ "cl:atomic-commit": "Commit each round's change as one atomic conventional commit scoped to the round — no mixed or out-of-scope content, no AI-generation trailers. A read-only round has nothing to commit: its only writes are the prescribed `OUTPUT_*` artifacts, and committing belongs to the orchestrator.",
413
426
  "cl:self-validate": "Self-validate before returning: run the validation/checks your change requires and record the evidence (command + exit code + result) in the report.",
414
427
  "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.",
415
428
  "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.",
416
429
  };
417
- /** The dispatch-prompt data plane — the typed template-contract surface. $version 20
430
+ /** The dispatch-prompt data plane — the typed template-contract surface. $version 23
431
+ * calibrates the shared body's five faces (§2.6 G · H · I · J · K): the freeze
432
+ * clause limits itself to the round's declared `capability: may.amend` scope and
433
+ * the commit clause names the read-only round's absent commit; the capability
434
+ * declaration names the judged document families (phase-spec / single-spec /
435
+ * overall charter / plan); the program-conformance clause is scoped to phase-spec;
436
+ * the branch criteria speak `wave`, not the retired `task`; the charter's rubric
437
+ * slots read charter / phase author. $version 22
438
+ * calibrates the referent face of the three instruction shells (§2.5 A · B · D):
439
+ * the review item splits the branch review out of the plan review (the live tree
440
+ * against `BASE_BRANCH`, with `INPUT_PLAN` as its plan-conformance reference) and
441
+ * names the charter anchor; the fix shell drops the unreachable spec line and
442
+ * marks the branch line's `INPUT_SPEC` as a conformance reference; the docs-fix
443
+ * shell marks the plan-doc line's `INPUT_SPEC` un-editable and names the overall
444
+ * line's `INPUT_OVERALL` anchor. The overall face's `INPUT_SPEC` value went empty
445
+ * in the same batch (C2 — one charter anchor). $version 21
446
+ * renames the target discriminant token to TARGET_TYPE and RENDERS it as a
447
+ * round-context line (`- \`TARGET_TYPE\`: <target word>`) immediately below ROLE on
448
+ * every face that has a target — the review variants, the two fix rows (wave ·
449
+ * branch) and the two document-fix rows' plan/spec types (plan · phase-spec ·
450
+ * overall · single-spec). Implement is the one role without a target, so its layout
451
+ * carries no such line and the empty value is dropped. $version 20
418
452
  * gives the charter its own review criteria body (the six charter criteria, with
419
453
  * none of the implementation-face evidence duty) and makes the criteria-body
420
454
  * selection explicit — the two spec-shaped document targets share the ONE narrative
@@ -456,7 +490,7 @@ export const CLAUSES = {
456
490
  * prose return contract (`RETURN_PROSE` — nothing downstream parses the child's
457
491
  * stdout), and the per-type review criterion shells. */
458
492
  export const TEMPLATE_PROMPT = {
459
- $version: 20,
493
+ $version: 23,
460
494
  modes: MODE_PROMPTS,
461
495
  reviews: REVIEW_VARIANTS,
462
496
  return: RETURN_ZONE,
@@ -469,7 +503,7 @@ export const WORK_MODES = ["implement", "fix", "review", "docs-fix"];
469
503
  * The template assembler — the ONE renderer over the typed template-prompt data
470
504
  * plane. Construction reads the typed contract (the module's declared data —
471
505
  * no file reads, no second copy). render(values) selects the row by the ROLE value
472
- * (the review mode by ROLE + REVIEW_TYPE) — the row's fixed prefix + the single
506
+ * (the review mode by ROLE + TARGET_TYPE) — the row's fixed prefix + the single
473
507
  * return contract + its reduced round context (empty-value keys not emitted).
474
508
  */
475
509
  export class TemplateAssembler {
@@ -502,12 +536,12 @@ export class TemplateAssembler {
502
536
  return lines.join("\n");
503
537
  }
504
538
  /** The row of a ROLE — the review mode's per-type variant (selected by the
505
- * REVIEW_TYPE discriminant), the work modes from the modes table. */
539
+ * TARGET_TYPE discriminant), the work modes from the modes table. */
506
540
  #rowOf(values) {
507
541
  if (values.ROLE === "review") {
508
- const row = this.#contract.reviews[values.REVIEW_TYPE];
542
+ const row = this.#contract.reviews[values.TARGET_TYPE];
509
543
  if (row === undefined) {
510
- throw new Error(`template review type not declared: ${values.REVIEW_TYPE === undefined || values.REVIEW_TYPE === "" ? "(missing REVIEW_TYPE)" : values.REVIEW_TYPE}`);
544
+ throw new Error(`template review type not declared: ${values.TARGET_TYPE === undefined || values.TARGET_TYPE === "" ? "(missing TARGET_TYPE)" : values.TARGET_TYPE}`);
511
545
  }
512
546
  return row;
513
547
  }
@@ -529,7 +563,7 @@ export class TemplateAssembler {
529
563
  }
530
564
  return lines.join("\n");
531
565
  }
532
- /** The hard gates — a known ROLE (+ its REVIEW_TYPE for reviews), every declared
566
+ /** The hard gates — a known ROLE (+ its TARGET_TYPE for reviews), every declared
533
567
  * token supplied (empty allowed — a mode's non-consumed slots are legitimately
534
568
  * empty and merely not emitted), no undeclared values, the single return
535
569
  * contract declared, and every round-context name the mode's shell prose
@@ -543,7 +577,7 @@ export class TemplateAssembler {
543
577
  : this.#workRow(role);
544
578
  if (row === undefined) {
545
579
  const message = role === "review"
546
- ? `template review type not declared: ${values.REVIEW_TYPE === undefined || values.REVIEW_TYPE === "" ? "(missing REVIEW_TYPE)" : values.REVIEW_TYPE}`
580
+ ? `template review type not declared: ${values.TARGET_TYPE === undefined || values.TARGET_TYPE === "" ? "(missing TARGET_TYPE)" : values.TARGET_TYPE}`
547
581
  : `template work-mode not declared: ${role === undefined ? "(missing ROLE)" : role}`;
548
582
  throw new Error(message);
549
583
  }
@@ -578,9 +612,9 @@ export class TemplateAssembler {
578
612
  }
579
613
  }
580
614
  }
581
- /** The review variant of a REVIEW_TYPE (verified in the gate). */
615
+ /** The review variant of a TARGET_TYPE (verified in the gate). */
582
616
  #reviewRow(values) {
583
- return this.#contract.reviews[values.REVIEW_TYPE];
617
+ return this.#contract.reviews[values.TARGET_TYPE];
584
618
  }
585
619
  /** The work-mode row of a ROLE (verified in the gate). */
586
620
  #workRow(role) {
@@ -85,14 +85,6 @@ export class CarrierIntegrity {
85
85
  return bytes;
86
86
  throw new CarrierMismatchError(path, gap.recorded, gap.current);
87
87
  }
88
- /** The record-shaped thin shell — the `RoundRecord`'s own two cells, so a caller
89
- * holding a record never re-derives "which digest belongs to this path". A record
90
- * with no carrier path reads `null` without touching the disk. */
91
- static readFor(record) {
92
- if (record.carrierPath === null)
93
- return null;
94
- return CarrierIntegrity.read(record.carrierPath, record.carrierDigest ?? null);
95
- }
96
88
  /** The payload view `digestOf` hashes — a shallow copy with the top-level
97
89
  * `contentSha256` key dropped (a non-object payload is returned as it stands). */
98
90
  static #payloadOf(value) {
@@ -181,7 +181,7 @@ export class DispatchAuthority {
181
181
  * finished run's plan edit blocked the branch review). Only an OPEN batch's brief
182
182
  * movement refuses the faces below the wave face. */
183
183
  #waveStation(facts) {
184
- const graph = facts.pipeline.planGraph;
184
+ const graph = facts.pipeline.plan.graph();
185
185
  if (graph === null)
186
186
  return null;
187
187
  const frontier = this.#frontierOf(facts);
@@ -6,9 +6,10 @@
6
6
  //
7
7
  // · projections: ① the prompt-injection text (schemaText — the ```json fences
8
8
  // byte-fixed per plane, so the fixed prefix tail of the dispatch prompt stays
9
- // cache-friendly) and ② the engine read-back validator (violations /
10
- // evidenceViolations — the child draft is validated against exactly the same
11
- // projected objects the prompt showed it).
9
+ // cache-friendly) and ② the engine read-back validator (readBack /
10
+ // evidenceViolations — the child draft is judged against exactly the same
11
+ // projected objects the prompt showed it, the required slots refusing the round
12
+ // and the decorative ones dropped in place).
12
13
  // · planes: the carrier plane is DERIVED from the op (planeOf), never declared per
13
14
  // family — `work` (implement/fix: status + artifacts, plus the separate
14
15
  // test-evidence file for task-family rounds) or `judge` (reviews: findings-only
@@ -26,6 +27,7 @@
26
27
  //
27
28
  // Module-level exports are types / the declared schema objects / the class — zero
28
29
  // behavior-carrying bare functions (the plan's zero-bare-function discipline).
30
+ var _a;
29
31
  /** One finding row — the shared base declaration of the judge plane (severity +
30
32
  * lens + summary required; the extra review columns — section / line / fix — are
31
33
  * declared optional, and unknown extra fields ride along).
@@ -113,8 +115,12 @@ const EVIDENCE = {
113
115
  },
114
116
  };
115
117
  /**
116
- * HandoffSchema — one declaration, two projections. `violations(plane, value)` is
117
- * the read-back validator (projection ② — the engine's seat, session plane);
118
+ * HandoffSchema — one declaration, two projections. `readBack(plane, draft)` is the
119
+ * carrier read-back validator (projection ② — the engine's seat, session plane: the
120
+ * dispatch gate's tiered ruling), and `evidenceViolations(value)` is the strict walk
121
+ * of the evidence file's own declaration (the evidence gate's input). The carrier
122
+ * plane has no strict reader: a decorative slot's mistake there costs a field, never
123
+ * a round, so a second strict walk of the carrier would judge nothing.
118
124
  * `schemaText(plane, evidence)` is the injected prompt text (projection ① — fixed
119
125
  * prefix tail, byte-stable per plane so the dispatch prompt stays cache-friendly).
120
126
  * `rollup(findings)` derives the review conclusion the old JSON face rolled up.
@@ -128,15 +134,15 @@ export class HandoffSchema {
128
134
  }
129
135
  /** Projection ① — the `## Handoff schema` section text: the plane's writable
130
136
  * subset in a ```json fence + (work plane) the evidence file's schema in a second
131
- * fence. The text is byte-stable per (plane, evidence, prefix) — the fixed bytes
132
- * of the dispatch prompt's contract surface. The evidence prefix is the family
133
- * spine (§3.7 naming: `tasks-` for the task families, `branch-` for the branch
134
- * fix — a branch evidence file never carries the misleading tasks- prefix). */
135
- schemaText(plane, evidence, evidencePrefix = "tasks") {
137
+ * fence. The carrier fence is byte-stable per (plane, evidence) — the fixed bytes
138
+ * of the dispatch prompt's contract surface. The evidence sentence names the
139
+ * `OUTPUT_EVIDENCE` slot alone — the file's own name is the naming face's single
140
+ * source (`tasks-*` / `branch-*` per family), never a second spelling here. */
141
+ schemaText(plane, evidence) {
136
142
  const carrier = this.#json(this.#writable(plane));
137
143
  let text = `Write the handoff draft at \`OUTPUT_HANDOFF\` per this writable subset — the engine validates it, then materializes the final carrier in place; fields not listed here are engine-reserved, do not write them.\n\n\`\`\`json\n${carrier}\n\`\`\``;
138
144
  if (evidence) {
139
- text += `\n\nThe evidence file (\`${evidencePrefix}-{key}-test-evidence.json\` under \`WORKSPACE_DIR\`) must comply with this schema — the engine reads it back with the same stakes:\n\n\`\`\`json\n${this.#json(EVIDENCE)}\n\`\`\``;
145
+ text += `\n\nThe evidence file (the file named by \`OUTPUT_EVIDENCE\`) must comply with this schema — the engine reads it back with the same stakes:\n\n\`\`\`json\n${this.#json(EVIDENCE)}\n\`\`\``;
140
146
  }
141
147
  return text;
142
148
  }
@@ -144,21 +150,28 @@ export class HandoffSchema {
144
150
  evidenceSchemaText() {
145
151
  return this.#json(EVIDENCE);
146
152
  }
147
- /** Projection ② — validate a child draft against a plane's writable subset. Every
148
- * problem is a read-back BLOCK; the draft is left untouched for the child's
149
- * resume (never overwritten — the engine never clobbers a child's work). */
150
- violations(plane, value) {
151
- const problems = [];
152
- this.#check(this.#writable(plane), value, "", problems);
153
- return problems.map((problem) => problem.path.length === 0 ? problem.reason : `${problem.path}: ${problem.reason}`);
153
+ /** The TIERED read-back — the dispatch gate's ONE ruling (spec §2.1): a REQUIRED
154
+ * slot that violates its declaration REFUSES the draft (the round blocks), while a
155
+ * DECORATIVE slot (declared, not required — BOTH planes' `notes`, the work plane's
156
+ * `dispositions`, the judge plane's `artifacts` and the finding row's `id` /
157
+ * `section` / `line` / `fix`) is DROPPED: its path is reported once and the slot is
158
+ * never carried. The walk WRITES nothing — materialize's copy points (`draftNotes`
159
+ * / `dispositions` / the judge carrier's `artifacts` read at lifecycle.ts's
160
+ * `#materialize` / `#findingsList`) consume `dropped`, so the ruling and the carrier
161
+ * cannot disagree. A wrong decorative value costs a field, never a round — the
162
+ * refusal face stays exactly as wide as the fields the child owes. */
163
+ readBack(plane, draft) {
164
+ const out = { tier: "tiered", problems: [], dropped: [] };
165
+ this.#check(this.#writable(plane), draft, "", out);
166
+ return { problems: _a.#problemsOf(out.problems), dropped: out.dropped };
154
167
  }
155
168
  /** Projection ② — validate the test-evidence file (work-plane wave / branch rounds). */
156
169
  evidenceViolations(value) {
157
170
  if (value === null || value === undefined)
158
171
  return ["the evidence file is missing"];
159
- const problems = [];
160
- this.#check(EVIDENCE, value, "", problems);
161
- return problems.map((problem) => problem.path.length === 0 ? problem.reason : `${problem.path}: ${problem.reason}`);
172
+ const out = { tier: "strict", problems: [], dropped: [] };
173
+ this.#check(EVIDENCE, value, "", out);
174
+ return _a.#problemsOf(out.problems);
162
175
  }
163
176
  /** The round conclusion, DERIVED at judgment time from the plane — the single
164
177
  * source the review/fix ledger legs read (D27 · judgment face ⊥ input face).
@@ -233,6 +246,15 @@ export class HandoffSchema {
233
246
  const declared = new Set(Object.keys(this.#writable(plane).properties ?? {}));
234
247
  return Object.keys(value).filter((key) => !declared.has(key));
235
248
  }
249
+ /** The column one dropped path names inside a finding row — `findings[2].line` at
250
+ * index 2 reads `line`; every other dropped path (a plane-level slot, another row's
251
+ * column) reads null. The dropped-path grammar is the walker's own
252
+ * (`findings[{index}].{column}`), so its parse lives beside the walk that spells it —
253
+ * materialize's finding copy point calls this instead of re-spelling the shape. */
254
+ static findingColumnOf(path, index) {
255
+ const match = /^findings\[(\d+)\]\.(.+)$/.exec(path);
256
+ return match !== null && Number(match[1]) === index ? match[2] : null;
257
+ }
236
258
  /** The plane's writable subset — CARRIER's declared slots filtered to the plane's
237
259
  * writable set (declaration order preserved) + the plane's required slots. */
238
260
  #writable(plane) {
@@ -252,71 +274,111 @@ export class HandoffSchema {
252
274
  #json(node) {
253
275
  return JSON.stringify(node);
254
276
  }
255
- /** Walk one schema node against a value; every mismatch is a `path: reason`. */
256
- #check(node, value, path, problems) {
277
+ /** The `path: reason` forms of one walk's problems — the ONE wording the read-back
278
+ * and the evidence gate report. */
279
+ static #problemsOf(problems) {
280
+ return problems.map((problem) => problem.path.length === 0 ? problem.reason : `${problem.path}: ${problem.reason}`);
281
+ }
282
+ /** Walk one schema node against a value — the ONE walker behind both tiers. `owed`
283
+ * says whether the slot being judged is one the child OWES: its mismatch is a
284
+ * problem on either tier. A DECORATIVE slot's mismatch (a declared slot outside the
285
+ * plane's required set, a finding row's decorative column) is a problem on the strict
286
+ * walk and a DROP on the tiered one; the parent prunes whatever the slot booked
287
+ * inside itself and reports the slot's own path.
288
+ * Five parameters, one reason: `owed` is the recursion's own fact — a per-node
289
+ * wrapper object would allocate a frame for one boolean and hide the frame's tier. */
290
+ #check(node, value, path, out, owed = true) {
257
291
  if (node.enum !== undefined && !node.enum.includes(value)) {
258
- problems.push({ path, reason: `must be one of ${node.enum.join(" | ")}` });
292
+ this.#refuse(out, path, `must be one of ${node.enum.join(" | ")}`, owed);
259
293
  return;
260
294
  }
261
- if (node.type !== undefined) {
262
- if (node.type === "object") {
263
- if (typeof value !== "object" || value === null || Array.isArray(value)) {
264
- problems.push({ path, reason: "expected an object" });
265
- return;
266
- }
267
- const obj = value;
268
- for (const key of node.required ?? []) {
269
- if (obj[key] === undefined)
270
- problems.push({ path: this.#at(path, key), reason: "required" });
271
- }
272
- for (const [key, sub] of Object.entries(node.properties ?? {})) {
273
- if (obj[key] !== undefined)
274
- this.#check(sub, obj[key], this.#at(path, key), problems);
275
- }
276
- // Non-declared keys (extra child fields such as a work-draft `findings`) are
277
- // DROPPED by materialize, never a BLOCK — the validator and materialize judge
278
- // the same field the same way (§8.7). Only semantic errors on declared fields
279
- // (required / type / enum / length) refuse the draft.
295
+ if (node.type === "object") {
296
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
297
+ this.#refuse(out, path, "expected an object", owed);
280
298
  return;
281
299
  }
282
- if (node.type === "array") {
283
- if (!Array.isArray(value)) {
284
- problems.push({ path, reason: "expected an array" });
285
- return;
286
- }
287
- if (node.items !== undefined) {
288
- for (let index = 0; index < value.length; index += 1) {
289
- this.#check(node.items, value[index], `${path}[${index}]`, problems);
290
- }
291
- }
292
- return;
293
- }
294
- if (node.type === "string") {
295
- if (typeof value !== "string") {
296
- problems.push({ path, reason: "expected a string" });
297
- return;
298
- }
299
- if (node.minLength !== undefined && value.length < node.minLength)
300
- problems.push({ path, reason: `must be at least ${node.minLength} characters` });
301
- if (node.maxLength !== undefined && value.length > node.maxLength)
302
- problems.push({ path, reason: `must be at most ${node.maxLength} characters` });
303
- return;
304
- }
305
- if (node.type === "integer") {
306
- if (typeof value !== "number" || !Number.isInteger(value)) {
307
- problems.push({ path, reason: "expected an integer" });
308
- }
300
+ // Non-declared keys (extra child fields such as a work-draft `findings`) are
301
+ // DROPPED by materialize, never a BLOCK — the validator and materialize judge
302
+ // the same field the same way (§8.7). Only semantic errors on declared fields
303
+ // (required / type / enum / length) refuse the draft.
304
+ this.#checkObject(node, value, path, out);
305
+ return;
306
+ }
307
+ if (node.type === "array") {
308
+ if (!Array.isArray(value)) {
309
+ this.#refuse(out, path, "expected an array", owed);
309
310
  return;
310
311
  }
311
- if (node.type === "boolean") {
312
- if (typeof value !== "boolean")
313
- problems.push({ path, reason: "expected a boolean" });
312
+ const items = node.items;
313
+ if (items === undefined)
314
314
  return;
315
+ // An element is owed once its slot is present: a bad element is judged INSIDE the
316
+ // slot, and a decorative slot's parent prunes it with the rest of the slot.
317
+ for (const [index, entry] of value.entries()) {
318
+ this.#check(items, entry, `${path}[${index}]`, out);
315
319
  }
320
+ return;
321
+ }
322
+ const reason = _a.#scalarReason(node, value);
323
+ if (reason !== null)
324
+ this.#refuse(out, path, reason, owed);
325
+ }
326
+ /** The object half — the required sweep (a missing owed key refuses on either tier),
327
+ * then every present declared slot judged at its own owed-ness. */
328
+ #checkObject(node, obj, path, out) {
329
+ const required = node.required ?? [];
330
+ for (const key of required) {
331
+ if (obj[key] !== undefined)
332
+ continue;
333
+ out.problems.push({ path: this.#at(path, key), reason: "required" });
334
+ }
335
+ for (const [key, sub] of Object.entries(node.properties ?? {})) {
336
+ if (obj[key] === undefined)
337
+ continue;
338
+ const at = this.#at(path, key);
339
+ const owed = required.includes(key);
340
+ const markProblems = out.problems.length;
341
+ const markDropped = out.dropped.length;
342
+ this.#check(sub, obj[key], at, out, owed);
343
+ if (owed || out.tier === "strict" || out.problems.length === markProblems)
344
+ continue;
345
+ // The decorative slot breaks its own declaration — prune everything it booked
346
+ // inside, then report the slot once (materialize's copy point reads this path).
347
+ out.problems.length = markProblems;
348
+ out.dropped.length = markDropped;
349
+ out.dropped.push(at);
316
350
  }
317
351
  }
352
+ /** The scalar keywords' judgment — the reason a value breaks its declared type or
353
+ * length, null when it passes. The enum is judged by the caller first (an enum value
354
+ * is matched by value, never by the declared type alone). */
355
+ static #scalarReason(node, value) {
356
+ if (node.type === "string") {
357
+ if (typeof value !== "string")
358
+ return "expected a string";
359
+ if (node.minLength !== undefined && value.length < node.minLength)
360
+ return `must be at least ${node.minLength} characters`;
361
+ if (node.maxLength !== undefined && value.length > node.maxLength)
362
+ return `must be at most ${node.maxLength} characters`;
363
+ return null;
364
+ }
365
+ if (node.type === "integer")
366
+ return typeof value === "number" && Number.isInteger(value) ? null : "expected an integer";
367
+ if (node.type === "boolean")
368
+ return typeof value === "boolean" ? null : "expected a boolean";
369
+ return null;
370
+ }
371
+ /** Book one mismatch at its tier — a problem for an owed slot (or a strict walk), a
372
+ * dropped path for a decorative one. */
373
+ #refuse(out, path, reason, owed) {
374
+ if (owed || out.tier === "strict")
375
+ out.problems.push({ path, reason });
376
+ else
377
+ out.dropped.push(path);
378
+ }
318
379
  /** The JSON-path join — `.field` (or bare, at the root). */
319
380
  #at(path, key) {
320
381
  return path.length === 0 ? key : `${path}.${key}`;
321
382
  }
322
383
  }
384
+ _a = HandoffSchema;