@oscaner-skills/cdd-engine 2.0.0 → 3.0.1

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 (127) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/{src-next/bin.ts → dist/bin.js} +18 -21
  4. package/dist/contract/declare.js +998 -0
  5. package/dist/contract/doc.js +565 -0
  6. package/dist/contract/frontmatter.js +209 -0
  7. package/dist/contract/home-extractors.js +379 -0
  8. package/dist/contract/invariants.js +1030 -0
  9. package/dist/contract/judge.js +109 -0
  10. package/dist/contract/lint.js +206 -0
  11. package/dist/contract/project.js +371 -0
  12. package/dist/contract/skill-anatomy.js +156 -0
  13. package/dist/contract/translate.js +85 -0
  14. package/dist/face/artifacts.js +189 -0
  15. package/dist/face/board-view.js +522 -0
  16. package/dist/face/capsule.js +141 -0
  17. package/dist/face/cli.js +891 -0
  18. package/dist/face/declare.js +241 -0
  19. package/dist/face/gate.js +158 -0
  20. package/dist/face/graph-view.js +66 -0
  21. package/dist/face/host.js +211 -0
  22. package/dist/face/lifecycle.js +603 -0
  23. package/dist/face/preview.js +136 -0
  24. package/dist/face/projection.js +259 -0
  25. package/dist/face/route-render.js +162 -0
  26. package/dist/face/termination.js +482 -0
  27. package/dist/face/words.js +220 -0
  28. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  29. package/dist/infra/doc-roots.js +19 -0
  30. package/dist/infra/git.js +37 -0
  31. package/dist/infra/process.js +22 -0
  32. package/dist/infra/root.js +62 -0
  33. package/dist/infra/runtime.js +85 -0
  34. package/dist/infra/workspace.js +276 -0
  35. package/dist/render/brief.js +82 -0
  36. package/dist/render/issue-body.js +129 -0
  37. package/dist/render/skeleton.js +434 -0
  38. package/dist/render/templates.js +520 -0
  39. package/dist/session/faces.js +38 -0
  40. package/dist/session/graph.js +309 -0
  41. package/dist/session/handoff-schema.js +295 -0
  42. package/dist/session/ledger.js +762 -0
  43. package/dist/session/next.js +211 -0
  44. package/dist/session/preflight.js +194 -0
  45. package/dist/session/round-naming.js +73 -0
  46. package/dist/session/run.js +441 -0
  47. package/dist/session/state.js +8 -0
  48. package/dist/session/wave.js +92 -0
  49. package/package.json +8 -7
  50. package/templates/report/issue-body.json +0 -46
  51. package/src-next/__tests__/bin.test.ts +0 -128
  52. package/src-next/__tests__/smoke.integration.test.ts +0 -202
  53. package/src-next/__tests__/zero-dep.test.ts +0 -134
  54. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -238
  55. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -153
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -173
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -89
  58. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -225
  59. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -155
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -175
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -85
  62. package/src-next/contract/__tests__/declare.test.ts +0 -242
  63. package/src-next/contract/__tests__/doc.test.ts +0 -358
  64. package/src-next/contract/__tests__/judge.test.ts +0 -873
  65. package/src-next/contract/__tests__/lint.test.ts +0 -314
  66. package/src-next/contract/__tests__/project.test.ts +0 -419
  67. package/src-next/contract/__tests__/translate.test.ts +0 -96
  68. package/src-next/contract/declare.ts +0 -983
  69. package/src-next/contract/doc.ts +0 -753
  70. package/src-next/contract/invariants.ts +0 -1268
  71. package/src-next/contract/judge.ts +0 -142
  72. package/src-next/contract/lint.ts +0 -275
  73. package/src-next/contract/project.ts +0 -596
  74. package/src-next/contract/skill-anatomy.ts +0 -273
  75. package/src-next/contract/translate.ts +0 -113
  76. package/src-next/face/__tests__/board-view.test.ts +0 -948
  77. package/src-next/face/__tests__/capsule.test.ts +0 -276
  78. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -102
  79. package/src-next/face/__tests__/cli.test.ts +0 -4643
  80. package/src-next/face/__tests__/face.test.ts +0 -289
  81. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  82. package/src-next/face/__tests__/host.test.ts +0 -24
  83. package/src-next/face/__tests__/negation.ts +0 -6
  84. package/src-next/face/__tests__/projection.test.ts +0 -301
  85. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
  86. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  87. package/src-next/face/artifacts.ts +0 -195
  88. package/src-next/face/board-view.ts +0 -662
  89. package/src-next/face/capsule.ts +0 -149
  90. package/src-next/face/cli.ts +0 -819
  91. package/src-next/face/declare.ts +0 -326
  92. package/src-next/face/gate.ts +0 -170
  93. package/src-next/face/graph-view.ts +0 -74
  94. package/src-next/face/host.ts +0 -326
  95. package/src-next/face/lifecycle.ts +0 -700
  96. package/src-next/face/projection.ts +0 -282
  97. package/src-next/face/route-render.ts +0 -160
  98. package/src-next/face/words.ts +0 -296
  99. package/src-next/infra/__tests__/infra.test.ts +0 -287
  100. package/src-next/infra/git.ts +0 -39
  101. package/src-next/infra/process.ts +0 -34
  102. package/src-next/infra/runtime.ts +0 -185
  103. package/src-next/infra/workspace.ts +0 -232
  104. package/src-next/render/__tests__/render.test.ts +0 -499
  105. package/src-next/render/__tests__/skeleton.test.ts +0 -466
  106. package/src-next/render/brief.ts +0 -121
  107. package/src-next/render/issue-body.ts +0 -159
  108. package/src-next/render/skeleton.ts +0 -437
  109. package/src-next/render/templates.ts +0 -650
  110. package/src-next/session/__tests__/graph.test.ts +0 -270
  111. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  112. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  113. package/src-next/session/__tests__/ledger.test.ts +0 -744
  114. package/src-next/session/__tests__/next.test.ts +0 -368
  115. package/src-next/session/__tests__/preflight.test.ts +0 -491
  116. package/src-next/session/__tests__/run.test.ts +0 -1014
  117. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  118. package/src-next/session/__tests__/wave.test.ts +0 -469
  119. package/src-next/session/faces.ts +0 -110
  120. package/src-next/session/graph.ts +0 -411
  121. package/src-next/session/handoff-schema.ts +0 -373
  122. package/src-next/session/ledger.ts +0 -1004
  123. package/src-next/session/next.ts +0 -192
  124. package/src-next/session/preflight.ts +0 -240
  125. package/src-next/session/run.ts +0 -606
  126. package/src-next/session/state.ts +0 -30
  127. 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 work 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
+ };