@oscaner-skills/cdd-engine 1.0.0 → 2.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 (99) hide show
  1. package/README.md +9 -8
  2. package/README.zh-CN.md +9 -8
  3. package/package.json +15 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/smoke.integration.test.ts +202 -0
  6. package/src-next/__tests__/zero-dep.test.ts +134 -0
  7. package/src-next/bin.ts +61 -0
  8. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
  9. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
  10. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
  12. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
  16. package/src-next/contract/__tests__/declare.test.ts +242 -0
  17. package/src-next/contract/__tests__/doc.test.ts +358 -0
  18. package/src-next/contract/__tests__/judge.test.ts +873 -0
  19. package/src-next/contract/__tests__/lint.test.ts +314 -0
  20. package/src-next/contract/__tests__/project.test.ts +419 -0
  21. package/src-next/contract/__tests__/translate.test.ts +96 -0
  22. package/src-next/contract/declare.ts +983 -0
  23. package/src-next/contract/doc.ts +753 -0
  24. package/src-next/contract/invariants.ts +1268 -0
  25. package/src-next/contract/judge.ts +142 -0
  26. package/src-next/contract/lint.ts +275 -0
  27. package/src-next/contract/project.ts +596 -0
  28. package/src-next/contract/skill-anatomy.ts +273 -0
  29. package/src-next/contract/translate.ts +113 -0
  30. package/src-next/face/__tests__/board-view.test.ts +948 -0
  31. package/src-next/face/__tests__/capsule.test.ts +276 -0
  32. package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
  33. package/src-next/face/__tests__/cli.test.ts +4643 -0
  34. package/src-next/face/__tests__/face.test.ts +289 -0
  35. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  36. package/src-next/face/__tests__/host.test.ts +24 -0
  37. package/src-next/face/__tests__/negation.ts +6 -0
  38. package/src-next/face/__tests__/projection.test.ts +301 -0
  39. package/src-next/face/__tests__/sync-runner.test.ts +70 -0
  40. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  41. package/src-next/face/artifacts.ts +195 -0
  42. package/src-next/face/board-view.ts +662 -0
  43. package/src-next/face/capsule.ts +149 -0
  44. package/src-next/face/cli.ts +819 -0
  45. package/src-next/face/declare.ts +326 -0
  46. package/src-next/face/gate.ts +170 -0
  47. package/src-next/face/graph-view.ts +74 -0
  48. package/src-next/face/host.ts +326 -0
  49. package/src-next/face/lifecycle.ts +700 -0
  50. package/src-next/face/projection.ts +282 -0
  51. package/src-next/face/route-render.ts +160 -0
  52. package/src-next/face/words.ts +296 -0
  53. package/src-next/infra/__tests__/infra.test.ts +287 -0
  54. package/src-next/infra/config.ts +42 -0
  55. package/src-next/infra/git.ts +39 -0
  56. package/src-next/infra/process.ts +34 -0
  57. package/src-next/infra/runtime.ts +185 -0
  58. package/src-next/infra/workspace.ts +232 -0
  59. package/src-next/render/__tests__/render.test.ts +499 -0
  60. package/src-next/render/__tests__/skeleton.test.ts +466 -0
  61. package/src-next/render/brief.ts +121 -0
  62. package/src-next/render/issue-body.ts +159 -0
  63. package/src-next/render/skeleton.ts +437 -0
  64. package/src-next/render/templates.ts +650 -0
  65. package/src-next/session/__tests__/graph.test.ts +270 -0
  66. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  67. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  68. package/src-next/session/__tests__/ledger.test.ts +744 -0
  69. package/src-next/session/__tests__/next.test.ts +368 -0
  70. package/src-next/session/__tests__/preflight.test.ts +491 -0
  71. package/src-next/session/__tests__/run.test.ts +1014 -0
  72. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  73. package/src-next/session/__tests__/wave.test.ts +469 -0
  74. package/src-next/session/faces.ts +110 -0
  75. package/src-next/session/graph.ts +411 -0
  76. package/src-next/session/handoff-schema.ts +373 -0
  77. package/src-next/session/ledger.ts +1004 -0
  78. package/src-next/session/next.ts +192 -0
  79. package/src-next/session/preflight.ts +240 -0
  80. package/src-next/session/run.ts +606 -0
  81. package/src-next/session/state.ts +30 -0
  82. package/src-next/session/wave.ts +139 -0
  83. package/templates/report/issue-body.json +18 -20
  84. package/dist/chunks/branch.mjs +0 -480
  85. package/dist/chunks/docs.mjs +0 -253
  86. package/dist/chunks/task.mjs +0 -913
  87. package/dist/cli.mjs +0 -5457
  88. package/dist/documents/schema/add-phase-protocol.json +0 -126
  89. package/dist/documents/schema/overall.json +0 -361
  90. package/dist/documents/schema/phase-spec.json +0 -145
  91. package/dist/documents/schema/plan.json +0 -191
  92. package/dist/documents/schema/skill-anatomy.json +0 -233
  93. package/dist/resources/harness-registry.json +0 -49
  94. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  95. package/templates/engine-config.json +0 -302
  96. package/templates/schema/cache-profile-schema.json +0 -23
  97. package/templates/schema/docs-handoff-schema.json +0 -129
  98. package/templates/schema/task-handoff-schema.json +0 -332
  99. package/templates/template-contract.json +0 -231
