@oscaner-skills/cdd-engine 1.0.0 → 2.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 (99) hide show
  1. package/README.md +9 -8
  2. package/README.zh-CN.md +9 -8
  3. package/package.json +15 -22
  4. package/src-next/__tests__/bin.test.ts +128 -0
  5. package/src-next/__tests__/smoke.integration.test.ts +202 -0
  6. package/src-next/__tests__/zero-dep.test.ts +134 -0
  7. package/src-next/bin.ts +61 -0
  8. package/src-next/contract/__tests__/__snapshots__/project.schema.overall-spec.snap +238 -0
  9. package/src-next/contract/__tests__/__snapshots__/project.schema.phase-spec.snap +153 -0
  10. package/src-next/contract/__tests__/__snapshots__/project.schema.plan.snap +173 -0
  11. package/src-next/contract/__tests__/__snapshots__/project.schema.single-spec.snap +89 -0
  12. package/src-next/contract/__tests__/__snapshots__/project.shape.overall-spec.snap +225 -0
  13. package/src-next/contract/__tests__/__snapshots__/project.shape.phase-spec.snap +155 -0
  14. package/src-next/contract/__tests__/__snapshots__/project.shape.plan.snap +175 -0
  15. package/src-next/contract/__tests__/__snapshots__/project.shape.single-spec.snap +85 -0
  16. package/src-next/contract/__tests__/declare.test.ts +242 -0
  17. package/src-next/contract/__tests__/doc.test.ts +358 -0
  18. package/src-next/contract/__tests__/judge.test.ts +873 -0
  19. package/src-next/contract/__tests__/lint.test.ts +314 -0
  20. package/src-next/contract/__tests__/project.test.ts +419 -0
  21. package/src-next/contract/__tests__/translate.test.ts +96 -0
  22. package/src-next/contract/declare.ts +983 -0
  23. package/src-next/contract/doc.ts +753 -0
  24. package/src-next/contract/invariants.ts +1268 -0
  25. package/src-next/contract/judge.ts +142 -0
  26. package/src-next/contract/lint.ts +275 -0
  27. package/src-next/contract/project.ts +596 -0
  28. package/src-next/contract/skill-anatomy.ts +273 -0
  29. package/src-next/contract/translate.ts +113 -0
  30. package/src-next/face/__tests__/board-view.test.ts +948 -0
  31. package/src-next/face/__tests__/capsule.test.ts +276 -0
  32. package/src-next/face/__tests__/channel-closure.guard.test.ts +102 -0
  33. package/src-next/face/__tests__/cli.test.ts +4643 -0
  34. package/src-next/face/__tests__/face.test.ts +289 -0
  35. package/src-next/face/__tests__/graph-view.test.ts +61 -0
  36. package/src-next/face/__tests__/host.test.ts +24 -0
  37. package/src-next/face/__tests__/negation.ts +6 -0
  38. package/src-next/face/__tests__/projection.test.ts +301 -0
  39. package/src-next/face/__tests__/sync-runner.test.ts +70 -0
  40. package/src-next/face/__tests__/words.guard.test.ts +93 -0
  41. package/src-next/face/artifacts.ts +195 -0
  42. package/src-next/face/board-view.ts +662 -0
  43. package/src-next/face/capsule.ts +149 -0
  44. package/src-next/face/cli.ts +819 -0
  45. package/src-next/face/declare.ts +326 -0
  46. package/src-next/face/gate.ts +170 -0
  47. package/src-next/face/graph-view.ts +74 -0
  48. package/src-next/face/host.ts +326 -0
  49. package/src-next/face/lifecycle.ts +700 -0
  50. package/src-next/face/projection.ts +282 -0
  51. package/src-next/face/route-render.ts +160 -0
  52. package/src-next/face/words.ts +296 -0
  53. package/src-next/infra/__tests__/infra.test.ts +287 -0
  54. package/src-next/infra/config.ts +42 -0
  55. package/src-next/infra/git.ts +39 -0
  56. package/src-next/infra/process.ts +34 -0
  57. package/src-next/infra/runtime.ts +185 -0
  58. package/src-next/infra/workspace.ts +232 -0
  59. package/src-next/render/__tests__/render.test.ts +499 -0
  60. package/src-next/render/__tests__/skeleton.test.ts +466 -0
  61. package/src-next/render/brief.ts +121 -0
  62. package/src-next/render/issue-body.ts +159 -0
  63. package/src-next/render/skeleton.ts +437 -0
  64. package/src-next/render/templates.ts +650 -0
  65. package/src-next/session/__tests__/graph.test.ts +270 -0
  66. package/src-next/session/__tests__/handoff-plane.guard.test.ts +48 -0
  67. package/src-next/session/__tests__/handoff-schema.test.ts +310 -0
  68. package/src-next/session/__tests__/ledger.test.ts +744 -0
  69. package/src-next/session/__tests__/next.test.ts +368 -0
  70. package/src-next/session/__tests__/preflight.test.ts +491 -0
  71. package/src-next/session/__tests__/run.test.ts +1014 -0
  72. package/src-next/session/__tests__/wave-line-phase.guard.test.ts +49 -0
  73. package/src-next/session/__tests__/wave.test.ts +469 -0
  74. package/src-next/session/faces.ts +110 -0
  75. package/src-next/session/graph.ts +411 -0
  76. package/src-next/session/handoff-schema.ts +373 -0
  77. package/src-next/session/ledger.ts +1004 -0
  78. package/src-next/session/next.ts +192 -0
  79. package/src-next/session/preflight.ts +240 -0
  80. package/src-next/session/run.ts +606 -0
  81. package/src-next/session/state.ts +30 -0
  82. package/src-next/session/wave.ts +139 -0
  83. package/templates/report/issue-body.json +18 -20
  84. package/dist/chunks/branch.mjs +0 -480
  85. package/dist/chunks/docs.mjs +0 -253
  86. package/dist/chunks/task.mjs +0 -913
  87. package/dist/cli.mjs +0 -5457
  88. package/dist/documents/schema/add-phase-protocol.json +0 -126
  89. package/dist/documents/schema/overall.json +0 -361
  90. package/dist/documents/schema/phase-spec.json +0 -145
  91. package/dist/documents/schema/plan.json +0 -191
  92. package/dist/documents/schema/skill-anatomy.json +0 -233
  93. package/dist/resources/harness-registry.json +0 -49
  94. package/dist/shared/cdd-engine.liioziig.mjs +0 -184
  95. package/templates/engine-config.json +0 -302
  96. package/templates/schema/cache-profile-schema.json +0 -23
  97. package/templates/schema/docs-handoff-schema.json +0 -129
  98. package/templates/schema/task-handoff-schema.json +0 -332
  99. package/templates/template-contract.json +0 -231
