@oscaner-skills/cdd-engine 2.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 (84) hide show
  1. package/README.md +2 -2
  2. package/README.zh-CN.md +2 -2
  3. package/package.json +4 -3
  4. package/src-next/__tests__/dead-decl.guard.test.ts +39 -0
  5. package/src-next/__tests__/floor.guard.test.ts +69 -0
  6. package/src-next/__tests__/issue-body.guard.test.ts +66 -0
  7. package/src-next/__tests__/phase-suffix.guard.test.ts +72 -0
  8. package/src-next/__tests__/smoke.integration.test.ts +60 -77
  9. package/src-next/__tests__/support/strip-comments.ts +99 -0
  10. package/src-next/__tests__/zero-dep.test.ts +6 -46
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +39 -21
  12. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +40 -28
  13. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +40 -23
  14. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +38 -21
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +21 -6
  16. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +22 -12
  17. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +23 -8
  18. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +21 -6
  19. package/src-next/contract/__tests__/declare.test.ts +251 -12
  20. package/src-next/contract/__tests__/doc.test.ts +214 -45
  21. package/src-next/contract/__tests__/dockey.guard.test.ts +58 -0
  22. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +81 -0
  23. package/src-next/contract/__tests__/frontmatter.test.ts +164 -0
  24. package/src-next/contract/__tests__/judge.test.ts +410 -172
  25. package/src-next/contract/__tests__/lint.test.ts +49 -39
  26. package/src-next/contract/__tests__/project.test.ts +60 -19
  27. package/src-next/contract/__tests__/structure-pin.test.ts +186 -0
  28. package/src-next/contract/declare.ts +179 -91
  29. package/src-next/contract/doc.ts +227 -164
  30. package/src-next/contract/frontmatter.ts +233 -0
  31. package/src-next/contract/home-extractors.ts +397 -0
  32. package/src-next/contract/invariants.ts +214 -69
  33. package/src-next/contract/judge.ts +28 -19
  34. package/src-next/contract/lint.ts +5 -41
  35. package/src-next/contract/project.ts +103 -43
  36. package/src-next/contract/skill-anatomy.ts +39 -11
  37. package/src-next/face/__tests__/board-view.test.ts +318 -115
  38. package/src-next/face/__tests__/capsule.test.ts +49 -25
  39. package/src-next/face/__tests__/channel-closure.guard.test.ts +28 -1
  40. package/src-next/face/__tests__/cli.test.ts +1091 -837
  41. package/src-next/face/__tests__/face.test.ts +5 -5
  42. package/src-next/face/__tests__/install-rows.guard.test.ts +58 -0
  43. package/src-next/face/__tests__/preview.test.ts +374 -0
  44. package/src-next/face/__tests__/projection.test.ts +5 -3
  45. package/src-next/face/__tests__/repo-root.guard.test.ts +120 -0
  46. package/src-next/face/__tests__/termination.test.ts +650 -0
  47. package/src-next/face/artifacts.ts +90 -37
  48. package/src-next/face/board-view.ts +128 -138
  49. package/src-next/face/capsule.ts +30 -16
  50. package/src-next/face/cli.ts +306 -97
  51. package/src-next/face/declare.ts +15 -18
  52. package/src-next/face/gate.ts +19 -18
  53. package/src-next/face/host.ts +6 -30
  54. package/src-next/face/lifecycle.ts +213 -188
  55. package/src-next/face/preview.ts +151 -0
  56. package/src-next/face/projection.ts +4 -1
  57. package/src-next/face/route-render.ts +39 -14
  58. package/src-next/face/termination.ts +573 -0
  59. package/src-next/face/words.ts +20 -2
  60. package/src-next/infra/__tests__/infra.test.ts +49 -3
  61. package/src-next/infra/__tests__/root.test.ts +56 -0
  62. package/src-next/infra/doc-roots.ts +29 -0
  63. package/src-next/infra/root.ts +73 -0
  64. package/src-next/infra/runtime.ts +12 -65
  65. package/src-next/infra/workspace.ts +95 -5
  66. package/src-next/render/__tests__/render.test.ts +92 -41
  67. package/src-next/render/__tests__/skeleton.test.ts +282 -64
  68. package/src-next/render/issue-body.ts +5 -2
  69. package/src-next/render/skeleton.ts +155 -90
  70. package/src-next/render/templates.ts +51 -56
  71. package/src-next/session/__tests__/graph.test.ts +11 -4
  72. package/src-next/session/__tests__/ledger.test.ts +3 -2
  73. package/src-next/session/__tests__/next.test.ts +100 -8
  74. package/src-next/session/__tests__/preflight.test.ts +79 -25
  75. package/src-next/session/__tests__/round-naming.test.ts +142 -0
  76. package/src-next/session/__tests__/run.test.ts +140 -128
  77. package/src-next/session/__tests__/wave.test.ts +11 -4
  78. package/src-next/session/ledger.ts +96 -24
  79. package/src-next/session/next.ts +116 -15
  80. package/src-next/session/preflight.ts +41 -10
  81. package/src-next/session/round-naming.ts +84 -0
  82. package/src-next/session/run.ts +24 -20
  83. package/templates/report/issue-body.json +0 -46
  84. package/src-next/face/__tests__/sync-runner.test.ts +0 -70
