@oscaner-skills/cdd-engine 1.0.0 → 3.0.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.
Files changed (120) hide show
  1. package/README.md +11 -10
  2. package/README.zh-CN.md +11 -10
  3. package/package.json +16 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  6. package/src-next/__tests__/floor.guard.test.ts +69 -0
  7. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  8. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  9. package/src-next/__tests__/smoke.integration.test.ts +185 -0
  10. package/src-next/__tests__/support/strip-comments.ts +99 -0
  11. package/src-next/__tests__/zero-dep.test.ts +94 -0
  12. package/src-next/bin.ts +61 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +256 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +165 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +190 -0
  16. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +106 -0
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +240 -0
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +165 -0
  19. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +190 -0
  20. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +100 -0
  21. package/src-next/contract/__tests__/declare.test.ts +481 -0
  22. package/src-next/contract/__tests__/doc.test.ts +527 -0
  23. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  24. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  25. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  26. package/src-next/contract/__tests__/judge.test.ts +1111 -0
  27. package/src-next/contract/__tests__/lint.test.ts +324 -0
  28. package/src-next/contract/__tests__/project.test.ts +460 -0
  29. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  30. package/src-next/contract/__tests__/translate.test.ts +96 -0
  31. package/src-next/contract/declare.ts +1071 -0
  32. package/src-next/contract/doc.ts +816 -0
  33. package/src-next/contract/frontmatter.ts +233 -0
  34. package/src-next/contract/home-extractors.ts +397 -0
  35. package/src-next/contract/invariants.ts +1413 -0
  36. package/src-next/contract/judge.ts +151 -0
  37. package/src-next/contract/lint.ts +239 -0
  38. package/src-next/contract/project.ts +656 -0
  39. package/src-next/contract/skill-anatomy.ts +301 -0
  40. package/src-next/contract/translate.ts +113 -0
  41. package/src-next/face/__tests__/board-view.test.ts +1151 -0
  42. package/src-next/face/__tests__/capsule.test.ts +300 -0
  43. package/src-next/face/__tests__/channel-closure.guard.test.ts +129 -0
  44. package/src-next/face/__tests__/cli.test.ts +4897 -0
  45. package/src-next/face/__tests__/face.test.ts +289 -0
  46. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  47. package/src-next/face/__tests__/host.test.ts +24 -0
  48. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  49. package/src-next/face/__tests__/negation.ts +6 -0
  50. package/src-next/face/__tests__/preview.test.ts +374 -0
  51. package/src-next/face/__tests__/projection.test.ts +303 -0
  52. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  53. package/src-next/face/__tests__/termination.test.ts +650 -0
  54. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  55. package/src-next/face/artifacts.ts +248 -0
  56. package/src-next/face/board-view.ts +652 -0
  57. package/src-next/face/capsule.ts +163 -0
  58. package/src-next/face/cli.ts +1028 -0
  59. package/src-next/face/declare.ts +323 -0
  60. package/src-next/face/gate.ts +171 -0
  61. package/src-next/face/graph-view.ts +74 -0
  62. package/src-next/face/host.ts +302 -0
  63. package/src-next/face/lifecycle.ts +725 -0
  64. package/src-next/face/preview.ts +151 -0
  65. package/src-next/face/projection.ts +285 -0
  66. package/src-next/face/route-render.ts +185 -0
  67. package/src-next/face/termination.ts +573 -0
  68. package/src-next/face/words.ts +314 -0
  69. package/src-next/infra/__tests__/infra.test.ts +333 -0
  70. package/src-next/infra/__tests__/root.test.ts +56 -0
  71. package/src-next/infra/config.ts +42 -0
  72. package/src-next/infra/doc-roots.ts +29 -0
  73. package/src-next/infra/git.ts +39 -0
  74. package/src-next/infra/process.ts +34 -0
  75. package/src-next/infra/root.ts +73 -0
  76. package/src-next/infra/runtime.ts +132 -0
  77. package/src-next/infra/workspace.ts +322 -0
  78. package/src-next/render/__tests__/render.test.ts +550 -0
  79. package/src-next/render/__tests__/skeleton.test.ts +684 -0
  80. package/src-next/render/brief.ts +121 -0
  81. package/src-next/render/issue-body.ts +162 -0
  82. package/src-next/render/skeleton.ts +502 -0
  83. package/src-next/render/templates.ts +645 -0
  84. package/src-next/session/__tests__/graph.test.ts +277 -0
  85. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  86. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  87. package/src-next/session/__tests__/ledger.test.ts +745 -0
  88. package/src-next/session/__tests__/next.test.ts +460 -0
  89. package/src-next/session/__tests__/preflight.test.ts +545 -0
  90. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  91. package/src-next/session/__tests__/run.test.ts +1026 -0
  92. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  93. package/src-next/session/__tests__/wave.test.ts +476 -0
  94. package/src-next/session/faces.ts +110 -0
  95. package/src-next/session/graph.ts +411 -0
  96. package/src-next/session/handoff-schema.ts +373 -0
  97. package/src-next/session/ledger.ts +1076 -0
  98. package/src-next/session/next.ts +293 -0
  99. package/src-next/session/preflight.ts +271 -0
  100. package/src-next/session/round-naming.ts +84 -0
  101. package/src-next/session/run.ts +610 -0
  102. package/src-next/session/state.ts +30 -0
  103. package/src-next/session/wave.ts +139 -0
  104. package/templates/report/issue-body.json +17 -65
  105. package/dist/chunks/branch.mjs +0 -480
  106. package/dist/chunks/docs.mjs +0 -253
  107. package/dist/chunks/task.mjs +0 -913
  108. package/dist/cli.mjs +0 -5457
  109. package/dist/documents/schema/add-phase-protocol.json +0 -126
  110. package/dist/documents/schema/overall.json +0 -361
  111. package/dist/documents/schema/phase-spec.json +0 -145
  112. package/dist/documents/schema/plan.json +0 -191
  113. package/dist/documents/schema/skill-anatomy.json +0 -233
  114. package/dist/resources/harness-registry.json +0 -49
  115. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  116. package/templates/engine-config.json +0 -302
  117. package/templates/schema/cache-profile-schema.json +0 -23
  118. package/templates/schema/docs-handoff-schema.json +0 -129
  119. package/templates/schema/task-handoff-schema.json +0 -332
  120. package/templates/template-contract.json +0 -231
