@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
@@ -10,7 +10,7 @@
10
10
  // acceptance's unknown-flag BLOCK) and the program scopes (--dry-run / --help)
11
11
  // — the parse-level assertions ride runArgv (the retired tokenizer and its
12
12
  // guard never return to the tree);
13
- // · the work-command E2E (dry-run) — implement / review / fix compose the lifecycle,
13
+ // · the work-command E2E — implement / review / fix compose the lifecycle,
14
14
  // the capsule and the ledger in a hermetic temp repo, advance the requested phase
15
15
  // and land the canonical artifacts (brief / handoffs / progress); the phase gate
16
16
  // refuses an unreachable round without dispatching a phantom;
@@ -23,8 +23,9 @@
23
23
  // renderer's own suite lives in render/__tests__/render.test.ts, its T19
24
24
  // home), base set/get (the single → artifact);
25
25
  // · the composition root + HarnessDispatch — host detection, the dispatch prompt
26
- // (template data plane), the child return-block parse (block + JSON).
27
- // Fixtures are hermetic mkdtemp repos (git-inited for the dry-run HEAD); the io is
26
+ // (template data plane), the handoff-draft readback into the outcome.
27
+ // Fixtures are hermetic mkdtemp repos (git-inited — the engine resolves the repo
28
+ // root from the git top level and the review binds its `next:` base there); the io is
28
29
  // captured, never the process.
29
30
 
30
31
  import { spawnSync } from "node:child_process";
@@ -35,26 +36,28 @@ import {
35
36
  mkdtempSync,
36
37
  readdirSync,
37
38
  readFileSync,
39
+ realpathSync,
38
40
  rmSync,
39
41
  writeFileSync,
40
42
  } from "node:fs";
41
43
  import { tmpdir } from "node:os";
42
44
  import path from "node:path";
43
45
  import type { Command } from "commander";
44
- import { describe, expect, it } from "vitest";
46
+ import { afterEach, describe, expect, it } from "vitest";
45
47
  import { ConfigLoader } from "../../infra/config.ts";
46
48
  import { Workspace, WorkspaceRoot } from "../../infra/workspace.ts";
47
49
  import { BriefRenderer } from "../../render/brief.ts";
48
50
  import type { RouteTarget } from "../../session/faces.ts";
49
- import { Ledger } from "../../session/ledger.ts";
51
+ import { Ledger, type SampleRecord } from "../../session/ledger.ts";
50
52
  import type { Route } from "../../session/next.ts";
51
53
  import { FIX_READBACK_SUFFIX } from "../../session/next.ts";
52
- import type { OpenFrame } from "../../session/run.ts";
54
+ import type { DispatchStep, OpenFrame } from "../../session/run.ts";
53
55
  import { Capsule } from "../capsule.ts";
54
- import type { CliIo, CliOptions, DispatchScene, SyncProcess } from "../cli.ts";
56
+ import type { CliIo, CliOptions, DispatchScene } from "../cli.ts";
55
57
  import { Cli, HarnessDispatch } from "../cli.ts";
56
58
  import { CLI_COMMANDS, type CliVerb } from "../declare.ts";
57
59
  import { CommandTreeBuilder } from "../projection.ts";
60
+ import type { ChildOutcome, ChildRun, ChildRunner, Termination } from "../termination.ts";
58
61
  import { Words } from "../words.ts";
59
62
  import { negatedOf } from "./negation.ts";
60
63
 
@@ -128,25 +131,50 @@ interface CliFixture {
128
131
  cleanup: () => void;
129
132
  }
130
133
 
131
- /** A hermetic CLI fixture — a fresh temp repo, the io captured, the root injected. */
134
+ /** The process cwd before any fixture chdir — restored after every test so the
135
+ * isolation never leaks across tests (§2.12: the engine resolves the repo root
136
+ * from the working directory, so the fixture isolates by chdir). */
137
+ const ORIGINAL_CWD = process.cwd();
138
+ afterEach(() => {
139
+ process.chdir(ORIGINAL_CWD);
140
+ });
141
+
142
+ /** The hermetic approving dispatch — the real-run stand-in for the retired
143
+ * `--dry-run` synthetic approval (P11 · §2.2/§2.4): a work round lands APPROVED
144
+ * (a findings-free work carrier), a findings round lands zero findings (its
145
+ * conclusion derives APPROVED at judgment time). The E2E tests inject it and drop
146
+ * `--dry-run`, so the lifecycle (bookkeep · capsule · next hop) runs for real
147
+ * without spawning a child. */
148
+ const APPROVING: DispatchStep = async () => ({ status: "APPROVED", findings: [] });
149
+
150
+ /** A hermetic CLI fixture — a fresh temp repo, the io captured, the cwd isolated
151
+ * into the temp root (the engine resolves the repo root from `process.cwd()`, so
152
+ * the fixture chdirs rather than injecting a root — §2.12). The temp root is taken
153
+ * through `realpathSync` because the engine's git-top-level resolution returns the
154
+ * REAL path (macOS `/var` is a symlink to `/private/var`), so the fixture's paths
155
+ * must speak the same basis the engine resolves. */
132
156
  const fixture = (opts: CliOptions = {}): CliFixture => {
133
- const repoRoot = mkdtempSync(path.join(tmpdir(), "cli-"));
157
+ const repoRoot = realpathSync(mkdtempSync(path.join(tmpdir(), "cli-")));
158
+ process.chdir(repoRoot);
134
159
  const io = new CaptureIo();
135
- const command = Cli.create({ io, repoRoot, ...opts });
160
+ const command = Cli.create({ io, ...opts });
136
161
  return {
137
162
  command,
138
163
  io,
139
164
  repoRoot,
140
- cleanup: () => rmSync(repoRoot, { recursive: true, force: true }),
165
+ cleanup: () => {
166
+ process.chdir(ORIGINAL_CWD);
167
+ rmSync(repoRoot, { recursive: true, force: true });
168
+ },
141
169
  };
142
170
  };
143
171
 
