@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
@@ -4,15 +4,16 @@
4
4
  // with no matching `- **DependsOn**:` declaration WARNs once per block, while
5
5
  // forward / self / unregistered / spec-item / code-span / declared-edge refs
6
6
  // stay silent (the positive surface);
7
- // · the cross-doc observation — the Class-B `**Parent program**` link whose
8
- // version-stripped label drifts from the target basename WARNs, the canonical
9
- // `basename v1.21` form stays silent;
7
+ // · the retired cross-doc drift observation (T6) — the Class-B link-text drift
8
+ // WARN retires with the ChainLink label face: parent references carry zero
9
+ // WARNs whatever their shape (the chain facts ride the front-matter head);
10
10
  // · the WARN-only gate — the same defective document produces ZERO Contract
11
11
  // findings (the lint never feeds the judgment face) and every warning carries
12
12
  // the reference-lint shape, never a Finding.
13
13
  // Fixtures are known-good plan literals parsed through the shared PlanDocType
14
14
  // instance (the parse-once-reuse discipline — the lint consumes the same parse
15
- // record the dispatch and the graph read).
15
+ // record the dispatch and the graph read). Since T6 the fixtures carry the
16
+ // front-matter head (the §2.2 delivery seam's canonical document form).
16
17
 
17
18
  import { describe, expect, it } from "vitest";
18
19
  import type { ParsedDoc } from "../doc.ts";
@@ -55,15 +56,20 @@ const planTask = (
55
56
  ];
56
57
  };
57
58
 
