@loucompanion/forge-bridge 0.1.1-dev.718bdb0018b9 → 0.1.1-dev.895607f4402a

package/dist/session/provider-cli/provider-cli.service.js

@@ -8,7 +8,7 @@ import { GitClient } from "../../shared/git/git.js";
 import { resolveCursorAgentDirectLaunch } from "../../shared/cursor-agent/cursor-agent.launch.js";
 import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "../qa-sidecar-validation.js";
 import { buildSpecBody, selectLaneCommand } from "../../worktree/artifact-injector.js";
-import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDevelopCycle, completionPromptForPhase, completionRedactionEnv, expectedCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDevelopCycleCompletion, writeCompletionArtifact, artifactRootFor } from "../phase-completion.js";
+import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDebugCycle, completionPromptForDevelopCycle, completionPromptForPhase, completionPromptForQaCycle, completionRedactionEnv, expectedCompletionToolName, expectedDebugCompletionToolName, expectedQaCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDebugCycleCompletion, usesDevelopCycleCompletion, writeCompletionArtifact, artifactRootFor, debugCompletionPhaseOrder, qaCompletionGateOrder } from "../phase-completion.js";
 import { addUsage, buildProviderUsageEvent, emptyUsage, hasUsage, readUsageNumber } from "./provider-usage.js";
 const fakeWorkerModel = "server-local-fake-worker";
 const execFileAsync = promisify(execFile);