@@ -0,0 +1,645 @@
1
+ // packages/cdd-engine/src-next/render/templates.ts
2
+ // T21 — the template-contract typed surface: the template-contract JSON's data-plane
3
+ // home PLUS the TemplateAssembler (one module, one renderer). The dispatch prompt
4
+ // data (the per-mode shell frames · the review variants · the single prose return block ·
5
+ // the round-context subsets · the token registry · the clause partials) and the
6
+ // review criteria (the four-type axes guides — P4, extended to spec/plan by the
7
+ // v1.8 review-closeout) are typed constant data here, imported never parsed:
8
+ //
9
+ // · TEMPLATE_PROMPT — the rendering data plane the assembler consumes; this
10
+ // module renders over it (the JSON's $schema/_doc prose plane is gone).
11
+ // · REVIEWS — the four-type review criteria (task/branch axes guides + the
12
+ // spec/plan URC prose, migrated from the dispatch table — their single typed
13
+ // home, P4). P5 lands here: the "no parallel sub-agents" phrase is deleted.
14
+ //
15
+ // T15 v1.8 (the mode dispatch table — §3.5) restructures the prompt from "one all-mode
16
+ // manual + dynamic zone" to the per-mode dispatch table:
17
+ // · MODE_PROMPTS — one row per work-mode (implement / fix / docs-fix — the ROLE
18
+ // vocabulary; the spec/plan fix faces ride the docs-fix row): the mode's FIXED
19
+ // prefix (its instruction shell + the injected writable-subset schema at the
20
+ // shell's tail — byte-identical for every dispatch of the mode, so the prompt-
21
+ // cache prefix groups by mode) + the mode's REDUCED round-context subset.
22
+ // · REVIEW_VARIANTS — the review mode's four per-type rows (task/branch/spec/plan):
23
+ // the criteria + lens text are FIXED PREFIX content (folded into each variant's
24
+ // shell — they are per-type constants, so they never ride the dynamic tail; the
25
+ // INPUT_CRITERIA / INPUT_LENS round-context tokens are gone) and each variant's
26
+ // fixed prefix is byte-stable — a review dispatch's cache prefix groups by type.
27
+ // · the normalized token vocabulary (§3.5): INPUT_* (read-side) / OUTPUT_* (write-
28
+ // side) / WORKSPACE_* (environment) / BASE_BRANCH (the branch review's scope
29
+ // anchor) / ROLE (the nominative identity) / WAVE (the wave-unitary unit).
30
+ // Round-context keys are the mode's consumption set — a key the shell never
31
+ // names is not declared (the fix round carries no INPUT_ RULES).
32
+ //
33
+ // T15 v1.9 (the handoff contract-surface rework — §3.6) lands the schema injection
34
+ // in the same plane: the `## Handoff schema` section at every shell's tail carries
35
+ // the {{HANDOFF_SCHEMA}} slot (projection ① of session/handoff-schema.ts — the same
36
+ // declared objects the engine validates the draft against, projection ②). The
37
+ // handoff-format prose is gone; RETURN_PROSE is the ONE return contract.
38
+ //
39
+ // T15 v1.10/1.11 (the review-closeout batch — §3.7) refines the shell composition:
40
+ // the work-mode tail is the shared EVIDENCE_ITEM cell (implement/fix carry it;
41
+ // docs-fix carries no evidence file — zero per-mode duplication), and the review
42
+ // variants fold the criteria/lens in.
43
+ //
44
+ // P5 (M1) supersede: the implement mode's dispatch wording names the upstream
45
+ // implement skill ref (`DISPATCH.implement`, the ref the dispatch row resolves
46
+ // to), never the retired tdd alias.
47
+ //
48
+ // Module-level exports are types / the declared constant data / the class — zero
49
+ // behavior-carrying bare functions (the plan's zero-bare-function discipline).
50
+
51
+ import { DISPATCH } from "../face/host.ts";
52
+ import type { TargetType } from "../session/faces.ts";
53
+
54
+ /** The per-dispatch slot values — one entry per declared template token. */
55
+ export interface TemplateValues {
56
+ readonly [name: string]: string;
57
+ }
58
+
59
+ /** One token declaration — a round-context/return zone slot the dispatch fills. */
60
+ export interface TemplateToken {
61
+ /** The token name — the `{{NAME}}` slot spelling. */
62
+ name: string;
63
+ /** The zone the token belongs to (shell / return / round-context). */
64
+ zone: string;
65
+ }
66
+
67
+ /** The work-modes of the dispatch table — the ROLE values (fix's spec/plan face is
68
+ * the docs-fix mode; review covers task/branch/spec/plan + branch-review). */
69
+ export type WorkMode = "implement" | "fix" | "review" | "docs-fix";
70
+
71
+ /** The work-mode rows of the dispatch table — every ROLE except review (the review
72
+ * mode's rows are the four per-type REVIEW_VARIANTS). */
73
+ export type WorkModeRowKey = Exclude<WorkMode, "review">;
74
+
75
+ /** The four review types — the review mode's per-type prefix variants (the criteria
76
+ * and lens are per-type constants, so each variant's fixed prefix is byte-stable). */
77
+
78
+ /** One dispatch-table row — a mode's fixed prefix + its reduced dynamic tail. */
79
+ export interface ModePromptRow {
80
+ /** The work-mode identity (the ROLE vocabulary). */
81
+ mode: WorkMode;
82
+ /** The mode's FIXED prefix — its instruction shell + the `## Handoff schema`
83
+ * section (with the {{HANDOFF_SCHEMA}} slot at the tail — the injected
84
+ * writable-subset fence): byte-identical for every dispatch of the mode. */
85
+ shell: readonly string[];
86
+ /** The mode's REDUCED round-context subset — the only dynamic region; a key
87
+ * whose value is empty is not emitted (empty-valued keys are dropped). */
88
+ roundContext: readonly string[];
89
+ }
90
+
91
+ /** The template prompt data plane — the work-mode rows + the review-per-type rows +
92
+ * the single return contract + the token registry + the clause partials. */
93
+ export interface TemplatePrompt {
94
+ $version: number;
95
+ /** The work-mode rows — one per non-review ROLE (§3.5; the review rows live in
96
+ * `reviews` — their ROLE value is "review" and REVIEW_TYPE selects the row). */
97
+ modes: Readonly<Record<WorkModeRowKey, ModePromptRow>>;
98
+ /** The review mode's per-type rows — each variant's fixed prefix carries its
99
+ * criteria + lens (folded in, never tokens). */
100
+ reviews: Readonly<Record<TargetType, ModePromptRow>>;
101
+ /** The `## Return` zone — the single plain-prose block (P11: the child's stdout
102
+ * contract is prose, never a fixed key=value block; the handoff draft is the
103
+ * round's machine-readable result). */
104
+ return: { readonly RETURN_PROSE: readonly string[] };
105
+ /** The token registry — the union across every mode's round context + the shell's
106
+ * schema slot (the gate's declared list). */
107
+ tokens: readonly TemplateToken[];
108
+ clauses: Readonly<Record<string, string>>;
109
+ }
110
+
111
+ /** One review guide row — the criteria of one review type (its lens vocabulary +
112
+ * the axes/URC prose — the review prompt's fixed criteria body). */
113
+ export interface ReviewGuideRow {
114
+ /** The lens vocabulary — the finding lens labels the review may carry. */
115
+ lensEnum: readonly string[];
116
+ /** The axes/URC guide prose — the criteria body (the task/branch four axes +
117
+ * verification-evidence duty; the spec/plan URC rows). */
118
+ axesGuide: string;
119
+ }
120
+
121
+ /** The review criteria — the four per-type guides (P4 typed data; the spec/plan
122
+ * URC prose migrated from the dispatch table at v1.8 closeout). */
123
+ export type ReviewGuides = Readonly<Record<TargetType, ReviewGuideRow>>;
124
+
125
+ /** The nominal fixed-frame cells shared by every shell (byte-identical words — the
126
+ * fixed prefix is read on every dispatch, so every word costs child context). */
127
+ const FRAME_ITEMS: readonly string[] = [
128
+ "**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.",
129
+ "**Scope lock:** use only this round's inputs in `## Round context`. No full plan reads. No extra features, no tangential refactors, no scope creep.",
130
+ ];
131
+
132
+ /** The shared work-mode tail cell — the evidence gate (implement/fix carry it;
133
+ * docs-fix carries no evidence file — zero per-mode duplication, §3.7). The
134
+ * evidence file's concrete name rides the injected schema's preamble (per-family
135
+ * prefix), never this fixed text. */
136
+ const EVIDENCE_ITEM =
137
+ "**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.";
138
+
139
+ /** The discipline-clause cells shared by every shell (the `{{> cl:…}}` partials
140
+ * resolve from the single clause container — the same bytes, one per shell). */
141
+ const LICENSE_ITEMS: readonly string[] = [
142
+ "",
143
+ "**Discipline clauses:**",
144
+ "- {{> cl:english-comments}}",
145
+ "- {{> cl:eof-newline}}",
146
+ "- {{> cl:no-full-tree-find}}",
147
+ "- {{> cl:bash-stall-limit}}",
148
+ "- {{> cl:plan-freeze}}",
149
+ "- {{> cl:atomic-commit}}",
150
+ "- {{> cl:self-validate}}",
151
+ ];
152
+
153
+ /** The `## Handoff schema` section — the injected writable-subset fence at every
154
+ * shell's tail (the {{HANDOFF_SCHEMA}} slot; the face's sets differ per mode, so
155
+ * the section's bytes are fixed per mode — §3.5 prefix-cache grouping). */
156
+ const SCHEMA_SECTION: readonly string[] = ["", "## Handoff schema", "", "{{HANDOFF_SCHEMA}}"];
157
+
158
+ /** The implement row's fixed prefix — header + instructions + the shared work tail. */
159
+ const IMPLEMENT_SHELL: readonly string[] = [
160
+ "# CDD dispatch — implement round",
161
+ "",
162
+ "## Instructions",
163
+ "",
164
+ ...FRAME_ITEMS,
165
+ `**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 + \`failure_category\`) and \`artifacts\` (the prescribed \`OUTPUT_REPORT\`/\`OUTPUT_EVIDENCE\` paths from the round context — the \`{family}-{key}-\` canonical names, zero free naming).`,
166
+ EVIDENCE_ITEM,
167
+ ...LICENSE_ITEMS,
168
+ ...SCHEMA_SECTION,
169
+ ];
170
+
171
+ /** The fix row's fixed prefix — header + instructions + the shared work tail. */
172
+ const FIX_TYPED_INSTRUCTIONS: readonly string[] = [
173
+ "**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.",
174
+ "**Conditional TDD:** when a finding requires a behavior change and the change has no test coverage, write or adjust the tests first and drive the change red→green — the discipline applies conditionally, never as a blanket demand on every finding.",
175
+ ];
176
+
177
+ /** The fix row's fixed prefix — header + instructions + the shared work tail. */
178
+ const FIX_SHELL: readonly string[] = [
179
+ "# CDD dispatch — fix round",
180
+ "",
181
+ "## Instructions",
182
+ "",
183
+ ...FRAME_ITEMS,
184
+ ...FIX_TYPED_INSTRUCTIONS,
185
+ "**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).",
186
+ EVIDENCE_ITEM,
187
+ ...LICENSE_ITEMS,
188
+ // T5 (v0.3) — The work face's ONE strict-schema sentence: every top-level draft
189
+ // field comes from the `## Handoff schema` declared properties (the fields'
190
+ // single source is the injected fence below — never a second enumeration in the
191
+ // shell prose; a fix child that mirrors the source review carrier's top-level
192
+ // shape trips the engine's read-back BLOCK, so the sentence names the schema as
193
+ // the field source explicitly).
194
+ "**Draft fields:** every top-level field of the draft comes from the `## Handoff schema` declared `properties` — the declaration is the field source, zero extra keys.",
195
+ ...SCHEMA_SECTION,
196
+ ];
197
+
198
+ /** The docs-fix row's fixed prefix — header + instructions (no evidence — the
199
+ * docs-fix face writes no evidence file). */
200
+ const DOCS_FIX_SHELL: readonly string[] = [
201
+ "# CDD dispatch — docs-fix round",
202
+ "",
203
+ "## Instructions",
204
+ "",
205
+ ...FRAME_ITEMS,
206
+ "**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`; empty `findings` = all fixed. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema`; the engine derives the conclusion from the residual findings; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
207
+ ...LICENSE_ITEMS,
208
+ // T5 (v0.3) — The findings face's ONE strict-schema sentence: same schema-first
209
+ // directive as the work shell, naming the required `findings` (carried over from
210
+ // the source review carrier verbatim — the required key is told how to fill, so
211
+ // the sentence never contradicts the findings carrier's own required gate; the
212
+ // work shell's field list is never copied here, and no field enumeration rides
213
+ // the findings shell's prose either).
214
+ "**Draft fields:** every top-level field of the draft comes from the `## Handoff schema` declared `properties` — `findings` (required) rides over from `INPUT_REVIEWS` verbatim, unmodified; the declaration is the field source, zero extra keys.",
215
+ ...SCHEMA_SECTION,
216
+ ];
217
+
218
+ /** The review variants' shared instruction text — the review's mode rule (the
219
+ * criteria body + the lens vocabulary ride per-type fixed items below). */
220
+ const REVIEW_ITEM =
221
+ "**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`. 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.";
222
+
223
+ /** The review mode's shared reduced tail — the only dynamic region of every review
224
+ * variant (the criteria/lens are fixed-prefix per type, never here). Each review
225
+ * type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan/branch
226
+ * → `INPUT_PLAN`; spec → `INPUT_SPEC`); the branch review additionally carries
227
+ * `BASE_BRANCH` (the scope anchor). Empty slots are dropped by the assembler. */
228
+ const REVIEW_CONTEXT: readonly string[] = [
229
+ "## Round context",
230
+ "",
231
+ "- `ROLE`: {{ROLE}}",
232
+ "- `WAVE`: {{WAVE}}",
233
+ "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
234
+ "- `INPUT_PLAN`: {{INPUT_PLAN}}",
235
+ "- `INPUT_SPEC`: {{INPUT_SPEC}}",
236
+ "- `BASE_BRANCH`: {{BASE_BRANCH}}",
237
+ "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
238
+ "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
239
+ "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
240
+ "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
241
+ ];
242
+
243
+ /** The work-mode dispatch rows — implement / fix / docs-fix (§3.5; the review rows
244
+ * are REVIEW_VARIANTS). */
245
+ const MODE_PROMPTS: Readonly<Record<WorkModeRowKey, ModePromptRow>> = {
246
+ implement: {
247
+ mode: "implement",
248
+ shell: IMPLEMENT_SHELL,
249
+ roundContext: [
250
+ "## Round context",
251
+ "",
252
+ "- `ROLE`: {{ROLE}}",
253
+ "- `WAVE`: {{WAVE}}",
254
+ "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
255
+ // find #4 + #5 — the plan's ## Constraints rides the wave brief mirror;
256
+ // the OUTPUT_* write paths are prescribed (the {family}-{key}- canonical names)
257
+ "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
258
+ "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
259
+ "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
260
+ "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
261
+ "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
262
+ ],
263
+ },
264
+ fix: {
265
+ mode: "fix",
266
+ shell: FIX_SHELL,
267
+ roundContext: [
268
+ "## Round context",
269
+ "",
270
+ "- `ROLE`: {{ROLE}}",
271
+ "- `WAVE`: {{WAVE}}",
272
+ "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
273
+ "- `INPUT_PLAN`: {{INPUT_PLAN}}",
274
+ "- `INPUT_SPEC`: {{INPUT_SPEC}}",
275
+ "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
276
+ "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
277
+ "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
278
+ "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
279
+ "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
280
+ "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
281
+ ],
282
+ },
283
+ "docs-fix": {
284
+ mode: "docs-fix",
285
+ shell: DOCS_FIX_SHELL,
286
+ roundContext: [
287
+ "## Round context",
288
+ "",
289
+ "- `ROLE`: {{ROLE}}",
290
+ "- `WAVE`: {{WAVE}}",
291
+ "- `INPUT_PLAN`: {{INPUT_PLAN}}",
292
+ "- `INPUT_SPEC`: {{INPUT_SPEC}}",
293
+ "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
294
+ "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
295
+ "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
296
+ "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
297
+ "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
298
+ ],
299
+ },
300
+ };
301
+
302
+ /** The four-type review criteria — the review prompts' fixed criteria body (P4; the
303
+ * spec/plan URC rows migrated from the dispatch table at the v1.8 closeout — their
304
+ * single typed home). */
305
+ export const REVIEWS = {
306
+ wave: {
307
+ lensEnum: ["standards", "spec", "buildability"],
308
+ axesGuide:
309
+ "Standards axis (repo coding standards + code-review smell baseline) + Spec axis (wave brief / plan requirements) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — `tsc --noEmit`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): run `git diff origin/<BASE_BRANCH>..HEAD` yourself (BASE_BRANCH as named in the round context; on a missing artifact judge the working tree) — every changed file must fall within the wave brief's file surface (`**Files:**` seams) or be attributable to the plan / reviewed intent; an unattributable changed file is a candidate finding (severity by your judgment). The reviewer is the changed-surface judge — the engine reconciles nothing. The reviewed artifact is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable user would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Calibrate findings by real severity — not everything is a blocker — and acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust). Single agent, four axes.",
310
+ },
311
+ branch: {
312
+ lensEnum: ["standards", "spec", "buildability"],
313
+ axesGuide:
314
+ "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. The reviewed artifact is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable user would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Calibrate findings by real severity — not everything is a blocker — and acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust).",
315
+ },
316
+ spec: {
317
+ lensEnum: ["completeness", "consistency", "clarity"],
318
+ axesGuide:
319
+ "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 (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + The reviewed spec is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable downstream author would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Calibrate findings by real severity — not everything is a blocker — and acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust).",
320
+ },
321
+ plan: {
322
+ lensEnum: ["completeness", "decomposition", "buildability"],
323
+ axesGuide:
324
+ "Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + spec conformance — the plan is judged against its design spec at `INPUT_SPEC` (the plan's `spec` front-matter target): every spec requirement must map to a task, and a spec requirement with no owning task is a completeness finding + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + The reviewed spec is a vision, not an exhaustive enumeration — behavior it is silent on is judged by what a reasonable implementer would expect; its silence is not permission, and a finding's severity grades that expectation, not whether the text mentions the trigger. Before your verdict, list every behavior you considered and set aside as outside the reviewed scope — one line each with the reason; nothing set aside is dropped silently; an empty list means you set nothing aside. Calibrate findings by real severity — not everything is a blocker — and acknowledge what was done well before listing findings (accurate praise earns the rest of the report trust).",
325
+ },
326
+ } as const satisfies ReviewGuides;
327
+
328
+ /** The per-type facts the review variants compose at module-const time (the lens
329
+ * vocabularies + the criteria bodies — single data references, never restates). */
330
+ const REVIEWS_WAVE_LENS = REVIEWS.wave.lensEnum.join(" | ");
331
+ const REVIEWS_BRANCH_LENS = REVIEWS.branch.lensEnum.join(" | ");
332
+ const REVIEWS_SPEC_LENS = REVIEWS.spec.lensEnum.join(" | ");
333
+ const REVIEWS_PLAN_LENS = REVIEWS.plan.lensEnum.join(" | ");
334
+ const REVIEW_WAVE_AXES = REVIEWS.wave.axesGuide;
335
+ const REVIEW_BRANCH_AXES = REVIEWS.branch.axesGuide;
336
+ const REVIEW_SPEC_URC = REVIEWS.spec.axesGuide;
337
+ const REVIEW_PLAN_URC = REVIEWS.plan.axesGuide;
338
+
339
+ /** The review mode's four per-type rows (§3.7) — each variant's fixed prefix folds
340
+ * its criteria + lens INLINE (the `INPUT_CRITERIA`/`INPUT_LENS` round-context
341
+ * tokens are gone), and shares the REVIEW_CONTEXT dynamic tail. */
342
+ const REVIEW_VARIANTS: Readonly<Record<TargetType, ModePromptRow>> = {
343
+ wave: {
344
+ mode: "review",
345
+ shell: [
346
+ "# CDD dispatch — review round",
347
+ "",
348
+ "## Instructions",
349
+ "",
350
+ ...FRAME_ITEMS,
351
+ REVIEW_ITEM,
352
+ `**Lens labels:** one of \`${REVIEWS_WAVE_LENS}\` — every finding MUST carry its \`lens\`.`,
353
+ `**Criteria — wave:** ${REVIEW_WAVE_AXES}`,
354
+ ...LICENSE_ITEMS,
355
+ ...SCHEMA_SECTION,
356
+ ],
357
+ roundContext: REVIEW_CONTEXT,
358
+ },
359
+ branch: {
360
+ mode: "review",
361
+ shell: [
362
+ "# CDD dispatch — review round",
363
+ "",
364
+ "## Instructions",
365
+ "",
366
+ ...FRAME_ITEMS,
367
+ REVIEW_ITEM,
368
+ `**Lens labels:** one of \`${REVIEWS_BRANCH_LENS}\` — every finding MUST carry its \`lens\`.`,
369
+ `**Criteria — branch:** ${REVIEW_BRANCH_AXES}`,
370
+ ...LICENSE_ITEMS,
371
+ ...SCHEMA_SECTION,
372
+ ],
373
+ roundContext: REVIEW_CONTEXT,
374
+ },
375
+ spec: {
376
+ mode: "review",
377
+ shell: [
378
+ "# CDD dispatch — review round",
379
+ "",
380
+ "## Instructions",
381
+ "",
382
+ ...FRAME_ITEMS,
383
+ REVIEW_ITEM,
384
+ `**Lens labels:** one of \`${REVIEWS_SPEC_LENS}\` — every finding MUST carry its \`lens\`.`,
385
+ `**Criteria — spec:** ${REVIEW_SPEC_URC}`,
386
+ ...LICENSE_ITEMS,
387
+ ...SCHEMA_SECTION,
388
+ ],
389
+ roundContext: REVIEW_CONTEXT,
390
+ },
391
+ plan: {
392
+ mode: "review",
393
+ shell: [
394
+ "# CDD dispatch — review round",
395
+ "",
396
+ "## Instructions",
397
+ "",
398
+ ...FRAME_ITEMS,
399
+ REVIEW_ITEM,
400
+ `**Lens labels:** one of \`${REVIEWS_PLAN_LENS}\` — every finding MUST carry its \`lens\`.`,
401
+ `**Criteria — plan:** ${REVIEW_PLAN_URC}`,
402
+ ...LICENSE_ITEMS,
403
+ ...SCHEMA_SECTION,
404
+ ],
405
+ roundContext: REVIEW_CONTEXT,
406
+ },
407
+ };
408
+
409
+ /** The `## Return` zone — the single plain-prose contract block (P11: the child
410
+ * narrates the round in prose; nothing downstream parses its stdout — the handoff
411
+ * draft at `OUTPUT_HANDOFF` is the round's machine-readable result). */
412
+ const RETURN_ZONE: TemplatePrompt["return"] = {
413
+ RETURN_PROSE: [
414
+ "## Return",
415
+ "",
416
+ "Report in a few plain sentences what this round did, whether it succeeded, and — if it",
417
+ "did not — what blocked it. Nothing downstream parses this text; the handoff draft at",
418
+ "`OUTPUT_HANDOFF` is the round's machine-readable result. Do not emit key-value lines,",
419
+ "JSON, or any fixed block.",
420
+ "",
421
+ "(fail: an uncaught failure → exit non-zero with a one-line reason)",
422
+ ],
423
+ };
424
+
425
+ /** The token registry — the union across every mode's round context + the shell's
426
+ * schema slot (the v1.8 normalized vocabulary; the assembly face supplies every
427
+ * declared slot, empty where the mode does not consume it — the round-context
428
+ * renderer drops the empty-valued lines). REVIEW_TYPE is the review-mode row
429
+ * selector (supplied but never rendered). */
430
+ const TOKENS: readonly TemplateToken[] = [
431
+ { name: "BASE_BRANCH", zone: "round-context" },
432
+ { name: "HANDOFF_SCHEMA", zone: "shell" },
433
+ { name: "INPUT_PLAN", zone: "round-context" },
434
+ { name: "INPUT_SPEC", zone: "round-context" },
435
+ { name: "INPUT_REVIEWS", zone: "round-context" },
436
+ { name: "INPUT_WAVE_BRIEF", zone: "round-context" },
437
+ // find #5 — the prescribed artifact write paths (the {family}-{key}-{artifact}
438
+ // single naming; the brief is a pure read input with no write slot).
439
+ { name: "OUTPUT_REPORT", zone: "round-context" },
440
+ { name: "OUTPUT_EVIDENCE", zone: "round-context" },
441
+ { name: "OUTPUT_HANDOFF", zone: "round-context" },
442
+ { name: "REVIEW_TYPE", zone: "round-context" },
443
+ { name: "ROLE", zone: "round-context" },
444
+ { name: "WAVE", zone: "round-context" },
445
+ { name: "WORKSPACE_DIR", zone: "round-context" },
446
+ { name: "WORKSPACE_ID", zone: "round-context" },
447
+ ];
448
+
449
+ /** The clause partials — the `{{> cl:…}}` forms of the discipline clauses. */
450
+ export const CLAUSES = {
451
+ "cl:english-comments":
452
+ "Write code comments and shipped prose in English only — English-primary (no other-language comment blocks, no translated mirrors).",
453
+ "cl:eof-newline":
454
+ "Every text file must end with exactly one newline (EOF newline): no missing final newline and no trailing blank lines.",
455
+ "cl:no-full-tree-find":
456
+ "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.",
457
+ "cl:bash-stall-limit":
458
+ "If a Bash command stalls without progress for more than 10 minutes, terminate it and substitute an equivalent, lighter command.",
459
+ "cl:plan-freeze":
460
+ "Approved plan/spec files are frozen — zero modification authority; any change needed is reported to the orchestrator through findings, never edited in place.",
461
+ "cl:atomic-commit":
462
+ "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.",
463
+ "cl:self-validate":
464
+ "Self-validate before returning: run the validation/checks your change requires and record the evidence (command + exit code + result) in the report.",
465
+ } as const;
466
+
467
+ /** The dispatch-prompt data plane — the typed template-contract surface. $version 9
468
+ * is the kind-named doc-anchor shape (INPUT_PLAN / INPUT_SPEC replace the generic
469
+ * INPUT_DOC; INPUT_WAVE_BRIEF), the branch scope anchor BASE_BRANCH, the single
470
+ * prose return contract (`RETURN_PROSE` — nothing downstream parses the child's
471
+ * stdout), and the per-type review criterion shells. The bump from 8 marks the
472
+ * return-shape change (the two-line key-value block retired). */
473
+ export const TEMPLATE_PROMPT = {
474
+ $version: 9,
475
+ modes: MODE_PROMPTS,
476
+ reviews: REVIEW_VARIANTS,
477
+ return: RETURN_ZONE,
478
+ tokens: TOKENS,
479
+ clauses: CLAUSES,
480
+ } as const satisfies TemplatePrompt;
481
+
482
+ /** The ROLE vocabulary — the four work-modes of the dispatch table (§3.5). */
483
+ export const WORK_MODES: readonly WorkMode[] = ["implement", "fix", "review", "docs-fix"];
484
+
485
+ /**
486
+ * The template assembler — the ONE renderer over the typed template-prompt data
487
+ * plane. Construction reads the typed contract (the module's declared data —
488
+ * no file reads, no second copy). render(values) selects the row by the ROLE value
489
+ * (the review mode by ROLE + REVIEW_TYPE) — the row's fixed prefix + the single
490
+ * return contract + its reduced round context (empty-value keys not emitted).
491
+ */
492
+ export class TemplateAssembler {
493
+ readonly #contract: TemplatePrompt;
494
+
495
+ constructor() {
496
+ this.#contract = TEMPLATE_PROMPT;
497
+ }
498
+
499
+ /** The tokens the contract declares (the union across every mode — all zones). */
500
+ declaredTokens(): readonly string[] {
501
+ return this.#contract.tokens.map((token) => token.name);
502
+ }
503
+
504
+ /** The work-modes of the dispatch table — the ROLE vocabulary. */
505
+ workModes(): readonly WorkMode[] {
506
+ return WORK_MODES;
507
+ }
508
+
509
+ /** Assemble the full dispatch template for a role with the slot values — the
510
+ * row's fixed prefix + the single return contract + its reduced round context
511
+ * (empty-value keys omitted). */
512
+ render(values: TemplateValues): string {
513
+ this.#gate(values);
514
+ const row = this.#rowOf(values);
515
+ const zones: Record<string, string> = {
516
+ shell: this.#joinLines(row.shell),
517
+ return: this.#joinLines(this.#contract.return.RETURN_PROSE),
518
+ "round-context": this.#contextLines(row, values),
519
+ };
520
+ return this.#fill([zones.shell, zones.return, zones["round-context"]].join("\n\n"), values);
521
+ }
522
+
523
+ #joinLines(lines: readonly string[]): string {
524
+ return lines.join("\n");
525
+ }
526
+
527
+ /** The row of a ROLE — the review mode's per-type variant (selected by the
528
+ * REVIEW_TYPE discriminant), the work modes from the modes table. */
529
+ #rowOf(values: TemplateValues): ModePromptRow {
530
+ if (values.ROLE === "review") {
531
+ const row = this.#contract.reviews[values.REVIEW_TYPE as TargetType];
532
+ if (row === undefined) {
533
+ throw new Error(
534
+ `template review type not declared: ${values.REVIEW_TYPE === undefined || values.REVIEW_TYPE === "" ? "(missing REVIEW_TYPE)" : values.REVIEW_TYPE}`,
535
+ );
536
+ }
537
+ return row;
538
+ }
539
+ const row = this.#contract.modes[values.ROLE as WorkModeRowKey];
540
+ if (row === undefined) {
541
+ throw new Error(
542
+ `template work-mode not declared: ${values.ROLE === undefined ? "(missing ROLE)" : values.ROLE}`,
543
+ );
544
+ }
545
+ return row;
546
+ }
547
+
548
+ /** The reduced round-context section — the row's subset, a key whose value is
549
+ * empty omitted (only present facts land in the dynamic region). */
550
+ #contextLines(row: ModePromptRow, values: TemplateValues): string {
551
+ const lines: string[] = [];
552
+ for (const line of row.roundContext) {
553
+ const slot = line.match(/\{\{([A-Z0-9_]+)\}\}/)?.[1];
554
+ if (slot !== undefined && values[slot] === "") continue;
555
+ lines.push(line);
556
+ }
557
+ return lines.join("\n");
558
+ }
559
+
560
+ /** The hard gates — a known ROLE (+ its REVIEW_TYPE for reviews), every declared
561
+ * token supplied (empty allowed — a mode's non-consumed slots are legitimately
562
+ * empty and merely not emitted), no undeclared values, the single return
563
+ * contract declared, and every round-context name the mode's shell prose
564
+ * references carried by that mode's layout (shell↔layout consistency). */
565
+ #gate(values: TemplateValues): void {
566
+ const role = values.ROLE;
567
+ const row =
568
+ role === undefined
569
+ ? undefined
570
+ : role === "review"
571
+ ? this.#reviewRow(values)
572
+ : this.#workRow(role);
573
+ if (row === undefined) {
574
+ const message =
575
+ role === "review"
576
+ ? `template review type not declared: ${values.REVIEW_TYPE === undefined || values.REVIEW_TYPE === "" ? "(missing REVIEW_TYPE)" : values.REVIEW_TYPE}`
577
+ : `template work-mode not declared: ${role === undefined ? "(missing ROLE)" : role}`;
578
+ throw new Error(message);
579
+ }
580
+ for (const token of this.#contract.tokens) {
581
+ if (values[token.name] === undefined) {
582
+ throw new Error(`template token ${token.name} (${token.zone}) has no value`);
583
+ }
584
+ }
585
+ for (const name of Object.keys(values)) {
586
+ if (!this.#contract.tokens.some((token) => token.name === name)) {
587
+ throw new Error(`template value provided for undeclared token ${name}`);
588
+ }
589
+ }
590
+ this.#assertShellLayout(row);
591
+ }
592
+
593
+ /** The shell↔layout consistency assertion (§3.6): every round-context name the
594
+ * mode's shell prose references (`INPUT_*` / `OUTPUT_*` / `BASE_BRANCH`) must be
595
+ * carried by that mode's round-context layout ∪ the shared return tail — a shell
596
+ * claiming a slot its layout never carries is a construction error. This closes
597
+ * the "claimed but not carried" blind spot the token gates cannot see (the shell
598
+ * prose is not `{{slot}}`-templated). */
599
+ #assertShellLayout(row: ModePromptRow): void {
600
+ const naming = /\b(?:INPUT_[A-Z0-9_]+|OUTPUT_[A-Z0-9_]+|BASE_BRANCH)\b/g;
601
+ const namesOf = (text: string): string[] => text.match(naming) ?? [];
602
+ const allowed = new Set<string>([
603
+ ...row.roundContext.flatMap((line) => namesOf(line)),
604
+ ...namesOf(this.#joinLines(this.#contract.return.RETURN_PROSE)),
605
+ ]);
606
+ for (const name of new Set(namesOf(this.#joinLines(row.shell)))) {
607
+ if (!allowed.has(name)) {
608
+ throw new Error(
609
+ `template mode ${row.mode} shell references ${name} not carried by its round context`,
610
+ );
611
+ }
612
+ }
613
+ }
614
+
615
+ /** The review variant of a REVIEW_TYPE (verified in the gate). */
616
+ #reviewRow(values: TemplateValues): ModePromptRow | undefined {
617
+ return this.#contract.reviews[values.REVIEW_TYPE as TargetType];
618
+ }
619
+
620
+ /** The work-mode row of a ROLE (verified in the gate). */
621
+ #workRow(role: string): ModePromptRow | undefined {
622
+ return this.#contract.modes[role as WorkModeRowKey];
623
+ }
624
+
625
+ /** Slot resolution — the `{{> cl:…}}` clause partials resolve from the contract's
626
+ * clauses container, the `{{TOKEN}}` slots from the values; any unresolved form
627
+ * (a clause absent from the container, a slot with no value) is a hard error. */
628
+ #fill(text: string, values: TemplateValues): string {
629
+ return text
630
+ .replace(/\{\{> cl:([A-Za-z0-9-]+)\}\}/g, (_match, name: string) => {
631
+ const clause = this.#contract.clauses[`cl:${name}`];
632
+ if (clause === undefined) {
633
+ throw new Error(`template clause cl:${name} not declared`);
634
+ }
635
+ return clause;
636
+ })
637
+ .replace(/\{\{([A-Z0-9_]+)\}\}/g, (_match, name: string) => {
638
+ const value = values[name];
639
+ if (value === undefined) {
640
+ throw new Error(`template slot not resolved: ${name}`);
641
+ }
642
+ return value;
643
+ });
644
+ }
645
+ }