@loucompanion/forge-bridge 0.1.1-dev.4f31cdd58cac → 0.1.1-dev.5093acd6bece

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.
@@ -3,9 +3,89 @@ import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
4
  import { fileURLToPath } from "node:url";
5
5
  import { redactSecrets } from "../shared/redaction/redaction.js";
6
+ import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "./qa-sidecar-validation.js";
6
7
  const toolServerName = "forge";
7
8
  const completionRedactionSecretsEnv = "FORGE_COMPLETION_REDACTION_SECRETS";
8
9
  const completionPhaseOrder = ["implementation", "self_review", "validation"];
10
+ export const debugCompletionPhaseOrder = [
11
+ "debug_repro",
12
+ "debug_root_cause",
13
+ "debug_fix",
14
+ "debug_regression"
15
+ ];
16
+ export const qaCompletionGateOrder = [
17
+ "qa_plan",
18
+ "qa_regression",
19
+ "qa_api",
20
+ "qa_manual_web",
21
+ "qa_bug_repro",
22
+ "qa_findings",
23
+ "qa_verdict"
24
+ ];
25
+ export const draftCompletionGateOrder = [
26
+ "draft_intent",
27
+ "draft_repo_context",
28
+ "draft_graph_context",
29
+ "draft_product_scope",
30
+ "draft_work_order_plan",
31
+ "draft_critic",
32
+ "draft_proposal"
33
+ ];
34
+ const draftGateFileNames = {
35
+ draft_intent: "draft.intent.json",
36
+ draft_repo_context: "draft.repo-context.json",
37
+ draft_graph_context: "draft.graph-context.json",
38
+ draft_product_scope: "draft.product-scope.json",
39
+ draft_work_order_plan: "draft.work-order-plan.json",
40
+ draft_critic: "draft.critic.json",
41
+ draft_proposal: "draft.proposal.json"
42
+ };
43
+ const draftGateToolNames = {
44
+ draft_intent: "complete_draft_intent",
45
+ draft_repo_context: "complete_draft_repo_context",
46
+ draft_graph_context: "complete_draft_graph_context",
47
+ draft_product_scope: "complete_draft_product_scope",
48
+ draft_work_order_plan: "complete_draft_work_order_plan",
49
+ draft_critic: "complete_draft_critic",
50
+ draft_proposal: "complete_draft_proposal"
51
+ };
52
+ const qaGateFileNames = {
53
+ qa_plan: "qa.plan.json",
54
+ qa_regression: "qa.regression.json",
55
+ qa_api: "qa.api.json",
56
+ qa_manual_web: "qa.manual-web.json",
57
+ qa_bug_repro: "qa.bug-repro.json",
58
+ qa_findings: "qa.findings.json",
59
+ qa_verdict: "qa.verdict.json"
60
+ };
61
+ const qaGateToolNames = {
62
+ qa_plan: "complete_qa_plan",
63
+ qa_regression: "complete_qa_regression",
64
+ qa_api: "complete_qa_api",
65
+ qa_manual_web: "complete_qa_manual_web",
66
+ qa_bug_repro: "complete_qa_bug_repro",
67
+ qa_findings: "complete_qa_findings",
68
+ qa_verdict: "complete_qa_verdict"
69
+ };
70
+ const debugGateToolNames = {
71
+ debug_repro: "complete_debug_repro",
72
+ debug_root_cause: "complete_debug_root_cause",
73
+ debug_fix: "complete_debug_fix",
74
+ debug_regression: "complete_debug_regression"
75
+ };
76
+ const qaBlockerReasons = new Set([
77
+ "missing_app_launch_target",
78
+ "inconclusive",
79
+ "environment_failure",
80
+ "missing_validation_evidence",
81
+ "missing_worktree",
82
+ "runner_failure"
83
+ ]);
84
+ const resolvedFindingStatusValues = ["resolved", "disputed", "not_reproduced"];
85
+ const resolvedFindingStatuses = new Set(resolvedFindingStatusValues);
86
+ const qaFindingSeverities = new Set(["critical", "major", "minor"]);
87
+ const qaFindingScopes = new Set(["in_scope", "out_of_scope", "unclear"]);
88
+ const qaCandidateBugActions = new Set(["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"]);
9
89
  const phaseFiles = {
10
90
  implementation: {
11
91
  jsonFileName: "implementation.completeness.json",
@@ -18,6 +98,34 @@ const phaseFiles = {
18
98
  validation: {
19
99
  jsonFileName: "validation.verdict.json",
20
100
  reportFileName: "validation.report.md"
101
+ },
102
+ qa: {
103
+ jsonFileName: "qa.verdict.json",
104
+ reportFileName: "qa.report.md"
105
+ },
106
+ debug_repro: {
107
+ jsonFileName: "debug.repro.json",
108
+ reportFileName: "debug.report.md"
109
+ },
110
+ debug_root_cause: {
111
+ jsonFileName: "debug.root-cause.json",
112
+ reportFileName: "debug.report.md"
113
+ },
114
+ debug_fix: {
115
+ jsonFileName: "debug.fix.json",
116
+ reportFileName: "debug.report.md"
117
+ },
118
+ debug_regression: {
119
+ jsonFileName: "debug.regression.json",
120
+ reportFileName: "debug.report.md"
121
+ },
122
+ architect: {
123
+ jsonFileName: "architect.verdict.json",
124
+ reportFileName: "architect.report.md"
125
+ },
126
+ draft: {
127
+ jsonFileName: "draft.proposal.json",
128
+ reportFileName: "draft.report.md"
21
129
  }
22
130
  };
23
131
  export function completionPhaseFromDispatch(dispatch) {
@@ -25,12 +133,25 @@ export function completionPhaseFromDispatch(dispatch) {
25
133
  }
26
134
  export function normalizeCompletionPhase(value) {
27
135
  const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
136
+ const debugPhase = normalizeDebugCompletionPhase(normalized);
137
+ if (debugPhase) {
138
+ return debugPhase;
139
+ }
28
140
  if (normalized === "self_review" || normalized === "selfreview" || normalized === "review") {
29
141
  return "self_review";
30
142
  }
31
143
  if (normalized === "validate" || normalized === "validation") {
32
144
  return "validation";
33
145
  }
146
+ if (normalized === "qa" || normalized === "quality_assurance" || normalized === "qualityassurance") {
147
+ return "qa";
148
+ }
149
+ if (normalized === "architect" || normalized === "architect_plan" || normalized === "planning" || normalized === "plan") {
150
+ return "architect";
151
+ }
152
+ if (normalized === "draft" || normalized === "drafting" || normalized === "draft_work_order") {
153
+ return "draft";
154
+ }
34
155
  return "implementation";
35
156
  }
36
157
  export function usesDevelopCycleCompletion(dispatch) {
@@ -42,36 +163,108 @@ export function usesDevelopCycleCompletion(dispatch) {
42
163
  && lane === "develop"
43
164
  && completionPhaseFromDispatch(dispatch) === "implementation";
44
165
  }
166
+ export function usesQaCycleCompletion(dispatch) {
167
+ const kind = dispatch.cycleRun.kind.trim().toLowerCase();
168
+ const role = dispatch.execution.role.trim().toLowerCase();
169
+ const lane = dispatch.execution.lane.trim().toLowerCase();
170
+ return kind === "qa"
171
+ && role === "qa"
172
+ && lane === "qa"
173
+ && completionPhaseFromDispatch(dispatch) === "qa";
174
+ }
175
+ export function usesDebugCycleCompletion(dispatch) {
176
+ const kind = dispatch.cycleRun.kind.trim().toLowerCase();
177
+ const role = dispatch.execution.role.trim().toLowerCase();
178
+ const lane = dispatch.execution.lane.trim().toLowerCase();
179
+ return kind === "debug"
180
+ && role === "debug"
181
+ && lane === "debug"
182
+ && isDebugCompletionPhase(completionPhaseFromDispatch(dispatch));
183
+ }
184
+ export function usesArchitectCycleCompletion(dispatch) {
185
+ const kind = dispatch.cycleRun.kind.trim().toLowerCase();
186
+ const role = dispatch.execution.role.trim().toLowerCase();
187
+ const lane = dispatch.execution.lane.trim().toLowerCase();
188
+ return kind === "architect" || role === "architect" || lane === "architect";
189
+ }
45
190
  export function completionToolNamesForPhase(phase) {
191
+ if (phase === "draft") {
192
+ return completionToolNamesForDraftGate("draft_proposal");
193
+ }
194
+ if (isDebugCompletionPhase(phase)) {
195
+ return completionToolNamesForDebugGate(phase);
196
+ }
46
197
  const base = phase === "implementation"
47
198
  ? "complete_implementation"
48
199
  : phase === "self_review"
49
200
  ? "complete_self_review"
50
- : "complete_validation";
201
+ : phase === "validation"
202
+ ? "complete_validation"
203
+ : phase === "architect"
204
+ ? "complete_architect_plan"
205
+ : "complete_qa";
206
+ return [`forge.${base}`, base];
207
+ }
208
+ export function completionToolNamesForQaGate(gate) {
209
+ const base = qaGateToolNames[gate];
210
+ return [`forge.${base}`, base];
211
+ }
212
+ export function completionToolNamesForDebugGate(gate) {
213
+ const base = debugGateToolNames[gate];
214
+ return [`forge.${base}`, base];
215
+ }
216
+ export function completionToolNamesForDraftGate(gate) {
217
+ const base = draftGateToolNames[gate];
51
218
  return [`forge.${base}`, base];
52
219
  }
53
220
  export function expectedCompletionToolName(phase) {
54
221
  return completionToolNamesForPhase(phase)[0];
55
222
  }
223
+ export function expectedQaCompletionToolName(gate) {
224
+ return completionToolNamesForQaGate(gate)[0];
225
+ }
226
+ export function expectedDebugCompletionToolName(gate) {
227
+ return completionToolNamesForDebugGate(gate)[0];
228
+ }
229
+ export function expectedDraftCompletionToolName(gate) {
230
+ return completionToolNamesForDraftGate(gate)[0];
231
+ }
56
232
  export function artifactRootFor(worktreePath, workItemId) {
57
233
  return path.join(worktreePath, ".forge", "work-items", safePathSegment(workItemId, "work item id"), "artifacts");
58
234
  }
59
- export function completionArtifactJsonPath(worktreePath, workItemId, phase) {
60
- return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].jsonFileName);
235
+ export function artifactRootForOwner(worktreePath, ownerType, ownerId) {
236
+ return path.join(worktreePath, ".forge", artifactOwnerDirectory(ownerType), safePathSegment(ownerId, "owner id"), "artifacts");
237
+ }
238
+ export function completionArtifactJsonPath(worktreePath, workItemId, phase, ownerType, ownerId) {
239
+ const artifactRoot = ownerType && ownerId
240
+ ? artifactRootForOwner(worktreePath, ownerType, ownerId)
241
+ : artifactRootFor(worktreePath, workItemId);
242
+ return path.join(artifactRoot, phaseFiles[phase].jsonFileName);
61
243
  }
62
- export function completionArtifactReportPath(worktreePath, workItemId, phase) {
63
- return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].reportFileName);
244
+ export function completionArtifactReportPath(worktreePath, workItemId, phase, ownerType, ownerId) {
245
+ const artifactRoot = ownerType && ownerId
246
+ ? artifactRootForOwner(worktreePath, ownerType, ownerId)
247
+ : artifactRootFor(worktreePath, workItemId);
248
+ return path.join(artifactRoot, phaseFiles[phase].reportFileName);
64
249
  }
65
250
  export async function prepareCompletionToolRuntime(options) {
66
251
  const phase = options.phase ?? completionPhaseFromDispatch(options.dispatch);
67
252
  const worktreePath = path.resolve(options.worktree.worktreePath);
68
253
  const workItemId = options.dispatch.workItem.id;
254
+ const ownerType = normalizedOwnerType(options.dispatch.cycleRun.ownerType) ?? "work_item";
255
+ const ownerId = options.dispatch.cycleRun.ownerId ?? workItemId;
69
256
  const mcpArgs = buildCompletionToolServerArgs({
70
257
  worktreePath,
71
258
  workItemId,
259
+ ownerType,
260
+ ownerId,
72
261
  phase,
73
262
  producedBy: `${options.dispatch.execution.provider}-cli`,
74
- developCycle: usesDevelopCycleCompletion(options.dispatch)
263
+ developCycle: usesDevelopCycleCompletion(options.dispatch),
264
+ qaCycle: usesQaCycleCompletion(options.dispatch),
265
+ debugCycle: usesDebugCycleCompletion(options.dispatch),
266
+ architectCycle: usesArchitectCycleCompletion(options.dispatch),
267
+ draftCycle: options.dispatch.execution.lane.trim().toLowerCase() === "draft" || options.dispatch.cycleRun.kind.trim().toLowerCase() === "draft"
75
268
  });
76
269
  const runtime = {
77
270
  serverName: toolServerName,
@@ -97,9 +290,25 @@ export function buildCompletionToolServerArgs(config) {
97
290
  "--produced-by",
98
291
  config.producedBy ?? "forge-completion-tool"
99
292
  ];
293
+ if (config.ownerType || config.ownerId) {
294
+ args.push("--owner-type", normalizedOwnerType(config.ownerType) ?? "work_item");
295
+ args.push("--owner-id", config.ownerId ?? config.workItemId);
296
+ }
100
297
  if (config.developCycle) {
101
298
  args.push("--develop-cycle");
102
299
  }
300
+ if (config.qaCycle) {
301
+ args.push("--qa-cycle");
302
+ }
303
+ if (config.debugCycle) {
304
+ args.push("--debug-cycle");
305
+ }
306
+ if (config.architectCycle) {
307
+ args.push("--architect-cycle");
308
+ }
309
+ if (config.draftCycle) {
310
+ args.push("--draft-cycle");
311
+ }
103
312
  return args;
104
313
  }
105
314
  export function codexMcpConfigArgs(runtime) {
@@ -126,6 +335,24 @@ export function completionPromptForPhase(phase) {
126
335
  const toolName = expectedCompletionToolName(phase);
127
336
  const alias = completionToolNamesForPhase(phase).find((name) => name !== toolName);
128
337
  const artifactName = phaseFiles[phase].jsonFileName;
338
+ if (phase === "qa") {
339
+ return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
340
+ Do not write QA artifacts by hand. When QA is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required structured QA payload.
341
+ That tool writes the durable QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`${artifactName}\`, and \`qa.report.md\`.
342
+ Use \`status: "pass"\` only when the validated changes satisfy acceptance criteria with concrete evidence. Use \`status: "needs_rework"\` with actionable in-scope findings, or \`status: "blocked"\` with a concrete blocker_reason.
343
+ Forge will mirror only the tool-written QA artifacts; reporting QA completion in prose is not enough.`;
344
+ }
345
+ if (phase === "architect") {
346
+ return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
347
+ Do not write Architect artifacts by hand. When the plan is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the full structured Architect planning payload.
348
+ That tool writes \`.forge/work-items/{workItemId}/artifacts/implementation.plan.json\`, \`qa.plan.json\`, \`${artifactName}\`, and \`architect.report.md\`.
349
+ The payload must put \`phases\`, \`tasks\`, \`dependencies\`, and \`phase_gates\` as top-level fields inside \`implementation_plan\`, for example:
350
+ \`{ "status": "pass", "summary": "...", "implementation_plan": { "schema_version": 1, "plan_id": "plan-...", "phases": [{ "id": "phase-1", "tasks": ["task-1"], "gate": "gate-1" }], "tasks": [{ "id": "task-1", "tests": [{ "command": "npm test" }] }], "dependencies": [], "phase_gates": [{ "id": "gate-1", "phase": "phase-1" }] }, "qa_plan": { "schema_version": 1, "final_qa": [{ "id": "qa-1", "coverage": "..." }] }, "report_markdown": "# Architect Report" }\`.
351
+ \`implementation_plan.tasks\` are Develop child tasks only: each task must require a focused repo/product implementation change. Put parent-story QA, sign-off, child-count/materialization inventory, parent plan artifact checks, and final integrated acceptance proof in \`qa_plan.final_qa\`, not as child Develop tasks.
352
+ Dependency entries use canonical \`before\` and \`after\` task ids, for example \`{ "before": "task-1", "after": "task-2" }\`. Forge accepts \`from\`/\`to\` only as aliases and normalizes them before writing artifacts.
353
+ Use \`status: "pass"\` for a valid pending-approval plan, \`needs_revision\` when story/design input must change, or \`blocked\` with a concrete blocker.
354
+ Forge will mirror only the tool-written Architect artifacts; reporting the plan in prose is not enough.`;
355
+ }
129
356
  return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
130
357
  Do not write phase artifacts by hand. When the phase is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required evidence payload.
131
358
  That tool writes \`.forge/work-items/{workItemId}/artifacts/${artifactName}\` and returns the artifact reference that Forge will mirror through the existing phase-artifact pipeline.
@@ -141,31 +368,95 @@ Complete the dev cycle in order inside this same provider session:
141
368
  Each tool writes the canonical artifact under \`.forge/work-items/{workItemId}/artifacts/\` and returns the next-phase instruction Forge expects you to follow.
142
369
  If the current phase cannot pass, call the current phase tool with a non-pass status and explicit blockers instead of reporting completion in prose only.`;
143
370
  }
371
+ export function completionPromptForQaCycle(currentGate = "qa_plan") {
372
+ return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
373
+ Do not write QA artifacts by hand. The tool server enforces QA gate order and starts this run at \`${currentGate}\`.
374
+ Complete the QA cycle in order inside this same provider session:
375
+ 1. Call \`forge.complete_qa_plan(...)\` after the QA test plan/checklist is ready.
376
+ 2. Follow the returned regression instruction, then call \`forge.complete_qa_regression(...)\`.
377
+ 3. Follow the returned API/backend instruction, then call \`forge.complete_qa_api(...)\`.
378
+ 4. Follow the returned manual web instruction, then call \`forge.complete_qa_manual_web(...)\`.
379
+ 5. Follow the returned bug reproduction instruction, then call \`forge.complete_qa_bug_repro(...)\`.
380
+ 6. Follow the returned findings instruction, then call \`forge.complete_qa_findings(...)\`.
381
+ 7. Follow the returned verdict instruction, then call \`forge.complete_qa_verdict(...)\`.
382
+ Use \`status: "skipped"\` with a reason for gates that are not applicable. If a gate is blocked, keep moving through later gates as skipped due to the blocker and finish with a blocked verdict.
383
+ The final verdict tool writes the canonical QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`qa.verdict.json\`, and \`qa.report.md\`.
384
+ The legacy \`forge.complete_qa\` one-shot tool is not available in normal QA-cycle mode. Reporting QA completion in prose is not enough.`;
385
+ }
386
+ export function completionPromptForDraftCycle(currentGate = "draft_intent") {
387
+ return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
388
+ Do not finish Draft by prose or raw JSON. The tool server enforces Draft gate order and starts at \`${currentGate}\`.
389
+ Complete the Draft cycle in order inside this same provider session:
390
+ 1. Call \`forge.complete_draft_intent(...)\` after interpreting user intent and non-goals.
391
+ 2. Follow the returned repo-context instruction, inspect selected project/repo assumptions, then call \`forge.complete_draft_repo_context(...)\`.
392
+ 3. Follow the returned graph-context instruction, account for DAG/dependency placement, then call \`forge.complete_draft_graph_context(...)\`.
393
+ 4. Follow the returned product-scope instruction, choose product scope for the selected project, then call \`forge.complete_draft_product_scope(...)\`.
394
+ 5. Follow the returned work-order-plan instruction, draft Work Order fields and candidate feature boundaries, then call \`forge.complete_draft_work_order_plan(...)\`.
395
+ 6. Follow the returned critic instruction, critique literalism, wrong-project scope, and decomposition quality, then call \`forge.complete_draft_critic(...)\`.
396
+ 7. Follow the returned proposal instruction, then call \`forge.complete_draft_proposal(...)\` with the final Work Order JSON in \`draft_json\`.
397
+ The final proposal tool writes \`draft.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. Reporting Draft completion in prose is not enough.`;
398
+ }
399
+ export function completionPromptForDebugCycle(currentGate = "debug_repro") {
400
+ return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
401
+ Do not write Debug artifacts by hand. The tool server enforces Debug gate order and starts this run at \`${currentGate}\`.
402
+ Complete the Debug cycle in order inside this same provider session:
403
+ 1. Reproduce or tightly characterize the bug, then call \`forge.complete_debug_repro(...)\`.
404
+ 2. Follow the returned root-cause instruction, isolate evidence, then call \`forge.complete_debug_root_cause(...)\`.
405
+ 3. Follow the returned fix instruction, apply the smallest safe fix with regression coverage when practical, then call \`forge.complete_debug_fix(...)\`.
406
+ 4. Follow the returned regression instruction, prove the original repro is negative and the fix is QA-ready, then call \`forge.complete_debug_regression(...)\`.
407
+ Each tool writes a canonical Debug artifact under \`.forge/work-items/{workItemId}/artifacts/\`: \`debug.repro.json\`, \`debug.root-cause.json\`, \`debug.fix.json\`, and \`debug.regression.json\` plus \`debug.report.md\` when report text is provided or generated.
408
+ Use a non-pass status with explicit blockers when the current Debug gate cannot pass. Reporting Debug completion in prose is not enough; the relevant MCP completion tool is the transition request.`;
409
+ }
144
410
  export function completionToolNamesForServer(config) {
145
- return config.developCycle
146
- ? completionPhaseOrder.flatMap((phase) => completionToolNamesForPhase(phase))
147
- : completionToolNamesForPhase(config.phase);
411
+ return config.draftCycle
412
+ ? draftCompletionGateOrder.flatMap((gate) => completionToolNamesForDraftGate(gate))
413
+ : config.debugCycle
414
+ ? debugCompletionPhaseOrder.flatMap((gate) => completionToolNamesForDebugGate(gate))
415
+ : config.qaCycle
416
+ ? qaCompletionGateOrder.flatMap((gate) => completionToolNamesForQaGate(gate))
417
+ : config.developCycle
418
+ ? completionPhaseOrder.flatMap((phase) => completionToolNamesForPhase(phase))
419
+ : config.architectCycle
420
+ ? completionToolNamesForPhase("architect")
421
+ : completionToolNamesForPhase(config.phase);
148
422
  }
149
423
  export class CompletionToolServerSession {
150
424
  config;
151
425
  currentPhase;
426
+ currentQaGate = "qa_plan";
427
+ currentDraftGate = "draft_intent";
152
428
  completed = false;
153
429
  constructor(config) {
154
430
  this.config = config;
155
431
  this.currentPhase = config.phase;
156
432
  }
157
433
  get instructions() {
158
- return this.config.developCycle
159
- ? completionPromptForDevelopCycle(this.currentPhase)
160
- : completionPromptForPhase(this.currentPhase);
434
+ return this.config.draftCycle
435
+ ? completionPromptForDraftCycle(this.currentDraftGate)
436
+ : this.config.debugCycle
437
+ ? completionPromptForDebugCycle(asDebugCompletionPhase(this.currentPhase))
438
+ : this.config.qaCycle
439
+ ? completionPromptForQaCycle(this.currentQaGate)
440
+ : this.config.developCycle
441
+ ? completionPromptForDevelopCycle(this.currentPhase)
442
+ : completionPromptForPhase(this.currentPhase);
161
443
  }
162
444
  toolDefinitions() {
163
- return completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name)));
445
+ return completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name), qaGateFromToolName(name)));
164
446
  }