@@ -47,6 +47,7 @@ export class ProcessBackedProviderCliService {
         const { dispatch, worktree } = context;
         const phase = completionPhaseFromDispatch(dispatch);
         const developCycle = usesDevelopCycleCompletion(dispatch);
+        const debugCycle = usesDebugCycleCompletion(dispatch);
         const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
         await fs.mkdir(metadataRoot, { recursive: true });
         const laneCommand = selectLaneCommand(dispatch.artifacts, dispatch.execution.lane, dispatch.cycleRun.phase);
@@ -60,7 +61,11 @@ export class ProcessBackedProviderCliService {
         const completionTools = await prepareCompletionToolRuntime({ dispatch, worktree, phase });
         const command = buildProviderCliCommand(dispatch, {
             worktreePath: worktree.worktreePath,
-            prompt: developCycle ? buildDevelopCyclePrompt(dispatch, phase) : buildImplementationPrompt(dispatch, phase),
+            prompt: debugCycle
+                ? buildDebugCyclePrompt(dispatch, phase)
+                : developCycle
+                    ? buildDevelopCyclePrompt(dispatch, phase)
+                    : buildImplementationPrompt(dispatch, phase),
             completionTools
         });
         await context.emit({
@@ -72,13 +77,15 @@ export class ProcessBackedProviderCliService {
         await context.emit({
             role: "runner",
             kind: "checkpoint",
-            content: developCycle
-                ? "Forge completion tools configured for implementation -> self_review -> validation; provider must call each MCP completion tool before exit."
-                : `Forge completion tools configured for ${phase}; provider must call the MCP completion tool before exit.`,
+            content: debugCycle
+                ? "Forge Debug completion tools configured for debug_repro -> debug_root_cause -> debug_fix -> debug_regression; provider must call each MCP completion tool before exit."
+                : developCycle
+                    ? "Forge completion tools configured for implementation -> self_review -> validation; provider must call each MCP completion tool before exit."
+                    : `Forge completion tools configured for ${phase}; provider must call the MCP completion tool before exit.`,
             eventType: "completion_tools_configured"
         });
         const outputState = createProviderOutputState(dispatch.execution.provider);
-        const liveCompletionEvents = new LiveCompletionArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, phase, developCycle, context.emit);
+        const liveCompletionEvents = new LiveCompletionArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, phase, developCycle, debugCycle, context.emit);
         let result;
         try {
             liveCompletionEvents.start();
@@ -112,7 +119,7 @@ export class ProcessBackedProviderCliService {
         });
         await emitProviderUsageEvent(context.emit, dispatch, outputState);
         const committed = await commitWorktreeChanges(this.git, worktree.worktreePath, dispatch.workItem.id);
-        const completionArtifacts = await readCompletionArtifactsForRun(worktree.worktreePath, dispatch.workItem.id, phase, developCycle);
+        const completionArtifacts = await readCompletionArtifactsForRun(worktree.worktreePath, dispatch.workItem.id, phase, developCycle, debugCycle);
         for (const artifact of completionArtifacts) {
             if (!liveCompletionEvents.hasEmitted(completionPhaseFromArtifact(artifact))) {
                 await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, artifact);
@@ -138,7 +145,7 @@ export class ProcessBackedProviderCliService {
             });
         }
         return {
-            summary: `${dispatch.execution.provider} CLI completed ${worktree.branchName} (${developCycle ? "develop cycle" : phase}, ${committed.commitSha.slice(0, 12)}).`,
+            summary: `${dispatch.execution.provider} CLI completed ${worktree.branchName} (${debugCycle ? "debug cycle" : developCycle ? "develop cycle" : phase}, ${committed.commitSha.slice(0, 12)}).`,
             spec: {
                 repoPath: worktree.worktreePath,
                 path: specPath,
@@ -152,10 +159,20 @@ export class ProcessBackedProviderCliService {
     }
     async runQa(context) {
         const { dispatch, worktree } = context;
+        const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
+        await fs.mkdir(metadataRoot, { recursive: true });
+        const laneCommand = selectLaneCommand(dispatch.artifacts, dispatch.execution.lane, dispatch.cycleRun.phase);
+        if (!laneCommand) {
+            throw new Error(`Lane command for lane '${dispatch.execution.lane}' phase '${dispatch.cycleRun.phase}' was not resolved.`);
+        }
+        const specBody = buildSpecBody(laneCommand, dispatch.workItem, "qa");
+        const specPath = path.join(metadataRoot, "spec.md");
+        await fs.writeFile(specPath, specBody, "utf8");
+        await fs.writeFile(path.join(metadataRoot, "spec.meta.json"), JSON.stringify({ schema_version: 1, status: "approved", produced_by: "forge-lane-command" }) + "\n", "utf8");
         const completionTools = await prepareCompletionToolRuntime({ dispatch, worktree, phase: "qa" });
         const command = buildProviderCliCommand(dispatch, {
             worktreePath: worktree.worktreePath,
-            prompt: buildQaPrompt(dispatch),
+            prompt: buildQaPrompt(dispatch, specBody),
             completionTools
         });
         const commandText = formatProviderCliCommand(command);
@@ -168,7 +185,7 @@ export class ProcessBackedProviderCliService {
         await context.emit({
             role: "runner",
             kind: "checkpoint",
-            content: "Forge QA completion tool configured; provider must call forge.complete_qa before exit.",
+            content: "Forge QA completion tools configured; provider must call all seven QA MCP gates before exit.",
             eventType: "completion_tools_configured"
         });
         const outputState = createProviderOutputState(dispatch.execution.provider);
@@ -225,20 +242,30 @@ export class ProcessBackedProviderCliService {
                 : "found rework";
         return {
             summary: `${dispatch.execution.provider} CLI QA ${statusSummary}.`,
+            spec: {
+                repoPath: worktree.worktreePath,
+                path: specPath,
+                body: specBody,
+                producedBy: "forge-lane-command",
+                status: "approved"
+            },
             artifact: qaArtifact,
             artifacts: [qaArtifact]
         };
     }
     async runConflictResolve(context) {
         const { dispatch, worktree } = context;
+        const addressComments = isPullRequestCommentsDispatch(dispatch);
         const command = buildProviderCliCommand(dispatch, {
             worktreePath: worktree.worktreePath,
-            prompt: buildConflictResolvePrompt(dispatch, worktree.branchName)
+            prompt: addressComments
+                ? buildPullRequestCommentsPrompt(dispatch, worktree.branchName)
+                : buildConflictResolvePrompt(dispatch, worktree.branchName)
         });
         await context.emit({
             role: "runner",
             kind: "checkpoint",
-            content: `Starting provider CLI conflict resolve: ${formatProviderCliCommand(command)} in ${worktree.worktreePath}`,
+            content: `Starting provider CLI ${addressComments ? "PR comment address" : "conflict resolve"}: ${formatProviderCliCommand(command)} in ${worktree.worktreePath}`,
             eventType: "provider_cli_started"
         });
         const outputState = createProviderOutputState(dispatch.execution.provider);
@@ -264,11 +291,15 @@ export class ProcessBackedProviderCliService {
         await context.emit({
             role: "assistant",
             kind: "message",
-            content: outputState.finalMessage || `${dispatch.execution.provider} CLI resolved merge conflicts for ${worktree.branchName}.`,
-            eventType: "conflict_resolve_complete"
+            content: outputState.finalMessage || (addressComments
+                ? `${dispatch.execution.provider} CLI addressed pull request comments for ${worktree.branchName}.`
+                : `${dispatch.execution.provider} CLI resolved merge conflicts for ${worktree.branchName}.`),
+            eventType: addressComments ? "pr_comments_complete" : "conflict_resolve_complete"
         });
         return {
-            summary: `${dispatch.execution.provider} CLI resolved conflicts on ${worktree.branchName} (${committed.commitSha.slice(0, 12)}).`
+            summary: addressComments
+                ? `${dispatch.execution.provider} CLI addressed PR comments on ${worktree.branchName} (${committed.commitSha.slice(0, 12)}).`
+                : `${dispatch.execution.provider} CLI resolved conflicts on ${worktree.branchName} (${committed.commitSha.slice(0, 12)}).`
         };
     }
 }
@@ -281,6 +312,7 @@ export class DeterministicProviderCliService {
         const { dispatch, worktree } = context;
         const phase = completionPhaseFromDispatch(dispatch);
         const developCycle = usesDevelopCycleCompletion(dispatch);
+        const debugCycle = usesDebugCycleCompletion(dispatch);
         const providerCommand = buildProviderCliCommand(dispatch);
         const providerCommandText = formatProviderCliCommand(providerCommand);
         const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
@@ -311,9 +343,11 @@ export class DeterministicProviderCliService {
             content: `Created bridge changeset at ${changesetPath}`,
             eventType: "changeset"
         });
-        const phases = developCycle
-            ? ["implementation", "self_review", "validation"]
-            : [phase];
+        const phases = debugCycle
+            ? debugCompletionPhaseOrder
+            : developCycle
+                ? ["implementation", "self_review", "validation"]
+                : [phase];
         const completionArtifacts = [];
         for (const completionPhase of phases) {
             await writeCompletionArtifact({
@@ -322,7 +356,9 @@ export class DeterministicProviderCliService {
                 phase: completionPhase,
                 producedBy: "forge-bridge",
                 redactionSecrets: exactRedactionSecrets(dispatch)
-            }, expectedCompletionToolName(completionPhase), deterministicCompletionPayload(completionPhase, dispatch, changesetBody));
+            }, isDebugCompletionPhaseForProvider(completionPhase)
+                ? expectedDebugCompletionToolName(completionPhase)
+                : expectedCompletionToolName(completionPhase), deterministicCompletionPayload(completionPhase, dispatch, changesetBody));
             const completionArtifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, completionPhase);
             if (!completionArtifact) {
                 throw new Error(`Deterministic provider did not produce the Forge ${completionPhase} completion artifact.`);
@@ -338,7 +374,7 @@ export class DeterministicProviderCliService {
         }
         await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
-            summary: `forge-bridge completed ${worktree.branchName} (${developCycle ? "develop cycle" : phase}).`,
+            summary: `forge-bridge completed ${worktree.branchName} (${debugCycle ? "debug cycle" : developCycle ? "develop cycle" : phase}).`,
             spec: {
                 repoPath: worktree.worktreePath,
                 path: specPath,
@@ -367,23 +403,38 @@ export class DeterministicProviderCliService {
         const browserChecks = browserSidecar && launchTarget
             ? [deterministicBrowserCheck(launchTarget, browserSidecar.relativePath)]
             : [];
+        const sidecars = await writeQaSidecarFiles(worktree.worktreePath, browserSidecar ? [browserSidecar] : []);
         const summary = missingLaunchTarget
             ? "QA blocked because browser testing is required but no app launch target was provided."
             : "All checks passed. forge-bridge QA completed.";
-        const qaArtifact = await writeQaArtifacts({
-            worktreePath: worktree.worktreePath,
-            workItemId: dispatch.workItem.id,
-            acceptanceCriteria: dispatch.workItem.acceptanceCriteria,
-            producedBy: "forge-bridge",
-            provider: dispatch.execution.provider,
-            model: dispatch.execution.model,
-            command: "forge-bridge deterministic QA",
-            summary,
-            status: missingLaunchTarget ? "blocked" : "pass",
-            blockerReason: missingLaunchTarget ? "missing_app_launch_target" : null,
-            browserChecks,
-            sidecarFiles: browserSidecar ? [browserSidecar] : []
-        });
+        const criterion = dispatch.workItem.acceptanceCriteria.trim() || "Forge QA evidence exists";
+        for (const gate of qaCompletionGateOrder) {
+            await writeCompletionArtifact({
+                worktreePath: worktree.worktreePath,
+                workItemId: dispatch.workItem.id,
+                phase: "qa",
+                producedBy: "forge-bridge",
+                redactionSecrets: exactRedactionSecrets(dispatch),
+                qaCycle: true
+            }, expectedQaCompletionToolName(gate), deterministicQaGatePayload({
+                gate,
+                criterion,
+                summary,
+                missingLaunchTarget,
+                browserChecks,
+                sidecars
+            }));
+            await context.emit({
+                role: "hook",
+                kind: "checkpoint",
+                content: `qa_gate: ${gate} artifact accepted.`,
+                eventType: "qa_gate"
+            });
+        }
+        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id);
+        if (!qaArtifact) {
+            throw new Error("Deterministic QA did not produce the complete durable QA artifact bundle.");
+        }
         await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
         await emitQaStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, qaArtifact);
         await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
@@ -395,22 +446,30 @@ export class DeterministicProviderCliService {
     }
     async runConflictResolve(context) {
         const { dispatch, worktree } = context;
-        await this.git.run(worktree.worktreePath, ["commit", "--allow-empty", "-m", `forge bridge conflict resolve for ${dispatch.workItem.id.slice(0, 8)}`]);
+        const addressComments = isPullRequestCommentsDispatch(dispatch);
+        await this.git.run(worktree.worktreePath, ["commit", "--allow-empty", "-m", `forge bridge ${addressComments ? "pr comments" : "conflict resolve"} for ${dispatch.workItem.id.slice(0, 8)}`]);
         await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         await context.emit({
             role: "assistant",
             kind: "message",
-            content: `Deterministic conflict resolve completed for ${worktree.branchName}.`,
-            eventType: "conflict_resolve_complete"
+            content: addressComments
+                ? `Deterministic PR comment addressing completed for ${worktree.branchName}.`
+                : `Deterministic conflict resolve completed for ${worktree.branchName}.`,
+            eventType: addressComments ? "pr_comments_complete" : "conflict_resolve_complete"
         });
         return {
-            summary: `forge-bridge resolved conflicts for ${worktree.branchName}.`
+            summary: addressComments
+                ? `forge-bridge addressed PR comments for ${worktree.branchName}.`
+                : `forge-bridge resolved conflicts for ${worktree.branchName}.`
         };
     }
 }
 function phaseCompleteEventType(phase) {
     return phase === "implementation" ? "implementation_complete" : `${phase}_complete`;
 }
+function isDebugCompletionPhaseForProvider(phase) {
+    return debugCompletionPhaseOrder.includes(phase);
+}
 function deterministicCompletionPayload(phase, dispatch, changesetBody) {
     const changesetHash = sha256(changesetBody);
     const criterion = dispatch.workItem.acceptanceCriteria || "Deterministic bridge changeset exists";
@@ -433,6 +492,56 @@ function deterministicCompletionPayload(phase, dispatch, changesetBody) {
             next_phase_context: "Review FORGE_PHASE5_CHANGESET.md and the bridge commit before validation."
         };
     }
+    if (phase === "debug_repro") {
+        return {
+            status: "pass",
+            summary: "forge-bridge reproduced the bug deterministically.",
+            repro_steps: ["Run the deterministic fake-worker debug reproduction."],
+            observed: "The configured bug scenario is reproducible in deterministic bridge mode.",
+            expected: "The bug scenario should be fixed before QA handoff.",
+            evidence: [{ kind: "changeset", path: "FORGE_PHASE5_CHANGESET.md", content_hash: changesetHash }]
+        };
+    }
+    if (phase === "debug_root_cause") {
+        return {
+            status: "pass",
+            summary: "forge-bridge isolated a deterministic root cause.",
+            root_cause: "The deterministic fake-worker bug is represented by the generated changeset evidence.",
+            evidence: [{ kind: "changeset", path: "FORGE_PHASE5_CHANGESET.md", content_hash: changesetHash }],
+            eliminated_alternatives: [{ summary: "No alternate deterministic fake-worker path was implicated." }],
+            risk_area: "forge-bridge deterministic debug lane"
+        };
+    }
+    if (phase === "debug_fix") {
+        return {
+            status: "pass",
+            summary: "forge-bridge applied a deterministic debug fix.",
+            changed_files: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Recorded deterministic debug fix evidence." }],
+            tests_added_or_updated: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Deterministic debug evidence doubles as fake-worker regression coverage." }],
+            remaining_risks: [],
+            resolved_findings: (dispatch.qaRework?.findingIds ?? []).map((qaId) => ({
+                qa_id: qaId,
+                status: "resolved",
+                summary: `Resolved deterministic QA finding ${qaId}.`,
+                evidence: { path: "FORGE_PHASE5_CHANGESET.md", content_hash: changesetHash },
+                changed_files: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Recorded deterministic debug fix evidence." }],
+                tests_added_or_updated: [{ path: "FORGE_PHASE5_CHANGESET.md", summary: "Deterministic fake-worker regression evidence." }],
+                regression_evidence: [{ command: "forge-bridge deterministic debug regression", status: "pass" }]
+            }))
+        };
+    }
+    if (phase === "debug_regression") {
+        return {
+            status: "pass",
+            summary: "forge-bridge proved the deterministic debug regression is QA-ready.",
+            commands: [{ command: "forge-bridge deterministic debug regression", exit_code: 0, status: "pass", summary: "Deterministic debug regression completed." }],
+            required_regressions: ["Original deterministic repro no longer fails."],
+            build_status: "not_applicable",
+            test_status: "pass",
+            repro_negative: true,
+            qa_ready: true
+        };
+    }
     if (phase === "self_review") {
         return {
             status: "pass",
@@ -493,6 +602,110 @@ function deterministicCompletionPayload(phase, dispatch, changesetBody) {
         ready_for_dev_test: true
     };
 }
+function deterministicQaGatePayload(options) {
+    const blocked = options.missingLaunchTarget;
+    const skippedBecauseBlocked = blocked
+        ? {
+            status: "skipped",
+            summary: "Skipped because browser QA was blocked by missing launch target.",
+            reason: "Upstream browser QA blocker prevents meaningful downstream evidence."
+        }
+        : null;
+    switch (options.gate) {
+        case "qa_plan":
+            return {
+                status: "pass",
+                summary: "Deterministic QA plan recorded.",
+                checklist: [
+                    "Review the validated work item against acceptance criteria.",
+                    "Run deterministic regression evidence.",
+                    "Confirm no in-scope QA findings remain."
+                ],
+                acceptance_criteria: [options.criterion]
+            };
+        case "qa_regression":
+            return {
+                status: "pass",
+                summary: "Deterministic regression QA completed.",
+                commands: [
+                    {
+                        command: "forge-bridge deterministic QA",
+                        exit_code: 0,
+                        status: "pass",
+                        summary: "Deterministic regression evidence completed."
+                    }
+                ],
+                notes: "Regression gate passed in deterministic fake-worker mode."
+            };
+        case "qa_api":
+            return {
+                status: "skipped",
+                summary: "No API/backend surface was identified for deterministic QA.",
+                reason: "The deterministic fake-worker changeset does not exercise API/backend behavior."
+            };
+        case "qa_manual_web":
+            return blocked
+                ? {
+                    status: "blocked",
+                    summary: "Browser QA could not run because no app launch target was provided.",
+                    blocker_reason: "missing_app_launch_target"
+                }
+                : options.browserChecks.length > 0
+                    ? {
+                        status: "pass",
+                        summary: "Deterministic browser QA exercised the configured launch target.",
+                        browser_checks: options.browserChecks,
+                        sidecars: options.sidecars,
+                        notes: "Browser sidecar evidence recorded."
+                    }
+                    : {
+                        status: "skipped",
+                        summary: "Manual web QA was not required for this deterministic run.",
+                        reason: "Forge did not require browser QA and no launch target was necessary."
+                    };
+        case "qa_bug_repro":
+            return skippedBecauseBlocked ?? {
+                status: "skipped",
+                summary: "No failed QA observation required bug reproduction.",
+                reason: "No defects or candidate bugs were observed."
+            };
+        case "qa_findings":
+            return skippedBecauseBlocked ?? {
+                status: "pass",
+                summary: "No QA findings or candidate bugs were identified.",
+                findings: [],
+                candidate_bugs: []
+            };
+        case "qa_verdict":
+            return {
+                status: blocked ? "blocked" : "pass",
+                summary: options.summary,
+                checklist: [
+                    "Review the validated work item against acceptance criteria.",
+                    "Run deterministic regression evidence.",
+                    blocked ? "Record missing browser launch target blocker." : "Confirm no in-scope QA findings remain."
+                ],
+                tested_acceptance_criteria: blocked ? [] : [options.criterion],
+                commands: blocked
+                    ? []
+                    : [
+                        {
+                            command: "forge-bridge deterministic QA",
+                            exit_code: 0,
+                            status: "pass",
+                            summary: "Deterministic QA command completed."
+                        }
+                    ],
+                browser_checks: blocked ? [] : options.browserChecks,
+                sidecars: blocked ? [] : options.sidecars,
+                notes: options.summary,
+                findings: [],
+                candidate_bugs: [],
+                blocker_reason: blocked ? "missing_app_launch_target" : null,
+                report_markdown: `# QA report\n\n${options.summary}\n`
+            };
+    }
+}
 const qaArtifactFileNames = {
     plan: "qa.plan.json",
     evidence: "qa.evidence.json",
@@ -551,78 +764,6 @@ async function writeQaSidecarFiles(worktreePath, files) {
     }
     return sidecars;
 }
-async function writeQaArtifacts(request) {
-    const artifactRoot = artifactRootFor(request.worktreePath, request.workItemId);
-    await fs.mkdir(artifactRoot, { recursive: true });
-    const sidecars = await writeQaSidecarFiles(request.worktreePath, request.sidecarFiles ?? []);
-    const status = request.status ?? "pass";
-    const criterion = request.acceptanceCriteria.trim() || "Forge QA evidence exists";
-    const relativeEvidencePath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.evidence);
-    const relativeFindingsPath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.findings);
-    const relativeReportPath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.report);
-    const planJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        checklist: [
-            "Review the validated work item against acceptance criteria.",
-            "Run relevant provider QA verification.",
-            "Confirm no in-scope QA findings remain."
-        ],
-        acceptance_criteria: [criterion]
-    });
-    const evidenceJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        commands: status === "blocked"
-            ? []
-            : [
-                {
-                    command: request.command,
-                    exit_code: 0,
-                    status: "pass",
-                    summary: `${request.provider} QA completed successfully.`
-                }
-            ],
-        browser_checks: request.browserChecks ?? [],
-        sidecars,
-        notes: request.summary
-    });
-    const findingsJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        findings: [],
-        candidate_bugs: []
-    });
-    const verdictJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        status,
-        summary: request.summary,
-        tested_acceptance_criteria: status === "blocked" ? [] : [criterion],
-        finding_ids: [],
-        candidate_bug_ids: [],
-        blocker_reason: status === "blocked" ? request.blockerReason ?? "inconclusive" : null,
-        evidence_path: relativeEvidencePath,
-        findings_path: relativeFindingsPath,
-        report_path: relativeReportPath
-    });
-    const report = `# QA report\n\n${request.summary}\n\n- Provider: ${singleLine(request.provider)}\n- Model: ${singleLine(request.model)}\n- Command: ${singleLine(request.command)}\n`;
-    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.plan), planJson, "utf8");
-    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.evidence), evidenceJson, "utf8");
-    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.findings), findingsJson, "utf8");
-    const verdictPath = path.join(artifactRoot, qaArtifactFileNames.verdict);
-    await fs.writeFile(verdictPath, verdictJson, "utf8");
-    await fs.writeFile(path.join(artifactRoot, qaArtifactFileNames.report), report, "utf8");
-    return {
-        repoPath: request.worktreePath,
-        path: verdictPath,
-        verdictJson,
-        report,
-        producedBy: request.producedBy,
-        status,
-        phase: "qa"
-    };
-}
 async function emitQaArtifactRecorded(emit, worktreePath, artifact) {
     const relativePath = path.relative(worktreePath, artifact.path) || path.basename(artifact.path);
     await emit({
@@ -835,9 +976,6 @@ function summarizeQaObject(source) {
 function qaArtifactRelativePath(workItemId, fileName) {
     return [".forge", "work-items", workItemId, "artifacts", fileName].join("/");
 }
-function jsonText(value) {
-    return `${JSON.stringify(value, null, 2)}\n`;
-}
 async function emitCompletionArtifactRecorded(emit, worktreePath, artifact) {
     const relativePath = path.relative(worktreePath, artifact.path) || path.basename(artifact.path);
     await emit({
@@ -872,7 +1010,15 @@ async function emitPhaseGateEvents(emit, artifact) {
         ? "phase_progression: implementation -> self_review"
         : phase === "self_review"
             ? "phase_progression: self_review -> validation"
-            : "phase_progression: validation -> QA ready";
+            : phase === "debug_repro"
+                ? "phase_progression: debug_repro -> debug_root_cause"
+                : phase === "debug_root_cause"
+                    ? "phase_progression: debug_root_cause -> debug_fix"
+                    : phase === "debug_fix"
+                        ? "phase_progression: debug_fix -> debug_regression"
+                        : phase === "debug_regression"
+                            ? "phase_progression: debug_regression -> QA ready"
+                            : "phase_progression: validation -> QA ready";
     await emit({
         role: "hook",
         kind: "checkpoint",
@@ -883,6 +1029,7 @@ async function emitPhaseGateEvents(emit, artifact) {
 function completionPhaseFromArtifact(artifact) {
     const phase = artifact.phase?.trim();
     return phase === "self_review" || phase === "validation" || phase === "implementation" || phase === "qa"
+        || phase === "debug_repro" || phase === "debug_root_cause" || phase === "debug_fix" || phase === "debug_regression"
         ? phase
         : "implementation";
 }
@@ -894,13 +1041,18 @@ class LiveCompletionArtifactEmitter {
     emitted = new Set();
     timer = null;
     pending = Promise.resolve();
-    constructor(worktreePath, workItemId, phase, developCycle, emit) {
+    constructor(worktreePath, workItemId, phase, developCycle, debugCycle, emit) {
         this.worktreePath = worktreePath;
         this.workItemId = workItemId;
         this.emit = emit;
-        this.phases = developCycle
-            ? developCyclePhaseOrder.slice(developCyclePhaseOrder.indexOf(phase))
-            : [phase];
+        if (debugCycle && isDebugCompletionPhaseForProvider(phase)) {
+            this.phases = debugCompletionPhaseOrder.slice(debugCompletionPhaseOrder.indexOf(phase));
+        }
+        else {
+            this.phases = developCycle
+                ? developCyclePhaseOrder.slice(developCyclePhaseOrder.indexOf(phase))
+                : [phase];
+        }
     }
     start() {
         void this.pollQueued();
@@ -943,20 +1095,23 @@ class LiveCompletionArtifactEmitter {
         }
     }
 }
-async function readCompletionArtifactsForRun(worktreePath, workItemId, phase, developCycle) {
-    if (!developCycle) {
+async function readCompletionArtifactsForRun(worktreePath, workItemId, phase, developCycle, debugCycle) {
+    if (!developCycle && !debugCycle) {
         const artifact = await readCompletionArtifact(worktreePath, workItemId, phase);
         if (!artifact) {
             throw new Error(`Provider CLI completed but did not call the Forge ${phase} completion tool.`);
         }
         return [artifact];
     }
+    const expectedPhases = debugCycle && isDebugCompletionPhaseForProvider(phase)
+        ? debugCompletionPhaseOrder.slice(debugCompletionPhaseOrder.indexOf(phase))
+        : ["implementation", "self_review", "validation"];
     const artifacts = [];
-    for (const expectedPhase of ["implementation", "self_review", "validation"]) {
+    for (const expectedPhase of expectedPhases) {
         const artifact = await readCompletionArtifact(worktreePath, workItemId, expectedPhase);
         if (!artifact) {
             if (artifacts.length === 0) {
-                throw new Error("Provider CLI completed but did not call the Forge implementation completion tool.");
+                throw new Error(`Provider CLI completed but did not call the Forge ${expectedPhase} completion tool.`);
             }
             const previous = artifacts[artifacts.length - 1];
             if ((previous.status ?? "").trim().toLowerCase() === "pass") {
@@ -1132,9 +1287,6 @@ function quoteWindowsCommandLineArg(value) {
     }
     return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, "$1$1")}"`;
 }
-async function fileExists(inputPath) {
-    return fs.stat(inputPath).then((stat) => stat.isFile()).catch(() => false);
-}
 async function readProcessLines(stream, onLine) {
     const reader = readline.createInterface({ input: stream });
     try {
@@ -1155,9 +1307,6 @@ function sha256(content) {
 export function formatProviderCliCommand(command) {
     return [command.command, ...command.args].map(singleLine).join(" ");
 }
-function yamlQuotedScalar(value) {
-    return JSON.stringify(singleLine(value));
-}
 function singleLine(value) {
     return value.replace(/\s+/g, " ").trim();
 }
@@ -1224,6 +1373,20 @@ ${completionPromptForDevelopCycle(phase)}
 
 Finish with a concise summary of changed files and verification after the validation completion tool has accepted the work, or after the current phase tool records a non-pass blocker.`;
 }
+function buildDebugCyclePrompt(dispatch, phase = completionPhaseFromDispatch(dispatch)) {
+    return `You are Forge's Debug lane running locally in a prepared git worktree for a bug work item.
+
+Read .forge/work-items/${dispatch.workItem.id}/spec.md, reproduce or characterize the bug, isolate root cause, apply the smallest safe fix, then prove the regression in this same provider session.
+Start in the ${phase.replace(/_/g, " ")} gate. Do not stop after a passing Debug gate; continue through the next Debug MCP instruction returned by the tool server until debug_regression is accepted or the current gate records a non-pass blocker.
+${debugQaReworkInstruction(dispatch)}
+Use the repository's existing conventions. Run focused tests when practical, especially the original repro and required regressions.
+Forge owns protocol files: worktree prep, injected .forge commands/hooks/skills, Debug verdict artifacts, reports, and commits.
+Read Forge-provided context under .forge when needed, but do not edit .forge files or create Forge Debug artifacts by hand.
+
+${completionPromptForDebugCycle(isDebugCompletionPhaseForProvider(phase) ? phase : "debug_repro")}
+
+Finish with a concise summary of changed files and verification after the debug_regression completion tool has accepted the work, or after the current Debug gate tool records a non-pass blocker.`;
+}
 function qaReworkImplementationInstruction(dispatch) {
     if (!dispatch.qaRework) {
         return "";
@@ -1235,6 +1398,17 @@ QA rework context:
 - Required QA finding IDs: ${dispatch.qaRework.findingIds.join(", ")}
 Read the packet JSON and fix or explicitly dispute each listed finding. The implementation completion artifact must include resolved_findings entries for every required QA ID with qa_id, status, summary, evidence, changed_files, tests_added_or_updated, and regression_evidence.`;
 }
+function debugQaReworkInstruction(dispatch) {
+    if (!dispatch.qaRework) {
+        return "";
+    }
+    return `
+QA rework context for Debug:
+- Attempt ${dispatch.qaRework.attempt}/${dispatch.qaRework.maxAttempts}
+- Rework packet: ${dispatch.qaRework.packetPath}
+- Required QA finding IDs: ${dispatch.qaRework.findingIds.join(", ")}
+Read the packet JSON, reproduce or characterize each listed finding, fix or explicitly dispute it, and include resolved_findings entries for every required QA ID in forge.complete_debug_fix with qa_id, status, summary, evidence, changed_files, tests_added_or_updated, and regression_evidence.`;
+}
 function qaReworkRetestInstruction(dispatch) {
     if (!dispatch.qaRework) {
         return "";
@@ -1270,9 +1444,16 @@ function qaBrowserInstruction(dispatch) {
     const routes = launchTarget.routes.length > 0 ? launchTarget.routes.join(", ") : "not specified";
     return `Browser/app launch context:\n- Browser QA required: ${qaBrowser.required ? "yes" : "no, unless the diff/AC requires it"}\n- URL: ${launchTarget.url || "not specified"}\n- Ready URL: ${launchTarget.ready_url || "not specified"}\n- Launch command: ${launchTarget.command || "not specified"}\n- Working directory: ${launchTarget.working_directory || "repo root"}\n- Routes to cover: ${routes}\n- Notes: ${launchTarget.notes || "none"}\n- Browser sidecars path: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
 }
-function buildQaPrompt(dispatch) {
+function buildQaPrompt(dispatch, laneSpec) {
     return `You are Forge's QA lane running locally in a prepared git worktree.
 
+First read and follow the injected QA lane command at .forge/work-items/${dispatch.workItem.id}/spec.md. It defines the required gated QA skill workflow for this run.
+
+Injected QA lane command and work item spec:
+${laneSpec}
+
+---
+
 Work item: ${dispatch.workItem.id}
 Title: ${dispatch.workItem.title}
 Description:
@@ -1295,9 +1476,9 @@ Record concrete evidence. For UI/browser work, include browser_checks with URLs/
 Report in-scope defects as actionable findings with repro steps, expected/actual behavior, evidence, likely area, required fix, and required regression.
 Out-of-scope or follow-up issues belong in candidate_bugs instead of blocking the current item.
 
-${completionPromptForPhase("qa")}
+${completionPromptForQaCycle()}
 
-Finish with a concise summary only after forge.complete_qa accepts the QA bundle.`;
+Finish with a concise summary only after forge.complete_qa_verdict accepts the QA bundle.`;
 }
 function buildConflictResolvePrompt(dispatch, branchName) {
     const targetBranch = dispatch.cycleRun.requestedBase || dispatch.repo.defaultBranch || "main";
@@ -1312,6 +1493,33 @@ Keep the original work item intent intact:
 
 Finish with a concise summary of the conflicts resolved and verification performed.`;
 }
+function buildPullRequestCommentsPrompt(dispatch, branchName) {
+    const pr = dispatch.pullRequest;
+    const targetBranch = pr?.targetBranch || dispatch.cycleRun.requestedBase || dispatch.repo.defaultBranch || "main";
+    const prLocator = pr
+        ? `PR #${pr.number}${pr.url ? ` (${pr.url})` : ""}`
+        : "the open pull request for this work item";
+    return `You are Forge's Pull Request Comments lane running locally in a prepared git worktree.
+
+The current branch is the pull request branch ${branchName}. Address unresolved review comments on ${prLocator}.
+PR context:
+- Provider: ${pr?.provider || "not provided"}
+- Source branch: ${pr?.sourceBranch || branchName}
+- Target branch: ${targetBranch}
+- Unresolved comments: ${pr?.unresolvedThreads ?? "unknown"}
+
+Use the PR URL, local git metadata, and available GitHub tooling/auth to inspect unresolved review threads. Make focused code or test changes that answer the feedback, commit the changes, and push ${branchName} to origin.
+If the review thread contents are unavailable, stop with a clear summary of what could not be accessed instead of guessing.
+Keep the original work item intent intact:
+- Work item: ${dispatch.workItem.id}
+- Title: ${dispatch.workItem.title}
+- Acceptance criteria: ${dispatch.workItem.acceptanceCriteria || "Not specified"}
+
+Finish with a concise summary of comments addressed and verification performed.`;
+}
+function isPullRequestCommentsDispatch(dispatch) {
+    return dispatch.cycleRun.kind.trim().toLowerCase() === "pr_comments";
+}
 async function cleanupCompletionTools(completionTools, emit) {
     try {
         await completionTools.cleanup();