@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,481 +0,0 @@
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
- });