165
447
  async callTool(toolName, input) {
166
448
  const requestedPhase = phaseFromToolName(toolName);
167
449
  if (this.completed) {
168
- throw new Error("Forge develop cycle is already complete; no more phase completion calls are accepted.");
450
+ throw new Error("Forge completion cycle is already complete; no more completion calls are accepted.");
451
+ }
452
+ if (this.config.draftCycle) {
453
+ return await this.callDraftGateTool(toolName, requestedPhase, input);
454
+ }
455
+ if (this.config.debugCycle) {
456
+ return await this.callDebugGateTool(toolName, requestedPhase, input);
457
+ }
458
+ if (this.config.qaCycle) {
459
+ return await this.callQaGateTool(toolName, requestedPhase, input);
169
460
  }
170
461
  if (requestedPhase !== this.currentPhase) {
171
462
  throw new Error(`Tool ${toolName} is out of order. Current Forge phase is ${this.currentPhase}.`);
@@ -201,7 +492,115 @@ export class CompletionToolServerSession {
201
492
  }
202
493
  };
203
494
  }
495
+ async callDraftGateTool(toolName, requestedPhase, input) {
496
+ const requestedGate = draftGateFromToolName(toolName);
497
+ if (requestedPhase !== "draft" || !requestedGate) {
498
+ throw new Error(`Tool ${toolName} is not available in Draft-cycle mode. Current Forge Draft gate is ${this.currentDraftGate}.`);
499
+ }
500
+ if (requestedGate !== this.currentDraftGate) {
501
+ throw new Error(`Tool ${toolName} is out of order. Current Forge Draft gate is ${this.currentDraftGate}.`);
502
+ }
503
+ const completedGate = this.currentDraftGate;
504
+ const reference = await writeDraftGateCompletionArtifact(this.config, completedGate, toolName, input);
505
+ const status = reference.status.trim().toLowerCase();
506
+ const nextGate = this.advanceAfterDraftGate(completedGate);
507
+ const nextPhase = nextGate ? "draft" : "sign_off_ready";
508
+ const nextInstruction = completionToolNextInstructionForDraftGate(completedGate, status, nextGate);
509
+ return {
510
+ content: [{ type: "text", text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}` }],
511
+ structuredContent: {
512
+ ...reference,
513
+ gate: { phase: "draft", draftGate: completedGate, status, allowed: status !== "blocked", reason: nextGate ? `${completedGate} artifact accepted; continue to ${nextGate}.` : `Draft proposal artifact accepted with status ${status}.` },
514
+ nextPhase,
515
+ nextInstruction
516
+ }
517
+ };
518
+ }
519
+ async callDebugGateTool(toolName, requestedPhase, input) {
520
+ const currentDebugGate = asDebugCompletionPhase(this.currentPhase);
521
+ if (!isDebugCompletionPhase(requestedPhase)) {
522
+ throw new Error(`Tool ${toolName} is not available in Debug-cycle mode. Current Forge Debug gate is ${currentDebugGate}.`);
523
+ }
524
+ if (requestedPhase !== currentDebugGate) {
525
+ throw new Error(`Tool ${toolName} is out of order. Current Forge Debug gate is ${currentDebugGate}.`);
526
+ }
527
+ const completedGate = currentDebugGate;
528
+ const reference = await writeCompletionArtifact({ ...this.config, phase: completedGate }, toolName, input);
529
+ const status = reference.status.trim().toLowerCase();
530
+ const pass = status === "pass";
531
+ const nextGate = pass ? this.advanceAfterDebugGate(completedGate) : completedGate;
532
+ const nextPhase = nextGate ?? "qa_ready";
533
+ const nextInstruction = completionToolNextInstructionForDebugGate(completedGate, status, nextGate);
534
+ const reason = pass
535
+ ? `${completedGate} artifact accepted${nextGate ? `; continue to ${nextGate}.` : "; Debug regression is QA-ready."}`
536
+ : `${completedGate} artifact recorded with status ${status}; rework is required before Debug progression.`;
537
+ return {
538
+ content: [
539
+ {
540
+ type: "text",
541
+ text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}`
542
+ }
543
+ ],
544
+ structuredContent: {
545
+ ...reference,
546
+ gate: {
547
+ phase: completedGate,
548
+ status,
549
+ allowed: pass,
550
+ reason
551
+ },
552
+ nextPhase,
553
+ nextInstruction
554
+ }
555
+ };
556
+ }
557
+ async callQaGateTool(toolName, requestedPhase, input) {
558
+ const requestedGate = qaGateFromToolName(toolName);
559
+ if (requestedPhase !== "qa" || !requestedGate) {
560
+ throw new Error(`Tool ${toolName} is not available in QA-cycle mode. Current Forge QA gate is ${this.currentQaGate}.`);
561
+ }
562
+ if (requestedGate !== this.currentQaGate) {
563
+ throw new Error(`Tool ${toolName} is out of order. Current Forge QA gate is ${this.currentQaGate}.`);
564
+ }
565
+ const completedGate = this.currentQaGate;
566
+ const reference = await writeCompletionArtifact({ ...this.config, phase: "qa" }, toolName, input);
567
+ const status = reference.status.trim().toLowerCase();
568
+ const nextGate = this.advanceAfterQaGate(completedGate);
569
+ const nextPhase = nextGate ? "qa" : "sign_off_ready";
570
+ const nextInstruction = completionToolNextInstructionForQaGate(completedGate, status, nextGate);
571
+ const allowed = status !== "blocked";
572
+ const reason = nextGate
573
+ ? `${completedGate} artifact accepted; continue to ${nextGate}.`
574
+ : `QA verdict artifact accepted with status ${status}.`;
575
+ return {
576
+ content: [
577
+ {
578
+ type: "text",
579
+ text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}`
580
+ }
581
+ ],
582
+ structuredContent: {
583
+ ...reference,
584
+ gate: {
585
+ phase: "qa",
586
+ qaGate: completedGate,
587
+ status,
588
+ allowed,
589
+ reason
590
+ },
591
+ nextPhase,
592
+ nextInstruction
593
+ }
594
+ };
595
+ }
204
596
  advanceAfterPass(phase) {
597
+ if (phase === "qa") {
598
+ this.completed = true;
599
+ return "sign_off_ready";
600
+ }
601
+ if (isDebugCompletionPhase(phase)) {
602
+ return nextDebugPhaseAfter(phase) ?? "qa_ready";
603
+ }
205
604
  const next = nextPhaseAfter(phase);
206
605
  if (!this.config.developCycle) {
207
606
  return next ?? "dev_test_ready";
@@ -213,15 +612,89 @@ export class CompletionToolServerSession {
213
612
  this.completed = true;
214
613
  return "dev_test_ready";
215
614
  }
615
+ advanceAfterDraftGate(gate) {
616
+ const index = draftCompletionGateOrder.indexOf(gate);
617
+ const next = index >= 0 ? draftCompletionGateOrder[index + 1] ?? null : null;
618
+ if (next) {
619
+ this.currentDraftGate = next;
620
+ return next;
621
+ }
622
+ this.completed = true;
623
+ return null;
624
+ }
625
+ advanceAfterQaGate(gate) {
626
+ const index = qaCompletionGateOrder.indexOf(gate);
627
+ const next = index >= 0 ? qaCompletionGateOrder[index + 1] ?? null : null;
628
+ if (next) {
629
+ this.currentQaGate = next;
630
+ return next;
631
+ }
632
+ this.completed = true;
633
+ return null;
634
+ }
635
+ advanceAfterDebugGate(gate) {
636
+ const index = debugCompletionPhaseOrder.indexOf(gate);
637
+ const next = index >= 0 ? debugCompletionPhaseOrder[index + 1] ?? null : null;
638
+ if (next) {
639
+ this.currentPhase = next;
640
+ return next;
641
+ }
642
+ this.completed = true;
643
+ return null;
644
+ }
645
+ }
646
+ async function writeDraftGateCompletionArtifact(config, gate, toolName, input) {
647
+ const payload = asRecord(input, "Draft completion payload");
648
+ const status = normalizeDraftStatus(optionalString(payload, "status") ?? "pass");
649
+ if (gate === "draft_proposal") {
650
+ const draftJson = asRecord(payload["draft_json"], "draft_json");
651
+ for (const key of ["title", "summary", "objective", "planningPacket", "decompositionContext"]) {
652
+ if (typeof draftJson[key] !== "string" || draftJson[key].trim().length === 0) {
653
+ throw new Error(`draft_json.${key}: expected non-empty string`);
654
+ }
655
+ }
656
+ }
657
+ const redactedPayload = redactSecrets({ ...payload, status, phase: "draft", gate, tool_name: toolName }, config.redactionSecrets ?? []);
658
+ const root = artifactRootFor(config.worktreePath, config.workItemId);
659
+ await fs.mkdir(root, { recursive: true });
660
+ const artifactPath = path.join(root, draftGateFileNames[gate]);
661
+ const reportPath = gate === "draft_proposal" ? path.join(root, phaseFiles.draft.reportFileName) : path.join(root, `${gate}.md`);
662
+ const verdictJson = jsonText(redactedPayload);
663
+ const report = optionalString(redactedPayload, "report_markdown") ?? `# ${gate.replace(/_/g, " ")}\n\n${optionalString(redactedPayload, "summary") ?? "Draft gate recorded."}\n`;
664
+ await writeFileAtomic(artifactPath, verdictJson);
665
+ await writeFileAtomic(reportPath, report);
666
+ return {
667
+ phase: "draft",
668
+ workItemId: config.workItemId,
669
+ ownerType: config.ownerType,
670
+ ownerId: config.ownerId,
671
+ repoPath: path.resolve(config.worktreePath),
672
+ path: artifactPath,
673
+ reportPath,
674
+ contentHash: sha256(verdictJson),
675
+ status,
676
+ producedBy: config.producedBy ?? "forge-completion-tool"
677
+ };
678
+ }
679
+ function normalizeDraftStatus(value) {
680
+ const normalized = value.trim().toLowerCase();
681
+ return normalized === "blocked" || normalized === "needs_revision" || normalized === "needs_rework" ? normalized : "pass";
216
682
  }
217
683
  export async function writeCompletionArtifact(config, toolName, input) {
218
684
  const phase = phaseFromToolName(toolName);
219
685
  if (phase !== config.phase) {
220
686
  throw new Error(`Tool ${toolName} is not allowed for phase ${config.phase}.`);
221
687
  }
688
+ const qaGate = qaGateFromToolName(toolName);
689
+ if (qaGate && qaGate !== "qa_verdict") {
690
+ return await writeQaGateCompletionArtifact(config, qaGate, input);
691
+ }
222
692
  const payload = asRecord(input, "completion payload");
223
- const status = normalizeCompletionStatus(requiredString(payload, "status"));
224
- const validationPayload = { ...payload, status };
693
+ const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
694
+ let validationPayload = { ...payload, status };
695
+ if (config.qaCycle && qaGate === "qa_verdict") {
696
+ validationPayload = await synthesizeQaCycleVerdictPayload(config, validationPayload, status);
697
+ }
225
698
  validatePayloadShape(phase, validationPayload);
226
699
  validateOptionalWorkItemId(validationPayload, config.workItemId);
227
700
  const redactedPayload = redactSecrets(validationPayload, config.redactionSecrets ?? []);
@@ -229,9 +702,17 @@ export async function writeCompletionArtifact(config, toolName, input) {
229
702
  ?? optionalString(redactedPayload, "producedBy")
230
703
  ?? config.producedBy
231
704
  ?? "forge-completion-tool";
705
+ if (phase === "qa") {
706
+ return await writeQaCompletionArtifact(config, redactedPayload, status, producedBy);
707
+ }
708
+ if (phase === "architect") {
709
+ return await writeArchitectCompletionArtifact(config, redactedPayload, status, producedBy);
710
+ }
232
711
  const artifactWithoutHash = normalizeArtifactPayload(redactedPayload, {
233
712
  phase,
234
713
  workItemId: config.workItemId,
714
+ ownerType: config.ownerType,
715
+ ownerId: config.ownerId,
235
716
  producedBy,
236
717
  status
237
718
  });
@@ -250,6 +731,93 @@ export async function writeCompletionArtifact(config, toolName, input) {
250
731
  return {
251
732
  phase,
252
733
  workItemId: config.workItemId,
734
+ ...artifactReferenceOwnerFields(config),
735
+ repoPath: path.resolve(config.worktreePath),
736
+ path: artifactPath,
737
+ reportPath,
738
+ contentHash,
739
+ status,
740
+ producedBy
741
+ };
742
+ }
743
+ async function writeArchitectCompletionArtifact(config, payload, status, producedBy) {
744
+ const ownerFields = artifactOwnerFields(config);
745
+ const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
746
+ ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
747
+ : artifactRootFor(config.worktreePath, config.workItemId);
748
+ const implementationPlanPath = path.join(artifactRoot, "implementation.plan.json");
749
+ const qaPlanPath = path.join(artifactRoot, "qa.plan.json");
750
+ const verdictPath = path.join(artifactRoot, "architect.verdict.json");
751
+ const reportPath = path.join(artifactRoot, "architect.report.md");
752
+ const implementationPlan = requiredRecord(payload, "implementation_plan");
753
+ const qaPlan = requiredRecord(payload, "qa_plan");
754
+ const report = optionalString(payload, "report") ?? optionalString(payload, "report_markdown") ?? reportMarkdown(payload, "architect", status, producedBy, "pending");
755
+ const artifactWithoutHash = normalizeArtifactPayload(payload, {
756
+ phase: "architect",
757
+ workItemId: config.workItemId,
758
+ ownerType: config.ownerType,
759
+ ownerId: config.ownerId,
760
+ producedBy,
761
+ status
762
+ });
763
+ const contentHash = sha256(stableStringify(artifactWithoutHash));
764
+ const verdict = {
765
+ ...artifactWithoutHash,
766
+ content_hash: contentHash
767
+ };
768
+ await fs.mkdir(artifactRoot, { recursive: true });
769
+ await writeFileAtomic(implementationPlanPath, jsonText(implementationPlan));
770
+ await writeFileAtomic(qaPlanPath, jsonText(qaPlan));
771
+ await writeFileAtomic(verdictPath, jsonText(verdict));
772
+ await writeFileAtomic(reportPath, `${report.trim()}\n`);
773
+ return {
774
+ phase: "architect",
775
+ workItemId: config.workItemId,
776
+ ...artifactReferenceOwnerFields(config),
777
+ repoPath: path.resolve(config.worktreePath),
778
+ path: verdictPath,
779
+ reportPath,
780
+ contentHash,
781
+ status,
782
+ producedBy
783
+ };
784
+ }
785
+ async function writeQaGateCompletionArtifact(config, gate, input) {
786
+ const payload = asRecord(input, "QA gate completion payload");
787
+ const status = normalizeQaGateStatus(requiredString(payload, "status"));
788
+ validateQaGatePayloadShape(gate, payload, status);
789
+ validateOptionalWorkItemId(payload, config.workItemId);
790
+ const redactedPayload = redactSecrets({ ...payload, status }, config.redactionSecrets ?? []);
791
+ const producedBy = optionalString(redactedPayload, "produced_by")
792
+ ?? optionalString(redactedPayload, "producedBy")
793
+ ?? config.producedBy
794
+ ?? "forge-completion-tool";
795
+ const ownerFields = artifactOwnerFields(config);
796
+ const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
797
+ ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
798
+ : artifactRootFor(config.worktreePath, config.workItemId);
799
+ const fileName = qaGateFileNames[gate];
800
+ const artifactPath = path.join(artifactRoot, fileName);
801
+ const reportPath = path.join(artifactRoot, "qa.report.md");
802
+ const artifactWithoutHash = normalizeQaGateArtifactPayload(redactedPayload, {
803
+ gate,
804
+ workItemId: config.workItemId,
805
+ ownerType: config.ownerType,
806
+ ownerId: config.ownerId,
807
+ producedBy,
808
+ status
809
+ });
810
+ const contentHash = sha256(stableStringify(artifactWithoutHash));
811
+ const artifact = {
812
+ ...artifactWithoutHash,
813
+ content_hash: contentHash
814
+ };
815
+ await fs.mkdir(artifactRoot, { recursive: true });
816
+ await writeFileAtomic(artifactPath, jsonText(artifact));
817
+ return {
818
+ phase: "qa",
819
+ workItemId: config.workItemId,
820
+ ...artifactReferenceOwnerFields(config),
253
821
  repoPath: path.resolve(config.worktreePath),
254
822
  path: artifactPath,
255
823
  reportPath,
@@ -258,19 +826,319 @@ export async function writeCompletionArtifact(config, toolName, input) {
258
826
  producedBy
259
827
  };
260
828
  }
261
- export async function readCompletionArtifact(worktreePath, workItemId, phase) {
262
- const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase);
263
- const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase);
829
+ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
830
+ const ownerFields = artifactOwnerFields(config);
831
+ const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
832
+ ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
833
+ : artifactRootFor(config.worktreePath, config.workItemId);
834
+ const planPath = path.join(artifactRoot, "qa.plan.json");
835
+ const evidencePath = path.join(artifactRoot, "qa.evidence.json");
836
+ const findingsPath = path.join(artifactRoot, "qa.findings.json");
837
+ const verdictPath = path.join(artifactRoot, "qa.verdict.json");
838
+ const reportPath = path.join(artifactRoot, "qa.report.md");
839
+ const relativeEvidencePath = ownerFields.owner_type && ownerFields.owner_id
840
+ ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.evidence.json")
841
+ : qaArtifactRelativePath(config.workItemId, "qa.evidence.json");
842
+ const relativeFindingsPath = ownerFields.owner_type && ownerFields.owner_id
843
+ ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.findings.json")
844
+ : qaArtifactRelativePath(config.workItemId, "qa.findings.json");
845
+ const relativeReportPath = ownerFields.owner_type && ownerFields.owner_id
846
+ ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.report.md")
847
+ : qaArtifactRelativePath(config.workItemId, "qa.report.md");
848
+ const evidenceSource = qaEvidenceSource(payload);
849
+ const commands = qaArray(payload, "commands", evidenceSource);
850
+ const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
851
+ const sidecars = await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(payload, "sidecars", evidenceSource), ownerFields.owner_type, ownerFields.owner_id);
852
+ const notes = optionalString(payload, "notes") ?? optionalString(evidenceSource, "notes") ?? "";
853
+ const findings = qaObjectArray(payload, "findings");
854
+ const candidateBugs = qaObjectArray(payload, "candidate_bugs");
855
+ const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
856
+ const explicitFindingIds = qaStringArray(payload, "finding_ids");
857
+ const explicitCandidateBugIds = qaStringArray(payload, "candidate_bug_ids");
858
+ const blockerReason = optionalString(payload, "blocker_reason");
859
+ const checklist = qaStringArray(payload, "checklist");
860
+ const planJson = jsonText({
861
+ schema_version: 1,
862
+ phase: "qa",
863
+ ...ownerFields,
864
+ checklist: checklist.length > 0 ? checklist : defaultQaChecklist(status),
865
+ acceptance_criteria: testedAcceptanceCriteria
866
+ });
867
+ const evidenceJson = jsonText({
868
+ schema_version: 1,
869
+ phase: "qa",
870
+ ...ownerFields,
871
+ commands,
872
+ browser_checks: browserChecks,
873
+ sidecars,
874
+ notes
875
+ });
876
+ const findingsJson = jsonText({
877
+ schema_version: 1,
878
+ phase: "qa",
879
+ ...ownerFields,
880
+ findings,
881
+ candidate_bugs: candidateBugs
882
+ });
883
+ const findingIds = status === "pass"
884
+ ? []
885
+ : explicitFindingIds.length > 0
886
+ ? explicitFindingIds
887
+ : findings
888
+ .filter((finding) => normalizedString(finding.scope) === "in_scope")
889
+ .map((finding) => optionalString(finding, "id"))
890
+ .filter((id) => Boolean(id));
891
+ const candidateBugIds = explicitCandidateBugIds.length > 0
892
+ ? explicitCandidateBugIds
893
+ : candidateBugs
894
+ .map((candidateBug) => optionalString(candidateBug, "id"))
895
+ .filter((id) => Boolean(id));
896
+ const verdictWithoutHash = {
897
+ schema_version: numberOrDefault(payload.schema_version, 1),
898
+ phase: "qa",
899
+ ...ownerFields,
900
+ status,
901
+ summary: requiredString(payload, "summary"),
902
+ tested_acceptance_criteria: testedAcceptanceCriteria,
903
+ finding_ids: findingIds,
904
+ candidate_bug_ids: candidateBugIds,
905
+ blocker_reason: status === "blocked" ? normalizedString(blockerReason) : null,
906
+ evidence_path: relativeEvidencePath,
907
+ findings_path: relativeFindingsPath,
908
+ report_path: relativeReportPath,
909
+ produced_by: producedBy
910
+ };
911
+ const contentHash = sha256(stableStringify({
912
+ plan: JSON.parse(planJson),
913
+ evidence: JSON.parse(evidenceJson),
914
+ findings: JSON.parse(findingsJson),
915
+ verdict: verdictWithoutHash
916
+ }));
917
+ const verdictJson = jsonText({
918
+ ...verdictWithoutHash,
919
+ content_hash: contentHash
920
+ });
921
+ const finalReport = reportMarkdown(payload, "qa", status, producedBy, contentHash);
922
+ await fs.mkdir(artifactRoot, { recursive: true });
923
+ await writeFileAtomic(planPath, planJson);
924
+ await writeFileAtomic(evidencePath, evidenceJson);
925
+ await writeFileAtomic(findingsPath, findingsJson);
926
+ await writeFileAtomic(verdictPath, verdictJson);
927
+ await writeFileAtomic(reportPath, finalReport);
928
+ return {
929
+ phase: "qa",
930
+ workItemId: config.workItemId,
931
+ ...artifactReferenceOwnerFields(config),
932
+ repoPath: path.resolve(config.worktreePath),
933
+ path: verdictPath,
934
+ reportPath,
935
+ contentHash,
936
+ status,
937
+ producedBy
938
+ };
939
+ }
940
+ async function synthesizeQaCycleVerdictPayload(config, payload, status) {
941
+ const qaPlan = await readQaGateArtifact(config, "qa_plan");
942
+ const qaRegression = await readQaGateArtifact(config, "qa_regression");
943
+ const qaApi = await readQaGateArtifact(config, "qa_api");
944
+ const qaManualWeb = await readQaGateArtifact(config, "qa_manual_web");
945
+ const qaBugRepro = await readQaGateArtifact(config, "qa_bug_repro");
946
+ const qaFindings = await readQaGateArtifact(config, "qa_findings");
947
+ const evidenceGates = [qaRegression, qaApi, qaManualWeb, qaBugRepro];
948
+ const payloadEvidence = qaEvidenceSource(payload);
949
+ const merged = { ...payload };
950
+ const checklist = qaStringArray(payload, "checklist");
951
+ if (checklist.length === 0) {
952
+ const plannedChecklist = qaStringArray(qaPlan, "checklist");
953
+ merged.checklist = plannedChecklist.length > 0 ? plannedChecklist : defaultQaChecklist(status);
954
+ }
955
+ const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
956
+ if (testedAcceptanceCriteria.length === 0) {
957
+ const plannedAcceptanceCriteria = qaStringArray(qaPlan, "acceptance_criteria");
958
+ const payloadAcceptanceCriteria = qaStringArray(payload, "acceptance_criteria");
959
+ const acceptanceCriteria = plannedAcceptanceCriteria.length > 0 ? plannedAcceptanceCriteria : payloadAcceptanceCriteria;
960
+ if (acceptanceCriteria.length > 0) {
961
+ merged.tested_acceptance_criteria = acceptanceCriteria;
962
+ }
963
+ }
964
+ const payloadCommands = qaArray(payload, "commands", payloadEvidence);
965
+ const inheritedCommands = evidenceGates.flatMap((gate) => qaArray(gate, "commands"));
966
+ const inheritedDiagnosticCommandNotes = status === "pass"
967
+ ? qaNonPassingCommandNotes(inheritedCommands)
968
+ : [];
969
+ merged.commands = dedupeUnknownArray([
970
+ ...payloadCommands,
971
+ ...(status === "pass" ? inheritedCommands.filter(isQaPassingCommandEvidence) : inheritedCommands)
972
+ ]);
973
+ merged.browser_checks = dedupeUnknownArray([
974
+ ...qaArray(payload, "browser_checks", payloadEvidence),
975
+ ...evidenceGates.flatMap((gate) => qaArray(gate, "browser_checks"))
976
+ ]);
977
+ merged.sidecars = dedupeUnknownArray([
978
+ ...qaArray(payload, "sidecars", payloadEvidence),
979
+ ...evidenceGates.flatMap((gate) => qaArray(gate, "sidecars"))
980
+ ]);
981
+ const notes = dedupeStrings([
982
+ optionalString(payload, "notes"),
983
+ optionalString(payloadEvidence, "notes"),
984
+ ...evidenceGates.map((gate) => optionalString(gate, "notes")),
985
+ ...inheritedDiagnosticCommandNotes
986
+ ]);
987
+ if (notes.length > 0) {
988
+ merged.notes = notes.join("\n");
989
+ }
990
+ merged.findings = mergeQaObjectArraysById(qaObjectArray(payload, "findings"), qaObjectArray(qaFindings, "findings"));
991
+ merged.candidate_bugs = mergeQaObjectArraysById(qaObjectArray(payload, "candidate_bugs"), qaObjectArray(qaFindings, "candidate_bugs"));
992
+ return merged;
993
+ }
994
+ async function readQaGateArtifact(config, gate) {
995
+ const ownerFields = artifactOwnerFields(config);
996
+ const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
997
+ ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
998
+ : artifactRootFor(config.worktreePath, config.workItemId);
999
+ const artifactPath = path.join(artifactRoot, qaGateFileNames[gate]);
1000
+ const content = await readOptionalFile(artifactPath);
1001
+ return content === null ? {} : parseOptionalJsonObject(content, qaGateFileNames[gate]);
1002
+ }
1003
+ function dedupeUnknownArray(values) {
1004
+ const seen = new Set();
1005
+ const deduped = [];
1006
+ for (const value of values) {
1007
+ const key = stableStringify(value);
1008
+ if (seen.has(key)) {
1009
+ continue;
1010
+ }
1011
+ seen.add(key);
1012
+ deduped.push(value);
1013
+ }
1014
+ return deduped;
1015
+ }
1016
+ function isQaPassingCommandEvidence(value) {
1017
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
1018
+ return false;
1019
+ }
1020
+ const record = value;
1021
+ return record.exit_code === 0 && normalizedString(record.status) === "pass";
1022
+ }
1023
+ function qaNonPassingCommandNotes(values) {
1024
+ return values
1025
+ .filter((value) => !isQaPassingCommandEvidence(value))
1026
+ .map((value, index) => {
1027
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
1028
+ return `QA diagnostic command ${index + 1} was omitted from pass evidence because it was not a structured passing command.`;
1029
+ }
1030
+ const record = value;
1031
+ const command = optionalString(record, "command") ?? "<missing command>";
1032
+ const status = optionalString(record, "status") ?? "<missing status>";
1033
+ const exitCode = typeof record.exit_code === "number" && Number.isFinite(record.exit_code)
1034
+ ? String(record.exit_code)
1035
+ : "<missing exit_code>";
1036
+ const summary = optionalString(record, "summary");
1037
+ return `QA diagnostic command omitted from pass evidence: ${command} (status ${status}, exit_code ${exitCode})${summary ? ` — ${summary}` : ""}.`;
1038
+ });
1039
+ }
1040
+ function mergeQaObjectArraysById(primary, fallback) {
1041
+ const seen = new Set();
1042
+ const merged = [];
1043
+ for (const value of [...primary, ...fallback]) {
1044
+ const id = optionalString(value, "id");
1045
+ const key = id ? `id:${id}` : stableStringify(value);
1046
+ if (seen.has(key)) {
1047
+ continue;
1048
+ }
1049
+ seen.add(key);
1050
+ merged.push(value);
1051
+ }
1052
+ return merged;
1053
+ }
1054
+ function dedupeStrings(values) {
1055
+ const seen = new Set();
1056
+ const deduped = [];
1057
+ for (const value of values) {
1058
+ const trimmed = value?.trim();
1059
+ if (!trimmed || seen.has(trimmed)) {
1060
+ continue;
1061
+ }
1062
+ seen.add(trimmed);
1063
+ deduped.push(trimmed);
1064
+ }
1065
+ return deduped;
1066
+ }
1067
+ async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, ownerType, ownerId) {
1068
+ if (sidecars.length === 0) {
1069
+ return [];
1070
+ }
1071
+ const artifactRoot = ownerType && ownerId
1072
+ ? artifactRootForOwner(worktreePath, ownerType, ownerId)
1073
+ : artifactRootFor(worktreePath, workItemId);
1074
+ const qaSidecarRoot = path.resolve(artifactRoot, "qa");
1075
+ const validated = [];
1076
+ for (const [index, sidecar] of sidecars.entries()) {
1077
+ if (!sidecar || typeof sidecar !== "object" || Array.isArray(sidecar)) {
1078
+ throw new Error(`sidecars[${index}] must be an object.`);
1079
+ }
1080
+ const record = sidecar;
1081
+ const sidecarPath = optionalString(record, "path");
1082
+ const contentHash = optionalString(record, "content_hash");
1083
+ const bytes = record.bytes;
1084
+ if (!sidecarPath || !contentHash || typeof bytes !== "number" || !Number.isFinite(bytes) || bytes <= 0) {
1085
+ throw new Error(`sidecars[${index}] must include path, content_hash, and positive bytes.`);
1086
+ }
1087
+ if (path.isAbsolute(sidecarPath)) {
1088
+ throw new Error(`sidecars[${index}].path must be relative to the worktree.`);
1089
+ }
1090
+ const fullPath = path.resolve(worktreePath, sidecarPath);
1091
+ if (!isPathUnderRoot(qaSidecarRoot, fullPath)) {
1092
+ throw new Error(`sidecars[${index}].path must be under ${artifactOwnerRelativeRoot(ownerType, ownerId, workItemId)}/qa/.`);
1093
+ }
1094
+ const stat = await fs.lstat(fullPath).catch((error) => {
1095
+ if (isNodeError(error) && error.code === "ENOENT") {
1096
+ throw new Error(`sidecars[${index}].path does not exist: ${sidecarPath}`);
1097
+ }
1098
+ throw error;
1099
+ });
1100
+ if (!stat.isFile() || stat.isSymbolicLink()) {
1101
+ throw new Error(`sidecars[${index}].path must reference a regular file.`);
1102
+ }
1103
+ await ensureNoSymbolicLinkPathSegments(qaSidecarRoot, path.dirname(fullPath), `sidecars[${index}].path must not traverse symbolic links.`);
1104
+ if (stat.size !== bytes) {
1105
+ throw new Error(`sidecars[${index}].bytes does not match the referenced file.`);
1106
+ }
1107
+ const actualHash = await sha256File(fullPath);
1108
+ if (actualHash !== contentHash.trim().toLowerCase()) {
1109
+ throw new Error(`sidecars[${index}].content_hash does not match the referenced file.`);
1110
+ }
1111
+ validated.push({
1112
+ ...record,
1113
+ path: path.relative(worktreePath, fullPath).split(path.sep).join("/"),
1114
+ content_hash: actualHash,
1115
+ bytes: stat.size
1116
+ });
1117
+ }
1118
+ return validated;
1119
+ }
1120
+ export async function readCompletionArtifact(worktreePath, workItemId, phase, ownerType, ownerId) {
1121
+ const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase, ownerType, ownerId);
1122
+ const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase, ownerType, ownerId);
264
1123
  const verdictJson = await readOptionalFile(artifactPath);
