@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
@@ -16,18 +16,30 @@
16
16
  // bare functions.
17
17
 
18
18
  import process from "node:process";
19
- import { execaSync } from "execa";
20
19
  import { printParseErrorCode } from "jsonc-parser";
21
20
  import { ConfigLoader } from "../infra/config.ts";
21
+ import type { RepoRoot } from "../infra/root.ts";
22
22
  import type { HandoffFamily } from "../infra/runtime.ts";
23
23
  import type { Workspace } from "../infra/workspace.ts";
24
24
  import type { TemplateValues, WorkMode } from "../render/templates.ts";
25
25
  import { TemplateAssembler } from "../render/templates.ts";
26
26
  import type { HandoffSchemaFace } from "../session/handoff-schema.ts";
27
27
  import { HandoffSchema } from "../session/handoff-schema.ts";
28
- import type { Ledger, OpType, RoundStatus } from "../session/ledger.ts";
28
+ import type { CrashCause, Ledger, OpType, RoundStatus } from "../session/ledger.ts";
29
+ import { RoundNaming } from "../session/round-naming.ts";
29
30
  import type { DispatchOutcome, DispatchStep, OpenFrame } from "../session/run.ts";
30
31
  import { DISPATCH, HOSTS, HostDetect, type HostId, type HostReferenceTable, REFS } from "./host.ts";
32
+ import {
33
+ type ChildRunner,
34
+ type Termination,
35
+ TerminationPolicy,
36
+ Terminator,
37
+ } from "./termination.ts";
38
+
39
+ /** The crash-record stdout-tail cap (P11 T2) — the child's last STDOUT_TAIL_MAX
40
+ * non-empty stdout lines ride the crash record's `stdoutTail` (the diagnostic
41
+ * channel; the child's Return is prose, never the round's content). */
42
+ const STDOUT_TAIL_MAX = 40;
31
43
 
32
44
  // ---------------------------------------------------------------------------
33
45
  // the stable seams — the shared faces the composition root + the lifecycle ride
@@ -41,64 +53,9 @@ export interface CliIo {
41
53
  }
42
54
 
43
55
  // ---------------------------------------------------------------------------
44
- // the sync process seam + the harness dispatch (the production dispatch default)
56
+ // the harness dispatch (the production dispatch default)
45
57
  // ---------------------------------------------------------------------------
46
58
 
47
- /** The sync child-process face — the fail-open subprocess seam the harness dispatch
48
- * runs through (a non-zero/broken child rides the code, never a throw). */
49
- export interface SyncProcess {
50
- run(
51
- command: string,
52
- args: readonly string[],
53
- cwd: string,
54
- ): { code: number; stdout: string; stderr: string };
55
- }
56
-
57
- /** SyncRunner — the unbounded sync child channel (spec §14 · D36): execa's
58
- * synchronous face, which imposes no output-buffer ceiling — the whole-buffer
59
- * cap class the retired built-in call hit (a fixed 1 MiB default, the W1
60
- * `child claude returned no status line` truncation) does not exist here. The
61
- * face stays synchronous (the T8 lifecycle's DispatchStep seam is one dispatch,
62
- * one advance) and keeps the injected `SyncProcess` shape byte-for-byte: a
63
- * non-zero/broken child rides the code, never a throw — `reject: false` surfaces
64
- * the failure as a result, and `stripFinalNewline: false` keeps the child's
65
- * stdout verbatim (the `RETURN_STDOUT_BLOCK` tail stays intact). The adapter is
66
- * a pure `#collect` read: no buffering to bound, no worker, no concurrency. */
67
- export class SyncRunner implements SyncProcess {
68
- run(
69
- command: string,
70
- args: readonly string[],
71
- cwd: string,
72
- ): { code: number; stdout: string; stderr: string } {
73
- return this.#collect(command, args, cwd);
74
- }
75
-
76
- /** The synchronous collection — execa's sync face with the three options the
77
- * fail-open `SyncProcess` contract needs: `reject: false` (a failed child is a
78
- * result, never a throw), `stripFinalNewline: false` (byte-verbatim stdout), and
79
- * the default unbounded output buffer (the cap class is retired). The result
80
- * reads back into the same `{code, stdout, stderr}` face — `exitCode ?? 1` is the
81
- * exit code; stderr is the child's own stream when it wrote one, else the execa
82
- * diagnostic (a spawn failure like ENOENT writes nothing, so its reason rides the
83
- * `shortMessage` — the fail-open face keeps a reason text, never an empty block). */
84
- #collect(
85
- command: string,
86
- args: readonly string[],
87
- cwd: string,
88
- ): { code: number; stdout: string; stderr: string } {
89
- const result = execaSync(command, [...args], {
90
- cwd,
91
- reject: false,
92
- stripFinalNewline: false,
93
- });
94
- return {
95
- code: result.exitCode ?? 1,
96
- stdout: result.stdout ?? "",
97
- stderr: result.stderr || (result.failed ? (result.shortMessage ?? "") : ""),
98
- };
99
- }
100
- }
101
-
102
59
  /** The environment face the harness dispatch detects the host against. */
