@oscaner-skills/cdd-engine 3.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 (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +141 -0
  15. package/dist/face/cli.js +891 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +603 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +482 -0
  25. package/dist/face/words.js +220 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +441 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -1,684 +0,0 @@
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
- };