@@ -1,480 +0,0 @@
1
- import { existsSync, readFileSync, mkdirSync } from 'node:fs';
2
- import path from 'node:path';
3
- import { B as getRoot, I as resolveWorkspace, J as familyConfig, s as exitWithCode, h as handoffName, w as writeHandoff, d as ReturnBlockParser, K as exitOk, u as resolveDocArg, r as readJson, k as writeBlockedCarrier, T as TemplateLoader, f as finalizeHandoff, a as writeOwnHandoff, b as DispatchLifecycle, l as FAILURE_CATEGORIES, R as ResidueManager, H as HandoffSchemaValidator, m as recoverHandoff, L as resolveNextRound, x as prevHandoffPath, M as ConvergenceChecker } from '../cli.mjs';
4
- import { E as EngineInvoker, R as Registry, a as REG_PATH, C as CddBlockedError } from '../shared/cdd-engine.liioziig.mjs';
5
- import 'node:process';
6
- import 'citty';
7
- import 'node:url';
8
- import 'tinyglobby';
9
- import 'node:child_process';
10
- import 'ajv';
11
- import 'execa';
12
- import 'simple-git';
13
- import 'node:crypto';
14
- import 'hookable';
15
- import 'handlebars';
16
-
17
- const registry = new Registry();
18
- const invoker = new EngineInvoker();
19
- const templates = new TemplateLoader();
20
- const convergence = new ConvergenceChecker();
21
- const schema = new HandoffSchemaValidator();
22
- const residue = new ResidueManager();
23
- const returnBlocks = new ReturnBlockParser();
24
- class BranchLifecycle extends DispatchLifecycle {
25
- opts;
26
- entry = null;
27
- repoRoot = "";
28
- workspace = "";
29
- handoffPath = "";
30
- /** invoke result code of the just-finished agent dispatch (schemaValidate reads it for the
31
- * failure-without-handoff lanes). */
32
- agentRc = 0;
33
- /** the schema-validated / recovered handoff (schemaValidate → normalizeResult handoff). */
34
- agentHandoff = null;
35
- /** post-finalization exit code — normalizeResult stores it; the fix wrapper emits it AFTER the
36
- * inherited exit gate ran (the gate failure rewrites the handoff and exits 1 before this is
37
- * read; the review wrapper never reads it — review's normalizeResult exits immediately). */
38
- finalExitCode = 0;
39
- /** The stored round conclusion (post-run read for the fix wrapper's exit). */
40
- get exitCode() {
41
- return this.finalExitCode;
42
- }
43
- constructor(options) {
44
- const { ctx, ...opts } = options;
45
- super({ ctx });
46
- this.opts = { ...opts };
47
- }
48
- /** Branch-family entry gate: NO-OP — branch review/fix rounds are ref-driven and never gate on
49
- * the pre-commit clean tree (the former cli flat bodies ran none). The working-tree contract of
50
- * the fix channel lives at the EXIT gate (inherited default commitPostCheck). */
51
- async commitPreCheck(_hookCtx) {
52
- }
53
- /** Lane-declared doc-audit target (T3 ④「lane 声明审计对象」): the branch channel audits its
54
- * `--plan` ref (the same plan the review/fix round derives its workspace from) — the base default
55
- * docContractValidate walks plan → `**Spec:**` → Parent program → overall and gates on the
56
- * parent-overall four tables when the lineage resolves. */
57
- docAuditTarget() {
58
- if (!this.opts.plan) return null;
59
- try {
60
- return resolveDocArg(this.opts.plan, this.repoRoot, "plan");
61
- } catch {
62
- return this.opts.plan;
63
- }
64
- }
65
- /** Plan-bearing declaration (P2 T4): the branch lane is ALWAYS plan-bearing — the closeout
66
- * terminal-debt hard gate and the base-default statusValidate key off its `--plan` ref (v1.12:
67
- * the v1.11 lane boundary is rescinded — branch-review's precondition IS the ended plan, so its
68
- * backfill obligation is already due and the gate is the correct behavior). */
69
- dispatchPlanPath() {
70
- return this.docAuditTarget();
71
- }
72
- /** Doc-contract BLOCK face (T3 ④): the branch terminal convention — stderr CDD_BLOCKED +
73
- * exitWithCode(1) (exit helpers throw ExitRequested, the bin maps the exact code; the default
74
- * DispatchBlocked throw would escape the wrappers' gate filters and land on exit 2). */
75
- docContractBlocked(guidance) {
76
- process.stderr.write(
77
- `CDD_BLOCKED: doc contract validation failed \u2014 fix the docs below:
78
- ${guidance}
79
- `
80
- );
81
- exitWithCode(1);
82
- }
83
- /** Registry ship gate (spec step 1): resolve the harness entry + dry-run-path CLI-existence
84
- * check. Failure → the message on stderr + the kind's exit code (cli-missing → 2, blocked → 1;
85
- * the CLI 0/1/2 table preserved — CddBlockedError.exitCode IS that code). A non-CddBlockedError
86
- * registry failure (e.g. corrupt registry JSON) rethrows to the caller surface. */
87
- registryGate() {
88
- try {
89
- this.entry = registry.checkHarness(
90
- registry.load(this.opts.registryPath ?? REG_PATH),
91
- this.opts.harness,
92
- {
93
- dryRun: this.opts.dryRun
94
- }
95
- );
96
- } catch (e) {
97
- if (e instanceof CddBlockedError) {
98
- process.stderr.write(`${e.message}
99
- `);
100
- exitWithCode(e.exitCode);
101
- }
102
- throw e;
103
- }
104
- }
105
- /** BLOCKED-carrier commits — only when the base satisfies the schema's `^[0-9a-f]{40}$`: a
106
- * short-form base is carried by the AC15 base7..head7 file name, and a BLOCKED payload must
107
- * always pass its own validation. head included only when present (branch-review carries the
108
- * reviewed range head; branch-fix has no head yet). */
109
- branchCarrierCommits(base, head) {
110
- const fullBase = typeof base === "string" && /^[0-9a-f]{40}$/.test(base) ? base : null;
111
- if (!fullBase) return void 0;
112
- return { base: fullBase, ...typeof head === "string" && head ? { head } : {} };
113
- }
114
- /** Shared schema-validate lane (single implementation for both branch channels — the former two
115
- * hook bodies were structurally identical parallel implementations of the same sequence; one
116
- * helper keeps the agent-failure / no-handoff / schema-recovery lanes from drifting between
117
- * branch-review and branch-fix). Every lane writes the BLOCKED carrier and exits 1; on recovery
118
- * the normalized handoff replaces the agent's file. `phase` is the handoff phase field, `label`
119
- * the channel word in the CDD_BLOCKED diagnostics, `reRun` the re-run command phrase in the
120
- * blockers, `commits` the channel's BLOCKED-carrier commits subset. T25: the execution-failure
121
- * lane records the death diagnosis (recovery.cause + exit_code) and preserves the dirty-tree
122
- * residue INLINE (these lanes abort via exitWithCode — the template post-flight settleResidue
123
- * step never fires on the branch channel). */
124
- async schemaValidateBranch(options) {
125
- const { phase, label, reRun, commits } = options;
126
- if (this.agentRc !== 0 && !existsSync(this.handoffPath)) {
127
- writeBlockedCarrier(this.handoffPath, {
128
- tasks: [1],
129
- phase,
130
- ...commits ? { commits } : {},
131
- recovery: { cause: FAILURE_CATEGORIES.EXECUTION_FAILURE.id, exit_code: this.agentRc },
132
- blocker: `cli exited ${this.agentRc}${this.agentRc === 143 ? " (SIGTERM \u2014 externally killed)" : ""} without writing handoff \u2192 worktree residue is preserved as a stash (\`git stash list\` \u2192 \`git stash apply <ref>\` \u2192 review \u2192 commit to salvage or \`git stash drop\` to discard) \u2192 re-run ${reRun}`
133
- });
134
- process.stderr.write(`CDD_BLOCKED: ${label} failed (exit ${this.agentRc})
135
- `);
136
- await residue.preserveAndAnnounceResidue(this.repoRoot, this.handoffPath, this.repoRoot);
137
- exitWithCode(1);
138
- }
139
- if (!existsSync(this.handoffPath)) {
140
- writeBlockedCarrier(this.handoffPath, {
141
- tasks: [1],
142
- phase,
143
- ...commits ? { commits } : {},
144
- blocker: `${path.basename(this.handoffPath)} not written after exit 0 \u2192 re-run ${reRun}`
145
- });
146
- process.stderr.write(`CDD_BLOCKED: ${label} handoff not written
147
- `);
148
- exitWithCode(1);
149
- }
150
- let agentHandoff;
151
- try {
152
- agentHandoff = JSON.parse(readFileSync(this.handoffPath, "utf8"));
153
- } catch (e) {
154
- writeBlockedCarrier(this.handoffPath, {
155
- tasks: [1],
156
- phase,
157
- ...commits ? { commits } : {},
158
- blocker: `${label} handoff JSON unparseable: ${e.message} \u2192 fix the handoff at ${this.handoffPath} and re-run ${reRun}`
159
- });
160
- process.stderr.write(`CDD_BLOCKED: ${label} handoff JSON unparseable
161
- `);
162
- exitWithCode(1);
163
- }
164
- let handoff = agentHandoff;
165
- const sv = schema.validateHandoffSchema(agentHandoff, "task");
166
- if (!sv.valid) {
167
- const rec = recoverHandoff(agentHandoff, "task");
168
- if (!rec.valid) {
169
- writeBlockedCarrier(this.handoffPath, {
170
- tasks: [1],
171
- phase,
172
- ...commits ? { commits } : {},
173
- findings: rec.preservedFindings,
174
- blocker: `${label} handoff schema invalid${rec.reason} \u2192 fix and re-run ${reRun}`,
175
- fullReplace: true
176
- // violating keys never stay on disk
177
- });
178
- process.stderr.write(`CDD_BLOCKED: ${label} handoff schema invalid
179
- `);
180
- exitWithCode(1);
181
- }
182
- writeOwnHandoff(this.handoffPath, rec.handoff);
183
- handoff = rec.handoff;
184
- }
185
- this.agentHandoff = handoff;
186
- }
187
- }
188
- class BranchReviewLifecycle extends BranchLifecycle {
189
- #base;
190
- #head;
191
- constructor(options) {
192
- super(options);
193
- this.#base = options.base;
194
- this.#head = options.head;
195
- }
196
- /** Round/ref derivation: per-ref round seq (resolveNextRound over the concrete base7/head7) +
197
- * --round backfill validation (conflict → exit 2) + Convergence prev read (canonical
198
- * prevHandoffPath concrete-matches the same ref) + the per-round handoff filename + workspace
199
- * bootstrap. */
200
- async resolveContext(_hookCtx) {
201
- this.registryGate();
202
- this.repoRoot = this.opts.root ?? getRoot();
203
- const base = String(this.#base);
204
- const head = String(this.#head);
205
- const base7 = base.slice(0, 7);
206
- const head7 = head.slice(0, 7);
207
- this.workspace = resolveWorkspace(this.opts.plan, this.repoRoot);
208
- const round = resolveNextRound(this.workspace, "review", "branch", {
209
- base7,
210
- head7
211
- });
212
- if (this.opts.round && Number(this.opts.round) !== round) {
213
- process.stderr.write(`--round ${this.opts.round} \u2260 engine round ${round}
214
- `);
215
- exitWithCode(2);
216
- }
217
- const prevPath = prevHandoffPath(this.workspace, "review", "branch", round, {
218
- base7,
219
- head7
220
- });
221
- let prev = null;
222
- if (prevPath && existsSync(prevPath)) {
223
- try {
224
- prev = JSON.parse(readFileSync(prevPath, "utf8"));
225
- } catch {
226
- process.stderr.write(
227
- `CDD_INFO: corrupt prev branch handoff ${prevPath} ignored \u2192 fail-open
228
- `
229
- );
230
- prev = null;
231
- }
232
- }
233
- if (prev) convergence.reviewConvergenceGuard(prev, "branch", round, `${base7}..${head7}`);
234
- this.handoffPath = path.join(
235
- this.workspace,
236
- handoffName("review", "branch", { base7, head7, round })
237
- );
238
- mkdirSync(this.workspace, { recursive: true });
239
- }
240
- /** Steps 7/8: render the branch-review prompt (docs-family shell + REVIEW_REFERENCE
241
- * base..head + review-family round-context slots) and spawn the harness CLI. Dry-run:
242
- * APPROVED stub handoff + the 5-line return block (assembleReturnBlock — the return-block single
243
- * point) + exit 0. */
244
- async dispatch(_hookCtx) {
245
- const base = String(this.#base);
246
- const head = String(this.#head);
247
- if (this.opts.dryRun) {
248
- writeHandoff(this.handoffPath, {
249
- tasks: [1],
250
- phase: "branch-review",
251
- status: "APPROVED",
252
- commits: { base, head },
253
- findings: [],
254
- artifacts: {},
255
- blocker: "dry-run"
256
- });
257
- const returnBlock = returnBlocks.assembleReturnBlock(
258
- {
259
- status: "APPROVED",
260
- commits: `base=${base} head=${head}`,
261
- artifacts: "",
262
- blocker: "dry-run"
263
- },
264
- this.workspace
265
- );
266
- for (const line of returnBlock) process.stdout.write(`${line}
267
- `);
268
- exitOk();
269
- return;
270
- }
271
- const cfg = templates.reviewTypeConfig("branch");
272
- const art = templates.reviewArtifactConfig("branch");
273
- const prompt = templates.renderTemplate(
274
- "review",
275
- {
276
- MODE: "review",
277
- REVIEW_TYPE: "branch",
278
- WORKSPACE: this.workspace,
279
- WORKSPACE_SLUG: path.basename(this.workspace),
280
- REVIEW_LENS_GUIDE: cfg.lensEnum.join(" \xB7 "),
281
- REVIEW_REFERENCE: `${base}..${head}`,
282
- REVIEW_AXES: cfg.axesGuide,
283
- HANDOFF_TARGET: this.handoffPath,
284
- RETURN_FORMAT: art.returnFormat,
285
- REVIEW_PLAN_LINE: this.opts.plan ? `**Plan:** ${this.opts.plan}` : "",
286
- HANDOFF_WRITE_GATE: templates.reviewHardGate(art.returnFormat, this.handoffPath)
287
- },
288
- "cdd review"
289
- );
290
- const terminationCfg = invoker.resolveTerminationConfig("review", void 0, this.workspace);
291
- const res = await invoker.invokeCliWithRetry(
292
- this.entry,
293
- prompt,
294
- { op: "review", type: "branch" },
295
- process.env,
296
- this.repoRoot,
297
- terminationCfg
298
- );
299
- this.agentRc = res.code;
300
- }
301
- /** Steps 8.8/10/10.5: agent-failure / no-handoff lanes (BLOCKED carrier writes) + schema
302
- * recovery + the review-family finalization read-back. */
303
- async schemaValidate(_hookCtx) {
304
- const base = String(this.#base);
305
- const head = String(this.#head);
306
- await this.schemaValidateBranch({
307
- phase: "branch-review",
308
- label: "branch-review",
309
- reRun: "branch-review",
310
- commits: this.branchCarrierCommits(base, head)
311
- });
312
- }
313
- /** Status single authority (T5/T7) — branch review (review family) reads back through finalizeHandoff
314
- * finalization (rollup derived override, SP-4 exempts failure rounds); the finalized write uses
315
- * writeOwnHandoff (the engine is the carrier's sole author, full-replace). The three consumers
316
- * (runner/docs-runner/cdd) share the same finalizeHandoff single point.
317
- * The exit comes from the finalized round conclusion (Task 23 ③: BLOCKED → 1,
318
- * APPROVED/CHANGES_REQUESTED → 0) — this is the sole exit path once the agent wrote a handoff. */
319
- async normalizeResult(_hookCtx) {
320
- const base = String(this.#base);
321
- const head = String(this.#head);
322
- const finalized = await finalizeHandoff({ mode: "review", agentHandoff: this.agentHandoff });
323
- let handoff = finalized.handoff;
324
- if (handoff && typeof handoff === "object" && handoff.commits === void 0) {
325
- const cc = this.branchCarrierCommits(base, head);
326
- if (cc) handoff = { ...handoff, commits: cc };
327
- }
328
- if (handoff && handoff !== this.agentHandoff) writeOwnHandoff(this.handoffPath, handoff);
329
- exitWithCode(finalized.exitCode);
330
- }
331
- /** Review-family exit gate: NO-OP — a review writes no code, there is no commit contract to
332
- * validate (the branch-fix channel inherits the base default instead). */
333
- async commitPostCheck(_hookCtx) {
334
- }
335
- }
336
- class BranchFixLifecycle extends BranchLifecycle {
337
- #base7 = "";
338
- #head7 = "";
339
- #fixRound = 0;
340
- /** the derived FIX_BASE (source review's commits.base — the reviewed range base). */
341
- fixBase = "";
342
- constructor(options) {
343
- super(options);
344
- }
345
- /** Round/ref derivation from the source review file name (the --findings path). The findings
346
- * name must mirror the source's ref + round: the ref segments are re-derived from the SAME
347
- * canonical family template with capturing groups (identical placeholder substitution rules as
348
- * roundPattern → the config name stays the single truth). Group order: [1]=base7 [2]=head7
349
- * [3]=round. A non-matching findings name → usage error exit 2 (before any path resolution — the
350
- * guard order contract, §2.4.2); a fixRound < 1 → usage error exit 2. */
351
- async resolveContext(_hookCtx) {
352
- this.registryGate();
353
- this.repoRoot = this.opts.root ?? getRoot();
354
- this.workspace = resolveWorkspace(this.opts.plan, this.repoRoot);
355
- const findingsBase = path.basename(this.opts.findings);
356
- const refRoundRe = new RegExp(
357
- "^" + familyConfig("review", "branch").name.replace("{round}", "(\\d+)").replace("{base7}", "([0-9a-f]{7})").replace("{head7}", "([0-9a-f]{7})").replaceAll(".", "\\.") + "$"
358
- );
359
- const refRound = findingsBase.match(refRoundRe);
360
- if (!refRound) {
361
- process.stderr.write(
362
- `cdd fix --type branch: --findings must name a branch-review-{base7}..{head7}-r{R}.json file (round + ref derived from the source review); got: ${this.opts.findings}
363
- `
364
- );
365
- exitWithCode(2);
366
- }
367
- this.#base7 = refRound[1];
368
- this.#head7 = refRound[2];
369
- this.#fixRound = Number(refRound[3]);
370
- if (!Number.isInteger(this.#fixRound) || this.#fixRound < 1) {
371
- process.stderr.write(
372
- `cdd fix --type branch: --findings round must be >= 1 (round derived from the source review); got: ${this.opts.findings}
373
- `
374
- );
375
- exitWithCode(2);
376
- }
377
- this.handoffPath = path.join(
378
- this.workspace,
379
- handoffName("fix", "branch", {
380
- base7: this.#base7,
381
- head7: this.#head7,
382
- round: this.#fixRound
383
- })
384
- );
385
- this.ctx = { ...this.ctx, handoffPath: this.handoffPath, repoRoot: this.repoRoot };
386
- }
387
- /** Steps 7/8: derive the FIX_BASE (source review's commits.base; missing/unknown → BLOCKED
388
- * carrier + exit 1), render the fix prompt (task-family shell + RETURN_STDOUT_BLOCK), spawn the
389
- * fix agent CLI. Dry-run: APPROVED stub handoff + the 5-line return block + exit 0. */
390
- async dispatch(_hookCtx) {
391
- if (this.opts.dryRun) {
392
- writeHandoff(this.handoffPath, {
393
- tasks: [1],
394
- phase: "fix",
395
- status: "APPROVED",
396
- commits: { base: "dry-run", head: "dry-run" },
397
- findings: [],
398
- artifacts: {},
399
- blocker: "dry-run"
400
- });
401
- const returnBlock = returnBlocks.assembleReturnBlock(
402
- {
403
- status: "APPROVED",
404
- commits: "base=dry-run head=dry-run",
405
- artifacts: "",
406
- blocker: "dry-run"
407
- },
408
- this.workspace
409
- );
410
- for (const line of returnBlock) process.stdout.write(`${line}
411
- `);
412
- exitOk();
413
- return;
414
- }
415
- const findingsPath = resolveDocArg(this.opts.findings, this.repoRoot, "findings");
416
- const src = readJson(findingsPath);
417
- const fixBase = src?.commits?.base;
418
- if (!fixBase || fixBase === "unknown") {
419
- writeBlockedCarrier(this.handoffPath, {
420
- tasks: [1],
421
- phase: "fix",
422
- blocker: `source review handoff ${findingsPath} has no valid commits.base \u2192 cannot derive the fix BASE; fix the source review and re-run cdd fix --type branch`
423
- });
424
- process.stderr.write(`CDD_BLOCKED: branch-fix source review missing commits.base
425
- `);
426
- exitWithCode(1);
427
- }
428
- this.fixBase = fixBase;
429
- const prompt = templates.renderTemplate(
430
- "fix",
431
- {
432
- MODE: "fix",
433
- WORKSPACE: this.workspace,
434
- WORKSPACE_SLUG: path.basename(this.workspace),
435
- FINDINGS: findingsPath,
436
- FIXED_POINT: fixBase,
437
- BRIEF: this.opts.plan,
438
- HANDOFF_TARGET: this.handoffPath,
439
- REVIEW_PLAN_LINE: this.opts.plan ? `**Plan:** ${this.opts.plan}` : "",
440
- RETURN_FORMAT: "RETURN_STDOUT_BLOCK",
441
- HANDOFF_WRITE_GATE: templates.reviewHardGate("RETURN_STDOUT_BLOCK", this.handoffPath)
442
- },
443
- "cdd fix"
444
- );
445
- const terminationCfg = invoker.resolveTerminationConfig("review", void 0, this.workspace);
446
- const res = await invoker.invokeCliWithRetry(
447
- this.entry,
448
- prompt,
449
- { op: "fix", type: "branch" },
450
- process.env,
451
- this.repoRoot,
452
- terminationCfg
453
- );
454
- this.agentRc = res.code;
455
- }
456
- /** Steps 8.8/10/10.5: agent-failure / no-handoff lanes + schema recovery (the commit-contract
457
- * BLOCKED rewrite rides the inherited exit gate in the next step). BLOCKED carrier commits carry
458
- * ONLY the FIX_BASE when 40-hex — a BLOCKED fix has no head yet (mirror of the former
459
- * writeBranchFixBlocked shape). */
460
- async schemaValidate(_hookCtx) {
461
- await this.schemaValidateBranch({
462
- phase: "fix",
463
- label: "branch-fix",
464
- reRun: "cdd fix --type branch",
465
- commits: this.branchCarrierCommits(this.fixBase)
466
- });
467
- }
468
- /** Finalize through the single finalization point (mode=fix → work-type passthrough: the
469
- * agent-declared status stays, vetoed by the commit-contract layer just below). Task 23 ③: the
470
- * fix round conclusion → exit (BLOCKED → 1, APPROVED/CHANGES_REQUESTED → 0) — captured here,
471
- * emitted by the wrapper AFTER the (inherited) exit gate ran clean. */
472
- async normalizeResult(_hookCtx) {
473
- const finalized = await finalizeHandoff({ mode: "fix", agentHandoff: this.agentHandoff });
474
- if (finalized.handoff && finalized.handoff !== this.agentHandoff)
475
- writeOwnHandoff(this.handoffPath, finalized.handoff);
476
- this.finalExitCode = finalized.exitCode;
477
- }
478
- }
479
-
480
- export { BranchFixLifecycle, BranchLifecycle, BranchReviewLifecycle };