103
60
  export type ProcessEnvLike = Record<string, string | undefined>;
104
61
 
@@ -112,6 +69,11 @@ export interface DispatchScene {
112
69
  planPath: string | null;
113
70
  briefPath: string | null;
114
71
  baseBranch?: string | null;
72
+ /** The plan's design-spec reference (the `spec:` front-matter link target), read
73
+ * from the plan document at the CLI seam — the plan-review round context's extra
74
+ * read input (a plan review judges the plan against its spec). Null off the plan
75
+ * scene (the slot stays empty and the assembler drops it). */
76
+ specLink?: string | null;
115
77
  }
116
78
 
117
79
  /**
@@ -120,45 +82,51 @@ export interface DispatchScene {
120
82
  * surface keeps its name). `step()` returns the DispatchStep the lifecycle runs, which
121
83
  * assembles the dispatch prompt (the render template-contract data plane) from the
122
84
  * frame, runs the host harness CLI (the harness-contract rows: cli + invoke flags +
123
- * the phase's skill-ref slash form) and parses the child's return block back into the
124
- * lifecycle's outcome. Detection reads the harness-contract detect markers from the
125
- * injected env — empty host → a BLOCKED outcome over the CDD_BLOCKED channel (never a
126
- * thrown dispatch).
85
+ * the phase's skill-ref slash form) and reads the child's OUTPUT_HANDOFF draft back
86
+ * into the lifecycle's outcome (the child's Return is prose, never parsed). Detection
87
+ * reads the harness-contract detect markers from the injected env — empty host → a
88
+ * BLOCKED outcome over the CDD_BLOCKED channel (never a thrown dispatch).
127
89
  */
128
90
  export class CliLifecycle {
129
91
  readonly #env: ProcessEnvLike;
130
- readonly #cwd: string;
131
- readonly #sync: SyncProcess;
92
+ readonly #sync: ChildRunner;
132
93
  readonly #config: ConfigLoader;
133
94
  readonly #template: TemplateAssembler;
134
95
  readonly #io: CliIo;
135
96
  readonly #scene: DispatchScene;
136
- readonly #findings: string | null;
97
+ readonly #reviews: string | null;
98
+ /** The round-naming single source (P11 T4) — every prescribed artifact name of a
99
+ * frame derives here (the report/evidence/brief names + the family op), so the
100
+ * lifecycle and the dry-run preview name the same artifacts by one rule. */
101
+ readonly #naming: RoundNaming;
137
102
  /** The handoff-schema face — stateless, one shared instance (the read-back
138
103
  * validator + the injected prompt text). */
139
104
  readonly #handoffSchema = new HandoffSchema();
105
+ /** The current dispatch's child-stdout diagnostic tail (the crash-record channel,
106
+ * P11 T2) — set in #dispatch after the child returns, read by #reject. The child's
107
+ * Return is prose; the engine never parses it — this is the failure channel only. */
108
+ #stdoutTail: readonly string[] = [];
140
109
 
141
110
  constructor(opts: {
142
111
  env?: ProcessEnvLike;
143
- cwd?: string;
144
- sync?: SyncProcess;
112
+ sync?: ChildRunner;
145
113
  config?: ConfigLoader;
146
114
  template?: TemplateAssembler;
147
115
  io?: CliIo;
148
116
  scene: DispatchScene;
149
- findings?: string | null;
117
+ reviews?: string | null;
150
118
  }) {
151
119
  this.#env = opts.env ?? process.env;
152
- this.#cwd = opts.cwd ?? process.cwd();
153
- this.#sync = opts.sync ?? new SyncRunner();
120
+ this.#scene = opts.scene;
121
+ this.#naming = new RoundNaming(opts.scene.workspace);
122
+ this.#sync = opts.sync ?? new Terminator();
154
123
  this.#config = opts.config ?? new ConfigLoader();
155
124
  this.#template = opts.template ?? new TemplateAssembler();
156
125
  this.#io = opts.io ?? {
157
126
  stdout: (t) => process.stdout.write(t),
158
127
  stderr: (t) => process.stderr.write(t),
159
128
  };
160
- this.#scene = opts.scene;
161
- this.#findings = opts.findings ?? null;
129
+ this.#reviews = opts.reviews ?? null;
162
130
  }
