@oscaner-skills/cdd-engine 3.0.0 → 3.1.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 (143) hide show
  1. package/{src-next/bin.ts → dist/bin.js} +18 -21
  2. package/dist/contract/declare.js +998 -0
  3. package/dist/contract/doc.js +565 -0
  4. package/dist/contract/frontmatter.js +209 -0
  5. package/dist/contract/home-extractors.js +379 -0
  6. package/dist/contract/invariants.js +1030 -0
  7. package/dist/contract/judge.js +109 -0
  8. package/dist/contract/lint.js +206 -0
  9. package/dist/contract/project.js +371 -0
  10. package/dist/contract/skill-anatomy.js +156 -0
  11. package/dist/contract/translate.js +85 -0
  12. package/dist/face/artifacts.js +189 -0
  13. package/dist/face/board-view.js +522 -0
  14. package/dist/face/capsule.js +149 -0
  15. package/dist/face/cli.js +893 -0
  16. package/dist/face/declare.js +241 -0
  17. package/dist/face/gate.js +158 -0
  18. package/dist/face/graph-view.js +66 -0
  19. package/dist/face/host.js +211 -0
  20. package/dist/face/lifecycle.js +702 -0
  21. package/dist/face/preview.js +136 -0
  22. package/dist/face/projection.js +259 -0
  23. package/dist/face/route-render.js +162 -0
  24. package/dist/face/termination.js +504 -0
  25. package/dist/face/words.js +258 -0
  26. package/{src-next/infra/config.ts → dist/infra/config.js} +19 -24
  27. package/{src-next/infra/doc-roots.ts → dist/infra/doc-roots.js} +3 -13
  28. package/dist/infra/git.js +37 -0
  29. package/dist/infra/process.js +22 -0
  30. package/{src-next/infra/root.ts → dist/infra/root.js} +25 -36
  31. package/dist/infra/runtime.js +85 -0
  32. package/dist/infra/workspace.js +276 -0
  33. package/dist/render/brief.js +82 -0
  34. package/dist/render/issue-body.js +129 -0
  35. package/dist/render/skeleton.js +434 -0
  36. package/dist/render/templates.js +520 -0
  37. package/dist/session/faces.js +38 -0
  38. package/dist/session/graph.js +309 -0
  39. package/dist/session/handoff-schema.js +295 -0
  40. package/dist/session/ledger.js +762 -0
  41. package/dist/session/next.js +211 -0
  42. package/dist/session/preflight.js +194 -0
  43. package/dist/session/round-naming.js +73 -0
  44. package/dist/session/run.js +453 -0
  45. package/dist/session/state.js +8 -0
  46. package/dist/session/wave.js +92 -0
  47. package/package.json +5 -5
  48. package/src-next/__tests__/bin.test.ts +0 -128
  49. package/src-next/__tests__/dead-decl.guard.test.ts +0 -39
  50. package/src-next/__tests__/floor.guard.test.ts +0 -69
  51. package/src-next/__tests__/issue-body.guard.test.ts +0 -66
  52. package/src-next/__tests__/phase-suffix.guard.test.ts +0 -72
  53. package/src-next/__tests__/smoke.integration.test.ts +0 -185
  54. package/src-next/__tests__/support/strip-comments.ts +0 -99
  55. package/src-next/__tests__/zero-dep.test.ts +0 -94
  56. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +0 -256
  57. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +0 -165
  58. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +0 -190
  59. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +0 -106
  60. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +0 -240
  61. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +0 -165
  62. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +0 -190
  63. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +0 -100
  64. package/src-next/contract/__tests__/declare.test.ts +0 -481
  65. package/src-next/contract/__tests__/doc.test.ts +0 -527
  66. package/src-next/contract/__tests__/dockey.guard.test.ts +0 -58
  67. package/src-next/contract/__tests__/edge-conditions.guard.test.ts +0 -81
  68. package/src-next/contract/__tests__/frontmatter.test.ts +0 -164
  69. package/src-next/contract/__tests__/judge.test.ts +0 -1111
  70. package/src-next/contract/__tests__/lint.test.ts +0 -324
  71. package/src-next/contract/__tests__/project.test.ts +0 -460
  72. package/src-next/contract/__tests__/structure-pin.test.ts +0 -186
  73. package/src-next/contract/__tests__/translate.test.ts +0 -96
  74. package/src-next/contract/declare.ts +0 -1071
  75. package/src-next/contract/doc.ts +0 -816
  76. package/src-next/contract/frontmatter.ts +0 -233
  77. package/src-next/contract/home-extractors.ts +0 -397
  78. package/src-next/contract/invariants.ts +0 -1413
  79. package/src-next/contract/judge.ts +0 -151
  80. package/src-next/contract/lint.ts +0 -239
  81. package/src-next/contract/project.ts +0 -656
  82. package/src-next/contract/skill-anatomy.ts +0 -301
  83. package/src-next/contract/translate.ts +0 -113
  84. package/src-next/face/__tests__/board-view.test.ts +0 -1151
  85. package/src-next/face/__tests__/capsule.test.ts +0 -300
  86. package/src-next/face/__tests__/channel-closure.guard.test.ts +0 -129
  87. package/src-next/face/__tests__/cli.test.ts +0 -4897
  88. package/src-next/face/__tests__/face.test.ts +0 -289
  89. package/src-next/face/__tests__/graph-view.test.ts +0 -61
  90. package/src-next/face/__tests__/host.test.ts +0 -24
  91. package/src-next/face/__tests__/install-rows.guard.test.ts +0 -58
  92. package/src-next/face/__tests__/negation.ts +0 -6
  93. package/src-next/face/__tests__/preview.test.ts +0 -374
  94. package/src-next/face/__tests__/projection.test.ts +0 -303
  95. package/src-next/face/__tests__/repo-root.guard.test.ts +0 -120
  96. package/src-next/face/__tests__/termination.test.ts +0 -650
  97. package/src-next/face/__tests__/words.guard.test.ts +0 -93
  98. package/src-next/face/artifacts.ts +0 -248
  99. package/src-next/face/board-view.ts +0 -652
  100. package/src-next/face/capsule.ts +0 -163
  101. package/src-next/face/cli.ts +0 -1028
  102. package/src-next/face/declare.ts +0 -323
  103. package/src-next/face/gate.ts +0 -171
  104. package/src-next/face/graph-view.ts +0 -74
  105. package/src-next/face/host.ts +0 -302
  106. package/src-next/face/lifecycle.ts +0 -725
  107. package/src-next/face/preview.ts +0 -151
  108. package/src-next/face/projection.ts +0 -285
  109. package/src-next/face/route-render.ts +0 -185
  110. package/src-next/face/termination.ts +0 -573
  111. package/src-next/face/words.ts +0 -314
  112. package/src-next/infra/__tests__/infra.test.ts +0 -333
  113. package/src-next/infra/__tests__/root.test.ts +0 -56
  114. package/src-next/infra/git.ts +0 -39
  115. package/src-next/infra/process.ts +0 -34
  116. package/src-next/infra/runtime.ts +0 -132
  117. package/src-next/infra/workspace.ts +0 -322
  118. package/src-next/render/__tests__/render.test.ts +0 -550
  119. package/src-next/render/__tests__/skeleton.test.ts +0 -684
  120. package/src-next/render/brief.ts +0 -121
  121. package/src-next/render/issue-body.ts +0 -162
  122. package/src-next/render/skeleton.ts +0 -502
  123. package/src-next/render/templates.ts +0 -645
  124. package/src-next/session/__tests__/graph.test.ts +0 -277
  125. package/src-next/session/__tests__/handoff-plane.guard.test.ts +0 -48
  126. package/src-next/session/__tests__/handoff-schema.test.ts +0 -310
  127. package/src-next/session/__tests__/ledger.test.ts +0 -745
  128. package/src-next/session/__tests__/next.test.ts +0 -460
  129. package/src-next/session/__tests__/preflight.test.ts +0 -545
  130. package/src-next/session/__tests__/round-naming.test.ts +0 -142
  131. package/src-next/session/__tests__/run.test.ts +0 -1026
  132. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +0 -49
  133. package/src-next/session/__tests__/wave.test.ts +0 -476
  134. package/src-next/session/faces.ts +0 -110
  135. package/src-next/session/graph.ts +0 -411
  136. package/src-next/session/handoff-schema.ts +0 -373
  137. package/src-next/session/ledger.ts +0 -1076
  138. package/src-next/session/next.ts +0 -293
  139. package/src-next/session/preflight.ts +0 -271
  140. package/src-next/session/round-naming.ts +0 -84
  141. package/src-next/session/run.ts +0 -610
  142. package/src-next/session/state.ts +0 -30
  143. package/src-next/session/wave.ts +0 -139