@@ -1,37 +1,66 @@
1
1
  // packages/cdd-engine/src-next/render/__tests__/skeleton.test.ts
2
2
  // The SkeletonAssembler suite (P2 — the `cdd schema get <type> --output skeleton`
3
- // render face, spec §3/§4.1):
3
+ // render face, spec §3/§4.1/§4.2):
4
4
  // · the four doc skeletons render the complete structural scaffolds — byte-
5
5
  // pinned from the P2 first version (the assembler's date is the injectable
6
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);
7
12
  // · the placeholder-anchoring probes (spec §4.1): pure content slots take
8
13
  // `:::fill <slot>`, the link-shaped anchors the placeholder links, the
9
14
  // pattern-typed rows the generator truths, and `:::fill` never lands on a
10
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);
11
19
  // · the EOF rule — render() never ends with a newline or a blank line; the
12
20
  // CLI's single appended `\n` leaves a redirected fixture with exactly one
13
21
  // final newline.
14
22
 
23
+ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
24
+ import { tmpdir } from "node:os";
25
+ import path from "node:path";
15
26
  import { describe, expect, it } from "vitest";
27
+ import { parse } from "yaml";
16
28
  import { declaredRegistries } from "../../contract/declare.ts";
17
- import type { DocKey, DocSkeleton } from "../../contract/project.ts";
29
+ import { Contract } from "../../contract/judge.ts";
30
+ import type { DocKey, DocSkeleton, SkeletonSlot } from "../../contract/project.ts";
18
31
  import { Projector } from "../../contract/project.ts";
32
+ import { BoardView } from "../../face/board-view.ts";
33
+ import { type RepoPath, RepoRoot } from "../../infra/root.ts";
19
34
  import { SkeletonAssembler } from "../skeleton.ts";
20
35
 
21
36
  /** The fixed run date — the injectable run-day truth (no live clock in the pins). */
22
37
  const DATE = "2026-10-11";
23
38
  const PROJECTOR = new Projector(declaredRegistries);
24
39
  const SKELETONS = PROJECTOR.skeleton();
40
+ const KEYS = ["overall-spec", "plan", "phase-spec", "single-spec"] as const;
25
41
 
26
42
  /** The fixed-date rendered skeleton bytes of one doc type. */
27
43
  const renderOf = (key: DocKey): string => new SkeletonAssembler(SKELETONS[key], DATE).render();
28
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
+
29
53
  /** The registered required anchors of one doc type (the live registry). */
30
54
  const requiredAnchorsOf = (key: DocKey): readonly string[] =>
31
55
  declaredRegistries[key].elements
32
56
  .filter((element) => element.presence === "required")
33
57
  .map((element) => element.anchor);
34
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
+
35
64
  /** The per-anchor skeleton probe of the semantic anchors — the anchors whose
36
65
  * skeleton form is NOT their literal token (the numeric headings, the table row /
37
66
  * cell values, the graph rows and the parse-face names). The literal-marker
@@ -65,28 +94,33 @@ const SEMANTIC_PROBES: Record<string, string> = {
65
94
  };
66
95
 
67
96
  /** 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). */
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. */
71
101
  const probeOf = (anchor: string): string => {
72
102
  const semantic = SEMANTIC_PROBES[anchor];
73
103
  if (semantic !== undefined) return semantic;
74
104
  if (anchor.startsWith("# ")) return "# :::fill title";
75
105
  if (anchor.startsWith("#")) return anchor;
76
- if (anchor.startsWith("**")) return anchor === "**Spec:**" ? "**Spec:**" : `- ${anchor}:`;
77
- return anchor;
106
+ if (anchor.startsWith("**")) return `- ${anchor}:`;
107
+ return `${anchor}: `;
78
108
  };