58
- /** A full canonical plan document over the task blocks — the shared parse fixture. */
59
- const planDoc = (
60
- blocks: readonly string[],
61
- parent = "[x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
62
- ): string => {
59
+ /** A full canonical plan document over the task blocks — the shared parse fixture
60
+ * (the front-matter head carries the chain scalars; the lint's scan surfaces are
61
+ * the task blocks only). */
62
+ const planDoc = (blocks: readonly string[]): string => {
63
63
  return [
64
- "# Test Plan",
65
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
66
- `- **Parent program**: ${parent}`,
64
+ "---",
65
+ "title: Test Plan",
66
+ "doc-type: plan",
67
+ "version: v1.0",
68
+ "date: 2026-10-09",
69
+ "spec: docs/kairos/specs/x-design.md",
70
+ "parent-program: docs/kairos/specs/x-overall.md",
71
+ "parent-version: v1.21",
72
+ "---",
67
73
  "",
68
74
  "## Constraints",
69
75
  "",
@@ -188,9 +194,15 @@ describe("the silent surfaces (positive reference scanning)", () => {
188
194
 
189
195
  it("the scan surface is prospective prose — a reference inside Files / Consumes / Steps is never prose intent", () => {
190
196
  const content = [
191
- "# Test Plan",
192
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
193
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
197
+ "---",
198
+ "title: Test Plan",
199
+ "doc-type: plan",
200
+ "version: v1.0",
201
+ "date: 2026-10-09",
202
+ "spec: docs/kairos/specs/x-design.md",
203
+ "parent-program: docs/kairos/specs/x-overall.md",
204
+ "parent-version: v1.21",
205
+ "---",
194
206
  "",
195
207
  "### Task 3: task 3",
196
208
  "- **Objective**: task three",
@@ -222,32 +234,33 @@ describe("the silent surfaces (positive reference scanning)", () => {
222
234
  });
223
235
  });
224
236
 
225
- describe("the cross-doc reference observation (Class-B label drift)", () => {
226
- it("the canonical `basename v1.21` parent form stays silent", () => {
237
+ describe("the retired cross-doc drift observation (T6 — zero WARNs)", () => {
238
+ it("the canonical parent reference stays silent (zero WARNs)", () => {
227
239
  const warns = lintPlan(planDoc([...planTask(1, "task one", "none")]));
228
240
  expect(warns).toEqual([]);
229
241
  });
230
242
 
231
- it("a parent link whose version-stripped label drifts from the target basename WARNs", () => {
232
- const warns = lintPlan(
233
- planDoc(
234
- [...planTask(1, "task one", "none")],
235
- "[overall v1.21](docs/kairos/specs/x-overall.md)",
236
- ),
237
- );
238
- expect(warns).toHaveLength(1);
239
- expect(warns[0]!.field).toBe("**Parent program**");
240
- expect(warns[0]!.message).toContain("x-overall.md");
243
+ it("a parent reference whose shape would have drifted WARNs no more — the link-text face is retired", () => {
244
+ // The Class-B link-text drift judgment retired with the ChainLink label face:
245
+ // the parent reference is a front-matter HEAD SCALAR (the `parent-program:`
246
+ // key) — there is no link text to compare, so no drift WARN can fire.
247
+ const warns = lintPlan(planDoc([...planTask(1, "task one", "none")]));
248
+ expect(warns).toEqual([]);
241
249
  });
242
250
 
243
- it("the same drift observation applies to a phase-spec's parent link", () => {
251
+ it("the same retired surface applies to a phase-spec's parent reference — zero WARNs", () => {
244
252
  const lines = [
245
- "# Test Spec",
246
- "- **Version**: v1.0",
247
- "- **Status**: Draft",
248
- "- **Author**: x",
249
- "- **Parent program**: [misnamed v1.0](docs/kairos/specs/x-overall.md)",
250
- "- **Depends on**: P1",
253
+ "---",
254
+ "title: Test Spec",
255
+ "doc-type: phase-spec",
256
+ "version: v1.0",
257
+ "date: 2026-10-09",
258
+ "status: Draft",
259
+ "author: x",
260
+ "parent-program: docs/kairos/specs/x-overall.md",
261
+ "parent-version: v1.0",
262
+ "depends-on: P1",
263
+ "---",
251
264
  "",
252
265
  "## Design",
253
266
  "",
@@ -263,7 +276,7 @@ describe("the cross-doc reference observation (Class-B label drift)", () => {
263
276
  path: SPEC_PATH,
264
277
  parsed: parseDoc("phase-spec", lines),
265
278
  });
266
- expect(warns).toHaveLength(1);
279
+ expect(warns).toEqual([]);
267
280
  });
268
281
 
269
282
  it("the overall carries no reference-lint surface — the class is a silent no-op over an overall", () => {
@@ -297,10 +310,7 @@ describe("the WARN-only gate", () => {
297
310
 
298
311
  it("every warning carries the reference-lint shape, never a judge Finding kind", () => {
299
312
  const warns = lintPlan(
300
- planDoc(
301
- [...planTask(1, "task one", "none"), ...planTask(3, "extends Task 1", "none")],
302
- "[overall v1.21](docs/kairos/specs/x-overall.md)",
303
- ),
313
+ planDoc([...planTask(1, "task one", "none"), ...planTask(3, "extends Task 1", "none")]),
304
314
  );
305
315
  expect(warns.length).toBeGreaterThan(0);
306
316
  for (const warn of warns) {
@@ -10,7 +10,9 @@
10
10
  // snapshot-pinned from the new tree's first version;
11
11
  // · Projector.shape — the shape elements correspond 1:1 with the registered
12
12
  // elements (grouped into the section skeleton), also snapshot-pinned;
13
- // · Projector.slices — every declared element's slice parses its own anchor;
13
+ // · Projector.slices — every body element's slice parses its own anchor; the
14
+ // frontmatter-home rows carry no compiled pattern (a YAML key is looked up
15
+ // directly, never a line scan);
14
16
  // · Projector.tokens / Projector.reference — both surfaces correspond 1:1
15
17
  // with the registered elements.
16
18
  // Every projection is derived: the registered declaration and known-good anchor
@@ -169,10 +171,19 @@ describe("slices projection (Projector.slices)", () => {
169
171
  const element = registry.elements[i];
170
172
  const slice = doc.slices[i];
171
173
  expect(slice.anchor).toBe(element.anchor);
174
+ if (element.home === "frontmatter") {
175
+ // Frontmatter-home elements anchor on a YAML key — never compiled into
176
+ // a line scan; both the anchor and value RegExp compilations stop on
177
+ // the header leg (§3.3).
178
+ expect(slice.anchorPattern, `${registry.docType}:${element.anchor}`).toBeUndefined();
179
+ expect(slice.valuePattern, `${registry.docType}:${element.anchor}`).toBeUndefined();
180
+ continue;
181
+ }
172
182
  expect(slice.anchorPattern, `${registry.docType}:${element.anchor}`).toBeInstanceOf(RegExp);
173
183
  // The slice parses its anchor — the escaped anchor literal matches the anchor itself.
184
+ // (Non-null: the body-home contract above guarantees a compiled pattern.)
174
185
  expect(
175
- slice.anchorPattern.test(element.anchor),
186
+ slice.anchorPattern!.test(element.anchor),
176
187
  `${registry.docType}:${element.anchor} anchorPattern`,
177
188
  ).toBe(true);
178
189
  }
@@ -181,22 +192,32 @@ describe("slices projection (Projector.slices)", () => {
181
192
 
182
193
  it("derives the anchor pattern from the anchor literal (known-good escapes)", () => {
183
194
  const overall = slices["overall-spec"];
184
- // No metacharacters: the anchor is its own pattern.
185
- expect(overall.slices[0].anchorPattern.source).toBe("# Title");
186
- // `**Version**` — every `*` escaped.
187
- expect(overall.slices[1].anchorPattern.source).toBe("\\*\\*Version\\*\\*");
195
+ // The two leading rows are front-matter keys — the slice carries the key as
196
+ // a literal, no compiled line scan.
197
+ expect(overall.slices[0].anchor).toBe("title");
198
+ expect(overall.slices[0].anchorPattern).toBeUndefined();
199
+ expect(overall.slices.find((s) => s.anchor === "version")?.anchorPattern).toBeUndefined();
200
+ // `## Document scope` — no metacharacters: the anchor is its own pattern.
201
+ const scope = overall.slices.find((s) => s.anchor === "## Document scope")!;
202
+ expect(scope.anchorPattern?.source).toBe("## Document scope");
188
203
  // `#### [MFRBEN] group` — brackets escaped (the anchor is the English canonical;
189
204
  // the legacy zh leaf matches through the judge's canonicalize view, never here).
190
205
  const mfrben = overall.slices.find((slice) => slice.anchor === "#### [MFRBEN] group")!;
191
- expect(mfrben.anchorPattern.source).toBe("#### \\[MFRBEN\\] group");
206
+ expect(mfrben.anchorPattern?.source).toBe("#### \\[MFRBEN\\] group");
192
207
  });
193
208
 
194
- it("derives the value slice from the declared value pattern", () => {
209
+ it("derives the value slice from the declared value pattern (body surfaces only)", () => {
195
210
  for (const [index, registry] of REGISTRIES.entries()) {
196
211
  const doc = slices[DOC_KEYS[index]];
197
212
  for (let i = 0; i < registry.elements.length; i++) {
198
213
  const element = registry.elements[i];
199
214
  const slice = doc.slices[i];
215
+ if (element.home === "frontmatter") {
216
+ // The registry still declares the scalar shape (the domain judgment
217
+ // reads it from the registry, never a compiled line slice).
218
+ expect(slice.valuePattern, `${registry.docType}:${element.anchor}`).toBeUndefined();
219
+ continue;
220
+ }
200
221
  expect(slice.valuePattern, `${registry.docType}:${element.anchor}`).toBeInstanceOf(RegExp);
201
222
  if (element.valuePattern !== undefined) {
202
223
  expect(slice.valuePattern?.source).toBe(element.valuePattern);
@@ -296,6 +317,23 @@ describe("skeleton projection (Projector.skeleton)", () => {
296
317
  }
297
318
  });
298
319
 
320
+ it("projects the front-matter emission list — every head key but `parent-version`, required and optional alike", () => {
321
+ // §4.2: the head emission list is independent of the slot channel — it
322
+ // carries the required head keys plus the type's optional head keys, and
323
+ // excludes `parent-version` (its shape-typed domain admits no placeholder).
324
+ for (const [index, registry] of REGISTRIES.entries()) {
325
+ const doc = skeletons[DOC_KEYS[index]];
326
+ const expected = registry.elements
327
+ .filter((element) => element.home === "frontmatter" && element.anchor !== "parent-version")
328
+ .map((element) => element.anchor);
329
+ expect(doc.frontmatter.map((slot) => slot.anchor)).toEqual(expected);
330
+ expect(doc.frontmatter.some((slot) => slot.home !== "frontmatter")).toBe(false);
331
+ }
332
+ expect(skeletons.plan.frontmatter.map((slot) => slot.anchor)).toContain("base");
333
+ expect(skeletons.plan.frontmatter.map((slot) => slot.anchor)).toContain("depends-on");
334
+ expect(skeletons["single-spec"].frontmatter.map((slot) => slot.anchor)).toContain("issues");
335
+ });
336
+
299
337
  it("keeps the shape home-group order — the slot homes run the shape's group sequence", () => {
300
338
  for (const [index] of REGISTRIES.entries()) {
301
339
  const doc = skeletons[DOC_KEYS[index]];
@@ -313,15 +351,15 @@ describe("skeleton projection (Projector.skeleton)", () => {
313
351
  const linkSlots = doc.slots.filter((slot) => slot.slot === "link");
314
352
  for (const slot of linkSlots) {
315
353
  const element = registry.elements.find((e) => e.anchor === slot.anchor);
316
- // the link class is exactly the header parent-program / spec-ref anchors
317
- // (never the enum-typed table cells that also mention spec/ref)
318
- expect(element?.home).toBe("header");
354
+ // the link class is exactly the frontmatter-home parent-program / spec-ref
355
+ // keys (never the enum-typed table cells that also mention spec/ref)
356
+ expect(element?.home).toBe("frontmatter");
319
357
  expect(["parent-program", "spec-ref"]).toContain(slot.refKind);
320
358
  }
321
359
  }
322
- expect(skeletons.plan.slots.find((s) => s.anchor === "**Spec:**")?.slot).toBe("link");
323
- expect(skeletons.plan.slots.find((s) => s.anchor === "**Parent program**")?.slot).toBe("link");
324
- expect(skeletons["phase-spec"].slots.find((s) => s.anchor === "**Parent program**")?.slot).toBe(
360
+ expect(skeletons.plan.slots.find((s) => s.anchor === "spec")?.slot).toBe("link");
361
+ expect(skeletons.plan.slots.find((s) => s.anchor === "parent-program")?.slot).toBe("link");
362
+ expect(skeletons["phase-spec"].slots.find((s) => s.anchor === "parent-program")?.slot).toBe(
325
363
  "link",
326
364
  );
327
365
  });
@@ -344,10 +382,10 @@ describe("skeleton projection (Projector.skeleton)", () => {
344
382
  }
345
383
  });
346
384
 
347
- it("classifies the enum domain (**Status**) and the graph rows as generator-truth", () => {
385
+ it("classifies the enum domain (status) and the graph rows as generator-truth", () => {
348
386
  for (const [index] of REGISTRIES.entries()) {
349
387
  const doc = skeletons[DOC_KEYS[index]];
350
- const status = doc.slots.find((slot) => slot.anchor === "**Status**");
388
+ const status = doc.slots.find((slot) => slot.anchor === "status");
351
389
  if (status !== undefined) expect(status.slot).toBe("generator-truth");
352
390
  for (const anchor of ["Hard edge", "Graph legend"]) {
353
391
  const slot = doc.slots.find((s) => s.anchor === anchor);
@@ -363,7 +401,8 @@ describe("skeleton projection (Projector.skeleton)", () => {
363
401
  for (const [index] of REGISTRIES.entries()) {
364
402
  const doc = skeletons[DOC_KEYS[index]];
365
403
  for (const anchor of [
366
- "**Version**",
404
+ "version",
405
+ "date",
367
406
  "Version token",
368
407
  "Change history date",
369
408
  "Phase id token",
@@ -377,9 +416,11 @@ describe("skeleton projection (Projector.skeleton)", () => {
377
416
  it("keeps the content slots free of fully-anchored enum and graph elements", () => {
378
417
  // the enum-domain + graph rows the generator-truth class owns — none of them
379
418
  // may ride the content class (a content slot is a free-text `:::fill` landing
380
- // position, never a judged enum/graph value)
419
+ // position, never a judged enum/graph value). The anchors are the front-matter
420
+ // keys (`status` · `doc-type`) plus the enum-typed table cells and the graph rows.
381
421
  const truthAnchors = [
382
- "**Status**",
422
+ "status",
423
+ "doc-type",
383
424
  "Issue ref cell",
384
425
  "Implementation plan cell",
385
426
  "Design spec cell",
@@ -0,0 +1,186 @@
1
+ // packages/cdd-engine/src-next/contract/__tests__/structure-pin.test.ts
2
+ // T9 — the spec §6 structure pin, one case carrying the three complementary
3
+ // assertions (each catches a defect the other two would let through):
4
+ // (a) retired literals — the seven line-anchored / hand-copied grammars the
5
+ // front-matter + home-extractor migration deleted (task-block head,
6
+ // task-field marker, task-step bullet, the markerValue payload slice, the
7
+ // phase-id hand copy, the design group/item headings) are each zero-hit in
8
+ // the parse face source;
9
+ // (b) retained primitives — every census hit in contract/doc.ts belongs to
10
+ // exactly one of the six preserved primitives, and the owning set equals
11
+ // that six-primitive set (set equality over primitive identities, never a
12
+ // line-number list — the valuePattern-application primitive has two
13
+ // landing sites, so a count pin would drift with any rewrite). The census
14
+ // vocabulary includes `.test(` and `.replace(` — the two keywords the
15
+ // retired phase-id hand copy and the markerValue slice rode, without which
16
+ // those two retirement classes would be invisible to the census;
17
+ // (d) the registry side — every `home: "frontmatter"` anchor is a §3.3 key
18
+ // (title / doc-type / version / date / status / author / spec /
19
+ // parent-program / parent-version / depends-on / base / issues) and carries
20
+ // no bullet/heading literal (a bullet-anchored header element would fail
21
+ // the key-set membership); `Depends on ref` is zero-hit in the registry.
22
+
23
+ import { readFileSync } from "node:fs";
24
+ import path from "node:path";
25
+ import { fileURLToPath } from "node:url";
26
+ import { expect, test } from "vitest";
27
+ import { declaredRegistries } from "../declare.ts";
28
+
29
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
30
+ /** The parse face source — the file the retired/retained census walks. */
31
+ const DOC_SRC = readFileSync(path.resolve(HERE, "../doc.ts"), "utf8");
32
+ /** The registry source — the `Depends on ref` retirement pin's surface. */
33
+ const DECLARE_SRC = readFileSync(path.resolve(HERE, "../declare.ts"), "utf8");
34
+
35
+ /** The census vocabulary — every structural-regex / string-primitive hit the pin
36
+ * sees. `.test(` and `.replace(` are REQUIRED members: the retired phase-id
37
+ * hand copy (`:576`) rode `.test(` and the retired markerValue payload slice
38
+ * (`:459`) rode `.replace(` — a vocabulary missing either is blind to that
39
+ * retirement class (spec §6 (c)). */
40
+ const CENSUS = /RegExp|\.match\(|\.matchAll\(|\.split\(|\.test\(|\.replace\(/;
41
+
42
+ /** The six retained primitives — the identities every census hit must resolve
43
+ * into (spec §6 (b); `#phaseId`'s valuePattern read is the second landing site
44
+ * of the valuePattern-application primitive, per the same row). */
45
+ const PRIMITIVES: readonly { id: string; owns: (line: string) => boolean }[] = [
46
+ {
47
+ id: "heading-rank",
48
+ owns: (line) => line.includes("/^(#+)\\s/"),
49
+ },
50
+ {
51
+ id: "table-split",
52
+ owns: (line) =>
53
+ line.includes('.split("|")') || (line.includes("/^\\|") && line.includes(".test(trimmed)")),
54
+ },
55
+ {
56
+ id: "markdown-link",
57
+ owns: (line) =>
58
+ line.includes("matchAll(linkPattern)") || line.includes("\\[([^\\]]*)\\]\\(([^)]+)\\)"),
59
+ },
60
+ {
61
+ id: "version-token",
62
+ owns: (line) => line.includes("matchAll(tokenPattern)") || line.includes("/v\\d+\\.\\d+/g"),
63
+ },
64
+ {
65
+ id: "graph-edge",
66
+ owns: (line) =>
67
+ line.includes("match(edgePattern)") || line.includes("P(\\d+(?:\\.\\d+)*)\\s*->"),
68
+ },
69
+ {
70
+ id: "valuePattern-application",
71
+ owns: (line) => line.includes(".valuePattern.test(") || line.includes("pattern?.test("),
72
+ },
73
+ ];
74
+
75
+ /** The §3.3 header-key set — the key form a frontmatter-home anchor must take.
76
+ * (a future keyed-header addition must extend this set with the registry,
77
+ * never split the two declarations.) */
78
+ const FRONTMATTER_KEYS = new Set([
79
+ "title",
80
+ "doc-type",
81
+ "version",
82
+ "date",
83
+ "status",
84
+ "author",
85
+ "spec",
86
+ "parent-program",
87
+ "parent-version",
88
+ "depends-on",
89
+ "base",
90
+ "issues",
91
+ ]);
92
+
93
+ test("spec §6 structure pin — retired grammars zero-hit · retained primitives set-equal · frontmatter-home anchors are keys", () => {
94
+ // (a) the retired grammars — each absent from the parse face source.
95
+ expect(CENSUS.test(".test("), "the census vocabulary must include `.test(`").toBe(true);
96
+ expect(CENSUS.test(".replace("), "the census vocabulary must include `.replace(`").toBe(true);
97
+
98
+ const retired = [
99
+ ["task-block head grammar", /^### Task \(\d+\):/m],
100
+ ["task-field marker grammar", /^-\s+\*\*([A-Za-z ]+)\*\*:\s*(.*)$/m],
101
+ ["task-step bullet grammar", /^-\s+(.*)$/m],
102
+ ["design group grammar", /^### (\d+)\.\s+(.*)$/m],
103
+ ["design item grammar", /^#### (\d+)\.(\d+)\s+(.*)$/m],
104
+ ] as const;
105
+ for (const [id, pattern] of retired) {
106
+ expect(pattern.test(DOC_SRC), `retired ${id} must be zero-hit in doc.ts`).toBe(false);
107
+ }
108
+ // the two hand-copied strings (spec §6 (a): the markerValue payload slice and
109
+ // the `#phaseId` phase-token copy) — the exact retired literal text.
110
+ expect(DOC_SRC, "retired markerValue payload slice must be zero-hit").not.toContain(
111
+ ".replace(/^:\\s*/",
112
+ );
113
+ expect(DOC_SRC, "retired phase-id hand copy must be zero-hit").not.toContain(
114
+ String.raw`/^P\d+(\.\d+)*$/`,
115
+ );
116
+
117
+ // (b) the retained primitives — every census hit resolves to exactly one of
118
+ // the six, and the owning set equals the six identities.
119
+ const hits = DOC_SRC.split("\n").filter((line) => CENSUS.test(line));
120
+ const owners = hits.map((line) => {
121
+ const matching = PRIMITIVES.filter((primitive) => primitive.owns(line));
122
+ if (matching.length !== 1) {
123
+ throw new Error(
124
+ `census hit must belong to exactly one retained primitive: "${line}" (matches ${matching.length})`,
125
+ );
126
+ }
127
+ return matching[0]!.id;
128
+ });
129
+ expect(
130
+ new Set(owners),
131
+ "the owning primitive set must equal the six retained primitives",
132
+ ).toEqual(new Set(PRIMITIVES.map((primitive) => primitive.id)));
133
+ // 6 primitives / 7 landing points / 7 census lines: the valuePattern-application
134
+ // primitive has TWO landing sites (sectionConforms and the rewritten #phaseId —
135
+ // the landing point moves from one site to two, spec §6 b), so the remaining
136
+ // five primitives hold one census line each. The table-split primitive's
137
+ // separator-row guard is no longer inline here — it is the TableExtractor's
138
+ // hand-rolled `isSeparatorRow` (the table home's fixed structure rule), so the
139
+ // table-split landing is the `split("|")` line alone.
140
+ const hitsPerPrimitive = new Map<string, number>();
141
+ for (const id of owners) hitsPerPrimitive.set(id, (hitsPerPrimitive.get(id) ?? 0) + 1);
142
+ expect(hits.length, "the migrated census line count (6 primitives / 7 landing points)").toBe(7);
143
+ // the double-landing primitive — valuePattern-application (sectionConforms +
144
+ // the rewritten #phaseId). The remaining five primitives hold one census line
145
+ // each.
146
+ expect(hitsPerPrimitive.get("valuePattern-application")).toBe(2);
147
+ for (const primitive of PRIMITIVES) {
148
+ if (primitive.id === "valuePattern-application") continue;
149
+ expect(hitsPerPrimitive.get(primitive.id), `${primitive.id} must own one census line`).toBe(1);
150
+ }
151
+
152
+ // (d) the registry side — the frontmatter-home anchor set is a key set.
153
+ const registries = [
154
+ declaredRegistries["overall-spec"],
155
+ declaredRegistries.plan,
156
+ declaredRegistries["phase-spec"],
157
+ declaredRegistries["single-spec"],
158
+ ];
159
+ const frontmatterAnchors: string[] = [];
160
+ for (const registry of registries) {
161
+ for (const element of registry.elements) {
162
+ if (element.home !== "frontmatter") continue;
163
+ frontmatterAnchors.push(element.anchor);
164
+ expect(
165
+ FRONTMATTER_KEYS.has(element.anchor),
166
+ `frontmatter-home anchor "${element.anchor}" must be a §3.3 key`,
167
+ ).toBe(true);
168
+ expect(
169
+ element.anchor,
170
+ `frontmatter-home anchor "${element.anchor}" must carry no bullet`,
171
+ ).not.toMatch(/\*\*/);
172
+ expect(
173
+ element.anchor,
174
+ `frontmatter-home anchor "${element.anchor}" must carry no heading prefix`,
175
+ ).not.toMatch(/^#\s/);
176
+ }
177
+ }
178
+ expect(
179
+ frontmatterAnchors.length,
180
+ "the frontmatter-home anchor set must be non-empty",
181
+ ).toBeGreaterThan(0);
182
+ // the `Depends on ref` retirement — the retired phase-id reference class (spec §3.3).
183
+ expect(DECLARE_SRC, "retired `Depends on ref` must be zero-hit in the registry").not.toContain(
184
+ "Depends on ref",
185
+ );
186
+ });