163
131
 
164
132
  /** The host-harness id detected from the env — "claude" | "cursor" | "pi" | "" —
@@ -175,9 +143,9 @@ export class CliLifecycle {
175
143
  }
176
144
 
177
145
  /** One dispatch — prompt from the template plane + the frame, host child via
178
- * the harness-contract rows, the child's write-back read in (v1.9: the draft at
179
- * OUTPUT_HANDOFF is the round's content — the block is the pointer). */
180
- #dispatch(frame: OpenFrame): DispatchOutcome {
146
+ * the harness-contract rows, the child's write-back read in (the draft at
147
+ * OUTPUT_HANDOFF is the round's content; the child's Return is prose, never parsed). */
148
+ async #dispatch(frame: OpenFrame): Promise<DispatchOutcome> {
181
149
  const host = this.detectHost();
182
150
  if (host === "") {
183
151
  this.#io.stderr(
@@ -195,27 +163,56 @@ export class CliLifecycle {
195
163
  // prompt positional (claude -p consumes the whole first positional as the prompt;
196
164
  // a standalone ref arg after the flags would be swallowed, losing everything after
197
165
  // the ref) — the prompt assembly is data, never a code assumption.
198
- const result = this.#sync.run(
199
- cliName,
200
- [...args, this.#childPrompt(row.promptForm, ref, prompt)],
201
- this.#cwd,
202
- );
203
- if (result.code !== 0) {
204
- this.#io.stderr(`CDD_BLOCKED: child ${cliName} exited ${result.code}\n`);
205
- return { status: "BLOCKED" };
166
+ const result = await this.#sync.run({
167
+ command: cliName,
168
+ args: [...args, this.#childPrompt(row.promptForm, ref, prompt)],
169
+ // The two paths the dispatch needs share ONE source (this workspace, held only
170
+ // here): the child's spawn directory is the repo root, and the heartbeat lands
171
+ // in this dispatch's workspace. The same `cwd` is also the tree-leg scan root,
172
+ // and the heartbeat path is the sampler's own write — the scan root ≡ child cwd
173
+ // correspondence is structural, never a convention.
174
+ cwd: this.#scene.workspace.root.repoRoot,
175
+ heartbeatPath: this.#scene.workspace.resolve("liveness.json"),
176
+ policy: TerminationPolicy.of(frame.phase),
177
+ });
178
+ // The child's stdout rides the diagnostic channel — #reject reads it into the
179
+ // crash record on either failure face. Child Return is prose: the engine never
180
+ // parses it; the round's content is the OUTPUT_HANDOFF draft, read in #reconstruct.
181
+ this.#stdoutTail = this.#tailOf(result.stdout);
182
+ // The termination leg FIRST (§4.3 — the judging order is a hard rule): a killed
183
+ // child's exit code is null, so `null !== 0` is true — judging the child-exit leg
184
+ // first would fold every terminated round into `child-exit` and falsify the crash
185
+ // cause. `termination !== null` → the round concludes TIMEOUT (the words table's
186
+ // status is already there), the reason rides the CDD_BLOCKED channel, and the
187
+ // failure face (no `next:` line) follows from the status alone.
188
+ if (result.termination !== null) {
189
+ return this.#reject(
190
+ frame,
191
+ this.#scene.ledger.handoffPath(this.#opOf(frame), frame.type, frame.params),
192
+ `child ${cliName} was terminated: ${result.termination.cause}`,
193
+ // the terminated round's OWN death facts — the termination rides whole
194
+ // (cause + last sample), the signalled child's code is null verbatim
195
+ { exitCode: result.code, cause: result.termination.cause, termination: result.termination },
196
+ );
206
197
  }
207
- // The three-line block is the child's termination handshake — a child that exits 0
208
- // without a status line misbehaved (the abnormal face owns it; no draft read).
209
- if (!/^status:\s*\S+/m.test(result.stdout)) {
210
- this.#io.stderr(`CDD_BLOCKED: child ${cliName} returned no status line\n`);
211
- return { status: "BLOCKED" };
198
+ if (result.code !== 0) {
199
+ return this.#reject(
200
+ frame,
201
+ this.#scene.ledger.handoffPath(this.#opOf(frame), frame.type, frame.params),
202
+ `child ${cliName} exited ${result.code}`,
203
+ // the dead child's OWN death facts — never the read-back face's defaults;
204
+ // this branch sits AFTER the termination leg, so the termination is null
205
+ { exitCode: result.code, cause: "child-exit", termination: null },
206
+ );
212
207
  }
213
- return this.#reconstruct(frame, this.#parseBlockReturn(result.stdout));
208
+ return this.#reconstruct(frame);
214
209
  }
