@oscaner-skills/cdd-engine 1.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +11 -10
  2. package/README.zh-CN.md +11 -10
  3. package/package.json +16 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  6. package/src-next/__tests__/floor.guard.test.ts +69 -0
  7. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  8. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  9. package/src-next/__tests__/smoke.integration.test.ts +185 -0
  10. package/src-next/__tests__/support/strip-comments.ts +99 -0
  11. package/src-next/__tests__/zero-dep.test.ts +94 -0
  12. package/src-next/bin.ts +61 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +256 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +165 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +190 -0
  16. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +106 -0
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +240 -0
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +165 -0
  19. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +190 -0
  20. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +100 -0
  21. package/src-next/contract/__tests__/declare.test.ts +481 -0
  22. package/src-next/contract/__tests__/doc.test.ts +527 -0
  23. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  24. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  25. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  26. package/src-next/contract/__tests__/judge.test.ts +1111 -0
  27. package/src-next/contract/__tests__/lint.test.ts +324 -0
  28. package/src-next/contract/__tests__/project.test.ts +460 -0
  29. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  30. package/src-next/contract/__tests__/translate.test.ts +96 -0
  31. package/src-next/contract/declare.ts +1071 -0
  32. package/src-next/contract/doc.ts +816 -0
  33. package/src-next/contract/frontmatter.ts +233 -0
  34. package/src-next/contract/home-extractors.ts +397 -0
  35. package/src-next/contract/invariants.ts +1413 -0
  36. package/src-next/contract/judge.ts +151 -0
  37. package/src-next/contract/lint.ts +239 -0
  38. package/src-next/contract/project.ts +656 -0
  39. package/src-next/contract/skill-anatomy.ts +301 -0
  40. package/src-next/contract/translate.ts +113 -0
  41. package/src-next/face/__tests__/board-view.test.ts +1151 -0
  42. package/src-next/face/__tests__/capsule.test.ts +300 -0
  43. package/src-next/face/__tests__/channel-closure.guard.test.ts +129 -0
  44. package/src-next/face/__tests__/cli.test.ts +4897 -0
  45. package/src-next/face/__tests__/face.test.ts +289 -0
  46. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  47. package/src-next/face/__tests__/host.test.ts +24 -0
  48. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  49. package/src-next/face/__tests__/negation.ts +6 -0
  50. package/src-next/face/__tests__/preview.test.ts +374 -0
  51. package/src-next/face/__tests__/projection.test.ts +303 -0
  52. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  53. package/src-next/face/__tests__/termination.test.ts +650 -0
  54. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  55. package/src-next/face/artifacts.ts +248 -0
  56. package/src-next/face/board-view.ts +652 -0
  57. package/src-next/face/capsule.ts +163 -0
  58. package/src-next/face/cli.ts +1028 -0
  59. package/src-next/face/declare.ts +323 -0
  60. package/src-next/face/gate.ts +171 -0
  61. package/src-next/face/graph-view.ts +74 -0
  62. package/src-next/face/host.ts +302 -0
  63. package/src-next/face/lifecycle.ts +725 -0
  64. package/src-next/face/preview.ts +151 -0
  65. package/src-next/face/projection.ts +285 -0
  66. package/src-next/face/route-render.ts +185 -0
  67. package/src-next/face/termination.ts +573 -0
  68. package/src-next/face/words.ts +314 -0
  69. package/src-next/infra/__tests__/infra.test.ts +333 -0
  70. package/src-next/infra/__tests__/root.test.ts +56 -0
  71. package/src-next/infra/config.ts +42 -0
  72. package/src-next/infra/doc-roots.ts +29 -0
  73. package/src-next/infra/git.ts +39 -0
  74. package/src-next/infra/process.ts +34 -0
  75. package/src-next/infra/root.ts +73 -0
  76. package/src-next/infra/runtime.ts +132 -0
  77. package/src-next/infra/workspace.ts +322 -0
  78. package/src-next/render/__tests__/render.test.ts +550 -0
  79. package/src-next/render/__tests__/skeleton.test.ts +684 -0
  80. package/src-next/render/brief.ts +121 -0
  81. package/src-next/render/issue-body.ts +162 -0
  82. package/src-next/render/skeleton.ts +502 -0
  83. package/src-next/render/templates.ts +645 -0
  84. package/src-next/session/__tests__/graph.test.ts +277 -0
  85. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  86. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  87. package/src-next/session/__tests__/ledger.test.ts +745 -0
  88. package/src-next/session/__tests__/next.test.ts +460 -0
  89. package/src-next/session/__tests__/preflight.test.ts +545 -0
  90. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  91. package/src-next/session/__tests__/run.test.ts +1026 -0
  92. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  93. package/src-next/session/__tests__/wave.test.ts +476 -0
  94. package/src-next/session/faces.ts +110 -0
  95. package/src-next/session/graph.ts +411 -0
  96. package/src-next/session/handoff-schema.ts +373 -0
  97. package/src-next/session/ledger.ts +1076 -0
  98. package/src-next/session/next.ts +293 -0
  99. package/src-next/session/preflight.ts +271 -0
  100. package/src-next/session/round-naming.ts +84 -0
  101. package/src-next/session/run.ts +610 -0
  102. package/src-next/session/state.ts +30 -0
  103. package/src-next/session/wave.ts +139 -0
  104. package/templates/report/issue-body.json +17 -65
  105. package/dist/chunks/branch.mjs +0 -480
  106. package/dist/chunks/docs.mjs +0 -253
  107. package/dist/chunks/task.mjs +0 -913
  108. package/dist/cli.mjs +0 -5457
  109. package/dist/documents/schema/add-phase-protocol.json +0 -126
  110. package/dist/documents/schema/overall.json +0 -361
  111. package/dist/documents/schema/phase-spec.json +0 -145
  112. package/dist/documents/schema/plan.json +0 -191
  113. package/dist/documents/schema/skill-anatomy.json +0 -233
  114. package/dist/resources/harness-registry.json +0 -49
  115. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  116. package/templates/engine-config.json +0 -302
  117. package/templates/schema/cache-profile-schema.json +0 -23
  118. package/templates/schema/docs-handoff-schema.json +0 -129
  119. package/templates/schema/task-handoff-schema.json +0 -332
  120. package/templates/template-contract.json +0 -231