@@ -0,0 +1,702 @@
1
+ // packages/cdd-engine/src-next/face/lifecycle.ts
2
+ // T8 — the lifecycle face (the split contract §6.2: face/cli.ts slims to composition).
3
+ // The dispatch seam's production default lives here — CliLifecycle (the former
4
+ // HarnessDispatch composition member, renamed by the split; face/cli.ts re-exports it
5
+ // as HarnessDispatch so the public surface is unchanged) — the dispatch + readback +
6
+ // round-context plane (§6.2: implement/review/fix dispatch, the read-back reconstruct
7
+ // (#reconstruct/#reject/#materialize + carrier helpers), the round-context data
8
+ // (#valuesOf/#childPrompt/round-context fact assembly)). The shared seams the
9
+ // lifecycle rides (cli io / sync process / env / scene) are declared here too — the
10
+ // root composition imports them back (zero public-export drift, zero import cycle).
11
+ // The root Cli holds the lifecycle instances and composes through them via its .action
12
+ // thin shells — zero bare functions; every collaborator stays injectable (the tests
13
+ // substitute the hermetic ones).
14
+ // The module exports the shared seams + the lifecycle class — zero behavior-carrying
15
+ // bare functions.
16
+ import process from "node:process";
17
+ import { printParseErrorCode } from "jsonc-parser";
18
+ import { ConfigLoader } from "../infra/config.js";
19
+ import { TemplateAssembler } from "../render/templates.js";
20
+ import { HandoffSchema } from "../session/handoff-schema.js";
21
+ import { RoundNaming } from "../session/round-naming.js";
22
+ import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
23
+ import { TerminationPolicy, Terminator, } from "./termination.js";
24
+ import { Words } from "./words.js";
25
+ /** The crash-record stdout-tail cap (P11 T2) — the child's last STDOUT_TAIL_MAX
26
+ * non-empty stdout lines ride the crash record's `stdoutTail` (the diagnostic
27
+ * channel; the child's Return is prose, never the round's content). */
28
+ const STDOUT_TAIL_MAX = 40;
29
+ /**
30
+ * CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
31
+ * lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
32
+ * surface keeps its name). `step()` returns the DispatchStep the lifecycle runs, which
33
+ * assembles the dispatch prompt (the render template-contract data plane) from the
34
+ * frame, runs the host harness CLI (the harness-contract rows: cli + invoke flags +
35
+ * the phase's skill-ref slash form) and reads the child's OUTPUT_HANDOFF draft back
36
+ * into the lifecycle's outcome (the child's Return is prose, never parsed). Detection
37
+ * reads the harness-contract detect markers from the injected env — empty host → a
38
+ * BLOCKED outcome over the CDD_BLOCKED channel (never a thrown dispatch).
39
+ */
40
+ export class CliLifecycle {
41
+ #env;
42
+ #sync;
43
+ #config;
44
+ #template;
45
+ #io;
46
+ #scene;
47
+ #reviews;
48
+ /** The single word table (the promotion WARN wording + its station) — one instance,
49
+ * injected at the composition root, so the lifecycle never re-types a user-facing
50
+ * line. */
51
+ #words;
52
+ /** The round-naming single source (P11 T4) — every prescribed artifact name of a
53
+ * frame derives here (the report/evidence/brief names + the family op), so the
54
+ * lifecycle and the dry-run preview name the same artifacts by one rule. */
55
+ #naming;
56
+ /** The handoff-schema face — stateless, one shared instance (the read-back
57
+ * validator + the injected prompt text). */
58
+ #handoffSchema = new HandoffSchema();
59
+ /** The current dispatch's child-stdout diagnostic tail (the crash-record channel,
60
+ * P11 T2) — set in #dispatch after the child returns, read by #reject. The child's
61
+ * Return is prose; the engine never parses it — this is the failure channel only. */
62
+ #stdoutTail = [];
63
+ constructor(opts) {
64
+ this.#env = opts.env ?? process.env;
65
+ this.#scene = opts.scene;
66
+ this.#naming = new RoundNaming(opts.scene.workspace);
67
+ this.#sync = opts.sync ?? new Terminator();
68
+ this.#config = opts.config ?? new ConfigLoader();
69
+ this.#template = opts.template ?? new TemplateAssembler();
70
+ this.#words = opts.words ?? new Words();
71
+ this.#io = opts.io ?? {
72
+ stdout: (t) => process.stdout.write(t),
73
+ stderr: (t) => process.stderr.write(t),
74
+ };
75
+ this.#reviews = opts.reviews ?? null;
76
+ }
77
+ /** The host-harness id detected from the env — "claude" | "cursor" | "pi" | "" —
78
+ * a delegation to the module-level judgment (HostDetect.detect, face/host.ts —
79
+ * the detection's single home; this instance method is the injectable-env
80
+ * adapter the lifecycle face rides, behavior unchanged). */
81
+ detectHost(env = this.#env) {
82
+ return HostDetect.detect(env);
83
+ }
84
+ /** The DispatchStep the lifecycle runs — one frame → the outcome. */
85
+ step() {
86
+ return (frame) => this.#dispatch(frame);
87
+ }
88
+ /** One dispatch — prompt from the template plane + the frame, host child via
89
+ * the harness-contract rows, the child's write-back read in (the draft at
90
+ * OUTPUT_HANDOFF is the round's content; the child's Return is prose, never parsed). */
91
+ async #dispatch(frame) {
92
+ const host = this.detectHost();
93
+ if (host === "") {
94
+ this.#io.stderr("CDD_BLOCKED: no host harness detected (run cdd from within a supported harness)\n");
95
+ return { status: "BLOCKED" };
96
+ }
97
+ const prompt = this.#template.render(this.#valuesOf(frame));
98
+ const row = HOSTS[host];
99
+ const cliName = row.cli;
100
+ const args = [...row.invoke.split(" ").filter((part) => part.length > 0)];
101
+ const ref = this.#skillRef(host, frame);
102
+ // The child receives ONE prompt argument — per the host's promptForm data column
103
+ // (§3.5): the ref-prefixed form embeds the slash ref at the start of the single
104
+ // prompt positional (claude -p consumes the whole first positional as the prompt;
105
+ // a standalone ref arg after the flags would be swallowed, losing everything after
106
+ // the ref) — the prompt assembly is data, never a code assumption.
107
+ const result = await this.#sync.run({
108
+ command: cliName,
109
+ args: [...args, this.#childPrompt(row.promptForm, ref, prompt)],
110
+ // The two paths the dispatch needs share ONE source (this workspace, held only
111
+ // here): the child's spawn directory is the repo root, and the heartbeat lands
112
+ // in this dispatch's workspace. The same `cwd` is also the tree-leg scan root,
113
+ // and the heartbeat path is the sampler's own write — the scan root ≡ child cwd
114
+ // correspondence is structural, never a convention.
115
+ cwd: this.#scene.workspace.root.repoRoot,
116
+ heartbeatPath: this.#scene.workspace.resolve("liveness.json"),
117
+ policy: TerminationPolicy.of(frame.phase),
118
+ });
119
+ // The child's stdout rides the diagnostic channel — #reject reads it into the
120
+ // crash record on either failure face. Child Return is prose: the engine never
121
+ // parses it; the round's content is the OUTPUT_HANDOFF draft, read in #reconstruct.
122
+ this.#stdoutTail = this.#tailOf(result.stdout);
123
+ // The termination leg FIRST (§4.3 — the judging order is a hard rule): a killed
124
+ // child's exit code is null, so `null !== 0` is true — judging the child-exit leg
125
+ // first would fold every terminated round into `child-exit` and falsify the crash
126
+ // cause. `termination !== null` → the round concludes TIMEOUT (the words table's
127
+ // status is already there), the reason rides the CDD_BLOCKED channel, and the
128
+ // failure face (no `next:` line) follows from the status alone.
129
+ //
130
+ // The ONE promotion exception (D53 Q12's deliberate narrowing): a terminated
131
+ // REVIEW round whose draft already sits on disk — valid against the findings
132
+ // schema and carrying at least one finding — has done its work; its conclusion is
133
+ // derived from the handoff, never from the termination word (termination ⊥
134
+ // conclusion). Every other terminated round keeps the TIMEOUT failure face.
135
+ if (result.termination !== null) {
136
+ const draft = this.#probeDraft(frame);
137
+ if (draft !== null) {
138
+ return this.#promote(frame, draft, result.termination, result);
139
+ }
140
+ return this.#reject(frame, this.#scene.ledger.handoffPath(this.#opOf(frame), frame.type, frame.params), `child ${cliName} was terminated: ${result.termination.cause}`,
141
+ // the terminated round's OWN death facts — the termination rides whole
142
+ // (cause + last sample), the signalled child's code is null verbatim
143
+ { exitCode: result.code, cause: result.termination.cause, termination: result.termination });
144
+ }
145
+ if (result.code !== 0) {
146
+ return this.#reject(frame, this.#scene.ledger.handoffPath(this.#opOf(frame), frame.type, frame.params), `child ${cliName} exited ${result.code}`,
147
+ // the dead child's OWN death facts — never the read-back face's defaults;
148
+ // this branch sits AFTER the termination leg, so the termination is null
149
+ { exitCode: result.code, cause: "child-exit", termination: null });
150
+ }
151
+ return this.#reconstruct(frame);
152
+ }
153
+ /** The work-mode of a frame phase — branch-review rides the review family. The
154
+ * mapping itself lives in `RoundNaming` (the artifact stems key on it); this is
155
+ * the lifecycle's read of that single source. */
156
+ #opOf(frame) {
157
+ return this.#naming.op(frame);
158
+ }
159
+ /** The dispatch-table work-mode (ROLE) of a frame — the spec/plan fix faces ride
160
+ * the docs-fix mode; everything else maps by its phase (§3.5's four-mode table). */
161
+ #roleOf(frame) {
162
+ if (frame.phase === "fix") {
163
+ return frame.type === "spec" || frame.type === "plan" ? "docs-fix" : "fix";
164
+ }
165
+ return frame.phase === "implement" ? "implement" : "review";
166
+ }
167
+ /** The phase's skill-ref slash form for the detected host ("/mattpocock-skills:implement"
168
+ * · "/mattpocock-skills:code-review" etc.); null when the phase carries no skill
169
+ * ref (the fix face and the spec/plan reviews — their criteria ride the
170
+ * prompt's fixed body, never a slash arg). */
171
+ #skillRef(host, frame) {
172
+ const dispatch = DISPATCH;
173
+ let ref = null;
174
+ if (frame.phase === "review" || frame.phase === "branch-review") {
175
+ // The task/branch rows are object-shaped {ref}; the spec/plan review types
176
+ // carry NO dispatch row (their criteria are the review prompt's fixed body).
177
+ const entry = dispatch.review[frame.type];
178
+ const declaredRef = entry?.ref;
179
+ ref =
180
+ typeof declaredRef === "string" && declaredRef.startsWith("mattpocock-skills:")
181
+ ? declaredRef
182
+ : null;
183
+ }
184
+ else {
185
+ // The implement row is the dispatch table's single string slot; the other
186
+ // phases (fix) carry no dispatch row — the lookup resolves null (the fix
187
+ // face's ref-less face, same-shape as the spec/plan reviews).
188
+ const value = dispatch[frame.phase];
189
+ ref = typeof value === "string" ? value : null;
190
+ }
191
+ if (typeof ref !== "string")
192
+ return null;
193
+ const hostForm = REFS[ref]?.[host];
194
+ return hostForm ?? null;
195
+ }
196
+ /** The child's single prompt argument — per the host's promptForm data contract
197
+ * (§3.5): the ref-prefixed form embeds the skill-ref slash form at the start of
198
+ * the assembled dispatch prompt as one positional (`/kairos:cdd-* <prompt>`); the
199
+ * plain form passes the prompt verbatim. */
200
+ #childPrompt(form, ref, prompt) {
201
+ return form === "ref-prefixed" && ref !== null ? `${ref} ${prompt}` : prompt;
202
+ }
203
+ /** The round-context zone values of the dispatch prompt (the naming contract:
204
+ * ROLE nominative · WAVE (unit) · INPUT_* read-side · OUTPUT_* write-side · WORKSPACE_*
205
+ * environment · BASE_BRANCH scope anchor). Every declared token supplied — a mode's
206
+ * non-consumed slots stay empty and are NOT emitted by the assembler
207
+ * (empty-valued keys are dropped), so each mode's round context carries only the
208
+ * facts the mode reads. The review criteria/lens are NOT values — they fold into
209
+ * the review type's fixed prefix (§3.7). */
210
+ #valuesOf(frame) {
211
+ const scene = this.#scene;
212
+ const op = this.#opOf(frame);
213
+ const role = this.#roleOf(frame);
214
+ const params = frame.params;
215
+ const isReview = frame.phase === "review" || frame.phase === "branch-review";
216
+ const docPath = frame.target.kind === "plan" || frame.target.kind === "spec" ? frame.target.doc : null;
217
+ const isWave = frame.type === "wave";
218
+ return {
219
+ ROLE: role,
220
+ // v1.22 (wave-unitary): the wave face's scope IS the wave (the whole task list)
221
+ // — the round context speaks the UNIT, `WAVE`; the line faces carry their own
222
+ // read-side identity (INPUT_PLAN / INPUT_SPEC — the doc/branch line's kind-named
223
+ // tokens under the wave-unitary model).
224
+ WAVE: isWave ? (params.tasks ?? "") : "",
225
+ // The wave-brief read input — the ONE engine-rendered brief of the current
226
+ // dispatch (the unconditional re-extract at every dispatch makes it the pure
227
+ // read face of the wave line — §4.2); the non-wave faces carry no brief path
228
+ // (the slot stays empty, never emitted).
229
+ INPUT_WAVE_BRIEF: isWave ? this.#rel(scene.briefPath ?? "") : "",
230
+ // v1.9: INPUT_REVIEWS is fix/docs-fix only — the source review's handoff
231
+ // carrier; a review writes its own draft (INPUT_REVIEWS === OUTPUT_HANDOFF
232
+ // would be a short-circuit).
233
+ INPUT_REVIEWS: op === "fix"
234
+ ? this.#rel(this.#reviews ?? scene.ledger.handoffPath("review", frame.type, params))
235
+ : "",
236
+ // The kind-named judged-doc anchors (the semantic retirement of the generic
237
+ // INPUT_DOC): the plan/branch lines carry the plan document (INPUT_PLAN — the
238
+ // doc path on a plan line, the plan path on a branch line, whose review/fix
239
+ // judges the plan document) AND its design-spec reference (INPUT_SPEC — the
240
+ // `spec:` front-matter link target, so the plan/branch reviewer judges plan→
241
+ // spec conformance); the spec line carries its spec document (INPUT_SPEC; the
242
+ // judged doc IS the spec, no plan anchor). Empty off the off-faces (the slots
243
+ // are dropped by the assembler).
244
+ INPUT_PLAN: frame.type === "plan"
245
+ ? this.#rel(docPath ?? "")
246
+ : frame.type === "branch"
247
+ ? this.#rel(scene.planPath ?? "")
248
+ : "",
249
+ INPUT_SPEC: frame.type === "spec"
250
+ ? this.#rel(docPath ?? "")
251
+ : frame.type === "plan" || frame.type === "branch"
252
+ ? this.#rel(scene.specLink ?? "")
253
+ : "",
254
+ // The branch/wave tree-review scope anchor (BASE_BRANCH) — engine-injected
255
+ // from the base artifact at dispatch; empty off those faces (spec/plan reviews
256
+ // carry none, and the empty slot is dropped by the assembler).
257
+ BASE_BRANCH: isReview && (frame.type === "branch" || frame.type === "wave")
258
+ ? (scene.baseBranch ?? "")
259
+ : "",
260
+ // find #5 (P4.1 T7) — the prescribed artifact write paths (the {family}-{key}-
261
+ // {artifact} single naming): the round context carries the canonical OUTPUT_*
262
+ // names the child MUST use (zero free naming · cross-round zero overwrite); a
263
+ // slot the frame's family does not consume stays empty and is dropped (only
264
+ // present facts land). The brief is a pure read input (INPUT_WAVE_BRIEF) with
265
+ // no write slot.
266
+ OUTPUT_REPORT: this.#rel(this.#naming.report(frame)),
267
+ OUTPUT_EVIDENCE: this.#rel(this.#naming.evidence(frame)),
268
+ OUTPUT_HANDOFF: this.#rel(scene.ledger.handoffPath(op, frame.type, params)),
269
+ REVIEW_TYPE: isReview ? frame.type : "",
270
+ WORKSPACE_DIR: this.#rel(scene.workspace.path),
271
+ WORKSPACE_ID: scene.workspace.slug,
272
+ // v1.9 — the injected writable-subset schema (projection ①): the `## Handoff
273
+ // schema` section of the mode's fixed prefix (byte-stable per mode; the work
274
+ // faces — implement/fix — carry the evidence-file fence too).
275
+ HANDOFF_SCHEMA: this.#schemaText(frame),
276
+ };
277
+ }
278
+ /** The round-context path normalizer (D46) — EVERY path token injected into the
279
+ * child prompt speaks ONE basis (repoRoot-relative): the child is spawned at
280
+ * cwd = repoRoot, so a relative token resolves from the same root for every
281
+ * token, input or output alike. The producers (`RoundNaming`/`handoffPath`/
282
+ * `workspace.path`) yield absolute; `INPUT_SPEC` is resolved absolute at the CLI
283
+ * seam; the post-T3 argv tokens (`INPUT_PLAN`/`INPUT_SPEC`/`INPUT_REVIEWS`) are repoRoot-relative
284
+ * `RepoPath`s. So the exit takes an absolute-or-repoRoot-relative value and emits
285
+ * repoRoot-relative through the ONE value object (`RepoRoot.relativize` reads an
286
+ * absolute value as itself and a relative value as repoRoot-relative, collapsing
287
+ * both to one basis — the single conversion point). */
288
+ #rel(value) {
289
+ if (value === "")
290
+ return "";
291
+ return this.#repoRootValue().relativize(value);
292
+ }
293
+ /** The repo-basis value object of this scene — the ONE conversion entry every
294
+ * round-context token normalizes through. The basis is the scene workspace
295
+ * root's OWN value object (built once at the root's boundary) — never re-wrapped
296
+ * here (branch-review-1 F2: one basis, one form). */
297
+ #repoRootValue() {
298
+ return this.#scene.workspace.root.basis;
299
+ }
300
+ /** The child-stdout diagnostic tail (P11 T2) — the last STDOUT_TAIL_MAX non-empty
301
+ * stdout lines, kept verbatim for the crash record. The child's Return is prose;
302
+ * the engine never parses it — this is the failure-diagnosis channel only. */
303
+ #tailOf(stdout) {
304
+ const lines = stdout.split("\n").filter((line) => line.trim() !== "");
305
+ return lines.slice(-STDOUT_TAIL_MAX);
306
+ }
307
+ // -------------------------------------------------------------------------
308
+ // the read-back reconstruct (§3.6) — the draft is the round's content
309
+ // -------------------------------------------------------------------------
310
+ /** The ONE draft-read point — the frame's handoff draft read with the lenient
311
+ * child-authored dialect (D39). The reconstruct reports its tri-state outcome;
312
+ * the terminated-round probe only asks "is there a promotable draft?". */
313
+ #readDraft(frame) {
314
+ const op = this.#opOf(frame);
315
+ return this.#scene.workspace.readJsonLenient(this.#scene.ledger.handoffName(op, frame.type, frame.params));
316
+ }
317
+ /** The non-rejecting draft probe of the termination branch — a terminated REVIEW
318
+ * round's draft is promotable iff it exists, parses, passes the findings schema,
319
+ * and carries at least one finding. Returns the validated draft (the promotion
320
+ * then rides the reconstruct's existing validation/persistence/conclusion path) or
321
+ * null (the round keeps the TIMEOUT failure face). It calls no `#reject` and
322
+ * produces no outcome — a probe is a question, never a verdict. Implement/fix
323
+ * rounds are outside the promotion domain (their `op` is not the review family). */
324
+ #probeDraft(frame) {
325
+ const op = this.#opOf(frame);
326
+ if (op !== "review")
327
+ return null;
328
+ const face = this.#familyOf(op, frame.type).schema ?? "delivery";
329
+ if (face !== "findings")
330
+ return null;
331
+ const read = this.#readDraft(frame);
332
+ if (read.kind !== "ok")
333
+ return null;
334
+ const draft = read.value;
335
+ if (this.#handoffSchema.violations(face, draft).length > 0)
336
+ return null;
337
+ const findings = Array.isArray(draft.findings) ? draft.findings : [];
338
+ return findings.length >= 1 ? draft : null;
339
+ }
340
+ /** Promote a terminated review round whose draft is valid and carries findings —
341
+ * the terminal ⊥ conclusion exception (D53 Q12): the conclusion derives from the
342
+ * handoff, never from the termination word. The crash record still lands
343
+ * (`promoted: true`, carrying the termination's `idleMs`/last sample), and the
344
+ * lifecycle emits the ONE `CDD_WARN` line — the CLI layer emits none. The outcome
345
+ * is the ordinary read-back outcome (carrier + findings + derived status) plus the
346
+ * termination fact, so the bookkeep records the round and the route derives
347
+ * normally. */
348
+ #promote(frame, draft, termination, dead) {
349
+ const op = this.#opOf(frame);
350
+ const path = this.#scene.ledger.handoffPath(op, frame.type, frame.params);
351
+ const outcome = this.#reconstruct(frame, draft);
352
+ this.#writeCrash(frame, path, `child was terminated: ${termination.cause}`, { exitCode: dead.code, cause: termination.cause, termination }, true);
353
+ const findings = outcome.findings ?? [];
354
+ const text = this.#words.promotionWarning({
355
+ cause: termination.cause,
356
+ idleMs: termination.idleMs,
357
+ verdict: termination.lastSample?.verdict ?? "none",
358
+ count: findings.length,
359
+ });
360
+ this.#io.stderr(`${this.#words.station("warn")} ${text}\n`);
361
+ return { ...outcome, termination };
362
+ }
363
+ /** The read-back reconstruct — the child's draft at OUTPUT_HANDOFF is the round's
364
+ * content source of truth: read it, validate it against the mode's writable
365
+ * subset (projection ② of session/handoff-schema.ts — the SAME declared objects
366
+ * the prompt injected), then build the final carrier the lifecycle persists in
367
+ * place (agent draft → finalized, full-replace at the same path — the engine
368
+ * remains the carrier's single author). A missing or schema-violating draft →
369
+ * BLOCK over the CDD_BLOCKED channel + a crash record + the draft untouched
370
+ * (on failure, no overwrite — the child's work is never clobbered; resume re-runs the same
371
+ * command, which re-offers the round). The test-evidence file (task-family delivery
372
+ * rounds only) is read back with the same stakes: a missing/violating file
373
+ * rewrites the carrier to BLOCKED (persisted — the child's work is kept, marked
374
+ * bad), the second fix for a prose-only claim.
375
+ *
376
+ * `prefetched` is the terminated-review promotion's already-probed draft — the ONE
377
+ * draft parse stays single-sourced (`#readDraft`), and the promotion rides this
378
+ * same validation/persistence/conclusion path rather than a second implementation. */
379
+ #reconstruct(frame, prefetched) {
380
+ const scene = this.#scene;
381
+ const op = this.#opOf(frame);
382
+ const face = this.#familyOf(op, frame.type).schema ?? "delivery";
383
+ const schema = this.#handoffSchema;
384
+ const path = scene.ledger.handoffPath(op, frame.type, frame.params);
385
+ let draft;
386
+ if (prefetched !== undefined) {
387
+ draft = prefetched;
388
+ }
389
+ else {
390
+ // The tri-state draft read — a MISSING draft ("never written") and a MALFORMED
391
+ // one (present but unparseable JSON) are different facts: the rejection reports
392
+ // each truly, so a corrupt draft is never misreported as "not written" (D27).
393
+ // The read is LENIENT (D39): the draft is a child-LLM-authored carrier, and a
394
+ // trailing comma (a routine model slip) must not void the whole round —
395
+ // jsonc-parser tolerates the lenient dialect while a real break (a missing
396
+ // brace, …) still reports malformed.
397
+ const draftRead = this.#readDraft(frame);
398
+ if (draftRead.kind === "missing") {
399
+ return this.#reject(frame, path, `the handoff draft was not written at ${path}`);
400
+ }
401
+ if (draftRead.kind === "malformed") {
402
+ // The lenient face carries the parser's precise error codes (D39) — surface
403
+ // them in the rejection so a genuinely corrupt draft is diagnosable, not just
404
+ // "malformed".
405
+ const codes = (draftRead.errors ?? [])
406
+ .map((error) => printParseErrorCode(error.error))
407
+ .join(", ");
408
+ const detail = codes === "" ? "" : ` (${codes})`;
409
+ return this.#reject(frame, path, `the handoff draft at ${path} is malformed JSON${detail}`);
410
+ }
411
+ draft = draftRead.value;
412
+ }
413
+ const problems = schema.violations(face, draft);
414
+ if (problems.length > 0) {
415
+ return this.#reject(frame, path, `the handoff draft at ${path} violates the ${face} schema: ${problems.join("; ")}`);
416
+ }
417
+ // T2 — the face-aware read: the findings face ALONE reads `draft.findings` (its
418
+ // own declared required field — rolled up to the conclusion); the delivery face
419
+ // derives its status from the draft's declared status, never the findings plane
420
+ // (the delivery writable subset declares no findings field — zero findings read).
421
+ // The conclusion rides the ONE source (`HandoffSchema.conclusionOf`) the ledger
422
+ // legs read too — the reconstruct never rules a delivery status by a second path.
423
+ const findings = face === "findings" ? (Array.isArray(draft.findings) ? draft.findings : []) : [];
424
+ // A validated draft's conclusion is total: the findings face rolls up its own
425
+ // required findings, and the delivery face's `status` passed the `required` gate above
426
+ // — so the `?? "BLOCKED"` never fires here (a delivery draft without a status never
427
+ // reaches this line; the absent→undefined case exists only for on-disk legacy
428
+ // carriers the ledger reads back, never a schema-validated draft).
429
+ let status = schema.conclusionOf(face, draft) ?? "BLOCKED";
430
+ let reason = null;
431
+ // The evidence gate (v1.9) — the delivery faces (implement/fix task+branch) write
432
+ // the canonical `{family-prefix}-{key}-test-evidence.json` under the workspace
433
+ // (§3.7 naming: tasks- for the task families, branch- for the branch fix); the
434
+ // docs faces (review/docs-fix) carry no evidence file. The read-back is REAL — a
435
+ // missing/malformed/schema-violating file rewrites the draft to BLOCKED (each
436
+ // cause reported truly — the tri-state read, D27).
437
+ if (face === "delivery") {
438
+ const evidenceName = this.#naming.evidenceName(frame);
439
+ const evidencePath = scene.workspace.resolve(evidenceName);
440
+ const evidenceRead = scene.workspace.readJson(evidenceName);
441
+ // The SAME tri-state discrimination as the draft leg (D27): a PRESENT-but-corrupt
442
+ // evidence file reports its true cause, never the misleading "missing" — only a
443
+ // genuinely absent file (or a schema-violating present one) rides the schema
444
+ // verdict below.
445
+ if (evidenceRead.kind === "malformed") {
446
+ status = "BLOCKED";
447
+ reason = `the test evidence at ${evidencePath} is malformed JSON`;
448
+ }
449
+ else {
450
+ const evidence = evidenceRead.kind === "ok" ? evidenceRead.value : null;
451
+ const evidenceProblems = schema.evidenceViolations(evidence);
452
+ if (evidenceProblems.length > 0) {
453
+ status = "BLOCKED";
454
+ reason = `the test evidence at ${evidencePath} violates the contract: ${evidenceProblems.join("; ")}`;
455
+ }
456
+ }
457
+ }
458
+ return {
459
+ status,
460
+ findings: face === "findings" ? schema.findingsOf(findings) : undefined,
461
+ carrier: this.#materialize(frame, face, draft, status, reason),
462
+ };
463
+ }
464
+ /** The read-back rejection face — CDD_BLOCKED reason + the crash record (the
465
+ * same-command resume's decision source: the attempted handoff + the resume
466
+ * command) + NO carrier (the bookkeep leaves the draft untouched). The crash
467
+ * record carries the caller's REAL death facts: an absent draft/schema violation
468
+ * is the read-back face (exit 0 · `contract-violation` — the defaults), a dead
469
+ * child passes its own exit code + `child-exit`, and a terminated round passes
470
+ * its whole `termination` fact (cause + last sample) — one record shape, three
471
+ * truthful callers (the record is the postmortem artifact; a misreported death
472
+ * sends a maintainer hunting the wrong fault).
473
+ *
474
+ * The returned status derives from the death facts alone (§4.3 — no status
475
+ * parameter): a termination rides it → `TIMEOUT`; otherwise → `BLOCKED` (the
476
+ * read-back and child-exit callers pass `termination: null`, today's behavior
477
+ * verbatim). */
478
+ #reject(frame, path, reason, death = {
479
+ exitCode: 0,
480
+ cause: "contract-violation",
481
+ termination: null,
482
+ }) {
483
+ this.#writeCrash(frame, path, reason, death, false);
484
+ // A terminated round extends its ONE CDD_BLOCKED line with the idle time and the
485
+ // last sample's verdict (the crash record carries the full sample).
486
+ const detail = death.termination === null
487
+ ? ""
488
+ : this.#words.terminationDetail({
489
+ idleMs: death.termination.idleMs,
490
+ verdict: death.termination.lastSample?.verdict ?? "none",
491
+ });
492
+ this.#io.stderr(`CDD_BLOCKED: ${reason}${detail}\n`);
493
+ if (death.termination === null)
494
+ return { status: "BLOCKED" };
495
+ return { status: "TIMEOUT", termination: death.termination };
496
+ }
497
+ /** Write the lane's crash record — the postmortem artifact and same-command
498
+ * resume's decision source. One writer serves both the rejection face
499
+ * (`promoted: false`) and the termination branch's promotion (`promoted: true`):
500
+ * the record shape is identical, only the promotion fact differs. */
501
+ #writeCrash(frame, path, reason, death, promoted) {
502
+ const op = this.#opOf(frame);
503
+ this.#scene.ledger.writeCrash(`${op}.${frame.type}`, frame.round, {
504
+ exitCode: death.exitCode,
505
+ stderrTail: [reason],
506
+ stdoutTail: this.#stdoutTail,
507
+ // The persisted attempted-handoff path is the CANONICAL repoRoot-relative
508
+ // shape (never the absolute `handoffPath` syscall form — §2.7).
509
+ attemptedHandoff: this.#rel(path),
510
+ next: this.#resumeOf(frame),
511
+ // The cause rides the termination fact when one is present (one of the three
512
+ // causes or the `unknown` fallback); without it, the caller's own cause.
513
+ cause: death.termination?.cause ?? death.cause,
514
+ // The last sample rides WITH the termination (in memory, zero re-read of the
515
+ // heartbeat file) — null on every non-terminated face.
516
+ lastSample: death.termination?.lastSample ?? null,
517
+ promoted,
518
+ idleMs: death.termination?.idleMs ?? null,
519
+ });
520
+ }
521
+ /** Build the final carrier — the validated writable fields from the draft (the
522
+ * engine-seated identity rides the canonical file name, never inline: phase/tasks
523
+ * are not declared and never written — v1.30), persisted by the bookkeep
524
+ * full-replace at the SAME path (agent draft → finalized). The evidence override
525
+ * rewrites the status to BLOCKED + a failure_category + the reason note (the
526
+ * child's work preserved, marked bad). */
527
+ #materialize(frame, face, draft, status, reason) {
528
+ const ledger = this.#scene.ledger;
529
+ const notes = [];
530
+ // The §8.7 classification ruling — the SAME judgment the read-back validator makes
531
+ // (non-declared keys are dropped, never a BLOCK): materialize drops them and books
532
+ // AT MOST ONE WARN on the carrier's notes (auditable, non-interrupting — replacing
533
+ // the retired "BLOCK + crash-resume + reopen" chain). The engine stays the carrier's
534
+ // single author; a child's stray key is surfaced, not obeyed.
535
+ const dropped = this.#handoffSchema.droppedKeys(face, draft);
536
+ if (dropped.length > 0) {
537
+ notes.push(`dropped non-declared draft field(s): ${dropped.join(", ")} — engine-reserved, never written`);
538
+ }
539
+ // The per-face carrier — buildHandoff's typed overloads: the findings face REQUIRES
540
+ // its findings payload (the schema-required field — cli.test pins the review
541
+ // carrier's findings + status), the delivery face builds a findings-FREE typed carrier
542
+ // (the delivery writable subset declares no findings field — the materialized delivery
543
+ // carrier carries zero findings keys). `Record<string, unknown>` local: the round
544
+ // conclusion (status — a RoundStatus, wider than the carrier's declared union) and
545
+ // the engine's extended fields ride the caller's set below.
546
+ const carrier = face === "findings"
547
+ ? ledger.buildHandoff("findings", {
548
+ artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
549
+ findings: this.#findingsList(draft.findings),
550
+ })
551
+ : ledger.buildHandoff("delivery", {
552
+ artifacts: this.#canonicalArtifacts(frame, draft.artifacts, notes),
553
+ });
554
+ // The delivery face ALONE persists the round conclusion — it is the child's own
555
+ // declared status (the schema enum pinned it to APPROVED | BLOCKED). The findings
556
+ // face holds NO status field: its conclusion is DERIVED at judgment time
557
+ // (`HandoffSchema.conclusionOf("findings", carrier)` → rollup(findings)), so the
558
+ // persisted findings carrier stays the pure declaration plane
559
+ // (findings/artifacts/notes) and a fix child's INPUT_REVIEWS carrier is
560
+ // status-free (the judgment face is perpendicular to the input face · D27).
561
+ const draftNotes = Array.isArray(draft.notes) ? [...draft.notes] : [];
562
+ if (face === "delivery") {
563
+ carrier.status = status;
564
+ if (typeof draft.failure_category === "string")
565
+ carrier.failure_category = draft.failure_category;
566
+ // The evidence-contract override (delivery faces only — the evidence gate reads a
567
+ // delivery round's evidence file) rewrites the persisted conclusion to BLOCKED.
568
+ if (reason !== null) {
569
+ carrier.status = "BLOCKED";
570
+ carrier.failure_category = "evidence-contract";
571
+ draftNotes.push(reason);
572
+ }
573
+ }
574
+ if (notes.length > 0 || draftNotes.length > 0)
575
+ carrier.notes = [...notes, ...draftNotes];
576
+ return carrier;
577
+ }
578
+ /** The carrier's artifacts map (find #5 — the engine self-derives, never trusts a
579
+ * child-reported path for the canonical slots): a declared PRESCRIBED slot
580
+ * (report/test_evidence) books the frame's canonical OUTPUT_* path — a
581
+ * free-named deviation is replaced and surfaced on the notes (the review scope
582
+ * axis reads them); the non-prescribed slots (a docs-fix's `doc`, child extras)
583
+ * pass verbatim. undefined when the draft declared no artifacts. */
584
+ #canonicalArtifacts(frame, artifacts, notes) {
585
+ const declared = this.#stringMap(artifacts);
586
+ if (declared === undefined)
587
+ return undefined;
588
+ const out = {};
589
+ for (const [key, value] of Object.entries(declared)) {
590
+ const canonical = this.#prescribedArtifact(frame, key);
591
+ if (canonical === "") {
592
+ // The non-prescribed slots (the pure read input `brief`, a docs-fix's `doc`,
593
+ // child extras) pass verbatim.
594
+ out[key] = value;
595
+ continue;
596
+ }
597
+ // A prescribed slot ALWAYS books the engine's canonical path in the CANONICAL
598
+ // shape (repoRoot-relative — never the absolute `workspace.resolve` form): the
599
+ // persisted carrier's artifacts map carries zero absolute strings (§2.7). The
600
+ // comparison runs on ONE basis (D46 — the child receives relative OUTPUT_*
601
+ // tokens, so a compliant declaration matches); a free-named OR absolute
602
+ // deviation is replaced and surfaced on the notes (the review scope axis reads
603
+ // them).
604
+ const relative = this.#rel(canonical);
605
+ if (this.#rel(value) !== relative) {
606
+ notes.push(`artifact ${key}: declared path ${value} deviates from the prescribed ${canonical} — the canonical path is booked`);
607
+ }
608
+ out[key] = relative;
609
+ }
610
+ return Object.keys(out).length > 0 ? out : undefined;
611
+ }
612
+ /** The prescribed path of one block-artifact slot — a slot the frame's family
613
+ * prescribes (report/test_evidence → the canonical name from `RoundNaming`), ""
614
+ * for every other slot (the pure read input `brief` is never a write slot, and a
615
+ * docs-fix's `doc` is never prescribed — both pass verbatim). */
616
+ #prescribedArtifact(frame, slot) {
617
+ switch (slot) {
618
+ case "report":
619
+ return this.#naming.report(frame);
620
+ case "test_evidence":
621
+ return this.#naming.evidence(frame);
622
+ default:
623
+ return "";
624
+ }
625
+ }
626
+ /** The `## Handoff schema` section value — the mode's writable-subset fence
627
+ * (projection ①; byte-fixed per mode so the prompt's fixed prefix stays
628
+ * cache-friendly). The family's `schema` field selects the face (§3.6: delivery →
629
+ * carrier + evidence fence for the implement/fix modes; findings → the review /
630
+ * docs-fix fence only). */
631
+ #schemaText(frame) {
632
+ const op = this.#opOf(frame);
633
+ const face = this.#familyOf(op, frame.type).schema ?? "delivery";
634
+ const evidence = face === "delivery";
635
+ const prefix = evidence ? this.#naming.prefix(frame) : "tasks";
636
+ return this.#handoffSchema.schemaText(face, evidence, prefix);
637
+ }
638
+ /** The op.type family record — the engine-config handoff namespace single truth
639
+ * (loud on an unknown family: never a second naming table). */
640
+ #familyOf(op, type) {
641
+ const family = this.#config.engineConfig().handoffNamespace.families[`${op}.${type}`];
642
+ if (family === undefined)
643
+ throw new Error(`unknown handoff family: ${op}.${type}`);
644
+ return family;
645
+ }
646
+ /** The artifacts field as a string-map (only string values land — non-string rows
647
+ * are dropped, never coerced). */
648
+ #stringMap(artifacts) {
649
+ if (typeof artifacts !== "object" || artifacts === null || Array.isArray(artifacts))
650
+ return undefined;
651
+ const out = {};
652
+ for (const [key, value] of Object.entries(artifacts)) {
653
+ if (typeof value === "string")
654
+ out[key] = value;
655
+ }
656
+ return Object.keys(out).length > 0 ? out : undefined;
657
+ }
658
+ /** The draft findings as a plain list (the materialized carrier keeps them
659
+ * verbatim; the schema validated their shape before this ran). */
660
+ #findingsList(findings) {
661
+ return Array.isArray(findings) ? findings : [];
662
+ }
663
+ /** The same-command resume string — the crash record's `next`, mirroring the
664
+ * CLI's dispatchable form of this frame (re-run the same command per the BLOCKED
665
+ * `next:` to continue — the idempotent full mode re-run). */
666
+ #resumeOf(frame) {
667
+ const scene = this.#scene;
668
+ const plan = scene.planPath ?? "<plan>";
669
+ switch (frame.phase) {
670
+ case "implement":
671
+ return `cdd implement --tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
672
+ case "branch-review":
673
+ // The branch re-review literal carries only the workspace-identity `--plan`
674
+ // — the review judges the live tree (the scope anchor BASE_BRANCH is
675
+ // engine-injected at dispatch), so no range rides the command.
676
+ return `cdd review --type branch --plan ${plan}`;
677
+ case "review":
678
+ if (frame.type === "spec")
679
+ return `cdd review --type spec --spec ${this.#docOf(frame)}`;
680
+ if (frame.type === "plan")
681
+ return `cdd review --type plan --plan ${this.#docOf(frame)}`;
682
+ return `cdd review --type wave --tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
683
+ case "fix": {
684
+ const findings = scene.ledger.handoffPath("review", frame.type, frame.params);
685
+ const target = frame.target.kind === "plan" || frame.target.kind === "spec"
686
+ ? `--${frame.type === "spec" ? "spec" : "plan"} ${frame.target.doc}`
687
+ : // The branch fix carries no refs — the source findings ride the
688
+ // --reviews handoff; the workspace-identity `--plan` still rides
689
+ // (the plan is the branch line's identity, zero orchestrator fallback).
690
+ frame.target.kind === "branch"
691
+ ? `--plan ${plan}`
692
+ : `--tasks ${frame.params.tasks ?? ""} --plan ${plan}`;
693
+ return `cdd fix --type ${frame.type} ${target} --reviews ${findings}`;
694
+ }
695
+ }
696
+ }
697
+ /** The doc path of a doc-target frame (the `""` never lands — the reject paths
698
+ * only frame docs). */
699
+ #docOf(frame) {
700
+ return frame.target.kind === "plan" || frame.target.kind === "spec" ? frame.target.doc : "";
701
+ }
702
+ }