@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
@@ -8,20 +8,31 @@
8
8
  // · the grep assertions: zero switch-case judgment dispatch + zero exported
9
9
  // behavior-carrying bare functions in judge/invariants.
10
10
  // Fixtures are known-good document literals (independent sources of truth) and an
11
- // injected in-memory fs seam — hermetic, no real filesystem here.
11
+ // injected in-memory fs seam — hermetic, no real filesystem here. Since T6 the
12
+ // fixtures carry the front-matter head (the §2.2 delivery seam: validate() splits
13
+ // the raw content, feeds the typed head into parse + the judged context, and the
14
+ // front-matter-home elements judge the head record).
12
15
 
13
16
  import { readFileSync } from "node:fs";
14
17
  import { describe, expect, it } from "vitest";
18
+ import { Words } from "../../face/words.ts";
19
+ import type { ParsedDoc } from "../doc.ts";
20
+ import { OverallDocType } from "../doc.ts";
21
+ import { FrontMatterExtractor } from "../frontmatter.ts";
15
22
  import type { DocFs, Finding } from "../invariants.ts";
16
23
  import { Contract } from "../judge.ts";
24
+ import { Translator } from "../translate.ts";
17
25
 
18
26
  /** A conforming overall — every registered element present, lineage self-consistent. */