144
- /** Init a git repo with one commit — the dry-run's HEAD (the review `next:` base).
145
- * The fixture .gitignore keeps the dispatch's own writes (the `.kairos` workspace)
146
- * and the fixture's synthetic docs (`/docs/`) out of the tree — the working tree
147
- * stays clean across multi-dispatch flows (the P4.1 clean-tree dispatch gate).
148
- * Pass an explicit ignore content to shape it (the no-`.kairos`-ignore consumer
149
- * regression). */
172
+ /** Init a git repo with one commit — the repo root the engine resolves from the
173
+ * working directory, and the review `next:` base. The fixture .gitignore keeps the
174
+ * dispatch's own writes (the `.kairos` workspace) and the fixture's synthetic docs
175
+ * (`/docs/`) out of the tree — the working tree stays clean across multi-dispatch
176
+ * flows (the P4.1 clean-tree dispatch gate). Pass an explicit ignore content to
177
+ * shape it (the no-`.kairos`-ignore consumer regression). */
150
178
  const gitInit = (repoRoot: string, ignore = ".kairos\n/docs/\n"): string => {
151
179
  spawnSync("git", ["init", "-q"], { cwd: repoRoot });
152
180
  spawnSync("git", ["config", "user.email", "cli@test"], { cwd: repoRoot });
@@ -180,9 +208,15 @@ const planFor = (repoRoot: string, count = 1, name = "p3.md"): string => {
180
208
  writeFileSync(
181
209
  file,
182
210
  [
183
- "# Test Plan",
184
- "**Spec:** [p3-design.md](docs/kairos/specs/p3-design.md)",
185
- "- **Parent program**: [p3-overall.md v1.0](docs/kairos/specs/p3-overall.md)",
211
+ "---",
212
+ "title: Test Plan",
213
+ "doc-type: plan",
214
+ "version: v1.0",
215
+ "date: 2026-10-09",
216
+ "spec: docs/kairos/specs/p3-design.md",
217
+ "parent-program: docs/kairos/specs/p3-overall.md",
218
+ "parent-version: v1.0",
219
+ "---",
186
220
  "",
187
221
  "## Constraints",
188
222
  "",
@@ -203,14 +237,16 @@ const readJson = <T>(file: string): T => {
203
237
  /** The D30 wave-line reviewed identity — the brief-revision ref a wave row binds:
204
238
  * the plan it renders FROM + the RENDERED brief's sha1 (the wave gate binds the
205
239
  * brief, never the whole plan). */
206
- const briefRevision = (plan: string, tasks: string) => {
240
+ const briefRevision = (repoRoot: string, plan: string, tasks: string) => {
207
241
  const brief = new BriefRenderer().render(
208
242
  readFileSync(plan, "utf8"),
209
243
  tasks.split(",").map(Number),
210
244
  );
211
245
  return {
212
246
  kind: "brief-revision" as const,
213
- plan,
247
+ // The persisted shape is the canonical repoRoot-relative form (P9 T4 §2.7):
248
+ // the rendered-from plan field lands relative to repoRoot, never absolute.
249
+ plan: path.relative(repoRoot, plan),
214
250
  brief_hash: createHash("sha1").update(brief).digest("hex"),
215
251
  };
216
252
  };
@@ -220,19 +256,26 @@ const briefRevision = (plan: string, tasks: string) => {
220
256
  * links resolving into existing same-family siblings. The P4.1 doc-contract
221
257
  * dispatch gate (the spec/plan faces) requires it — a plain task-fixture plan is
222
258
  * structurally defective and never dispatches a doc round. */
223
- const conformingPlan = (repoRoot: string): string => {
259
+ const conformingPlan = (
260
+ repoRoot: string,
261
+ specTarget = "docs/kairos/specs/p3-design.md",
262
+ ): string => {
224
263
  const file = path.join(repoRoot, "docs", "kairos", "plans", "p3.md");
225
264
  mkdirSync(path.dirname(file), { recursive: true });
226
265
  writeFileSync(
227
266
  file,
228
267
  [
229
- "# Test Plan",
230
- "**Spec:** [p3-design.md](docs/kairos/specs/p3-design.md)",
231
- "- **Parent program**: [p3-overall.md v1.0](docs/kairos/specs/p3-overall.md)",
232
- "- **Version**: v1.0 · 2026-10-09",
233
- "- **Doc type**: plan",
234
- "- **Depends on**: P1",
235
- "- **Base**: develop",
268
+ "---",
269
+ "title: Test Plan",
270
+ "doc-type: plan",
271
+ "version: v1.0",
272
+ "date: 2026-10-09",
273
+ `spec: ${specTarget}`,
274
+ "parent-program: docs/kairos/specs/p3-overall.md",
275
+ "parent-version: v1.0",
276
+ "depends-on: P1",
277
+ "base: develop",
278
+ "---",
236
279
  "",
237
280
  "## Constraints",
238
281
  "",
@@ -276,12 +319,14 @@ const conformingOverall = (repoRoot: string): string => {
276
319
  writeFileSync(
277
320
  file,
278
321
  [
279
- "# Test Overall",
280
- "- **Version**: v1.21 · 2026-10-07",
281
- "- **Status**: Approved",
282
- "- **Doc type**: overall-spec",
283
- "- **Author**: [human]",
284
- "- **Constraints**: all cross-cutting constraints apply",
322
+ "---",
323
+ "title: Test Overall",
324
+ "doc-type: overall-spec",
325
+ "version: v1.21",
326
+ "date: 2026-10-07",
327
+ "status: Approved",
328
+ 'author: "[human]"',
329
+ "---",
285
330
  "",
286
331
  "## Document scope",
287
332
  "scope prose",
@@ -320,6 +365,10 @@ const conformingOverall = (repoRoot: string): string => {
320
365
  "## Boundary rules",
321
366
  "- boundary rule",
322
367
  "",
368
+ "## Constraints",
369
+ "",
370
+ "- 全部约定自动生效",
371
+ "",
323
372
  "## Maintenance",
324
373
  "- maintenance note",
325
374
  "",
@@ -366,9 +415,15 @@ const independentPlan = (repoRoot: string, name: string, count: number): string
366
415
  writeFileSync(
367
416
  file,
368
417
  [
369
- "# Test Plan",
370
- "**Spec:** [p3-design.md](docs/kairos/specs/p3-design.md)",
371
- "- **Parent program**: [p3-overall.md v1.0](docs/kairos/specs/p3-overall.md)",
418
+ "---",
419
+ "title: Test Plan",
420
+ "doc-type: plan",
421
+ "version: v1.0",
422
+ "date: 2026-10-09",
423
+ "spec: docs/kairos/specs/p3-design.md",
424
+ "parent-program: docs/kairos/specs/p3-overall.md",
425
+ "parent-version: v1.0",
426
+ "---",
372
427
  "",
373
428
  "## Constraints",
374
429
  "",
@@ -382,22 +437,26 @@ const independentPlan = (repoRoot: string, name: string, count: number): string
382
437
  };
383
438
 
384
439
  /** A doc-contract-clean phase-spec — every registered phase-spec element present
385
- * (the header tuple + the version lineage + a Change-history table + the design
386
- * skeleton), carrying the `- **Doc type**:` declaration line (spec §12 · D34) the
387
- * capsule's doc-class discrimination reads (zero filename inference). */
440
+ * (the head tuple + the version lineage + a Change-history table + the design
441
+ * skeleton), carrying the `doc-type:` head key (spec §12 · D34) the capsule's
442
+ * doc-class discrimination reads (zero filename inference). */
388
443
  const conformingSpec = (repoRoot: string, name = "s1-design.md"): string => {
389
444
  const file = path.join(repoRoot, "docs", "kairos", "specs", name);
390
445
  mkdirSync(path.dirname(file), { recursive: true });
391
446
  writeFileSync(
392
447
  file,
393
448
  [
394
- "# Test Spec",
395
- "- **Version**: v1.0 · 2026-10-09",
396
- "- **Status**: Draft",
397
- "- **Doc type**: phase-spec",
398
- "- **Author**: x",
399
- "- **Parent program**: [x-overall.md v1.0](docs/kairos/specs/x-overall.md)",
400
- "- **Depends on**: P1",
449
+ "---",
450
+ "title: Test Spec",
451
+ "doc-type: phase-spec",
452
+ "version: v1.0",
453
+ "date: 2026-10-09",
454
+ "status: Draft",
455
+ "author: x",
456
+ "parent-program: docs/kairos/specs/x-overall.md",
457
+ "parent-version: v1.0",
458
+ "depends-on: P1",
459
+ "---",
401
460
  "",
402
461
  "## Design",
403
462
  "",
@@ -423,7 +482,7 @@ const conformingSpec = (repoRoot: string, name = "s1-design.md"): string => {
423
482
  ].join("\n"),
424
483
  "utf8",
425
484
  );
426
- // The chain sibling — the `**Parent program**` link resolves into the specs dir.
485
+ // The chain sibling — the `parent-program:` link resolves into the specs dir.
427
486
  const sibling = path.join(repoRoot, "docs", "kairos", "specs", "x-overall.md");
428
487
  mkdirSync(path.dirname(sibling), { recursive: true });
429
488
  writeFileSync(sibling, "# x-overall\n", "utf8");
@@ -568,14 +627,11 @@ describe("parse — the component-value validation + the unknown-flag guard", ()
568
627
  });
569
628
 
570
629
  it("the fix face declares NO branch refs — the review judges the live tree (no re-declared range)", () => {
571
- // fix --type branch parses with --plan + --findings alone (no base/head)
630
+ // fix --type branch parses with --plan + --reviews alone (no base/head)
572
631
  const fix = nodeOf("fix");
573
- gate.parse(
574
- ["fix", "--type", "branch", "--plan", "p.md", "--findings", "branch-review-x.json"],
575
- {
576
- from: "user",
577
- },
578
- );
632
+ gate.parse(["fix", "--type", "branch", "--plan", "p.md", "--reviews", "branch-review-x.json"], {
633
+ from: "user",
634
+ });
579
635
  expect((fix.opts() as Record<string, unknown>).base).toBeUndefined();
580
636
  expect((fix.opts() as Record<string, unknown>).head).toBeUndefined();
581
637
  // re-declaring the range on the fix CLI is rejected — the unknown-option
@@ -787,7 +843,7 @@ describe("parse — the component-value validation + the unknown-flag guard", ()
787
843
  }
788
844
  });
789
845
 
790
- it("a pre-verb --dry-run dispatches through the program scope — the flag merges into the run (exit 0)", async () => {
846
+ it("a pre-verb --dry-run reaches the program scope — the flag merges into the run as the read-only preview (exit 0)", async () => {
791
847
  const { command, io, repoRoot, cleanup } = fixture();
792
848
  try {
793
849
  gitInit(repoRoot);
@@ -799,14 +855,12 @@ describe("parse — the component-value validation + the unknown-flag guard", ()
799
855
  "1",
800
856
  "--plan",
801
857
  plan,
802
- "--root",
803
- repoRoot,
804
858
  ]);
805
859
  expect(code).toBe(0);
806
- expect(io.stdoutText).toContain("status: APPROVED");
807
- expect(
808
- existsSync(path.join(repoRoot, ".kairos", "cdd", "p3", "tasks-1-implement.json")),
809
- ).toBe(true);
860
+ // the merged program-scope flag drives the preview — the next step forecast
861
+ // with zero repo writes (the retired synthetic bookkeeping is gone)
862
+ expect(io.stdoutText.startsWith("cdd implement: preview (no repo changes)\n")).toBe(true);
863
+ expect(existsSync(path.join(repoRoot, ".kairos"))).toBe(false);
810
864
  } finally {
811
865
  cleanup();
812
866
  }
@@ -913,7 +967,9 @@ describe("the help/--help display face — the per-command render", () => {
913
967
  expect(io.stdoutText).toContain("Usage: cdd implement [options]");
914
968
  expect(io.stdoutText).toContain("--tasks <n|n,n,…>");
915
969
  expect(io.stdoutText).toContain("--plan <path>");
916
- expect(io.stdoutText).toContain("--root <path>");
970
+ // `--root` is retired (T2 · §2.5 — the deliberate command-declaration byte
971
+ // break): the help face no longer carries the option.
972
+ expect(io.stdoutText).not.toContain("--root <path>");
917
973
  expect(io.stdoutText).toContain("the task ids of the wave group (comma-separated)");
918
974
  expect(io.stdoutText).toContain("(required)");
919
975
  expect(io.stdoutText).toContain("run the task implement phase");
@@ -950,10 +1006,10 @@ describe("the help/--help display face — the per-command render", () => {
950
1006
  try {
951
1007
  const code = await command.runArgv(["fix", "--help"]);
952
1008
  expect(code).toBe(0);
953
- expect(io.stdoutText).toContain("--findings <path>");
1009
+ expect(io.stdoutText).toContain("--reviews <path>");
954
1010
  expect(io.stdoutText).toContain("the source review handoff JSON path");
955
1011
  expect(io.stdoutText).toContain(
956
- "cdd fix --type wave --tasks 1 --findings tasks-1-review-1.json",
1012
+ "cdd fix --type wave --tasks 1 --reviews tasks-1-review-1.json",
957
1013
  );
958
1014
  } finally {
959
1015
  cleanup();
@@ -1044,7 +1100,8 @@ describe("the help/--help display face — the per-command render", () => {
1044
1100
  }
1045
1101
  // the tail note rides the commander afterAll surface — one line per help
1046
1102
  // face, listing --dry-run ALONE (the -h/--help redundant column unwritten)
1047
- const legend = /program flags \(accepted at any position\): --dry-run/g;
1103
+ const legend =
1104
+ /program flags \(accepted at any position\): --dry-run \(implement\/review\/fix only\)/g;
1048
1105
  expect(io.stdoutText.match(legend) ?? []).toHaveLength(7);
1049
1106
  expect(io.stdoutText).not.toContain("· --help / -h");
1050
1107
  } finally {
@@ -1083,7 +1140,9 @@ describe("the T4 commander-native help acceptance — the projected help face (
1083
1140
  // The program-flag tail note: --dry-run listed ALONE — the -h/--help
1084
1141
  // redundant column is not written (the built-in helpOption faces Options).
1085
1142
  const footer = io.stdoutText.split("\n").find((line) => line.startsWith("program flags"));
1086
- expect(footer).toBe("program flags (accepted at any position): --dry-run");
1143
+ expect(footer).toBe(
1144
+ "program flags (accepted at any position): --dry-run (implement/review/fix only)",
1145
+ );
1087
1146
  expect(footer).not.toContain("--help");
1088
1147
  expect(footer).not.toContain("-h");
1089
1148
  } finally {
@@ -1108,7 +1167,8 @@ describe("the T4 commander-native help acceptance — the projected help face (
1108
1167
  // declared keys (the registration order never a sorted/derived one).
1109
1168
  expect(help.indexOf("--type")).toBeLessThan(help.indexOf("--tasks"));
1110
1169
  expect(help.indexOf("--plan")).toBeLessThan(help.indexOf("--spec"));
1111
- expect(help.indexOf("--root")).toBeLessThan(help.indexOf("--dry-run"));
1170
+ // `--root` is retired (T2) — it no longer appears on the review node's help.
1171
+ expect(help).not.toContain("--root");
1112
1172
  } finally {
1113
1173
  cleanup();
1114
1174
  }
@@ -1293,25 +1353,17 @@ describe("the error-path face — commander's native suggestion bytes (T5 re-pin
1293
1353
  });
1294
1354
 
1295
1355
  // ---------------------------------------------------------------------------
1296
- // the work commands — the lifecycle/capsule/ledger composition (dry-run E2E)
1356
+ // the work commands — the lifecycle/capsule/ledger composition (the real run
1357
+ // with a hermetic injected dispatch; the retired `--dry-run` synthetic approval)
1297
1358
  // ---------------------------------------------------------------------------
1298
1359
 
1299
- describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", () => {
1360
+ describe("the work commands run the lifecycle/capsule/ledger — injected-dispatch E2E", () => {
1300
1361
  it("implement — one dispatch, the capsule face, the ledger record + the rendered brief", async () => {
1301
- const { command, io, repoRoot, cleanup } = fixture();
1362
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1302
1363
  try {
1303
1364
  gitInit(repoRoot);
1304
1365
  const plan = planFor(repoRoot);
1305
- const code = await command.runArgv([
1306
- "implement",
1307
- "--tasks",
1308
- "1",
1309
- "--plan",
1310
- plan,
1311
- "--dry-run",
1312
- "--root",
1313
- repoRoot,
1314
- ]);
1366
+ const code = await command.runArgv(["implement", "--tasks", "1", "--plan", plan]);
1315
1367
  expect(code).toBe(0);
1316
1368
  expect(io.stdoutText).toContain("status: APPROVED · blocker: 0 · handoff: ");
1317
1369
  expect(io.stdoutText).toContain(`next: review --type wave --tasks 1`);
@@ -1329,32 +1381,21 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1329
1381
  });
1330
1382
 
1331
1383
  it("every wave-face dispatch re-extracts the brief from the CURRENT plan — the complete plan mirror (task + Constraints), never an exists→reuse copy (§4.1/§5)", async () => {
1332
- const { command, io, repoRoot, cleanup } = fixture();
1384
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1333
1385
  try {
1334
1386
  gitInit(repoRoot);
1335
1387
  const plan = planFor(repoRoot);
1336
1388
  const briefPath = path.join(repoRoot, ".kairos", "cdd", "p3", "tasks-1-brief.md");
1337
- expect(
1338
- await command.runArgv([
1339
- "implement",
1340
- "--tasks",
1341
- "1",
1342
- "--plan",
1343
- plan,
1344
- "--dry-run",
1345
- "--root",
1346
- repoRoot,
1347
- ]),
1348
- ).toBe(0);
1389
+ expect(await command.runArgv(["implement", "--tasks", "1", "--plan", plan])).toBe(0);
1349
1390
  const firstBrief = readFileSync(briefPath, "utf8");
1350
1391
  // the complete plan mirror — the wave's task section AND the plan's
1351
1392
  // `## Constraints` section (both faces of the mirror, not the task block alone)
1352
1393
  expect(firstBrief).toContain("### Task 1:");
1353
1394
  expect(firstBrief).toContain("## Constraints");
1354
1395
  expect(firstBrief).toContain("- delta");
1355
- // The plan's Constraints section moves between dispatches (the Plan Sole Writer
1356
- // amends mid-run): the review dispatch re-extracts the brief from the CURRENT
1357
- // plan — no "exists → leave it" reuse.
1396
+ // The plan's Constraints section moves between dispatches (the plan write
1397
+ // authority amends mid-run): the review dispatch re-extracts the brief from the
1398
+ // CURRENT plan — no "exists → leave it" reuse.
1358
1399
  writeFileSync(
1359
1400
  plan,
1360
1401
  readFileSync(plan, "utf8").replace("- delta", "- delta (amended)"),
@@ -1362,18 +1403,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1362
1403
  );
1363
1404
  io.stdoutText = "";
1364
1405
  expect(
1365
- await command.runArgv([
1366
- "review",
1367
- "--type",
1368
- "wave",
1369
- "--tasks",
1370
- "1",
1371
- "--plan",
1372
- plan,
1373
- "--dry-run",
1374
- "--root",
1375
- repoRoot,
1376
- ]),
1406
+ await command.runArgv(["review", "--type", "wave", "--tasks", "1", "--plan", plan]),
1377
1407
  ).toBe(0);
1378
1408
  const secondBrief = readFileSync(briefPath, "utf8");
1379
1409
  // the mirrored Constraints reflect the CURRENT plan (fresh-extracted at the
@@ -1387,7 +1417,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1387
1417
  });
1388
1418
 
1389
1419
  it("implement — strict-wave dispatch: one derived wave per invocation (the C5 closure advances the wave)", async () => {
1390
- const { command, io, repoRoot, cleanup } = fixture();
1420
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1391
1421
  try {
1392
1422
  gitInit(repoRoot);
1393
1423
  const plan = planFor(repoRoot, 2);
@@ -1395,44 +1425,13 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1395
1425
  // NOT close it (implement rounds are never a closure — v1.20 closedWaves), so the
1396
1426
  // wave advances only through the review's C5 closure: review 1 must land before
1397
1427
  // task 2 becomes dispatchable.
1398
- expect(
1399
- await command.runArgv([
1400
- "implement",
1401
- "--tasks",
1402
- "1",
1403
- "--plan",
1404
- plan,
1405
- "--dry-run",
1406
- "--root",
1407
- repoRoot,
1408
- ]),
1409
- ).toBe(0);
1428
+ expect(await command.runArgv(["implement", "--tasks", "1", "--plan", plan])).toBe(0);
1410
1429
  io.stdoutText = "";
1411
1430
  expect(
1412
- await command.runArgv([
1413
- "review",
1414
- "--type",
1415
- "wave",
1416
- "--tasks",
1417
- "1",
1418
- "--plan",
1419
- plan,
1420
- "--dry-run",
1421
- "--root",
1422
- repoRoot,
1423
- ]),
1431
+ await command.runArgv(["review", "--type", "wave", "--tasks", "1", "--plan", plan]),
1424
1432
  ).toBe(0);
1425
1433
  io.stdoutText = "";
1426
- const code = await command.runArgv([
1427
- "implement",
1428
- "--tasks",
1429
- "2",
1430
- "--plan",
1431
- plan,
1432
- "--dry-run",
1433
- "--root",
1434
- repoRoot,
1435
- ]);
1434
+ const code = await command.runArgv(["implement", "--tasks", "2", "--plan", plan]);
1436
1435
  expect(code).toBe(0);
1437
1436
  const workspace = path.join(repoRoot, ".kairos", "cdd", "p3");
1438
1437
  const progress = readJson<{ waves: unknown[] }>(path.join(workspace, "progress.json"));
@@ -1443,7 +1442,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1443
1442
  expect(progress.waves).toContainEqual({
1444
1443
  wave: "1",
1445
1444
  rounds: { implement: [1], review: [1] },
1446
- reviewedRevision: briefRevision(plan, "1"),
1445
+ reviewedRevision: briefRevision(repoRoot, plan, "1"),
1447
1446
  });
1448
1447
  expect(progress.waves).toContainEqual({ wave: "2", rounds: { implement: [1] } });
1449
1448
  // the invocation's single stdout face — only the LAST step's capsule
@@ -1451,40 +1450,25 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1451
1450
  expect(existsSync(path.join(workspace, "tasks-2-implement.json"))).toBe(true);
1452
1451
  // the strict-wave gate (T24): a `--tasks` splitting the derived wave BLOCKs
1453
1452
  io.stderrText = "";
1454
- const split = await command.runArgv([
1455
- "implement",
1456
- "--tasks",
1457
- "1,2",
1458
- "--plan",
1459
- plan,
1460
- "--dry-run",
1461
- "--root",
1462
- repoRoot,
1463
- ]);
1453
+ const split = await command.runArgv(["implement", "--tasks", "1,2", "--plan", plan]);
1464
1454
  expect(split).toBe(1);
1465
1455
  expect(io.stderrText).toContain("derived wave");
1456
+ // T18 (§2.13) — the graph title's embedded plan path is repoRoot-relative
1457
+ // (the argv plan is relativized before it reaches the `graph:` line; the
1458
+ // absolute argv form never renders).
1459
+ expect(io.stderrText).toContain("graph: docs/kairos/plans/p3.md");
1460
+ expect(io.stderrText).not.toContain(`graph: ${repoRoot}`);
1466
1461
  } finally {
1467
1462
  cleanup();
1468
1463
  }
1469
1464
  });
1470
1465
 
1471
1466
  it("review — the phase derives from the ledger (implement then review), a clean review closes", async () => {
1472
- const { command, io, repoRoot, cleanup } = fixture();
1467
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1473
1468
  try {
1474
1469
  gitInit(repoRoot);
1475
1470
  const plan = planFor(repoRoot);
1476
- expect(
1477
- await command.runArgv([
1478
- "implement",
1479
- "--tasks",
1480
- "1",
1481
- "--plan",
1482
- plan,
1483
- "--dry-run",
1484
- "--root",
1485
- repoRoot,
1486
- ]),
1487
- ).toBe(0);
1471
+ expect(await command.runArgv(["implement", "--tasks", "1", "--plan", plan])).toBe(0);
1488
1472
  io.stdoutText = "";
1489
1473
  const code = await command.runArgv([
1490
1474
  "review",
@@ -1494,9 +1478,6 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1494
1478
  "1",
1495
1479
  "--plan",
1496
1480
  plan,
1497
- "--dry-run",
1498
- "--root",
1499
- repoRoot,
1500
1481
  ]);
1501
1482
  expect(code).toBe(0);
1502
1483
  expect(io.stdoutText).toContain("status: APPROVED · blocker: 0 · handoff: ");
@@ -1513,7 +1494,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1513
1494
 
1514
1495
  it("review with findings — the fix-route next: line carries the readback suffix", async () => {
1515
1496
  const { command, io, repoRoot, cleanup } = fixture({
1516
- dispatch: (frame: OpenFrame) =>
1497
+ dispatch: async (frame: OpenFrame) =>
1517
1498
  frame.phase === "review"
1518
1499
  ? {
1519
1500
  status: "CHANGES_REQUESTED",
@@ -1524,18 +1505,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1524
1505
  try {
1525
1506
  gitInit(repoRoot);
1526
1507
  const plan = planFor(repoRoot);
1527
- expect(
1528
- await command.runArgv([
1529
- "implement",
1530
- "--tasks",
1531
- "1",
1532
- "--plan",
1533
- plan,
1534
- "--dry-run",
1535
- "--root",
1536
- repoRoot,
1537
- ]),
1538
- ).toBe(0);
1508
+ expect(await command.runArgv(["implement", "--tasks", "1", "--plan", plan])).toBe(0);
1539
1509
  io.stdoutText = "";
1540
1510
  const code = await command.runArgv([
1541
1511
  "review",
@@ -1545,9 +1515,6 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1545
1515
  "1",
1546
1516
  "--plan",
1547
1517
  plan,
1548
- "--dry-run",
1549
- "--root",
1550
- repoRoot,
1551
1518
  ]);
1552
1519
  expect(code).toBe(0);
1553
1520
  // the review's findings route the one-way fix hop — the capsule next: line
@@ -1555,8 +1522,9 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1555
1522
  // readback suffix (the cli face checkable)
1556
1523
  expect(io.stdoutText).toContain("status: CHANGES_REQUESTED · blocker: 1 · handoff: ");
1557
1524
  const workspace = path.join(repoRoot, ".kairos", "cdd", "p3");
1525
+ // D47 — the next: literal's embedded paths are repoRoot-relative (the ONE shape).
1558
1526
  expect(io.stdoutText).toContain(
1559
- `next: fix --type wave --tasks 1 --plan ${plan} --findings ${path.join(workspace, "tasks-1-review-1.json")} ${FIX_READBACK_SUFFIX}`,
1527
+ `next: fix --type wave --tasks 1 --plan ${path.relative(repoRoot, plan)} --reviews ${path.relative(repoRoot, path.join(workspace, "tasks-1-review-1.json"))} ${FIX_READBACK_SUFFIX}`,
1560
1528
  );
1561
1529
  } finally {
1562
1530
  cleanup();
@@ -1564,7 +1532,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1564
1532
  });
1565
1533
 
1566
1534
  it("fix — the source review's blocker findings drive the re-review next (C5-1)", async () => {
1567
- const { command, io, repoRoot, cleanup } = fixture();
1535
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1568
1536
  try {
1569
1537
  gitInit(repoRoot);
1570
1538
  const plan = planFor(repoRoot);
@@ -1583,18 +1551,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1583
1551
  },
1584
1552
  );
1585
1553
  ledger.recordRound(1, "review");
1586
- const code = await command.runArgv([
1587
- "fix",
1588
- "--type",
1589
- "wave",
1590
- "--tasks",
1591
- "1",
1592
- "--plan",
1593
- plan,
1594
- "--dry-run",
1595
- "--root",
1596
- repoRoot,
1597
- ]);
1554
+ const code = await command.runArgv(["fix", "--type", "wave", "--tasks", "1", "--plan", plan]);
1598
1555
  expect(code).toBe(0);
1599
1556
  expect(io.stdoutText).toContain("status: APPROVED · blocker: 0 · handoff: ");
1600
1557
  expect(io.stdoutText).toContain(`next: review --type wave --tasks 1`);
@@ -1606,14 +1563,14 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1606
1563
 
1607
1564
  it("fix — the branch re-review next: carries the workspace --plan and re-dispatches through the runtime gate (find #8/#9)", async () => {
1608
1565
  const { command, io, repoRoot, cleanup } = fixture({
1609
- dispatch: (frame: OpenFrame) =>
1566
+ dispatch: async (frame: OpenFrame) =>
1610
1567
  frame.phase === "fix" ? { status: "APPROVED" } : { status: "APPROVED", findings: [] },
1611
1568
  });
1612
1569
  try {
1613
1570
  gitInit(repoRoot);
1614
1571
  const plan = conformingPlan(repoRoot);
1615
1572
  // Seed the branch line: a blocker branch-review round (the fix's C5-1 input)
1616
- // whose handoff carries the reviewed findings (the fix's --findings single
1573
+ // whose handoff carries the reviewed findings (the fix's --reviews single
1617
1574
  // carrier).
1618
1575
  // find #9 — the branch line's workspace is the plan-slug (the fix dispatch's
1619
1576
  // --plan); the handoff file is the spine name `branch-review-{round}.json`.
@@ -1630,35 +1587,26 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1630
1587
  // find #9 — the line key is the stable "branch" (round accumulates across
1631
1588
  // re-reviews; the old range-short key reset to 1 on every head move).
1632
1589
  ledger.recordRound("branch", "branch-review");
1633
- const findingsPath = workspace.resolve("branch-review-1.json");
1590
+ const reviewsPath = workspace.resolve("branch-review-1.json");
1634
1591
  const code = await command.runArgv([
1635
1592
  "fix",
1636
1593
  "--type",
1637
1594
  "branch",
1638
1595
  "--plan",
1639
1596
  plan,
1640
- "--findings",
1641
- findingsPath,
1642
- "--dry-run",
1643
- "--root",
1644
- repoRoot,
1597
+ "--reviews",
1598
+ reviewsPath,
1645
1599
  ]);
1646
1600
  expect(code).toBe(0);
1647
1601
  // the re-review literal carries the workspace --plan only — the review judges
1648
- // the live tree (the scope anchor BASE_BRANCH is engine-injected at dispatch)
1649
- expect(io.stdoutText).toContain(`next: review --type branch --plan ${plan}`);
1602
+ // the live tree (the scope anchor BASE_BRANCH is engine-injected at dispatch);
1603
+ // D47 — the embedded path is repoRoot-relative
1604
+ expect(io.stdoutText).toContain(
1605
+ `next: review --type branch --plan ${path.relative(repoRoot, plan)}`,
1606
+ );
1650
1607
  // the runtime gate, not parse-only: re-feeding the literal's argv through the CLI
1651
1608
  // dispatches a real branch review — exit 0, never a missing-refs refusal
1652
- const reExit = await command.runArgv([
1653
- "review",
1654
- "--type",
1655
- "branch",
1656
- "--plan",
1657
- plan,
1658
- "--dry-run",
1659
- "--root",
1660
- repoRoot,
1661
- ]);
1609
+ const reExit = await command.runArgv(["review", "--type", "branch", "--plan", plan]);
1662
1610
  expect(reExit).toBe(0);
1663
1611
  } finally {
1664
1612
  cleanup();
@@ -1666,20 +1614,11 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1666
1614
  });
1667
1615
 
1668
1616
  it("review --type branch — the live-tree branch face", async () => {
1669
- const { command, io, repoRoot, cleanup } = fixture();
1617
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1670
1618
  try {
1671
1619
  gitInit(repoRoot);
1672
1620
  const plan = conformingPlan(repoRoot);
1673
- const code = await command.runArgv([
1674
- "review",
1675
- "--type",
1676
- "branch",
1677
- "--plan",
1678
- plan,
1679
- "--dry-run",
1680
- "--root",
1681
- repoRoot,
1682
- ]);
1621
+ const code = await command.runArgv(["review", "--type", "branch", "--plan", plan]);
1683
1622
  expect(code).toBe(0);
1684
1623
  expect(io.stdoutText).toContain("status: APPROVED · blocker: 0 ·");
1685
1624
  // T3 deliberate pin break: the branch closure routes the cdd-close ref
@@ -1695,14 +1634,15 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1695
1634
  });
1696
1635
 
1697
1636
  it("review --type branch — the CLI injects the base artifact's branch as BASE_BRANCH (the scope anchor value source)", async () => {
1698
- const sync = new FakeSync();
1637
+ const sync = new StubRunner();
1699
1638
  sync.stdout = "status: APPROVED\n";
1700
1639
  const { command, repoRoot, cleanup } = fixture({ sync });
1701
1640
  try {
1702
1641
  gitInit(repoRoot);
1703
1642
  const plan = conformingPlan(repoRoot);
1704
1643
  // the base artifact the CLI reads (the same `base set` write-through source);
1705
- // the leaf carries no --root — the fixture's injected repoRoot is the root.
1644
+ // the leaf carries no basis flag — the engine resolves the repo root from the
1645
+ // fixture's working directory (T2 · §2.12).
1706
1646
  expect(
1707
1647
  await command.runArgv([
1708
1648
  "base",
@@ -1715,22 +1655,14 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1715
1655
  "plan-field",
1716
1656
  ]),
1717
1657
  ).toBe(0);
1718
- // A REAL branch-review dispatch (not --dry-run — the dry-run synthetic approval
1719
- // never reaches the lifecycle). The host is injected ambiently (the CLI's
1720
- // production dispatch reads process.env), so mark it and restore it.
1658
+ // A REAL branch-review dispatch (the production HarnessDispatch — no injected
1659
+ // seam). The host is injected ambiently (the CLI's production dispatch reads
1660
+ // process.env), so mark it and restore it.
1721
1661
  const saved = process.env.CLAUDE_CODE_SESSION_ID;
1722
1662
  process.env.CLAUDE_CODE_SESSION_ID = "s";
1723
1663
  let code: number;
1724
1664
  try {
1725
- code = await command.runArgv([
1726
- "review",
1727
- "--type",
1728
- "branch",
1729
- "--plan",
1730
- plan,
1731
- "--root",
1732
- repoRoot,
1733
- ]);
1665
+ code = await command.runArgv(["review", "--type", "branch", "--plan", plan]);
1734
1666
  } finally {
1735
1667
  if (saved === undefined) delete process.env.CLAUDE_CODE_SESSION_ID;
1736
1668
  else process.env.CLAUDE_CODE_SESSION_ID = saved;
@@ -1748,7 +1680,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1748
1680
  });
1749
1681
 
1750
1682
  it("BASE_BRANCH injection — the wave/branch tree-review faces carry the anchor; the spec/plan doc faces never do (§3.2)", async () => {
1751
- const sync = new FakeSync();
1683
+ const sync = new StubRunner();
1752
1684
  sync.stdout = "status: APPROVED\n";
1753
1685
  const { command, repoRoot, cleanup } = fixture({ sync });
1754
1686
  try {
@@ -1782,13 +1714,13 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1782
1714
  artifacts: {},
1783
1715
  },
1784
1716
  );
1785
- // A REAL dispatch (not --dry-run — the synthetic approval never reaches the
1786
- // lifecycle). The host is injected ambiently (the CLI's production dispatch
1787
- // reads process.env), so mark it and restore it.
1717
+ // A REAL dispatch (the production HarnessDispatch — no injected seam). The
1718
+ // host is injected ambiently (the CLI's production dispatch reads
1719
+ // process.env), so mark it and restore it.
1788
1720
  const saved = process.env.CLAUDE_CODE_SESSION_ID;
1789
1721
  process.env.CLAUDE_CODE_SESSION_ID = "s";
1790
1722
  const promptOf = async (argv: readonly string[]): Promise<string> => {
1791
- await command.runArgv([...argv, "--root", repoRoot]);
1723
+ await command.runArgv([...argv]);
1792
1724
  const call = sync.calls[sync.calls.length - 1]!;
1793
1725
  return call.args[call.args.length - 1];
1794
1726
  };
@@ -1809,35 +1741,144 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1809
1741
  path.join(repoRoot, "docs", "kairos", "specs", "s1-design.md"),
1810
1742
  ]);
1811
1743
  expect(spec).not.toContain("BASE_BRANCH");
1744
+ // the spec review's judged doc IS the spec — the kind-named anchor carries it
1745
+ expect(spec).toContain("- `INPUT_SPEC`: docs/kairos/specs/s1-design.md");
1812
1746
  const planReview = await promptOf(["review", "--type", "plan", "--plan", plan]);
1813
1747
  expect(planReview).not.toContain("BASE_BRANCH");
1748
+ // the plan-review round context carries the plan's `spec:` anchor
1749
+ // (INPUT_SPEC) so the reviewer judges the plan against its design spec
1750
+ expect(planReview).toContain("- `INPUT_SPEC`: docs/kairos/specs/p3-design.md");
1751
+ } finally {
1752
+ if (saved === undefined) delete process.env.CLAUDE_CODE_SESSION_ID;
1753
+ else process.env.CLAUDE_CODE_SESSION_ID = saved;
1754
+ }
1755
+ } finally {
1756
+ cleanup();
1757
+ }
1758
+ });
1759
+
1760
+ it("D46 — INPUT_SPEC is rebased to a repoRoot-relative token from the plan's plan-dir-relative `spec:` scalar", async () => {
1761
+ const sync = new StubRunner();
1762
+ sync.stdout = "status: APPROVED\n";
1763
+ const { command, repoRoot, cleanup } = fixture({ sync });
1764
+ try {
1765
+ gitInit(repoRoot);
1766
+ // The live plan header form: the `spec:` front-matter scalar may carry a
1767
+ // plan-dir-relative value (`../specs/X.md`, relative to the plan's OWN dir) —
1768
+ // the actual form every in-repo plan P6+ uses. The reviewer is spawned at
1769
+ // cwd = repoRoot, so the raw plan-dir-relative form would resolve OUTSIDE
1770
+ // the repo; the scene rebases it to the repoRoot-relative token (the one
1771
+ // basis every round-context path token speaks).
1772
+ const plan = conformingPlan(repoRoot, "../specs/p3-design.md");
1773
+ const saved = process.env.CLAUDE_CODE_SESSION_ID;
1774
+ process.env.CLAUDE_CODE_SESSION_ID = "s";
1775
+ try {
1776
+ await command.runArgv(["review", "--type", "plan", "--plan", plan]);
1777
+ } finally {
1778
+ if (saved === undefined) delete process.env.CLAUDE_CODE_SESSION_ID;
1779
+ else process.env.CLAUDE_CODE_SESSION_ID = saved;
1780
+ }
1781
+ const prompt =
1782
+ sync.calls[sync.calls.length - 1]!.args[sync.calls[sync.calls.length - 1]!.args.length - 1];
1783
+ // The token is the repoRoot-relative path (never the raw `../specs/p3-design.md`)
1784
+ // and it points at an existing file the reviewer can open from cwd = repoRoot.
1785
+ expect(prompt).toContain("- `INPUT_SPEC`: docs/kairos/specs/p3-design.md");
1786
+ expect(prompt).not.toContain("- `INPUT_SPEC`: ../specs/p3-design.md");
1787
+ expect(existsSync(path.join(repoRoot, "docs/kairos/specs/p3-design.md"))).toBe(true);
1788
+ } finally {
1789
+ cleanup();
1790
+ }
1791
+ });
1792
+
1793
+ it("T4 — the round-context prompt's path tokens are ALL repoRoot-relative (one basis, zero absolute)", async () => {
1794
+ // §2.7 — every path token injected into the child speaks ONE basis (repoRoot-
1795
+ // relative): the child is spawned at cwd = repoRoot (T2), so a relative token
1796
+ // resolves identically for every token, input or output alike. Across the modes
1797
+ // the 8-token set is WORKSPACE_DIR · INPUT_PLAN · INPUT_SPEC · INPUT_REVIEWS ·
1798
+ // INPUT_WAVE_BRIEF · OUTPUT_REPORT · OUTPUT_EVIDENCE · OUTPUT_HANDOFF (the
1799
+ // non-path tokens excluded); each mode emits its own subset. This pin drives an
1800
+ // implement dispatch (the wave line's work face) and asserts EVERY emitted path
1801
+ // token is relative — no absolute prefix, no `..` escape.
1802
+ const sync = new StubRunner();
1803
+ sync.stdout = "status: APPROVED\n";
1804
+ const { command, repoRoot, cleanup } = fixture({ sync });
1805
+ try {
1806
+ gitInit(repoRoot);
1807
+ const plan = conformingPlan(repoRoot);
1808
+ const saved = process.env.CLAUDE_CODE_SESSION_ID;
1809
+ process.env.CLAUDE_CODE_SESSION_ID = "s";
1810
+ try {
1811
+ await command.runArgv(["implement", "--tasks", "1", "--plan", plan]);
1814
1812
  } finally {
1815
1813
  if (saved === undefined) delete process.env.CLAUDE_CODE_SESSION_ID;
1816
1814
  else process.env.CLAUDE_CODE_SESSION_ID = saved;
1817
1815
  }
1816
+ const call = sync.calls[sync.calls.length - 1]!;
1817
+ const prompt = call.args[call.args.length - 1];
1818
+ // The child is spawned at the repo root — the load-bearing fact a relative
1819
+ // token relies on.
1820
+ expect(call.cwd).toBe(repoRoot);
1821
+ // Every emitted path token is repoRoot-relative: no absolute prefix, no escape.
1822
+ const PATH_TOKENS = [
1823
+ "WORKSPACE_DIR",
1824
+ "INPUT_PLAN",
1825
+ "INPUT_SPEC",
1826
+ "INPUT_REVIEWS",
1827
+ "INPUT_WAVE_BRIEF",
1828
+ "OUTPUT_REPORT",
1829
+ "OUTPUT_EVIDENCE",
1830
+ "OUTPUT_HANDOFF",
1831
+ ];
1832
+ const emitted = [...prompt.matchAll(/^- `([A-Z0-9_]+)`: (.+)$/gm)].flatMap((m) =>
1833
+ PATH_TOKENS.includes(m[1]!) ? [[m[1]!, m[2]!.trim()]] : [],
1834
+ );
1835
+ // The implement-mode work face carries its path tokens (the wave brief + the
1836
+ // prescribed write paths + the workspace dir) — never an empty assertion.
1837
+ expect(emitted.length).toBeGreaterThanOrEqual(5);
1838
+ for (const [token, value] of emitted) {
1839
+ expect(path.isAbsolute(value), `${token} is repoRoot-relative`).toBe(false);
1840
+ expect(value.startsWith(".."), `${token} carries no parent-escape prefix`).toBe(false);
1841
+ }
1842
+ // The absolute repo root never appears on any path-token line.
1843
+ expect(prompt).not.toMatch(/^- `[A-Z0-9_]+`: \/.*repoRoot/m);
1844
+ } finally {
1845
+ cleanup();
1846
+ }
1847
+ });
1848
+
1849
+ it("T3 — an out-of-repo path is accepted with a stderr warning (shape judged, never location)", async () => {
1850
+ // §2.10 — a `..`-carrying relativized value lies outside the repo; the engine
1851
+ // still reads it (the shape is what is judged), but the fact rides the stderr
1852
+ // CDD_WARN channel so the caller is not surprised.
1853
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1854
+ try {
1855
+ gitInit(repoRoot);
1856
+ const outside = realpathSync(mkdtempSync(path.join(tmpdir(), "cli-outside-")));
1857
+ const plan = conformingPlan(outside);
1858
+ try {
1859
+ // a plan OUTSIDE the fixture repo (the absolute path relativizes to `../…`);
1860
+ // the injected dispatch keeps the run hermetic (no child spawn).
1861
+ const code = await command.runArgv(["implement", "--tasks", "1", "--plan", plan]);
1862
+ expect(code).toBe(0);
1863
+ expect(io.stderrText).toContain("CDD_WARN:");
1864
+ expect(io.stderrText).toContain("outside the repository");
1865
+ } finally {
1866
+ rmSync(outside, { recursive: true, force: true });
1867
+ }
1818
1868
  } finally {
1819
1869
  cleanup();
1820
1870
  }
1821
1871
  });
1822
1872
 
1823
1873
  it("review --type spec/plan — the doc-path face (the doc-derived workspace slug)", async () => {
1824
- const { command, io, repoRoot, cleanup } = fixture();
1874
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1825
1875
  try {
1826
1876
  gitInit(repoRoot);
1827
- // The declared, contract-clean spec doc — the `- **Doc type**:` header
1828
- // declaration (spec §12 · D34) the capsule's doc-class discrimination reads
1877
+ // The declared, contract-clean spec doc — the `doc-type:` head key
1878
+ // (spec §12 · D34) the capsule's doc-class discrimination reads
1829
1879
  // (zero filename inference).
1830
1880
  const spec = conformingSpec(repoRoot);
1831
- const specCode = await command.runArgv([
1832
- "review",
1833
- "--type",
1834
- "spec",
1835
- "--spec",
1836
- spec,
1837
- "--dry-run",
1838
- "--root",
1839
- repoRoot,
1840
- ]);
1881
+ const specCode = await command.runArgv(["review", "--type", "spec", "--spec", spec]);
1841
1882
  expect(specCode).toBe(0);
1842
1883
  // T3 deliberate pin break: the phase-spec closure routes the cdd-plan ref (PIPELINE_NEXT.phase-spec).
1843
1884
  expect(io.stdoutText).toContain("next: /kairos:cdd-plan");
@@ -1849,16 +1890,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1849
1890
  // header tuple + version lineage + Change-history table + the chain siblings)
1850
1891
  // dispatches its review round.
1851
1892
  const plan = conformingPlan(repoRoot);
1852
- const planCode = await command.runArgv([
1853
- "review",
1854
- "--type",
1855
- "plan",
1856
- "--plan",
1857
- plan,
1858
- "--dry-run",
1859
- "--root",
1860
- repoRoot,
1861
- ]);
1893
+ const planCode = await command.runArgv(["review", "--type", "plan", "--plan", plan]);
1862
1894
  expect(planCode).toBe(0);
1863
1895
  expect(existsSync(path.join(repoRoot, ".kairos", "cdd", "p3", "plan-review-1.json"))).toBe(
1864
1896
  true,
@@ -1872,25 +1904,16 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1872
1904
  const { command, io, repoRoot, cleanup } = fixture();
1873
1905
  try {
1874
1906
  gitInit(repoRoot);
1875
- // A structurally contract-clean plan with its `- **Doc type**:` line stripped:
1907
+ // A structurally contract-clean plan with its `doc-type:` key stripped:
1876
1908
  // the plan face keys the doc-contract target by the DECLARED type alone, never
1877
- // by the command verb — a missing declaration reads null and the seam BLOCKs.
1909
+ // by the command verb — a missing key reads null and the seam BLOCKs.
1878
1910
  const plan = conformingPlan(repoRoot);
1879
- const stripped = readFileSync(plan, "utf8").replace("- **Doc type**: plan\n", "");
1911
+ const stripped = readFileSync(plan, "utf8").replace("doc-type: plan\n", "");
1880
1912
  writeFileSync(plan, stripped, "utf8");
1881
- const code = await command.runArgv([
1882
- "review",
1883
- "--type",
1884
- "plan",
1885
- "--plan",
1886
- plan,
1887
- "--dry-run",
1888
- "--root",
1889
- repoRoot,
1890
- ]);
1913
+ const code = await command.runArgv(["review", "--type", "plan", "--plan", plan]);
1891
1914
  expect(code).toBe(1);
1892
1915
  expect(io.stderrText).toContain("CDD_BLOCKED");
1893
- expect(io.stderrText).toContain("the doc declares no `- **Doc type**:` line");
1916
+ expect(io.stderrText).toContain("the doc declares no `doc-type:` key");
1894
1917
  // no phantom round lands — the BLOCK precedes any child dispatch
1895
1918
  expect(existsSync(path.join(repoRoot, ".kairos", "cdd", "p3", "plan-review-1.json"))).toBe(
1896
1919
  false,
@@ -1901,24 +1924,15 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1901
1924
  });
1902
1925
 
1903
1926
  it("review --type spec of an -overall.md — the overall-spec doc-key face (zero phase-spec misreport)", async () => {
1904
- const { command, io, repoRoot, cleanup } = fixture();
1927
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1905
1928
  try {
1906
1929
  gitInit(repoRoot);
1907
1930
  const overall = conformingOverall(repoRoot);
1908
- const overallCode = await command.runArgv([
1909
- "review",
1910
- "--type",
1911
- "spec",
1912
- "--spec",
1913
- overall,
1914
- "--dry-run",
1915
- "--root",
1916
- repoRoot,
1917
- ]);
1931
+ const overallCode = await command.runArgv(["review", "--type", "spec", "--spec", overall]);
1918
1932
  expect(overallCode).toBe(0);
1919
1933
  expect(io.stdoutText).toContain("next: done");
1920
1934
  // The overall was judged under the overall-spec key (its declared
1921
- // `- **Doc type**:` line, spec §12 · D34) — a phase-spec misjudge would trip
1935
+ // `doc-type:` key, spec §12 · D34) — a phase-spec misjudge would trip
1922
1936
  // the doc-contract gate: the charter fails the phase-spec face, the pre-flight
1923
1937
  // refuses over CDD_BLOCKED and no round lands. The exit 0 + round +
1924
1938
  // empty-findings carrier pin the zero misreport; the stderr stays free of the
@@ -1933,24 +1947,13 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1933
1947
  });
1934
1948
 
1935
1949
  it("a closed doc line REOPENS on doc-revision drift — the identity-aware line gate (T7)", async () => {
1936
- const { command, io, repoRoot, cleanup } = fixture();
1950
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1937
1951
  try {
1938
1952
  gitInit(repoRoot);
1939
1953
  const plan = conformingPlan(repoRoot);
1940
1954
  // Round 1: the initial clean review closes the doc line AND records the
1941
1955
  // reviewed doc revision (the line's identity — the T7 write-back at bookkeep).
1942
- expect(
1943
- await command.runArgv([
1944
- "review",
1945
- "--type",
1946
- "plan",
1947
- "--plan",
1948
- plan,
1949
- "--dry-run",
1950
- "--root",
1951
- repoRoot,
1952
- ]),
1953
- ).toBe(0);
1956
+ expect(await command.runArgv(["review", "--type", "plan", "--plan", plan])).toBe(0);
1954
1957
  // T3 deliberate pin break: the plan closure routes the cdd-dev ref (PIPELINE_NEXT.plan).
1955
1958
  expect(io.stdoutText).toContain("next: /kairos:cdd-dev");
1956
1959
  // The target doc then DRIFTS (a backfill edits the plan — the pre-T7 flow
@@ -1963,16 +1966,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1963
1966
  );
1964
1967
  writeFileSync(plan, driftedSource, "utf8");
1965
1968
  io.stdoutText = "";
1966
- const reopen = await command.runArgv([
1967
- "review",
1968
- "--type",
1969
- "plan",
1970
- "--plan",
1971
- plan,
1972
- "--dry-run",
1973
- "--root",
1974
- repoRoot,
1975
- ]);
1969
+ const reopen = await command.runArgv(["review", "--type", "plan", "--plan", plan]);
1976
1970
  expect(reopen).toBe(0);
1977
1971
  expect(existsSync(path.join(repoRoot, ".kairos", "cdd", "p3", "plan-review-2.json"))).toBe(
1978
1972
  true,
@@ -1983,37 +1977,17 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
1983
1977
  });
1984
1978
 
1985
1979
  it("an UNCHANGED closed doc line stays blocked — the revision-aware BLOCK message (T7)", async () => {
1986
- const { command, io, repoRoot, cleanup } = fixture();
1980
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
1987
1981
  try {
1988
1982
  gitInit(repoRoot);
1989
1983
  const plan = conformingPlan(repoRoot);
1990
- expect(
1991
- await command.runArgv([
1992
- "review",
1993
- "--type",
1994
- "plan",
1995
- "--plan",
1996
- plan,
1997
- "--dry-run",
1998
- "--root",
1999
- repoRoot,
2000
- ]),
2001
- ).toBe(0);
1984
+ expect(await command.runArgv(["review", "--type", "plan", "--plan", plan])).toBe(0);
2002
1985
  expect(io.stdoutText).toContain("next: /kairos:cdd-dev");
2003
1986
  // The doc did NOT move — the line gate compares the current revision to the
2004
1987
  // reviewed one and BLOCKs with the identity-aware message (the old "no open
2005
1988
  // round" text retires on the doc face).
2006
1989
  io.stderrText = "";
2007
- const unchanged = await command.runArgv([
2008
- "review",
2009
- "--type",
2010
- "plan",
2011
- "--plan",
2012
- plan,
2013
- "--dry-run",
2014
- "--root",
2015
- repoRoot,
2016
- ]);
1990
+ const unchanged = await command.runArgv(["review", "--type", "plan", "--plan", plan]);
2017
1991
  expect(unchanged).toBe(1);
2018
1992
  expect(io.stderrText).toContain("already reviewed at v1.0");
2019
1993
  expect(io.stderrText).toContain("target revision unchanged");
@@ -2050,8 +2024,6 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2050
2024
  "--spec",
2051
2025
  specPath,
2052
2026
  "--dry-run",
2053
- "--root",
2054
- repoRoot,
2055
2027
  ]);
2056
2028
  expect(blocked).toBe(1);
2057
2029
  expect(io.stderrText).toContain("the line holds no open round");
@@ -2067,7 +2039,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2067
2039
 
2068
2040
  it("T8 — after an ABORTED fix the drifted doc re-reviews directly — the doc revision is the gate's primary criterion (judgment order = doc revision first)", async () => {
2069
2041
  const { command, io, repoRoot, cleanup } = fixture({
2070
- dispatch: (frame: OpenFrame) =>
2042
+ dispatch: async (frame: OpenFrame) =>
2071
2043
  frame.phase === "fix"
2072
2044
  ? { status: "BLOCKED" } // the aborted fix — its round never records
2073
2045
  : {
@@ -2081,18 +2053,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2081
2053
  // Review round 1 with blockers — the line awaits its fix (fixes < reviews:
2082
2054
  // the pre-T8 gate read the fix-awaited route and froze the re-review at
2083
2055
  // "the next round is fix" even after the doc moved).
2084
- expect(
2085
- await command.runArgv([
2086
- "review",
2087
- "--type",
2088
- "plan",
2089
- "--plan",
2090
- plan,
2091
- "--dry-run",
2092
- "--root",
2093
- repoRoot,
2094
- ]),
2095
- ).toBe(0);
2056
+ expect(await command.runArgv(["review", "--type", "plan", "--plan", plan])).toBe(0);
2096
2057
  const workspace = path.join(repoRoot, ".kairos", "cdd", "p3");
2097
2058
  expect(existsSync(path.join(workspace, "plan-review-1.json"))).toBe(true);
2098
2059
  // The aborted fix — the pre-T8 stuck path's origin: the fix attempt BLOCKS,
@@ -2100,18 +2061,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2100
2061
  // findings binding the reviewed doc revision.
2101
2062
  io.stdoutText = "";
2102
2063
  io.stderrText = "";
2103
- expect(
2104
- await command.runArgv([
2105
- "fix",
2106
- "--type",
2107
- "plan",
2108
- "--plan",
2109
- plan,
2110
- "--dry-run",
2111
- "--root",
2112
- repoRoot,
2113
- ]),
2114
- ).toBe(1);
2064
+ expect(await command.runArgv(["fix", "--type", "plan", "--plan", plan])).toBe(1);
2115
2065
  // The doc then moves (fix applied · backfill · user decision are the SAME
2116
2066
  // case — the doc revision is the gate's primary criterion): the review runs
2117
2067
  // directly, whatever the fix-awaited round state says, and the old findings
@@ -2123,16 +2073,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2123
2073
  writeFileSync(plan, driftedSource, "utf8");
2124
2074
  io.stderrText = "";
2125
2075
  io.stdoutText = "";
2126
- const reopen = await command.runArgv([
2127
- "review",
2128
- "--type",
2129
- "plan",
2130
- "--plan",
2131
- plan,
2132
- "--dry-run",
2133
- "--root",
2134
- repoRoot,
2135
- ]);
2076
+ const reopen = await command.runArgv(["review", "--type", "plan", "--plan", plan]);
2136
2077
  expect(reopen).toBe(0);
2137
2078
  expect(io.stderrText).not.toContain("cannot dispatch");
2138
2079
  expect(io.stderrText).not.toContain("the next round is fix");
@@ -2154,7 +2095,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2154
2095
  });
2155
2096
 
2156
2097
  it("dogfood §3.7 — the same doc via an ABSOLUTE then a RELATIVE argv path lands ONE ledger line (the doc line keys by its line-type constant, never the argv string)", async () => {
2157
- const { command, io, repoRoot, cleanup } = fixture();
2098
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
2158
2099
  const savedCwd = process.cwd();
2159
2100
  try {
2160
2101
  gitInit(repoRoot);
@@ -2169,9 +2110,6 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2169
2110
  "plan",
2170
2111
  "--plan",
2171
2112
  plan, // the ABSOLUTE argv spelling
2172
- "--dry-run",
2173
- "--root",
2174
- repoRoot,
2175
2113
  ]),
2176
2114
  ).toBe(0);
2177
2115
  expect(io.stdoutText).toContain("next: /kairos:cdd-dev");
@@ -2191,9 +2129,6 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2191
2129
  "plan",
2192
2130
  "--plan",
2193
2131
  relativePlan, // the RELATIVE argv spelling — the same file
2194
- "--dry-run",
2195
- "--root",
2196
- repoRoot,
2197
2132
  ]);
2198
2133
  expect(relative).toBe(0);
2199
2134
  expect(io.stdoutText).toContain("next: /kairos:cdd-dev");
@@ -2215,7 +2150,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2215
2150
 
2216
2151
  it("T8 — an UNCHANGED fix-awaited doc stays rejected — the pending fix is derived (doc same + not APPROVED), never an independent field", async () => {
2217
2152
  const { command, io, repoRoot, cleanup } = fixture({
2218
- dispatch: (frame: OpenFrame) =>
2153
+ dispatch: async (frame: OpenFrame) =>
2219
2154
  frame.phase === "review"
2220
2155
  ? {
2221
2156
  status: "CHANGES_REQUESTED",
@@ -2226,33 +2161,13 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2226
2161
  try {
2227
2162
  gitInit(repoRoot);
2228
2163
  const plan = conformingPlan(repoRoot);
2229
- expect(
2230
- await command.runArgv([
2231
- "review",
2232
- "--type",
2233
- "plan",
2234
- "--plan",
2235
- plan,
2236
- "--dry-run",
2237
- "--root",
2238
- repoRoot,
2239
- ]),
2240
- ).toBe(0);
2164
+ expect(await command.runArgv(["review", "--type", "plan", "--plan", plan])).toBe(0);
2241
2165
  // The SAME doc (no drift) — the repeat review stays REFUSED (Review
2242
2166
  // Convergence anti-spin): the pending fix derives from the doc-same +
2243
2167
  // non-APPROVED face (the review's own fix is still outstanding), and the
2244
2168
  // message names the derived hop.
2245
2169
  io.stderrText = "";
2246
- const repeat = await command.runArgv([
2247
- "review",
2248
- "--type",
2249
- "plan",
2250
- "--plan",
2251
- plan,
2252
- "--dry-run",
2253
- "--root",
2254
- repoRoot,
2255
- ]);
2170
+ const repeat = await command.runArgv(["review", "--type", "plan", "--plan", plan]);
2256
2171
  expect(repeat).toBe(1);
2257
2172
  expect(io.stderrText).toContain("the pending fix applies to the unchanged doc");
2258
2173
  expect(io.stderrText).toContain("— run cdd fix first");
@@ -2266,7 +2181,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2266
2181
 
2267
2182
  it("T8 — a COMPLETED fix on an UNCHANGED doc reopens the review through its C5-1 route — the doc-same face keeps the legacy rounds/routes judgment (the gate and the frame agree)", async () => {
2268
2183
  const { command, io, repoRoot, cleanup } = fixture({
2269
- dispatch: (frame: OpenFrame) =>
2184
+ dispatch: async (frame: OpenFrame) =>
2270
2185
  frame.phase === "fix"
2271
2186
  ? { status: "APPROVED" }
2272
2187
  : {
@@ -2284,44 +2199,13 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2284
2199
  // the review lead. The lifecycle already dispatches this face; the CLI gate
2285
2200
  // must agree (an open gate and a dispatchable frame — the run.ts JSDoc
2286
2201
  // invariant) instead of the revision-aware "amend body/version" rejection.
2287
- expect(
2288
- await command.runArgv([
2289
- "review",
2290
- "--type",
2291
- "plan",
2292
- "--plan",
2293
- plan,
2294
- "--dry-run",
2295
- "--root",
2296
- repoRoot,
2297
- ]),
2298
- ).toBe(0);
2202
+ expect(await command.runArgv(["review", "--type", "plan", "--plan", plan])).toBe(0);
2299
2203
  io.stdoutText = "";
2300
2204
  io.stderrText = "";
2301
- expect(
2302
- await command.runArgv([
2303
- "fix",
2304
- "--type",
2305
- "plan",
2306
- "--plan",
2307
- plan,
2308
- "--dry-run",
2309
- "--root",
2310
- repoRoot,
2311
- ]),
2312
- ).toBe(0);
2205
+ expect(await command.runArgv(["fix", "--type", "plan", "--plan", plan])).toBe(0);
2313
2206
  io.stdoutText = "";
2314
2207
  io.stderrText = "";
2315
- const reopen = await command.runArgv([
2316
- "review",
2317
- "--type",
2318
- "plan",
2319
- "--plan",
2320
- plan,
2321
- "--dry-run",
2322
- "--root",
2323
- repoRoot,
2324
- ]);
2208
+ const reopen = await command.runArgv(["review", "--type", "plan", "--plan", plan]);
2325
2209
  expect(reopen).toBe(0);
2326
2210
  // no revision-aware rejection on the completed-fix face — the delta has moved
2327
2211
  expect(io.stderrText).not.toContain("already reviewed");
@@ -2346,9 +2230,6 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2346
2230
  "1",
2347
2231
  "--plan",
2348
2232
  plan,
2349
- "--dry-run",
2350
- "--root",
2351
- repoRoot,
2352
2233
  ]);
2353
2234
  expect(code).toBe(1);
2354
2235
  expect(io.stderrText).toContain("the open wave is at implement");
@@ -2361,20 +2242,13 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2361
2242
  });
2362
2243
 
2363
2244
  it("a BLOCKED dispatch exits 1 with the capsule (the round outcome rides the face)", async () => {
2364
- const { command, io, repoRoot, cleanup } = fixture({ dispatch: () => ({ status: "BLOCKED" }) });
2245
+ const { command, io, repoRoot, cleanup } = fixture({
2246
+ dispatch: async () => ({ status: "BLOCKED" }),
2247
+ });
2365
2248
  try {
2366
2249
  gitInit(repoRoot);
2367
2250
  const plan = planFor(repoRoot);
2368
- const code = await command.runArgv([
2369
- "implement",
2370
- "--tasks",
2371
- "1",
2372
- "--plan",
2373
- plan,
2374
- "--dry-run",
2375
- "--root",
2376
- repoRoot,
2377
- ]);
2251
+ const code = await command.runArgv(["implement", "--tasks", "1", "--plan", plan]);
2378
2252
  expect(code).toBe(1);
2379
2253
  expect(io.stdoutText).toContain("status: BLOCKED");
2380
2254
  } finally {
@@ -2382,6 +2256,29 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2382
2256
  }
2383
2257
  });
2384
2258
 
2259
+ it("a TIMEOUT dispatch — the failure face: exit 1, NO next: line, and progress's timeoutCount increments (§4.2/§4.3)", async () => {
2260
+ const { command, io, repoRoot, cleanup } = fixture({
2261
+ dispatch: async () => ({ status: "TIMEOUT" }),
2262
+ });
2263
+ try {
2264
+ gitInit(repoRoot);
2265
+ const plan = planFor(repoRoot);
2266
+ const workspace = new Workspace(new WorkspaceRoot(repoRoot, ".kairos/cdd"), "p3").ensure();
2267
+ const ledger = new Ledger(workspace, new ConfigLoader());
2268
+ expect(ledger.counterOf("timeoutCount")).toBe(0);
2269
+ const code = await command.runArgv(["implement", "--tasks", "1", "--plan", plan]);
2270
+ // The failure face — exit 1 with the capsule naming the TIMEOUT status…
2271
+ expect(code).toBe(1);
2272
+ expect(io.stdoutText).toContain("status: TIMEOUT");
2273
+ // …and NO next: line (the frozen failure face — a hung round never auto-retries).
2274
+ expect(io.stdoutText).not.toContain("next:");
2275
+ // §4.2 — the terminated round landed, the counter's only writer fired.
2276
+ expect(ledger.counterOf("timeoutCount")).toBe(1);
2277
+ } finally {
2278
+ cleanup();
2279
+ }
2280
+ });
2281
+
2385
2282
  it("dogfood §2.8 — a rejected fix round with a leftover APPROVED draft renders NO next: line (the verdict is single-sourced; a stale draft is never read back)", async () => {
2386
2283
  // The round-verdict single-source pin: the child's fix write is REJECTED (the
2387
2284
  // round stays BLOCKED and unrecorded), yet a stale APPROVED draft sits on disk
@@ -2389,7 +2286,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2389
2286
  // the self-contradictory `status: BLOCKED · next: done`; the gated round-read
2390
2287
  // (§2.8) returns null for the unrecorded round → no next: line.
2391
2288
  const { command, io, repoRoot, cleanup } = fixture({
2392
- dispatch: () => ({ status: "BLOCKED" }),
2289
+ dispatch: async () => ({ status: "BLOCKED" }),
2393
2290
  });
2394
2291
  try {
2395
2292
  gitInit(repoRoot);
@@ -2416,18 +2313,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2416
2313
  JSON.stringify({ status: "APPROVED", findings: [] }),
2417
2314
  "utf8",
2418
2315
  );
2419
- const code = await command.runArgv([
2420
- "fix",
2421
- "--type",
2422
- "wave",
2423
- "--tasks",
2424
- "1",
2425
- "--plan",
2426
- plan,
2427
- "--dry-run",
2428
- "--root",
2429
- repoRoot,
2430
- ]);
2316
+ const code = await command.runArgv(["fix", "--type", "wave", "--tasks", "1", "--plan", plan]);
2431
2317
  expect(code).toBe(1);
2432
2318
  expect(io.stdoutText).toContain("status: BLOCKED");
2433
2319
  // the verdict single-source face — zero next: line (the unrecorded round holds
@@ -2450,35 +2336,13 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2450
2336
  // review of a subset {1} while the wave sits at {1,2} → the split BLOCK (review is
2451
2337
  // gated like implement — the half-wave review is structurally refused)
2452
2338
  expect(
2453
- await command.runArgv([
2454
- "review",
2455
- "--type",
2456
- "wave",
2457
- "--tasks",
2458
- "1",
2459
- "--plan",
2460
- planPath,
2461
- "--dry-run",
2462
- "--root",
2463
- repoRoot,
2464
- ]),
2339
+ await command.runArgv(["review", "--type", "wave", "--tasks", "1", "--plan", planPath]),
2465
2340
  ).toBe(1);
2466
2341
  expect(io.stderrText).toContain("splits/mismatches the derived wave");
2467
2342
  io.stderrText = "";
2468
2343
  // fix of a subset {2} before its implement → the split BLOCK (fix shares the gate)
2469
2344
  expect(
2470
- await command.runArgv([
2471
- "fix",
2472
- "--type",
2473
- "wave",
2474
- "--tasks",
2475
- "2",
2476
- "--plan",
2477
- planPath,
2478
- "--dry-run",
2479
- "--root",
2480
- repoRoot,
2481
- ]),
2345
+ await command.runArgv(["fix", "--type", "wave", "--tasks", "2", "--plan", planPath]),
2482
2346
  ).toBe(1);
2483
2347
  expect(io.stderrText).toContain("splits/mismatches the derived wave");
2484
2348
  } finally {
@@ -2496,32 +2360,23 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2496
2360
  const workspace = new Workspace(new WorkspaceRoot(repoRoot, ".kairos/cdd"), "two").ensure();
2497
2361
  new Ledger(workspace, new ConfigLoader()).recordRound("1,2", "implement");
2498
2362
  io.stderrText = "";
2499
- // review on the implemented multi-task wave passes the gate (dispatch proceeds).
2363
+ // review on the implemented multi-task wave passes the gate (the preview renders).
2500
2364
  expect(
2501
2365
  await command.runArgv([
2502
2366
  "review",
2367
+ "--type",
2368
+ "wave",
2503
2369
  "--tasks",
2504
2370
  "1,2",
2505
2371
  "--plan",
2506
2372
  planPath,
2507
2373
  "--dry-run",
2508
- "--root",
2509
- repoRoot,
2510
2374
  ]),
2511
- ).not.toBe(1);
2375
+ ).toBe(0);
2512
2376
  // a re-implement on the at-review wave is the wrong-phase BLOCK, not a silent split.
2513
2377
  io.stderrText = "";
2514
2378
  expect(
2515
- await command.runArgv([
2516
- "implement",
2517
- "--tasks",
2518
- "1,2",
2519
- "--plan",
2520
- planPath,
2521
- "--dry-run",
2522
- "--root",
2523
- repoRoot,
2524
- ]),
2379
+ await command.runArgv(["implement", "--tasks", "1,2", "--plan", planPath, "--dry-run"]),
2525
2380
  ).toBe(1);
2526
2381
  expect(io.stderrText).toContain("at review");
2527
2382
  } finally {
@@ -2536,24 +2391,17 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2536
2391
  // implement now ALWAYS routes `{ kind: "review" }` — the live tree needs no sha — so
2537
2392
  // the same approved round yields its review hop, exit 0.
2538
2393
  const { command, io, repoRoot, cleanup } = fixture({
2539
- dispatch: () => ({ status: "APPROVED" }),
2394
+ dispatch: APPROVING,
2540
2395
  });
2541
2396
  try {
2542
2397
  gitInit(repoRoot);
2543
2398
  const plan = planFor(repoRoot);
2544
- const code = await command.runArgv([
2545
- "implement",
2546
- "--tasks",
2547
- "1",
2548
- "--plan",
2549
- plan,
2550
- "--dry-run",
2551
- "--root",
2552
- repoRoot,
2553
- ]);
2399
+ const code = await command.runArgv(["implement", "--tasks", "1", "--plan", plan]);
2554
2400
  expect(code).toBe(0);
2555
2401
  expect(io.stdoutText).toContain("status: APPROVED");
2556
- expect(io.stdoutText).toContain(`next: review --type wave --tasks 1 --plan ${plan}`);
2402
+ expect(io.stdoutText).toContain(
2403
+ `next: review --type wave --tasks 1 --plan ${path.relative(repoRoot, plan)}`,
2404
+ );
2557
2405
  expect(io.stderrText).not.toContain("CDD_BLOCKED:");
2558
2406
  } finally {
2559
2407
  cleanup();
@@ -2562,7 +2410,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2562
2410
 
2563
2411
  it("the clean-tree gate blocks the three verbs on a dirty tree — CDD_BLOCKED · guidance · child zero (P4.1 T1)", async () => {
2564
2412
  const { command, io, repoRoot, cleanup } = fixture({
2565
- dispatch: () => ({ status: "APPROVED" }), // a spy — must never run on a dirty tree
2413
+ dispatch: APPROVING, // a spy — must never run on a dirty tree
2566
2414
  });
2567
2415
  try {
2568
2416
  gitInit(repoRoot);
@@ -2578,7 +2426,7 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2578
2426
  : verb === "review"
2579
2427
  ? ["review", "--type", "wave", "--tasks", "1", "--plan", plan]
2580
2428
  : ["fix", "--type", "wave", "--tasks", "1", "--plan", plan];
2581
- const code = await command.runArgv([...args, "--dry-run", "--root", repoRoot]);
2429
+ const code = await command.runArgv([...args, "--dry-run"]);
2582
2430
  expect(code).toBe(1);
2583
2431
  // the CDD_BLOCKED channel + the commit/discard guidance
2584
2432
  expect(io.stderrText).toContain("CDD_BLOCKED:");
@@ -2593,31 +2441,26 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2593
2441
  }
2594
2442
  });
2595
2443
 
2596
- it("a consumer repo WITHOUT a .kairos gitignore — the engine workspace does not self-BLOCK the clean-tree gate across dispatches (P4.1 F1 regression)", async () => {
2597
- const { command, io, repoRoot, cleanup } = fixture();
2444
+ it("P4.1 F1 (real run) — a consumer repo WITHOUT a .kairos gitignore does not self-BLOCK the clean-tree gate across dispatches", async () => {
2445
+ // The consumer-repo shape: no `.kairos` entry in the fixture .gitignore — the
2446
+ // real run's workspace ensure self-publishes `.kairos/cdd/.gitignore` (content
2447
+ // `*`) at its first write point, BEFORE the next dispatch's gate reads the tree,
2448
+ // so the engine's own writes (the workspace + the round artifacts) land under
2449
+ // its keep-out marker — git's judgment stays clean, and the gate refuses only
2450
+ // genuinely dirty user work (never the engine's own outputs).
2451
+ const { command, io, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
2598
2452
  try {
2599
- // The consumer-repo shape: no `.kairos` entry in the fixture .gitignore — the
2600
- // workspace ensure self-publishes `.kairos/cdd/.gitignore` (content `*`)
2601
- // BEFORE the gate reads the tree, so the first dispatch's own writes (the
2602
- // scene's workspace ensure + the round artifacts) land under the engine's own
2603
- // keep-out marker — git's judgment stays clean, and the gate refuses only
2604
- // genuinely dirty user work (never the engine's own outputs).
2605
2453
  gitInit(repoRoot, "/docs/\n");
2606
2454
  const plan = conformingPlan(repoRoot);
2607
- const implement = await command.runArgv([
2608
- "implement",
2609
- "--tasks",
2610
- "1",
2611
- "--plan",
2612
- plan,
2613
- "--dry-run",
2614
- "--root",
2615
- repoRoot,
2616
- ]);
2455
+ const implement = await command.runArgv(["implement", "--tasks", "1", "--plan", plan]);
2617
2456
  expect(implement).toBe(0);
2618
2457
  // the first dispatch landed the engine workspace + its self-published keep-out
2619
2458
  expect(existsSync(path.join(repoRoot, ".kairos", "cdd", "p3"))).toBe(true);
2620
2459
  expect(readFileSync(path.join(repoRoot, ".kairos", ".gitignore"), "utf8")).toBe("*\n");
2460
+ // the brief the first dispatch rendered from the current plan is on disk
2461
+ expect(existsSync(path.join(repoRoot, ".kairos", "cdd", "p3", "tasks-1-brief.md"))).toBe(
2462
+ true,
2463
+ );
2621
2464
  io.stderrText = "";
2622
2465
  // the SECOND dispatch must not self-BLOCK on the engine's own artifacts
2623
2466
  const review = await command.runArgv([
@@ -2628,9 +2471,6 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2628
2471
  "1",
2629
2472
  "--plan",
2630
2473
  plan,
2631
- "--dry-run",
2632
- "--root",
2633
- repoRoot,
2634
2474
  ]);
2635
2475
  expect(review).toBe(0);
2636
2476
  expect(io.stderrText).not.toContain("CDD_BLOCKED:");
@@ -2639,21 +2479,56 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2639
2479
  }
2640
2480
  });
2641
2481
 
2642
- it("the materialized implement carrier on disk carries zero findings keys — the work face's zero-findings write path (T2)", async () => {
2643
- const { command, repoRoot, cleanup } = fixture();
2482
+ it("P4.1 F1 (preview leg) — the `--dry-run` chain writes nothing and consumes no round, so the review preview is never refused", async () => {
2483
+ // The preview's zero-write face on the same consumer-repo shape: `.kairos/` never
2484
+ // appears, the tree stays byte-identical, and because the implement preview books
2485
+ // no round the review preview still renders (no round consumed — the chained
2486
+ // command is not refused by the phase gate).
2487
+ const { command, io, repoRoot, cleanup } = fixture();
2644
2488
  try {
2645
- gitInit(repoRoot);
2646
- const plan = planFor(repoRoot);
2647
- const code = await command.runArgv([
2489
+ gitInit(repoRoot, "/docs/\n");
2490
+ const plan = conformingPlan(repoRoot);
2491
+ const implement = await command.runArgv([
2648
2492
  "implement",
2649
2493
  "--tasks",
2650
2494
  "1",
2651
2495
  "--plan",
2652
2496
  plan,
2653
2497
  "--dry-run",
2654
- "--root",
2655
- repoRoot,
2656
2498
  ]);
2499
+ expect(implement).toBe(0);
2500
+ expect(io.stdoutText.startsWith("cdd implement: preview (no repo changes)\n")).toBe(true);
2501
+ expect(existsSync(path.join(repoRoot, ".kairos"))).toBe(false);
2502
+ io.stdoutText = "";
2503
+ // the review preview: the implement preview left no ledger row, so the same
2504
+ // wave is still open at implement — the real run's phase gate would refuse it,
2505
+ // and the preview reports that refusal verbatim (pre-flight gates still run).
2506
+ const review = await command.runArgv([
2507
+ "review",
2508
+ "--type",
2509
+ "wave",
2510
+ "--tasks",
2511
+ "1",
2512
+ "--plan",
2513
+ plan,
2514
+ "--dry-run",
2515
+ ]);
2516
+ expect(review).toBe(1);
2517
+ expect(io.stderrText).toContain("the open wave is at implement");
2518
+ expect(io.stdoutText).toBe("");
2519
+ // zero writes across both previews — the chain never materialized the workspace
2520
+ expect(existsSync(path.join(repoRoot, ".kairos"))).toBe(false);
2521
+ } finally {
2522
+ cleanup();
2523
+ }
2524
+ });
2525
+
2526
+ it("the materialized implement carrier on disk carries zero findings keys — the work face's zero-findings write path (T2)", async () => {
2527
+ const { command, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
2528
+ try {
2529
+ gitInit(repoRoot);
2530
+ const plan = planFor(repoRoot);
2531
+ const code = await command.runArgv(["implement", "--tasks", "1", "--plan", plan]);
2657
2532
  expect(code).toBe(0);
2658
2533
  const carrier = JSON.parse(
2659
2534
  readFileSync(path.join(repoRoot, ".kairos", "cdd", "p3", "tasks-1-implement.json"), "utf8"),
@@ -2665,24 +2540,13 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2665
2540
  }
2666
2541
  });
2667
2542
 
2668
- it("T6 — probe A: the end-to-end dry-run implement + fix final carriers carry zero findings keys — both work-face materialization legs (implement + wave fix)", async () => {
2669
- const { command, repoRoot, cleanup } = fixture();
2543
+ it("T6 — probe A: the end-to-end implement + fix final carriers carry zero findings keys — both work-face materialization legs (implement + wave fix)", async () => {
2544
+ const { command, repoRoot, cleanup } = fixture({ dispatch: APPROVING });
2670
2545
  try {
2671
2546
  gitInit(repoRoot);
2672
2547
  const plan = planFor(repoRoot);
2673
- // the implement leg — the dry-run dispatch persists the work-face final carrier
2674
- expect(
2675
- await command.runArgv([
2676
- "implement",
2677
- "--tasks",
2678
- "1",
2679
- "--plan",
2680
- plan,
2681
- "--dry-run",
2682
- "--root",
2683
- repoRoot,
2684
- ]),
2685
- ).toBe(0);
2548
+ // the implement leg — the injected dispatch persists the work-face final carrier
2549
+ expect(await command.runArgv(["implement", "--tasks", "1", "--plan", plan])).toBe(0);
2686
2550
  const implementCarrier = JSON.parse(
2687
2551
  readFileSync(path.join(repoRoot, ".kairos", "cdd", "p3", "tasks-1-implement.json"), "utf8"),
2688
2552
  ) as Record<string, unknown>;
@@ -2704,20 +2568,9 @@ describe("the work commands run the lifecycle/capsule/ledger — dry-run E2E", (
2704
2568
  },
2705
2569
  );
2706
2570
  ledger.recordRound(1, "review");
2707
- expect(
2708
- await command.runArgv([
2709
- "fix",
2710
- "--type",
2711
- "wave",
2712
- "--tasks",
2713
- "1",
2714
- "--plan",
2715
- plan,
2716
- "--dry-run",
2717
- "--root",
2718
- repoRoot,
2719
- ]),
2720
- ).toBe(0);
2571
+ expect(await command.runArgv(["fix", "--type", "wave", "--tasks", "1", "--plan", plan])).toBe(
2572
+ 0,
2573
+ );
2721
2574
  const fixCarrier = JSON.parse(
2722
2575
  readFileSync(path.join(repoRoot, ".kairos", "cdd", "p3", "tasks-1-fix-1.json"), "utf8"),
2723
2576
  ) as Record<string, unknown>;
@@ -2813,29 +2666,29 @@ describe("P4.1 T4 — the next literal is a complete executable command (zero-er
2813
2666
  parses(branchLiteral);
2814
2667
  });
2815
2668
 
2816
- it("fix × 4 types — `fix --type <type> <type-arg> --findings <handoff>` parses", () => {
2817
- const waveLiteral = literalOf({ kind: "fix", findings: "tasks-1-review-1.json" }, wave);
2669
+ it("fix × 4 types — `fix --type <type> <type-arg> --reviews <handoff>` parses", () => {
2670
+ const waveLiteral = literalOf({ kind: "fix", reviews: "tasks-1-review-1.json" }, wave);
2818
2671
  expect(waveLiteral).toBe(
2819
- "fix --type wave --tasks 1,2 --plan docs/kairos/plans/p3.md --findings tasks-1-review-1.json " +
2672
+ "fix --type wave --tasks 1,2 --plan docs/kairos/plans/p3.md --reviews tasks-1-review-1.json " +
2820
2673
  FIX_READBACK_SUFFIX,
2821
2674
  );
2822
2675
  parses(waveLiteral);
2823
- const specLiteral = literalOf({ kind: "fix", findings: "s1-review-1.json" }, spec);
2676
+ const specLiteral = literalOf({ kind: "fix", reviews: "s1-review-1.json" }, spec);
2824
2677
  expect(specLiteral).toBe(
2825
- "fix --type spec --spec docs/kairos/specs/p3-design.md --findings s1-review-1.json " +
2678
+ "fix --type spec --spec docs/kairos/specs/p3-design.md --reviews s1-review-1.json " +
2826
2679
  FIX_READBACK_SUFFIX,
2827
2680
  );
2828
2681
  parses(specLiteral);
2829
- const planLiteral = literalOf({ kind: "fix", findings: "p1-review-1.json" }, planT);
2682
+ const planLiteral = literalOf({ kind: "fix", reviews: "p1-review-1.json" }, planT);
2830
2683
  expect(planLiteral).toBe(
2831
- `fix --type plan --plan docs/kairos/plans/p3.md --findings p1-review-1.json ${FIX_READBACK_SUFFIX}`,
2684
+ `fix --type plan --plan docs/kairos/plans/p3.md --reviews p1-review-1.json ${FIX_READBACK_SUFFIX}`,
2832
2685
  );
2833
2686
  parses(planLiteral);
2834
- const branchLiteral = literalOf({ kind: "fix", findings: "br1-review-1.json" }, branch);
2687
+ const branchLiteral = literalOf({ kind: "fix", reviews: "br1-review-1.json" }, branch);
2835
2688
  // find #8 F1b — the branch fix literal carries the workspace --plan
2836
2689
  // (user-decided; the orchestrator provides zero fallback · spec §5.7 fix (2))
2837
2690
  expect(branchLiteral).toBe(
2838
- `fix --type branch --plan docs/kairos/plans/p3.md --findings br1-review-1.json ${FIX_READBACK_SUFFIX}`,
2691
+ `fix --type branch --plan docs/kairos/plans/p3.md --reviews br1-review-1.json ${FIX_READBACK_SUFFIX}`,
2839
2692
  );
2840
2693
  parses(branchLiteral);
2841
2694
  });
@@ -2860,17 +2713,17 @@ describe("P4.1 T4 — the next literal is a complete executable command (zero-er
2860
2713
  expect(literalOf({ kind: "review" }, wave)).toMatch(
2861
2714
  new RegExp(`^${words.routeWord("review")} `),
2862
2715
  );
2863
- expect(literalOf({ kind: "fix", findings: "f.json" }, wave)).toMatch(
2716
+ expect(literalOf({ kind: "fix", reviews: "f.json" }, wave)).toMatch(
2864
2717
  new RegExp(`^${words.routeWord("fix")} `),
2865
2718
  );
2866
2719
  expect(literalOf({ kind: "done" })).toBe(words.routeWord("done"));
2867
2720
  });
2868
2721
  });
2869
2722
 
2870
- describe("P4.1 T4 — the dry-run real chain: next literals dispatch the next round (rev1→implement wave 2 · rev2→done)", () => {
2723
+ describe("P4.1 T4 — the real chain: next literals dispatch the next round (rev1→implement wave 2 · rev2→done)", () => {
2871
2724
  it("implement→review(fix)→fix(closure)→implement wave 2→review→done — every next literal re-dispatches", async () => {
2872
2725
  const { command, io, repoRoot, cleanup } = fixture({
2873
- dispatch: (frame: OpenFrame) => {
2726
+ dispatch: async (frame: OpenFrame) => {
2874
2727
  // the first review finds a warn (one-way fix hop); everything else approves
2875
2728
  return frame.phase === "review" && frame.params.tasks === "1"
2876
2729
  ? {
@@ -2883,6 +2736,7 @@ describe("P4.1 T4 — the dry-run real chain: next literals dispatch the next ro
2883
2736
  try {
2884
2737
  gitInit(repoRoot);
2885
2738
  const plan = planFor(repoRoot, 2);
2739
+ const planRel = path.relative(repoRoot, plan);
2886
2740
  const workspace = path.join(repoRoot, ".kairos", "cdd", "p3");
2887
2741
  const nextOf = (): string | null => {
2888
2742
  const m = io.stdoutText.match(/^next: (.+)$/m);
@@ -2890,92 +2744,37 @@ describe("P4.1 T4 — the dry-run real chain: next literals dispatch the next ro
2890
2744
  };
2891
2745
 
2892
2746
  // rev 1 — implement wave 1 → the review literal
2893
- expect(
2894
- await command.runArgv([
2895
- "implement",
2896
- "--tasks",
2897
- "1",
2898
- "--plan",
2899
- plan,
2900
- "--dry-run",
2901
- "--root",
2902
- repoRoot,
2903
- ]),
2904
- ).toBe(0);
2905
- expect(nextOf()).toBe(`review --type wave --tasks 1 --plan ${plan}`);
2747
+ expect(await command.runArgv(["implement", "--tasks", "1", "--plan", plan])).toBe(0);
2748
+ expect(nextOf()).toBe(`review --type wave --tasks 1 --plan ${planRel}`);
2906
2749
  io.stdoutText = "";
2907
2750
 
2908
2751
  // the review finds a warn → the fix literal
2909
2752
  expect(
2910
- await command.runArgv([
2911
- "review",
2912
- "--type",
2913
- "wave",
2914
- "--tasks",
2915
- "1",
2916
- "--plan",
2917
- plan,
2918
- "--dry-run",
2919
- "--root",
2920
- repoRoot,
2921
- ]),
2753
+ await command.runArgv(["review", "--type", "wave", "--tasks", "1", "--plan", plan]),
2922
2754
  ).toBe(0);
2923
2755
  expect(nextOf()).toBe(
2924
- `fix --type wave --tasks 1 --plan ${plan} --findings ${path.join(workspace, "tasks-1-review-1.json")} ${FIX_READBACK_SUFFIX}`,
2756
+ `fix --type wave --tasks 1 --plan ${planRel} --reviews ${path.relative(repoRoot, path.join(workspace, "tasks-1-review-1.json"))} ${FIX_READBACK_SUFFIX}`,
2925
2757
  );
2926
2758
  io.stdoutText = "";
2927
2759
 
2928
2760
  // the fix closes (warn-only input) → rev1 lands on the NEXT WAVE's implement literal
2929
- expect(
2930
- await command.runArgv([
2931
- "fix",
2932
- "--type",
2933
- "wave",
2934
- "--tasks",
2935
- "1",
2936
- "--plan",
2937
- plan,
2938
- "--dry-run",
2939
- "--root",
2940
- repoRoot,
2941
- ]),
2942
- ).toBe(0);
2943
- expect(nextOf()).toBe(`implement --plan ${plan} --tasks 2`);
2761
+ expect(await command.runArgv(["fix", "--type", "wave", "--tasks", "1", "--plan", plan])).toBe(
2762
+ 0,
2763
+ );
2764
+ expect(nextOf()).toBe(`implement --plan ${planRel} --tasks 2`);
2944
2765
  io.stdoutText = "";
2945
2766
 
2946
2767
  // rev 2 — implement wave 2 → the review literal
2947
- expect(
2948
- await command.runArgv([
2949
- "implement",
2950
- "--tasks",
2951
- "2",
2952
- "--plan",
2953
- plan,
2954
- "--dry-run",
2955
- "--root",
2956
- repoRoot,
2957
- ]),
2958
- ).toBe(0);
2959
- expect(nextOf()).toBe(`review --type wave --tasks 2 --plan ${plan}`);
2768
+ expect(await command.runArgv(["implement", "--tasks", "2", "--plan", plan])).toBe(0);
2769
+ expect(nextOf()).toBe(`review --type wave --tasks 2 --plan ${planRel}`);
2960
2770
  io.stdoutText = "";
2961
2771
 
2962
2772
  // the final review closes the run → rev2 lands on the wave→branch wiring
2963
2773
  // literal (T3 deliberate pin break — the PIPELINE_NEXT.wave route)
2964
2774
  expect(
2965
- await command.runArgv([
2966
- "review",
2967
- "--type",
2968
- "wave",
2969
- "--tasks",
2970
- "2",
2971
- "--plan",
2972
- plan,
2973
- "--dry-run",
2974
- "--root",
2975
- repoRoot,
2976
- ]),
2775
+ await command.runArgv(["review", "--type", "wave", "--tasks", "2", "--plan", plan]),
2977
2776
  ).toBe(0);
2978
- expect(nextOf()).toBe(`review --type branch --plan ${plan}`);
2777
+ expect(nextOf()).toBe(`review --type branch --plan ${planRel}`);
2979
2778
 
2980
2779
  const progress = readJson<{ waves: unknown[] }>(path.join(workspace, "progress.json"));
2981
2780
  // the wave-2 row carries its own D30 revision record — the final APPROVED
@@ -2983,7 +2782,7 @@ describe("P4.1 T4 — the dry-run real chain: next literals dispatch the next ro
2983
2782
  expect(progress.waves).toContainEqual({
2984
2783
  wave: "2",
2985
2784
  rounds: { implement: [1], review: [1] },
2986
- reviewedRevision: briefRevision(plan, "2"),
2785
+ reviewedRevision: briefRevision(repoRoot, plan, "2"),
2987
2786
  });
2988
2787
  } finally {
2989
2788
  cleanup();
@@ -3031,6 +2830,7 @@ describe("the pure commands — schema / issue / base", () => {
3031
2830
  it("schema get phase-spec --output skeleton <target> — the derived doc skeleton written directly into the target document", async () => {
3032
2831
  const { command, io, repoRoot, cleanup } = fixture();
3033
2832
  try {
2833
+ gitInit(repoRoot);
3034
2834
  const target = path.join(repoRoot, "docs", "skeleton.md");
3035
2835
  mkdirSync(path.dirname(target), { recursive: true });
3036
2836
  const code = await command.runArgv([
@@ -3049,13 +2849,17 @@ describe("the pure commands — schema / issue / base", () => {
3049
2849
  expect(text).toContain("## Design");
3050
2850
  expect(text).toContain("### 1. :::fill group-title");
3051
2851
  expect(text).toContain("- `:::fill acceptance-entry`");
3052
- expect(text).toContain("- **Version**: v0.1 · ");
2852
+ // the front-matter head — the doc-type/version/status truth keys
2853
+ expect(text).toContain("doc-type: phase-spec");
2854
+ expect(text).toContain("version: v0.1");
2855
+ expect(text).toContain("status: Draft");
3053
2856
  expect(text).toContain("| v0.1 | ");
3054
2857
  // the written doc ends with exactly one newline — the EOF rule (render()
3055
2858
  // never appends; the D19 write path appends the single `\n`)
3056
2859
  expect(text.endsWith("\n")).toBe(true);
3057
2860
  expect(text.endsWith("\n\n")).toBe(false);
3058
- expect(io.stdoutText.trim()).toBe(target);
2861
+ // the echoed path is the repoRoot-relative shape (D47 · §2.13)
2862
+ expect(io.stdoutText.trim()).toBe(path.relative(repoRoot, target));
3059
2863
  } finally {
3060
2864
  cleanup();
3061
2865
  }
@@ -3064,6 +2868,7 @@ describe("the pure commands — schema / issue / base", () => {
3064
2868
  it("schema get single-spec — the fourth doc-type channel: the json render without a target, the skeleton render into a required target", async () => {
3065
2869
  const { command, io, repoRoot, cleanup } = fixture();
3066
2870
  try {
2871
+ gitInit(repoRoot);
3067
2872
  // the json render face — the derived single-spec declaration, no target
3068
2873
  let code = await command.runArgv(["schema", "get", "single-spec"]);
3069
2874
  expect(code).toBe(0);
@@ -3084,12 +2889,14 @@ describe("the pure commands — schema / issue / base", () => {
3084
2889
  ]);
3085
2890
  expect(code).toBe(0);
3086
2891
  const text = readFileSync(target, "utf8");
3087
- // the header five-tuple without the phase-spec's Parent program
3088
- expect(text).toContain("- **Version**: v0.1 · ");
3089
- expect(text).toContain("- **Status**: Draft");
3090
- expect(text).toContain("- **Author**: :::fill author");
3091
- expect(text).toContain("- **Depends on**: :::fill depends-on");
3092
- expect(text).not.toContain("**Parent program**");
2892
+ // the head key set without the phase-spec's parent-program key
2893
+ expect(text).toContain("---");
2894
+ expect(text).toContain("doc-type: single-spec");
2895
+ expect(text).toContain("version: v0.1");
2896
+ expect(text).toContain("status: Draft");
2897
+ expect(text).toContain("author: ':::fill author'");
2898
+ expect(text).toContain("depends-on: ':::fill depends-on'");
2899
+ expect(text).not.toContain("parent-program");
3093
2900
  // the prose `:::fill` body + the change-history lineage — no `### N.` outline
3094
2901
  expect(text).toContain("## Background & root cause");
3095
2902
  expect(text).toContain(":::fill background-root-cause");
@@ -3102,7 +2909,8 @@ describe("the pure commands — schema / issue / base", () => {
3102
2909
  // the written doc ends with exactly one newline — the EOF rule
3103
2910
  expect(text.endsWith("\n")).toBe(true);
3104
2911
  expect(text.endsWith("\n\n")).toBe(false);
3105
- expect(io.stdoutText.trim()).toBe(target);
2912
+ // the echoed path is the repoRoot-relative shape (D47 · §2.13)
2913
+ expect(io.stdoutText.trim()).toBe(path.relative(repoRoot, target));
3106
2914
  // a missing <target> under --output skeleton exits 2 with the conditional-required byte
3107
2915
  io.stderrText = "";
3108
2916
  code = await command.runArgv(["schema", "get", "single-spec", "--output", "skeleton"]);
@@ -3117,6 +2925,8 @@ describe("the pure commands — schema / issue / base", () => {
3117
2925
  const dash = fixture();
3118
2926
  const camel = fixture();
3119
2927
  try {
2928
+ gitInit(dash.repoRoot);
2929
+ gitInit(camel.repoRoot);
3120
2930
  const dashTarget = path.join(dash.repoRoot, "dash.md");
3121
2931
  const camelTarget = path.join(camel.repoRoot, "camel.md");
3122
2932
  expect(
@@ -3220,6 +3030,7 @@ describe("the pure commands — schema / issue / base", () => {
3220
3030
  it("base set/get — the single --plan artifact write-through + the force gate (T20 face)", async () => {
3221
3031
  const { command, io, repoRoot, cleanup } = fixture();
3222
3032
  try {
3033
+ gitInit(repoRoot);
3223
3034
  const plan = planFor(repoRoot);
3224
3035
  const setCode = await command.runArgv([
3225
3036
  "base",
@@ -3233,6 +3044,12 @@ describe("the pure commands — schema / issue / base", () => {
3233
3044
  ]);
3234
3045
  expect(setCode).toBe(0);
3235
3046
  expect(io.stdoutText).toContain("base.json");
3047
+ // T18 (§2.13) — the `base set` echo is the repoRoot-relative shape, never the
3048
+ // absolute artifact path the write used.
3049
+ expect(io.stdoutText).not.toContain(repoRoot);
3050
+ expect(io.stdoutText.trim()).toBe(
3051
+ path.join(".kairos", "cdd", "p3", "base.json").replaceAll(path.sep, "/"),
3052
+ );
3236
3053
  const workspace = path.join(repoRoot, ".kairos", "cdd", "p3");
3237
3054
  const artifact = readJson<{ base: string; source: string }>(
3238
3055
  path.join(workspace, "base.json"),
@@ -3281,6 +3098,147 @@ describe("the pure commands — schema / issue / base", () => {
3281
3098
  });
3282
3099
  });
3283
3100
 
3101
+ // ---------------------------------------------------------------------------
3102
+ // P11 T3 — the write-point single authority: scene assembly never builds the
3103
+ // workspace (the first real write owns it) and the base artifact read rides the
3104
+ // SAME normalization path as its write.
3105
+ // ---------------------------------------------------------------------------
3106
+
3107
+ describe("P11 T3 — the workspace write-point + the base read normalization", () => {
3108
+ it("a READ-ONLY `cdd base get` on a fresh repo writes nothing (no .kairos/)", async () => {
3109
+ const { command, io, repoRoot, cleanup } = fixture();
3110
+ try {
3111
+ gitInit(repoRoot);
3112
+ const plan = planFor(repoRoot);
3113
+ const code = await command.runArgv(["base", "get", "--plan", plan]);
3114
+ // the artifact is absent — the read reports it (exit 2) and builds nothing
3115
+ expect(code).toBe(2);
3116
+ expect(io.stderrText).toContain("missing or corrupt base artifact");
3117
+ expect(existsSync(path.join(repoRoot, ".kairos"))).toBe(false);
3118
+ } finally {
3119
+ cleanup();
3120
+ }
3121
+ });
3122
+
3123
+ it("`cdd base get` reports a legacy ABSOLUTE `plan` field in the repoRoot-relative shape (the read normalization covers base.json)", async () => {
3124
+ const { command, io, repoRoot, cleanup } = fixture();
3125
+ try {
3126
+ gitInit(repoRoot);
3127
+ const plan = planFor(repoRoot);
3128
+ const workspace = new Workspace(new WorkspaceRoot(repoRoot, ".kairos/cdd"), "p3").ensure();
3129
+ const absolutePlan = path.join(repoRoot, "docs", "kairos", "plans", "p3.md");
3130
+ writeFileSync(
3131
+ path.join(workspace.path, "base.json"),
3132
+ `${JSON.stringify(
3133
+ { base: "develop", source: "plan-field", plan: absolutePlan, recordedAt: "t" },
3134
+ null,
3135
+ 2,
3136
+ )}\n`,
3137
+ "utf8",
3138
+ );
3139
+ const code = await command.runArgv(["base", "get", "--plan", plan]);
3140
+ expect(code).toBe(0);
3141
+ expect(io.stdoutText).toContain('"plan": "docs/kairos/plans/p3.md"');
3142
+ expect(io.stdoutText).not.toContain(repoRoot);
3143
+ } finally {
3144
+ cleanup();
3145
+ }
3146
+ });
3147
+
3148
+ it("`cdd base get` treats a non-object base.json as corrupt (exit 2, never a throw)", async () => {
3149
+ const { command, io, repoRoot, cleanup } = fixture();
3150
+ try {
3151
+ gitInit(repoRoot);
3152
+ const plan = planFor(repoRoot);
3153
+ const workspace = new Workspace(new WorkspaceRoot(repoRoot, ".kairos/cdd"), "p3").ensure();
3154
+ // the literal `null` is valid JSON but no base artifact — the read stays total
3155
+ writeFileSync(path.join(workspace.path, "base.json"), "null\n", "utf8");
3156
+ const code = await command.runArgv(["base", "get", "--plan", plan]);
3157
+ expect(code).toBe(2);
3158
+ expect(io.stderrText).toContain("missing or corrupt base artifact");
3159
+ } finally {
3160
+ cleanup();
3161
+ }
3162
+ });
3163
+
3164
+ it("a fresh repo's first REAL dispatch builds `.kairos/<slug>/` + publishes `.kairos/.gitignore` BEFORE the child spawns — every face (wave / spec / plan / branch)", async () => {
3165
+ const cases: { face: string; slug: string; argv: (plan: string, spec: string) => string[] }[] =
3166
+ [
3167
+ {
3168
+ face: "wave",
3169
+ slug: "p3",
3170
+ argv: (plan) => ["implement", "--tasks", "1", "--plan", plan],
3171
+ },
3172
+ {
3173
+ face: "branch",
3174
+ slug: "p3",
3175
+ argv: (plan) => ["review", "--type", "branch", "--plan", plan],
3176
+ },
3177
+ {
3178
+ face: "spec",
3179
+ slug: "s1",
3180
+ argv: (_plan, spec) => ["review", "--type", "spec", "--spec", spec],
3181
+ },
3182
+ {
3183
+ face: "plan",
3184
+ slug: "p3",
3185
+ argv: (plan) => ["review", "--type", "plan", "--plan", plan],
3186
+ },
3187
+ ];
3188
+ for (const entry of cases) {
3189
+ // The spawn-time observations — read INSIDE the dispatch seam, before the
3190
+ // round's bookkeeping could build anything. An after-the-run existsSync
3191
+ // cannot discriminate (the bookkeep's own writeJson ensures internally), so
3192
+ // the assertion has to sit at the child-spawn boundary itself.
3193
+ let workspaceAtSpawn = false;
3194
+ let keepOutAtSpawn = false;
3195
+ const { command, repoRoot, cleanup } = fixture({
3196
+ dispatch: async () => {
3197
+ workspaceAtSpawn = existsSync(path.join(repoRoot, ".kairos", "cdd", entry.slug));
3198
+ const keepOut = path.join(repoRoot, ".kairos", ".gitignore");
3199
+ keepOutAtSpawn = existsSync(keepOut) && readFileSync(keepOut, "utf8") === "*\n";
3200
+ return { status: "APPROVED" };
3201
+ },
3202
+ });
3203
+ try {
3204
+ gitInit(repoRoot);
3205
+ const plan = conformingPlan(repoRoot);
3206
+ const spec = conformingSpec(repoRoot);
3207
+ // scene assembly builds nothing — the workspace is absent before the run
3208
+ expect(existsSync(path.join(repoRoot, ".kairos")), `${entry.face}: pre-run`).toBe(false);
3209
+ const code = await command.runArgv(entry.argv(plan, spec));
3210
+ expect(code, `${entry.face}: dispatch exited ${code}`).toBe(0);
3211
+ expect(workspaceAtSpawn, `${entry.face}: workspace absent at spawn`).toBe(true);
3212
+ expect(keepOutAtSpawn, `${entry.face}: keep-out marker absent at spawn`).toBe(true);
3213
+ } finally {
3214
+ cleanup();
3215
+ }
3216
+ }
3217
+ });
3218
+
3219
+ it("a fresh repo's first REAL dispatch builds the workspace + renders the brief (zero ENOENT)", async () => {
3220
+ const { command, io, repoRoot, cleanup } = fixture({
3221
+ dispatch: APPROVING,
3222
+ });
3223
+ try {
3224
+ gitInit(repoRoot);
3225
+ const plan = planFor(repoRoot);
3226
+ // scene assembly builds nothing — the workspace is absent before the run
3227
+ expect(existsSync(path.join(repoRoot, ".kairos"))).toBe(false);
3228
+ const code = await command.runArgv(["implement", "--tasks", "1", "--plan", plan]);
3229
+ expect(code).toBe(0);
3230
+ const workspace = path.join(repoRoot, ".kairos", "cdd", "p3");
3231
+ expect(existsSync(workspace)).toBe(true);
3232
+ expect(existsSync(path.join(workspace, "tasks-1-brief.md"))).toBe(true);
3233
+ expect(io.stderrText).not.toContain("ENOENT");
3234
+ // the namespace keep-out marker is published at the first write point
3235
+ expect(readFileSync(path.join(repoRoot, ".kairos", ".gitignore"), "utf8")).toBe("*\n");
3236
+ } finally {
3237
+ cleanup();
3238
+ }
3239
+ });
3240
+ });
3241
+
3284
3242
  describe("T9 — the composition-root entry is the Cli.create static factory (deliberate pin)", () => {
3285
3243
  it("the module's composition root is the class static factory — zero bare-function entry", () => {
3286
3244
  // The P5 zero-bare-function closure locked the composition root's class form:
@@ -3312,17 +3270,17 @@ describe("T5 — cdd board <slug>: the pure-read board command", () => {
3312
3270
  mkdirSync(path.join(repoRoot, "docs/kairos/plans"), { recursive: true });
3313
3271
  writeFileSync(
3314
3272
  path.join(repoRoot, `docs/kairos/specs/${program}-overall.md`),
3315
- "# O\n\n- **Doc type**: overall-spec\n",
3273
+ "---\ntitle: O\ndoc-type: overall-spec\n---\n",
3316
3274
  "utf8",
3317
3275
  );
3318
3276
  writeFileSync(
3319
3277
  path.join(repoRoot, `docs/kairos/specs/${program}-p1-design.md`),
3320
- "# S\n\n- **Doc type**: phase-spec\n",
3278
+ "---\ntitle: S\ndoc-type: phase-spec\n---\n",
3321
3279
  "utf8",
3322
3280
  );
3323
3281
  writeFileSync(
3324
3282
  path.join(repoRoot, `docs/kairos/plans/${program}-p1.md`),
3325
- "# Plan\n\n- **Doc type**: plan\n",
3283
+ "---\ntitle: Plan\ndoc-type: plan\n---\n",
3326
3284
  "utf8",
3327
3285
  );
3328
3286
  };
@@ -3330,6 +3288,7 @@ describe("T5 — cdd board <slug>: the pure-read board command", () => {
3330
3288
  it("a valid slug renders the board to stdout and exits 0", async () => {
3331
3289
  const { command, io, repoRoot, cleanup } = fixture();
3332
3290
  try {
3291
+ gitInit(repoRoot);
3333
3292
  seedPhaseDocs(repoRoot, "prog");
3334
3293
  const code = await command.runArgv(["board", "prog-p1"]);
3335
3294
  expect(code).toBe(0);
@@ -3352,8 +3311,9 @@ describe("T5 — cdd board <slug>: the pure-read board command", () => {
3352
3311
  });
3353
3312
 
3354
3313
  it("a ghost slug matches nothing on disk — exit 2, no wall", async () => {
3355
- const { command, io, cleanup } = fixture();
3314
+ const { command, io, repoRoot, cleanup } = fixture();
3356
3315
  try {
3316
+ gitInit(repoRoot);
3357
3317
  const code = await command.runArgv(["board", "nonexistent-slug"]);
3358
3318
  expect(code).toBe(2);
3359
3319
  expect(io.stderrText).toContain("no docs match slug nonexistent-slug");
@@ -3540,22 +3500,18 @@ describe("T3 — the commander-native composition root: program parse + .action
3540
3500
  it("the shared text-read's unreadable-file refusal rides the work face's native usage line", async () => {
3541
3501
  const { command, io, repoRoot, cleanup } = fixture();
3542
3502
  try {
3503
+ gitInit(repoRoot);
3543
3504
  // The text-read face the work commands share (readText) — its unreadable-file
3544
3505
  // refusal surfaces through the wave face's --plan read (the same artifacts
3545
3506
  // face; the owning node's usage line).
3546
3507
  const missing = path.join(repoRoot, "no-such-plan.md");
3547
- const code = await command.runArgv([
3548
- "implement",
3549
- "--tasks",
3550
- "1",
3551
- "--plan",
3552
- missing,
3553
- "--root",
3554
- repoRoot,
3555
- ]);
3508
+ const code = await command.runArgv(["implement", "--tasks", "1", "--plan", missing]);
3556
3509
  expect(code).toBe(2);
3557
3510
  expect(io.stderrText).toContain("Usage: cdd implement [options]");
3558
- expect(io.stderrText).toContain(`error: cannot read file: ${missing}`);
3511
+ // the refusal byte echoes the repoRoot-relative shape (D47 · §2.13)
3512
+ expect(io.stderrText).toContain(
3513
+ `error: cannot read file: ${path.relative(repoRoot, missing)}`,
3514
+ );
3559
3515
  } finally {
3560
3516
  cleanup();
3561
3517
  }
@@ -3564,6 +3520,7 @@ describe("T3 — the commander-native composition root: program parse + .action
3564
3520
  it("the base get domain read — a set artifact exits 0 over the write-through path", async () => {
3565
3521
  const { command, io, repoRoot, cleanup } = fixture();
3566
3522
  try {
3523
+ gitInit(repoRoot);
3567
3524
  const plan = planFor(repoRoot);
3568
3525
  expect(
3569
3526
  await command.runArgv([
@@ -3586,30 +3543,50 @@ describe("T3 — the commander-native composition root: program parse + .action
3586
3543
  }
3587
3544
  });
3588
3545
 
3589
- it("review --type spec --dry-run — the thin-shell domain run synthesizes the approval", async () => {
3546
+ it("review --type spec --dry-run — the preview forecasts the spec round at zero writes", async () => {
3590
3547
  const { command, io, repoRoot, cleanup } = fixture();
3591
3548
  try {
3592
3549
  gitInit(repoRoot);
3593
- // The declared, contract-clean spec doc — the `- **Doc type**:` header
3594
- // declaration (spec §12 · D34) the capsule's doc-class discrimination reads
3550
+ // The declared, contract-clean spec doc — the `doc-type:` head key
3551
+ // (spec §12 · D34) the capsule's doc-class discrimination reads
3595
3552
  // (zero filename inference).
3596
3553
  const spec = conformingSpec(repoRoot);
3597
- const code = await command.runArgv([
3598
- "review",
3599
- "--type",
3600
- "spec",
3601
- "--spec",
3602
- spec,
3603
- "--dry-run",
3604
- "--root",
3605
- repoRoot,
3606
- ]);
3554
+ const code = await command.runArgv(["review", "--type", "spec", "--spec", spec, "--dry-run"]);
3607
3555
  expect(code).toBe(0);
3608
- expect(io.stdoutText).toContain("next: /kairos:cdd-plan");
3556
+ // the preview names the spec round's step + its prescribed write set, and
3557
+ // fabricates neither a conclusion nor a next hop (P11 §3.3)
3558
+ expect(io.stdoutText.startsWith("cdd review: preview (no repo changes)\n")).toBe(true);
3559
+ expect(io.stdoutText).toContain(" step: review round 1 — spec");
3560
+ expect(io.stdoutText).toContain(
3561
+ " would write: .kairos/cdd/s1/spec-review-1.json · .kairos/cdd/s1/spec-review-1-report.md",
3562
+ );
3563
+ expect(io.stdoutText).not.toContain("next:");
3564
+ expect(existsSync(path.join(repoRoot, ".kairos"))).toBe(false);
3609
3565
  } finally {
3610
3566
  cleanup();
3611
3567
  }
3612
3568
  });
3569
+
3570
+ it("an underivable repo root BLOCKs (exit 1, never a usage 2) — a work verb from outside any git repo (§2.6)", async () => {
3571
+ // The repo root is the ONE conversion point (T2): the working directory's git
3572
+ // top level. A cwd outside any git repository cannot derive it — a missing
3573
+ // run-environment fact, so the command rides the CDD_BLOCKED channel and exits 1
3574
+ // (never a usage error — exit 2, zero new message surface).
3575
+ const nonRepo = realpathSync(mkdtempSync(path.join(tmpdir(), "cli-nonrepo-")));
3576
+ const savedCwd = process.cwd();
3577
+ process.chdir(nonRepo);
3578
+ const io = new CaptureIo();
3579
+ const command = Cli.create({ io, dispatch: APPROVING });
3580
+ try {
3581
+ const code = await command.runArgv(["implement", "--tasks", "1", "--plan", "p3.md"]);
3582
+ expect(code).toBe(1);
3583
+ expect(io.stderrText).toContain("CDD_BLOCKED:");
3584
+ expect(io.stderrText).toContain("not inside a git repository");
3585
+ } finally {
3586
+ process.chdir(savedCwd);
3587
+ rmSync(nonRepo, { recursive: true, force: true });
3588
+ }
3589
+ });
3613
3590
  });
3614
3591
 
3615
3592
  // ---------------------------------------------------------------------------
@@ -3637,7 +3614,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3637
3614
  type: "spec",
3638
3615
  phase: "review",
3639
3616
  round: 1,
3640
- target: { kind: "doc", doc: "docs/kairos/specs/s1-design.md" },
3617
+ target: { kind: "spec", doc: "docs/kairos/specs/s1-design.md" },
3641
3618
  params: { round: 1 },
3642
3619
  key: "docs/kairos/specs/s1-design.md",
3643
3620
  };
@@ -3679,15 +3656,15 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3679
3656
  }
3680
3657
  });
3681
3658
 
3682
- it("dispatches through the harness rows — the skill-ref slash form + the prompt, the draft read back into the outcome", () => {
3659
+ it("dispatches through the harness rows — the skill-ref slash form + the prompt, the draft read back into the outcome", async () => {
3683
3660
  const { repoRoot, cleanup } = fixture();
3684
3661
  try {
3685
3662
  const scene = harnessScene(repoRoot);
3686
3663
  const io = new CaptureIo();
3687
- const sync = new FakeSync();
3688
- // the child's block-return is the two-line contract (status + artifacts — the
3689
- // commit carrier is retired · spec §2.4)
3690
- sync.stdout = "status: APPROVED\nartifacts: brief=/b report=/r test_evidence=/t\n";
3664
+ const sync = new StubRunner();
3665
+ // the child's Return is prose (P11 · §2.1) — the engine never parses it; the
3666
+ // round's content is the OUTPUT_HANDOFF draft read back below.
3667
+ sync.stdout = "Implemented the task. All checks green.\n";
3691
3668
  // The child's write-back: the implement draft at OUTPUT_HANDOFF per the injected
3692
3669
  // `work` schema + the canonical test-evidence file (the v1.9 read-back inputs).
3693
3670
  const draft = path.join(scene.workspace.path, "tasks-1-implement.json");
@@ -3725,24 +3702,29 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3725
3702
  sync,
3726
3703
  env: { CLAUDE_CODE_SESSION_ID: "s" },
3727
3704
  });
3728
- const outcome = dispatch.step()(implementFrame);
3705
+ const outcome = await dispatch.step()(implementFrame);
3729
3706
  expect(sync.calls.length).toBe(1);
3730
3707
  const call = sync.calls[0];
3731
3708
  expect(call.command).toBe("claude");
3732
3709
  expect(call.args).toContain("-p");
3710
+ // D46 — the child is spawned at cwd = repoRoot: the round-context path tokens
3711
+ // are repoRoot-relative, so a relative token only resolves correctly when the
3712
+ // child's cwd IS the repoRoot (the coupled invariant — pin both together).
3713
+ expect(call.cwd).toBe(repoRoot);
3733
3714
  // The skill ref is NOT a standalone positional (the harness CLI consumes the
3734
3715
  // first positional as the whole prompt — a split prompt loses everything after
3735
3716
  // the ref). It prefixes the single prompt argument instead.
3736
3717
  expect(call.args).not.toContain("/mattpocock-skills:implement");
3737
3718
  const prompt = call.args[call.args.length - 1];
3738
3719
  expect(prompt.startsWith("/mattpocock-skills:implement ")).toBe(true);
3739
- // v1.8 — the mode dispatch table + the normalized naming grammar (ROLE/WAVE · INPUT_/OUTPUT_/WORKSPACE_)
3720
+ // v1.8 — the mode dispatch table + the normalized naming grammar (ROLE/WAVE · INPUT_/OUTPUT_/WORKSPACE_).
3721
+ // D46 — every round-context path token is repoRoot-RELATIVE (the child is spawned
3722
+ // at cwd = repoRoot): the tokens carry the workspace path minus the repoRoot prefix.
3723
+ const wsRel = path.relative(repoRoot, scene.workspace.path);
3740
3724
  expect(prompt).toContain("- `ROLE`: implement");
3741
3725
  expect(prompt).toContain("- `WAVE`: 1");
3742
- expect(prompt).toContain(`- \`WORKSPACE_DIR\`: ${scene.workspace.path}`);
3743
- expect(prompt).toContain(
3744
- `- \`OUTPUT_HANDOFF\`: ${path.join(scene.workspace.path, "tasks-1-implement.json")}`,
3745
- );
3726
+ expect(prompt).toContain(`- \`WORKSPACE_DIR\`: ${wsRel}`);
3727
+ expect(prompt).toContain(`- \`OUTPUT_HANDOFF\`: ${wsRel}/tasks-1-implement.json`);
3746
3728
  // find #4 — INPUT_RULES is gone: the implement child reads the plan's
3747
3729
  // `## Constraints` through the wave brief mirror (zero materialized rules file,
3748
3730
  // zero dead pointer — the round context carries no rules channel).
@@ -3751,12 +3733,8 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3751
3733
  // prefix): the brief is a pure read input (INPUT_WAVE_BRIEF) with no write slot
3752
3734
  // (only present facts ride the prompt), while report + evidence are prescribed.
3753
3735
  expect(prompt).not.toContain("OUTPUT_BRIEF");
3754
- expect(prompt).toContain(
3755
- `- \`OUTPUT_REPORT\`: ${path.join(scene.workspace.path, "tasks-1-implement-report.md")}`,
3756
- );
3757
- expect(prompt).toContain(
3758
- `- \`OUTPUT_EVIDENCE\`: ${path.join(scene.workspace.path, "tasks-1-test-evidence.json")}`,
3759
- );
3736
+ expect(prompt).toContain(`- \`OUTPUT_REPORT\`: ${wsRel}/tasks-1-implement-report.md`);
3737
+ expect(prompt).toContain(`- \`OUTPUT_EVIDENCE\`: ${wsRel}/tasks-1-test-evidence.json`);
3760
3738
  // the per-mode trimming: this scene carries no brief (briefPath null) — the empty
3761
3739
  // INPUT_TASK key is NOT emitted (empty keys are never emitted)
3762
3740
  expect(prompt).not.toContain("- `INPUT_TASK`");
@@ -3768,13 +3746,21 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3768
3746
  expect(prompt).not.toContain("HANDOFF_WRITE_GATE");
3769
3747
  // the read-back reconstruct — the final carrier (the schema's declared fields
3770
3748
  // only: identity rides the file name, never phase/tasks inline — v1.30) rides
3771
- // the outcome, the block's two lines the pointer
3749
+ // the outcome; the child's stdout prose is never parsed
3772
3750
  expect(outcome.status).toBe("APPROVED");
3751
+ // The prescribed slots book the canonical repoRoot-RELATIVE paths (§2.7) even
3752
+ // when the child declared them absolute; the non-prescribed `brief` passes verbatim.
3773
3753
  expect(outcome.carrier).toEqual({
3774
3754
  artifacts: {
3775
3755
  brief: "/b",
3776
- report: path.join(scene.workspace.path, "tasks-1-implement-report.md"),
3777
- test_evidence: path.join(scene.workspace.path, "tasks-1-test-evidence.json"),
3756
+ report: path.relative(
3757
+ repoRoot,
3758
+ path.join(scene.workspace.path, "tasks-1-implement-report.md"),
3759
+ ),
3760
+ test_evidence: path.relative(
3761
+ repoRoot,
3762
+ path.join(scene.workspace.path, "tasks-1-test-evidence.json"),
3763
+ ),
3778
3764
  },
3779
3765
  status: "APPROVED",
3780
3766
  });
@@ -3786,7 +3772,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3786
3772
  }
3787
3773
  });
3788
3774
 
3789
- it("prescribes the implement artifact paths — REPORT/EVIDENCE carry the canonical {family}-{key}- names (find #5)", () => {
3775
+ it("prescribes the implement artifact paths — REPORT/EVIDENCE carry the canonical {family}-{key}- names (find #5)", async () => {
3790
3776
  const { repoRoot, cleanup } = fixture();
3791
3777
  try {
3792
3778
  const workspace = new Workspace(new WorkspaceRoot(repoRoot, ".kairos/cdd"), "p3").ensure();
@@ -3798,7 +3784,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3798
3784
  briefPath: path.join(workspace.path, "tasks-1-brief.md"),
3799
3785
  };
3800
3786
  const io = new CaptureIo();
3801
- const sync = new FakeSync();
3787
+ const sync = new StubRunner();
3802
3788
  sync.stdout = "status: APPROVED\n";
3803
3789
  const dispatch = new HarnessDispatch({
3804
3790
  scene,
@@ -3806,27 +3792,24 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3806
3792
  sync,
3807
3793
  env: { CLAUDE_CODE_SESSION_ID: "s" },
3808
3794
  });
3809
- dispatch.step()(implementFrame);
3795
+ await dispatch.step()(implementFrame);
3810
3796
  const prompt = sync.calls[0]!.args[sync.calls[0]!.args.length - 1];
3811
3797
  // the brief is a pure read input (INPUT_WAVE_BRIEF — no OUTPUT_BRIEF · spec §4.2);
3812
3798
  // the prescribed write paths ride the round context (report + evidence = the
3813
3799
  // report/verify write paths — zero free naming, cross-round zero overwrite).
3814
- expect(prompt).toContain(
3815
- `- \`INPUT_WAVE_BRIEF\`: ${path.join(workspace.path, "tasks-1-brief.md")}`,
3816
- );
3800
+ // D46 — every round-context path token is repoRoot-relative (the child spawned at
3801
+ // cwd = repoRoot), so the tokens carry the workspace minus the repoRoot prefix.
3802
+ const wsRel = path.relative(repoRoot, workspace.path);
3803
+ expect(prompt).toContain(`- \`INPUT_WAVE_BRIEF\`: ${wsRel}/tasks-1-brief.md`);
3817
3804
  expect(prompt).not.toContain("OUTPUT_BRIEF");
3818
- expect(prompt).toContain(
3819
- `- \`OUTPUT_REPORT\`: ${path.join(workspace.path, "tasks-1-implement-report.md")}`,
3820
- );
3821
- expect(prompt).toContain(
3822
- `- \`OUTPUT_EVIDENCE\`: ${path.join(workspace.path, "tasks-1-test-evidence.json")}`,
3823
- );
3805
+ expect(prompt).toContain(`- \`OUTPUT_REPORT\`: ${wsRel}/tasks-1-implement-report.md`);
3806
+ expect(prompt).toContain(`- \`OUTPUT_EVIDENCE\`: ${wsRel}/tasks-1-test-evidence.json`);
3824
3807
  } finally {
3825
3808
  cleanup();
3826
3809
  }
3827
3810
  });
3828
3811
 
3829
- it("§4.2 — every wave frame (implement/review/fix) carries the scene's brief as INPUT_WAVE_BRIEF, never a disk-existence read", () => {
3812
+ it("§4.2 — every wave frame (implement/review/fix) carries the scene's brief as INPUT_WAVE_BRIEF, never a disk-existence read", async () => {
3830
3813
  const { repoRoot, cleanup } = fixture();
3831
3814
  try {
3832
3815
  const workspace = new Workspace(new WorkspaceRoot(repoRoot, ".kairos/cdd"), "p3").ensure();
@@ -3841,7 +3824,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3841
3824
  briefPath,
3842
3825
  };
3843
3826
  const io = new CaptureIo();
3844
- const sync = new FakeSync();
3827
+ const sync = new StubRunner();
3845
3828
  sync.stdout = "status: APPROVED\n";
3846
3829
  const dispatch = new HarnessDispatch({
3847
3830
  scene,
@@ -3849,19 +3832,21 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3849
3832
  sync,
3850
3833
  env: { CLAUDE_CODE_SESSION_ID: "s" },
3851
3834
  });
3852
- // the review + fix frames both carry the ONE scene brief (not implement-only)
3853
- dispatch.step()(taskReviewFrame);
3854
- dispatch.step()(fixFrame);
3835
+ // the review + fix frames both carry the ONE scene brief (not implement-only).
3836
+ // D46 — the token is repoRoot-relative (the child spawned at cwd = repoRoot).
3837
+ const briefRel = path.relative(repoRoot, briefPath);
3838
+ await dispatch.step()(taskReviewFrame);
3839
+ await dispatch.step()(fixFrame);
3855
3840
  for (const call of sync.calls) {
3856
3841
  const prompt = call.args[call.args.length - 1];
3857
- expect(prompt).toContain(`- \`INPUT_WAVE_BRIEF\`: ${briefPath}`);
3842
+ expect(prompt).toContain(`- \`INPUT_WAVE_BRIEF\`: ${briefRel}`);
3858
3843
  }
3859
3844
  } finally {
3860
3845
  cleanup();
3861
3846
  }
3862
3847
  });
3863
3848
 
3864
- it("the doc-family artifacts are round-keyed — a second review round prescribes a different report path, never an overwrite (find #5)", () => {
3849
+ it("the doc-family artifacts are round-keyed — a second review round prescribes a different report path, never an overwrite (find #5)", async () => {
3865
3850
  const { repoRoot, cleanup } = fixture();
3866
3851
  try {
3867
3852
  const workspace = new Workspace(new WorkspaceRoot(repoRoot, ".kairos/cdd"), "p3").ensure();
@@ -3873,7 +3858,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3873
3858
  briefPath: null,
3874
3859
  };
3875
3860
  const io = new CaptureIo();
3876
- const sync = new FakeSync();
3861
+ const sync = new StubRunner();
3877
3862
  sync.stdout = "status: APPROVED\n";
3878
3863
  const dispatch = new HarnessDispatch({
3879
3864
  scene,
@@ -3881,16 +3866,14 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3881
3866
  sync,
3882
3867
  env: { CLAUDE_CODE_SESSION_ID: "s" },
3883
3868
  });
3884
- dispatch.step()(specReviewFrame);
3869
+ await dispatch.step()(specReviewFrame);
3885
3870
  const first = sync.calls[0]!.args[sync.calls[0]!.args.length - 1];
3886
- dispatch.step()({ ...specReviewFrame, round: 2, params: { round: 2 } });
3871
+ await dispatch.step()({ ...specReviewFrame, round: 2, params: { round: 2 } });
3887
3872
  const second = sync.calls[1]!.args[sync.calls[1]!.args.length - 1];
3888
- expect(first).toContain(
3889
- `- \`OUTPUT_REPORT\`: ${path.join(workspace.path, "spec-review-1-report.md")}`,
3890
- );
3891
- expect(second).toContain(
3892
- `- \`OUTPUT_REPORT\`: ${path.join(workspace.path, "spec-review-2-report.md")}`,
3893
- );
3873
+ // D46 — the token is repoRoot-relative (the child spawned at cwd = repoRoot).
3874
+ const wsRel = path.relative(repoRoot, workspace.path);
3875
+ expect(first).toContain(`- \`OUTPUT_REPORT\`: ${wsRel}/spec-review-1-report.md`);
3876
+ expect(second).toContain(`- \`OUTPUT_REPORT\`: ${wsRel}/spec-review-2-report.md`);
3894
3877
  // the round-keyed names never collide — a re-review cannot overwrite its predecessor
3895
3878
  expect(path.join(workspace.path, "spec-review-1-report.md")).not.toBe(
3896
3879
  path.join(workspace.path, "spec-review-2-report.md"),
@@ -3900,12 +3883,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3900
3883
  }
3901
3884
  });
3902
3885
 
3903
- it("a free-named declared artifact path is corrected to the canonical OUTPUT_* path + surfaced on the notes (find #5 self-derivation)", () => {
3886
+ it("a free-named declared artifact path is corrected to the canonical OUTPUT_* path + surfaced on the notes (find #5 self-derivation)", async () => {
3904
3887
  const { repoRoot, cleanup } = fixture();
3905
3888
  try {
3906
3889
  const scene = harnessScene(repoRoot);
3907
3890
  const io = new CaptureIo();
3908
- const sync = new FakeSync();
3891
+ const sync = new StubRunner();
3909
3892
  sync.stdout = "status: APPROVED\n";
3910
3893
  const draftPath = path.join(scene.workspace.path, "tasks-1-implement.json");
3911
3894
  writeFileSync(
@@ -3935,14 +3918,22 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3935
3918
  sync,
3936
3919
  env: { CLAUDE_CODE_SESSION_ID: "s" },
3937
3920
  });
3938
- const outcome = dispatch.step()(implementFrame);
3921
+ const outcome = await dispatch.step()(implementFrame);
3939
3922
  expect(outcome.status).toBe("APPROVED");
3940
3923
  // the engine books the canonical names — a child-reported free path never lands;
3941
- // both deviations ride the carrier's notes (the review scope axis reads them)
3924
+ // both deviations ride the carrier's notes (the review scope axis reads them).
3925
+ // The booked canonical paths are the repoRoot-RELATIVE shape (P9 T4 §2.7 —
3926
+ // persisted path fields carry zero absolute strings).
3942
3927
  expect(outcome.carrier).toEqual({
3943
3928
  artifacts: {
3944
- report: path.join(scene.workspace.path, "tasks-1-implement-report.md"),
3945
- test_evidence: path.join(scene.workspace.path, "tasks-1-test-evidence.json"),
3929
+ report: path.relative(
3930
+ repoRoot,
3931
+ path.join(scene.workspace.path, "tasks-1-implement-report.md"),
3932
+ ),
3933
+ test_evidence: path.relative(
3934
+ repoRoot,
3935
+ path.join(scene.workspace.path, "tasks-1-test-evidence.json"),
3936
+ ),
3946
3937
  },
3947
3938
  status: "APPROVED",
3948
3939
  notes: [
@@ -3957,12 +3948,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3957
3948
  }
3958
3949
  });
3959
3950
 
3960
- it("D39 — a trailing-comma draft reconstructs cleanly (the lenient read face; the round is not voided)", () => {
3951
+ it("D39 — a trailing-comma draft reconstructs cleanly (the lenient read face; the round is not voided)", async () => {
3961
3952
  const { repoRoot, cleanup } = fixture();
3962
3953
  try {
3963
3954
  const scene = harnessScene(repoRoot);
3964
3955
  const io = new CaptureIo();
3965
- const sync = new FakeSync();
3956
+ const sync = new StubRunner();
3966
3957
  sync.stdout = "status: APPROVED\n";
3967
3958
  // The child LLM writes a draft with a routine slip — a trailing comma in the
3968
3959
  // notes array (the W3 {5,11} block shape). The reconstruct's draft read is the
@@ -3994,7 +3985,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
3994
3985
  sync,
3995
3986
  env: { CLAUDE_CODE_SESSION_ID: "s" },
3996
3987
  });
3997
- const outcome = dispatch.step()(implementFrame);
3988
+ const outcome = await dispatch.step()(implementFrame);
3998
3989
  // The trailing comma is tolerated — the round lands APPROVED, never a malformed
3999
3990
  // reject; the notes the child wrote survive into the carrier.
4000
3991
  expect(outcome.status).toBe("APPROVED");
@@ -4005,12 +3996,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4005
3996
  }
4006
3997
  });
4007
3998
 
4008
- it("§8.7 — a non-declared / engine-reserved draft field is dropped with a single WARN, never a BLOCK (materialize and the validator judge the same way)", () => {
3999
+ it("§8.7 — a non-declared / engine-reserved draft field is dropped with a single WARN, never a BLOCK (materialize and the validator judge the same way)", async () => {
4009
4000
  const { repoRoot, cleanup } = fixture();
4010
4001
  try {
4011
4002
  const scene = harnessScene(repoRoot);
4012
4003
  const io = new CaptureIo();
4013
- const sync = new FakeSync();
4004
+ const sync = new StubRunner();
4014
4005
  sync.stdout = "status: APPROVED\n";
4015
4006
  // A work draft carrying engine-reserved keys (commits — retired) + a child extra
4016
4007
  // (phase). The read-back validator drops them (never a refusal); materialize
@@ -4045,7 +4036,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4045
4036
  sync,
4046
4037
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4047
4038
  });
4048
- const outcome = dispatch.step()(implementFrame);
4039
+ const outcome = await dispatch.step()(implementFrame);
4049
4040
  // the round is NOT blocked (a non-declared extra field is not a semantic error)
4050
4041
  expect(outcome.status).toBe("APPROVED");
4051
4042
  expect(io.stderrText).toBe("");
@@ -4065,12 +4056,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4065
4056
  }
4066
4057
  });
4067
4058
 
4068
- it("§8.7 — a findings-face draft carrying a stray `status` (+ another key) is dropped with a single WARN, never a BLOCK (the exact dogfood crash face)", () => {
4059
+ it("§8.7 — a findings-face draft carrying a stray `status` (+ another key) is dropped with a single WARN, never a BLOCK (the exact dogfood crash face)", async () => {
4069
4060
  const { repoRoot, cleanup } = fixture();
4070
4061
  try {
4071
4062
  const scene = harnessScene(repoRoot);
4072
4063
  const io = new CaptureIo();
4073
- const sync = new FakeSync();
4064
+ const sync = new StubRunner();
4074
4065
  // The §2.8/§8.7 dogfood crash face: a child-authored `status` (non-declared on
4075
4066
  // the findings face — the finding carrier holds no status; the conclusion derives
4076
4067
  // at judgment time) on a review draft, plus a stray extra key. The read-back
@@ -4092,7 +4083,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4092
4083
  sync,
4093
4084
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4094
4085
  });
4095
- const outcome = dispatch.step()(specReviewFrame);
4086
+ const outcome = await dispatch.step()(specReviewFrame);
4096
4087
  // the round is NOT blocked (a non-declared field is not a semantic error) — the
4097
4088
  // conclusion derives from the draft's findings (nit → REVIEW_FIX), never the
4098
4089
  // dropped child status
@@ -4114,12 +4105,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4114
4105
  }
4115
4106
  });
4116
4107
 
4117
- it("the docs review — the block + draft face: findings flow back from the file, the status rolls up", () => {
4108
+ it("the docs review — the block + draft face: findings flow back from the file, the status rolls up", async () => {
4118
4109
  const { repoRoot, cleanup } = fixture();
4119
4110
  try {
4120
4111
  const scene = harnessScene(repoRoot);
4121
4112
  const io = new CaptureIo();
4122
- const sync = new FakeSync();
4113
+ const sync = new StubRunner();
4123
4114
  // The review child states `status: APPROVED` in the block (its conclusion is the
4124
4115
  // draft's findings — never printed); the engine derives the capsule status.
4125
4116
  sync.stdout = "status: APPROVED\n";
@@ -4136,7 +4127,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4136
4127
  sync,
4137
4128
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4138
4129
  });
4139
- const outcome = dispatch.step()(specReviewFrame);
4130
+ const outcome = await dispatch.step()(specReviewFrame);
4140
4131
  // the rollup (v1.9: a review never declares its own status) + the findings from
4141
4132
  // the FILE — the read-back is the fix loop's only content channel
4142
4133
  expect(outcome.status).toBe("CHANGES_REQUESTED");
@@ -4156,21 +4147,21 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4156
4147
  const prompt = call.args[call.args.length - 1];
4157
4148
  expect(prompt).toContain("Follow URC:");
4158
4149
  expect(prompt).toContain("- `ROLE`: review");
4159
- expect(prompt).toContain("- `INPUT_DOC`: docs/kairos/specs/s1-design.md");
4150
+ expect(prompt).toContain("- `INPUT_SPEC`: docs/kairos/specs/s1-design.md");
4160
4151
  // the v1.8 per-mode trimming: a review context carries no fix/work keys
4161
- expect(prompt).not.toContain("- `INPUT_FINDINGS`");
4152
+ expect(prompt).not.toContain("- `INPUT_REVIEWS`");
4162
4153
  expect(prompt).not.toContain("- `INPUT_CRITERIA`");
4163
4154
  } finally {
4164
4155
  cleanup();
4165
4156
  }
4166
4157
  });
4167
4158
 
4168
- it("a task review appends the review skill ref — the object {ref} row's slash form", () => {
4159
+ it("a task review appends the review skill ref — the object {ref} row's slash form", async () => {
4169
4160
  const { repoRoot, cleanup } = fixture();
4170
4161
  try {
4171
4162
  const scene = harnessScene(repoRoot);
4172
4163
  const io = new CaptureIo();
4173
- const sync = new FakeSync();
4164
+ const sync = new StubRunner();
4174
4165
  sync.stdout = "status: APPROVED\n";
4175
4166
  writeFileSync(
4176
4167
  path.join(scene.workspace.path, "tasks-1-review-1.json"),
@@ -4185,7 +4176,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4185
4176
  sync,
4186
4177
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4187
4178
  });
4188
- const outcome = dispatch.step()(taskReviewFrame);
4179
+ const outcome = await dispatch.step()(taskReviewFrame);
4189
4180
  // the finding flows back from the FILE; the status rolls up from its severity
4190
4181
  // (blocker → CHANGES_REQUESTED · warn/nit → REVIEW_FIX · none → APPROVED) — a
4191
4182
  // review never declares its own status, so the block's `status: APPROVED` is
@@ -4208,12 +4199,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4208
4199
  }
4209
4200
  });
4210
4201
 
4211
- it("the fix face carries no skill ref — the prompt opens with the template header, never a slash ref (T1)", () => {
4202
+ it("the fix face carries no skill ref — the prompt opens with the template header, never a slash ref (T1)", async () => {
4212
4203
  const { repoRoot, cleanup } = fixture();
4213
4204
  try {
4214
4205
  const scene = harnessScene(repoRoot);
4215
4206
  const io = new CaptureIo();
4216
- const sync = new FakeSync();
4207
+ const sync = new StubRunner();
4217
4208
  sync.stdout = "status: APPROVED\n";
4218
4209
  writeFileSync(
4219
4210
  path.join(scene.workspace.path, "tasks-1-fix-1.json"),
@@ -4243,7 +4234,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4243
4234
  sync,
4244
4235
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4245
4236
  });
4246
- const outcome = dispatch.step()(fixFrame);
4237
+ const outcome = await dispatch.step()(fixFrame);
4247
4238
  expect(outcome.status).toBe("APPROVED");
4248
4239
  const call = sync.calls[0];
4249
4240
  const prompt = call.args[call.args.length - 1];
@@ -4256,12 +4247,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4256
4247
  }
4257
4248
  });
4258
4249
 
4259
- it("T6 — probe B: the fix dispatch prompt carries the strict-schema single sentence — the declaration is the field source, zero extra keys (the child-facing fix shell)", () => {
4250
+ it("T6 — probe B: the fix dispatch prompt carries the strict-schema single sentence — the declaration is the field source, zero extra keys (the child-facing fix shell)", async () => {
4260
4251
  const { repoRoot, cleanup } = fixture();
4261
4252
  try {
4262
4253
  const scene = harnessScene(repoRoot);
4263
4254
  const io = new CaptureIo();
4264
- const sync = new FakeSync();
4255
+ const sync = new StubRunner();
4265
4256
  sync.stdout = "status: APPROVED\n";
4266
4257
  writeFileSync(
4267
4258
  path.join(scene.workspace.path, "tasks-1-fix-1.json"),
@@ -4291,7 +4282,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4291
4282
  sync,
4292
4283
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4293
4284
  });
4294
- const outcome = dispatch.step()(fixFrame);
4285
+ const outcome = await dispatch.step()(fixFrame);
4295
4286
  expect(outcome.status).toBe("APPROVED");
4296
4287
  const call = sync.calls[0];
4297
4288
  const prompt = call.args[call.args.length - 1];
@@ -4307,64 +4298,293 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4307
4298
  }
4308
4299
  });
4309
4300
 
4310
- it("no host harness → BLOCKED over the CDD_BLOCKED channel; a broken child → BLOCKED too", () => {
4301
+ it("D46/§2.9 — the BEHAVIOR pin: every work face spawns the child at cwd = repoRoot (implement · review · fix)", async () => {
4302
+ // The behavior pin guards the SPAWN cwd, the fact the round-context tokens'
4303
+ // repoRoot-relative basis rests on: a child spawned anywhere but the repo root
4304
+ // would resolve every relative token off-root. It stands apart from the
4305
+ // structural pin (repo-root.guard.test.ts — which guards the conversion point);
4306
+ // the two pins cover different facts. This test drives all three work faces and
4307
+ // pins `call.cwd === repoRoot` on each — the review/fix faces had no such read,
4308
+ // so the pin now covers the whole work surface, not implement alone.
4309
+ const { repoRoot, cleanup } = fixture();
4310
+ try {
4311
+ const scene = harnessScene(repoRoot);
4312
+ const io = new CaptureIo();
4313
+ const sync = new StubRunner();
4314
+ sync.stdout = "status: APPROVED\n";
4315
+ // Deterministic read-back inputs per face (the spawn precedes the read-back,
4316
+ // so the cwd pin holds regardless — the drafts keep the outcome clean too).
4317
+ writeFileSync(
4318
+ path.join(scene.workspace.path, "tasks-1-implement.json"),
4319
+ JSON.stringify({
4320
+ status: "APPROVED",
4321
+ artifacts: {
4322
+ report: path.join(scene.workspace.path, "tasks-1-implement-report.md"),
4323
+ test_evidence: path.join(scene.workspace.path, "tasks-1-test-evidence.json"),
4324
+ },
4325
+ }),
4326
+ "utf8",
4327
+ );
4328
+ writeFileSync(
4329
+ path.join(scene.workspace.path, "tasks-1-test-evidence.json"),
4330
+ JSON.stringify({
4331
+ command: "npx vitest run",
4332
+ exit_code: 0,
4333
+ passed: true,
4334
+ warnings_count: 0,
4335
+ typecheck: { command: "tsc --noEmit", exit_code: 0, passed: true },
4336
+ }),
4337
+ "utf8",
4338
+ );
4339
+ writeFileSync(
4340
+ path.join(scene.workspace.path, "tasks-1-review-1.json"),
4341
+ JSON.stringify({ findings: [] }),
4342
+ "utf8",
4343
+ );
4344
+ writeFileSync(
4345
+ path.join(scene.workspace.path, "tasks-1-fix-1.json"),
4346
+ JSON.stringify({
4347
+ status: "APPROVED",
4348
+ artifacts: {
4349
+ report: path.join(scene.workspace.path, "tasks-1-fix-1-report.md"),
4350
+ test_evidence: path.join(scene.workspace.path, "tasks-1-test-evidence.json"),
4351
+ },
4352
+ }),
4353
+ "utf8",
4354
+ );
4355
+ const dispatch = new HarnessDispatch({
4356
+ scene,
4357
+ io,
4358
+ sync,
4359
+ env: { CLAUDE_CODE_SESSION_ID: "s" },
4360
+ });
4361
+ for (const frame of [implementFrame, taskReviewFrame, fixFrame]) {
4362
+ await dispatch.step()(frame);
4363
+ const call = sync.calls[sync.calls.length - 1]!;
4364
+ // the load-bearing spawn fact: cwd IS the repo root, the basis every
4365
+ // repoRoot-relative round-context token resolves against.
4366
+ expect(call.cwd, `the ${frame.phase} face spawns at cwd = repoRoot`).toBe(repoRoot);
4367
+ }
4368
+ // all three work faces were exercised (never a vacuous single-face pin)
4369
+ expect(sync.calls).toHaveLength(3);
4370
+ } finally {
4371
+ cleanup();
4372
+ }
4373
+ });
4374
+
4375
+ it("no host harness → BLOCKED over the CDD_BLOCKED channel; a broken child → BLOCKED too", async () => {
4311
4376
  const { repoRoot, cleanup } = fixture();
4312
4377
  try {
4313
4378
  const scene = harnessScene(repoRoot);
4314
4379
  const io = new CaptureIo();
4315
4380
  const noHost = new HarnessDispatch({ scene, io, env: {} });
4316
- expect(noHost.step()(implementFrame)).toEqual({ status: "BLOCKED" });
4381
+ expect(await noHost.step()(implementFrame)).toEqual({ status: "BLOCKED" });
4317
4382
  expect(io.stderrText).toContain("CDD_BLOCKED: no host harness detected");
4318
4383
  const failed = new HarnessDispatch({
4319
4384
  scene,
4320
4385
  io,
4321
- sync: { run: () => ({ code: 1, stdout: "", stderr: "boom" }) },
4386
+ sync: {
4387
+ run: async () => ({ code: 1, stdout: "", stderr: "boom", termination: null }),
4388
+ },
4322
4389
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4323
4390
  });
4324
- expect(failed.step()(implementFrame)).toEqual({ status: "BLOCKED" });
4391
+ expect(await failed.step()(implementFrame)).toEqual({ status: "BLOCKED" });
4325
4392
  expect(io.stderrText).toContain("child");
4326
4393
  } finally {
4327
4394
  cleanup();
4328
4395
  }
4329
4396
  });
4330
4397
 
4331
- it("a child that exits 0 without the handoff → BLOCKED + CDD_BLOCKED + crash record (nothing clobbered)", () => {
4398
+ it("a child that exits 0 without the handoff → BLOCKED + CDD_BLOCKED + crash record (nothing clobbered)", async () => {
4332
4399
  const { repoRoot, cleanup } = fixture();
4333
4400
  try {
4334
4401
  const scene = harnessScene(repoRoot);
4335
4402
  const io = new CaptureIo();
4336
- const sync = new FakeSync();
4337
- sync.stdout = "status: APPROVED\n";
4403
+ const sync = new StubRunner();
4404
+ sync.stdout = "done — the handoff draft is written\n";
4338
4405
  const dispatch = new HarnessDispatch({
4339
4406
  scene,
4340
4407
  io,
4341
4408
  sync,
4342
4409
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4343
4410
  });
4344
- const outcome = dispatch.step()(implementFrame);
4411
+ const outcome = await dispatch.step()(implementFrame);
4345
4412
  // no carrier → the bookkeep persists nothing: the read-back rejection face
4346
4413
  expect(outcome).toEqual({ status: "BLOCKED" });
4347
4414
  expect(io.stderrText).toContain("CDD_BLOCKED: the handoff draft was not written");
4348
4415
  // the crash record — the same-command resume's decision source
4349
- const crash = readJson<{ attemptedHandoff: string; next: string; cause: string }>(
4350
- path.join(scene.workspace.path, "crash-implement.wave-1.json"),
4351
- );
4416
+ const crash = readJson<{
4417
+ attemptedHandoff: string;
4418
+ next: string;
4419
+ cause: string;
4420
+ stdoutTail: readonly string[];
4421
+ }>(path.join(scene.workspace.path, "crash-implement.wave-1.json"));
4422
+ // the persisted attempted-handoff path is the canonical repoRoot-RELATIVE
4423
+ // shape (P9 T4 §2.7 — the absolute handoffPath syscall form never lands).
4352
4424
  expect(crash.attemptedHandoff).toBe(
4353
- path.join(scene.workspace.path, "tasks-1-implement.json"),
4425
+ path.relative(repoRoot, path.join(scene.workspace.path, "tasks-1-implement.json")),
4354
4426
  );
4355
4427
  expect(crash.next).toBe("cdd implement --tasks 1 --plan <plan>");
4356
4428
  expect(crash.cause).toBe("contract-violation");
4429
+ // the child's stdout tail rides the crash record (P11 T2 — the diagnostic channel;
4430
+ // the child's Return is prose, never parsed for the round's content).
4431
+ expect(crash.stdoutTail).toEqual(["done — the handoff draft is written"]);
4357
4432
  } finally {
4358
4433
  cleanup();
4359
4434
  }
4360
4435
  });
4361
4436
 
4362
- it("a MALFORMED draft → BLOCKED reporting the true cause (malformed JSON), never the misleading 'not written' (D27)", () => {
4437
+ it("a child that exits NON-ZERO → BLOCKED + the crash record reports the real death (exitCode / cause / stdoutTail)", async () => {
4363
4438
  const { repoRoot, cleanup } = fixture();
4364
4439
  try {
4365
4440
  const scene = harnessScene(repoRoot);
4366
4441
  const io = new CaptureIo();
4367
- const sync = new FakeSync();
4442
+ const sync = new StubRunner();
4443
+ // the child died with code 7 and wrote no draft — the death facts, not the
4444
+ // read-back face's exit-0/contract-violation shape, ride the crash record
4445
+ sync.code = 7;
4446
+ sync.stdout = "boom — the child died before writing\n";
4447
+ const dispatch = new HarnessDispatch({
4448
+ scene,
4449
+ io,
4450
+ sync,
4451
+ env: { CLAUDE_CODE_SESSION_ID: "s" },
4452
+ });
4453
+ const outcome = await dispatch.step()(implementFrame);
4454
+ expect(outcome).toEqual({ status: "BLOCKED" });
4455
+ expect(io.stderrText).toContain("child");
4456
+ const crash = readJson<{
4457
+ exitCode: number;
4458
+ cause: string;
4459
+ stdoutTail: readonly string[];
4460
+ lastSample: SampleRecord | null;
4461
+ }>(path.join(scene.workspace.path, "crash-implement.wave-1.json"));
4462
+ // the record tells the truth: the dead child's OWN exit code and the child-exit
4463
+ // cause — never the read-back face's 0 / contract-violation (T2 misreport fix).
4464
+ expect(crash.exitCode).toBe(7);
4465
+ expect(crash.cause).toBe("child-exit");
4466
+ expect(crash.stdoutTail).toEqual(["boom — the child died before writing"]);
4467
+ // the child-exit face explicitly passes `termination: null` — its crash record
4468
+ // carries no last sample (§4.2: the sample rides WITH the termination).
4469
+ expect(crash.lastSample).toBeNull();
4470
+ } finally {
4471
+ cleanup();
4472
+ }
4473
+ });
4474
+
4475
+ it("a TERMINATED round → TIMEOUT + the crash record carries the termination facts (cause / last sample / null exitCode)", async () => {
4476
+ const { repoRoot, cleanup } = fixture();
4477
+ try {
4478
+ const scene = harnessScene(repoRoot);
4479
+ const io = new CaptureIo();
4480
+ const sync = new StubRunner();
4481
+ // The stub mimes the stalled kill exactly as the terminator reports it: the
4482
+ // killed child's exit code is null, and the termination fact rides whole
4483
+ // (cause + the in-memory last sample — zero heartbeat re-read).
4484
+ const lastSample: SampleRecord = {
4485
+ sampledAt: 1_700_000_000,
4486
+ groupCpuMs: 120,
4487
+ newestMtimeMs: 1_700_000_500,
4488
+ verdict: "stalled",
4489
+ };
4490
+ sync.code = null;
4491
+ sync.termination = { cause: "stalled", lastSample };
4492
+ const dispatch = new HarnessDispatch({
4493
+ scene,
4494
+ io,
4495
+ sync,
4496
+ env: { CLAUDE_CODE_SESSION_ID: "s" },
4497
+ });
4498
+ const outcome = await dispatch.step()(implementFrame);
4499
+ // §4.3 — the derived status: a termination ⇒ TIMEOUT (never BLOCKED).
4500
+ expect(outcome).toEqual({ status: "TIMEOUT" });
4501
+ // The reason rides the CDD_BLOCKED channel with its cause.
4502
+ expect(io.stderrText).toContain("CDD_BLOCKED:");
4503
+ expect(io.stderrText).toContain("stalled");
4504
+ const crash = readJson<{
4505
+ exitCode: number | null;
4506
+ cause: string;
4507
+ stdoutTail: readonly string[];
4508
+ stderrTail: readonly string[];
4509
+ lastSample: SampleRecord | null;
4510
+ next: string;
4511
+ }>(path.join(scene.workspace.path, "crash-implement.wave-1.json"));
4512
+ // The record tells the truth: the killed child has NO exit code (null verbatim,
4513
+ // never folded to 1), the derived cause, and the last sample riding in memory.
4514
+ expect(crash.exitCode).toBeNull();
4515
+ expect(crash.cause).toBe("stalled");
4516
+ expect(crash.lastSample).toEqual(lastSample);
4517
+ expect(crash.next).toBe("cdd implement --tasks 1 --plan <plan>");
4518
+ } finally {
4519
+ cleanup();
4520
+ }
4521
+ });
4522
+
4523
+ it("the termination leg is judged BEFORE the child-exit leg — a killed child with a non-zero-null code never folds into `child-exit`", async () => {
4524
+ // The judging-order hard rule (§4.3): a terminated round's outcome carries
4525
+ // code null AND termination non-null — the termination check must win, or the
4526
+ // crash cause would be falsified to `child-exit`. The pin below drives the
4527
+ // aliasing case: even a stub that reports BOTH a non-zero code and a
4528
+ // termination still concludes by the termination fact.
4529
+ const { repoRoot, cleanup } = fixture();
4530
+ try {
4531
+ const scene = harnessScene(repoRoot);
4532
+ const io = new CaptureIo();
4533
+ const sync = new StubRunner();
4534
+ sync.code = 143;
4535
+ sync.termination = { cause: "over-budget", lastSample: null };
4536
+ const dispatch = new HarnessDispatch({
4537
+ scene,
4538
+ io,
4539
+ sync,
4540
+ env: { CLAUDE_CODE_SESSION_ID: "s" },
4541
+ });
4542
+ const outcome = await dispatch.step()(implementFrame);
4543
+ expect(outcome).toEqual({ status: "TIMEOUT" });
4544
+ const crash = readJson<{ exitCode: number | null; cause: string }>(
4545
+ path.join(scene.workspace.path, "crash-implement.wave-1.json"),
4546
+ );
4547
+ expect(crash.cause).toBe("over-budget");
4548
+ } finally {
4549
+ cleanup();
4550
+ }
4551
+ });
4552
+
4553
+ it("the read-back rejection face keeps its BLOCKED conclusion verbatim — the death-facts default carries `termination: null`", async () => {
4554
+ // §4.3 — the status derives from the death facts (no status parameter): the
4555
+ // read-back caller passes the defaults (termination null) ⇒ BLOCKED, byte-for-
4556
+ // byte today's behavior.
4557
+ const { repoRoot, cleanup } = fixture();
4558
+ try {
4559
+ const scene = harnessScene(repoRoot);
4560
+ const io = new CaptureIo();
4561
+ const sync = new StubRunner();
4562
+ sync.stdout = "done — the handoff draft is written\n";
4563
+ const dispatch = new HarnessDispatch({
4564
+ scene,
4565
+ io,
4566
+ sync,
4567
+ env: { CLAUDE_CODE_SESSION_ID: "s" },
4568
+ });
4569
+ const outcome = await dispatch.step()(implementFrame);
4570
+ expect(outcome).toEqual({ status: "BLOCKED" });
4571
+ expect(io.stderrText).toContain("CDD_BLOCKED: the handoff draft was not written");
4572
+ const crash = readJson<{ cause: string; lastSample: SampleRecord | null }>(
4573
+ path.join(scene.workspace.path, "crash-implement.wave-1.json"),
4574
+ );
4575
+ expect(crash.cause).toBe("contract-violation");
4576
+ expect(crash.lastSample).toBeNull();
4577
+ } finally {
4578
+ cleanup();
4579
+ }
4580
+ });
4581
+
4582
+ it("a MALFORMED draft → BLOCKED reporting the true cause (malformed JSON), never the misleading 'not written' (D27)", async () => {
4583
+ const { repoRoot, cleanup } = fixture();
4584
+ try {
4585
+ const scene = harnessScene(repoRoot);
4586
+ const io = new CaptureIo();
4587
+ const sync = new StubRunner();
4368
4588
  sync.stdout = "status: APPROVED\n";
4369
4589
  // the child wrote an unparseable draft at OUTPUT_HANDOFF — present but corrupt.
4370
4590
  // The tri-state read reports the true cause; a corrupt draft is never misreported
@@ -4380,7 +4600,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4380
4600
  sync,
4381
4601
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4382
4602
  });
4383
- const outcome = dispatch.step()(implementFrame);
4603
+ const outcome = await dispatch.step()(implementFrame);
4384
4604
  expect(outcome).toEqual({ status: "BLOCKED" });
4385
4605
  expect(io.stderrText).toContain("CDD_BLOCKED: the handoff draft at");
4386
4606
  expect(io.stderrText).toContain("is malformed JSON");
@@ -4390,12 +4610,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4390
4610
  }
4391
4611
  });
4392
4612
 
4393
- it("a schema-violating draft → BLOCKED with the draft preserved untouched (no-overwrite on failure)", () => {
4613
+ it("a schema-violating draft → BLOCKED with the draft preserved untouched (no-overwrite on failure)", async () => {
4394
4614
  const { repoRoot, cleanup } = fixture();
4395
4615
  try {
4396
4616
  const scene = harnessScene(repoRoot);
4397
4617
  const io = new CaptureIo();
4398
- const sync = new FakeSync();
4618
+ const sync = new StubRunner();
4399
4619
  sync.stdout = "status: APPROVED\n";
4400
4620
  // the child wrote a draft MISSING the required `status` — the `work` subset's
4401
4621
  // read-back refuses it
@@ -4407,7 +4627,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4407
4627
  sync,
4408
4628
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4409
4629
  });
4410
- const outcome = dispatch.step()(implementFrame);
4630
+ const outcome = await dispatch.step()(implementFrame);
4411
4631
  expect(outcome).toEqual({ status: "BLOCKED" });
4412
4632
  expect(io.stderrText).toContain("violates the work schema");
4413
4633
  expect(io.stderrText).toContain("status: required");
@@ -4421,12 +4641,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4421
4641
  }
4422
4642
  });
4423
4643
 
4424
- it("a missing/violating test-evidence file rewrites the draft to BLOCKED (the evidence read-back)", () => {
4644
+ it("a missing/violating test-evidence file rewrites the draft to BLOCKED (the evidence read-back)", async () => {
4425
4645
  const { repoRoot, cleanup } = fixture();
4426
4646
  try {
4427
4647
  const scene = harnessScene(repoRoot);
4428
4648
  const io = new CaptureIo();
4429
- const sync = new FakeSync();
4649
+ const sync = new StubRunner();
4430
4650
  sync.stdout = "status: APPROVED\n";
4431
4651
  // the implement draft is valid, but NO evidence file was written — the evidence
4432
4652
  // gate (v1.9) turns the round BLOCKED with the carrier preserved
@@ -4444,17 +4664,24 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4444
4664
  sync,
4445
4665
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4446
4666
  });
4447
- const outcome = dispatch.step()(implementFrame);
4667
+ const outcome = await dispatch.step()(implementFrame);
4448
4668
  expect(outcome.status).toBe("BLOCKED");
4449
4669
  // the carrier is materialized (the child's work preserved) but rewritten BLOCKED.
4450
4670
  // The free-named declared paths are corrected to the canonical OUTPUT_* names
4451
4671
  // (find #5 — the engine derives, never books a child-reported path): the report
4452
- // and evidence book their canonical tasks-1- names with the deviations surfaced.
4672
+ // and evidence book their canonical tasks-1- names (repoRoot-RELATIVE — §2.7)
4673
+ // with the deviations surfaced; the non-prescribed `brief` slot passes verbatim.
4453
4674
  expect(outcome.carrier).toEqual({
4454
4675
  artifacts: {
4455
4676
  brief: "/b",
4456
- report: path.join(scene.workspace.path, "tasks-1-implement-report.md"),
4457
- test_evidence: path.join(scene.workspace.path, "tasks-1-test-evidence.json"),
4677
+ report: path.relative(
4678
+ repoRoot,
4679
+ path.join(scene.workspace.path, "tasks-1-implement-report.md"),
4680
+ ),
4681
+ test_evidence: path.relative(
4682
+ repoRoot,
4683
+ path.join(scene.workspace.path, "tasks-1-test-evidence.json"),
4684
+ ),
4458
4685
  },
4459
4686
  status: "BLOCKED",
4460
4687
  failure_category: "evidence-contract",
@@ -4472,12 +4699,12 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4472
4699
  }
4473
4700
  });
4474
4701
 
4475
- it("a MALFORMED test-evidence file → BLOCKED reporting the true cause (malformed JSON), never the misleading 'missing' (D27)", () => {
4702
+ it("a MALFORMED test-evidence file → BLOCKED reporting the true cause (malformed JSON), never the misleading 'missing' (D27)", async () => {
4476
4703
  const { repoRoot, cleanup } = fixture();
4477
4704
  try {
4478
4705
  const scene = harnessScene(repoRoot);
4479
4706
  const io = new CaptureIo();
4480
- const sync = new FakeSync();
4707
+ const sync = new StubRunner();
4481
4708
  sync.stdout = "status: APPROVED\n";
4482
4709
  // a VALID draft + a PRESENT-but-corrupt evidence file — the tri-state read
4483
4710
  // reports the true cause; a corrupt file is never misreported as absent
@@ -4502,7 +4729,7 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4502
4729
  sync,
4503
4730
  env: { CLAUDE_CODE_SESSION_ID: "s" },
4504
4731
  });
4505
- const outcome = dispatch.step()(implementFrame);
4732
+ const outcome = await dispatch.step()(implementFrame);
4506
4733
  expect(outcome.status).toBe("BLOCKED");
4507
4734
  expect(outcome.carrier?.failure_category).toBe("evidence-contract");
4508
4735
  const notes = (outcome.carrier?.notes ?? []) as string[];
@@ -4514,13 +4741,15 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4514
4741
  }
4515
4742
  });
4516
4743
 
4517
- it("find #9 — the branch fix's OUTPUT_* artifacts are the line-keyed names (report `branch-fix-{round}-report.md` · evidence `branch-test-evidence.json`), never the range", () => {
4744
+ it("find #9 — the branch fix's OUTPUT_* artifacts are the line-keyed names (report `branch-fix-{round}-report.md` · evidence `branch-test-evidence.json`), never the range", async () => {
4518
4745
  const { repoRoot, cleanup } = fixture();
4519
4746
  try {
4520
4747
  const scene = harnessScene(repoRoot);
4521
4748
  const io = new CaptureIo();
4522
- const sync = new FakeSync();
4523
- sync.stdout = "status: APPROVED\nartifacts: report=/r test_evidence=/t\n";
4749
+ const sync = new StubRunner();
4750
+ // the child returns prose — the engine zero-parses stdout (the draft
4751
+ // written below is the round's machine-readable result)
4752
+ sync.stdout = "Implemented the branch fix; the handoff draft is written.\n";
4524
4753
  writeFileSync(
4525
4754
  path.join(scene.workspace.path, "branch-fix-1.json"),
4526
4755
  JSON.stringify({
@@ -4560,19 +4789,17 @@ describe("the HarnessDispatch — the production dispatch default", () => {
4560
4789
  params: { round: 1 },
4561
4790
  key: "branch",
4562
4791
  };
4563
- const outcome = dispatch.step()(frame);
4792
+ const outcome = await dispatch.step()(frame);
4564
4793
  expect(io.stderrText).toBe("");
4565
4794
  expect(outcome.status).toBe("APPROVED");
4566
4795
  const prompt = sync.calls[0]!.args[sync.calls[0]!.args.length - 1];
4567
4796
  // find #9 — the prescribed artifact names are line-keyed: the round rides the
4568
4797
  // name (branch-fix-1-report.md), the evidence is the line's single file
4569
- // (branch-test-evidence.json); the range token appears NOWHERE in the paths
4570
- expect(prompt).toContain(
4571
- `- \`OUTPUT_REPORT\`: ${path.join(scene.workspace.path, "branch-fix-1-report.md")}`,
4572
- );
4573
- expect(prompt).toContain(
4574
- `- \`OUTPUT_EVIDENCE\`: ${path.join(scene.workspace.path, "branch-test-evidence.json")}`,
4575
- );
4798
+ // (branch-test-evidence.json); the range token appears NOWHERE in the paths.
4799
+ // D46 — the token is repoRoot-relative (the child spawned at cwd = repoRoot).
4800
+ const wsRel = path.relative(repoRoot, scene.workspace.path);
4801
+ expect(prompt).toContain(`- \`OUTPUT_REPORT\`: ${wsRel}/branch-fix-1-report.md`);
4802
+ expect(prompt).toContain(`- \`OUTPUT_EVIDENCE\`: ${wsRel}/branch-test-evidence.json`);
4576
4803
  expect(prompt).not.toContain("aaaaaaaa..bbbbbbbb");
4577
4804
  } finally {
4578
4805
  cleanup();
@@ -4605,17 +4832,16 @@ describe("T9 — the destroy-list zero-residual sweep (spec §6.3 cross-referenc
4605
4832
 
4606
4833
  it("the retired commit-sha vocabulary carries zero residual across the engine source (spec §7.4)", () => {
4607
4834
  // The sha surface retired engine-wide (§2): no source file names the retired
4608
- // scope tokens (WAVE_BASE / FIX_BASE / INPUT_RANGE / INPUT_PLAN) or the
4609
- // retired git/BranchRef members (revParseHead / BranchRef) — the GitClient
4610
- // holds only topLevel + isClean, the review carries the single doc anchor
4611
- // (INPUT_DOC), and the branch scope rides the base artifact's BASE_BRANCH.
4612
- // The pin is construction-establishment-level: it fails if any retired name
4613
- // resurfaces in a non-test source file.
4835
+ // scope tokens (WAVE_BASE / FIX_BASE / INPUT_RANGE) or the retired git/BranchRef
4836
+ // members (revParseHead / BranchRef) — the GitClient holds only topLevel +
4837
+ // isClean, the review carries the kind-named doc anchors (INPUT_PLAN / INPUT_SPEC,
4838
+ // resurrected as the semantic round-context tokens), and the branch scope rides
4839
+ // the base artifact's BASE_BRANCH. The pin is construction-establishment-level:
4840
+ // it fails if any retired name resurfaces in a non-test source file.
4614
4841
  const retiredShaVocab = [
4615
4842
  "WAVE_BASE",
4616
4843
  "FIX_BASE",
4617
4844
  "INPUT_RANGE",
4618
- "INPUT_PLAN",
4619
4845
  "revParseHead",
4620
4846
  "BranchRef",
4621
4847
  ] as const;
@@ -4625,19 +4851,47 @@ describe("T9 — the destroy-list zero-residual sweep (spec §6.3 cross-referenc
4625
4851
  }
4626
4852
  }
4627
4853
  });
4854
+
4855
+ it("the retired process-seam + dead-cause vocabulary carries zero residual across the engine source", () => {
4856
+ // The child seam is asynchronous and value-shaped (P12 T1): the synchronous
4857
+ // process face (SyncProcess/SyncRunner) and execa's synchronous entry
4858
+ // (execaSync) are retired whole — the terminator holds the process lifecycle.
4859
+ // The three dead crash causes (`engine-timeout` / `engine-over-budget` /
4860
+ // `child-signal`) had zero writers and are retired in favour of the single
4861
+ // termination-cause vocabulary. The user-facing `detached` option is never set
4862
+ // (it would short-circuit execa's parent-exit cleanup — group kill rides
4863
+ // `killDescendants` alone), so the option-key form must not appear either.
4864
+ const retiredProcessVocab = [
4865
+ "execaSync",
4866
+ "SyncProcess",
4867
+ "SyncRunner",
4868
+ "engine-timeout",
4869
+ "engine-over-budget",
4870
+ "child-signal",
4871
+ "detached:",
4872
+ ] as const;
4873
+ for (const [file, text] of engineSourceTexts()) {
4874
+ for (const name of retiredProcessVocab) {
4875
+ expect(text, `${name} must not survive in ${file}`).not.toContain(name);
4876
+ }
4877
+ }
4878
+ });
4628
4879
  });
4629
4880
 
4630
- /** The fake child-process seam — records every invocation, ans answers a canned stdout. */
4631
- class FakeSync implements SyncProcess {
4632
- calls: { command: string; args: string[]; cwd: string }[] = [];
4881
+ /** The stub child-runner seam — records every dispatch's `ChildRun`, and answers a
4882
+ * canned stdout. */
4883
+ class StubRunner implements ChildRunner {
4884
+ calls: ChildRun[] = [];
4633
4885
  stdout = "";
4634
-
4635
- run(
4636
- command: string,
4637
- args: readonly string[],
4638
- cwd: string,
4639
- ): { code: number; stdout: string; stderr: string } {
4640
- this.calls.push({ command, args: [...args], cwd });
4641
- return { code: 0, stdout: this.stdout, stderr: "" };
4886
+ /** The canned child exit code (default 0 = success; null = the child was killed
4887
+ * and has no exit code) — drives the crash-record face's death facts. */
4888
+ code: number | null = 0;
4889
+ /** The canned termination fact (default null = the round ended by itself) — a
4890
+ * non-null value drives the terminated-round face's TIMEOUT + crash facts. */
4891
+ termination: Termination | null = null;
4892
+
4893
+ async run(run: ChildRun): Promise<ChildOutcome> {
4894
+ this.calls.push(run);
4895
+ return { code: this.code, stdout: this.stdout, stderr: "", termination: this.termination };
4642
4896
  }
4643
4897
  }