215
210
 
216
- /** The work-mode of a frame phase — branch-review rides the review family. */
211
+ /** The work-mode of a frame phase — branch-review rides the review family. The
212
+ * mapping itself lives in `RoundNaming` (the artifact stems key on it); this is
213
+ * the lifecycle's read of that single source. */
217
214
  #opOf(frame: OpenFrame): OpType {
218
- return frame.phase === "branch-review" ? "review" : frame.phase;
215
+ return this.#naming.op(frame);
219
216
  }
220
217
 
221
218
  /** The dispatch-table work-mode (ROLE) of a frame — the spec/plan fix faces ride
@@ -276,30 +273,48 @@ export class CliLifecycle {
276
273
  const role = this.#roleOf(frame);
277
274
  const params = frame.params;
278
275
  const isReview = frame.phase === "review" || frame.phase === "branch-review";
279
- const docPath = frame.target.kind === "doc" ? frame.target.doc : null;
276
+ const docPath =
277
+ frame.target.kind === "plan" || frame.target.kind === "spec" ? frame.target.doc : null;
280
278
  const isWave = frame.type === "wave";
281
279
  return {
282
280
  ROLE: role,
283
281
  // v1.22 (wave-unitary): the wave face's scope IS the wave (the whole task list)
284
282
  // — the round context speaks the UNIT, `WAVE`; the line faces carry their own
285
- // read-side identity (INPUT_DOC — the doc/branch line's own token under the
286
- // wave-unitary model).
283
+ // read-side identity (INPUT_PLAN / INPUT_SPEC — the doc/branch line's kind-named
284
+ // tokens under the wave-unitary model).
287
285
  WAVE: isWave ? (params.tasks ?? "") : "",
288
286
  // The wave-brief read input — the ONE engine-rendered brief of the current
289
287
  // dispatch (the unconditional re-extract at every dispatch makes it the pure
290
288
  // read face of the wave line — §4.2); the non-wave faces carry no brief path
291
289
  // (the slot stays empty, never emitted).
292
- INPUT_WAVE_BRIEF: isWave ? (scene.briefPath ?? "") : "",
293
- // v1.9: INPUT_FINDINGS is fix/docs-fix only — the open findings of the source
294
- // review; a review writes its own draft (INPUT_FINDINGS === OUTPUT_HANDOFF
290
+ INPUT_WAVE_BRIEF: isWave ? this.#rel(scene.briefPath ?? "") : "",
291
+ // v1.9: INPUT_REVIEWS is fix/docs-fix only — the source review's handoff
292
+ // carrier; a review writes its own draft (INPUT_REVIEWS === OUTPUT_HANDOFF
295
293
  // would be a short-circuit).
296
- INPUT_FINDINGS:
294
+ INPUT_REVIEWS:
297
295
  op === "fix"
298
- ? (this.#findings ?? scene.ledger.handoffPath("review", frame.type, params))
296
+ ? this.#rel(this.#reviews ?? scene.ledger.handoffPath("review", frame.type, params))
299
297
  : "",
300
- // The doc anchor — the target doc for a doc line, the plan path for a branch
301
- // line (the branch review/fix judge the plan document). Empty off those faces.
302
- INPUT_DOC: docPath ?? (frame.target.kind === "branch" ? (scene.planPath ?? "") : ""),
298
+ // The kind-named judged-doc anchors (the semantic retirement of the generic
299
+ // INPUT_DOC): the plan/branch lines carry the plan document (INPUT_PLAN — the
300
+ // doc path on a plan line, the plan path on a branch line, whose review/fix
301
+ // judges the plan document) AND its design-spec reference (INPUT_SPEC — the
302
+ // `spec:` front-matter link target, so the plan/branch reviewer judges plan→
303
+ // spec conformance); the spec line carries its spec document (INPUT_SPEC; the
304
+ // judged doc IS the spec, no plan anchor). Empty off the off-faces (the slots
305
+ // are dropped by the assembler).
306
+ INPUT_PLAN:
307
+ frame.type === "plan"
308
+ ? this.#rel(docPath ?? "")
309
+ : frame.type === "branch"
310
+ ? this.#rel(scene.planPath ?? "")
311
+ : "",
312
+ INPUT_SPEC:
313
+ frame.type === "spec"
314
+ ? this.#rel(docPath ?? "")
315
+ : frame.type === "plan" || frame.type === "branch"
316
+ ? this.#rel(scene.specLink ?? "")
317
+ : "",
303
318
  // The branch/wave tree-review scope anchor (BASE_BRANCH) — engine-injected
304
319
  // from the base artifact at dispatch; empty off those faces (spec/plan reviews
305
320
  // carry none, and the empty slot is dropped by the assembler).
@@ -313,11 +328,11 @@ export class CliLifecycle {
313
328
  // slot the frame's family does not consume stays empty and is dropped (only
314
329
  // present facts land). The brief is a pure read input (INPUT_WAVE_BRIEF) with
315
330
  // no write slot.
316
- OUTPUT_REPORT: this.#outputOf(frame, "report"),
317
- OUTPUT_EVIDENCE: this.#outputOf(frame, "evidence"),
318
- OUTPUT_HANDOFF: scene.ledger.handoffPath(op, frame.type, params),
331
+ OUTPUT_REPORT: this.#rel(this.#naming.report(frame)),
332
+ OUTPUT_EVIDENCE: this.#rel(this.#naming.evidence(frame)),
333
+ OUTPUT_HANDOFF: this.#rel(scene.ledger.handoffPath(op, frame.type, params)),
319
334
  REVIEW_TYPE: isReview ? frame.type : "",
320
- WORKSPACE_DIR: scene.workspace.path,
335
+ WORKSPACE_DIR: this.#rel(scene.workspace.path),
321
336
  WORKSPACE_ID: scene.workspace.slug,
322
337
  // v1.9 — the injected writable-subset schema (projection ①): the `## Handoff
323
338
  // schema` section of the mode's fixed prefix (byte-stable per mode; the work
@@ -326,60 +341,35 @@ export class CliLifecycle {
326
341
  };
327
342
  }
328
343
 
329
- /** The canonical prescribed OUTPUT_* write path of one artifact kind (find #5 —
330
- * the {family}-{key}-{artifact} single naming scheme; find #9 — branch line
331
- * drops the range token: `branch-{op}{-round}-report.md` · `branch-test-evidence.json`,
332
- * the branch line carries no commit identity · doc = the {type}-{op}-{round} stem,
333
- * spec-review-1). "" when the frame's family does not consume the slot — only
334
- * present facts ride the prompt (the assembler drops the empty-valued keys). */
335
- #outputOf(frame: OpenFrame, kind: "report" | "evidence"): string {
336
- const workspace = this.#scene.workspace;
337
- const op = this.#opOf(frame);
338
- if (frame.type === "spec" || frame.type === "plan") {
339
- // The doc family — the round-keyed {type}-{op}-{round} stem (spec-review-1):
340
- // every review/docs-fix round books its own report (a re-review never
341
- // overwrites its predecessor); evidence is a work-family face only.
342
- if (kind !== "report") return "";
343
- return workspace.resolve(`${frame.type}-${op}-${frame.round}-report.md`);
344
- }
345
- const family = frame.type === "wave" ? `tasks-${frame.params.tasks ?? ""}` : "branch";
346
- if (kind === "report") {
347
- const suffix = frame.phase === "implement" ? "" : `-${frame.round}`;
348
- return workspace.resolve(`${family}-${op}${suffix}-report.md`);
349
- }
350
- // evidence — the work faces only (implement/fix write the canonical evidence file)
351
- if (frame.phase !== "implement" && frame.phase !== "fix") return "";
352
- return workspace.resolve(this.#evidenceName(frame));
344
+ /** The round-context path normalizer (D46) — EVERY path token injected into the
345
+ * child prompt speaks ONE basis (repoRoot-relative): the child is spawned at
346
+ * cwd = repoRoot, so a relative token resolves from the same root for every
347
+ * token, input or output alike. The producers (`RoundNaming`/`handoffPath`/
348
+ * `workspace.path`) yield absolute; `INPUT_SPEC` is resolved absolute at the CLI
349
+ * seam; the post-T3 argv tokens (`INPUT_PLAN`/`INPUT_SPEC`/`INPUT_REVIEWS`) are repoRoot-relative
350
+ * `RepoPath`s. So the exit takes an absolute-or-repoRoot-relative value and emits
351
+ * repoRoot-relative through the ONE value object (`RepoRoot.relativize` reads an
352
+ * absolute value as itself and a relative value as repoRoot-relative, collapsing
353
+ * both to one basis — the single conversion point). */
354
+ #rel(value: string): string {
355
+ if (value === "") return "";
356
+ return this.#repoRootValue().relativize(value);
353
357
  }