@@ -0,0 +1,684 @@
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.2):
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 front-matter head (spec §2.2/§4.2) — a `---`-fenced YAML record whose
8
+ // key set is the projection's front-matter emission list (the head's required
9
+ // keys plus the type's optional head keys); the placeholder three-way split
10
+ // (link keys a `<…>` scalar · content keys `:::fill <key>` · truth keys their
11
+ // true values; `parent-version` never emitted);
12
+ // · the placeholder-anchoring probes (spec §4.1): pure content slots take
13
+ // `:::fill <slot>`, the link-shaped anchors the placeholder links, the
14
+ // pattern-typed rows the generator truths, and `:::fill` never lands on a
15
+ // structure/truth/link/table-header position;
16
+ // · the doc-contract pin — every rendered skeleton passes its own
17
+ // Contract.validate with zero findings (the skeleton is green by
18
+ // construction);
19
+ // · the EOF rule — render() never ends with a newline or a blank line; the
20
+ // CLI's single appended `\n` leaves a redirected fixture with exactly one
21
+ // final newline.
22
+
23
+ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
24
+ import { tmpdir } from "node:os";
25
+ import path from "node:path";
26
+ import { describe, expect, it } from "vitest";
27
+ import { parse } from "yaml";
28
+ import { declaredRegistries } from "../../contract/declare.ts";
29
+ import { Contract } from "../../contract/judge.ts";
30
+ import type { DocKey, DocSkeleton, SkeletonSlot } from "../../contract/project.ts";
31
+ import { Projector } from "../../contract/project.ts";
32
+ import { BoardView } from "../../face/board-view.ts";
33
+ import { type RepoPath, RepoRoot } from "../../infra/root.ts";
34
+ import { SkeletonAssembler } from "../skeleton.ts";
35
+
36
+ /** The fixed run date — the injectable run-day truth (no live clock in the pins). */
37
+ const DATE = "2026-10-11";
38
+ const PROJECTOR = new Projector(declaredRegistries);
39
+ const SKELETONS = PROJECTOR.skeleton();
40
+ const KEYS = ["overall-spec", "plan", "phase-spec", "single-spec"] as const;
41
+
42
+ /** The fixed-date rendered skeleton bytes of one doc type. */
43
+ const renderOf = (key: DocKey): string => new SkeletonAssembler(SKELETONS[key], DATE).render();
44
+
45
+ /** The front-matter block of a rendered skeleton — the lines between the two `---`
46
+ * fences (the §2.2 YAML record; the markdown body starts after the second fence). */
47
+ const frontmatterBlockOf = (key: DocKey): string => {
48
+ const lines = renderOf(key).split("\n");
49
+ const first = lines.indexOf("---");
50
+ return lines.slice(first + 1, lines.indexOf("---", first + 1)).join("\n");
51
+ };
52
+
53
+ /** The registered required anchors of one doc type (the live registry). */
54
+ const requiredAnchorsOf = (key: DocKey): readonly string[] =>
55
+ declaredRegistries[key].elements
56
+ .filter((element) => element.presence === "required")
57
+ .map((element) => element.anchor);
58
+
59
+ /** The live front-matter emission list of one doc type (the head key set the
60
+ * renderer emits — the projection's independent list: required head keys plus
61
+ * the type's optional head keys, `parent-version` excluded). */
62
+ const frontmatterSlotsOf = (key: DocKey): readonly SkeletonSlot[] => SKELETONS[key].frontmatter;
63
+
64
+ /** The per-anchor skeleton probe of the semantic anchors — the anchors whose
65
+ * skeleton form is NOT their literal token (the numeric headings, the table row /
66
+ * cell values, the graph rows and the parse-face names). The literal-marker
67
+ * anchors (`### Goal`, `- **Objective**:` …) fall back to their generic forms. */
68
+ const SEMANTIC_PROBES: Record<string, string> = {
69
+ "### N. group heading": "### 1. :::fill group-title",
70
+ "#### N.M item heading": "#### 1.1 :::fill item-title",
71
+ "### Task N:": "### Task 1: :::fill task-title",
72
+ "Task id token": "### Task 1:",
73
+ "File path token": "- **Files**: :::fill file-paths",
74
+ "Step action": ":::fill step-action",
75
+ "Step checkable": "— checkable: :::fill step-checkable",
76
+ "Acceptance entry": "- `:::fill acceptance-entry`",
77
+ "Constraint delta bullet": "- :::fill constraint",
78
+ "Issue inventory columns": "| Phase | Issue (ref) | Title summary |",
79
+ "Issue row": "| P1 | none | :::fill issue-title |",
80
+ "Issue ref cell": "| P1 | none |",
81
+ "Phase inventory columns":
82
+ "| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
83
+ "Phase row": "| P1 | :::fill phase-name |",
84
+ "Phase id token": "| P1 |",
85
+ "Implementation plan cell": "| Pending |",
86
+ "Design spec cell": "| [Pending] |",
87
+ "Dependency cell": ":::fill dependency",
88
+ "File path row": "| overall-spec | `:::fill overall-path` |",
89
+ "Change history row": "| v0.1 |",
90
+ "Version token": "| v0.1 |",
91
+ "Change history date": DATE,
92
+ "Hard edge": "P1 -> P2",
93
+ "Graph legend": "- `->` = hard block",
94
+ };
95
+
96
+ /** The skeleton-probe token of one registered anchor — the semantic map first,
97
+ * the literal-marker anchors by their generic skeleton forms (the heading
98
+ * literal, the `- **Key**:` field markers), and the front-matter key anchors
99
+ * (the remaining plain tokens — the head's key set) by their `key: ` declaration
100
+ * line. */
101
+ const probeOf = (anchor: string): string => {
102
+ const semantic = SEMANTIC_PROBES[anchor];
103
+ if (semantic !== undefined) return semantic;
104
+ if (anchor.startsWith("# ")) return "# :::fill title";
105
+ if (anchor.startsWith("#")) return anchor;
106
+ if (anchor.startsWith("**")) return `- ${anchor}:`;
107
+ return `${anchor}: `;
108
+ };
109
+
110
+ describe("SkeletonAssembler — the four doc skeletons (byte pins)", () => {
111
+ it("renders the phase-spec skeleton — the front-matter head + the Design double layer + the lineage", () => {
112
+ expect(renderOf("phase-spec")).toBe(
113
+ [
114
+ "---",
115
+ "title: ':::fill title'",
116
+ "doc-type: phase-spec",
117
+ "version: v0.1",
118
+ "date: 2026-10-11",
119
+ "status: Draft",
120
+ "author: ':::fill author'",
121
+ "parent-program: <docs/kairos/specs/…-overall.md>",
122
+ "depends-on: ':::fill depends-on'",
123
+ "---",
124
+ "",
125
+ "## Design",
126
+ "",
127
+ ":::fill design-intro",
128
+ "",
129
+ "### 1. :::fill group-title",
130
+ "#### 1.1 :::fill item-title",
131
+ "- :::fill item-body",
132
+ "",
133
+ "### Acceptance criteria",
134
+ "",
135
+ "- `:::fill acceptance-entry`",
136
+ "",
137
+ "## Constraints",
138
+ "",
139
+ "- :::fill constraint",
140
+ "",
141
+ "## Change history",
142
+ "",
143
+ "| Version | date | summary | author |",
144
+ "| --- | --- | --- | --- |",
145
+ "| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
146
+ ].join("\n"),
147
+ );
148
+ });
149
+
150
+ it("renders the plan skeleton — the Class-A/B front-matter head + the first task block + the lineage", () => {
151
+ expect(renderOf("plan")).toBe(
152
+ [
153
+ "---",
154
+ "title: ':::fill title'",
155
+ "doc-type: plan",
156
+ "version: v0.1",
157
+ "date: 2026-10-11",
158
+ "spec: <docs/kairos/specs/…-design.md>",
159
+ "parent-program: <docs/kairos/specs/…-overall.md>",
160
+ "depends-on: ':::fill depends-on'",
161
+ "base: ':::fill base'",
162
+ "---",
163
+ "",
164
+ "## Constraints",
165
+ "",
166
+ "- :::fill constraint",
167
+ "",
168
+ "### Task 1: :::fill task-title",
169
+ "- **Objective**: :::fill objective",
170
+ "- **Files**: :::fill file-paths",
171
+ "- **Consumes**: :::fill consumes",
172
+ "- **Produces**: :::fill produces",
173
+ "- **Steps**:",
174
+ " - :::fill step-action — checkable: :::fill step-checkable",
175
+ "- **Acceptance**: :::fill acceptance",
176
+ "- **DependsOn**: none",
177
+ "",
178
+ "## Change history",
179
+ "",
180
+ "| Version | date | summary | author |",
181
+ "| --- | --- | --- | --- |",
182
+ "| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
183
+ ].join("\n"),
184
+ );
185
+ });
186
+
187
+ it("renders the overall skeleton — the front-matter head + the table sections + the dependency graph", () => {
188
+ expect(renderOf("overall-spec")).toBe(
189
+ [
190
+ "---",
191
+ "title: ':::fill title'",
192
+ "doc-type: overall-spec",
193
+ "version: v0.1",
194
+ "date: 2026-10-11",
195
+ "status: Draft",
196
+ "author: ':::fill author'",
197
+ "---",
198
+ "",
199
+ "## Document scope",
200
+ "",
201
+ ":::fill document-scope",
202
+ "",
203
+ "## File paths",
204
+ "",
205
+ "| Artifact | Path |",
206
+ "| --- | --- |",
207
+ "| overall-spec | `:::fill overall-path` |",
208
+ "",
209
+ "## Program charter",
210
+ "",
211
+ "### Goal",
212
+ "",
213
+ "- :::fill goal-description",
214
+ "",
215
+ "### Non-goals",
216
+ "",
217
+ "- :::fill non-goal-description",
218
+ "",
219
+ "### Cross-cutting",
220
+ "",
221
+ "- :::fill cross-cutting-description",
222
+ "",
223
+ "## Issue inventory",
224
+ "",
225
+ "| Phase | Issue (ref) | Title summary |",
226
+ "| --- | --- | --- |",
227
+ "| P1 | none | :::fill issue-title |",
228
+ "",
229
+ "## Phase inventory",
230
+ "",
231
+ "| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
232
+ "| --- | --- | --- | --- | --- | --- | --- |",
233
+ "| P1 | :::fill phase-name | :::fill scope | [Pending] | Pending | :::fill acceptance-criteria | :::fill dependency |",
234
+ "| P2 | :::fill phase-name | :::fill scope | [Pending] | Pending | :::fill acceptance-criteria | :::fill dependency |",
235
+ "",
236
+ "## Dependency graph",
237
+ "",
238
+ "P1 -> P2",
239
+ "- `->` = hard block",
240
+ "",
241
+ "## Boundary rules",
242
+ "",
243
+ "- :::fill boundary-rule",
244
+ "",
245
+ "## Constraints",
246
+ "",
247
+ "- :::fill constraint",
248
+ "",
249
+ "## Maintenance",
250
+ "",
251
+ "- :::fill maintenance-note",
252
+ "",
253
+ "## Change history",
254
+ "",
255
+ "| Version | date | summary | author |",
256
+ "| --- | --- | --- | --- |",
257
+ "| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
258
+ ].join("\n"),
259
+ );
260
+ });
261
+
262
+ it("renders the single-spec skeleton — the front-matter head + the prose sections + the lineage", () => {
263
+ expect(renderOf("single-spec")).toBe(
264
+ [
265
+ "---",
266
+ "title: ':::fill title'",
267
+ "doc-type: single-spec",
268
+ "version: v0.1",
269
+ "date: 2026-10-11",
270
+ "status: Draft",
271
+ "author: ':::fill author'",
272
+ "depends-on: ':::fill depends-on'",
273
+ "issues: ':::fill issues'",
274
+ "---",
275
+ "",
276
+ "## Background & root cause",
277
+ "",
278
+ ":::fill background-root-cause",
279
+ "",
280
+ "## Design decisions",
281
+ "",
282
+ ":::fill design-ruling",
283
+ "",
284
+ "## Acceptance",
285
+ "",
286
+ ":::fill acceptance",
287
+ "",
288
+ "## Constraints",
289
+ "",
290
+ ":::fill constraints",
291
+ "",
292
+ "## Change history",
293
+ "",
294
+ "| Version | date | summary | author |",
295
+ "| --- | --- | --- | --- |",
296
+ "| v0.1 | 2026-10-11 | :::fill summary | :::fill author |",
297
+ ].join("\n"),
298
+ );
299
+ });
300
+ });
301
+
302
+ describe("SkeletonAssembler — the required-anchor coverage probes (§3.2)", () => {
303
+ it("carries every required anchor of the four doc types (the live registry set)", () => {
304
+ for (const key of KEYS) {
305
+ const rendered = renderOf(key);
306
+ for (const anchor of requiredAnchorsOf(key)) {
307
+ // The grep probe per anchor — the skeleton line form of the anchor lands
308
+ // in the rendered bytes (headings and markers by their literal, the
309
+ // semantic anchors by their rendered value forms, the front-matter keys
310
+ // by their `key: ` declaration line).
311
+ expect(rendered, `${key}: ${anchor}`).toContain(probeOf(anchor));
312
+ }
313
+ }
314
+ });
315
+
316
+ it("renders the numeric headings as true numbers — zero literal `N`", () => {
317
+ const spec = renderOf("phase-spec");
318
+ expect(spec).toContain("### 1. :::fill group-title");
319
+ expect(spec).toContain("#### 1.1 :::fill item-title");
320
+ const plan = renderOf("plan");
321
+ expect(plan).toContain("### Task 1: :::fill task-title");
322
+ // the declared digit-headed anchors never render a literal `N` placeholder
323
+ expect(rendersNoLiteralN("phase-spec")).toBe(true);
324
+ expect(rendersNoLiteralN("plan")).toBe(true);
325
+ });
326
+
327
+ it("renders the version and date keys and the change-history first row with the injected date truth", () => {
328
+ for (const key of KEYS) {
329
+ const rendered = renderOf(key);
330
+ // the front-matter `version:` / `date:` truth keys — v0.1 · the injected
331
+ // run date (real shape hit, never a `<date>` notation marker)
332
+ expect(rendered).toContain("version: v0.1");
333
+ expect(rendered).toContain(`date: ${DATE}`);
334
+ // the change-history first row — the header version (v0.1) + the date cell
335
+ // + the summary/author content fills
336
+ expect(rendered).toContain(`| v0.1 | ${DATE} | :::fill summary | :::fill author |`);
337
+ // the header version equals the change-history row version (self-consistent
338
+ // lineage, ascending oldest-first with a single row)
339
+ const headerVersion = rendered.match(/^version: (v\d+\.\d+)$/m)?.[1];
340
+ expect(rendered).toContain(`| ${headerVersion} |`);
341
+ }
342
+ });
343
+
344
+ it("renders the generator truths — the enum status key and the graph rows", () => {
345
+ for (const key of ["overall-spec", "phase-spec", "single-spec"] as const) {
346
+ expect(renderOf(key)).toContain("status: Draft");
347
+ }
348
+ // the plan head carries no status key (its registry omits it)
349
+ expect(renderOf("plan")).not.toContain("status: ");
350
+ expect(renderOf("overall-spec")).toContain("P1 -> P2");
351
+ expect(renderOf("overall-spec")).toContain("- `->` = hard block");
352
+ });
353
+
354
+ it("renders every content position as a `:::fill <slot>` slot — the body and the front-matter content keys", () => {
355
+ for (const key of KEYS) {
356
+ const rendered = renderOf(key);
357
+ expect(rendered).toMatch(/:::fill \S+/g);
358
+ // the fill values are the declared slot names — never a residual `<…>`
359
+ // notation or a bare empty value
360
+ expect(rendered).not.toContain(":::fill <");
361
+ const block = frontmatterBlockOf(key);
362
+ for (const slot of frontmatterSlotsOf(key)) {
363
+ if (slot.slot === "content") {
364
+ expect(block, `${key}: ${slot.anchor} content fill`).toContain(
365
+ `${slot.anchor}: ':::fill ${slot.anchor}'`,
366
+ );
367
+ }
368
+ }
369
+ }
370
+ });
371
+
372
+ it("renders the link-typed anchors as placeholder scalars (the `<…>` exemption shape)", () => {
373
+ const spec = renderOf("phase-spec");
374
+ expect(spec).toContain("parent-program: <docs/kairos/specs/…-overall.md>");
375
+ const plan = renderOf("plan");
376
+ expect(plan).toContain("spec: <docs/kairos/specs/…-design.md>");
377
+ expect(plan).toContain("parent-program: <docs/kairos/specs/…-overall.md>");
378
+ });
379
+ });
380
+
381
+ describe("SkeletonAssembler — the front-matter head (spec §2.2/§4.2)", () => {
382
+ it("emits the projection's front-matter key set — the head parses back key-identical, zero extras", () => {
383
+ for (const key of KEYS) {
384
+ const block = frontmatterBlockOf(key);
385
+ const parsed = parse(block) as Record<string, unknown>;
386
+ const keys = frontmatterSlotsOf(key).map((slot) => slot.anchor);
387
+ expect(Object.keys(parsed).sort(), `${key}: yaml-key set = registry head set`).toEqual(
388
+ [...keys].sort(),
389
+ );
390
+ }
391
+ });
392
+
393
+ it("splits the §4.2 placeholder classes — truth keys never carry a fill, content keys always do, link keys the `<…>` shape", () => {
394
+ for (const key of KEYS) {
395
+ const lines = frontmatterBlockOf(key).split("\n");
396
+ for (const slot of frontmatterSlotsOf(key)) {
397
+ const line = lines.find((candidate) => candidate.startsWith(`${slot.anchor}: `));
398
+ expect(line, `${key}: ${slot.anchor} emitted`).toBeDefined();
399
+ if (slot.slot === "content") {
400
+ expect(line, `${key}: ${slot.anchor} content`).toBe(
401
+ `${slot.anchor}: ':::fill ${slot.anchor}'`,
402
+ );
403
+ } else if (slot.slot === "link") {
404
+ expect(line, `${key}: ${slot.anchor} link`).toMatch(
405
+ new RegExp(`^${slot.anchor}: <[^>]+>$`),
406
+ );
407
+ } else {
408
+ expect(line, `${key}: ${slot.anchor} truth`).not.toContain(":::fill");
409
+ }
410
+ }
411
+ }
412
+ });
413
+
414
+ it("emits the truth keys' true values — doc-type · v0.1 · the injected date · Draft", () => {
415
+ for (const key of KEYS) {
416
+ const block = frontmatterBlockOf(key);
417
+ expect(block).toContain(`doc-type: ${key}`);
418
+ expect(block).toContain("version: v0.1");
419
+ expect(block).toContain(`date: ${DATE}`);
420
+ if (key !== "plan") expect(block).toContain("status: Draft");
421
+ }
422
+ });
423
+
424
+ it("never emits the optional `parent-version` key — its `v<n>.<m>` domain admits no placeholder form", () => {
425
+ for (const key of ["plan", "phase-spec"] as const) {
426
+ expect(renderOf(key)).not.toContain("parent-version");
427
+ }
428
+ });
429
+
430
+ it("emits the type's optional front-matter keys — `base` / `depends-on` on the plan head, `issues` on the single-spec head", () => {
431
+ // §4.2's independent emission list = the head's required keys PLUS the
432
+ // type's optional head keys — the optional keys never ride the slot channel
433
+ // (they are not required), so the head would silently drop them without the
434
+ // dedicated list.
435
+ for (const key of KEYS) {
436
+ const block = frontmatterBlockOf(key);
437
+ const optionalAnchors = declaredRegistries[key].elements
438
+ .filter((element) => element.home === "frontmatter" && element.presence === "optional")
439
+ .map((element) => element.anchor)
440
+ .filter((anchor) => anchor !== "parent-version");
441
+ for (const anchor of optionalAnchors) {
442
+ expect(block, `${key}: optional head key ${anchor} emitted`).toContain(
443
+ `${anchor}: ':::fill ${anchor}'`,
444
+ );
445
+ }
446
+ }
447
+ expect(frontmatterBlockOf("plan")).toContain("base: ':::fill base'");
448
+ expect(frontmatterBlockOf("plan")).toContain("depends-on: ':::fill depends-on'");
449
+ expect(frontmatterBlockOf("single-spec")).toContain("issues: ':::fill issues'");
450
+ });
451
+ });
452
+
453
+ describe("SkeletonAssembler — the placeholder-anchoring probes (§4.1)", () => {
454
+ /** The structure/truth/header rows that must never carry a `:::fill` — the
455
+ * front-matter truth/link keys, the doc-type declaration, the fixed heading
456
+ * lines, the version row, the Status truth, the link anchors, the graph rows
457
+ * and the table headers/separators. */
458
+ const STRUCTURE_LINES: Record<string, readonly string[]> = {
459
+ "overall-spec": [
460
+ "doc-type: overall-spec",
461
+ "version: v0.1",
462
+ "date: 2026-10-11",
463
+ "status: Draft",
464
+ "## Document scope",
465
+ "## File paths",
466
+ "| Artifact | Path |",
467
+ "| --- | --- |",
468
+ "## Program charter",
469
+ "### Goal",
470
+ "### Non-goals",
471
+ "### Cross-cutting",
472
+ "## Issue inventory",
473
+ "| Phase | Issue (ref) | Title summary |",
474
+ "| --- | --- | --- |",
475
+ "## Phase inventory",
476
+ "| # | Phase | Scope | Design spec | Implementation plan | Acceptance criteria | Dependency |",
477
+ "| --- | --- | --- | --- | --- | --- | --- |",
478
+ "## Dependency graph",
479
+ "P1 -> P2",
480
+ "- `->` = hard block",
481
+ "## Boundary rules",
482
+ "## Constraints",
483
+ "## Maintenance",
484
+ "## Change history",
485
+ "| Version | date | summary | author |",
486
+ "| --- | --- | --- | --- |",
487
+ ],
488
+ plan: [
489
+ "doc-type: plan",
490
+ "version: v0.1",
491
+ "date: 2026-10-11",
492
+ "spec: <docs/kairos/specs/…-design.md>",
493
+ "parent-program: <docs/kairos/specs/…-overall.md>",
494
+ "## Constraints",
495
+ "## Change history",
496
+ "| Version | date | summary | author |",
497
+ "| --- | --- | --- | --- |",
498
+ ],
499
+ "phase-spec": [
500
+ "doc-type: phase-spec",
501
+ "version: v0.1",
502
+ "date: 2026-10-11",
503
+ "status: Draft",
504
+ "parent-program: <docs/kairos/specs/…-overall.md>",
505
+ "## Design",
506
+ "### Acceptance criteria",
507
+ "## Constraints",
508
+ "## Change history",
509
+ "| Version | date | summary | author |",
510
+ "| --- | --- | --- | --- |",
511
+ ],
512
+ "single-spec": [
513
+ "doc-type: single-spec",
514
+ "version: v0.1",
515
+ "date: 2026-10-11",
516
+ "status: Draft",
517
+ "## Background & root cause",
518
+ "## Design decisions",
519
+ "## Acceptance",
520
+ "## Constraints",
521
+ "## Change history",
522
+ "| Version | date | summary | author |",
523
+ "| --- | --- | --- | --- |",
524
+ ],
525
+ };
526
+
527
+ it("lands every `:::fill` on a content position — zero on the structure/truth/link/header rows", () => {
528
+ for (const key of KEYS) {
529
+ const lines = renderOf(key).split("\n");
530
+ for (const line of lines) {
531
+ if (!line.includes(":::fill")) continue;
532
+ expect(STRUCTURE_LINES[key], `${key}: ${line}`).not.toContain(line);
533
+ }
534
+ expect(renderOf(key)).not.toMatch(/\| --- \|.*:::fill/);
535
+ // the front-matter truth keys carry no fill inside the head block
536
+ for (const line of frontmatterBlockOf(key).split("\n")) {
537
+ if (line.includes(":::fill")) {
538
+ expect(line, `${key} head fill`).toMatch(/':::fill [a-z-]+'$/);
539
+ }
540
+ }
541
+ }
542
+ });
543
+
544
+ it("keeps structure true — the fixed headings and table headers carry no fill", () => {
545
+ for (const key of KEYS) {
546
+ const rendered = renderOf(key);
547
+ for (const line of STRUCTURE_LINES[key]) {
548
+ expect(rendered, `${key}: ${line}`).toContain(line);
549
+ if (!line.includes(":::")) expect(line).not.toContain(":::fill");
550
+ }
551
+ }
552
+ });
553
+ });
554
+
555
+ describe("SkeletonAssembler — the slot-consumption invariant (composition vs registry)", () => {
556
+ it("consumes every required slot of the four live projections — render() never trips the assertion", () => {
557
+ // The four not-to-throw pins also tripwire the overall Constraints
558
+ // triple-same-order composition: the declared `## Constraints` section anchor,
559
+ // the composed heading and the composed `Constraint delta bullet` must land in
560
+ // the same step — a heading without its bullet (or a bullet no longer
561
+ // required) omits a registered required slot and throws below.
562
+ for (const key of KEYS) {
563
+ expect(() => renderOf(key)).not.toThrow();
564
+ }
565
+ });
566
+
567
+ it("loud-throws on an unemitted required slot — a registered anchor the composition does not place", () => {
568
+ const plan = SKELETONS.plan;
569
+ const tampered: DocSkeleton = {
570
+ docType: plan.docType,
571
+ frontmatter: plan.frontmatter,
572
+ slots: [
573
+ ...plan.slots,
574
+ {
575
+ anchor: "**Guest anchor**",
576
+ presence: "required",
577
+ home: "section",
578
+ slot: "content",
579
+ refKind: "none",
580
+ },
581
+ ],
582
+ };
583
+ expect(() => new SkeletonAssembler(tampered, DATE).render()).toThrow(
584
+ /omits the registered required slot\(s\): \*\*Guest anchor\*\*/,
585
+ );
586
+ });
587
+
588
+ it("loud-throws on an emitted anchor the registry no longer requires — a composed anchor with no registered slot", () => {
589
+ const plan = SKELETONS.plan;
590
+ const tampered: DocSkeleton = {
591
+ docType: plan.docType,
592
+ frontmatter: plan.frontmatter,
593
+ slots: plan.slots.filter((slot) => slot.anchor !== "## Constraints"),
594
+ };
595
+ expect(() => new SkeletonAssembler(tampered, DATE).render()).toThrow(
596
+ /emits the unregistered anchor: ## Constraints/,
597
+ );
598
+ });
599
+ });
600
+
601
+ describe("SkeletonAssembler — the Doc type declaration (spec §3.1 ⑩ / D34)", () => {
602
+ it("declares the doc type in the front-matter head — `doc-type:` precedes `version:` (the registry key order)", () => {
603
+ for (const key of KEYS) {
604
+ const lines = frontmatterBlockOf(key).split("\n");
605
+ const docTypeIndex = lines.indexOf(`doc-type: ${key}`);
606
+ expect(docTypeIndex, `${key}: doc-type key present`).toBeGreaterThan(-1);
607
+ const versionIndex = lines.indexOf("version: v0.1");
608
+ expect(versionIndex, `${key}: version key present`).toBeGreaterThan(-1);
609
+ // the front-matter key order follows the registry's frontmatter-home slot
610
+ // order — doc-type (the doc-identity key) comes before the version row
611
+ expect(docTypeIndex, `${key}: doc-type before version`).toBeLessThan(versionIndex);
612
+ }
613
+ });
614
+
615
+ it("the engine-produced skeleton passes its OWN doc-type reader — BoardView.readDocType (self-preflight regression)", () => {
616
+ // The ⑩ defect: the engine's skeleton omitted the Doc type declaration, so a
617
+ // skeleton it produced failed its own preflight (BoardView.readDocType → null
618
+ // → BLOCK). After the front-matter flip the head's `doc-type:` key IS the
619
+ // canonical machine read — the board face reads the head record (§3.1 ⑩
620
+ // regression). This pin writes each skeleton to disk and asserts the doc-type
621
+ // reader returns the matching key — the writer/reader pair now agrees.
622
+ const dir = mkdtempSync(path.join(tmpdir(), "skeleton-doctype-"));
623
+ try {
624
+ for (const key of KEYS) {
625
+ const file = path.join(dir, `${key}.md`);
626
+ writeFileSync(file, `${renderOf(key)}\n`, "utf8");
627
+ expect(
628
+ BoardView.readDocType(new RepoRoot(dir), path.relative(dir, file) as RepoPath),
629
+ `${key}: skeleton fails its own doc-type read`,
630
+ ).toBe(key);
631
+ }
632
+ } finally {
633
+ rmSync(dir, { recursive: true, force: true });
634
+ }
635
+ });
636
+ });
637
+
638
+ describe("SkeletonAssembler — the doc-contract pin (the skeleton green by construction)", () => {
639
+ it("every rendered skeleton passes its own Contract.validate — zero findings on all four types", () => {
640
+ const contract = new Contract();
641
+ const dir = mkdtempSync(path.join(tmpdir(), "skeleton-contract-"));
642
+ try {
643
+ for (const key of KEYS) {
644
+ const file = path.join(dir, `${key}.md`);
645
+ writeFileSync(file, `${renderOf(key)}\n`, "utf8");
646
+ const findings = contract.validate({
647
+ docKey: key,
648
+ path: file,
649
+ content: readFileSync(file, "utf8"),
650
+ root: dir,
651
+ });
652
+ expect(findings, `${key}: skeleton fails its own contract judgment`).toEqual([]);
653
+ }
654
+ } finally {
655
+ rmSync(dir, { recursive: true, force: true });
656
+ }
657
+ });
658
+ });
659
+
660
+ describe("SkeletonAssembler — the EOF rule", () => {
661
+ it("render() never ends with a newline or a blank line — the redirected fixture ends with exactly one `\\n`", () => {
662
+ for (const key of KEYS) {
663
+ const rendered = renderOf(key);
664
+ expect(rendered.endsWith("\n"), `${key}: no trailing newline from render`).toBe(false);
665
+ expect(rendered.endsWith("\n\n") || rendered.endsWith(" \n"), `${key}: no blank tail`).toBe(
666
+ false,
667
+ );
668
+ const withCliNewline = `${rendered}\n`;
669
+ expect(withCliNewline.endsWith("\n")).toBe(true);
670
+ expect(withCliNewline.endsWith("\n\n"), `${key}: exactly one final newline`).toBe(false);
671
+ // the last line of the rendered bytes is real content, never a blank
672
+ const lastLine = rendered.split("\n").at(-1);
673
+ expect(lastLine?.trim().length, `${key}: last line non-blank`).toBeGreaterThan(0);
674
+ }
675
+ });
676
+ });
677
+
678
+ /** Whether any rendered skeleton line carries a literal `N` heading placeholder —
679
+ * the declared digit headings (`### N.` / `#### N.M` / `### Task N:`) always
680
+ * render true numbers, never the letter. */
681
+ const rendersNoLiteralN = (key: DocKey): boolean => {
682
+ const rendered = renderOf(key);
683
+ return !/(?:^|\n)#{2,4} (?:Task )?N[.:]/m.test(rendered) && !rendered.includes("Task N:");
684
+ };