@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,100 @@
1
+ {
2
+ "docType": "single-spec",
3
+ "structure": [
4
+ {
5
+ "home": "frontmatter",
6
+ "elements": [
7
+ {
8
+ "anchor": "title",
9
+ "presence": "required",
10
+ "refKind": "none"
11
+ },
12
+ {
13
+ "anchor": "doc-type",
14
+ "presence": "required",
15
+ "refKind": "none"
16
+ },
17
+ {
18
+ "anchor": "version",
19
+ "presence": "required",
20
+ "refKind": "version-lineage"
21
+ },
22
+ {
23
+ "anchor": "date",
24
+ "presence": "required",
25
+ "refKind": "none"
26
+ },
27
+ {
28
+ "anchor": "status",
29
+ "presence": "required",
30
+ "refKind": "none"
31
+ },
32
+ {
33
+ "anchor": "author",
34
+ "presence": "required",
35
+ "refKind": "none"
36
+ },
37
+ {
38
+ "anchor": "depends-on",
39
+ "presence": "required",
40
+ "refKind": "none"
41
+ },
42
+ {
43
+ "anchor": "issues",
44
+ "presence": "optional",
45
+ "refKind": "none"
46
+ }
47
+ ]
48
+ },
49
+ {
50
+ "home": "section",
51
+ "elements": [
52
+ {
53
+ "anchor": "## Background & root cause",
54
+ "presence": "required",
55
+ "refKind": "none"
56
+ },
57
+ {
58
+ "anchor": "## Design decisions",
59
+ "presence": "required",
60
+ "refKind": "none"
61
+ },
62
+ {
63
+ "anchor": "## Acceptance",
64
+ "presence": "required",
65
+ "refKind": "none"
66
+ },
67
+ {
68
+ "anchor": "## Constraints",
69
+ "presence": "required",
70
+ "refKind": "none"
71
+ },
72
+ {
73
+ "anchor": "## Change history",
74
+ "presence": "required",
75
+ "refKind": "none"
76
+ }
77
+ ]
78
+ },
79
+ {
80
+ "home": "table",
81
+ "elements": [
82
+ {
83
+ "anchor": "Change history row",
84
+ "presence": "required",
85
+ "refKind": "version-lineage"
86
+ },
87
+ {
88
+ "anchor": "Version token",
89
+ "presence": "required",
90
+ "refKind": "version-lineage"
91
+ },
92
+ {
93
+ "anchor": "Change history date",
94
+ "presence": "required",
95
+ "refKind": "none"
96
+ }
97
+ ]
98
+ }
99
+ ]
100
+ }
@@ -0,0 +1,481 @@
1
+ // packages/cdd-engine/src-next/contract/__tests__/declare.test.ts
2
+ // T2 test suite for the element-registry declaration (contract/declare.ts).
3
+ //
4
+ // The declare module is the doc contract's single declaration: one typed
5
+ // registry per doc type (overall-spec / plan / phase-spec / single-spec). These
6
+ // tests pin the acceptance gates of the declared data — every full doc type
7
+ // carrying at least MIN_ELEMENTS registered elements (single-spec is the declared
8
+ // lightweight exception, exempted by name), each doc type's body side
9
+ // (non-frontmatter homes) kept within MAX_BODY_ELEMENTS and its header side
10
+ // (the frontmatter surface) within MAX_HEADER_ELEMENTS, every element carrying
11
+ // all five fields (anchor · presence · value pattern · ref kind · home), the
12
+ // presence and ref-kind vocabularies staying inside their legal domains, and
13
+ // anchors unique per registry — plus the
14
+ // runtime type guards and the type-level contract surface.
15
+ //
16
+ // The legal value vocabularies are pinned here as the spec-side source of truth
17
+ // (an independent authority from the implementation): the guard or the data may
18
+ // never drift outside these domains. The negative type checks (a missing home,
19
+ // a missing elements surface) are pinned by expectTypeOf(...).not.toMatchTypeOf
20
+ // assertions: if a required field ever stopped being required, the incomplete
21
+ // shapes below would satisfy the type and the assertion itself would become a
22
+ // compile error, which the `tsc -p packages/cdd-engine --noEmit` gate fails on —
23
+ // so the compile surface is pinned even though vitest transforms types away.
24
+
25
+ import { describe, expect, expectTypeOf, it } from "vitest";
26
+ import type {
27
+ DocType,
28
+ ElementRegistry,
29
+ Home,
30
+ Presence,
31
+ RefKind,
32
+ RegistryElement,
33
+ } from "../declare.ts";
34
+ import { declaredRegistries, RegistryGuard } from "../declare.ts";
35
+
36
+ const PRESENCE_VALUES = [
37
+ "required",
38
+ "optional",
39
+ "conditional",
40
+ ] as const satisfies readonly Presence[];
41
+ const REF_KIND_VALUES = [
42
+ "none",
43
+ "version-lineage",
44
+ "markdown-link",
45
+ "phase-id",
46
+ "issue-ref",
47
+ "spec-ref",
48
+ "parent-program",
49
+ "task-id",
50
+ ] as const satisfies readonly RefKind[];
51
+ const HOME_VALUES = [
52
+ "frontmatter",
53
+ "section",
54
+ "facet",
55
+ "table",
56
+ "graph",
57
+ "task-block",
58
+ "task-field",
59
+ "task-step",
60
+ "design-body",
61
+ "conditional",
62
+ ] as const satisfies readonly Home[];
63
+
64
+ const MIN_ELEMENTS = 20;
65
+ /** The body-side element gate — every non-frontmatter home (section / facet / table /
66
+ * graph / task-block / task-field / task-step / design-body / conditional) tallies into
67
+ * the body side; a doc type's body side must stay at or below this count. The value (40)
68
+ * keeps today's live body-side highs (overall-spec 34 · plan 22 · phase-spec 18 ·
69
+ * single-spec 8) inside the gate with the post-migration additions' margin. */
70
+ const MAX_BODY_ELEMENTS = 40;
71
+ /** The header-side element gate — the frontmatter surface (H1 + metadata rows). Today's
72
+ * live header counts run overall-spec 5 / plan 6 / phase-spec 7 / single-spec 5; 12 keeps
73
+ * the post-migration header additions inside the gate with margin. */
74
+ const MAX_HEADER_ELEMENTS = 12;
75
+ /** The two home partitions — the header side is the single `frontmatter` surface; the body
76
+ * side is every remaining declared home (derived from HOME_VALUES, so a newly declared
77
+ * home is classified body-side until explicitly moved into the header partition). */
78
+ const HEADER_HOMES: ReadonlySet<Home> = new Set(["frontmatter"]);
79
+ const BODY_HOMES: ReadonlySet<Home> = new Set(
80
+ HOME_VALUES.filter((home) => !HEADER_HOMES.has(home)),
81
+ );
82
+ /** Count the elements of a registry whose home falls inside the given partition. */
83
+ const countByHome = (registry: ElementRegistry, homes: ReadonlySet<Home>): number =>
84
+ registry.elements.filter((element) => homes.has(element.home)).length;
85
+ /** The declared light-weight exception — single-spec is a deliberately sparse
86
+ * scaffold (header five-tuple + four prose sections + the change-history trio)
87
+ * whose registered element set sits below the full-doc band by design
88
+ * (declare.ts); it is exempted from the band and pinned separately. */
89
+ const LIGHTWEIGHT_DOC_TYPES: ReadonlySet<string> = new Set(["single-spec"]);
90
+
91
+ const ALL_REGISTRIES = [
92
+ declaredRegistries["overall-spec"],
93
+ declaredRegistries.plan,
94
+ declaredRegistries["phase-spec"],
95
+ declaredRegistries["single-spec"],
96
+ ] as const satisfies readonly ElementRegistry[];
97
+
98
+ describe("declared registries", () => {
99
+ it("declares exactly the four doc types with their docType identity", () => {
100
+ expect(declaredRegistries["overall-spec"].docType).toBe("overall-spec");
101
+ expect(declaredRegistries.plan.docType).toBe("plan");
102
+ expect(declaredRegistries["phase-spec"].docType).toBe("phase-spec");
103
+ expect(declaredRegistries["single-spec"].docType).toBe("single-spec");
104
+ });
105
+
106
+ it("carries at least 20 elements per full doc type (acceptance count gate)", () => {
107
+ for (const registry of ALL_REGISTRIES) {
108
+ if (LIGHTWEIGHT_DOC_TYPES.has(registry.docType)) continue;
109
+ expect(registry.elements.length, `${registry.docType} element count`).toBeGreaterThanOrEqual(
110
+ MIN_ELEMENTS,
111
+ );
112
+ }
113
+ });
114
+
115
+ it("keeps the header side (frontmatter home) within MAX_HEADER_ELEMENTS per doc type", () => {
116
+ for (const registry of ALL_REGISTRIES) {
117
+ expect(
118
+ countByHome(registry, HEADER_HOMES),
119
+ `${registry.docType} header element count`,
120
+ ).toBeLessThanOrEqual(MAX_HEADER_ELEMENTS);
121
+ }
122
+ });
123
+
124
+ it("keeps the body side (every non-frontmatter home) within MAX_BODY_ELEMENTS per doc type", () => {
125
+ for (const registry of ALL_REGISTRIES) {
126
+ expect(
127
+ countByHome(registry, BODY_HOMES),
128
+ `${registry.docType} body element count`,
129
+ ).toBeLessThanOrEqual(MAX_BODY_ELEMENTS);
130
+ }
131
+ });
132
+
133
+ it("keeps the light-weight doc types below the band by design (explicit exemption)", () => {
134
+ for (const registry of ALL_REGISTRIES) {
135
+ if (!LIGHTWEIGHT_DOC_TYPES.has(registry.docType)) continue;
136
+ expect(registry.elements.length, `${registry.docType} element count`).toBeLessThan(
137
+ MIN_ELEMENTS,
138
+ );
139
+ expect(registry.elements.length, `${registry.docType} element count`).toBeGreaterThan(0);
140
+ }
141
+ });
142
+
143
+ it("fills all five fields on every element (anchor · presence · valuePattern · refKind · home)", () => {
144
+ for (const registry of ALL_REGISTRIES) {
145
+ for (const element of registry.elements) {
146
+ expect(element.anchor.length, `${registry.docType} anchor`).toBeGreaterThan(0);
147
+ expect(PRESENCE_VALUES, `${registry.docType}:${element.anchor} presence`).toContain(
148
+ element.presence,
149
+ );
150
+ expect(
151
+ typeof element.valuePattern,
152
+ `${registry.docType}:${element.anchor} valuePattern`,
153
+ ).toBe("string");
154
+ expect(REF_KIND_VALUES, `${registry.docType}:${element.anchor} refKind`).toContain(
155
+ element.refKind,
156
+ );
157
+ expect(HOME_VALUES, `${registry.docType}:${element.anchor} home`).toContain(element.home);
158
+ }
159
+ }
160
+ });
161
+
162
+ it("keeps anchors unique within each registry", () => {
163
+ for (const registry of ALL_REGISTRIES) {
164
+ const seen = new Set<string>();
165
+ for (const element of registry.elements) {
166
+ expect(
167
+ seen.has(element.anchor),
168
+ `${registry.docType} duplicate anchor: ${element.anchor}`,
169
+ ).toBe(false);
170
+ seen.add(element.anchor);
171
+ }
172
+ }
173
+ });
174
+
175
+ it("keeps the ref-kind vocabulary inside its legal enum", () => {
176
+ const legal = new Set<unknown>(REF_KIND_VALUES);
177
+ for (const registry of ALL_REGISTRIES) {
178
+ for (const element of registry.elements) {
179
+ expect(element.refKind, `${registry.docType}:${element.anchor} refKind`).toBeDefined();
180
+ expect(legal.has(element.refKind), `${registry.docType}:${element.anchor} refKind`).toBe(
181
+ true,
182
+ );
183
+ }
184
+ }
185
+ });
186
+ });
187
+
188
+ describe("frontmatter header-key contract (spec §2.3 / §3.3)", () => {
189
+ // The canonical per-type front-matter key set of the contraction table (§2.3):
190
+ // plan deliberately omits `status`/`author` (no plan head carries either row),
191
+ // single-spec adds the optional `issues` key, plan/phase-spec add the optional
192
+ // `parent-version`. The order mirrors the §2.1 front-matter emission shapes.
193
+ const HEADER_KEYS: Record<DocType, readonly string[]> = {
194
+ "overall-spec": ["title", "doc-type", "version", "date", "status", "author"],
195
+ plan: [
196
+ "title",
197
+ "doc-type",
198
+ "version",
199
+ "date",
200
+ "spec",
201
+ "parent-program",
202
+ "parent-version",
203
+ "depends-on",
204
+ "base",
205
+ ],
206
+ "phase-spec": [
207
+ "title",
208
+ "doc-type",
209
+ "version",
210
+ "date",
211
+ "status",
212
+ "author",
213
+ "parent-program",
214
+ "parent-version",
215
+ "depends-on",
216
+ ],
217
+ "single-spec": [
218
+ "title",
219
+ "doc-type",
220
+ "version",
221
+ "date",
222
+ "status",
223
+ "author",
224
+ "depends-on",
225
+ "issues",
226
+ ],
227
+ };
228
+ /** The closed §3.3 key vocabulary — the registry's sole legal front-matter anchor set. */
229
+ const KEY_VOCABULARY = new Set([
230
+ "title",
231
+ "doc-type",
232
+ "version",
233
+ "date",
234
+ "status",
235
+ "author",
236
+ "spec",
237
+ "parent-program",
238
+ "parent-version",
239
+ "depends-on",
240
+ "base",
241
+ "issues",
242
+ ]);
243
+ const findKey = (docType: DocType, anchor: string): RegistryElement =>
244
+ declaredRegistries[docType].elements.find((element) => element.anchor === anchor)!;
245
+
246
+ it("registers exactly the canonical front-matter key set per doc type, in order", () => {
247
+ for (const registry of ALL_REGISTRIES) {
248
+ expect(
249
+ registry.elements
250
+ .filter((element) => element.home === "frontmatter")
251
+ .map((element) => element.anchor),
252
+ `${registry.docType} header keys`,
253
+ ).toEqual(HEADER_KEYS[registry.docType]);
254
+ }
255
+ });
256
+
257
+ it("keeps every front-matter anchor inside the §3.3 key vocabulary — zero bullet/heading literals", () => {
258
+ for (const registry of ALL_REGISTRIES) {
259
+ for (const element of registry.elements.filter((element) => element.home === "frontmatter")) {
260
+ expect(KEY_VOCABULARY.has(element.anchor), `${registry.docType}:${element.anchor}`).toBe(
261
+ true,
262
+ );
263
+ expect(element.anchor, `${registry.docType}:${element.anchor}`).not.toMatch(/^# /);
264
+ expect(element.anchor, `${registry.docType}:${element.anchor}`).not.toContain("**");
265
+ }
266
+ }
267
+ });
268
+
269
+ it("assigns the per-type presence per the §2.3 contraction table", () => {
270
+ // The four-type required keys.
271
+ for (const anchor of ["title", "doc-type", "version", "date"]) {
272
+ for (const registry of ALL_REGISTRIES) {
273
+ expect(findKey(registry.docType, anchor).presence, `${registry.docType}:${anchor}`).toBe(
274
+ "required",
275
+ );
276
+ }
277
+ }
278
+ // `status`/`author` ride the three spec carriers — plan has no such key.
279
+ for (const docType of ["overall-spec", "phase-spec", "single-spec"] as const) {
280
+ expect(findKey(docType, "status").presence).toBe("required");
281
+ expect(findKey(docType, "author").presence).toBe("required");
282
+ }
283
+ expect(declaredRegistries.plan.elements.some((element) => element.anchor === "status")).toBe(
284
+ false,
285
+ );
286
+ expect(declaredRegistries.plan.elements.some((element) => element.anchor === "author")).toBe(
287
+ false,
288
+ );
289
+ // `spec` is plan-only (the plan's design-spec pointer).
290
+ expect(findKey("plan", "spec").presence).toBe("required");
291
+ for (const docType of ["overall-spec", "phase-spec", "single-spec"] as const) {
292
+ expect(
293
+ declaredRegistries[docType].elements.some((element) => element.anchor === "spec"),
294
+ `${docType} has no spec key`,
295
+ ).toBe(false);
296
+ }
297
+ // `parent-program` required on the two Class-B carriers.
298
+ expect(findKey("plan", "parent-program").presence).toBe("required");
299
+ expect(findKey("phase-spec", "parent-program").presence).toBe("required");
300
+ // `depends-on` per type.
301
+ expect(findKey("plan", "depends-on").presence).toBe("optional");
302
+ expect(findKey("phase-spec", "depends-on").presence).toBe("required");
303
+ expect(findKey("single-spec", "depends-on").presence).toBe("required");
304
+ // The optional shape-typed keys: `parent-version` (Class-B), `base` (plan).
305
+ expect(findKey("plan", "parent-version").presence).toBe("optional");
306
+ expect(findKey("phase-spec", "parent-version").presence).toBe("optional");
307
+ for (const docType of ["overall-spec", "single-spec"] as const) {
308
+ expect(
309
+ declaredRegistries[docType].elements.some((element) => element.anchor === "parent-version"),
310
+ `${docType} has no parent-version key`,
311
+ ).toBe(false);
312
+ }
313
+ expect(findKey("plan", "base").presence).toBe("optional");
314
+ // `issues` is single-spec optional (the free-form's issue pointer).
315
+ expect(findKey("single-spec", "issues").presence).toBe("optional");
316
+ for (const docType of ["overall-spec", "plan", "phase-spec"] as const) {
317
+ expect(
318
+ declaredRegistries[docType].elements.some((element) => element.anchor === "issues"),
319
+ `${docType} has no issues key`,
320
+ ).toBe(false);
321
+ }
322
+ });
323
+
324
+ it("re-shapes every front-matter value pattern as a YAML scalar (zero bullet/heading forms)", () => {
325
+ for (const registry of ALL_REGISTRIES) {
326
+ for (const element of registry.elements.filter((element) => element.home === "frontmatter")) {
327
+ expect(element.valuePattern, `${registry.docType}:${element.anchor}`).toBeDefined();
328
+ expect(element.valuePattern, `${registry.docType}:${element.anchor}`).not.toContain(
329
+ "\\*\\*",
330
+ );
331
+ expect(element.valuePattern, `${registry.docType}:${element.anchor}`).not.toMatch(/^# /);
332
+ expect(element.valuePattern, `${registry.docType}:${element.anchor}`).not.toMatch(/^- /);
333
+ }
334
+ }
335
+ });
336
+
337
+ it("matches the declared scalar shapes against known-good front-matter values", () => {
338
+ const samples: Array<readonly [DocType, string, string]> = [
339
+ ["overall-spec", "version", "v2.46"],
340
+ ["plan", "version", "v0.9"],
341
+ ["phase-spec", "version", "v1.9"],
342
+ ["single-spec", "version", "v0.1"],
343
+ ["overall-spec", "date", "2026-10-17"],
344
+ ["plan", "date", "2026-10-17"],
345
+ ["phase-spec", "date", "2026-10-17"],
346
+ ["single-spec", "date", "2026-10-17"],
347
+ ["overall-spec", "doc-type", "overall-spec"],
348
+ ["plan", "doc-type", "plan"],
349
+ ["phase-spec", "doc-type", "phase-spec"],
350
+ ["single-spec", "doc-type", "single-spec"],
351
+ ["overall-spec", "status", "Approved"],
352
+ ["phase-spec", "status", "Plan pending"],
353
+ ["single-spec", "status", "Draft"],
354
+ ["plan", "title", "A plan title"],
355
+ ["plan", "spec", "docs/kairos/specs/p3-design.md"],
356
+ ["plan", "parent-program", "docs/kairos/specs/overall.md"],
357
+ ["plan", "parent-version", "v2.46"],
358
+ ["plan", "base", "main"],
359
+ ["phase-spec", "depends-on", "P9"],
360
+ ["single-spec", "issues", "#302"],
361
+ ["overall-spec", "author", "[human] · Claude Opus 5(…)"],
362
+ ];
363
+ for (const [docType, anchor, value] of samples) {
364
+ const pattern = new RegExp(findKey(docType, anchor).valuePattern!);
365
+ expect(pattern.test(value), `${docType}:${anchor} value ${JSON.stringify(value)}`).toBe(true);
366
+ }
367
+ // The scalar shapes are fully anchored — the retired bullet/date-combined form
368
+ // and the empty scalar both fail.
369
+ expect(
370
+ new RegExp(findKey("overall-spec", "version").valuePattern!).test("v2.46 · 2026-10-17"),
371
+ ).toBe(false);
372
+ expect(new RegExp(findKey("plan", "title").valuePattern!).test("")).toBe(false);
373
+ });
374
+
375
+ it("reconciles the post-migration element totals against the §2.3 arithmetic (42/31/27/16)", () => {
376
+ expect(declaredRegistries["overall-spec"].elements.length).toBe(42);
377
+ expect(declaredRegistries.plan.elements.length).toBe(31);
378
+ expect(declaredRegistries["phase-spec"].elements.length).toBe(27);
379
+ expect(declaredRegistries["single-spec"].elements.length).toBe(16);
380
+ });
381
+ });
382
+
383
+ describe("RegistryGuard type guards", () => {
384
+ it("accepts a well-formed registry element and rejects malformed shapes", () => {
385
+ const element = {
386
+ anchor: "## Goal",
387
+ presence: "required",
388
+ valuePattern: "^## Goal$",
389
+ refKind: "none",
390
+ home: "facet",
391
+ } satisfies RegistryElement;
392
+ expect(RegistryGuard.isElement(element)).toBe(true);
393
+
394
+ // Missing the required home surface.
395
+ expect(
396
+ RegistryGuard.isElement({
397
+ anchor: "## Goal",
398
+ presence: "required",
399
+ valuePattern: "^## Goal$",
400
+ refKind: "none",
401
+ }),
402
+ ).toBe(false);
403
+ // Presence outside the legal domain.
404
+ expect(
405
+ RegistryGuard.isElement({ anchor: "## Goal", presence: "sometimes", home: "facet" }),
406
+ ).toBe(false);
407
+ // Empty anchor token.
408
+ expect(RegistryGuard.isElement({ anchor: "", presence: "required", home: "facet" })).toBe(
409
+ false,
410
+ );
411
+ // Ref kind outside the legal enum.
412
+ expect(
413
+ RegistryGuard.isElement({
414
+ anchor: "## Goal",
415
+ presence: "required",
416
+ refKind: "elsewhere",
417
+ home: "facet",
418
+ }),
419
+ ).toBe(false);
420
+ // Non-object inputs.
421
+ expect(RegistryGuard.isElement(null)).toBe(false);
422
+ expect(RegistryGuard.isElement("## Goal")).toBe(false);
423
+ });
424
+
425
+ it("recognizes the four declared registries and rejects registry-shaped non-registries", () => {
426
+ expect(RegistryGuard.isRegistry(declaredRegistries["overall-spec"])).toBe(true);
427
+ expect(RegistryGuard.isRegistry(declaredRegistries.plan)).toBe(true);
428
+ expect(RegistryGuard.isRegistry(declaredRegistries["phase-spec"])).toBe(true);
429
+ expect(RegistryGuard.isRegistry(declaredRegistries["single-spec"])).toBe(true);
430
+ // Missing the elements surface.
431
+ expect(RegistryGuard.isRegistry({ docType: "overall-spec" })).toBe(false);
432
+ // Unknown doc type.
433
+ expect(RegistryGuard.isRegistry({ docType: "unknown", elements: [] })).toBe(false);
434
+ // A registry whose element fails the element guard is not a registry.
435
+ expect(
436
+ RegistryGuard.isRegistry({
437
+ docType: "overall-spec",
438
+ elements: [{ anchor: "## X", presence: "sometimes", home: "section" }],
439
+ }),
440
+ ).toBe(false);
441
+ });
442
+ });
443
+
444
+ describe("type-level contract", () => {
445
+ it("pins the legal value vocabularies as the narrow unions", () => {
446
+ expectTypeOf<Presence>().toEqualTypeOf<"required" | "optional" | "conditional">();
447
+ expectTypeOf<RefKind>().toEqualTypeOf<
448
+ | "none"
449
+ | "version-lineage"
450
+ | "markdown-link"
451
+ | "phase-id"
452
+ | "issue-ref"
453
+ | "spec-ref"
454
+ | "parent-program"
455
+ | "task-id"
456
+ >();
457
+ });
458
+
459
+ it("narrows a guarded unknown to the registry-element contract", () => {
460
+ const candidate: unknown = {
461
+ anchor: "## Goal",
462
+ presence: "required",
463
+ valuePattern: "^## Goal$",
464
+ refKind: "none",
465
+ home: "facet",
466
+ };
467
+ if (RegistryGuard.isElement(candidate)) {
468
+ expectTypeOf(candidate).toMatchTypeOf<RegistryElement>();
469
+ }
470
+ });
471
+
472
+ it("rejects incomplete shapes at the type level (home and elements are required)", () => {
473
+ expectTypeOf({
474
+ anchor: "## Goal",
475
+ presence: "required",
476
+ valuePattern: "^## Goal$",
477
+ refKind: "none",
478
+ }).not.toMatchTypeOf<RegistryElement>();
479
+ expectTypeOf({ docType: "overall-spec" }).not.toMatchTypeOf<ElementRegistry>();
480
+ });
481
+ });