354
358
 
355
- /** The canonical evidence file name of a work frame (find #5/#9 — the
356
- * {line}-test-evidence.json form: `tasks-{tasks}-test-evidence.json` /
357
- * `branch-test-evidence.json` — the branch line's row-level current state,
358
- * overwritten each round (the range token left the name);
359
- * the same name the read-back gate reads). The line token joins when the frame
360
- * keys it (the task face) — a key-less line (branch) names the family alone. */
361
- #evidenceName(frame: OpenFrame): string {
362
- const key = frame.type === "wave" ? (frame.params.tasks ?? "") : "";
363
- const line = key === "" ? this.#evidencePrefix(frame) : `${this.#evidencePrefix(frame)}-${key}`;
364
- return `${line}-test-evidence.json`;
359
+ /** The repo-basis value object of this scene — the ONE conversion entry every
360
+ * round-context token normalizes through. The basis is the scene workspace
361
+ * root's OWN value object (built once at the root's boundary) — never re-wrapped
362
+ * here (branch-review-1 F2: one basis, one form). */
363
+ #repoRootValue(): RepoRoot {
364
+ return this.#scene.workspace.root.basis;
365
365
  }
366
366
 
367
- /** The RETURN_STDOUT_BLOCK child stdout → the outcome: the two canonical lines
368
- * (status / artifacts), each key=value tokens; a missing status line is a BLOCKED
369
- * outcome (only present facts land). */
370
- #parseBlockReturn(stdout: string): DispatchOutcome {
371
- const status = stdout.match(/^status:\s*(\S+)/m)?.[1];
372
- if (status === undefined) return { status: "BLOCKED" };
373
- const outcome: DispatchOutcome = { status: status as RoundStatus };
374
- const artifacts = stdout.match(/^artifacts:(.*)$/m);
375
- if (artifacts !== null) {
376
- outcome.artifacts = {};
377
- for (const pair of artifacts[1].trim().split(/\s+/)) {
378
- const eq = pair.indexOf("=");
379
- if (eq !== -1) outcome.artifacts[pair.slice(0, eq)] = pair.slice(eq + 1);
380
- }
381
- }
382
- return outcome;
367
+ /** The child-stdout diagnostic tail (P11 T2) — the last STDOUT_TAIL_MAX non-empty
368
+ * stdout lines, kept verbatim for the crash record. The child's Return is prose;
369
+ * the engine never parses it — this is the failure-diagnosis channel only. */
370
+ #tailOf(stdout: string): readonly string[] {
371
+ const lines = stdout.split("\n").filter((line) => line.trim() !== "");
372
+ return lines.slice(-STDOUT_TAIL_MAX);
383
373
  }
