@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
@@ -2,32 +2,47 @@
2
2
  "docType": "single-spec",
3
3
  "structure": [
4
4
  {
5
- "home": "header",
5
+ "home": "frontmatter",
6
6
  "elements": [
7
7
  {
8
- "anchor": "# Title",
8
+ "anchor": "title",
9
9
  "presence": "required",
10
10
  "refKind": "none"
11
11
  },
12
12
  {
13
- "anchor": "**Version**",
13
+ "anchor": "doc-type",
14
+ "presence": "required",
15
+ "refKind": "none"
16
+ },
17
+ {
18
+ "anchor": "version",
14
19
  "presence": "required",
15
20
  "refKind": "version-lineage"
16
21
  },
17
22
  {
18
- "anchor": "**Status**",
23
+ "anchor": "date",
19
24
  "presence": "required",
20
25
  "refKind": "none"
21
26
  },
22
27
  {
23
- "anchor": "**Author**",
28
+ "anchor": "status",
24
29
  "presence": "required",
25
30
  "refKind": "none"
26
31
  },
27
32
  {
28
- "anchor": "**Depends on**",
33
+ "anchor": "author",
29
34
  "presence": "required",
30
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"
31
46
  }
32
47
  ]
33
48
  },
@@ -3,11 +3,14 @@
3
3
  //
4
4
  // The declare module is the doc contract's single declaration: one typed
5
5
  // registry per doc type (overall-spec / plan / phase-spec / single-spec). These
6
- // tests pin the acceptance gates of the declared data — every registry inside
7
- // the 20–40 element band (single-spec is the declared lightweight exception,
8
- // exempted by name), every element carrying all five fields (anchor · presence ·
9
- // value pattern · ref kind · home), the presence and ref-kind vocabularies
10
- // staying inside their legal domains, and anchors unique per registry — plus the
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
11
14
  // runtime type guards and the type-level contract surface.
12
15
  //
13
16
  // The legal value vocabularies are pinned here as the spec-side source of truth
@@ -20,7 +23,14 @@
20
23
  // so the compile surface is pinned even though vitest transforms types away.
21
24
 
22
25
  import { describe, expect, expectTypeOf, it } from "vitest";
23
- import type { ElementRegistry, Home, Presence, RefKind, RegistryElement } from "../declare.ts";
26
+ import type {
27
+ DocType,
28
+ ElementRegistry,
29
+ Home,
30
+ Presence,
31
+ RefKind,
32
+ RegistryElement,
33
+ } from "../declare.ts";
24
34
  import { declaredRegistries, RegistryGuard } from "../declare.ts";
25
35
 
26
36
  const PRESENCE_VALUES = [
@@ -39,7 +49,7 @@ const REF_KIND_VALUES = [
39
49
  "task-id",
40
50
  ] as const satisfies readonly RefKind[];
41
51
  const HOME_VALUES = [
42
- "header",
52
+ "frontmatter",
43
53
  "section",
44
54
  "facet",
45
55
  "table",
@@ -52,7 +62,26 @@ const HOME_VALUES = [
52
62
  ] as const satisfies readonly Home[];
53
63
 
54
64
  const MIN_ELEMENTS = 20;
55
- const MAX_ELEMENTS = 40;
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;
56
85
  /** The declared light-weight exception — single-spec is a deliberately sparse
57
86
  * scaffold (header five-tuple + four prose sections + the change-history trio)
58
87
  * whose registered element set sits below the full-doc band by design
@@ -74,15 +103,30 @@ describe("declared registries", () => {
74
103
  expect(declaredRegistries["single-spec"].docType).toBe("single-spec");
75
104
  });
76
105
 
77
- it("carries between 20 and 40 elements per full doc type (acceptance count gate)", () => {
106
+ it("carries at least 20 elements per full doc type (acceptance count gate)", () => {
78
107
  for (const registry of ALL_REGISTRIES) {
79
108
  if (LIGHTWEIGHT_DOC_TYPES.has(registry.docType)) continue;
80
109
  expect(registry.elements.length, `${registry.docType} element count`).toBeGreaterThanOrEqual(
81
110
  MIN_ELEMENTS,
82
111
  );
83
- expect(registry.elements.length, `${registry.docType} element count`).toBeLessThanOrEqual(
84
- MAX_ELEMENTS,
85
- );
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);
86
130
  }
87
131
  });
88
132
 
@@ -141,6 +185,201 @@ describe("declared registries", () => {
141
185
  });
142
186
  });
143
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
+
144
383
  describe("RegistryGuard type guards", () => {
145
384
  it("accepts a well-formed registry element and rejects malformed shapes", () => {
146
385
  const element = {