79
109
 
80
110
  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", () => {
111
+ it("renders the phase-spec skeleton — the front-matter head + the Design double layer + the lineage", () => {
82
112
  expect(renderOf("phase-spec")).toBe(
83
113
  [
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",
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
+ "---",
90
124
  "",
91
125
  "## Design",
92
126
  "",
@@ -113,13 +147,19 @@ describe("SkeletonAssembler — the four doc skeletons (byte pins)", () => {
113
147
  );
114
148
  });
115
149
 
116
- it("renders the plan skeleton — the Class-A/B header + the first task block + the lineage", () => {
150
+ it("renders the plan skeleton — the Class-A/B front-matter head + the first task block + the lineage", () => {
117
151
  expect(renderOf("plan")).toBe(
118
152
  [
119
- "# :::fill title",
120
- "**Spec:** [<spec path>](<spec path>)",
121
- "- **Parent program**: [<parent overall>](<parent path>)",
122
- "- **Version**: v0.1 · 2026-10-11",
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
+ "---",
123
163
  "",
124
164
  "## Constraints",
125
165
  "",
@@ -144,14 +184,17 @@ describe("SkeletonAssembler — the four doc skeletons (byte pins)", () => {
144
184
  );
145
185
  });
146
186
 
147
- it("renders the overall skeleton — the header tuple + the table sections + the dependency graph", () => {
187
+ it("renders the overall skeleton — the front-matter head + the table sections + the dependency graph", () => {
148
188
  expect(renderOf("overall-spec")).toBe(
149
189
  [
150
- "# :::fill title",
151
- "- **Version**: v0.1 · 2026-10-11",
152
- "- **Status**: Draft",
153
- "- **Author**: :::fill author",
154
- "- **Constraints**: :::fill constraints",
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
+ "---",
155
198
  "",
156
199
  "## Document scope",
157
200
  "",
@@ -199,6 +242,10 @@ describe("SkeletonAssembler — the four doc skeletons (byte pins)", () => {
199
242
  "",
200
243
  "- :::fill boundary-rule",
201
244
  "",
245
+ "## Constraints",
246
+ "",
247
+ "- :::fill constraint",
248
+ "",
202
249
  "## Maintenance",
203
250
  "",
204
251
  "- :::fill maintenance-note",
@@ -212,14 +259,19 @@ describe("SkeletonAssembler — the four doc skeletons (byte pins)", () => {
212
259
  );
213
260
  });
214
261
 
215
- it("renders the single-spec skeleton — the header five-tuple + the prose sections + the lineage", () => {
262
+ it("renders the single-spec skeleton — the front-matter head + the prose sections + the lineage", () => {
216
263
  expect(renderOf("single-spec")).toBe(
217
264
  [
218
- "# :::fill title",
219
- "- **Version**: v0.1 · 2026-10-11",
220
- "- **Status**: Draft",
221
- "- **Author**: :::fill author",
222
- "- **Depends on**: :::fill depends-on",
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
+ "---",
223
275
  "",
224
276
  "## Background & root cause",
225
277
  "",
@@ -249,12 +301,13 @@ describe("SkeletonAssembler — the four doc skeletons (byte pins)", () => {
249
301
 
250
302
  describe("SkeletonAssembler — the required-anchor coverage probes (§3.2)", () => {
251
303
  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) {
304
+ for (const key of KEYS) {
253
305
  const rendered = renderOf(key);
254
306
  for (const anchor of requiredAnchorsOf(key)) {
255
307
  // The grep probe per anchor — the skeleton line form of the anchor lands
256
308
  // in the rendered bytes (headings and markers by their literal, the
257
- // semantic anchors by their rendered value forms).
309
+ // semantic anchors by their rendered value forms, the front-matter keys
310
+ // by their `key: ` declaration line).
258
311
  expect(rendered, `${key}: ${anchor}`).toContain(probeOf(anchor));
259
312
  }
260
313
  }
@@ -271,57 +324,143 @@ describe("SkeletonAssembler — the required-anchor coverage probes (§3.2)", ()
271
324
  expect(rendersNoLiteralN("plan")).toBe(true);
272
325
  });
273
326
 
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) {
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) {
276
329
  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}`);
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}`);
280
334
  // the change-history first row — the header version (v0.1) + the date cell
281
335
  // + the summary/author content fills
282
336
  expect(rendered).toContain(`| v0.1 | ${DATE} | :::fill summary | :::fill author |`);
283
337
  // the header version equals the change-history row version (self-consistent
284
338
  // lineage, ascending oldest-first with a single row)
285
- const headerVersion = rendered.match(/- \*\*Version\*\*: (v\d+\.\d+) ·/)?.[1];
339
+ const headerVersion = rendered.match(/^version: (v\d+\.\d+)$/m)?.[1];
286
340
  expect(rendered).toContain(`| ${headerVersion} |`);
287
341
  }
288
342
  });
289
343
 
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");
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");
293
347
  }
348
+ // the plan head carries no status key (its registry omits it)
349
+ expect(renderOf("plan")).not.toContain("status: ");
294
350
  expect(renderOf("overall-spec")).toContain("P1 -> P2");
295
351
  expect(renderOf("overall-spec")).toContain("- `->` = hard block");
296
352
  });
297
353
 
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) {
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) {
300
356
  const rendered = renderOf(key);
301
357
  expect(rendered).toMatch(/:::fill \S+/g);
302
358
  // the fill values are the declared slot names — never a residual `<…>`
303
359
  // notation or a bare empty value
304
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
+ }
305
369
  }
306
370
  });
307
371
 
308
- it("renders the link-typed anchors as placeholder links (label + target `<…>` literals)", () => {
372
+ it("renders the link-typed anchors as placeholder scalars (the `<…>` exemption shape)", () => {
309
373
  const spec = renderOf("phase-spec");
310
- expect(spec).toContain("- **Parent program**: [<parent overall>](<parent path>)");
374
+ expect(spec).toContain("parent-program: <docs/kairos/specs/…-overall.md>");
311
375
  const plan = renderOf("plan");
312
- expect(plan).toContain("**Spec:** [<spec path>](<spec path>)");
313
- expect(plan).toContain("- **Parent program**: [<parent overall>](<parent path>)");
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'");
314
450
  });
315
451
  });
316
452
 
317
453
  describe("SkeletonAssembler — the placeholder-anchoring probes (§4.1)", () => {
318
454
  /** 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. */
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. */
321
458
  const STRUCTURE_LINES: Record<string, readonly string[]> = {
322
459
  "overall-spec": [
323
- "- **Version**: v0.1 · 2026-10-11",
324
- "- **Status**: Draft",
460
+ "doc-type: overall-spec",
461
+ "version: v0.1",
462
+ "date: 2026-10-11",
463
+ "status: Draft",
325
464
  "## Document scope",
326
465
  "## File paths",
327
466
  "| Artifact | Path |",
@@ -340,24 +479,29 @@ describe("SkeletonAssembler — the placeholder-anchoring probes (§4.1)", () =>
340
479
  "P1 -> P2",
341
480
  "- `->` = hard block",
342
481
  "## Boundary rules",
482
+ "## Constraints",
343
483
  "## Maintenance",
344
484
  "## Change history",
345
485
  "| Version | date | summary | author |",
346
486
  "| --- | --- | --- | --- |",
347
487
  ],
348
488
  plan: [
349
- "- **Version**: v0.1 · 2026-10-11",
350
- "**Spec:** [<spec path>](<spec path>)",
351
- "- **Parent program**: [<parent overall>](<parent path>)",
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>",
352
494
  "## Constraints",
353
495
  "## Change history",
354
496
  "| Version | date | summary | author |",
355
497
  "| --- | --- | --- | --- |",
356
498
  ],
357
499
  "phase-spec": [
358
- "- **Version**: v0.1 · 2026-10-11",
359
- "- **Status**: Draft",
360
- "- **Parent program**: [<parent overall>](<parent path>)",
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>",
361
505
  "## Design",
362
506
  "### Acceptance criteria",
363
507
  "## Constraints",
@@ -366,8 +510,10 @@ describe("SkeletonAssembler — the placeholder-anchoring probes (§4.1)", () =>
366
510
  "| --- | --- | --- | --- |",
367
511
  ],
368
512
  "single-spec": [
369
- "- **Version**: v0.1 · 2026-10-11",
370
- "- **Status**: Draft",
513
+ "doc-type: single-spec",
514
+ "version: v0.1",
515
+ "date: 2026-10-11",
516
+ "status: Draft",
371
517
  "## Background & root cause",
372
518
  "## Design decisions",
373
519
  "## Acceptance",
@@ -379,18 +525,24 @@ describe("SkeletonAssembler — the placeholder-anchoring probes (§4.1)", () =>
379
525
  };
380
526
 
381
527
  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) {
528
+ for (const key of KEYS) {
383
529
  const lines = renderOf(key).split("\n");
384
530
  for (const line of lines) {
385
531
  if (!line.includes(":::fill")) continue;
386
532
  expect(STRUCTURE_LINES[key], `${key}: ${line}`).not.toContain(line);
387
533
  }
388
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
+ }
389
541
  }
390
542
  });
391
543
 
392
544
  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) {
545
+ for (const key of KEYS) {
394
546
  const rendered = renderOf(key);
395
547
  for (const line of STRUCTURE_LINES[key]) {
396
548
  expect(rendered, `${key}: ${line}`).toContain(line);
@@ -402,7 +554,12 @@ describe("SkeletonAssembler — the placeholder-anchoring probes (§4.1)", () =>
402
554
 
403
555
  describe("SkeletonAssembler — the slot-consumption invariant (composition vs registry)", () => {
404
556
  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) {
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) {
406
563
  expect(() => renderOf(key)).not.toThrow();
407
564
  }
408
565
  });
@@ -411,6 +568,7 @@ describe("SkeletonAssembler — the slot-consumption invariant (composition vs r
411
568
  const plan = SKELETONS.plan;
412
569
  const tampered: DocSkeleton = {
413
570
  docType: plan.docType,
571
+ frontmatter: plan.frontmatter,
414
572
  slots: [
415
573
  ...plan.slots,
416
574
  {
@@ -431,6 +589,7 @@ describe("SkeletonAssembler — the slot-consumption invariant (composition vs r
431
589
  const plan = SKELETONS.plan;
432
590
  const tampered: DocSkeleton = {
433
591
  docType: plan.docType,
592
+ frontmatter: plan.frontmatter,
434
593
  slots: plan.slots.filter((slot) => slot.anchor !== "## Constraints"),
435
594
  };
436
595
  expect(() => new SkeletonAssembler(tampered, DATE).render()).toThrow(
@@ -439,9 +598,68 @@ describe("SkeletonAssembler — the slot-consumption invariant (composition vs r
439
598
  });
440
599
  });
441
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
+
442
660
  describe("SkeletonAssembler — the EOF rule", () => {
443
661
  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) {
662
+ for (const key of KEYS) {
445
663
  const rendered = renderOf(key);
446
664
  expect(rendered.endsWith("\n"), `${key}: no trailing newline from render`).toBe(false);
447
665
  expect(rendered.endsWith("\n\n") || rendered.endsWith(" \n"), `${key}: no blank tail`).toBe(
@@ -17,6 +17,7 @@
17
17
  // Module-level exports are types / the class — zero behavior-carrying bare functions.
18
18
 
19
19
  import type { Translator, WordLocaleFace } from "../contract/translate.ts";
20
+ import { ISSUE_TYPES } from "../face/words.ts";
20
21
 
21
22
  /** One finding row of the issue-report input. */
22
23
  export interface ReportFindingInput {
@@ -48,8 +49,10 @@ export interface IssueReportInput {
48
49
  * (open hits) → Related (closed hits + program). Pure deterministic text.
49
50
  */
50
51
  export class IssueBodyRenderer {
51
- /** The finding-type vocabulary (the canonical type set). */
52
- readonly types: readonly string[] = ["bug", "enhancement", "chore"];
52
+ /** The finding-type vocabulary (the canonical type set) — the word table's
53
+ * `ISSUE_TYPES` (derived from the issue-label rows, the ONE type source), never a
54
+ * second hand-written list. */
55
+ readonly types: readonly string[] = ISSUE_TYPES;
53
56
  /** The four text-segment keys, in the render order. */
54
57
  readonly #segments: readonly string[] = ["context", "problem", "impact", "suggestedFix"];
55
58
  /** The word table's locale face — the langs projection + the label rows. */