384
374
 
385
375
  // -------------------------------------------------------------------------
@@ -398,7 +388,7 @@ export class CliLifecycle {
398
388
  * rounds only) is read back with the same stakes: a missing/violating file
399
389
  * rewrites the carrier to BLOCKED (persisted — the child's work is kept, marked
400
390
  * bad), the second fix for a prose-only claim. */
401
- #reconstruct(frame: OpenFrame, block: DispatchOutcome): DispatchOutcome {
391
+ #reconstruct(frame: OpenFrame): DispatchOutcome {
402
392
  const scene = this.#scene;
403
393
  const op = this.#opOf(frame);
404
394
  const face = this.#familyOf(op, frame.type).schema ?? "work";
@@ -457,7 +447,7 @@ export class CliLifecycle {
457
447
  // missing/malformed/schema-violating file rewrites the draft to BLOCKED (each
458
448
  // cause reported truly — the tri-state read, D27).
459
449
  if (face === "work") {
460
- const evidenceName = this.#evidenceName(frame);
450
+ const evidenceName = this.#naming.evidenceName(frame);
461
451
  const evidencePath = scene.workspace.resolve(evidenceName);
462
452
  const evidenceRead = scene.workspace.readJson<unknown>(evidenceName);
463
453
  // The SAME tri-state discrimination as the draft leg (D27): a PRESENT-but-corrupt
@@ -479,26 +469,56 @@ export class CliLifecycle {
479
469
  return {
480
470
  status,
481
471
  findings: face === "findings" ? schema.findingsOf(findings) : undefined,
482
- artifacts: block.artifacts,
483
472
  carrier: this.#materialize(frame, face, draft, status, reason),
484
473
  };
485
474
  }
486
475
 
487
476
  /** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
488
477
  * same-command resume's decision source: the attempted handoff + the resume
489
- * command) + NO carrier (the bookkeep leaves the draft untouched). */
490
- #reject(frame: OpenFrame, path: string, reason: string): DispatchOutcome {
478
+ * command) + NO carrier (the bookkeep leaves the draft untouched). The crash
479
+ * record carries the caller's REAL death facts: an absent draft/schema violation
480
+ * is the read-back face (exit 0 · `contract-violation` — the defaults), a dead
481
+ * child passes its own exit code + `child-exit`, and a terminated round passes
482
+ * its whole `termination` fact (cause + last sample) — one record shape, three
483
+ * truthful callers (the record is the postmortem artifact; a misreported death
484
+ * sends a maintainer hunting the wrong fault).
485
+ *
486
+ * The returned status derives from the death facts alone (§4.3 — no status
487
+ * parameter): a termination rides it → `TIMEOUT`; otherwise → `BLOCKED` (the
488
+ * read-back and child-exit callers pass `termination: null`, today's behavior
489
+ * verbatim). */
490
+ #reject(
491
+ frame: OpenFrame,
492
+ path: string,
493
+ reason: string,
494
+ death: {
495
+ exitCode: number | null;
496
+ cause: CrashCause;
497
+ termination: Termination | null;
498
+ } = {
499
+ exitCode: 0,
500
+ cause: "contract-violation",
501
+ termination: null,
502
+ },
503
+ ): DispatchOutcome {
491
504
  this.#io.stderr(`CDD_BLOCKED: ${reason}\n`);
492
505
  const op = this.#opOf(frame);
493
506
  this.#scene.ledger.writeCrash(`${op}.${frame.type}`, frame.round, {
494
- exitCode: 0,
507
+ exitCode: death.exitCode,
495
508
  stderrTail: [reason],
496
- stdoutTail: [],
497
- attemptedHandoff: path,
509
+ stdoutTail: this.#stdoutTail,
510
+ // The persisted attempted-handoff path is the CANONICAL repoRoot-relative
511
+ // shape (never the absolute `handoffPath` syscall form — §2.7).
512
+ attemptedHandoff: this.#rel(path),
498
513
  next: this.#resumeOf(frame),
499
- cause: "contract-violation",
514
+ // The cause rides the termination fact when one is present (one of the three
515
+ // causes or the `unknown` fallback); without it, the caller's own cause.
516
+ cause: death.termination?.cause ?? death.cause,
517
+ // The last sample rides WITH the termination (in memory, zero re-read of the
518
+ // heartbeat file) — null on every non-terminated face.
519
+ lastSample: death.termination?.lastSample ?? null,
500
520
  });
