@oscaner-skills/cdd-engine 3.0.0 → 3.1.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 (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +149 -0
  15. package/dist/face/cli.js +893 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +702 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +504 -0
  25. package/dist/face/words.js +258 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +453 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,520 @@
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
+ import { DISPATCH } from "../face/host.js";
51
+ /** The nominal fixed-frame cells shared by every shell (byte-identical words — the
52
+ * fixed prefix is read on every dispatch, so every word costs child context). */
53
+ const FRAME_ITEMS = [
54
+ "**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.",
55
+ "**Scope lock:** use only this round's inputs in `## Round context`. No full plan reads. No extra features, no tangential refactors, no scope creep.",
56
+ ];
57
+ /** The shared work-mode tail cell — the evidence gate (implement/fix carry it;
58
+ * docs-fix carries no evidence file — zero per-mode duplication, §3.7). The
59
+ * evidence file's concrete name rides the injected schema's preamble (per-family
60
+ * prefix), never this fixed text. */
61
+ 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.";
62
+ /** The discipline-clause cells shared by every shell (the `{{> cl:…}}` partials
63
+ * resolve from the single clause container — the same bytes, one per shell). */
64
+ const LICENSE_ITEMS = [
65
+ "",
66
+ "**Discipline clauses:**",
67
+ "- {{> cl:english-comments}}",
68
+ "- {{> cl:eof-newline}}",
69
+ "- {{> cl:no-full-tree-find}}",
70
+ "- {{> cl:bash-stall-limit}}",
71
+ "- {{> cl:plan-freeze}}",
72
+ "- {{> cl:atomic-commit}}",
73
+ "- {{> cl:self-validate}}",
74
+ ];
75
+ /** The `## Handoff schema` section — the injected writable-subset fence at every
76
+ * shell's tail (the {{HANDOFF_SCHEMA}} slot; the face's sets differ per mode, so
77
+ * the section's bytes are fixed per mode — §3.5 prefix-cache grouping). */
78
+ const SCHEMA_SECTION = ["", "## Handoff schema", "", "{{HANDOFF_SCHEMA}}"];
79
+ /** The implement row's fixed prefix — header + instructions + the shared work tail. */
80
+ const IMPLEMENT_SHELL = [
81
+ "# CDD dispatch — implement round",
82
+ "",
83
+ "## Instructions",
84
+ "",
85
+ ...FRAME_ITEMS,
86
+ `**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).`,
87
+ EVIDENCE_ITEM,
88
+ ...LICENSE_ITEMS,
89
+ ...SCHEMA_SECTION,
90
+ ];
91
+ /** The fix row's fixed prefix — header + instructions + the shared work tail. */
92
+ const FIX_TYPED_INSTRUCTIONS = [
93
+ "**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.",
94
+ "**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.",
95
+ ];
96
+ /** The fix row's fixed prefix — header + instructions + the shared work tail. */
97
+ const FIX_SHELL = [
98
+ "# CDD dispatch — fix round",
99
+ "",
100
+ "## Instructions",
101
+ "",
102
+ ...FRAME_ITEMS,
103
+ ...FIX_TYPED_INSTRUCTIONS,
104
+ "**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).",
105
+ EVIDENCE_ITEM,
106
+ ...LICENSE_ITEMS,
107
+ // T5 (v0.3) — The delivery face's ONE strict-schema sentence: every top-level draft
108
+ // field comes from the `## Handoff schema` declared properties (the fields'
109
+ // single source is the injected fence below — never a second enumeration in the
110
+ // shell prose; a fix child that mirrors the source review carrier's top-level
111
+ // shape trips the engine's read-back BLOCK, so the sentence names the schema as
112
+ // the field source explicitly).
113
+ "**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.",
114
+ ...SCHEMA_SECTION,
115
+ ];
116
+ /** The docs-fix row's fixed prefix — header + instructions (no evidence — the
117
+ * docs-fix face writes no evidence file). */
118
+ const DOCS_FIX_SHELL = [
119
+ "# CDD dispatch — docs-fix round",
120
+ "",
121
+ "## Instructions",
122
+ "",
123
+ ...FRAME_ITEMS,
124
+ "**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).",
125
+ ...LICENSE_ITEMS,
126
+ // T5 (v0.3) — The findings face's ONE strict-schema sentence: same schema-first
127
+ // directive as the work shell, naming the required `findings` (carried over from
128
+ // the source review carrier verbatim — the required key is told how to fill, so
129
+ // the sentence never contradicts the findings carrier's own required gate; the
130
+ // work shell's field list is never copied here, and no field enumeration rides
131
+ // the findings shell's prose either).
132
+ "**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.",
133
+ ...SCHEMA_SECTION,
134
+ ];
135
+ /** The review variants' shared instruction text — the review's mode rule (the
136
+ * criteria body + the lens vocabulary ride per-type fixed items below). */
137
+ 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`. 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.";
138
+ /** The review mode's shared reduced tail — the only dynamic region of every review
139
+ * variant (the criteria/lens are fixed-prefix per type, never here). Each review
140
+ * type carries its own judged-doc referent (wave → `INPUT_WAVE_BRIEF`; plan/branch
141
+ * → `INPUT_PLAN`; spec → `INPUT_SPEC`); the branch review additionally carries
142
+ * `BASE_BRANCH` (the scope anchor). Empty slots are dropped by the assembler. */
143
+ const REVIEW_CONTEXT = [
144
+ "## Round context",
145
+ "",
146
+ "- `ROLE`: {{ROLE}}",
147
+ "- `WAVE`: {{WAVE}}",
148
+ "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
149
+ "- `INPUT_PLAN`: {{INPUT_PLAN}}",
150
+ "- `INPUT_SPEC`: {{INPUT_SPEC}}",
151
+ "- `BASE_BRANCH`: {{BASE_BRANCH}}",
152
+ "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
153
+ "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
154
+ "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
155
+ "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
156
+ ];
157
+ /** The work-mode dispatch rows — implement / fix / docs-fix (§3.5; the review rows
158
+ * are REVIEW_VARIANTS). */
159
+ const MODE_PROMPTS = {
160
+ implement: {
161
+ mode: "implement",
162
+ shell: IMPLEMENT_SHELL,
163
+ roundContext: [
164
+ "## Round context",
165
+ "",
166
+ "- `ROLE`: {{ROLE}}",
167
+ "- `WAVE`: {{WAVE}}",
168
+ "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
169
+ // find #4 + #5 — the plan's ## Constraints rides the wave brief mirror;
170
+ // the OUTPUT_* write paths are prescribed (the {family}-{key}- canonical names)
171
+ "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
172
+ "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
173
+ "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
174
+ "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
175
+ "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
176
+ ],
177
+ },
178
+ fix: {
179
+ mode: "fix",
180
+ shell: FIX_SHELL,
181
+ roundContext: [
182
+ "## Round context",
183
+ "",
184
+ "- `ROLE`: {{ROLE}}",
185
+ "- `WAVE`: {{WAVE}}",
186
+ "- `INPUT_WAVE_BRIEF`: {{INPUT_WAVE_BRIEF}}",
187
+ "- `INPUT_PLAN`: {{INPUT_PLAN}}",
188
+ "- `INPUT_SPEC`: {{INPUT_SPEC}}",
189
+ "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
190
+ "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
191
+ "- `OUTPUT_EVIDENCE`: {{OUTPUT_EVIDENCE}}",
192
+ "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
193
+ "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
194
+ "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
195
+ ],
196
+ },
197
+ "docs-fix": {
198
+ mode: "docs-fix",
199
+ shell: DOCS_FIX_SHELL,
200
+ roundContext: [
201
+ "## Round context",
202
+ "",
203
+ "- `ROLE`: {{ROLE}}",
204
+ "- `WAVE`: {{WAVE}}",
205
+ "- `INPUT_PLAN`: {{INPUT_PLAN}}",
206
+ "- `INPUT_SPEC`: {{INPUT_SPEC}}",
207
+ "- `INPUT_REVIEWS`: {{INPUT_REVIEWS}}",
208
+ "- `OUTPUT_REPORT`: {{OUTPUT_REPORT}}",
209
+ "- `OUTPUT_HANDOFF`: {{OUTPUT_HANDOFF}}",
210
+ "- `WORKSPACE_DIR`: {{WORKSPACE_DIR}}",
211
+ "- `WORKSPACE_ID`: {{WORKSPACE_ID}}",
212
+ ],
213
+ },
214
+ };
215
+ /** The four-type review criteria — the review prompts' fixed criteria body (P4; the
216
+ * spec/plan URC rows migrated from the dispatch table at the v1.8 closeout — their
217
+ * single typed home). */
218
+ export const REVIEWS = {
219
+ wave: {
220
+ lensEnum: ["standards", "spec", "buildability"],
221
+ axesGuide: "Standards axis (repo coding standards + code-review smell baseline) + Spec axis (wave brief / plan requirements) + Buildability axis (the reviewer explicitly runs the repository's typecheck command — `tsc --noEmit`, or the repo equivalent — AND its test command; every buildability finding self-reports the dual evidence, both commands ran) + Scope axis (changed-surface reasonableness): run `git diff origin/<BASE_BRANCH>..HEAD` yourself (BASE_BRANCH as named in the round context; on a missing artifact judge the working tree) — every changed file must fall within the wave brief's file surface (`**Files:**` seams) or be attributable to the plan / reviewed intent; an unattributable changed file is a candidate finding (severity by your judgment). The reviewer is the changed-surface judge — the engine reconciles nothing. 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.",
222
+ },
223
+ branch: {
224
+ lensEnum: ["standards", "spec", "buildability"],
225
+ 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. 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).",
226
+ },
227
+ spec: {
228
+ lensEnum: ["completeness", "consistency", "clarity"],
229
+ axesGuide: "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).",
230
+ },
231
+ plan: {
232
+ lensEnum: ["completeness", "decomposition", "buildability"],
233
+ axesGuide: "Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + spec conformance — the plan is judged against its design spec at `INPUT_SPEC` (the plan's `spec` front-matter target): every spec requirement must map to a task, and a spec requirement with no owning task is a completeness finding + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + 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).",
234
+ },
235
+ };
236
+ /** The per-type facts the review variants compose at module-const time (the lens
237
+ * vocabularies + the criteria bodies — single data references, never restates). */
238
+ const REVIEWS_WAVE_LENS = REVIEWS.wave.lensEnum.join(" | ");
239
+ const REVIEWS_BRANCH_LENS = REVIEWS.branch.lensEnum.join(" | ");
240
+ const REVIEWS_SPEC_LENS = REVIEWS.spec.lensEnum.join(" | ");
241
+ const REVIEWS_PLAN_LENS = REVIEWS.plan.lensEnum.join(" | ");
242
+ const REVIEW_WAVE_AXES = REVIEWS.wave.axesGuide;
243
+ const REVIEW_BRANCH_AXES = REVIEWS.branch.axesGuide;
244
+ const REVIEW_SPEC_URC = REVIEWS.spec.axesGuide;
245
+ const REVIEW_PLAN_URC = REVIEWS.plan.axesGuide;
246
+ /** The review mode's four per-type rows (§3.7) — each variant's fixed prefix folds
247
+ * its criteria + lens INLINE (the `INPUT_CRITERIA`/`INPUT_LENS` round-context
248
+ * tokens are gone), and shares the REVIEW_CONTEXT dynamic tail. */
249
+ const REVIEW_VARIANTS = {
250
+ wave: {
251
+ mode: "review",
252
+ shell: [
253
+ "# CDD dispatch — review round",
254
+ "",
255
+ "## Instructions",
256
+ "",
257
+ ...FRAME_ITEMS,
258
+ REVIEW_ITEM,
259
+ `**Lens labels:** one of \`${REVIEWS_WAVE_LENS}\` — every finding MUST carry its \`lens\`.`,
260
+ `**Criteria — wave:** ${REVIEW_WAVE_AXES}`,
261
+ ...LICENSE_ITEMS,
262
+ ...SCHEMA_SECTION,
263
+ ],
264
+ roundContext: REVIEW_CONTEXT,
265
+ },
266
+ branch: {
267
+ mode: "review",
268
+ shell: [
269
+ "# CDD dispatch — review round",
270
+ "",
271
+ "## Instructions",
272
+ "",
273
+ ...FRAME_ITEMS,
274
+ REVIEW_ITEM,
275
+ `**Lens labels:** one of \`${REVIEWS_BRANCH_LENS}\` — every finding MUST carry its \`lens\`.`,
276
+ `**Criteria — branch:** ${REVIEW_BRANCH_AXES}`,
277
+ ...LICENSE_ITEMS,
278
+ ...SCHEMA_SECTION,
279
+ ],
280
+ roundContext: REVIEW_CONTEXT,
281
+ },
282
+ spec: {
283
+ mode: "review",
284
+ shell: [
285
+ "# CDD dispatch — review round",
286
+ "",
287
+ "## Instructions",
288
+ "",
289
+ ...FRAME_ITEMS,
290
+ REVIEW_ITEM,
291
+ `**Lens labels:** one of \`${REVIEWS_SPEC_LENS}\` — every finding MUST carry its \`lens\`.`,
292
+ `**Criteria — spec:** ${REVIEW_SPEC_URC}`,
293
+ ...LICENSE_ITEMS,
294
+ ...SCHEMA_SECTION,
295
+ ],
296
+ roundContext: REVIEW_CONTEXT,
297
+ },
298
+ plan: {
299
+ mode: "review",
300
+ shell: [
301
+ "# CDD dispatch — review round",
302
+ "",
303
+ "## Instructions",
304
+ "",
305
+ ...FRAME_ITEMS,
306
+ REVIEW_ITEM,
307
+ `**Lens labels:** one of \`${REVIEWS_PLAN_LENS}\` — every finding MUST carry its \`lens\`.`,
308
+ `**Criteria — plan:** ${REVIEW_PLAN_URC}`,
309
+ ...LICENSE_ITEMS,
310
+ ...SCHEMA_SECTION,
311
+ ],
312
+ roundContext: REVIEW_CONTEXT,
313
+ },
314
+ };
315
+ /** The `## Return` zone — the single plain-prose contract block (P11: the child
316
+ * narrates the round in prose; nothing downstream parses its stdout — the handoff
317
+ * draft at `OUTPUT_HANDOFF` is the round's machine-readable result). */
318
+ const RETURN_ZONE = {
319
+ RETURN_PROSE: [
320
+ "## Return",
321
+ "",
322
+ "Report in a few plain sentences what this round did, whether it succeeded, and — if it",
323
+ "did not — what blocked it. Nothing downstream parses this text; the handoff draft at",
324
+ "`OUTPUT_HANDOFF` is the round's machine-readable result. Do not emit key-value lines,",
325
+ "JSON, or any fixed block.",
326
+ "",
327
+ "(fail: an uncaught failure → exit non-zero with a one-line reason)",
328
+ ],
329
+ };
330
+ /** The token registry — the union across every mode's round context + the shell's
331
+ * schema slot (the v1.8 normalized vocabulary; the assembly face supplies every
332
+ * declared slot, empty where the mode does not consume it — the round-context
333
+ * renderer drops the empty-valued lines). REVIEW_TYPE is the review-mode row
334
+ * selector (supplied but never rendered). */
335
+ const TOKENS = [
336
+ { name: "BASE_BRANCH", zone: "round-context" },
337
+ { name: "HANDOFF_SCHEMA", zone: "shell" },
338
+ { name: "INPUT_PLAN", zone: "round-context" },
339
+ { name: "INPUT_SPEC", zone: "round-context" },
340
+ { name: "INPUT_REVIEWS", zone: "round-context" },
341
+ { name: "INPUT_WAVE_BRIEF", zone: "round-context" },
342
+ // find #5 — the prescribed artifact write paths (the {family}-{key}-{artifact}
343
+ // single naming; the brief is a pure read input with no write slot).
344
+ { name: "OUTPUT_REPORT", zone: "round-context" },
345
+ { name: "OUTPUT_EVIDENCE", zone: "round-context" },
346
+ { name: "OUTPUT_HANDOFF", zone: "round-context" },
347
+ { name: "REVIEW_TYPE", zone: "round-context" },
348
+ { name: "ROLE", zone: "round-context" },
349
+ { name: "WAVE", zone: "round-context" },
350
+ { name: "WORKSPACE_DIR", zone: "round-context" },
351
+ { name: "WORKSPACE_ID", zone: "round-context" },
352
+ ];
353
+ /** The clause partials — the `{{> cl:…}}` forms of the discipline clauses. */
354
+ export const CLAUSES = {
355
+ "cl:english-comments": "Write code comments and shipped prose in English only — English-primary (no other-language comment blocks, no translated mirrors).",
356
+ "cl:eof-newline": "Every text file must end with exactly one newline (EOF newline): no missing final newline and no trailing blank lines.",
357
+ "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.",
358
+ "cl:bash-stall-limit": "If a Bash command stalls without progress for more than 10 minutes, terminate it and substitute an equivalent, lighter command.",
359
+ "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.",
360
+ "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.",
361
+ "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.",
362
+ };
363
+ /** The dispatch-prompt data plane — the typed template-contract surface. $version 9
364
+ * is the kind-named doc-anchor shape (INPUT_PLAN / INPUT_SPEC replace the generic
365
+ * INPUT_DOC; INPUT_WAVE_BRIEF), the branch scope anchor BASE_BRANCH, the single
366
+ * prose return contract (`RETURN_PROSE` — nothing downstream parses the child's
367
+ * stdout), and the per-type review criterion shells. The bump from 8 marks the
368
+ * return-shape change (the two-line key-value block retired). */
369
+ export const TEMPLATE_PROMPT = {
370
+ $version: 9,
371
+ modes: MODE_PROMPTS,
372
+ reviews: REVIEW_VARIANTS,
373
+ return: RETURN_ZONE,
374
+ tokens: TOKENS,
375
+ clauses: CLAUSES,
376
+ };
377
+ /** The ROLE vocabulary — the four work-modes of the dispatch table (§3.5). */
378
+ export const WORK_MODES = ["implement", "fix", "review", "docs-fix"];
379
+ /**
380
+ * The template assembler — the ONE renderer over the typed template-prompt data
381
+ * plane. Construction reads the typed contract (the module's declared data —
382
+ * no file reads, no second copy). render(values) selects the row by the ROLE value
383
+ * (the review mode by ROLE + REVIEW_TYPE) — the row's fixed prefix + the single
384
+ * return contract + its reduced round context (empty-value keys not emitted).
385
+ */
386
+ export class TemplateAssembler {
387
+ #contract;
388
+ constructor() {
389
+ this.#contract = TEMPLATE_PROMPT;
390
+ }
391
+ /** The tokens the contract declares (the union across every mode — all zones). */
392
+ declaredTokens() {
393
+ return this.#contract.tokens.map((token) => token.name);
394
+ }
395
+ /** The work-modes of the dispatch table — the ROLE vocabulary. */
396
+ workModes() {
397
+ return WORK_MODES;
398
+ }
399
+ /** Assemble the full dispatch template for a role with the slot values — the
400
+ * row's fixed prefix + the single return contract + its reduced round context
401
+ * (empty-value keys omitted). */
402
+ render(values) {
403
+ this.#gate(values);
404
+ const row = this.#rowOf(values);
405
+ const zones = {
406
+ shell: this.#joinLines(row.shell),
407
+ return: this.#joinLines(this.#contract.return.RETURN_PROSE),
408
+ "round-context": this.#contextLines(row, values),
409
+ };
410
+ return this.#fill([zones.shell, zones.return, zones["round-context"]].join("\n\n"), values);
411
+ }
412
+ #joinLines(lines) {
413
+ return lines.join("\n");
414
+ }
415
+ /** The row of a ROLE — the review mode's per-type variant (selected by the
416
+ * REVIEW_TYPE discriminant), the work modes from the modes table. */
417
+ #rowOf(values) {
418
+ if (values.ROLE === "review") {
419
+ const row = this.#contract.reviews[values.REVIEW_TYPE];
420
+ if (row === undefined) {
421
+ throw new Error(`template review type not declared: ${values.REVIEW_TYPE === undefined || values.REVIEW_TYPE === "" ? "(missing REVIEW_TYPE)" : values.REVIEW_TYPE}`);
422
+ }
423
+ return row;
424
+ }
425
+ const row = this.#contract.modes[values.ROLE];
426
+ if (row === undefined) {
427
+ throw new Error(`template work-mode not declared: ${values.ROLE === undefined ? "(missing ROLE)" : values.ROLE}`);
428
+ }
429
+ return row;
430
+ }
431
+ /** The reduced round-context section — the row's subset, a key whose value is
432
+ * empty omitted (only present facts land in the dynamic region). */
433
+ #contextLines(row, values) {
434
+ const lines = [];
435
+ for (const line of row.roundContext) {
436
+ const slot = line.match(/\{\{([A-Z0-9_]+)\}\}/)?.[1];
437
+ if (slot !== undefined && values[slot] === "")
438
+ continue;
439
+ lines.push(line);
440
+ }
441
+ return lines.join("\n");
442
+ }
443
+ /** The hard gates — a known ROLE (+ its REVIEW_TYPE for reviews), every declared
444
+ * token supplied (empty allowed — a mode's non-consumed slots are legitimately
445
+ * empty and merely not emitted), no undeclared values, the single return
446
+ * contract declared, and every round-context name the mode's shell prose
447
+ * references carried by that mode's layout (shell↔layout consistency). */
448
+ #gate(values) {
449
+ const role = values.ROLE;
450
+ const row = role === undefined
451
+ ? undefined
452
+ : role === "review"
453
+ ? this.#reviewRow(values)
454
+ : this.#workRow(role);
455
+ if (row === undefined) {
456
+ const message = role === "review"
457
+ ? `template review type not declared: ${values.REVIEW_TYPE === undefined || values.REVIEW_TYPE === "" ? "(missing REVIEW_TYPE)" : values.REVIEW_TYPE}`
458
+ : `template work-mode not declared: ${role === undefined ? "(missing ROLE)" : role}`;
459
+ throw new Error(message);
460
+ }
461
+ for (const token of this.#contract.tokens) {
462
+ if (values[token.name] === undefined) {
463
+ throw new Error(`template token ${token.name} (${token.zone}) has no value`);
464
+ }
465
+ }
466
+ for (const name of Object.keys(values)) {
467
+ if (!this.#contract.tokens.some((token) => token.name === name)) {
468
+ throw new Error(`template value provided for undeclared token ${name}`);
469
+ }
470
+ }
471
+ this.#assertShellLayout(row);
472
+ }
473
+ /** The shell↔layout consistency assertion (§3.6): every round-context name the
474
+ * mode's shell prose references (`INPUT_*` / `OUTPUT_*` / `BASE_BRANCH`) must be
475
+ * carried by that mode's round-context layout ∪ the shared return tail — a shell
476
+ * claiming a slot its layout never carries is a construction error. This closes
477
+ * the "claimed but not carried" blind spot the token gates cannot see (the shell
478
+ * prose is not `{{slot}}`-templated). */
479
+ #assertShellLayout(row) {
480
+ const naming = /\b(?:INPUT_[A-Z0-9_]+|OUTPUT_[A-Z0-9_]+|BASE_BRANCH)\b/g;
481
+ const namesOf = (text) => text.match(naming) ?? [];
482
+ const allowed = new Set([
483
+ ...row.roundContext.flatMap((line) => namesOf(line)),
484
+ ...namesOf(this.#joinLines(this.#contract.return.RETURN_PROSE)),
485
+ ]);
486
+ for (const name of new Set(namesOf(this.#joinLines(row.shell)))) {
487
+ if (!allowed.has(name)) {
488
+ throw new Error(`template mode ${row.mode} shell references ${name} not carried by its round context`);
489
+ }
490
+ }
491
+ }
492
+ /** The review variant of a REVIEW_TYPE (verified in the gate). */
493
+ #reviewRow(values) {
494
+ return this.#contract.reviews[values.REVIEW_TYPE];
495
+ }
496
+ /** The work-mode row of a ROLE (verified in the gate). */
497
+ #workRow(role) {
498
+ return this.#contract.modes[role];
499
+ }
500
+ /** Slot resolution — the `{{> cl:…}}` clause partials resolve from the contract's
501
+ * clauses container, the `{{TOKEN}}` slots from the values; any unresolved form
502
+ * (a clause absent from the container, a slot with no value) is a hard error. */
503
+ #fill(text, values) {
504
+ return text
505
+ .replace(/\{\{> cl:([A-Za-z0-9-]+)\}\}/g, (_match, name) => {
506
+ const clause = this.#contract.clauses[`cl:${name}`];
507
+ if (clause === undefined) {
508
+ throw new Error(`template clause cl:${name} not declared`);
509
+ }
510
+ return clause;
511
+ })
512
+ .replace(/\{\{([A-Z0-9_]+)\}\}/g, (_match, name) => {
513
+ const value = values[name];
514
+ if (value === undefined) {
515
+ throw new Error(`template slot not resolved: ${name}`);
516
+ }
517
+ return value;
518
+ });
519
+ }
520
+ }
@@ -0,0 +1,38 @@
1
+ // packages/cdd-engine/src-next/session/faces.ts
2
+ // T8 — the target-type faces data table (design spec §3.3: the parameterized single
3
+ // lifecycle). The three old near-isomorphic lifecycles (task / branch / docs)
4
+ // converge into ONE lifecycle class whose per-type variance lives in this table:
5
+ // each target type (task | branch | spec | plan) carries its audit target, the
6
+ // product face (the review-lead round mode) and the next-hop consumption semantics.
7
+ // The lifecycle reads the row through the same class — a new target type is a table
8
+ // row, never a lifecycle edit.
9
+ //
10
+ // Module-level exports are types / the table const — zero behavior-carrying bare
11
+ // functions (the plan's zero-bare-function discipline).
12
+ /** The four target-type faces — one row per CLI `--type` value (the single table). */
13
+ export const targetFaces = {
14
+ wave: {
15
+ type: "wave",
16
+ audit: { kind: "task-graph" },
17
+ product: { reviewLead: "review" },
18
+ nextSemantics: { batch: true },
19
+ },
20
+ branch: {
21
+ type: "branch",
22
+ audit: { kind: "branch-tree" },
23
+ product: { reviewLead: "branch-review" },
24
+ nextSemantics: { batch: false },
25
+ },
26
+ spec: {
27
+ type: "spec",
28
+ audit: { kind: "doc-path" },
29
+ product: { reviewLead: "review" },
30
+ nextSemantics: { batch: false },
31
+ },
32
+ plan: {
33
+ type: "plan",
34
+ audit: { kind: "doc-path" },
35
+ product: { reviewLead: "review" },
36
+ nextSemantics: { batch: false },
37
+ },
38
+ };