@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
@@ -6,7 +6,7 @@
6
6
  // · BoardView.scanPhases — the phase-suffix set from the specs dir, sorted by the
7
7
  // dot-separated numeric path, with NO on-disk-absent parent synthesized;
8
8
  // · the artifact header read — `{version, status, docType}` from the doc's
9
- // header block, the doc type read from the `- **Doc type**:` declaration line
9
+ // front-matter head record, the doc type read from the `doc-type:` key
10
10
  // (spec §12 · D34 — null when absent, zero filename-suffix inference).
11
11
  // Fixtures are hermetic tmp dirs (no git needed — pure file-system reads).
12
12
 
@@ -15,6 +15,7 @@ import { tmpdir } from "node:os";
15
15
  import path from "node:path";
16
16
  import { afterEach, beforeEach, describe, expect, it } from "vitest";
17
17
  import { ConfigLoader } from "../../infra/config.ts";
18
+ import { type RepoPath, RepoRoot } from "../../infra/root.ts";
18
19
  import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
19
20
  import { Ledger } from "../../session/ledger.ts";
20
21
  import { BoardView } from "../board-view.ts";
@@ -143,17 +144,18 @@ describe("BoardView.readHeader — the artifact header `{version, status, docTyp
143
144
  rmSync(repo, { recursive: true, force: true });
144
145
  });
145
146
 