265
1124
  if (verdictJson === null) {
266
1125
  return null;
267
1126
  }
268
1127
  const parsed = parseJsonObject(verdictJson, artifactPath);
269
1128
  const report = await readOptionalFile(reportPath) ?? fallbackReport(parsed, phase, artifactPath);
1129
+ const artifactRoot = path.dirname(artifactPath);
1130
+ const implementationPlanJson = phase === "architect"
1131
+ ? await readOptionalFile(path.join(artifactRoot, "implementation.plan.json"))
1132
+ : null;
1133
+ const qaPlanJson = phase === "architect"
1134
+ ? await readOptionalFile(path.join(artifactRoot, "qa.plan.json"))
1135
+ : null;
270
1136
  return {
271
1137
  repoPath: path.resolve(worktreePath),
272
1138
  path: artifactPath,
273
1139
  verdictJson,
1140
+ implementationPlanJson,
1141
+ qaPlanJson,
274
1142
  report,
275
1143
  producedBy: optionalString(parsed, "produced_by") ?? optionalString(parsed, "producedBy") ?? "forge-completion-tool",
276
1144
  status: optionalString(parsed, "status") ?? "unknown",
@@ -302,8 +1170,14 @@ export function parseCompletionMcpArgs(argv) {
302
1170
  let worktreePath = null;
303
1171
  let workItemId = null;
304
1172
  let phase = "implementation";
1173
+ let ownerType;
1174
+ let ownerId;
305
1175
  let producedBy;
306
1176
  let developCycle = false;
1177
+ let qaCycle = false;
1178
+ let debugCycle = false;
1179
+ let architectCycle = false;
1180
+ let draftCycle = false;
307
1181
  for (let index = 1; index < argv.length; index += 1) {
308
1182
  const arg = argv[index];
309
1183
  if (arg === "--worktree") {
@@ -312,11 +1186,20 @@ export function parseCompletionMcpArgs(argv) {
312
1186
  else if (arg === "--work-item-id") {
313
1187
  workItemId = argv[++index] ?? null;
314
1188
  }
1189
+ else if (arg === "--owner-type") {
1190
+ ownerType = normalizedOwnerType(argv[++index]);
1191
+ if (!ownerType) {
1192
+ return { ok: false, error: "mcp --owner-type must be work_item or story." };
1193
+ }
1194
+ }
1195
+ else if (arg === "--owner-id") {
1196
+ ownerId = argv[++index] ?? undefined;
1197
+ }
315
1198
  else if (arg === "--phase") {
316
1199
  const rawPhase = argv[++index];
317
1200
  const parsedPhase = parseStrictCompletionPhase(rawPhase);
318
1201
  if (!parsedPhase) {
319
- return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation." };
1202
+ return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation, qa, architect, draft, debug-repro, debug-root-cause, debug-fix, debug-regression." };
320
1203
  }
321
1204
  phase = parsedPhase;
322
1205
  }
@@ -326,6 +1209,18 @@ export function parseCompletionMcpArgs(argv) {
326
1209
  else if (arg === "--develop-cycle") {
327
1210
  developCycle = true;
328
1211
  }
1212
+ else if (arg === "--qa-cycle") {
1213
+ qaCycle = true;
1214
+ }
1215
+ else if (arg === "--debug-cycle") {
1216
+ debugCycle = true;
1217
+ }
1218
+ else if (arg === "--architect-cycle") {
1219
+ architectCycle = true;
1220
+ }
1221
+ else if (arg === "--draft-cycle") {
1222
+ draftCycle = true;
1223
+ }
329
1224
  else {
330
1225
  return { ok: false, error: `Unknown mcp argument: ${arg}` };
331
1226
  }
@@ -333,15 +1228,39 @@ export function parseCompletionMcpArgs(argv) {
333
1228
  if (!worktreePath?.trim() || !workItemId?.trim()) {
334
1229
  return { ok: false, error: "mcp requires --worktree and --work-item-id." };
335
1230
  }
1231
+ if ([developCycle, qaCycle, debugCycle, architectCycle, draftCycle].filter(Boolean).length > 1) {
1232
+ return { ok: false, error: "mcp accepts only one cycle mode." };
1233
+ }
1234
+ if (developCycle && !isDevelopCompletionPhase(phase)) {
1235
+ return { ok: false, error: "mcp --develop-cycle requires --phase implementation, self-review, or validation." };
1236
+ }
1237
+ if (qaCycle && phase !== "qa") {
1238
+ return { ok: false, error: "mcp --qa-cycle requires --phase qa." };
1239
+ }
1240
+ if (debugCycle && !isDebugCompletionPhase(phase)) {
1241
+ return { ok: false, error: "mcp --debug-cycle requires --phase debug-repro, debug-root-cause, debug-fix, or debug-regression." };
1242
+ }
1243
+ if (architectCycle && phase !== "architect") {
1244
+ return { ok: false, error: "mcp --architect-cycle requires --phase architect." };
1245
+ }
1246
+ if (draftCycle && phase !== "draft") {
1247
+ return { ok: false, error: "mcp --draft-cycle requires --phase draft." };
1248
+ }
336
1249
  return {
337
1250
  ok: true,
338
1251
  config: {
339
1252
  worktreePath: path.resolve(worktreePath),
340
1253
  workItemId,
1254
+ ownerType,
1255
+ ownerId,
341
1256
  phase,
342
1257
  producedBy,
343
1258
  redactionSecrets: parseCompletionRedactionSecrets(process.env[completionRedactionSecretsEnv]),
344
- developCycle
1259
+ developCycle,
1260
+ qaCycle,
1261
+ debugCycle,
1262
+ architectCycle,
1263
+ draftCycle
345
1264
  }
346
1265
  };
347
1266
  }
@@ -436,39 +1355,143 @@ async function handleJsonRpcRequest(session, method, params) {
436
1355
  }
437
1356
  throw new Error(`Unsupported MCP method: ${method}`);
438
1357
  }
439
- function toolDefinition(name, phase) {
1358
+ function toolDefinition(name, phase, qaGate = null) {
440
1359
  return {
441
1360
  name,
442
- description: toolDescription(phase),
443
- inputSchema: toolInputSchema(phase)
1361
+ description: toolDescription(phase, qaGate),
1362
+ inputSchema: toolInputSchema(phase, qaGate)
444
1363
  };
445
1364
  }
446
1365
  function nextPhaseAfter(phase) {
1366
+ if (!isDevelopCompletionPhase(phase)) {
1367
+ return null;
1368
+ }
447
1369
  const index = completionPhaseOrder.indexOf(phase);
448
1370
  return index >= 0 ? completionPhaseOrder[index + 1] ?? null : null;
449
1371
  }
1372
+ function nextDebugPhaseAfter(phase) {
1373
+ const index = debugCompletionPhaseOrder.indexOf(phase);
1374
+ return index >= 0 ? debugCompletionPhaseOrder[index + 1] ?? null : null;
1375
+ }
450
1376
  function completionToolNextInstruction(completedPhase, status, nextPhase) {
1377
+ if (completedPhase === "qa") {
1378
+ if (status === "blocked") {
1379
+ return "QA blocked. Forge recorded the blocker reason and will surface the run for human attention.";
1380
+ }
1381
+ if (status === "needs_rework") {
1382
+ return "QA findings recorded. Forge has the structured evidence needed to route this work back for implementation rework.";
1383
+ }
1384
+ return "QA accepted. Forge has the structured evidence needed to move this work item to Sign-Off.";
1385
+ }
451
1386
  if (status !== "pass") {
452
1387
  return `Stay in ${completedPhase}, address the recorded blockers, then call ${expectedCompletionToolName(completedPhase)} again.`;
453
1388
  }
1389
+ if (isDebugCompletionPhase(completedPhase)) {
1390
+ const debugNext = isDebugCompletionPhase(nextPhase) ? nextPhase : null;
1391
+ return completionToolNextInstructionForDebugGate(completedPhase, status, debugNext);
1392
+ }
454
1393
  if (nextPhase === "self_review") {
455
1394
  return "Implementation accepted. Begin self-review: inspect the diff, apply safe fixes, and call forge.complete_self_review with review evidence.";
456
1395
  }
457
1396
  if (nextPhase === "validation") {
458
1397
  return "Self-review accepted. Begin validation: run deterministic checks, prove acceptance criteria, and call forge.complete_validation with command evidence.";
459
1398
  }
460
- return "Validation accepted. Forge has the structured evidence needed to move this work item to Dev Test.";
1399
+ return "Validation accepted. Forge has the structured evidence needed to move this work item to QA.";
1400
+ }
1401
+ function completionToolNextInstructionForDraftGate(completedGate, status, nextGate) {
1402
+ if (status === "blocked") {
1403
+ return `Stay in ${completedGate}; record the blocker and retry the same Draft gate when unblocked.`;
1404
+ }
1405
+ if (!nextGate) {
1406
+ return "Draft proposal accepted. Forge has the structured Work Order draft JSON needed to populate the form.";
1407
+ }
1408
+ const instructions = {
1409
+ draft_intent: "Capture intent/non-goals, then call forge.complete_draft_intent.",
1410
+ draft_repo_context: "Inspect selected repo/project assumptions, then call forge.complete_draft_repo_context.",
1411
+ draft_graph_context: "Account for DAG dependencies and placement, then call forge.complete_draft_graph_context.",
1412
+ draft_product_scope: "Choose product scope for the selected project, then call forge.complete_draft_product_scope.",
1413
+ draft_work_order_plan: "Draft Work Order fields and candidate Feature boundaries, then call forge.complete_draft_work_order_plan.",
1414
+ draft_critic: "Critique literalism/wrong-project scope/decomposition risk, then call forge.complete_draft_critic.",
1415
+ draft_proposal: "Submit final draft_json through forge.complete_draft_proposal."
1416
+ };
1417
+ return `${completedGate} accepted. Continue to ${nextGate}. ${instructions[nextGate]}`;
461
1418
  }
462
- function toolDescription(phase) {
1419
+ function completionToolNextInstructionForQaGate(completedGate, status, nextGate) {
1420
+ if (!nextGate) {
1421
+ if (status === "blocked") {
1422
+ return "QA blocked. Forge recorded the blocker reason and will surface the run for human attention.";
1423
+ }
1424
+ if (status === "needs_rework") {
1425
+ return "QA findings recorded. Forge has the structured evidence needed to route this work back for implementation rework.";
1426
+ }
1427
+ return "QA accepted. Forge has the structured evidence needed to move this work item to Sign-Off.";
1428
+ }
1429
+ const skipped = status === "skipped";
1430
+ const blocked = status === "blocked";
1431
+ const prefix = blocked
1432
+ ? `${completedGate} recorded a blocker. Continue through ${nextGate} and mark downstream gates skipped if the blocker prevents evidence collection.`
1433
+ : skipped
1434
+ ? `${completedGate} skipped. Continue to ${nextGate}.`
1435
+ : `${completedGate} accepted. Continue to ${nextGate}.`;
1436
+ return `${prefix} ${qaGateInstruction(nextGate)}`;
1437
+ }
1438
+ function completionToolNextInstructionForDebugGate(completedGate, status, nextGate) {
1439
+ if (status !== "pass") {
1440
+ return `Stay in ${completedGate}, address the recorded blockers, then call ${expectedDebugCompletionToolName(completedGate)} again.`;
1441
+ }
1442
+ if (nextGate === "debug_root_cause") {
1443
+ return "Debug repro accepted. Begin root-cause analysis: connect the observed failure to code evidence and call forge.complete_debug_root_cause.";
1444
+ }
1445
+ if (nextGate === "debug_fix") {
1446
+ return "Debug root cause accepted. Apply the smallest safe fix with regression coverage where practical, then call forge.complete_debug_fix.";
1447
+ }
1448
+ if (nextGate === "debug_regression") {
1449
+ return "Debug fix accepted. Prove the original repro is negative, run targeted regression checks, and call forge.complete_debug_regression.";
1450
+ }
1451
+ return "Debug regression accepted. Forge has the structured evidence needed to move this bug fix to QA.";
1452
+ }
1453
+ function qaGateInstruction(gate) {
1454
+ switch (gate) {
1455
+ case "qa_regression":
1456
+ return "Run or explicitly skip applicable regression/build/lint/typecheck/e2e checks, then call forge.complete_qa_regression.";
1457
+ case "qa_api":
1458
+ return "Run or explicitly skip applicable API/backend contract checks, then call forge.complete_qa_api.";
1459
+ case "qa_manual_web":
1460
+ return "Run or explicitly skip applicable browser/manual web checks, then call forge.complete_qa_manual_web.";
1461
+ case "qa_bug_repro":
1462
+ return "Reproduce or explicitly skip relevant defects/candidate bugs, then call forge.complete_qa_bug_repro.";
1463
+ case "qa_findings":
1464
+ return "Normalize observations into findings and candidate bugs, then call forge.complete_qa_findings.";
1465
+ case "qa_verdict":
1466
+ return "Assemble the final QA verdict from all prior gate evidence, then call forge.complete_qa_verdict.";
1467
+ case "qa_plan":
1468
+ return "Prepare the QA checklist, then call forge.complete_qa_plan.";
1469
+ }
1470
+ }
1471
+ function toolDescription(phase, qaGate = null) {
1472
+ if (qaGate) {
1473
+ return qaGate === "qa_verdict"
1474
+ ? "Complete the final Forge QA verdict by writing the canonical QA bundle with pass, needs_rework, or blocked evidence."
1475
+ : `Complete the ${qaGate.replace(/_/g, " ")} QA gate by writing ${qaGateFileNames[qaGate]} before continuing to the next QA gate.`;
1476
+ }
1477
+ if (isDebugCompletionPhase(phase)) {
1478
+ return `Complete the ${phase.replace(/_/g, " ")} Debug gate by writing ${phaseFiles[phase].jsonFileName} with structured bug-fix evidence before continuing.`;
1479
+ }
463
1480
  if (phase === "implementation") {
464
1481
  return "Complete Forge implementation by writing implementation.completeness.json with scoped changed-file, verification, acceptance-criteria, gap, and next-phase evidence.";
465
1482
  }
466
1483
  if (phase === "self_review") {
467
1484
  return "Complete Forge self-review by writing self-review.report.json with diff review, findings, security, edge-case, design, deterministic-comparison, fixes, and remaining-risk evidence.";
468
1485
  }
1486
+ if (phase === "qa") {
1487
+ return "Complete Forge QA by writing qa.plan.json, qa.evidence.json, qa.findings.json, qa.verdict.json, and qa.report.md with structured pass, needs-rework, or blocked evidence.";
1488
+ }
1489
+ if (phase === "architect") {
1490
+ return "Complete Forge Architect planning by writing implementation.plan.json, qa.plan.json, architect.verdict.json, and architect.report.md with a pending-approval plan or explicit revision/blocker reasons.";
1491
+ }
469
1492
  return "Complete Forge validation by writing validation.verdict.json with command, build/test/lint/design, drift, acceptance-criteria, and ready-for-dev-test evidence.";
470
1493
  }
471
- function toolInputSchema(phase) {
1494
+ function toolInputSchema(phase, qaGate = null) {
472
1495
  const baseProperties = {
473
1496
  status: {
474
1497
  type: "string",
@@ -487,6 +1510,12 @@ function toolInputSchema(phase) {
487
1510
  })
488
1511
  }
489
1512
  };
1513
+ if (qaGate && qaGate !== "qa_verdict") {
1514
+ return qaGateToolInputSchema(qaGate);
1515
+ }
1516
+ if (isDebugCompletionPhase(phase)) {
1517
+ return debugToolInputSchema(phase, baseProperties);
1518
+ }
490
1519
  if (phase === "implementation") {
491
1520
  return objectToolSchema({
492
1521
  ...baseProperties,
@@ -509,7 +1538,7 @@ function toolInputSchema(phase) {
509
1538
  },
510
1539
  tests_added_or_updated: {
511
1540
  type: "array",
512
- description: "Required for pass. Use an object explaining why no tests were needed for docs/config-only work if empty would be ambiguous.",
1541
+ description: "Required for pass. Use an object explaining why no tests were needed for documentation/config-only work if empty would be ambiguous.",
513
1542
  items: evidenceObjectSchema(["path", "summary"], {
514
1543
  path: { type: "string" },
515
1544
  summary: { type: "string" }
@@ -540,6 +1569,11 @@ function toolInputSchema(phase) {
540
1569
  },
541
1570
  next_phase_context: {
542
1571
  description: "Required for pass. Context the self-review phase should carry forward."
1572
+ },
1573
+ resolved_findings: {
1574
+ type: "array",
1575
+ description: "Required for QA rework. Each entry must use status resolved, disputed, or not_reproduced.",
1576
+ items: resolvedFindingSchema()
543
1577
  }
544
1578
  }, ["status", "summary"], "For status pass, include plan, changed_files, tests_added_or_updated, docs_added_or_updated, acceptance_criteria, known_gaps, and next_phase_context. Acceptance criteria entries must use status: satisfied plus evidence.");
545
1579
  }
@@ -588,6 +1622,170 @@ function toolInputSchema(phase) {
588
1622
  }
589
1623
  }, ["status", "summary"], "For status pass, include reviewed_diff, findings, security_review, edge_case_review, design_review, deterministic_comparison, fixes_applied, and remaining_risks.");
590
1624
  }
1625
+ if (phase === "qa") {
1626
+ return objectToolSchema({
1627
+ ...baseProperties,
1628
+ status: {
1629
+ type: "string",
1630
+ enum: ["pass", "needs_rework", "blocked"],
1631
+ description: "Use pass only when QA evidence satisfies acceptance criteria, needs_rework for actionable in-scope defects, or blocked for an inconclusive QA blocker."
1632
+ },
1633
+ checklist: {
1634
+ type: "array",
1635
+ description: "QA plan/checklist. Forge writes this to qa.plan.json; a default checklist is generated if omitted.",
1636
+ items: { type: "string" }
1637
+ },
1638
+ tested_acceptance_criteria: {
1639
+ type: "array",
1640
+ description: "Required and non-empty for pass/needs_rework. Criteria actually tested by QA.",
1641
+ items: { type: "string" }
1642
+ },
1643
+ commands: {
1644
+ type: "array",
1645
+ description: "Command evidence written to qa.evidence.json.",
1646
+ items: commandEvidenceSchema()
1647
+ },
1648
+ browser_checks: {
1649
+ type: "array",
1650
+ description: "Browser/manual UI checks with URL or route, action, observed result, screenshot/trace references, console/network notes, and status.",
1651
+ items: evidenceObjectSchema(["summary", "status"], {
1652
+ summary: { type: "string" },
1653
+ url: { type: "string" },
1654
+ route: { type: "string" },
1655
+ status: { type: "string" },
1656
+ screenshot: { type: "string" },
1657
+ trace: { type: "string" }
1658
+ })
1659
+ },
1660
+ sidecars: {
1661
+ type: "array",
1662
+ description: "Optional QA sidecar files already written under .forge/work-items/<id>/artifacts/qa/ with path/content_hash/bytes metadata.",
1663
+ items: evidenceObjectSchema(["path", "content_hash", "bytes"], {
1664
+ path: { type: "string" },
1665
+ content_hash: { type: "string" },
1666
+ bytes: { type: "number" }
1667
+ })
1668
+ },
1669
+ notes: { type: "string", description: "Additional QA evidence notes." },
1670
+ evidence: {
1671
+ type: "object",
1672
+ description: "Optional wrapper containing commands, browser_checks, and notes when a client prefers nested evidence."
1673
+ },
1674
+ findings: {
1675
+ type: "array",
1676
+ description: "QA findings. needs_rework requires at least one actionable in_scope finding.",
1677
+ items: evidenceObjectSchema(["id", "severity", "scope", "title"], {
1678
+ id: { type: "string" },
1679
+ severity: { type: "string", enum: ["critical", "major", "minor"] },
1680
+ scope: { type: "string", enum: ["in_scope", "out_of_scope", "unclear"] },
1681
+ title: { type: "string" },
1682
+ acceptance_criteria: { type: "array", items: { type: "string" } },
1683
+ repro_steps: { type: "array", items: { type: "string" } },
1684
+ expected: { type: "string" },
1685
+ actual: { type: "string" },
1686
+ evidence: { type: "object" },
1687
+ likely_area: { type: "array", items: { type: "string" } },
1688
+ required_fix: { type: "string" },
1689
+ required_regression: { type: "string" }
1690
+ })
1691
+ },
1692
+ candidate_bugs: {
1693
+ type: "array",
1694
+ description: "Out-of-scope/follow-up bug candidates. They do not block the current item unless attached as in-scope findings.",
1695
+ items: evidenceObjectSchema(["id", "title", "suggested_action"], {
1696
+ id: { type: "string" },
1697
+ title: { type: "string" },
1698
+ severity: { type: "string" },
1699
+ scope_reason: { type: "string" },
1700
+ repro_steps: { type: "array", items: { type: "string" } },
1701
+ evidence: { type: "object" },
1702
+ suggested_action: { type: "string", enum: ["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"] }
1703
+ })
1704
+ },
1705
+ blocker_reason: {
1706
+ type: "string",
1707
+ enum: [...qaBlockerReasons],
1708
+ description: "Required when status is blocked."
1709
+ }
1710
+ }, ["status", "summary"], "For pass, include tested_acceptance_criteria plus concrete command/browser/note evidence. For needs_rework, include at least one actionable in_scope finding. For blocked, include blocker_reason.");
1711
+ }
1712
+ if (phase === "architect") {
1713
+ return objectToolSchema({
1714
+ status: {
1715
+ type: "string",
1716
+ enum: ["pass", "needs_revision", "blocked"],
1717
+ description: "Use pass only for a complete pending-approval Architect plan. Use needs_revision for fixable story/design/repo gaps, or blocked for missing required context or decisions."
1718
+ },
1719
+ summary: { type: "string", description: "Concise Architect plan verdict summary." },
1720
+ implementation_plan: {
1721
+ type: "object",
1722
+ description: "Required for pass. Top-level fields inside this object must include schema_version, plan_id, phases, tasks, dependencies, and phase_gates.",
1723
+ additionalProperties: true,
1724
+ properties: {
1725
+ schema_version: { type: "number", enum: [1] },
1726
+ plan_id: { type: "string" },
1727
+ phases: {
1728
+ type: "array",
1729
+ description: "Required top-level implementation_plan.phases array.",
1730
+ items: { type: "object", additionalProperties: true }
1731
+ },
1732
+ tasks: {
1733
+ type: "array",
1734
+ description: "Required Develop child task list. Each task must include id and a non-empty tests array, and must require a focused repo/product implementation change. Do not put parent-story QA/sign-off, child-count/materialization inventory, parent plan artifact checks, or final acceptance proof here; those belong in qa_plan.final_qa.",
1735
+ items: { type: "object", additionalProperties: true }
1736
+ },
1737
+ dependencies: {
1738
+ type: "array",
1739
+ description: "Required dependency edge array. Use [] when no task dependencies exist. Each edge should use before and after task ids; from/to are accepted only as aliases and normalized before writing artifacts.",
1740
+ items: {
1741
+ type: "object",
1742
+ additionalProperties: true,
1743
+ properties: {
1744
+ id: { type: "string" },
1745
+ before: { type: "string", description: "Task id that must complete first." },
1746
+ after: { type: "string", description: "Task id that depends on before." },
1747
+ from: { type: "string", description: "Alias for before." },
1748
+ to: { type: "string", description: "Alias for after." },
1749
+ type: { type: "string" },
1750
+ rationale: { type: "string" }
1751
+ }
1752
+ }
1753
+ },
1754
+ phase_gates: {
1755
+ type: "array",
1756
+ description: "Required non-empty phase gate array.",
1757
+ items: { type: "object", additionalProperties: true }
1758
+ }
1759
+ }
1760
+ },
1761
+ qa_plan: {
1762
+ type: "object",
1763
+ description: "Required for pass. Must include schema_version: 1 and non-empty final_qa coverage.",
1764
+ additionalProperties: true,
1765
+ properties: {
1766
+ schema_version: { type: "number", enum: [1] },
1767
+ final_qa: {
1768
+ type: "array",
1769
+ description: "Required non-empty final QA coverage array.",
1770
+ items: { type: "object", additionalProperties: true }
1771
+ }
1772
+ }
1773
+ },
1774
+ report_markdown: { type: "string", description: "Human-readable Architect report. Use report as an alias only when the client cannot send report_markdown." },
1775
+ report: { type: "string", description: "Alias for report_markdown." },
1776
+ blockers: baseProperties.blockers,
1777
+ revision_questions: {
1778
+ type: "array",
1779
+ description: "Required for needs_revision when blockers are not used.",
1780
+ items: { type: "string" }
1781
+ },
1782
+ revision_reasons: {
1783
+ type: "array",
1784
+ description: "Concrete reasons that prevent pass status.",
1785
+ items: { type: "string" }
1786
+ }
1787
+ }, ["status", "summary"], "For status pass, include implementation_plan and qa_plan at the top level of the MCP tool arguments. implementation_plan.phases must be a top-level array inside implementation_plan, not nested under another object.");
1788
+ }
591
1789
  return objectToolSchema({
592
1790
  ...baseProperties,
593
1791
  commands: {
@@ -612,6 +1810,144 @@ function toolInputSchema(phase) {
612
1810
  ready_for_dev_test: { type: "boolean", description: "Required for pass and must be true." }
613
1811
  }, ["status", "summary"], "For status pass, commands must include at least one passing deterministic command, acceptance criteria entries must use status: satisfied plus evidence, and ready_for_dev_test must be true.");
614
1812
  }
1813
+ function debugToolInputSchema(phase, baseProperties) {
1814
+ if (phase === "debug_repro") {
1815
+ return objectToolSchema({
1816
+ ...baseProperties,
1817
+ repro_steps: {
1818
+ type: "array",
1819
+ description: "Required for pass. Minimal reproduction or characterization steps.",
1820
+ items: { type: "string" }
1821
+ },
1822
+ observed: { type: "string", description: "Observed failure behavior." },
1823
+ expected: { type: "string", description: "Expected behavior." },
1824
+ evidence: {
1825
+ type: "array",
1826
+ description: "Required for pass. Concrete logs, commands, screenshots, file refs, or characterization notes.",
1827
+ items: { type: "object", additionalProperties: true }
1828
+ }
1829
+ }, ["status", "summary"], "For status pass, include repro_steps, observed, expected, and evidence.");
1830
+ }
1831
+ if (phase === "debug_root_cause") {
1832
+ return objectToolSchema({
1833
+ ...baseProperties,
1834
+ root_cause: { type: "string", description: "Likely root cause tied to code or config evidence." },
1835
+ evidence: {
1836
+ type: "array",
1837
+ description: "Required for pass. Concrete code/log/test evidence supporting the root cause.",
1838
+ items: { type: "object", additionalProperties: true }
1839
+ },
1840
+ eliminated_alternatives: {
1841
+ type: "array",
1842
+ description: "Required for pass. Plausible alternatives checked or ruled out.",
1843
+ items: { type: "object", additionalProperties: true }
1844
+ },
1845
+ risk_area: { type: "string", description: "Subsystem or behavior most at risk from the fix." }
1846
+ }, ["status", "summary"], "For status pass, include root_cause, evidence, eliminated_alternatives, and risk_area.");
1847
+ }
1848
+ if (phase === "debug_fix") {
1849
+ return objectToolSchema({
1850
+ ...baseProperties,
1851
+ changed_files: {
1852
+ type: "array",
1853
+ description: "Required for pass. Files changed by the bug fix.",
1854
+ items: evidenceObjectSchema(["path", "summary"], { path: { type: "string" }, summary: { type: "string" } })
1855
+ },
1856
+ tests_added_or_updated: {
1857
+ type: "array",
1858
+ description: "Required for pass. Regression tests or checks added/updated, or justify omission in remaining_risks.",
1859
+ items: evidenceObjectSchema(["path", "summary"], { path: { type: "string" }, summary: { type: "string" } })
1860
+ },
1861
+ remaining_risks: {
1862
+ type: "array",
1863
+ description: "Required for pass, even when empty. Include why no regression coverage changed when tests_added_or_updated is empty.",
1864
+ items: evidenceObjectSchema(["summary"], { summary: { type: "string" }, mitigation: { type: "string" } })
1865
+ },
1866
+ resolved_findings: {
1867
+ type: "array",
1868
+ description: "Required for QA rework. Each entry must use status resolved, disputed, or not_reproduced.",
1869
+ items: resolvedFindingSchema()
1870
+ }
1871
+ }, ["status", "summary"], "For status pass, include changed_files, tests_added_or_updated, and remaining_risks.");
1872
+ }
1873
+ return objectToolSchema({
1874
+ ...baseProperties,
1875
+ commands: {
1876
+ type: "array",
1877
+ description: "Required for pass. Targeted regression/repro-negative commands with exit_code: 0 and status: pass.",
1878
+ items: commandEvidenceSchema()
1879
+ },
1880
+ required_regressions: {
1881
+ type: "array",
1882
+ description: "Required for pass. Repro-negative and regression coverage checklist.",
1883
+ items: { type: "string" }
1884
+ },
1885
+ build_status: { type: "string", description: "Required for pass. pass or not_applicable." },
1886
+ test_status: { type: "string", description: "Required for pass. pass or not_applicable." },
1887
+ repro_negative: { type: "boolean", description: "Required for pass and must be true after the original repro no longer fails." },
1888
+ qa_ready: { type: "boolean", description: "Required for pass and must be true." }
1889
+ }, ["status", "summary"], "For status pass, commands must include at least one passing deterministic debug regression check, repro_negative must be true, and qa_ready must be true.");
1890
+ }
1891
+ function qaGateToolInputSchema(gate) {
1892
+ const baseProperties = {
1893
+ status: {
1894
+ type: "string",
1895
+ enum: ["pass", "skipped", "blocked"],
1896
+ description: "Use pass when this QA gate produced evidence, skipped when not applicable, or blocked when a prerequisite prevents this gate."
1897
+ },
1898
+ summary: { type: "string", description: "Concise QA gate summary." },
1899
+ reason: { type: "string", description: "Required for skipped or blocked gates." },
1900
+ blocker_reason: {
1901
+ type: "string",
1902
+ enum: [...qaBlockerReasons],
1903
+ description: "Required when status is blocked."
1904
+ }
1905
+ };
1906
+ if (gate === "qa_plan") {
1907
+ return objectToolSchema({
1908
+ ...baseProperties,
1909
+ checklist: {
1910
+ type: "array",
1911
+ description: "Required for pass. QA checklist entries planned for this work item.",
1912
+ items: { type: "string" }
1913
+ },
1914
+ acceptance_criteria: {
1915
+ type: "array",
1916
+ description: "Acceptance criteria selected for QA.",
1917
+ items: { type: "string" }
1918
+ }
1919
+ }, ["status", "summary"], "Record the QA plan gate. Pass requires a non-empty checklist.");
1920
+ }
1921
+ if (gate === "qa_findings") {
1922
+ return objectToolSchema({
1923
+ ...baseProperties,
1924
+ findings: {
1925
+ type: "array",
1926
+ description: "Normalized in-scope and out-of-scope QA findings.",
1927
+ items: { type: "object", additionalProperties: true }
1928
+ },
1929
+ candidate_bugs: {
1930
+ type: "array",
1931
+ description: "Out-of-scope or follow-up candidates.",
1932
+ items: { type: "object", additionalProperties: true }
1933
+ }
1934
+ }, ["status", "summary"], "Record normalized QA findings. Pass or skipped requires findings and candidate_bugs arrays, even when empty.");
1935
+ }
1936
+ return objectToolSchema({
1937
+ ...baseProperties,
1938
+ commands: {
1939
+ type: "array",
1940
+ description: "Command evidence for this gate when applicable.",
1941
+ items: commandEvidenceSchema()
1942
+ },
1943
+ browser_checks: {
1944
+ type: "array",
1945
+ description: "Browser/manual evidence for this gate when applicable.",
1946
+ items: { type: "object", additionalProperties: true }
1947
+ },
1948
+ notes: { type: "string", description: "Evidence notes for this gate." }
1949
+ }, ["status", "summary"], "Record this QA evidence gate. Use skipped with a reason when the gate is not applicable.");
1950
+ }
615
1951
  function objectToolSchema(properties, required, description) {
616
1952
  return {
617
1953
  type: "object",
@@ -637,6 +1973,29 @@ function commandEvidenceSchema() {
637
1973
  summary: { type: "string" }
638
1974
  });
639
1975
  }
1976
+ function resolvedFindingSchema() {
1977
+ return evidenceObjectSchema([
1978
+ "qa_id",
1979
+ "status",
1980
+ "summary",
1981
+ "evidence",
1982
+ "changed_files",
1983
+ "tests_added_or_updated",
1984
+ "regression_evidence"
1985
+ ], {
1986
+ qa_id: { type: "string" },
1987
+ status: {
1988
+ type: "string",
1989
+ enum: [...resolvedFindingStatusValues],
1990
+ description: "Use resolved when fixed, disputed when the QA finding is incorrect/out-of-scope, or not_reproduced when retesting cannot reproduce it."
1991
+ },
1992
+ summary: { type: "string" },
1993
+ evidence: { description: "Concrete evidence for the resolution." },
1994
+ changed_files: { type: "array", description: "Required and non-empty when status is resolved." },
1995
+ tests_added_or_updated: { type: "array", description: "Required and non-empty when status is resolved." },
1996
+ regression_evidence: { description: "Concrete regression evidence for this QA finding." }
1997
+ });
1998
+ }
640
1999
  function acceptanceCriteriaSchema() {
641
2000
  return {
642
2001
  type: "array",
@@ -662,8 +2021,22 @@ function reviewSectionProperties() {
662
2021
  notes: { type: "string" }
663
2022
  };
664
2023
  }
665
- function normalizeCompletionStatus(value) {
2024
+ function normalizeCompletionStatus(value, phase) {
666
2025
  const normalized = value.trim().toLowerCase().replace(/-/g, "_");
2026
+ if (phase === "qa") {
2027
+ const canonical = normalized === "needsrework" ? "needs_rework" : normalized;
2028
+ if (canonical !== "pass" && canonical !== "needs_rework" && canonical !== "blocked") {
2029
+ throw new Error("QA status must be pass, needs_rework, or blocked.");
2030
+ }
2031
+ return canonical;
2032
+ }
2033
+ if (phase === "architect") {
2034
+ const canonical = normalized === "needsrevision" ? "needs_revision" : normalized;
2035
+ if (canonical !== "pass" && canonical !== "needs_revision" && canonical !== "blocked") {
2036
+ throw new Error("Architect status must be pass, needs_revision, or blocked.");
2037
+ }
2038
+ return canonical;
2039
+ }
667
2040
  const canonical = normalized === "blocked" || normalized === "needsrework"
668
2041
  ? "needs_rework"
669
2042
  : normalized === "failed"
@@ -674,17 +2047,36 @@ function normalizeCompletionStatus(value) {
674
2047
  }
675
2048
  return canonical;
676
2049
  }
2050
+ function normalizeQaGateStatus(value) {
2051
+ const normalized = value.trim().toLowerCase().replace(/-/g, "_");
2052
+ if (normalized !== "pass" && normalized !== "skipped" && normalized !== "blocked") {
2053
+ throw new Error("QA gate status must be pass, skipped, or blocked.");
2054
+ }
2055
+ return normalized;
2056
+ }
677
2057
  function validatePayloadShape(phase, payload) {
678
- const status = normalizeCompletionStatus(requiredString(payload, "status"));
2058
+ const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
679
2059
  if (!status) {
680
2060
  throw new Error("status is required.");
681
2061
  }
682
- const pass = status === "pass";
683
2062
  requireField(payload, "summary");
2063
+ if (phase === "qa") {
2064
+ validateQaPayloadShape(payload, status);
2065
+ return;
2066
+ }
2067
+ if (phase === "architect") {
2068
+ validateArchitectPayloadShape(payload, status);
2069
+ return;
2070
+ }
2071
+ const pass = status === "pass";
684
2072
  if (!pass) {
685
2073
  requireNonPassEvidence(payload);
686
2074
  return;
687
2075
  }
2076
+ if (isDebugCompletionPhase(phase)) {
2077
+ validateDebugPayloadShape(phase, payload);
2078
+ return;
2079
+ }
688
2080
  if (phase === "implementation") {
689
2081
  requireArray(payload, "plan");
690
2082
  requireArray(payload, "changed_files");
@@ -695,6 +2087,7 @@ function validatePayloadShape(phase, payload) {
695
2087
  requireField(payload, "next_phase_context");
696
2088
  requireImplementationEvidence(payload);
697
2089
  requireSatisfiedAcceptanceCriteria(payload);
2090
+ validateResolvedFindings(payload);
698
2091
  return;
699
2092
  }
700
2093
  if (phase === "self_review") {
@@ -722,6 +2115,504 @@ function validatePayloadShape(phase, payload) {
722
2115
  requirePassingCommands(payload);
723
2116
  requireSatisfiedAcceptanceCriteria(payload);
724
2117
  }
2118
+ function validateDebugPayloadShape(phase, payload) {
2119
+ if (phase === "debug_repro") {
2120
+ requireArray(payload, "repro_steps");
2121
+ requireField(payload, "observed");
2122
+ requireField(payload, "expected");
2123
+ requireArray(payload, "evidence");
2124
+ requireNonEmptyArray(payload, "repro_steps");
2125
+ requireNonEmptyArray(payload, "evidence");
2126
+ return;
2127
+ }
2128
+ if (phase === "debug_root_cause") {
2129
+ requireField(payload, "root_cause");
2130
+ requireArray(payload, "evidence");
2131
+ requireArray(payload, "eliminated_alternatives");
2132
+ requireField(payload, "risk_area");
2133
+ requireNonEmptyArray(payload, "evidence");
2134
+ return;
2135
+ }
2136
+ if (phase === "debug_fix") {
2137
+ requireArray(payload, "changed_files");
2138
+ requireArray(payload, "tests_added_or_updated");
2139
+ requireArray(payload, "remaining_risks");
2140
+ requireNonEmptyArray(payload, "changed_files");
2141
+ if (arrayLength(payload, "tests_added_or_updated") === 0 && arrayLength(payload, "remaining_risks") === 0) {
2142
+ throw new Error("tests_added_or_updated is empty; remaining_risks must explain why no regression coverage changed.");
2143
+ }
2144
+ validateResolvedFindings(payload);
2145
+ return;
2146
+ }
2147
+ requireArray(payload, "commands");
2148
+ requireArray(payload, "required_regressions");
2149
+ requireField(payload, "build_status");
2150
+ requireField(payload, "test_status");
2151
+ requireBoolean(payload, "repro_negative");
2152
+ requireBoolean(payload, "qa_ready");
2153
+ if (payload.repro_negative !== true) {
2154
+ throw new Error("debug_regression pass requires repro_negative: true.");
2155
+ }
2156
+ if (payload.qa_ready !== true) {
2157
+ throw new Error("debug_regression pass requires qa_ready: true.");
2158
+ }
2159
+ requireAllowedStatus(payload, "build_status", ["pass", "not_applicable"]);
2160
+ requireAllowedStatus(payload, "test_status", ["pass", "not_applicable"]);
2161
+ requireNonEmptyArray(payload, "required_regressions");
2162
+ requirePassingCommands(payload);
2163
+ }
2164
+ function validateQaGatePayloadShape(gate, payload, status) {
2165
+ requireField(payload, "summary");
2166
+ if (status === "skipped") {
2167
+ requireField(payload, "reason");
2168
+ }
2169
+ if (status === "blocked") {
2170
+ const reason = normalizedString(optionalString(payload, "blocker_reason"));
2171
+ if (!qaBlockerReasons.has(reason)) {
2172
+ throw new Error("QA gate blocked requires blocker_reason to be one of missing_app_launch_target, inconclusive, environment_failure, missing_validation_evidence, missing_worktree, or runner_failure.");
2173
+ }
2174
+ }
2175
+ if (gate === "qa_plan" && status === "pass") {
2176
+ const checklist = qaStringArray(payload, "checklist");
2177
+ if (checklist.length === 0) {
2178
+ throw new Error("complete_qa_plan pass requires checklist with at least one entry.");
2179
+ }
2180
+ }
2181
+ if (gate === "qa_findings" && status !== "blocked") {
2182
+ qaObjectArray(payload, "findings");
2183
+ qaObjectArray(payload, "candidate_bugs");
2184
+ }
2185
+ if ((gate === "qa_regression" || gate === "qa_api") && status === "pass") {
2186
+ const commands = qaArray(payload, "commands");
2187
+ if (commands.length === 0) {
2188
+ throw new Error(`${qaGateToolNames[gate]} pass requires commands with at least one entry.`);
2189
+ }
2190
+ validateQaGatePassingCommands(commands);
2191
+ }
2192
+ if (gate === "qa_manual_web" && status === "pass") {
2193
+ const browserChecks = qaArray(payload, "browser_checks");
2194
+ const notes = optionalString(payload, "notes");
2195
+ if (browserChecks.length === 0 && !notes) {
2196
+ throw new Error(`${qaGateToolNames[gate]} pass requires browser_checks or notes.`);
2197
+ }
2198
+ }
2199
+ }
2200
+ function validateQaGatePassingCommands(commands) {
2201
+ for (const [index, command] of commands.entries()) {
2202
+ requireEvidenceRecord(command, `commands[${index}]`);
2203
+ const record = command;
2204
+ requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
2205
+ requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
2206
+ requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
2207
+ if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
2208
+ throw new Error(`commands[${index}].exit_code is required.`);
2209
+ }
2210
+ if (record.exit_code !== 0) {
2211
+ throw new Error(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
2212
+ }
2213
+ if (normalizedString(record.status) !== "pass") {
2214
+ throw new Error(`commands[${index}].status must be pass when QA gate status is pass.`);
2215
+ }
2216
+ }
2217
+ }
2218
+ function validateArchitectPayloadShape(payload, status) {
2219
+ if (status !== "pass") {
2220
+ requireArchitectNonPassEvidence(payload);
2221
+ return;
2222
+ }
2223
+ const implementationPlan = requiredRecord(payload, "implementation_plan");
2224
+ const qaPlan = requiredRecord(payload, "qa_plan");
2225
+ requireNumericOne(implementationPlan, "schema_version", "implementation_plan.schema_version");
2226
+ requireNonEmptyStringRecord(implementationPlan, "plan_id", "implementation_plan.");
2227
+ requireArchitectArray(implementationPlan, "phases", payload);
2228
+ requireArchitectArray(implementationPlan, "tasks", payload);
2229
+ requireArchitectArray(implementationPlan, "dependencies", payload, { allowEmpty: true });
2230
+ requireArchitectArray(implementationPlan, "phase_gates", payload);
2231
+ if (arrayLength(implementationPlan, "tasks") === 0) {
2232
+ throw new Error("implementation_plan.tasks: expected non-empty array; correction: include at least one task with id and tests.");
2233
+ }
2234
+ const taskIds = new Set();
2235
+ for (const task of implementationPlan.tasks) {
2236
+ if (!task || typeof task !== "object" || Array.isArray(task)) {
2237
+ throw new Error("implementation_plan.tasks[]: expected object entries; correction: each task must be an object with id and tests.");
2238
+ }
2239
+ const taskRecord = task;
2240
+ requireNonEmptyStringRecord(taskRecord, "id", "implementation_plan.tasks[].");
2241
+ const taskId = optionalString(taskRecord, "id") ?? "";
2242
+ if (taskIds.has(taskId)) {
2243
+ throw new Error(`implementation_plan.tasks: duplicate task id '${taskId}'.`);
2244
+ }
2245
+ taskIds.add(taskId);
2246
+ validateArchitectTaskDevelopScope(taskRecord, taskId);
2247
+ requireArchitectArray(taskRecord, "tests", payload, { path: `implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests` });
2248
+ if (arrayLength(taskRecord, "tests") === 0) {
2249
+ throw new Error(`implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests: expected non-empty array; correction: include task-specific verification.`);
2250
+ }
2251
+ }
2252
+ validateAndNormalizeArchitectDependencies(implementationPlan, taskIds);
2253
+ requireNumericOne(qaPlan, "schema_version", "qa_plan.schema_version");
2254
+ requireArchitectArray(qaPlan, "final_qa", payload, { path: "qa_plan.final_qa" });
2255
+ if (arrayLength(qaPlan, "final_qa") === 0) {
2256
+ throw new Error("qa_plan.final_qa: expected non-empty array; correction: include final QA coverage for the completed plan.");
2257
+ }
2258
+ }
2259
+ function validateArchitectTaskDevelopScope(task, taskId) {
2260
+ const explicitScope = firstOptionalString(task, ["execution_scope", "scope", "task_scope", "task_type", "lane", "kind", "type"]);
2261
+ if (isStoryQaScope(explicitScope)) {
2262
+ throw new Error(`implementation_plan.tasks[${taskId}]: story QA/sign-off work must not be materialized as a Develop child task; correction: move this coverage to qa_plan.final_qa and keep implementation_plan.tasks limited to repo/product changes.`);
2263
+ }
2264
+ if (looksLikeStoryLevelVerificationTask(architectTaskScopeText(task))) {
2265
+ throw new Error(`implementation_plan.tasks[${taskId}]: parent-story materialization or sign-off verification belongs in qa_plan.final_qa, not implementation_plan.tasks; correction: keep child tasks focused on implementation work and put child-count/parent-plan artifact checks in final QA coverage.`);
2266
+ }
2267
+ }
2268
+ function firstOptionalString(record, keys) {
2269
+ for (const key of keys) {
2270
+ const value = optionalString(record, key);
2271
+ if (value) {
2272
+ return value;
2273
+ }
2274
+ }
2275
+ return null;
2276
+ }
2277
+ function isStoryQaScope(value) {
2278
+ if (!value) {
2279
+ return false;
2280
+ }
2281
+ const normalized = value.trim().toLowerCase().replace(/[\s-]+/g, "_");
2282
+ return [
2283
+ "qa",
2284
+ "story_qa",
2285
+ "final_qa",
2286
+ "sign_off",
2287
+ "signoff",
2288
+ "story_sign_off",
2289
+ "story_verification",
2290
+ "story_validation"
2291
+ ].includes(normalized);
2292
+ }
2293
+ function architectTaskScopeText(task) {
2294
+ const parts = [];
2295
+ for (const key of ["id", "title", "summary", "phase", "phase_id"]) {
2296
+ appendOptionalString(parts, task, key);
2297
+ }
2298
+ for (const key of ["acceptance_criteria", "expected_paths", "touched_surfaces", "implementation_notes"]) {
2299
+ appendOptionalStringArray(parts, task, key);
2300
+ }
2301
+ const tests = task.tests;
2302
+ if (Array.isArray(tests)) {
2303
+ for (const test of tests) {
2304
+ if (!test || typeof test !== "object" || Array.isArray(test)) {
2305
+ continue;
2306
+ }
2307
+ const record = test;
2308
+ for (const key of ["id", "command", "purpose", "target", "expected"]) {
2309
+ appendOptionalString(parts, record, key);
2310
+ }
2311
+ appendOptionalStringArray(parts, record, "steps");
2312
+ }
2313
+ }
2314
+ return parts.join(" ");
2315
+ }
2316
+ function appendOptionalString(parts, record, key) {
2317
+ const value = optionalString(record, key);
2318
+ if (value) {
2319
+ parts.push(value);
2320
+ }
2321
+ }
2322
+ function appendOptionalStringArray(parts, record, key) {
2323
+ const value = record[key];
2324
+ if (!Array.isArray(value)) {
2325
+ return;
2326
+ }
2327
+ for (const entry of value) {
2328
+ if (typeof entry === "string" && entry.trim().length > 0) {
2329
+ parts.push(entry.trim());
2330
+ }
2331
+ }
2332
+ }
2333
+ function looksLikeStoryLevelVerificationTask(text) {
2334
+ if (!text.trim()) {
2335
+ return false;
2336
+ }
2337
+ const normalized = text.toLowerCase();
2338
+ const verificationWords = [
2339
+ "verify",
2340
+ "verification",
2341
+ "validate",
2342
+ "validation",
2343
+ "inspect",
2344
+ "audit",
2345
+ "check",
2346
+ "confirm",
2347
+ "prove",
2348
+ "evidence",
2349
+ "sign-off",
2350
+ "sign off"
2351
+ ];
2352
+ if (!verificationWords.some((word) => normalized.includes(word))) {
2353
+ return false;
2354
+ }
2355
+ return [
2356
+ "materialization",
2357
+ "materialized child",
2358
+ "child inventory",
2359
+ "child work-item",
2360
+ "child work item",
2361
+ "created task count",
2362
+ "created_task_count",
2363
+ "parent plan",
2364
+ "parent story",
2365
+ "story sign-off",
2366
+ "story sign off",
2367
+ ".forge/work-items",
2368
+ ".forge\\work-items",
2369
+ ".forge/stories",
2370
+ ".forge\\stories",
2371
+ "implementation.plan.json",
2372
+ "qa.plan.json",
2373
+ "architect plan artifact",
2374
+ "child spec"
2375
+ ].some((needle) => normalized.includes(needle));
2376
+ }
2377
+ function validateAndNormalizeArchitectDependencies(implementationPlan, taskIds) {
2378
+ const dependencies = implementationPlan.dependencies;
2379
+ const edges = new Map();
2380
+ for (const taskId of taskIds) {
2381
+ edges.set(taskId, []);
2382
+ }
2383
+ const normalizedDependencies = [];
2384
+ for (const [index, dependency] of dependencies.entries()) {
2385
+ if (!dependency || typeof dependency !== "object" || Array.isArray(dependency)) {
2386
+ throw new Error("implementation_plan.dependencies[]: expected object entries; correction: each dependency must be an object with before and after task ids.");
2387
+ }
2388
+ const record = dependency;
2389
+ const before = architectDependencyEndpoint(record, index, "before", "from");
2390
+ const after = architectDependencyEndpoint(record, index, "after", "to");
2391
+ if (!taskIds.has(before) || !taskIds.has(after)) {
2392
+ throw new Error("implementation_plan.dependencies: dependency references an unknown task id.");
2393
+ }
2394
+ const normalized = stripUndefined({
2395
+ ...record,
2396
+ before,
2397
+ after,
2398
+ from: undefined,
2399
+ to: undefined
2400
+ });
2401
+ normalizedDependencies.push(normalized);
2402
+ edges.get(before)?.push(after);
2403
+ }
2404
+ implementationPlan.dependencies = normalizedDependencies;
2405
+ if (hasArchitectDependencyCycle(edges)) {
2406
+ throw new Error("implementation_plan.dependencies: expected acyclic graph; correction: remove or revise cyclic task dependencies.");
2407
+ }
2408
+ }
2409
+ function architectDependencyEndpoint(dependency, index, canonicalKey, aliasKey) {
2410
+ const canonical = optionalString(dependency, canonicalKey);
2411
+ const alias = optionalString(dependency, aliasKey);
2412
+ if (canonical && alias && canonical !== alias) {
2413
+ throw new Error(`implementation_plan.dependencies[${index}].${canonicalKey}: conflicts with ${aliasKey}; correction: use one task id for ${canonicalKey}.`);
2414
+ }
2415
+ const value = canonical ?? alias;
2416
+ if (!value) {
2417
+ throw new Error(`implementation_plan.dependencies[${index}].${canonicalKey}: expected string; correction: use before and after task ids for each dependency.`);
2418
+ }
2419
+ return value;
2420
+ }
2421
+ function hasArchitectDependencyCycle(edges) {
2422
+ const visiting = new Set();
2423
+ const visited = new Set();
2424
+ const visit = (node) => {
2425
+ if (visited.has(node)) {
2426
+ return false;
2427
+ }
2428
+ if (visiting.has(node)) {
2429
+ return true;
2430
+ }
2431
+ visiting.add(node);
2432
+ for (const next of edges.get(node) ?? []) {
2433
+ if (visit(next)) {
2434
+ return true;
2435
+ }
2436
+ }
2437
+ visiting.delete(node);
2438
+ visited.add(node);
2439
+ return false;
2440
+ };
2441
+ for (const node of edges.keys()) {
2442
+ if (visit(node)) {
2443
+ return true;
2444
+ }
2445
+ }
2446
+ return false;
2447
+ }
2448
+ function requireArchitectNonPassEvidence(payload) {
2449
+ const evidenceKeys = ["blockers", "revision_questions", "revision_reasons", "known_gaps", "findings", "remaining_risks", "failures"];
2450
+ const hasEvidence = evidenceKeys.some((key) => {
2451
+ const value = payload[key];
2452
+ if (typeof value === "string") {
2453
+ return value.trim().length > 0;
2454
+ }
2455
+ if (Array.isArray(value)) {
2456
+ return value.length > 0;
2457
+ }
2458
+ return Boolean(value && typeof value === "object");
2459
+ });
2460
+ if (!hasEvidence) {
2461
+ throw new Error("status: non-pass Architect completion requires blockers, revision_questions, revision_reasons, findings, failures, or known_gaps; correction: explain why the plan cannot pass.");
2462
+ }
2463
+ }
2464
+ function requireArchitectArray(source, key, rootPayload, options = {}) {
2465
+ const pathLabel = options.path ?? `implementation_plan.${key}`;
2466
+ if (!Array.isArray(source[key])) {
2467
+ const nestedHint = architectNestedArrayHint(rootPayload, key);
2468
+ throw new Error(`${pathLabel}: expected array${key === "phases" ? " as a top-level field inside implementation_plan" : ""}; correction: ${nestedHint ?? `set ${pathLabel} to an array${options.allowEmpty ? " (use [] when none exist)" : " with at least one entry"}.`}`);
2469
+ }
2470
+ if (!options.allowEmpty && arrayLength(source, key) === 0) {
2471
+ throw new Error(`${pathLabel}: expected non-empty array; correction: include at least one entry.`);
2472
+ }
2473
+ }
2474
+ function architectNestedArrayHint(rootPayload, key) {
2475
+ if (Array.isArray(rootPayload[key])) {
2476
+ return `move top-level ${key} into implementation_plan.${key}.`;
2477
+ }
2478
+ const implementationPlan = rootPayload.implementation_plan;
2479
+ if (!implementationPlan || typeof implementationPlan !== "object" || Array.isArray(implementationPlan)) {
2480
+ return null;
2481
+ }
2482
+ const plan = implementationPlan;
2483
+ for (const container of ["plan", "dag", "implementation_dag", "implementationPlan", "implementation_plan"]) {
2484
+ const nested = plan[container];
2485
+ if (nested && typeof nested === "object" && !Array.isArray(nested) && Array.isArray(nested[key])) {
2486
+ return `move implementation_plan.${container}.${key} to implementation_plan.${key}.`;
2487
+ }
2488
+ }
2489
+ return null;
2490
+ }
2491
+ function validateQaPayloadShape(payload, status) {
2492
+ const evidenceSource = qaEvidenceSource(payload);
2493
+ const commands = qaArray(payload, "commands", evidenceSource);
2494
+ const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
2495
+ const sidecars = qaArray(payload, "sidecars", evidenceSource);
2496
+ const notes = optionalString(payload, "notes") ?? optionalString(evidenceSource, "notes") ?? "";
2497
+ const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
2498
+ const findings = qaObjectArray(payload, "findings");
2499
+ const candidateBugs = qaObjectArray(payload, "candidate_bugs");
2500
+ const explicitFindingIds = qaStringArray(payload, "finding_ids");
2501
+ const explicitCandidateBugIds = qaStringArray(payload, "candidate_bug_ids");
2502
+ if (payload.schema_version !== undefined && payload.schema_version !== 1) {
2503
+ throw new Error("QA schema_version must be numeric 1 when provided.");
2504
+ }
2505
+ if (status === "pass" || status === "needs_rework") {
2506
+ if (testedAcceptanceCriteria.length === 0) {
2507
+ throw new Error("QA pass/needs_rework requires tested_acceptance_criteria with at least one criterion.");
2508
+ }
2509
+ if (commands.length === 0 && browserChecks.length === 0 && notes.length === 0) {
2510
+ throw new Error("QA pass/needs_rework requires at least one command, browser check, or evidence note.");
2511
+ }
2512
+ }
2513
+ for (const [index, command] of commands.entries()) {
2514
+ requireEvidenceRecord(command, `commands[${index}]`);
2515
+ const record = command;
2516
+ requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
2517
+ requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
2518
+ requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
2519
+ if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
2520
+ throw new Error(`commands[${index}].exit_code is required.`);
2521
+ }
2522
+ if (status === "pass" && record.exit_code !== 0) {
2523
+ throw new Error(`commands[${index}].exit_code must be 0 when QA status is pass.`);
2524
+ }
2525
+ if (status === "pass" && normalizedString(record.status) !== "pass") {
2526
+ throw new Error(`commands[${index}].status must be pass when QA status is pass.`);
2527
+ }
2528
+ }
2529
+ for (const [index, browserCheck] of browserChecks.entries()) {
2530
+ requireEvidenceRecord(browserCheck, `browser_checks[${index}]`);
2531
+ const record = browserCheck;
2532
+ requireNonEmptyStringRecord(record, "summary", `browser_checks[${index}].`);
2533
+ requireNonEmptyStringRecord(record, "status", `browser_checks[${index}].`);
2534
+ const checkStatus = optionalString(record, "status");
2535
+ if (status === "pass" && checkStatus && normalizedString(checkStatus) !== "pass") {
2536
+ throw new Error(`browser_checks[${index}].status must be pass when QA status is pass.`);
2537
+ }
2538
+ if (!optionalString(record, "url") && !optionalString(record, "route")) {
2539
+ throw new Error(`browser_checks[${index}] must include url or route.`);
2540
+ }
2541
+ }
2542
+ for (const [index, sidecar] of sidecars.entries()) {
2543
+ requireEvidenceRecord(sidecar, `sidecars[${index}]`);
2544
+ const record = sidecar;
2545
+ requireNonEmptyStringRecord(record, "path", `sidecars[${index}].`);
2546
+ requireNonEmptyStringRecord(record, "content_hash", `sidecars[${index}].`);
2547
+ if (typeof record.bytes !== "number" || !Number.isFinite(record.bytes) || record.bytes <= 0) {
2548
+ throw new Error(`sidecars[${index}].bytes must be greater than 0.`);
2549
+ }
2550
+ }
2551
+ for (const [index, finding] of findings.entries()) {
2552
+ requireNonEmptyStringRecord(finding, "id", `findings[${index}].`);
2553
+ requireNonEmptyStringRecord(finding, "title", `findings[${index}].`);
2554
+ requireKnownStringRecord(finding, "severity", qaFindingSeverities, `findings[${index}].`);
2555
+ requireKnownStringRecord(finding, "scope", qaFindingScopes, `findings[${index}].`);
2556
+ if (normalizedString(finding.scope) === "in_scope") {
2557
+ validateActionableQaFinding(finding, index);
2558
+ }
2559
+ }
2560
+ for (const [index, candidateBug] of candidateBugs.entries()) {
2561
+ requireNonEmptyStringRecord(candidateBug, "id", `candidate_bugs[${index}].`);
2562
+ requireNonEmptyStringRecord(candidateBug, "title", `candidate_bugs[${index}].`);
2563
+ requireKnownStringRecord(candidateBug, "suggested_action", qaCandidateBugActions, `candidate_bugs[${index}].`);
2564
+ }
2565
+ const inScopeFindingIds = findings
2566
+ .filter((finding) => normalizedString(finding.scope) === "in_scope")
2567
+ .map((finding) => optionalString(finding, "id"))
2568
+ .filter((id) => Boolean(id));
2569
+ for (const findingId of explicitFindingIds) {
2570
+ if (!inScopeFindingIds.includes(findingId)) {
2571
+ throw new Error(`QA finding_ids contains '${findingId}', but findings has no matching in-scope finding.`);
2572
+ }
2573
+ }
2574
+ const candidateBugIds = candidateBugs
2575
+ .map((candidateBug) => optionalString(candidateBug, "id"))
2576
+ .filter((id) => Boolean(id));
2577
+ for (const candidateBugId of explicitCandidateBugIds) {
2578
+ if (!candidateBugIds.includes(candidateBugId)) {
2579
+ throw new Error(`QA candidate_bug_ids contains '${candidateBugId}', but candidate_bugs has no matching candidate bug.`);
2580
+ }
2581
+ }
2582
+ if (status === "pass") {
2583
+ if (explicitFindingIds.length > 0 || inScopeFindingIds.length > 0) {
2584
+ throw new Error("QA pass must not include in-scope finding_ids or in-scope findings.");
2585
+ }
2586
+ if (optionalString(payload, "blocker_reason")) {
2587
+ throw new Error("QA pass must not include blocker_reason.");
2588
+ }
2589
+ }
2590
+ if (status === "needs_rework") {
2591
+ if (inScopeFindingIds.length === 0) {
2592
+ throw new Error("QA needs_rework requires at least one actionable in-scope finding.");
2593
+ }
2594
+ if (optionalString(payload, "blocker_reason")) {
2595
+ throw new Error("QA needs_rework must not include blocker_reason.");
2596
+ }
2597
+ }
2598
+ if (status === "blocked") {
2599
+ const reason = normalizedString(optionalString(payload, "blocker_reason"));
2600
+ if (!qaBlockerReasons.has(reason)) {
2601
+ throw new Error("QA blocked requires blocker_reason to be one of missing_app_launch_target, inconclusive, environment_failure, missing_validation_evidence, missing_worktree, or runner_failure.");
2602
+ }
2603
+ }
2604
+ }
2605
+ function validateActionableQaFinding(finding, index) {
2606
+ const prefix = `findings[${index}].`;
2607
+ requireNonEmptyStringArrayRecord(finding, "acceptance_criteria", prefix);
2608
+ requireNonEmptyStringArrayRecord(finding, "repro_steps", prefix);
2609
+ requireNonEmptyStringRecord(finding, "expected", prefix);
2610
+ requireNonEmptyStringRecord(finding, "actual", prefix);
2611
+ requireSubstantiveEvidenceRecord(finding, prefix);
2612
+ requireNonEmptyStringArrayRecord(finding, "likely_area", prefix);
2613
+ requireNonEmptyStringRecord(finding, "required_fix", prefix);
2614
+ requireNonEmptyStringRecord(finding, "required_regression", prefix);
2615
+ }
725
2616
  function validateOptionalWorkItemId(payload, expectedWorkItemId) {
726
2617
  const actual = optionalString(payload, "work_item_id") ?? optionalString(payload, "workItemId");
727
2618
  if (actual && actual !== expectedWorkItemId) {
@@ -736,10 +2627,36 @@ function normalizeArtifactPayload(payload, defaults) {
736
2627
  normalized.schema_version = numberOrDefault(normalized.schema_version, 1);
737
2628
  normalized.phase = defaults.phase;
738
2629
  normalized.work_item_id = defaults.workItemId;
2630
+ const ownerFields = artifactOwnerFields(defaults);
2631
+ Object.assign(normalized, ownerFields);
739
2632
  normalized.status = defaults.status;
740
2633
  normalized.produced_by = defaults.producedBy;
741
2634
  return normalized;
742
2635
  }
2636
+ function normalizeQaGateArtifactPayload(payload, defaults) {
2637
+ const normalized = stripUndefined({ ...payload });
2638
+ delete normalized.report_markdown;
2639
+ delete normalized.content_hash;
2640
+ delete normalized.contentHash;
2641
+ normalized.schema_version = numberOrDefault(normalized.schema_version, 1);
2642
+ normalized.phase = "qa";
2643
+ normalized.gate = defaults.gate;
2644
+ normalized.work_item_id = defaults.workItemId;
2645
+ const ownerFields = artifactOwnerFields(defaults);
2646
+ Object.assign(normalized, ownerFields);
2647
+ normalized.status = defaults.status;
2648
+ normalized.produced_by = defaults.producedBy;
2649
+ if (defaults.gate === "qa_plan") {
2650
+ const checklist = qaStringArray(normalized, "checklist");
2651
+ normalized.checklist = checklist.length > 0 ? checklist : defaultQaChecklist(defaults.status);
2652
+ normalized.acceptance_criteria = qaStringArray(normalized, "acceptance_criteria");
2653
+ }
2654
+ if (defaults.gate === "qa_findings") {
2655
+ normalized.findings = qaObjectArray(normalized, "findings");
2656
+ normalized.candidate_bugs = qaObjectArray(normalized, "candidate_bugs");
2657
+ }
2658
+ return normalized;
2659
+ }
743
2660
  function reportMarkdown(payload, phase, status, producedBy, contentHash) {
744
2661
  const explicit = optionalString(payload, "report_markdown");
745
2662
  if (explicit) {
@@ -759,6 +2676,10 @@ ${summary}
759
2676
  }
760
2677
  function parseStrictCompletionPhase(value) {
761
2678
  const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
2679
+ const debugPhase = normalizeDebugCompletionPhase(normalized);
2680
+ if (debugPhase) {
2681
+ return debugPhase;
2682
+ }
762
2683
  if (normalized === "implementation" || normalized === "implement" || normalized === "develop") {
763
2684
  return "implementation";
764
2685
  }
@@ -768,8 +2689,54 @@ function parseStrictCompletionPhase(value) {
768
2689
  if (normalized === "validate" || normalized === "validation") {
769
2690
  return "validation";
770
2691
  }
2692
+ if (normalized === "qa" || normalized === "quality_assurance" || normalized === "qualityassurance") {
2693
+ return "qa";
2694
+ }
2695
+ if (normalized === "architect" || normalized === "architect_plan" || normalized === "planning" || normalized === "plan") {
2696
+ return "architect";
2697
+ }
2698
+ if (normalized === "draft" || normalized === "drafting" || normalized === "draft_work_order") {
2699
+ return "draft";
2700
+ }
771
2701
  return null;
772
2702
  }
2703
+ function normalizeDebugCompletionPhase(value) {
2704
+ const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
2705
+ switch (normalized) {
2706
+ case "debug_repro":
2707
+ case "debugrepro":
2708
+ case "repro":
2709
+ case "reproduce":
2710
+ return "debug_repro";
2711
+ case "debug_root_cause":
2712
+ case "debugrootcause":
2713
+ case "root_cause":
2714
+ case "rootcause":
2715
+ return "debug_root_cause";
2716
+ case "debug_fix":
2717
+ case "debugfix":
2718
+ case "fix":
2719
+ return "debug_fix";
2720
+ case "debug_regression":
2721
+ case "debugregression":
2722
+ case "regression":
2723
+ return "debug_regression";
2724
+ default:
2725
+ return null;
2726
+ }
2727
+ }
2728
+ function isDevelopCompletionPhase(phase) {
2729
+ return phase === "implementation" || phase === "self_review" || phase === "validation";
2730
+ }
2731
+ function isDebugCompletionPhase(phase) {
2732
+ return debugCompletionPhaseOrder.includes(phase);
2733
+ }
2734
+ function asDebugCompletionPhase(phase) {
2735
+ if (isDebugCompletionPhase(phase)) {
2736
+ return phase;
2737
+ }
2738
+ throw new Error(`Expected Debug completion phase, got ${phase}.`);
2739
+ }
773
2740
  function parseCompletionRedactionSecrets(raw) {
774
2741
  if (!raw?.trim()) {
775
2742
  return [];
@@ -796,8 +2763,54 @@ function phaseFromToolName(toolName) {
796
2763
  if (normalized === "forge.complete_validation" || normalized === "complete_validation") {
797
2764
  return "validation";
798
2765
  }
2766
+ if (normalized === "forge.complete_qa" || normalized === "complete_qa") {
2767
+ return "qa";
2768
+ }
2769
+ if (normalized === "forge.complete_architect_plan" || normalized === "complete_architect_plan") {
2770
+ return "architect";
2771
+ }
2772
+ if (draftGateFromToolName(toolName)) {
2773
+ return "draft";
2774
+ }
2775
+ const debugGate = debugGateFromToolName(toolName);
2776
+ if (debugGate) {
2777
+ return debugGate;
2778
+ }
2779
+ if (qaGateFromToolName(toolName)) {
2780
+ return "qa";
2781
+ }
799
2782
  throw new Error(`Unknown Forge completion tool: ${toolName}`);
800
2783
  }
2784
+ function draftGateFromToolName(toolName) {
2785
+ const normalized = toolName.trim().toLowerCase();
2786
+ for (const gate of draftCompletionGateOrder) {
2787
+ const base = draftGateToolNames[gate];
2788
+ if (normalized === `forge.${base}` || normalized === base) {
2789
+ return gate;
2790
+ }
2791
+ }
2792
+ return null;
2793
+ }
2794
+ function debugGateFromToolName(toolName) {
2795
+ const normalized = toolName.trim().toLowerCase();
2796
+ for (const gate of debugCompletionPhaseOrder) {
2797
+ const base = debugGateToolNames[gate];
2798
+ if (normalized === `forge.${base}` || normalized === base) {
2799
+ return gate;
2800
+ }
2801
+ }
2802
+ return null;
2803
+ }
2804
+ function qaGateFromToolName(toolName) {
2805
+ const normalized = toolName.trim().toLowerCase();
2806
+ for (const gate of qaCompletionGateOrder) {
2807
+ const base = qaGateToolNames[gate];
2808
+ if (normalized === `forge.${base}` || normalized === base) {
2809
+ return gate;
2810
+ }
2811
+ }
2812
+ return null;
2813
+ }
801
2814
  function requireField(payload, key) {
802
2815
  if (payload[key] === undefined || payload[key] === null || (typeof payload[key] === "string" && payload[key].trim().length === 0)) {
803
2816
  throw new Error(`${key} is required.`);
@@ -865,17 +2878,42 @@ function requireArray(payload, key) {
865
2878
  throw new Error(`${key} must be an array.`);
866
2879
  }
867
2880
  }
2881
+ function requireNonEmptyArray(payload, key) {
2882
+ requireArray(payload, key);
2883
+ if (arrayLength(payload, key) === 0) {
2884
+ throw new Error(`${key} must include at least one value.`);
2885
+ }
2886
+ }
2887
+ function arrayLength(payload, key) {
2888
+ const value = payload[key];
2889
+ return Array.isArray(value) ? value.length : 0;
2890
+ }
2891
+ function requireAllowedStatus(payload, key, allowed) {
2892
+ const value = normalizedString(optionalString(payload, key));
2893
+ if (!allowed.includes(value)) {
2894
+ throw new Error(`${key} must be one of ${allowed.join(", ")}.`);
2895
+ }
2896
+ }
868
2897
  function requireObject(payload, key) {
869
2898
  const value = payload[key];
870
2899
  if (!value || typeof value !== "object" || Array.isArray(value)) {
871
2900
  throw new Error(`${key} must be an object.`);
872
2901
  }
873
2902
  }
2903
+ function requiredRecord(payload, key) {
2904
+ requireObject(payload, key);
2905
+ return payload[key];
2906
+ }
874
2907
  function requireBoolean(payload, key) {
875
2908
  if (typeof payload[key] !== "boolean") {
876
2909
  throw new Error(`${key} must be a boolean.`);
877
2910
  }
878
2911
  }
2912
+ function requireNumericOne(payload, key, pathLabel) {
2913
+ if (payload[key] !== 1) {
2914
+ throw new Error(`${pathLabel}: expected numeric 1; correction: set ${pathLabel} to 1.`);
2915
+ }
2916
+ }
879
2917
  function requireSatisfiedAcceptanceCriteria(payload) {
880
2918
  const criteria = payload.acceptance_criteria;
881
2919
  if (!Array.isArray(criteria)) {
@@ -893,6 +2931,183 @@ function requireSatisfiedAcceptanceCriteria(payload) {
893
2931
  }
894
2932
  }
895
2933
  }
2934
+ function validateResolvedFindings(payload) {
2935
+ const resolvedFindings = payload.resolved_findings;
2936
+ if (resolvedFindings === undefined || resolvedFindings === null) {
2937
+ return;
2938
+ }
2939
+ if (!Array.isArray(resolvedFindings)) {
2940
+ throw new Error("resolved_findings must be an array.");
2941
+ }
2942
+ for (const [index, finding] of resolvedFindings.entries()) {
2943
+ const prefix = `resolved_findings[${index}].`;
2944
+ if (!finding || typeof finding !== "object" || Array.isArray(finding)) {
2945
+ throw new Error(`resolved_findings[${index}] must be an object.`);
2946
+ }
2947
+ const record = finding;
2948
+ requireNonEmptyStringRecord(record, "qa_id", prefix);
2949
+ requireKnownStringRecord(record, "status", resolvedFindingStatuses, prefix);
2950
+ requireNonEmptyStringRecord(record, "summary", prefix);
2951
+ requireSubstantiveValueRecord(record, "evidence", prefix);
2952
+ requireArrayRecord(record, "changed_files", prefix);
2953
+ requireArrayRecord(record, "tests_added_or_updated", prefix);
2954
+ requireSubstantiveValueRecord(record, "regression_evidence", prefix);
2955
+ if (normalizedString(record.status) === "resolved") {
2956
+ if (record.changed_files.length === 0) {
2957
+ throw new Error(`${prefix}changed_files must include at least one changed file for resolved QA findings.`);
2958
+ }
2959
+ if (record.tests_added_or_updated.length === 0) {
2960
+ throw new Error(`${prefix}tests_added_or_updated must include at least one regression test for resolved QA findings.`);
2961
+ }
2962
+ }
2963
+ }
2964
+ }
2965
+ function qaEvidenceSource(payload) {
2966
+ const evidence = payload.evidence;
2967
+ return evidence && typeof evidence === "object" && !Array.isArray(evidence)
2968
+ ? evidence
2969
+ : {};
2970
+ }
2971
+ function qaArray(payload, key, fallback = {}) {
2972
+ const value = payload[key] ?? fallback[key];
2973
+ if (value === undefined || value === null) {
2974
+ return [];
2975
+ }
2976
+ if (!Array.isArray(value)) {
2977
+ throw new Error(`${key} must be an array.`);
2978
+ }
2979
+ return value;
2980
+ }
2981
+ function qaObjectArray(payload, key) {
2982
+ return qaArray(payload, key).map((entry, index) => {
2983
+ if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
2984
+ throw new Error(`${key}[${index}] must be an object.`);
2985
+ }
2986
+ return entry;
2987
+ });
2988
+ }
2989
+ function qaStringArray(payload, key) {
2990
+ const value = payload[key];
2991
+ if (value === undefined || value === null) {
2992
+ return [];
2993
+ }
2994
+ if (!Array.isArray(value)) {
2995
+ throw new Error(`${key} must be an array.`);
2996
+ }
2997
+ return value.map((entry, index) => {
2998
+ if (typeof entry !== "string" || entry.trim().length === 0) {
2999
+ throw new Error(`${key}[${index}] must be a non-empty string.`);
3000
+ }
3001
+ return entry;
3002
+ });
3003
+ }
3004
+ function requireEvidenceRecord(value, label) {
3005
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
3006
+ throw new Error(`${label} must be an object.`);
3007
+ }
3008
+ }
3009
+ function requireNonEmptyStringRecord(source, key, prefix = "") {
3010
+ if (!optionalString(source, key)) {
3011
+ throw new Error(`${prefix}${key} is required.`);
3012
+ }
3013
+ }
3014
+ function requireArrayRecord(source, key, prefix = "") {
3015
+ if (!Array.isArray(source[key])) {
3016
+ throw new Error(`${prefix}${key} must be an array.`);
3017
+ }
3018
+ }
3019
+ function requireKnownStringRecord(source, key, allowed, prefix = "") {
3020
+ const value = normalizedString(optionalString(source, key));
3021
+ if (!allowed.has(value)) {
3022
+ throw new Error(`${prefix}${key} must be one of ${[...allowed].sort().join(", ")}.`);
3023
+ }
3024
+ }
3025
+ function requireNonEmptyStringArrayRecord(source, key, prefix = "") {
3026
+ const value = source[key];
3027
+ if (!Array.isArray(value) || value.length === 0) {
3028
+ throw new Error(`${prefix}${key} must include at least one value.`);
3029
+ }
3030
+ for (const [index, entry] of value.entries()) {
3031
+ if (typeof entry !== "string" || entry.trim().length === 0) {
3032
+ throw new Error(`${prefix}${key}[${index}] must be a non-empty string.`);
3033
+ }
3034
+ }
3035
+ }
3036
+ function requireSubstantiveValueRecord(source, key, prefix = "") {
3037
+ if (!hasSubstantiveJsonValue(source[key])) {
3038
+ throw new Error(`${prefix}${key} must include at least one concrete evidence reference or summary.`);
3039
+ }
3040
+ }
3041
+ function requireSubstantiveEvidenceRecord(source, prefix = "") {
3042
+ const evidence = source.evidence;
3043
+ if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) {
3044
+ throw new Error(`${prefix}evidence must be an object.`);
3045
+ }
3046
+ if (!Object.values(evidence).some(hasSubstantiveJsonValue)) {
3047
+ throw new Error(`${prefix}evidence must include at least one concrete evidence reference or summary.`);
3048
+ }
3049
+ }
3050
+ function hasSubstantiveJsonValue(value) {
3051
+ if (typeof value === "string") {
3052
+ return value.trim().length > 0;
3053
+ }
3054
+ if (Array.isArray(value)) {
3055
+ return value.length > 0;
3056
+ }
3057
+ if (value && typeof value === "object") {
3058
+ return Object.keys(value).length > 0;
3059
+ }
3060
+ return false;
3061
+ }
3062
+ function normalizedString(value) {
3063
+ return typeof value === "string" ? value.trim().toLowerCase().replace(/-/g, "_") : "";
3064
+ }
3065
+ function normalizedOwnerType(value) {
3066
+ const normalized = normalizedString(value);
3067
+ return normalized === "work_item" || normalized === "story" ? normalized : undefined;
3068
+ }
3069
+ function artifactOwnerFields(config) {
3070
+ const ownerType = normalizedOwnerType(config.ownerType);
3071
+ const ownerId = config.ownerId?.trim();
3072
+ if (!ownerType && !ownerId) {
3073
+ return {};
3074
+ }
3075
+ return {
3076
+ owner_type: ownerType ?? "work_item",
3077
+ owner_id: ownerId || config.workItemId
3078
+ };
3079
+ }
3080
+ function artifactReferenceOwnerFields(config) {
3081
+ const owner = artifactOwnerFields(config);
3082
+ return owner.owner_type && owner.owner_id
3083
+ ? { ownerType: owner.owner_type, ownerId: owner.owner_id }
3084
+ : {};
3085
+ }
3086
+ function artifactOwnerDirectory(ownerType) {
3087
+ return normalizedOwnerType(ownerType) === "story" ? "stories" : "work-items";
3088
+ }
3089
+ function artifactOwnerRelativeRoot(ownerType, ownerId, workItemId) {
3090
+ const owner = artifactOwnerFields({ workItemId, ownerType, ownerId });
3091
+ return owner.owner_type && owner.owner_id
3092
+ ? [".forge", artifactOwnerDirectory(owner.owner_type), owner.owner_id, "artifacts"].join("/")
3093
+ : [".forge", "work-items", workItemId, "artifacts"].join("/");
3094
+ }
3095
+ function defaultQaChecklist(status) {
3096
+ return [
3097
+ "Review the validated work item against acceptance criteria.",
3098
+ "Inspect implementation, self-review, and validation evidence when available.",
3099
+ status === "blocked" ? "Record the blocker reason preventing a conclusive QA verdict." : "Record concrete QA evidence and findings."
3100
+ ];
3101
+ }
3102
+ function qaArtifactRelativePath(workItemId, fileName) {
3103
+ return [".forge", "work-items", workItemId, "artifacts", fileName].join("/");
3104
+ }
3105
+ function qaArtifactRelativePathForOwner(ownerType, ownerId, fileName) {
3106
+ return [".forge", artifactOwnerDirectory(ownerType), ownerId, "artifacts", fileName].join("/");
3107
+ }
3108
+ function jsonText(value) {
3109
+ return `${JSON.stringify(value, null, 2)}\n`;
3110
+ }
896
3111
  function fallbackReport(parsed, phase, artifactPath) {
897
3112
  return `# Forge ${phase.replace(/_/g, " ")} completion
898
3113
 
@@ -905,7 +3120,7 @@ function parseJsonObject(content, label) {
905
3120
  return asRecord(JSON.parse(content), label);
906
3121
  }
907
3122
  catch (error) {
908
- throw new Error(`${label} is not valid JSON: ${errorMessage(error)}`);
3123
+ throw new Error(`${label} is not valid JSON: ${errorMessage(error)}`, { cause: error });
909
3124
  }
910
3125
  }
911
3126
  function parseOptionalJsonObject(content, label) {