@@ -0,0 +1,466 @@
1
+ // packages/cdd-engine/src-next/render/__tests__/skeleton.test.ts
2
+ // The SkeletonAssembler suite (P2 — the `cdd schema get <type> --output skeleton`
3
+ // render face, spec §3/§4.1):
4
+ // · the four doc skeletons render the complete structural scaffolds — byte-
5
+ // pinned from the P2 first version (the assembler's date is the injectable
6
+ // run-day truth, fixed here — never a live clock);
7
+ // · the placeholder-anchoring probes (spec §4.1): pure content slots take
8
+ // `:::fill <slot>`, the link-shaped anchors the placeholder links, the
9
+ // pattern-typed rows the generator truths, and `:::fill` never lands on a
10
+ // structure/truth/link/table-header position;
11
+ // · the EOF rule — render() never ends with a newline or a blank line; the
12
+ // CLI's single appended `\n` leaves a redirected fixture with exactly one
13
+ // final newline.
14
+
15
+ import { describe, expect, it } from "vitest";
16
+ import { declaredRegistries } from "../../contract/declare.ts";
17
+ import type { DocKey, DocSkeleton } from "../../contract/project.ts";
18
+ import { Projector } from "../../contract/project.ts";
19
+ import { SkeletonAssembler } from "../skeleton.ts";
20
+
21
+ /** The fixed run date — the injectable run-day truth (no live clock in the pins). */
22
+ const DATE = "2026-10-11";
23
+ const PROJECTOR = new Projector(declaredRegistries);
24
+ const SKELETONS = PROJECTOR.skeleton();
25
+
26
+ /** The fixed-date rendered skeleton bytes of one doc type. */
27
+ const renderOf = (key: DocKey): string => new SkeletonAssembler(SKELETONS[key], DATE).render();
28
+
29
+ /** The registered required anchors of one doc type (the live registry). */
30
+ const requiredAnchorsOf = (key: DocKey): readonly string[] =>
31
+ declaredRegistries[key].elements
32
+ .filter((element) => element.presence === "required")
33
+ .map((element) => element.anchor);
34
+
35
+ /** The per-anchor skeleton probe of the semantic anchors — the anchors whose
36
+ * skeleton form is NOT their literal token (the numeric headings, the table row /
37
+ * cell values, the graph rows and the parse-face names). The literal-marker
38
+ * anchors (`### Goal`, `- **Objective**:` …) fall back to their generic forms. */
39
+ const SEMANTIC_PROBES: Record<string, string> = {
40
+ "### N. group heading": "### 1. :::fill group-title",
41
+ "#### N.M item heading": "#### 1.1 :::fill item-title",
42
+ "### Task N:": "### Task 1: :::fill task-title",
43
+ "Task id token": "### Task 1:",
44
+ "File path token": "- **Files**: :::fill file-paths",
45
+ "Step action": ":::fill step-action",
46
+ "Step checkable": "— checkable: :::fill step-checkable",
47
+ "Acceptance entry": "- `:::fill acceptance-entry`",
48
+ "Constraint delta bullet": "- :::fill constraint",
49
+ "Issue inventory columns": "| Phase | Issue (ref) | Title summary |",
50
+ "Issue row": "| P1 | none | :::fill issue-title |",
51
+ "Issue ref cell": "| P1 | none |",
52
+ "Phase inventory columns":
53
+ "| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
54
+ "Phase row": "| P1 | :::fill phase-name |",
55
+ "Phase id token": "| P1 |",
56
+ "Implementation plan cell": "| Pending |",
57
+ "Design spec cell": "| [Pending] |",
58
+ "Dependency cell": ":::fill dependency",
59
+ "File path row": "| overall-spec | `:::fill overall-path` |",
60
+ "Change history row": "| v0.1 |",
61
+ "Version token": "| v0.1 |",
62
+ "Change history date": DATE,
63
+ "Hard edge": "P1 -> P2",
64
+ "Graph legend": "- `->` = hard block",
65
+ };
66
+
67
+ /** The skeleton-probe token of one registered anchor — the semantic map first,
68
+ * the literal-marker anchors by their generic skeleton forms (the title fill,
69
+ * the heading literal, the `- **Key**:` field markers — the plan's `**Spec:**`
70
+ * rides the bare marker, never a `- ` prefix). */
71
+ const probeOf = (anchor: string): string => {
72
+ const semantic = SEMANTIC_PROBES[anchor];
73
+ if (semantic !== undefined) return semantic;
74
+ if (anchor.startsWith("# ")) return "# :::fill title";
75
+ if (anchor.startsWith("#")) return anchor;
76
+ if (anchor.startsWith("**")) return anchor === "**Spec:**" ? "**Spec:**" : `- ${anchor}:`;
77
+ return anchor;
78
+ };
79
+
80
+ describe("SkeletonAssembler — the four doc skeletons (byte pins)", () => {
81
+ it("renders the phase-spec skeleton — the header five-tuple + the Design double layer + the lineage", () => {
82
+ expect(renderOf("phase-spec")).toBe(
83
+ [
84
+ "# :::fill title",
85
+ "- **Version**: v0.1 · 2026-10-11",
86
+ "- **Status**: Draft",
87
+ "- **Author**: :::fill author",
88
+ "- **Parent program**: [<parent overall>](<parent path>)",
89
+ "- **Depends on**: :::fill depends-on",
90
+ "",
91
+ "## Design",
92
+ "",
93
+ ":::fill design-intro",
94
+ "",
95
+ "### 1. :::fill group-title",
96
+ "#### 1.1 :::fill item-title",
97
+ "- :::fill item-body",
98
+ "",
99
+ "### Acceptance criteria",
100
+ "",
101
+ "- `:::fill acceptance-entry`",
102
+ "",
103
+ "## Constraints",
104
+ "",
105
+ "- :::fill constraint",
106
+ "",
107
+ "## Change history",
108
+ "",
109
+ "| Version | date | summary | author |",
110
+ "| --- | --- | --- | --- |",
111
+ "| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
112
+ ].join("\n"),
113
+ );
114
+ });
115
+
116
+ it("renders the plan skeleton — the Class-A/B header + the first task block + the lineage", () => {
117
+ expect(renderOf("plan")).toBe(
118
+ [
119
+ "# :::fill title",
120
+ "**Spec:** [<spec path>](<spec path>)",
121
+ "- **Parent program**: [<parent overall>](<parent path>)",
122
+ "- **Version**: v0.1 · 2026-10-11",
123
+ "",
124
+ "## Constraints",
125
+ "",
126
+ "- :::fill constraint",
127
+ "",
128
+ "### Task 1: :::fill task-title",
129
+ "- **Objective**: :::fill objective",
130
+ "- **Files**: :::fill file-paths",
131
+ "- **Consumes**: :::fill consumes",
132
+ "- **Produces**: :::fill produces",
133
+ "- **Steps**:",
134
+ " - :::fill step-action — checkable: :::fill step-checkable",
135
+ "- **Acceptance**: :::fill acceptance",
136
+ "- **DependsOn**: none",
137
+ "",
138
+ "## Change history",
139
+ "",
140
+ "| Version | date | summary | author |",
141
+ "| --- | --- | --- | --- |",
142
+ "| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
143
+ ].join("\n"),
144
+ );
145
+ });
146
+
147
+ it("renders the overall skeleton — the header tuple + the table sections + the dependency graph", () => {
148
+ expect(renderOf("overall-spec")).toBe(
149
+ [
150
+ "# :::fill title",
151
+ "- **Version**: v0.1 · 2026-10-11",
152
+ "- **Status**: Draft",
153
+ "- **Author**: :::fill author",
154
+ "- **Constraints**: :::fill constraints",
155
+ "",
156
+ "## Document scope",
157
+ "",
158
+ ":::fill document-scope",
159
+ "",
160
+ "## File paths",
161
+ "",
162
+ "| Artifact | Path |",
163
+ "| --- | --- |",
164
+ "| overall-spec | `:::fill overall-path` |",
165
+ "",
166
+ "## Program charter",
167
+ "",
168
+ "### Goal",
169
+ "",
170
+ "- :::fill goal-description",
171
+ "",
172
+ "### Non-goals",
173
+ "",
174
+ "- :::fill non-goal-description",
175
+ "",
176
+ "### Cross-cutting",
177
+ "",
178
+ "- :::fill cross-cutting-description",
179
+ "",
180
+ "## Issue inventory",
181
+ "",
182
+ "| Phase | Issue (ref) | Title summary |",
183
+ "| --- | --- | --- |",
184
+ "| P1 | none | :::fill issue-title |",
185
+ "",
186
+ "## Phase inventory",
187
+ "",
188
+ "| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
189
+ "| --- | --- | --- | --- | --- | --- | --- |",
190
+ "| P1 | :::fill phase-name | :::fill scope | [Pending] | Pending | :::fill acceptance-criteria | :::fill dependency |",
191
+ "| P2 | :::fill phase-name | :::fill scope | [Pending] | Pending | :::fill acceptance-criteria | :::fill dependency |",
192
+ "",
193
+ "## Dependency graph",
194
+ "",
195
+ "P1 -> P2",
196
+ "- `->` = hard block",
197
+ "",
198
+ "## Boundary rules",
199
+ "",
200
+ "- :::fill boundary-rule",
201
+ "",
202
+ "## Maintenance",
203
+ "",
204
+ "- :::fill maintenance-note",
205
+ "",
206
+ "## Change history",
207
+ "",
208
+ "| Version | date | summary | author |",
209
+ "| --- | --- | --- | --- |",
210
+ "| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
211
+ ].join("\n"),
212
+ );
213
+ });
214
+
215
+ it("renders the single-spec skeleton — the header five-tuple + the prose sections + the lineage", () => {
216
+ expect(renderOf("single-spec")).toBe(
217
+ [
218
+ "# :::fill title",
219
+ "- **Version**: v0.1 · 2026-10-11",
220
+ "- **Status**: Draft",
221
+ "- **Author**: :::fill author",
222
+ "- **Depends on**: :::fill depends-on",
223
+ "",
224
+ "## Background & root cause",
225
+ "",
226
+ ":::fill background-root-cause",
227
+ "",
228
+ "## Design decisions",
229
+ "",
230
+ ":::fill design-ruling",
231
+ "",
232
+ "## Acceptance",
233
+ "",
234
+ ":::fill acceptance",
235
+ "",
236
+ "## Constraints",
237
+ "",
238
+ ":::fill constraints",
239
+ "",
240
+ "## Change history",
241
+ "",
242
+ "| Version | date | summary | author |",
243
+ "| --- | --- | --- | --- |",
244
+ "| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
245
+ ].join("\n"),
246
+ );
247
+ });
248
+ });
249
+
250
+ describe("SkeletonAssembler — the required-anchor coverage probes (§3.2)", () => {
251
+ it("carries every required anchor of the four doc types (the live registry set)", () => {
252
+ for (const key of ["overall-spec", "plan", "phase-spec", "single-spec"] as const) {
253
+ const rendered = renderOf(key);
254
+ for (const anchor of requiredAnchorsOf(key)) {
255
+ // The grep probe per anchor — the skeleton line form of the anchor lands
256
+ // in the rendered bytes (headings and markers by their literal, the
257
+ // semantic anchors by their rendered value forms).
258
+ expect(rendered, `${key}: ${anchor}`).toContain(probeOf(anchor));
259
+ }
260
+ }
261
+ });
262
+
263
+ it("renders the numeric headings as true numbers — zero literal `N`", () => {
264
+ const spec = renderOf("phase-spec");
265
+ expect(spec).toContain("### 1. :::fill group-title");
266
+ expect(spec).toContain("#### 1.1 :::fill item-title");
267
+ const plan = renderOf("plan");
268
+ expect(plan).toContain("### Task 1: :::fill task-title");
269
+ // the declared digit-headed anchors never render a literal `N` placeholder
270
+ expect(rendersNoLiteralN("phase-spec")).toBe(true);
271
+ expect(rendersNoLiteralN("plan")).toBe(true);
272
+ });
273
+
274
+ it("renders the version row and the change-history first row with the injected date truth", () => {
275
+ for (const key of ["overall-spec", "plan", "phase-spec", "single-spec"] as const) {
276
+ const rendered = renderOf(key);
277
+ // the version row — v0.1 · the injected run date (real shape hit, never a
278
+ // `<date>` notation marker)
279
+ expect(rendered).toContain(`- **Version**: v0.1 · ${DATE}`);
280
+ // the change-history first row — the header version (v0.1) + the date cell
281
+ // + the summary/author content fills
282
+ expect(rendered).toContain(`| v0.1 | ${DATE} | :::fill summary | :::fill author |`);
283
+ // the header version equals the change-history row version (self-consistent
284
+ // lineage, ascending oldest-first with a single row)
285
+ const headerVersion = rendered.match(/- \*\*Version\*\*: (v\d+\.\d+) ·/)?.[1];
286
+ expect(rendered).toContain(`| ${headerVersion} |`);
287
+ }
288
+ });
289
+
290
+ it("renders the generator truths — the enum Status line and the graph rows", () => {
291
+ for (const key of ["overall-spec", "phase-spec"] as const) {
292
+ expect(renderOf(key)).toContain("- **Status**: Draft");
293
+ }
294
+ expect(renderOf("overall-spec")).toContain("P1 -> P2");
295
+ expect(renderOf("overall-spec")).toContain("- `->` = hard block");
296
+ });
297
+
298
+ it("renders every content position as a `:::fill <slot>` slot", () => {
299
+ for (const key of ["overall-spec", "plan", "phase-spec", "single-spec"] as const) {
300
+ const rendered = renderOf(key);
301
+ expect(rendered).toMatch(/:::fill \S+/g);
302
+ // the fill values are the declared slot names — never a residual `<…>`
303
+ // notation or a bare empty value
304
+ expect(rendered).not.toContain(":::fill <");
305
+ }
306
+ });
307
+
308
+ it("renders the link-typed anchors as placeholder links (label + target `<…>` literals)", () => {
309
+ const spec = renderOf("phase-spec");
310
+ expect(spec).toContain("- **Parent program**: [<parent overall>](<parent path>)");
311
+ const plan = renderOf("plan");
312
+ expect(plan).toContain("**Spec:** [<spec path>](<spec path>)");
313
+ expect(plan).toContain("- **Parent program**: [<parent overall>](<parent path>)");
314
+ });
315
+ });
316
+
317
+ describe("SkeletonAssembler — the placeholder-anchoring probes (§4.1)", () => {
318
+ /** The structure/truth/header rows that must never carry a `:::fill` — the
319
+ * fixed heading lines, the version row, the Status truth, the link anchors,
320
+ * the graph rows and the table headers/separators. */
321
+ const STRUCTURE_LINES: Record<string, readonly string[]> = {
322
+ "overall-spec": [
323
+ "- **Version**: v0.1 · 2026-10-11",
324
+ "- **Status**: Draft",
325
+ "## Document scope",
326
+ "## File paths",
327
+ "| Artifact | Path |",
328
+ "| --- | --- |",
329
+ "## Program charter",
330
+ "### Goal",
331
+ "### Non-goals",
332
+ "### Cross-cutting",
333
+ "## Issue inventory",
334
+ "| Phase | Issue (ref) | Title summary |",
335
+ "| --- | --- | --- |",
336
+ "## Phase inventory",
337
+ "| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
338
+ "| --- | --- | --- | --- | --- | --- | --- |",
339
+ "## Dependency graph",
340
+ "P1 -> P2",
341
+ "- `->` = hard block",
342
+ "## Boundary rules",
343
+ "## Maintenance",
344
+ "## Change history",
345
+ "| Version | date | summary | author |",
346
+ "| --- | --- | --- | --- |",
347
+ ],
348
+ plan: [
349
+ "- **Version**: v0.1 · 2026-10-11",
350
+ "**Spec:** [<spec path>](<spec path>)",
351
+ "- **Parent program**: [<parent overall>](<parent path>)",
352
+ "## Constraints",
353
+ "## Change history",
354
+ "| Version | date | summary | author |",
355
+ "| --- | --- | --- | --- |",
356
+ ],
357
+ "phase-spec": [
358
+ "- **Version**: v0.1 · 2026-10-11",
359
+ "- **Status**: Draft",
360
+ "- **Parent program**: [<parent overall>](<parent path>)",
361
+ "## Design",
362
+ "### Acceptance criteria",
363
+ "## Constraints",
364
+ "## Change history",
365
+ "| Version | date | summary | author |",
366
+ "| --- | --- | --- | --- |",
367
+ ],
368
+ "single-spec": [
369
+ "- **Version**: v0.1 · 2026-10-11",
370
+ "- **Status**: Draft",
371
+ "## Background & root cause",
372
+ "## Design decisions",
373
+ "## Acceptance",
374
+ "## Constraints",
375
+ "## Change history",
376
+ "| Version | date | summary | author |",
377
+ "| --- | --- | --- | --- |",
378
+ ],
379
+ };
380
+
381
+ it("lands every `:::fill` on a content position — zero on the structure/truth/link/header rows", () => {
382
+ for (const key of ["overall-spec", "plan", "phase-spec", "single-spec"] as const) {
383
+ const lines = renderOf(key).split("\n");
384
+ for (const line of lines) {
385
+ if (!line.includes(":::fill")) continue;
386
+ expect(STRUCTURE_LINES[key], `${key}: ${line}`).not.toContain(line);
387
+ }
388
+ expect(renderOf(key)).not.toMatch(/\| --- \|.*:::fill/);
389
+ }
390
+ });
391
+
392
+ it("keeps structure true — the fixed headings and table headers carry no fill", () => {
393
+ for (const key of ["overall-spec", "plan", "phase-spec", "single-spec"] as const) {
394
+ const rendered = renderOf(key);
395
+ for (const line of STRUCTURE_LINES[key]) {
396
+ expect(rendered, `${key}: ${line}`).toContain(line);
397
+ if (!line.includes(":::")) expect(line).not.toContain(":::fill");
398
+ }
399
+ }
400
+ });
401
+ });
402
+
403
+ describe("SkeletonAssembler — the slot-consumption invariant (composition vs registry)", () => {
404
+ it("consumes every required slot of the four live projections — render() never trips the assertion", () => {
405
+ for (const key of ["overall-spec", "plan", "phase-spec", "single-spec"] as const) {
406
+ expect(() => renderOf(key)).not.toThrow();
407
+ }
408
+ });
409
+
410
+ it("loud-throws on an unemitted required slot — a registered anchor the composition does not place", () => {
411
+ const plan = SKELETONS.plan;
412
+ const tampered: DocSkeleton = {
413
+ docType: plan.docType,
414
+ slots: [
415
+ ...plan.slots,
416
+ {
417
+ anchor: "**Guest anchor**",
418
+ presence: "required",
419
+ home: "section",
420
+ slot: "content",
421
+ refKind: "none",
422
+ },
423
+ ],
424
+ };
425
+ expect(() => new SkeletonAssembler(tampered, DATE).render()).toThrow(
426
+ /omits the registered required slot\(s\): \*\*Guest anchor\*\*/,
427
+ );
428
+ });
429
+
430
+ it("loud-throws on an emitted anchor the registry no longer requires — a composed anchor with no registered slot", () => {
431
+ const plan = SKELETONS.plan;
432
+ const tampered: DocSkeleton = {
433
+ docType: plan.docType,
434
+ slots: plan.slots.filter((slot) => slot.anchor !== "## Constraints"),
435
+ };
436
+ expect(() => new SkeletonAssembler(tampered, DATE).render()).toThrow(
437
+ /emits the unregistered anchor: ## Constraints/,
438
+ );
439
+ });
440
+ });
441
+
442
+ describe("SkeletonAssembler — the EOF rule", () => {
443
+ it("render() never ends with a newline or a blank line — the redirected fixture ends with exactly one `\\n`", () => {
444
+ for (const key of ["overall-spec", "plan", "phase-spec", "single-spec"] as const) {
445
+ const rendered = renderOf(key);
446
+ expect(rendered.endsWith("\n"), `${key}: no trailing newline from render`).toBe(false);
447
+ expect(rendered.endsWith("\n\n") || rendered.endsWith(" \n"), `${key}: no blank tail`).toBe(
448
+ false,
449
+ );
450
+ const withCliNewline = `${rendered}\n`;
451
+ expect(withCliNewline.endsWith("\n")).toBe(true);
452
+ expect(withCliNewline.endsWith("\n\n"), `${key}: exactly one final newline`).toBe(false);
453
+ // the last line of the rendered bytes is real content, never a blank
454
+ const lastLine = rendered.split("\n").at(-1);
455
+ expect(lastLine?.trim().length, `${key}: last line non-blank`).toBeGreaterThan(0);
456
+ }
457
+ });
458
+ });
459
+
460
+ /** Whether any rendered skeleton line carries a literal `N` heading placeholder —
461
+ * the declared digit headings (`### N.` / `#### N.M` / `### Task N:`) always
462
+ * render true numbers, never the letter. */
463
+ const rendersNoLiteralN = (key: DocKey): boolean => {
464
+ const rendered = renderOf(key);
465
+ return !/(?:^|\n)#{2,4} (?:Task )?N[.:]/m.test(rendered) && !rendered.includes("Task N:");
466
+ };
@@ -0,0 +1,121 @@
1
+ // packages/cdd-engine/src-next/render/brief.ts
2
+ // T12 — BriefRenderer: the task-brief renderer. The brief materializes the
3
+ // dispatch's `### Task N:` sections from a plan: extraction rides the contract
4
+ // parse face (doc.ts PlanDocType.parse — the same task-block parse instance the
5
+ // graph and the dispatch reuse), the step surface carries the `— checkable:`
6
+ // clause (the dispatch contract's evidence gate), and the rendered brief appends
7
+ // the plan's `## Constraints` section (the complete plan mirror). The checkable
8
+ // gate blocks step surfaces that carry a step
9
+ // with no checkable clause; a requested task with no matching heading blocks the
10
+ // whole render (the group-level out-of-bounds contract).
11
+
12
+ import type { TaskStep } from "../contract/doc.ts";
13
+ import { PlanDocType } from "../contract/doc.ts";
14
+
15
+ /** One parsed task-block field of the brief. */
16
+ export interface BriefField {
17
+ key: string;
18
+ lines: readonly string[];
19
+ }
20
+
21
+ /** One parsed task block of the brief — the plan's block + its checkable verdict. */
22
+ export interface BriefTask {
23
+ /** The task number. */
24
+ id: number;
25
+ /** The `### Task N: …` heading line verbatim. */
26
+ heading: string;
27
+ /** The block's keyed fields in document order. */
28
+ fields: readonly BriefField[];
29
+ /** The parsed `**Steps**` bullets. */
30
+ steps: readonly TaskStep[];
31
+ /** Whether every step carries a `— checkable:` clause. */
32
+ checkableComplete: boolean;
33
+ /** The step actions whose `— checkable:` clause is missing. */
34
+ missingCheckables: readonly string[];
35
+ }
36
+
37
+ /** The extraction outcome — the requested briefs + the out-of-bounds task ids. */
38
+ export interface BriefExtraction {
39
+ data: readonly BriefTask[];
40
+ missing: readonly number[];
41
+ }
42
+
43
+ /**
44
+ * The brief single renderer — pure data + content (no direct file system writes;
45
+ * the caller/CLI writes the rendered content into the workspace).
46
+ */
47
+ export class BriefRenderer {
48
+ readonly #parser: PlanDocType;
49
+
50
+ constructor(parser = new PlanDocType("plan")) {
51
+ this.#parser = parser;
52
+ }
53
+
54
+ /** The task-heading slices of the plan parse face (the render's parse-face consumption). */
55
+ taskHeadingPattern(): RegExp | undefined {
56
+ return this.#parser.slices.slices.find((slice) => slice.anchor === "### Task N:")?.valuePattern;
57
+ }
58
+
59
+ /** Extract the requested task blocks from a plan's content — the brief data. */
60
+ extract(planContent: string, tasks: readonly number[]): BriefExtraction {
61
+ const parsed = this.#parser.parse(planContent.split("\n"));
62
+ const byId = new Map(parsed.taskBlocks.map((block) => [block.id, block]));
63
+ const missing: number[] = [];
64
+ const data: BriefTask[] = [];
65
+ for (const id of new Set(tasks)) {
66
+ const block = byId.get(id);
67
+ if (block === undefined) {
68
+ missing.push(id);
69
+ continue;
70
+ }
71
+ const steps = block.steps;
72
+ const missingCheckables = steps
73
+ .filter((step) => step.checkable === null)
74
+ .map((step) => step.action);
75
+ data.push({
76
+ id: block.id,
77
+ heading: block.heading,
78
+ fields: block.fields,
79
+ steps,
80
+ checkableComplete: missingCheckables.length === 0,
81
+ missingCheckables,
82
+ });
83
+ }
84
+ return { data, missing };
85
+ }
86
+
87
+ /** Render the brief content — the requested task sections + the plan's
88
+ * `## Constraints` section (the complete plan mirror). Any requested task without
89
+ * a heading blocks the whole render (out-of-bounds). */
90
+ render(planContent: string, tasks: readonly number[]): string {
91
+ const { data, missing } = this.extract(planContent, tasks);
92
+ if (missing.length > 0) {
93
+ throw new Error(
94
+ `task${missing.length > 1 ? "s" : ""} ${missing.join(", ")} not found in the plan`,
95
+ );
96
+ }
97
+ const lines = planContent.split("\n");
98
+ const sections = data.map((task) =>
99
+ this.#rawSection(lines, (line) => line.startsWith(`### Task ${task.id}:`)),
100
+ );
101
+ const constraints = this.#rawSection(lines, (line) => line.trimEnd() === "## Constraints");
102
+ const body =
103
+ constraints === "" ? sections.join("\n\n") : `${sections.join("\n\n")}\n\n${constraints}`;
104
+ return `${body}\n`;
105
+ }
106
+
107
+ /** The shared heading slice — from the first line a matcher accepts to the next
108
+ * heading line ("" when nothing matches). Both the `### Task N:` sections and the
109
+ * `## Constraints` mirror render through this one shape. */
110
+ #rawSection(lines: readonly string[], match: (line: string) => boolean): string {
111
+ const start = lines.findIndex(match);
112
+ if (start === -1) return "";
113
+ const out: string[] = [];
114
+ for (let i = start; i < lines.length; i++) {
115
+ const line = lines[i];
116
+ if (i > start && /^#/.test(line)) break;
117
+ out.push(line);
118
+ }
119
+ return out.join("\n").replace(/\s+$/, "");
120
+ }
121
+ }