501
- return { status: "BLOCKED" };
521
+ return { status: death.termination === null ? "BLOCKED" : "TIMEOUT" };
502
522
  }
503
523
 
504
524
  /** Build the final carrier — the validated writable fields from the draft (the
@@ -548,7 +568,7 @@ export class CliLifecycle {
548
568
  // face holds NO status field: its conclusion is DERIVED at judgment time
549
569
  // (`HandoffSchema.conclusionOf("findings", carrier)` → rollup(findings)), so the
550
570
  // persisted findings carrier stays the pure declaration plane
551
- // (findings/artifacts/notes) and a fix child's INPUT_FINDINGS carrier is
571
+ // (findings/artifacts/notes) and a fix child's INPUT_REVIEWS carrier is
552
572
  // status-free (the judgment face is perpendicular to the input face · D27).
553
573
  const draftNotes = Array.isArray(draft.notes) ? [...(draft.notes as unknown[])] : [];
554
574
  if (face === "work") {
@@ -583,28 +603,40 @@ export class CliLifecycle {
583
603
  const out: Record<string, string> = {};
584
604
  for (const [key, value] of Object.entries(declared)) {
585
605
  const canonical = this.#prescribedArtifact(frame, key);
586
- if (canonical !== "" && value !== canonical) {
606
+ if (canonical === "") {
607
+ // The non-prescribed slots (the pure read input `brief`, a docs-fix's `doc`,
608
+ // child extras) pass verbatim.
609
+ out[key] = value;
610
+ continue;
611
+ }
612
+ // A prescribed slot ALWAYS books the engine's canonical path in the CANONICAL
613
+ // shape (repoRoot-relative — never the absolute `workspace.resolve` form): the
614
+ // persisted carrier's artifacts map carries zero absolute strings (§2.7). The
615
+ // comparison runs on ONE basis (D46 — the child receives relative OUTPUT_*
616
+ // tokens, so a compliant declaration matches); a free-named OR absolute
617
+ // deviation is replaced and surfaced on the notes (the review scope axis reads
618
+ // them).
619
+ const relative = this.#rel(canonical);
620
+ if (this.#rel(value) !== relative) {
587
621
  notes.push(
588
622
  `artifact ${key}: declared path ${value} deviates from the prescribed ${canonical} — the canonical path is booked`,
589
623
  );
590
- out[key] = canonical;
591
- } else {
592
- out[key] = value;
593
624
  }
625
+ out[key] = relative;
594
626
  }
595
627
  return Object.keys(out).length > 0 ? out : undefined;
596
628
  }
597
629
 
598
630
  /** The prescribed path of one block-artifact slot — a slot the frame's family
599
- * prescribes (report/test_evidence → the canonical OUTPUT_* name), "" for every
600
- * other slot (the pure read input `brief` is never a write slot, and a docs-fix's
601
- * `doc` is never prescribed — both pass verbatim). */
631
+ * prescribes (report/test_evidence → the canonical name from `RoundNaming`), ""
632
+ * for every other slot (the pure read input `brief` is never a write slot, and a
633
+ * docs-fix's `doc` is never prescribed — both pass verbatim). */
602
634
  #prescribedArtifact(frame: OpenFrame, slot: string): string {
603
635
  switch (slot) {
604
636
  case "report":
605
- return this.#outputOf(frame, "report");
637
+ return this.#naming.report(frame);
606
638
  case "test_evidence":
607
- return this.#outputOf(frame, "evidence");
639
+ return this.#naming.evidence(frame);
608
640
  default:
609
641
  return "";
610
642
  }
@@ -619,17 +651,10 @@ export class CliLifecycle {
619
651
  const op = this.#opOf(frame);
620
652
  const face = this.#familyOf(op, frame.type).schema ?? "work";
621
653
  const evidence = face === "work";
622
- const prefix = evidence ? this.#evidencePrefix(frame) : "tasks";
654
+ const prefix = evidence ? this.#naming.prefix(frame) : "tasks";
623
655
  return this.#handoffSchema.schemaText(face, evidence, prefix);
624
656
  }
625
657
 
626
- /** The evidence file's family prefix (§3.7 naming) — the task-family work rounds
627
- * use the canonical `tasks-` prefix; the branch fix uses the `branch-` family
628
- * prefix (never the misleading tasks- spine). */
629
- #evidencePrefix(frame: OpenFrame): string {
630
- return frame.type === "wave" ? "tasks" : "branch";
631
- }
632
-
633
658
  /** The op.type family record — the engine-config handoff namespace single truth
634
659
  * (loud on an unknown family: never a second naming table). */