19
27
  const GOOD_OVERALL = [
20
- "# 测试 Overall",
21
- "- **Version**: v1.21 · 2026-10-07",
22
- "- **Status**: Approved",
23
- "- **Author**: [human]",
24
- "- **Constraints**: 全部约定自动生效",
28
+ "---",
29
+ "title: 测试 Overall",
30
+ "doc-type: overall-spec",
31
+ "version: v1.21",
32
+ "date: 2026-10-07",
33
+ "status: Approved",
34
+ 'author: "[human]"',
35
+ "---",
25
36
  "",
26
37
  "## Document scope",
27
38
  "scope prose",
@@ -60,6 +71,10 @@ const GOOD_OVERALL = [
60
71
  "## Boundary rules",
61
72
  "- boundary rule",
62
73
  "",
74
+ "## Constraints",
75
+ "",
76
+ "- 全部约定自动生效",
77
+ "",
63
78
  "## Maintenance",
64
79
  "- maintenance note",
65
80
  "",
@@ -96,12 +111,13 @@ const judge = (
96
111
  content: string,
97
112
  fs: DocFs = EMPTY_FS,
98
113
  phaseId?: string,
114
+ root = ".",
99
115
  ): Finding[] =>
100
116
  new Contract().validate({
101
117
  docKey,
102
118
  path: docKey === "overall-spec" ? OVERALL_PATH : docKey === "plan" ? PLAN_PATH : SPEC_PATH,
103
119
  content,
104
- root: ".",
120
+ root,
105
121
  fs,
106
122
  phaseId,
107
123
  });
@@ -197,10 +213,10 @@ describe("base nine invariants — one negative case each", () => {
197
213
  expect(withKind(findings, "uniqueness", "## Document scope")).toBe(true);
198
214
  });
199
215
 
200
- it("domain: a header value outside its declared shape is reported", () => {
201
- const content = GOOD_OVERALL.replace("- **Status**: Approved", "- **Status**: Deleted");
216
+ it("domain: a front-matter value outside its declared shape is reported", () => {
217
+ const content = GOOD_OVERALL.replace("status: Approved", "status: Deleted");
202
218
  const findings = judge("overall-spec", content, GOOD_OVERALL_FS);
203
- expect(withKind(findings, "domain", "**Status**")).toBe(true);
219
+ expect(withKind(findings, "domain", "status")).toBe(true);
204
220
  });
205
221
 
206
222
  it("crosslink: an issue row referencing an unregistered phase is reported", () => {
@@ -212,12 +228,17 @@ describe("base nine invariants — one negative case each", () => {
212
228
  it("order: the section sequence must follow the declared registry order", () => {
213
229
  // A phase-spec with Constraints BEFORE Design inverts the declared sequence.
214
230
  const content = [
215
- "# Test Spec",
216
- "- **Version**: v1.0",
217
- "- **Status**: Draft",
218
- "- **Author**: x",
219
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
220
- "- **Depends on**: P1",
231
+ "---",
232
+ "title: Test Spec",
233
+ "doc-type: phase-spec",
234
+ "version: v1.0",
235
+ "date: 2026-10-09",
236
+ "status: Draft",
237
+ "author: x",
238
+ "parent-program: docs/kairos/specs/x-overall.md",
239
+ "parent-version: v1.0",
240
+ "depends-on: P1",
241
+ "---",
221
242
  "",
222
243
  "## Constraints",
223
244
  "",
@@ -239,9 +260,15 @@ describe("base nine invariants — one negative case each", () => {
239
260
 
240
261
  it("continuity: plan task ids must be contiguous from 1", () => {
241
262
  const content = [
242
- "# Test Plan",
243
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
244
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
263
+ "---",
264
+ "title: Test Plan",
265
+ "doc-type: plan",
266
+ "version: v1.0",
267
+ "date: 2026-10-09",
268
+ "spec: docs/kairos/specs/x-design.md",
269
+ "parent-program: docs/kairos/specs/x-overall.md",
270
+ "parent-version: v1.21",
271
+ "---",
245
272
  "",
246
273
  ...planTask(1),
247
274
  ...planTask(3),
@@ -252,12 +279,17 @@ describe("base nine invariants — one negative case each", () => {
252
279
 
253
280
  it("residue: conditional content leaks while its section is absent", () => {
254
281
  const content = [
255
- "# Test Spec",
256
- "- **Version**: v1.0",
257
- "- **Status**: Draft",
258
- "- **Author**: x",
259
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
260
- "- **Depends on**: P1",
282
+ "---",
283
+ "title: Test Spec",
284
+ "doc-type: phase-spec",
285
+ "version: v1.0",
286
+ "date: 2026-10-09",
287
+ "status: Draft",
288
+ "author: x",
289
+ "parent-program: docs/kairos/specs/x-overall.md",
290
+ "parent-version: v1.0",
291
+ "depends-on: P1",
292
+ "---",
261
293
  "",
262
294
  "## Design",
263
295
  "",
@@ -299,7 +331,7 @@ describe("base nine invariants — one negative case each", () => {
299
331
  "| v1.20 | 2026-10-06 | older only |",
300
332
  );
301
333
  const findings = judge("overall-spec", content, GOOD_OVERALL_FS);
302
- expect(withKind(findings, "selfBounded", "**Version**")).toBe(true);
334
+ expect(withKind(findings, "selfBounded", "version")).toBe(true);
303
335
  });
304
336
  });
305
337
 
@@ -316,14 +348,19 @@ describe("T6 — prose task mentions carry zero crosslink findings (the WARN-onl
316
348
  };
317
349
 
318
350
  /** A structurally conforming plan — every registered plan element present
319
- * (header tuple + version lineage + task fields + Change history) carrying a
320
- * prose mention of an unregistered historical task id in its Objective. */
351
+ * (front-matter head + version lineage + task fields + Change history) carrying
352
+ * a prose mention of an unregistered historical task id in its Objective. */
321
353
  function conformingPlanWithProse(objective: string): string {
322
354
  return [
323
- "# Test Plan",
324
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
325
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
326
- "- **Version**: v1.1 · 2026-10-09",
355
+ "---",
356
+ "title: Test Plan",
357
+ "doc-type: plan",
358
+ "version: v1.1",
359
+ "date: 2026-10-09",
360
+ "spec: docs/kairos/specs/x-design.md",
361
+ "parent-program: docs/kairos/specs/x-overall.md",
362
+ "parent-version: v1.21",
363
+ "---",
327
364
  "",
328
365
  "## Constraints",
329
366
  "",
@@ -372,9 +409,19 @@ describe("T6 — prose task mentions carry zero crosslink findings (the WARN-onl
372
409
  describe("the canonical repo forms (no false positives on real conventions)", () => {
373
410
  it("presence: the token-in-heading task id is satisfied by the parsed task blocks (not a line scan)", () => {
374
411
  const content = [
375
- "# Test Plan",
376
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
377
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
412
+ "---",
413
+ "title: Test Plan",
414
+ "doc-type: plan",
415
+ "version: v1.0",
416
+ "date: 2026-10-09",
417
+ "spec: docs/kairos/specs/x-design.md",
418
+ "parent-program: docs/kairos/specs/x-overall.md",
419
+ "parent-version: v1.21",
420
+ "---",
421
+ "",
422
+ "## Constraints",
423
+ "",
424
+ "- delta",
378
425
  "",
379
426
  ...planTask(1),
380
427
  ].join("\n");
@@ -394,9 +441,19 @@ describe("the canonical repo forms (no false positives on real conventions)", ()
394
441
 
395
442
  it("presence: a task block missing a registry-declared task field is reported (derived field set)", () => {
396
443
  const content = [
397
- "# Test Plan",
398
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
399
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
444
+ "---",
445
+ "title: Test Plan",
446
+ "doc-type: plan",
447
+ "version: v1.0",
448
+ "date: 2026-10-09",
449
+ "spec: docs/kairos/specs/x-design.md",
450
+ "parent-program: docs/kairos/specs/x-overall.md",
451
+ "parent-version: v1.21",
452
+ "---",
453
+ "",
454
+ "## Constraints",
455
+ "",
456
+ "- delta",
400
457
  "",
401
458
  "### Task 1: task",
402
459
  "- **Objective**: objective",
@@ -413,12 +470,29 @@ describe("the canonical repo forms (no false positives on real conventions)", ()
413
470
 
414
471
  it("domain: a backticked citation of an anchor literal is not judged as a value", () => {
415
472
  const content = [
416
- "# Test Plan",
417
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
418
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
419
- "- **Consumes**: T1 骨架 · doc.ts(plan DocType.parse:`### Task N:` 块归口 doc.ts)",
473
+ "---",
474
+ "title: Test Plan",
475
+ "doc-type: plan",
476
+ "version: v1.0",
477
+ "date: 2026-10-09",
478
+ "spec: docs/kairos/specs/x-design.md",
479
+ "parent-program: docs/kairos/specs/x-overall.md",
480
+ "parent-version: v1.21",
481
+ "---",
420
482
  "",
421
- ...planTask(1),
483
+ "## Constraints",
484
+ "",
485
+ "- delta",
486
+ "",
487
+ "### Task 1: task",
488
+ "- **Objective**: 引用 `### Task N:` 块归口 doc.ts",
489
+ "- **Files**: file",
490
+ "- **Consumes**: consumes",
491
+ "- **Produces**: produces",
492
+ "- **Steps**:",
493
+ " - step one",
494
+ "- **Acceptance**: acceptance",
495
+ "- **DependsOn**: none",
422
496
  ].join("\n");
423
497
  const findings = judge("plan", content, EMPTY_FS);
424
498
  expect(withKind(findings, "domain", "### Task N:")).toBe(false);
@@ -437,9 +511,19 @@ describe("the canonical repo forms (no false positives on real conventions)", ()
437
511
  // find #8: the registry's bare-heading pattern rejected the titled form — the
438
512
  // wave's own plan (25/25 plans use `### Task N: <title>`) was reported missing
439
513
  const content = [
440
- "# Test Plan",
441
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
442
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
514
+ "---",
515
+ "title: Test Plan",
516
+ "doc-type: plan",
517
+ "version: v1.0",
518
+ "date: 2026-10-09",
519
+ "spec: docs/kairos/specs/x-design.md",
520
+ "parent-program: docs/kairos/specs/x-overall.md",
521
+ "parent-version: v1.21",
522
+ "---",
523
+ "",
524
+ "## Constraints",
525
+ "",
526
+ "- delta",
443
527
  "",
444
528
  "### Task 1: task title",
445
529
  "- **Objective**: objective",
@@ -469,20 +553,37 @@ describe("the canonical repo forms (no false positives on real conventions)", ()
469
553
 
470
554
  it("domain: a nested backtick citation (`outer quote … inner `anchor`) is not judged as a value", () => {
471
555
  // find #8: the old span-by-span strip consumed the outer quote's opener and left
472
- // the nested `…` citation naked — the p4.1 spec's command-quoted prose was judged
473
- // as `## Constraints` / `**Version**` values
556
+ // the nested `…` citation naked — quoted prose was judged as `## Constraints`
557
+ // values (the plan's front-matter `version:` is a head scalar: a body citation
558
+ // of `version:` is outside the judged surface entirely)
474
559
  const content = [
475
- "# Test Plan",
476
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
477
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
478
- "- **Depends on**: P1",
479
- "- **Consumes**: T1(`read the plan's `## Constraints` (at INPUT_PLAN)`)·「`the `**Version**` header`」零残留",
560
+ "---",
561
+ "title: Test Plan",
562
+ "doc-type: plan",
563
+ "version: v1.0",
564
+ "date: 2026-10-09",
565
+ "spec: docs/kairos/specs/x-design.md",
566
+ "parent-program: docs/kairos/specs/x-overall.md",
567
+ "parent-version: v1.21",
568
+ "---",
480
569
  "",
481
- ...planTask(1),
570
+ "## Constraints",
571
+ "",
572
+ "- delta",
573
+ "",
574
+ "### Task 1: task",
575
+ "- **Objective**: T1(`read the plan's `## Constraints` (at INPUT_PLAN)`)·「`the `**Version**` header`」零残留",
576
+ "- **Files**: file",
577
+ "- **Consumes**: consumes",
578
+ "- **Produces**: produces",
579
+ "- **Steps**:",
580
+ " - step one",
581
+ "- **Acceptance**: acceptance",
582
+ "- **DependsOn**: none",
482
583
  ].join("\n");
483
584
  const findings = judge("plan", content, EMPTY_FS);
484
585
  expect(withKind(findings, "domain", "## Constraints")).toBe(false);
485
- expect(withKind(findings, "domain", "**Version**")).toBe(false);
586
+ expect(withKind(findings, "domain", "version")).toBe(false);
486
587
  });
487
588
 
488
589
  it("two adjacent backtick spans read as ONE quoted region — the mid-span prose is not judged (the pinned first-last strip)", () => {
@@ -493,41 +594,12 @@ describe("the canonical repo forms (no false positives on real conventions)", ()
493
594
  // shapes are the simple `span` and the nested citation, neither of which hides a
494
595
  // real structural anchor between two adjacent spans; a span-by-span strip would
495
596
  // judge this middle prose and reopen the nested-citation gap the pin closes.
496
- const content = [
497
- "# Test Spec",
498
- "- **Version**: v1.1 · 2026-10-09",
499
- "- **Status**: Draft",
500
- "- **Author**: x",
501
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
502
- "- **Depends on**: P1",
503
- "",
504
- "## Design",
505
- "",
506
- "intro — the double-layer skeleton semantics.",
507
- "",
508
- "### 1. 数据面",
509
- "#### 1.1 登记表",
510
- "- text",
511
- "",
512
- "### Acceptance criteria",
513
- "",
514
- "- `c`",
515
- "",
516
- "## Constraints",
517
- "",
597
+ const content = phaseSpec("v1.1").replace(
518
598
  "- delta",
519
- "",
520
- "## Change history",
521
- "",
522
- "| Version | date | summary | author |",
523
- "|---|---|---|---|",
524
- "| v1.0 | 2026-10-08 | prior | [human] |",
525
- "| v1.1 | 2026-10-09 | merged | [human] |",
526
- ]
527
- .join("\n")
528
- .replace("- **Status**: Draft", "- `p1` then **Status**: Deleted then `p2`");
599
+ "- `p1` then ## Constraints: Deleted then `p2`",
600
+ );
529
601
  const findings = judge("phase-spec", content, EMPTY_FS);
530
- expect(withKind(findings, "domain", "**Status**")).toBe(false);
602
+ expect(withKind(findings, "domain", "## Constraints")).toBe(false);
531
603
  });
532
604
 
533
605
  it("order: the change-history rows must be version-ascending (canonical oldest-first)", () => {
@@ -544,34 +616,10 @@ describe("the canonical repo forms (no false positives on real conventions)", ()
544
616
  });
545
617
 
546
618
  it("residue: a legitimate design-body table does not count as Deviations residue", () => {
547
- const content = [
548
- "# Test Spec",
549
- "- **Version**: v1.0",
550
- "- **Status**: Draft",
551
- "- **Author**: x",
552
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
553
- "- **Depends on**: P1",
554
- "",
555
- "## Design",
556
- "",
557
- "### 1. 数据面",
558
- "#### 1.1 技能集合",
559
- "| skill | 角色 | 说明 |",
560
- "| --- | --- | --- |",
561
- "| cdd-design | 编排 | brainstorm 路由 |",
562
- "| cdd-analysis | spec-writer | 参数化模板 |",
563
- "",
564
- "### Acceptance criteria",
565
- "",
566
- "- `c`",
567
- "",
568
- "## Constraints",
569
- "",
570
- "- delta",
571
- "",
572
- "## Review record",
573
- "- review note",
574
- ].join("\n");
619
+ const content = phaseSpec("v1.1").replace(
620
+ "### 1. 数据面\n#### 1.1 登记表\n- text",
621
+ "### 1. 数据面\n#### 1.1 技能集合\n| skill | 角色 | 说明 |\n| --- | --- | --- |\n| cdd-design | 编排 | brainstorm 路由 |\n| cdd-analysis | spec-writer | 参数化模板 |",
622
+ );
575
623
  const findings = judge("phase-spec", content, EMPTY_FS);
576
624
  expect(withKind(findings, "residue")).toBe(false);
577
625
  });
@@ -596,16 +644,53 @@ describe("the four context-seam invariants — one negative case each", () => {
596
644
  expect(withKind(findings, "sibling-scan")).toBe(true);
597
645
  });
598
646
 
599
- it("cross-doc-chain: a **Spec:** label that drifts from the resolved basename is reported", () => {
647
+ it("P9 T5 — #scanRoots composes the doc dir + doc roots on ONE basis (ctx.root)", () => {
648
+ // The scan roots resolve through the SAME `ctx.root` basis the rest of the
649
+ // judgment reads (never a bare relative string against process.cwd()): with a
650
+ // non-trivial root, the doc's own dir and BOTH declared doc roots join it.
651
+ const seen: string[] = [];
652
+ const fs: DocFs = {
653
+ exists: () => true,
654
+ read: () => null,
655
+ list: (dir) => {
656
+ seen.push(dir);
657
+ return dir.endsWith("/specs") || dir.endsWith("specs")
658
+ ? ["x-overall.md", "x-p1-design.md", "x-p2-design.md"]
659
+ : ["x-p1.md", "x-p2.md"];
660
+ },
661
+ };
662
+ judge("overall-spec", GOOD_OVERALL, fs, undefined, "/abs/repo");
663
+ // Every scan root carries the root basis (`/abs/repo`) — the doc dir + both
664
+ // doc roots, never a bare relative against process.cwd().
665
+ expect(seen.every((dir) => dir.startsWith("/abs/repo/"))).toBe(true);
666
+ expect(seen.some((dir) => dir.endsWith("/docs/kairos/specs"))).toBe(true);
667
+ expect(seen.some((dir) => dir.endsWith("/docs/kairos/plans"))).toBe(true);
668
+ });
669
+
670
+ it("T6 — the spec link-text drift judgment retired: a spec reference carries zero cross-doc-chain findings", () => {
671
+ // The plan's spec reference is a HEAD scalar (the `spec:` key) — the link text
672
+ // face is gone, so no Class-A drift judgment can fire. The cross-doc-chain
673
+ // surface judges the chain FACTS (presence + lineage), never a textual match.
600
674
  const content = [
601
- "# Test Plan",
602
- "**Spec:** [wrong-label](docs/kairos/specs/x-design.md)",
603
- "- **Parent program**: [x-overall.md v1.21](docs/kairos/specs/x-overall.md)",
675
+ "---",
676
+ "title: Test Plan",
677
+ "doc-type: plan",
678
+ "version: v1.0",
679
+ "date: 2026-10-09",
680
+ "spec: docs/kairos/specs/x-design.md",
681
+ "parent-program: docs/kairos/specs/x-overall.md",
682
+ "parent-version: v1.21",
683
+ "---",
684
+ "",
685
+ "## Constraints",
686
+ "",
687
+ "- delta",
604
688
  "",
605
689
  ...planTask(1),
606
690
  ].join("\n");
607
691
  const findings = judge("plan", content, EMPTY_FS);
608
- expect(withKind(findings, "cross-doc-chain", "**Spec:**")).toBe(true);
692
+ expect(withKind(findings, "cross-doc-chain", "spec")).toBe(false);
693
+ expect(findings.filter((finding) => finding.kind === "cross-doc-chain")).toEqual([]);
609
694
  });
610
695
 
611
696
  it("cross-doc-chain: an unregistered dispatch phase is reported (face ④)", () => {
@@ -625,12 +710,12 @@ describe("the four context-seam invariants — one negative case each", () => {
625
710
 
626
711
  describe("the coordinator", () => {
627
712
  it("aggregates findings from multiple strategies on one document", () => {
628
- const content = GOOD_OVERALL.replace("- **Status**: Approved", "- **Status**: Deleted").replace(
713
+ const content = GOOD_OVERALL.replace("status: Approved", "status: Deleted").replace(
629
714
  "| P2 | none | issue two |",
630
715
  "| P9 | prose | issue nine |",
631
716
  );
632
717
  const findings = judge("overall-spec", content, GOOD_OVERALL_FS, "P9");
633
- expect(withKind(findings, "domain", "**Status**")).toBe(true);
718
+ expect(withKind(findings, "domain", "status")).toBe(true);
634
719
  expect(withKind(findings, "crosslink", "Issue inventory")).toBe(true);
635
720
  expect(withKind(findings, "section-scoped-domain", "Issue inventory")).toBe(true);
636
721
  expect(withKind(findings, "presence", "Issue inventory")).toBe(false); // sections are present
@@ -639,20 +724,25 @@ describe("the coordinator", () => {
639
724
  });
640
725
 
641
726
  // ---------------------------------------------------------------------------
642
- // P4.1 T2 — the three-type homogeneity: `**Version**` required + strict (number · date) ·
727
+ // P4.1 T2 — the three-type homogeneity: `version:` required + strict (number · date) ·
643
728
  // `## Change history` required ×3 · selfBounded ×3 (header = the newest in-row)
644
729
  // ---------------------------------------------------------------------------
645
730
 
646
- /** A minimal phase-spec carrying the canonical version lineage (strict Version
647
- * header + a Change-history table) — the T2 judgment surface. */
731
+ /** A minimal phase-spec carrying the canonical version lineage (a strict `version:`
732
+ * front-matter scalar + a Change-history table) — the T2 judgment surface. */
648
733
  const specLineage = (headerVersion: string, rows: readonly string[]): string => {
649
734
  return [
650
- "# Test Spec",
651
- `- **Version**: ${headerVersion}`,
652
- "- **Status**: Draft",
653
- "- **Author**: x",
654
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
655
- "- **Depends on**: P1",
735
+ "---",
736
+ "title: Test Spec",
737
+ "doc-type: phase-spec",
738
+ `version: ${headerVersion}`,
739
+ "date: 2026-10-09",
740
+ "status: Draft",
741
+ "author: x",
742
+ "parent-program: docs/kairos/specs/x-overall.md",
743
+ "parent-version: v1.0",
744
+ "depends-on: P1",
745
+ "---",
656
746
  "",
657
747
  "## Design",
658
748
  "",
@@ -681,10 +771,15 @@ const specLineage = (headerVersion: string, rows: readonly string[]): string =>
681
771
  /** A minimal plan carrying the canonical version lineage. */
682
772
  const planLineage = (headerVersion: string, rows: readonly string[]): string => {
683
773
  return [
684
- "# Test Plan",
685
- "**Spec:** [x-design.md](docs/kairos/specs/x-design.md)",
686
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
687
- `- **Version**: ${headerVersion}`,
774
+ "---",
775
+ "title: Test Plan",
776
+ "doc-type: plan",
777
+ `version: ${headerVersion}`,
778
+ "date: 2026-10-09",
779
+ "spec: docs/kairos/specs/x-design.md",
780
+ "parent-program: docs/kairos/specs/x-overall.md",
781
+ "parent-version: v1.0",
782
+ "---",
688
783
  "",
689
784
  "## Constraints",
690
785
  "",
@@ -703,39 +798,33 @@ const planLineage = (headerVersion: string, rows: readonly string[]): string =>
703
798
  const ROW_100 = "| v1.0 | 2026-10-08 | prior | [human] |";
704
799
  const ROW_101 = "| v1.1 | 2026-10-09 | merged | [human] |";
705
800
 
706
- describe("P4.1 T2 — **Version** presence required ×3 (plan optional → required)", () => {
707
- it("a plan without a **Version** header is reported", () => {
708
- const content = planLineage("v1.0 · 2026-10-09", [ROW_100]).replace(
709
- "- **Version**: v1.0 · 2026-10-09",
710
- "",
711
- );
801
+ describe("P4.1 T2 — `version:` presence required ×3 (plan optional → required)", () => {
802
+ it("a plan without the version front-matter key is reported", () => {
803
+ const content = planLineage("v1.0", [ROW_100]).replace("\nversion: v1.0", "");
712
804
  const findings = judge("plan", content);
713
- expect(withKind(findings, "presence", "**Version**")).toBe(true);
805
+ expect(withKind(findings, "presence", "version")).toBe(true);
714
806
  });
715
807
 
716
- it("a phase-spec without a **Version** header is reported", () => {
717
- const content = specLineage("v1.0 · 2026-10-09", [ROW_100]).replace(
718
- "- **Version**: v1.0 · 2026-10-09",
719
- "",
720
- );
808
+ it("a phase-spec without the version front-matter key is reported", () => {
809
+ const content = specLineage("v1.0", [ROW_100]).replace("\nversion: v1.0", "");
721
810
  const findings = judge("phase-spec", content);
722
- expect(withKind(findings, "presence", "**Version**")).toBe(true);
811
+ expect(withKind(findings, "presence", "version")).toBe(true);
723
812
  });
724
813
 
725
- it("an overall without a **Version** header is reported (the requiredness holds)", () => {
726
- const content = GOOD_OVERALL.replace("- **Version**: v1.21 · 2026-10-07", "");
814
+ it("an overall without the version front-matter key is reported (the requiredness holds)", () => {
815
+ const content = GOOD_OVERALL.replace("version: v1.21", "");
727
816
  const findings = judge("overall-spec", content, GOOD_OVERALL_FS);
728
- expect(withKind(findings, "presence", "**Version**")).toBe(true);
817
+ expect(withKind(findings, "presence", "version")).toBe(true);
729
818
  });
730
819
  });
731
820
 
732
- describe("P4.1 T2 — the **Version** strict form (number + date · zero supplement/link/bold)", () => {
821
+ describe("P4.1 T2 — the `version:` strict form (a bare `vX.Y` scalar · zero supplement/link/bold)", () => {
733
822
  it("a trailing parenthetical supplement is refused (plan and spec)", () => {
734
823
  for (const [docKey, doc] of [
735
824
  ["plan", planLineage("v1.0 (v1.0 补充)", [ROW_100])],
736
825
  ["phase-spec", specLineage("v1.0 (v1.0 补充)", [ROW_100])],
737
826
  ] as const) {
738
- expect(withKind(judge(docKey, doc), "domain", "**Version**")).toBe(true);
827
+ expect(withKind(judge(docKey, doc), "domain", "version")).toBe(true);
739
828
  }
740
829
  });
741
830
 
@@ -744,33 +833,31 @@ describe("P4.1 T2 — the **Version** strict form (number + date · zero supplem
744
833
  ["plan", planLineage("v1.0 · 2026-10-09 说明应在 Change history", [ROW_100])],
745
834
  ["phase-spec", specLineage("v1.0 · 2026-10-09 说明应在 Change history", [ROW_100])],
746
835
  ] as const) {
747
- expect(withKind(judge(docKey, doc), "domain", "**Version**")).toBe(true);
836
+ expect(withKind(judge(docKey, doc), "domain", "version")).toBe(true);
748
837
  }
749
838
  });
750
839
 
751
840
  it("a bold **vX.Y** form is refused (plan and spec)", () => {
752
841
  for (const [docKey, doc] of [
753
- ["plan", planLineage("**v1.0** · 2026-10-09", [ROW_100])],
754
- ["phase-spec", specLineage("**v1.0** · 2026-10-09", [ROW_100])],
842
+ ["plan", planLineage('"**v1.0** · 2026-10-09"', [ROW_100])],
843
+ ["phase-spec", specLineage('"**v1.0** · 2026-10-09"', [ROW_100])],
755
844
  ] as const) {
756
- expect(withKind(judge(docKey, doc), "domain", "**Version**")).toBe(true);
845
+ expect(withKind(judge(docKey, doc), "domain", "version")).toBe(true);
757
846
  }
758
847
  });
759
848
 
760
- it("the canonical `vX.Y · date` form carries no **Version** domain finding (plan and spec)", () => {
849
+ it("the canonical bare `vX.Y` form carries no `version:` domain finding (plan and spec)", () => {
761
850
  for (const docKey of ["plan", "phase-spec"] as const) {
762
851
  const doc =
763
- docKey === "plan"
764
- ? planLineage("v1.0 · 2026-10-09", [ROW_100])
765
- : specLineage("v1.0 · 2026-10-09", [ROW_100]);
766
- expect(withKind(judge(docKey, doc), "domain", "**Version**")).toBe(false);
852
+ docKey === "plan" ? planLineage("v1.0", [ROW_100]) : specLineage("v1.0", [ROW_100]);
853
+ expect(withKind(judge(docKey, doc), "domain", "version")).toBe(false);
767
854
  }
768
855
  });
769
856
  });
770
857
 
771
858
  describe("P4.1 T2 — `## Change history` presence required ×3", () => {
772
859
  it("a plan without the Change-history section is reported", () => {
773
- const content = planLineage("v1.0 · 2026-10-09", [ROW_100]).replace(
860
+ const content = planLineage("v1.0", [ROW_100]).replace(
774
861
  [
775
862
  "## Change history",
776
863
  "",
@@ -785,7 +872,7 @@ describe("P4.1 T2 — `## Change history` presence required ×3", () => {
785
872
  });
786
873
 
787
874
  it("a phase-spec without the Change-history section is reported", () => {
788
- const content = specLineage("v1.0 · 2026-10-09", [ROW_100]).replace(
875
+ const content = specLineage("v1.0", [ROW_100]).replace(
789
876
  [
790
877
  "## Change history",
791
878
  "",
@@ -813,26 +900,41 @@ describe("P4.1 T2 — `## Change history` presence required ×3", () => {
813
900
  const findings = judge("overall-spec", content, GOOD_OVERALL_FS);
814
901
  expect(withKind(findings, "presence", "## Change history")).toBe(true);
815
902
  });
903
+
904
+ it("a phase-spec whose parent-program is a markdown link reports the shape rule ONCE — never the resolution cascade (D2 · #342)", () => {
905
+ const content = specLineage("v1.0", [ROW_100]).replace(
906
+ "parent-program: docs/kairos/specs/x-overall.md",
907
+ 'parent-program: "[2026-10-02-x-overall.md](docs/kairos/specs/2026-10-02-x-overall.md)"',
908
+ );
909
+ const findings = judge("phase-spec", content);
910
+ // exactly the single link-shape finding — the malformed target is judged
911
+ // BEFORE resolution, so the file-existence dead-tail and the sibling-scan
912
+ // basename cascade never fire on top of it
913
+ expect(findings).toHaveLength(1);
914
+ expect(findings[0].kind).toBe("link-shape");
915
+ expect(findings[0].field).toBe("parent-program");
916
+ expect(findings[0].message).toContain("not a bare relative path");
917
+ });
816
918
  });
817
919
 
818
920
  describe("P4.1 T2 — selfBounded applies to spec/plan (header = the newest in-row)", () => {
819
921
  it("a phase-spec whose header is NOT the change-history's newest row is reported", () => {
820
- const findings = judge("phase-spec", specLineage("v1.0 · 2026-10-09", [ROW_100, ROW_101]));
821
- expect(withKind(findings, "selfBounded", "**Version**")).toBe(true);
922
+ const findings = judge("phase-spec", specLineage("v1.0", [ROW_100, ROW_101]));
923
+ expect(withKind(findings, "selfBounded", "version")).toBe(true);
822
924
  });
823
925
 
824
926
  it("a plan whose header is OUTSIDE the lineage is reported", () => {
825
- const findings = judge("plan", planLineage("v1.2 · 2026-10-09", [ROW_100, ROW_101]));
826
- expect(withKind(findings, "selfBounded", "**Version**")).toBe(true);
927
+ const findings = judge("plan", planLineage("v1.2", [ROW_100, ROW_101]));
928
+ expect(withKind(findings, "selfBounded", "version")).toBe(true);
827
929
  });
828
930
 
829
931
  it("a spec/plan whose header IS the newest in-row version carries no selfBounded finding", () => {
830
932
  for (const docKey of ["plan", "phase-spec"] as const) {
831
933
  const doc =
832
934
  docKey === "plan"
833
- ? planLineage("v1.1 · 2026-10-09", [ROW_100, ROW_101])
834
- : specLineage("v1.1 · 2026-10-09", [ROW_100, ROW_101]);
835
- expect(withKind(judge(docKey, doc), "selfBounded", "**Version**")).toBe(false);
935
+ ? planLineage("v1.1", [ROW_100, ROW_101])
936
+ : specLineage("v1.1", [ROW_100, ROW_101]);
937
+ expect(withKind(judge(docKey, doc), "selfBounded", "version")).toBe(false);
836
938
  }
837
939
  });
838
940
  });
@@ -857,6 +959,142 @@ describe("governance greps (the engine-zero criterion)", () => {
857
959
  });
858
960
  });
859
961
 
962
+ describe("P10 W7 T11 — the migration judgment-regression pins (spec §6 · §5.2)", () => {
963
+ /** A minimal plan carrying a caller-chosen `parent-version:` scalar (the
964
+ * Class-B chain carrier under test). */
965
+ const planWithParentVersion = (parentVersion: string): string =>
966
+ [
967
+ "---",
968
+ "title: Test Plan",
969
+ "doc-type: plan",
970
+ "version: v1.0",
971
+ "date: 2026-10-09",
972
+ "spec: docs/kairos/specs/x-design.md",
973
+ "parent-program: docs/kairos/specs/x-overall.md",
974
+ `parent-version: ${parentVersion}`,
975
+ "---",
976
+ "",
977
+ "## Constraints",
978
+ "",
979
+ "- delta",
980
+ "",
981
+ ...planTask(1),
982
+ ].join("\n");
983
+
984
+ it("version lineage — a head version OUTSIDE the Change-history lineage still fires selfBounded", () => {
985
+ // The T6 read flip made the version a head scalar — a version the Change-history
986
+ // table never carries must STILL be reported (no false-green from a body scan
987
+ // that can no longer see the head).
988
+ const overall = judge(
989
+ "overall-spec",
990
+ GOOD_OVERALL.replace("version: v1.21", "version: v9.9"),
991
+ GOOD_OVERALL_FS,
992
+ );
993
+ expect(withKind(overall, "selfBounded", "version")).toBe(true);
994
+ const plan = judge("plan", planLineage("v9.9", [ROW_100, ROW_101]));
995
+ expect(withKind(plan, "selfBounded", "version")).toBe(true);
996
+ });
997
+
998
+ it("parent lineage — a parent-version outside the parent overall's lineage fires classB through the chainDocs seam", () => {
999
+ const { head, body } = FrontMatterExtractor.split(GOOD_OVERALL);
1000
+ const parentParsed = new OverallDocType("overall-spec").parse(body.split("\n"), head);
1001
+ const plan = planWithParentVersion("v7.7");
1002
+ // The production seam is not wired in this phase — without chainDocs the
1003
+ // Class-B chain resolves nowhere and stays silent (the preflight call point
1004
+ // does not pass the map).
1005
+ expect(withKind(judge("plan", plan), "cross-doc-chain", "parent-program")).toBe(false);
1006
+ const findings = new Contract().validate({
1007
+ docKey: "plan",
1008
+ path: PLAN_PATH,
1009
+ content: plan,
1010
+ root: ".",
1011
+ chainDocs: new Map<string, ParsedDoc>([["docs/kairos/specs/x-overall.md", parentParsed]]),
1012
+ });
1013
+ // The parentTokens carrier is non-empty (`v7.7` rides the parent-version key)
1014
+ // and the parent lineage is {v1.20, v1.21} — the classB early return is not
1015
+ // the reason this fires; the token is genuinely outside the lineage.
1016
+ expect(withKind(findings, "cross-doc-chain", "parent-program")).toBe(true);
1017
+ });
1018
+
1019
+ it("presence — a doc missing the status key reports exactly one presence finding (typed head, not a line scan)", () => {
1020
+ const presence = judge(
1021
+ "phase-spec",
1022
+ specLineage("v1.1", [ROW_100, ROW_101]).replace("\nstatus: Draft", ""),
1023
+ ).filter((finding) => finding.kind === "presence");
1024
+ expect(presence).toHaveLength(1);
1025
+ expect(presence[0]!.field).toBe("status");
1026
+ });
1027
+
1028
+ it("domain — a status outside the declared enum reports exactly one domain finding", () => {
1029
+ const domain = judge(
1030
+ "phase-spec",
1031
+ specLineage("v1.1", [ROW_100, ROW_101]).replace("status: Draft", "status: Bogus"),
1032
+ ).filter((finding) => finding.kind === "domain");
1033
+ expect(domain).toHaveLength(1);
1034
+ expect(domain[0]!.field).toBe("status");
1035
+ });
1036
+
1037
+ it("RAW — the head value extracts verbatim while the body still canonicalizes (both sides of the same doc)", () => {
1038
+ const content = GOOD_OVERALL.replace("title: 测试 Overall", "title: 任务组总体").replace(
1039
+ "### Goal\n- goal text",
1040
+ "### Goal\n- goal text\n\n#### M 组(skill-ref 映射,M1–M4 全关)\n- m leaf",
1041
+ );
1042
+ // The head channel reads the RAW content — the registered zh alias 组 rides
1043
+ // the title verbatim, never the canonicalize view.
1044
+ const { head } = FrontMatterExtractor.split(content);
1045
+ expect(head.value("title")).toBe("任务组总体");
1046
+ // The body channel canonicalizes in the SAME validate call — the zh 组 leaf
1047
+ // conforms to the `#### [MFRBEN] group` facet only through the view.
1048
+ const findings = judge("overall-spec", content, GOOD_OVERALL_FS);
1049
+ expect(withKind(findings, "presence", "#### [MFRBEN] group")).toBe(false);
1050
+ expect(withKind(findings, "domain", "#### [MFRBEN] group")).toBe(false);
1051
+ // The exact body-line face — the same Translator seam validate applies to
1052
+ // every body row (the canonicalize target of the registered 组 alias).
1053
+ expect(new Translator(new Words()).canonicalize("TaskGraph 分组派生")).toBe(
1054
+ "TaskGraph 分group派生",
1055
+ );
1056
+ });
1057
+ });
1058
+
1059
+ /** A conforming phase-spec — the front-matter head + the double-layer design
1060
+ * skeleton + the Change-history lineage (the shared phase-spec fixture family). */
1061
+ const phaseSpec = (version: string): string => {
1062
+ return [
1063
+ "---",
1064
+ "title: Test Spec",
1065
+ "doc-type: phase-spec",
1066
+ `version: ${version}`,
1067
+ "date: 2026-10-09",
1068
+ "status: Draft",
1069
+ "author: x",
1070
+ "parent-program: docs/kairos/specs/x-overall.md",
1071
+ "parent-version: v1.0",
1072
+ "depends-on: P1",
1073
+ "---",
1074
+ "",
1075
+ "## Design",
1076
+ "",
1077
+ "### 1. 数据面",
1078
+ "#### 1.1 登记表",
1079
+ "- text",
1080
+ "",
1081
+ "### Acceptance criteria",
1082
+ "",
1083
+ "- `c`",
1084
+ "",
1085
+ "## Constraints",
1086
+ "",
1087
+ "- delta",
1088
+ "",
1089
+ "## Change history",
1090
+ "",
1091
+ "| Version | date | summary | author |",
1092
+ "|---|---|---|---|",
1093
+ "| v1.0 | 2026-10-08 | prior | [human] |",
1094
+ "| v1.1 | 2026-10-09 | merged | [human] |",
1095
+ ].join("\n");
1096
+ };
1097
+
860
1098
  /** One rendered `### Task N:` block with all required fields. */
861
1099
  const planTask = (id: number): string[] => {
862
1100
  return [