146
- it("reads the Version/Status/Doc type markers from a plan doc's header block", () => {
147
+ it("reads the version / status / doc-type head keys from a plan doc's front-matter", () => {
147
148
  mkdirSync(path.join(repo, "docs/kairos/plans"), { recursive: true });
148
149
  const planPath = path.join(repo, "docs/kairos/plans/prog-p8.md");
149
150
  writeFileSync(
150
151
  planPath,
151
152
  [
152
- "# The plan",
153
- "",
154
- "- **Version**: v0.9 · …",
155
- "- **Status**: Done",
156
- "- **Doc type**: plan",
153
+ "---",
154
+ "title: The plan",
155
+ "version: v0.9",
156
+ "status: Done",
157
+ "doc-type: plan",
158
+ "---",
157
159
  "",
158
160
  "## Constraints",
159
161
  "",
@@ -167,17 +169,18 @@ describe("BoardView.readHeader — the artifact header `{version, status, docTyp
167
169
  });
168
170
  });
169
171
 
170
- it("reads the declared docType from a phase-spec's `- **Doc type**:` declaration line", () => {
172
+ it("reads the declared docType from a phase-spec's front-matter `doc-type:` key", () => {
171
173
  mkdirSync(path.join(repo, "docs/kairos/specs"), { recursive: true });
172
174
  const specPath = path.join(repo, "docs/kairos/specs/prog-p8-design.md");
173
175
  writeFileSync(
174
176
  specPath,
175
177
  [
176
- "# The phase spec",
177
- "",
178
- "- **Version**: v1.2 · 2026-10-15",
179
- "- **Status**: In review",
180
- "- **Doc type**: phase-spec",
178
+ "---",
179
+ "title: The phase spec",
180
+ "version: v1.2",
181
+ "status: In review",
182
+ "doc-type: phase-spec",
183
+ "---",
181
184
  "",
182
185
  "## 1. The design group",
183
186
  "",
@@ -189,15 +192,17 @@ describe("BoardView.readHeader — the artifact header `{version, status, docTyp
189
192
  status: "In review",
190
193
  docType: "phase-spec",
191
194
  });
192
- expect(BoardView.readDocType(specPath)).toBe("phase-spec");
195
+ expect(
196
+ BoardView.readDocType(new RepoRoot(repo), path.relative(repo, specPath) as RepoPath),
197
+ ).toBe("phase-spec");
193
198
  });
194
199
 
195
- it("a doc without a Doc type declaration reads docType null — the consumer blocks, no suffix fallback", () => {
200
+ it("a doc without a `doc-type:` key reads docType null — the consumer blocks, no suffix fallback", () => {
196
201
  mkdirSync(path.join(repo, "docs/kairos/specs"), { recursive: true });
197
202
  const specPath = path.join(repo, "docs/kairos/specs/prog-p8-design.md");
198
203
  writeFileSync(
199
204
  specPath,
200
- ["# The phase spec", "", "- **Version**: v1.0", "- **Status**: Draft", ""].join("\n"),
205
+ ["---", "title: The phase spec", "version: v1.0", "status: Draft", "---", ""].join("\n"),
201
206
  );
202
207
 
203
208
  expect(BoardView.readHeader(specPath)).toEqual({
@@ -205,15 +210,19 @@ describe("BoardView.readHeader — the artifact header `{version, status, docTyp
205
210
  status: "Draft",
206
211
  docType: null,
207
212
  });
208
- expect(BoardView.readDocType(specPath)).toBeNull();
213
+ expect(
214
+ BoardView.readDocType(new RepoRoot(repo), path.relative(repo, specPath) as RepoPath),
215
+ ).toBeNull();
209
216
  });
210
217
 
211
- it("an out-of-domain Doc type value reads null — present facts, never a fabricated type", () => {
218
+ it("an out-of-domain doc-type value reads null — present facts, never a fabricated type", () => {
212
219
  mkdirSync(path.join(repo, "docs/kairos/plans"), { recursive: true });
213
220
  const planPath = path.join(repo, "docs/kairos/plans/prog-p8.md");
214
- writeFileSync(planPath, ["# The plan", "", "- **Doc type**: memo", ""].join("\n"));
221
+ writeFileSync(planPath, ["---", "title: The plan", "doc-type: memo", "---", ""].join("\n"));
215
222
 
216
- expect(BoardView.readDocType(planPath)).toBeNull();
223
+ expect(
224
+ BoardView.readDocType(new RepoRoot(repo), path.relative(repo, planPath) as RepoPath),
225
+ ).toBeNull();
217
226
  });
218
227
 
219
228
  it("an absent doc yields nulls — never a fabricated value", () => {
@@ -224,15 +233,17 @@ describe("BoardView.readHeader — the artifact header `{version, status, docTyp
224
233
  });
225
234
  });
226
235
 
227
- it("a doc whose first line is not the `# Title` still reads its metadata block", () => {
236
+ it("a doc whose head is the front-matter block (never an `# Title` line) still reads its metadata", () => {
228
237
  mkdirSync(path.join(repo, "docs/kairos/plans"), { recursive: true });
229
238
  const planPath = path.join(repo, "docs/kairos/plans/prog-p8.md");
230
239
  writeFileSync(
231
240
  planPath,
232
241
  [
233
- "- **Version**: v0.9 · …",
234
- "- **Status**: Done",
235
- "- **Doc type**: plan",
242
+ "---",
243
+ "version: v0.9",
244
+ "status: Done",
245
+ "doc-type: plan",
246
+ "---",
236
247
  "",
237
248
  "## Constraints",
238
249
  "",
@@ -413,19 +424,26 @@ describe("BoardView.render — the phase / program board layouts + the next deri
413
424
  };
414
425
 
415
426
  it("renders the phase board header + rows + the fixed legend tail", () => {
416
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
427
+ writeDoc("docs/kairos/specs/prog-overall.md", [
428
+ "---",
429
+ "title: O",
430
+ "doc-type: overall-spec",
431
+ "---",
432
+ ]);
417
433
  writeDoc("docs/kairos/specs/prog-p1-design.md", [
418
- "# S",
419
- "",
420
- "- **Version**: v0.14",
421
- "- **Status**: Done",
422
- "- **Doc type**: phase-spec",
434
+ "---",
435
+ "title: S",
436
+ "version: v0.14",
437
+ "status: Done",
438
+ "doc-type: phase-spec",
439
+ "---",
423
440
  ]);
424
441
  writeDoc("docs/kairos/plans/prog-p1.md", [
425
- "# Plan",
426
- "",
427
- "- **Version**: v0.9",
428
- "- **Doc type**: plan",
442
+ "---",
443
+ "title: Plan",
444
+ "version: v0.9",
445
+ "doc-type: plan",
446
+ "---",
429
447
  ]);
430
448
  seed("prog-p1", [{ wave: "spec", rounds: { review: [1, 2], fix: [1] } }]);
431
449
 
@@ -436,18 +454,34 @@ describe("BoardView.render — the phase / program board layouts + the next deri
436
454
  expect(text).toContain(" overall ");
437
455
  expect(text).toContain("prog-p1-design.md v0.14 · Done");
438
456
  expect(text).toContain("prog-p1.md v0.9");
457
+ // D47 — the doc cells render repoRoot-relative (docsOfSlug derives them absolute;
458
+ // the board emits the ONE shape). No row carries the absolute repo prefix.
459
+ expect(text).toContain(" spec docs/kairos/specs/prog-p1-design.md");
460
+ expect(text).toContain(" plan docs/kairos/plans/prog-p1.md");
461
+ expect(text).not.toContain(repo);
439
462
  expect(text).toContain(" branch ○ open");
440
463
  expect(text.split("\n").at(-1)).toBe("progress: ✔ done · ▶ current · ○ pending");
441
464
  });
442
465
 
443
466
  it("renders one wave line per derived wave with the ✔/▶ markers", () => {
444
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
445
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
467
+ writeDoc("docs/kairos/specs/prog-overall.md", [
468
+ "---",
469
+ "title: O",
470
+ "doc-type: overall-spec",
471
+ "---",
472
+ ]);
473
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
474
+ "---",
475
+ "title: S",
476
+ "doc-type: phase-spec",
477
+ "---",
478
+ ]);
446
479
  // Two task blocks → two waves.
447
480
  writeDoc("docs/kairos/plans/prog-p1.md", [
448
- "# Plan",
449
- "",
450
- "- **Doc type**: plan",
481
+ "---",
482
+ "title: Plan",
483
+ "doc-type: plan",
484
+ "---",
451
485
  "",
452
486
  "## Constraints",
453
487
  "",
@@ -491,22 +525,42 @@ describe("BoardView.render — the phase / program board layouts + the next deri
491
525
  // so its ACTIVE hop is the review-lead the dispatch engine would run (Ledger#lineRoute
492
526
  // → {kind:"review"}), NOT the exhausted-face handoff `/kairos:cdd-plan`. board next ==
493
527
  // engine next (the retired shallow form rendered the face-to-face entry for an open line).
494
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
495
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
496
- writeDoc("docs/kairos/plans/prog-p1.md", ["# Plan", "", "- **Doc type**: plan"]);
528
+ writeDoc("docs/kairos/specs/prog-overall.md", [
529
+ "---",
530
+ "title: O",
531
+ "doc-type: overall-spec",
532
+ "---",
533
+ ]);
534
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
535
+ "---",
536
+ "title: S",
537
+ "doc-type: phase-spec",
538
+ "---",
539
+ ]);
540
+ writeDoc("docs/kairos/plans/prog-p1.md", ["---", "title: Plan", "doc-type: plan", "---"]);
497
541
 
498
542
  const { text } = render("prog-p1");
499
543
 
500
544
  expect(text).toContain(
501
- ` next: review --type spec --spec ${path.join(repo, "docs/kairos/specs/prog-p1-design.md")}`,
545
+ ` next: review --type spec --spec ${path.relative(repo, path.join(repo, "docs/kairos/specs/prog-p1-design.md"))}`,
502
546
  );
503
547
  expect(text).not.toContain(" next: /kairos:cdd-plan");
504
548
  });
505
549
 
506
550
  it("phase board next: spec closed + plan not started → the plan line's active review hop", () => {
507
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
508
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
509
- writeDoc("docs/kairos/plans/prog-p1.md", ["# Plan", "", "- **Doc type**: plan"]);
551
+ writeDoc("docs/kairos/specs/prog-overall.md", [
552
+ "---",
553
+ "title: O",
554
+ "doc-type: overall-spec",
555
+ "---",
556
+ ]);
557
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
558
+ "---",
559
+ "title: S",
560
+ "doc-type: phase-spec",
561
+ "---",
562
+ ]);
563
+ writeDoc("docs/kairos/plans/prog-p1.md", ["---", "title: Plan", "doc-type: plan", "---"]);
510
564
  // Close the spec line: a recorded zero-findings spec review.
511
565
  const workspace = new Workspace(new WorkspaceRoot(repo, ".kairos/cdd"), "prog-p1").ensure();
512
566
  const ledger = new Ledger(workspace, new ConfigLoader());
@@ -518,7 +572,7 @@ describe("BoardView.render — the phase / program board layouts + the next deri
518
572
  // The spec face is exhausted → the plan line is the frontier; the plan line has not
519
573
  // started its C5 → its ACTIVE hop is the plan review (not the cdd-dev handoff).
520
574
  expect(text).toContain(
521
- ` next: review --type plan --plan ${path.join(repo, "docs/kairos/plans/prog-p1.md")}`,
575
+ ` next: review --type plan --plan ${path.relative(repo, path.join(repo, "docs/kairos/plans/prog-p1.md"))}`,
522
576
  );
523
577
  expect(text).not.toContain(" next: /kairos:cdd-dev");
524
578
  });
@@ -528,9 +582,19 @@ describe("BoardView.render — the phase / program board layouts + the next deri
528
582
  // count-based closure judge reads the nonexistent fix cycle 1 → plan OPEN → the
529
583
  // plan entry; the engine's identity judge reads the fix at cycle 2 → plan CLOSED
530
584
  // → next advances past the plan face.
531
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
532
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
533
- writeDoc("docs/kairos/plans/prog-p1.md", ["# Plan", "", "- **Doc type**: plan"]);
585
+ writeDoc("docs/kairos/specs/prog-overall.md", [
586
+ "---",
587
+ "title: O",
588
+ "doc-type: overall-spec",
589
+ "---",
590
+ ]);
591
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
592
+ "---",
593
+ "title: S",
594
+ "doc-type: phase-spec",
595
+ "---",
596
+ ]);
597
+ writeDoc("docs/kairos/plans/prog-p1.md", ["---", "title: Plan", "doc-type: plan", "---"]);
534
598
  const workspace = new Workspace(new WorkspaceRoot(repo, ".kairos/cdd"), "prog-p1").ensure();
535
599
  const ledger = new Ledger(workspace, new ConfigLoader());
536
600
  // spec closed (a recorded zero-findings spec review)
@@ -555,9 +619,19 @@ describe("BoardView.render — the phase / program board layouts + the next deri
555
619
  // (the single judge) — a jump-number row `{review:[1,2], fix:[2]}` (D28) must read
556
620
  // CLOSED on BOTH faces. A count-based board judge (the retired hand-rolled form)
557
621
  // would read it OPEN and diverge from the engine.
558
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
559
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
560
- writeDoc("docs/kairos/plans/prog-p1.md", ["# Plan", "", "- **Doc type**: plan"]);
622
+ writeDoc("docs/kairos/specs/prog-overall.md", [
623
+ "---",
624
+ "title: O",
625
+ "doc-type: overall-spec",
626
+ "---",
627
+ ]);
628
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
629
+ "---",
630
+ "title: S",
631
+ "doc-type: phase-spec",
632
+ "---",
633
+ ]);
634
+ writeDoc("docs/kairos/plans/prog-p1.md", ["---", "title: Plan", "doc-type: plan", "---"]);
561
635
  const workspace = new Workspace(new WorkspaceRoot(repo, ".kairos/cdd"), "prog-p1").ensure();
562
636
  const ledger = new Ledger(workspace, new ConfigLoader());
563
637
  ledger.persistHandoff("review", "plan", { round: 2 }, { findings: [] });
@@ -574,12 +648,23 @@ describe("BoardView.render — the phase / program board layouts + the next deri
574
648
  });
575
649
 
576
650
  it("D40 — the wave line's label carries the wave's task scope (W3 = tasks 5,11)", () => {
577
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
578
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
651
+ writeDoc("docs/kairos/specs/prog-overall.md", [
652
+ "---",
653
+ "title: O",
654
+ "doc-type: overall-spec",
655
+ "---",
656
+ ]);
657
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
658
+ "---",
659
+ "title: S",
660
+ "doc-type: phase-spec",
661
+ "---",
662
+ ]);
579
663
  writeDoc("docs/kairos/plans/prog-p1.md", [
580
- "# Plan",
581
- "",
582
- "- **Doc type**: plan",
664
+ "---",
665
+ "title: Plan",
666
+ "doc-type: plan",
667
+ "---",
583
668
  "",
584
669
  "## Constraints",
585
670
  "",
@@ -622,12 +707,23 @@ describe("BoardView.render — the phase / program board layouts + the next deri
622
707
  // (`implement --plan <plan> --tasks 12,13,14`), NOT the exhausted-wave face handoff
623
708
  // (`review --type branch …`). A shallow `resolve(null, …)` renders the branch-review
624
709
  // handoff here — the bug (W4 in flight rendering branch review) this pin drives out.
625
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
626
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
710
+ writeDoc("docs/kairos/specs/prog-overall.md", [
711
+ "---",
712
+ "title: O",
713
+ "doc-type: overall-spec",
714
+ "---",
715
+ ]);
716
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
717
+ "---",
718
+ "title: S",
719
+ "doc-type: phase-spec",
720
+ "---",
721
+ ]);
627
722
  writeDoc("docs/kairos/plans/prog-p1.md", [
628
- "# Plan",
629
- "",
630
- "- **Doc type**: plan",
723
+ "---",
724
+ "title: Plan",
725
+ "doc-type: plan",
726
+ "---",
631
727
  "",
632
728
  "## Constraints",
633
729
  "",
@@ -689,7 +785,7 @@ describe("BoardView.render — the phase / program board layouts + the next deri
689
785
  // 12,13,14`, never the exhausted-wave face handoff `review --type branch`).
690
786
 
691
787
  const { text } = render("prog-p1");
692
- const planPath = path.join(repo, "docs/kairos/plans/prog-p1.md");
788
+ const planPath = path.relative(repo, path.join(repo, "docs/kairos/plans/prog-p1.md"));
693
789
 
694
790
  // The active wave hop — the not-yet-implemented wave renders its implement literal.
695
791
  expect(text).toContain(` next: implement --plan ${planPath} --tasks 12,13,14`);
@@ -698,12 +794,23 @@ describe("BoardView.render — the phase / program board layouts + the next deri
698
794
  });
699
795
 
700
796
  it("D40 — the wave-line markers align into one fixed-width column across differing id-set widths", () => {
701
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
702
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
797
+ writeDoc("docs/kairos/specs/prog-overall.md", [
798
+ "---",
799
+ "title: O",
800
+ "doc-type: overall-spec",
801
+ "---",
802
+ ]);
803
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
804
+ "---",
805
+ "title: S",
806
+ "doc-type: phase-spec",
807
+ "---",
808
+ ]);
703
809
  writeDoc("docs/kairos/plans/prog-p1.md", [
704
- "# Plan",
705
- "",
706
- "- **Doc type**: plan",
810
+ "---",
811
+ "title: Plan",
812
+ "doc-type: plan",
813
+ "---",
707
814
  "",
708
815
  "## Constraints",
709
816
  "",
@@ -764,14 +871,27 @@ describe("BoardView.render — the phase / program board layouts + the next deri
764
871
  expect(new Set(markerColumns).size).toBe(1);
765
872
  });
766
873
 
767
- it("phase board next: a drained line hands off to the next face's skill ref (host fallback)", () => {
768
- // D40 deep-solve — the spec line is closed and NO plan doc exists: the plan line
769
- // (not closed — no row) holds no active C5 hop (no doc), so it hands off to its
770
- // pipeline entry `PIPELINE_NEXT.plan` → the cdd-dev ref. The board renders that
771
- // through the SAME RouteRenderer the Capsule's `done` face uses; host "" falls
772
- // back to the claude form (REFS[ref].claude) — never a bare plugin guess.
773
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
774
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
874
+ it("phase board next: a just-closed spec hands off to its OWN exit (never the absent plan's)", () => {
875
+ // D40 deep-solve / D26 — the spec line is closed and NO plan doc exists yet: the
876
+ // plan face is the frontier but was NEVER ENTERED (no doc), so the transition is
877
+ // the PRECEDING face's exit — the spec's `PIPELINE_NEXT["phase-spec"]` → the
878
+ // cdd-plan ref. The retired board fork handed off via the frontier LINE's own key
879
+ // (the absent plan's `cdd-dev`) — a face-boundary off-by-one the ONE walk kills
880
+ // (a closed spec means "author the plan", not "the plan is done"). Rendering rides
881
+ // the SAME RouteRenderer the Capsule's `done` face uses; host "" falls back to the
882
+ // claude form (REFS[ref].claude) — never a bare plugin guess.
883
+ writeDoc("docs/kairos/specs/prog-overall.md", [
884
+ "---",
885
+ "title: O",
886
+ "doc-type: overall-spec",
887
+ "---",
888
+ ]);
889
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
890
+ "---",
891
+ "title: S",
892
+ "doc-type: phase-spec",
893
+ "---",
894
+ ]);
775
895
  const workspace = new Workspace(new WorkspaceRoot(repo, ".kairos/cdd"), "prog-p1").ensure();
776
896
  const ledger = new Ledger(workspace, new ConfigLoader());
777
897
  ledger.persistHandoff("review", "spec", { round: 1 }, { findings: [] });
@@ -779,58 +899,119 @@ describe("BoardView.render — the phase / program board layouts + the next deri
779
899
 
780
900
  const { text } = render("prog-p1", "");
781
901
 
782
- expect(text).toContain(" next: /kairos:cdd-dev");
902
+ expect(text).toContain(" next: /kairos:cdd-plan");
783
903
  });
784
904
 
785
905
  it("board per-harness ref pins — a drained line renders REFS[ref][host] (host=pi → /skill:…)", () => {
786
906
  // The board's per-harness spelling rides REFS[ref][host] (never a claude-form
787
- // constant). The reachable refs on the phase board's per-line walk: the spec face
788
- // (no spec doc → the cdd-plan entry) and the plan face (spec closed + no plan doc
789
- // → the cdd-dev entry). host=pi renders the flat `/skill:<bare>` form.
790
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
907
+ // constant). The reachable ref at the spec boundary is cdd-plan through both
908
+ // sub-states — the spec face never authored, and the spec face just closed with no
909
+ // plan authored (the off-by-one the fork rendered as the absent plan's cdd-dev).
910
+ // host=pi renders the flat `/skill:<bare>` form.
911
+ writeDoc("docs/kairos/specs/prog-overall.md", [
912
+ "---",
913
+ "title: O",
914
+ "doc-type: overall-spec",
915
+ "---",
916
+ ]);
791
917
  // The spec face is the frontier with no spec doc → PIPELINE_NEXT."phase-spec" → cdd-plan.
792
918
  expect(nextOf("prog-p1", "pi")).toBe("/skill:cdd-plan");
793
919
  expect(nextOf("prog-p1", "claude")).toBe("/kairos:cdd-plan");
794
920
 
795
- // Close the spec line so the plan face is the frontier; no plan doc → the cdd-dev ref.
796
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
921
+ // Close the spec line so the plan face is the frontier; no plan doc → the spec's OWN
922
+ // exit (cdd-plan), never the absent plan's cdd-dev.
923
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
924
+ "---",
925
+ "title: S",
926
+ "doc-type: phase-spec",
927
+ "---",
928
+ ]);
797
929
  const workspace = new Workspace(new WorkspaceRoot(repo, ".kairos/cdd"), "prog-p1").ensure();
798
930
  const ledger = new Ledger(workspace, new ConfigLoader());
799
931
  ledger.persistHandoff("review", "spec", { round: 1 }, { findings: [] });
800
932
  ledger.recordRound("spec", "review");
801
- expect(nextOf("prog-p1", "pi")).toBe("/skill:cdd-dev");
802
- expect(nextOf("prog-p1", "claude")).toBe("/kairos:cdd-dev");
933
+ expect(nextOf("prog-p1", "pi")).toBe("/skill:cdd-plan");
934
+ expect(nextOf("prog-p1", "claude")).toBe("/kairos:cdd-plan");
803
935
  });
804
936
 
805
937
  it("board next == the Capsule's done face — the shared renderer byte-identity (host claude / pi)", () => {
806
938
  // route-render.ts claims the board's `next:` and the capsule's `next:` are
807
- // byte-identical by construction (ONE RouteRenderer). Pin it: a drained plan face
808
- // hands off to the SAME pipeline entry through both seams, and both seams now read
809
- // the SAME argv channel (the board is threaded ARGV_CHANNEL from the composition
810
- // root) — a flag-spelling change cannot silently split the two faces.
811
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
812
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
939
+ // byte-identical by construction (ONE RouteRenderer). Pin it at the state BOTH
940
+ // seams agree on: the spec boundary. The board has a closed spec face + no plan doc
941
+ // (the plan face unentered → the spec's exit entry); the capsule's `done` face is
942
+ // fed the closed spec line's target (a phase-spec doc → `PIPELINE_NEXT["phase-spec"]`).
943
+ // Both resolve to the SAME pipeline entry through the ONE renderer, and both seams
944
+ // read the SAME argv channel (the board is threaded ARGV_CHANNEL from the
945
+ // composition root) — a flag-spelling change cannot silently split the two faces.
946
+ writeDoc("docs/kairos/specs/prog-overall.md", [
947
+ "---",
948
+ "title: O",
949
+ "doc-type: overall-spec",
950
+ "---",
951
+ ]);
952
+ const specId = writeDoc("docs/kairos/specs/prog-p1-design.md", [
953
+ "---",
954
+ "title: S",
955
+ "doc-type: phase-spec",
956
+ "---",
957
+ ]);
813
958
  const workspace = new Workspace(new WorkspaceRoot(repo, ".kairos/cdd"), "prog-p1").ensure();
814
959
  const ledger = new Ledger(workspace, new ConfigLoader());
815
960
  ledger.persistHandoff("review", "spec", { round: 1 }, { findings: [] });
816
961
  ledger.recordRound("spec", "review");
817
- const planId = path.join(repo, "docs/kairos/plans/prog-p1.md");
818
962
 
819
963
  for (const host of ["claude", "pi"]) {
820
- const capsuleNext = new Capsule(new Words(), ARGV_CHANNEL, host, repo)
821
- .emit("APPROVED", "0", "/h.json", { kind: "done" }, { type: "plan", id: planId })[1]!
964
+ const capsuleNext = new Capsule(new Words(), ARGV_CHANNEL, host, new RepoRoot(repo))
965
+ .emit("APPROVED", "0", "/h.json", { kind: "done" }, { type: "spec", id: specId })[1]!
966
+ .slice("next: ".length);
967
+ // The board's spec face is drained (spec closed + no plan doc) → the same entry.
968
+ expect(nextOf("prog-p1", host)).toBe(capsuleNext);
969
+ expect(capsuleNext).toBe(host === "pi" ? "/skill:cdd-plan" : "/kairos:cdd-plan");
970
+ }
971
+ });
972
+
973
+ it("D47 — the next: literal's embedded paths are repoRoot-relative, byte-identical board↔capsule", () => {
974
+ // route-render.ts is the ONE renderer for both faces; D47 makes its embedded path
975
+ // values repoRoot-relative (the ONE shape, §2.13). Pin BOTH seams at a path-bearing
976
+ // C5 hop — the spec review literal's `--spec` — feeding the capsule an ABSOLUTE
977
+ // target path: the renderer must emit the repoRoot-relative form on both faces alike.
978
+ writeDoc("docs/kairos/specs/prog-overall.md", [
979
+ "---",
980
+ "title: O",
981
+ "doc-type: overall-spec",
982
+ "---",
983
+ ]);
984
+ const specId = writeDoc("docs/kairos/specs/prog-p1-design.md", [
985
+ "---",
986
+ "title: S",
987
+ "doc-type: phase-spec",
988
+ "---",
989
+ ]);
990
+ writeDoc("docs/kairos/plans/prog-p1.md", ["---", "title: Plan", "doc-type: plan", "---"]);
991
+ expect(path.isAbsolute(specId)).toBe(true);
992
+
993
+ for (const host of ["claude", "pi"]) {
994
+ const capsuleNext = new Capsule(new Words(), ARGV_CHANNEL, host, new RepoRoot(repo))
995
+ .emit("APPROVED", "0", "/h.json", { kind: "review" }, { type: "spec", id: specId })[1]!
822
996
  .slice("next: ".length);
823
- // The board's plan face is drained (spec closed + no plan doc) → the same entry.
997
+ // The reviewer's own hop renders the repoRoot-relative --spec (never the absolute).
998
+ expect(capsuleNext).toBe("review --type spec --spec docs/kairos/specs/prog-p1-design.md");
999
+ expect(capsuleNext).not.toContain(repo);
1000
+ // The board's spec frontier renders the SAME byte-identical relative literal.
824
1001
  expect(nextOf("prog-p1", host)).toBe(capsuleNext);
825
- expect(capsuleNext).toBe(host === "pi" ? "/skill:cdd-dev" : "/kairos:cdd-dev");
826
1002
  }
827
1003
  });
828
1004
 
829
1005
  it("a present doc without a Doc type declaration renders BLOCKED and exits 2", () => {
830
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
831
- // The spec doc carries NO `- **Doc type**:` line.
832
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Version**: v1.0"]);
833
- writeDoc("docs/kairos/plans/prog-p1.md", ["# Plan", "", "- **Doc type**: plan"]);
1006
+ writeDoc("docs/kairos/specs/prog-overall.md", [
1007
+ "---",
1008
+ "title: O",
1009
+ "doc-type: overall-spec",
1010
+ "---",
1011
+ ]);
1012
+ // The spec doc carries NO `doc-type:` key.
1013
+ writeDoc("docs/kairos/specs/prog-p1-design.md", ["---", "title: S", "version: v1.0", "---"]);
1014
+ writeDoc("docs/kairos/plans/prog-p1.md", ["---", "title: Plan", "doc-type: plan", "---"]);
834
1015
 
835
1016
  const { text, exitCode } = render("prog-p1");
836
1017
 
@@ -840,17 +1021,24 @@ describe("BoardView.render — the phase / program board layouts + the next deri
840
1021
 
841
1022
  it("renders the program board with one phase summary line + next: done", () => {
842
1023
  writeDoc("docs/kairos/specs/prog-overall.md", [
843
- "# O",
844
- "",
845
- "- **Version**: v2.33",
846
- "- **Doc type**: overall-spec",
1024
+ "---",
1025
+ "title: O",
1026
+ "version: v2.33",
1027
+ "doc-type: overall-spec",
1028
+ "---",
1029
+ ]);
1030
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
1031
+ "---",
1032
+ "title: S",
1033
+ "doc-type: phase-spec",
1034
+ "---",
847
1035
  ]);
848
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
849
1036
  // Two task blocks → two waves, so the phase line carries its `wave W1…` token (spec §5.3).
850
1037
  writeDoc("docs/kairos/plans/prog-p1.md", [
851
- "# Plan",
852
- "",
853
- "- **Doc type**: plan",
1038
+ "---",
1039
+ "title: Plan",
1040
+ "doc-type: plan",
1041
+ "---",
854
1042
  "",
855
1043
  "## Constraints",
856
1044
  "",
@@ -897,11 +1085,16 @@ describe("BoardView.render — the phase / program board layouts + the next deri
897
1085
  });
898
1086
 
899
1087
  it("the program board propagates a phase doc-type BLOCK — a present phase spec without a declaration exits 2", () => {
900
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
901
- // The phase spec carries NO `- **Doc type**:` line — the phase board BLOCKs it;
1088
+ writeDoc("docs/kairos/specs/prog-overall.md", [
1089
+ "---",
1090
+ "title: O",
1091
+ "doc-type: overall-spec",
1092
+ "---",
1093
+ ]);
1094
+ // The phase spec carries NO `doc-type:` key — the phase board BLOCKs it;
902
1095
  // the program board must propagate the SAME BLOCK (no silent fallback, spec §12).
903
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Version**: v1.0"]);
904
- writeDoc("docs/kairos/plans/prog-p1.md", ["# Plan", "", "- **Doc type**: plan"]);
1096
+ writeDoc("docs/kairos/specs/prog-p1-design.md", ["---", "title: S", "version: v1.0", "---"]);
1097
+ writeDoc("docs/kairos/plans/prog-p1.md", ["---", "title: Plan", "doc-type: plan", "---"]);
905
1098
 
906
1099
  const { text, exitCode } = render("prog");
907
1100
 
@@ -910,8 +1103,18 @@ describe("BoardView.render — the phase / program board layouts + the next deri
910
1103
  });
911
1104
 
912
1105
  it("degrades without error — an absent plan leaves the wave segment empty", () => {
913
- writeDoc("docs/kairos/specs/prog-overall.md", ["# O", "", "- **Doc type**: overall-spec"]);
914
- writeDoc("docs/kairos/specs/prog-p1-design.md", ["# S", "", "- **Doc type**: phase-spec"]);
1106
+ writeDoc("docs/kairos/specs/prog-overall.md", [
1107
+ "---",
1108
+ "title: O",
1109
+ "doc-type: overall-spec",
1110
+ "---",
1111
+ ]);
1112
+ writeDoc("docs/kairos/specs/prog-p1-design.md", [
1113
+ "---",
1114
+ "title: S",
1115
+ "doc-type: phase-spec",
1116
+ "---",
1117
+ ]);
915
1118
 
916
1119
  const board = BoardView.render("prog-p1", repo, new Words(), "claude");
917
1120