635
660
  #familyOf(op: string, type: string): HandoffFamily {
@@ -679,15 +704,15 @@ export class CliLifecycle {
679
704
  case "fix": {
680
705
  const findings = scene.ledger.handoffPath("review", frame.type, frame.params);
681
706
  const target =
682
- frame.target.kind === "doc"
707
+ frame.target.kind === "plan" || frame.target.kind === "spec"
683
708
  ? `--${frame.type === "spec" ? "spec" : "plan"} ${frame.target.doc}`
684
709
  : // The branch fix carries no refs — the source findings ride the
685
- // --findings handoff; the workspace-identity `--plan` still rides
710
+ // --reviews handoff; the workspace-identity `--plan` still rides
686
711
  // (the plan is the branch line's identity, zero orchestrator fallback).
687
712
  frame.target.kind === "branch"
688
713
  ? `--plan ${plan}`
689
714
  : `--tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
690
- return `cdd fix --type ${frame.type} ${target} --findings ${findings}`;
715
+ return `cdd fix --type ${frame.type} ${target} --reviews ${findings}`;
691
716
  }
692
717
  }
693
718
  }
@@ -695,6 +720,6 @@ export class CliLifecycle {
695
720
  /** The doc path of a doc-target frame (the `""` never lands — the reject paths
696
721
  * only frame docs). */
697
722
  #docOf(frame: OpenFrame): string {
698
- return frame.target.kind === "doc" ? frame.target.doc : "";
723
+ return frame.target.kind === "plan" || frame.target.kind === "spec" ? frame.target.doc : "";
699
724
  }
700
725
  }