@loucompanion/forge-bridge 0.1.1-dev.caea7216568f → 0.1.1-dev.e646c8fd6b9b

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

@@ -1,17 +1,60 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { execFile, spawn } from "node:child_process";
 import readline from "node:readline";
 import { promisify } from "node:util";
 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, artifactRootForOwner, 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);
 const developCyclePhaseOrder = ["implementation", "self_review", "validation"];
+const allowedProviderParentEnvNames = [
+    "PATH",
+    "HOME",
+    "USERPROFILE",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "LANG"
+];
+const windowsAllowedProviderParentEnvNames = [
+    "SystemRoot",
+    "ComSpec",
+    "PATHEXT",
+    "APPDATA",
+    "LOCALAPPDATA"
+];
+function buildProviderChildEnvironment(requestEnv) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (typeof value === "string" && isAllowedProviderParentEnv(key)) {
+            env[key] = value;
+        }
+    }
+    if (requestEnv) {
+        for (const [key, value] of Object.entries(requestEnv)) {
+            const trimmedKey = key.trim();
+            if (trimmedKey.length > 0) {
+                env[trimmedKey] = value;
+            }
+        }
+    }
+    return env;
+}
+function isAllowedProviderParentEnv(key) {
+    return isAllowedProviderParentEnvName(key, allowedProviderParentEnvNames)
+        || key.toUpperCase().startsWith("LC_")
+        || (process.platform === "win32" && isAllowedProviderParentEnvName(key, windowsAllowedProviderParentEnvNames));
+}
+function isAllowedProviderParentEnvName(key, allowedNames) {
+    return allowedNames.some((allowed) => allowed.toLowerCase() === key.toLowerCase());
+}
 export class RoutingProviderCliService {
     realProvider;
     deterministicProvider;
@@ -24,6 +67,11 @@ export class RoutingProviderCliService {
             ? await this.deterministicProvider.runImplementation(context)
             : await this.realProvider.runImplementation(context);
     }
+    async runArchitect(context) {
+        return isFakeWorkerModel(context.dispatch.execution.model)
+            ? await this.deterministicProvider.runArchitect(context)
+            : await this.realProvider.runArchitect(context);
+    }
     async runConflictResolve(context) {
         return isFakeWorkerModel(context.dispatch.execution.model)
             ? await this.deterministicProvider.runConflictResolve(context)
@@ -34,6 +82,11 @@ export class RoutingProviderCliService {
             ? await this.deterministicProvider.runQa(context)
             : await this.realProvider.runQa(context);
     }
+    async runDraft(context) {
+        return isFakeWorkerModel(context.dispatch.execution.model)
+            ? await this.deterministicProvider.runDraft(context)
+            : await this.realProvider.runDraft(context);
+    }
 }
 export class ProcessBackedProviderCliService {
     processRunner;
@@ -42,10 +95,65 @@ export class ProcessBackedProviderCliService {
         this.processRunner = processRunner;
         this.git = git;
     }
+    async runDraft(context) {
+        const { dispatch } = context;
+        if (!dispatch.draft) {
+            throw new Error("Draft dispatch context is missing.");
+        }
+        const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "forge-bridge-draft-"));
+        const command = buildProviderCliCommand(dispatch, {
+            worktreePath: tempDir,
+            prompt: buildDraftPrompt(dispatch),
+            skipGitRepoCheck: true
+        });
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Starting provider CLI Draft: ${formatProviderCliCommand(command)}`,
+            eventType: "provider_cli_started"
+        });
+        const outputState = createProviderOutputState(dispatch.execution.provider);
+        try {
+            const result = await this.processRunner.run({
+                command: command.command,
+                args: command.args,
+                cwd: tempDir,
+                env: providerProcessEnv(dispatch)
+            }, {
+                onStdoutLine: async (line) => {
+                    for (const event of outputState.consume(line)) {
+                        await context.emit(event);
+                    }
+                }
+            }, context.signal);
+            if (result.exitCode !== 0) {
+                throw new Error(`Provider CLI exited with code ${result.exitCode}${summarizeStderr(result.stderr)}.`);
+            }
+            const content = outputState.finalMessage ?? result.stdout.trim();
+            if (!content) {
+                throw new Error("Provider CLI completed without returning a draft.");
+            }
+            const json = extractJsonObject(content);
+            await context.emit({
+                role: "assistant",
+                kind: "message",
+                content: json,
+                eventType: "draft_complete"
+            });
+            await emitProviderUsageEvent(context.emit, dispatch, outputState);
+            return {
+                summary: "Draft generated through Forge Runner."
+            };
+        }
+        finally {
+            await fs.rm(tempDir, { recursive: true, force: true });
+        }
+    }
     async runImplementation(context) {
         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);
@@ -59,7 +167,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({
@@ -71,13 +183,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();
@@ -85,11 +199,10 @@ export class ProcessBackedProviderCliService {
                 command: command.command,
                 args: command.args,
                 cwd: worktree.worktreePath,
-                env: providerRedactionEnv(dispatch)
+                env: providerProcessEnv(dispatch)
             }, {
                 onStdoutLine: async (line) => {
-                    const event = outputState.consume(line);
-                    if (event) {
+                    for (const event of outputState.consume(line)) {
                         await context.emit(event);
                     }
                 }
@@ -111,7 +224,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);
@@ -137,7 +250,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,
@@ -149,12 +262,105 @@ export class ProcessBackedProviderCliService {
             artifacts: completionArtifacts
         };
     }
+    async runArchitect(context) {
+        const { dispatch, worktree } = context;
+        const completionTools = await prepareCompletionToolRuntime({ dispatch, worktree, phase: "architect" });
+        const command = buildProviderCliCommand(dispatch, {
+            worktreePath: worktree.worktreePath,
+            prompt: buildArchitectPrompt(dispatch),
+            completionTools
+        });
+        const commandText = formatProviderCliCommand(command);
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Starting provider CLI Architect: ${commandText} in ${worktree.worktreePath}`,
+            eventType: "provider_cli_started"
+        });
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: "Forge Architect completion tools configured; provider must call forge.complete_architect_plan before exit.",
+            eventType: "completion_tools_configured"
+        });
+        const outputState = createProviderOutputState(dispatch.execution.provider);
+        const liveArchitectEvents = new LiveArchitectArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, context.emit);
+        let result;
+        try {
+            liveArchitectEvents.start();
+            result = await this.processRunner.run({
+                command: command.command,
+                args: command.args,
+                cwd: worktree.worktreePath,
+                env: providerProcessEnv(dispatch)
+            }, {
+                onStdoutLine: async (line) => {
+                    for (const event of outputState.consume(line)) {
+                        await context.emit(event);
+                    }
+                }
+            }, context.signal);
+        }
+        finally {
+            await liveArchitectEvents.stop();
+            await cleanupCompletionTools(completionTools, context.emit);
+        }
+        if (result.exitCode !== 0) {
+            const stderr = clip(result.stderr.trim() || result.stdout.trim(), 1200);
+            throw new Error(`${command.command} exited ${result.exitCode}${stderr ? `: ${stderr}` : ""}`);
+        }
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Provider CLI Architect completed: ${command.command} exit ${result.exitCode}${outputState.sessionLabel ? ` ${outputState.sessionLabel}` : ""}.`,
+            eventType: "provider_cli_completed"
+        });
+        await emitProviderUsageEvent(context.emit, dispatch, outputState);
+        const architectArtifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "architect");
+        if (!architectArtifact) {
+            throw new Error("Provider CLI Architect completed but did not call the Forge Architect completion tool.");
+        }
+        if (!liveArchitectEvents.hasEmitted()) {
+            await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, architectArtifact);
+            await emitArchitectStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, architectArtifact);
+        }
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content: outputState.finalMessage || `${dispatch.execution.provider} CLI produced an Architect plan for ${worktree.branchName}.`,
+            eventType: "architect_complete"
+        });
+        const specPath = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id, "spec.md");
+        const specBody = await fs.readFile(specPath, "utf8").catch(() => `# ${dispatch.workItem.title}\n\nArchitect plan pending approval.\n`);
+        return {
+            summary: `${dispatch.execution.provider} CLI Architect plan produced.`,
+            spec: {
+                repoPath: worktree.worktreePath,
+                path: specPath,
+                body: specBody,
+                producedBy: `${dispatch.execution.provider}-cli`,
+                status: "pending_approval"
+            },
+            artifact: architectArtifact,
+            artifacts: [architectArtifact]
+        };
+    }
     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);
@@ -167,11 +373,11 @@ 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);
-        const liveQaEvents = new LiveQaArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, context.emit);
+        const liveQaEvents = new LiveQaArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, dispatch, context.emit);
         let result;
         try {
             liveQaEvents.start();
@@ -179,11 +385,10 @@ export class ProcessBackedProviderCliService {
                 command: command.command,
                 args: command.args,
                 cwd: worktree.worktreePath,
-                env: providerRedactionEnv(dispatch)
+                env: providerProcessEnv(dispatch)
             }, {
                 onStdoutLine: async (line) => {
-                    const event = outputState.consume(line);
-                    if (event) {
+                    for (const event of outputState.consume(line)) {
                         await context.emit(event);
                     }
                 }
@@ -204,16 +409,17 @@ export class ProcessBackedProviderCliService {
             eventType: "provider_cli_completed"
         });
         await emitProviderUsageEvent(context.emit, dispatch, outputState);
-        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id);
+        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId);
         if (!qaArtifact) {
             const verdictOnly = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "qa");
             throw new Error(verdictOnly
                 ? "Provider CLI QA completed but did not produce the complete durable QA artifact bundle."
                 : "Provider CLI QA completed but did not call the Forge QA completion tool.");
         }
+        enforceQaBrowserLaunchTargetGate(dispatch, qaArtifact);
         if (!liveQaEvents.hasEmitted()) {
             await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
-            await emitQaStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, qaArtifact);
+            await emitQaStructuredEvents(context.emit, qaArtifact);
         }
         const status = (qaArtifact.status ?? "unknown").trim().toLowerCase();
         const statusSummary = status === "pass"
@@ -223,31 +429,41 @@ 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);
         const result = await this.processRunner.run({
             command: command.command,
             args: command.args,
-            cwd: worktree.worktreePath
+            cwd: worktree.worktreePath,
+            env: providerProcessEnv(dispatch)
         }, {
             onStdoutLine: async (line) => {
-                const event = outputState.consume(line);
-                if (event) {
+                for (const event of outputState.consume(line)) {
                     await context.emit(event);
                 }
             }
@@ -262,11 +478,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)}).`
         };
     }
 }
@@ -275,10 +495,22 @@ export class DeterministicProviderCliService {
     constructor(git = new GitClient()) {
         this.git = git;
     }
+    async runDraft(context) {
+        const content = JSON.stringify(deterministicDraftPayload(context.dispatch));
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content,
+            eventType: "draft_complete"
+        });
+        await context.emit(buildProviderUsageEvent(context.dispatch, estimatedDeterministicUsage()));
+        return { summary: "forge-bridge generated deterministic draft." };
+    }
     async runImplementation(context) {
         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);
@@ -309,9 +541,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({
@@ -320,7 +554,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.`);
@@ -336,7 +572,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,
@@ -348,6 +584,47 @@ export class DeterministicProviderCliService {
             artifacts: completionArtifacts
         };
     }
+    async runArchitect(context) {
+        const { dispatch, worktree } = context;
+        const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
+        await fs.mkdir(metadataRoot, { recursive: true });
+        const specBody = `---\ntitle: "${dispatch.workItem.title}"\nstatus: pending_approval\nproduced_by: forge-bridge\n---\n\n# ${dispatch.workItem.title}\n\nArchitect plan pending approval.\n`;
+        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: "pending_approval", produced_by: "forge-bridge" }) + "\n", "utf8");
+        await writeCompletionArtifact({
+            worktreePath: worktree.worktreePath,
+            workItemId: dispatch.workItem.id,
+            phase: "architect",
+            producedBy: "forge-bridge",
+            redactionSecrets: exactRedactionSecrets(dispatch),
+            architectCycle: true
+        }, expectedCompletionToolName("architect"), deterministicArchitectPayload(dispatch));
+        const artifact = await readCompletionArtifact(worktree.worktreePath, dispatch.workItem.id, "architect");
+        if (!artifact) {
+            throw new Error("Deterministic provider did not produce the Forge Architect completion artifact.");
+        }
+        await emitCompletionArtifactRecorded(context.emit, worktree.worktreePath, artifact);
+        await emitArchitectStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, artifact);
+        await context.emit({
+            role: "assistant",
+            kind: "message",
+            content: "Architect plan complete. forge-bridge produced deterministic planning artifacts.",
+            eventType: "architect_complete"
+        });
+        return {
+            summary: "forge-bridge completed Architect plan (deterministic).",
+            spec: {
+                repoPath: worktree.worktreePath,
+                path: specPath,
+                body: specBody,
+                producedBy: "forge-bridge",
+                status: "pending_approval"
+            },
+            artifact,
+            artifacts: [artifact]
+        };
+    }
     async runQa(context) {
         const { dispatch, worktree } = context;
         await context.emit({
@@ -356,44 +633,82 @@ export class DeterministicProviderCliService {
             content: `Planning ${dispatch.execution.provider} QA checks through forge-bridge.`,
             eventType: "qa_plan"
         });
-        const summary = "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
-        });
+        const qaBrowser = dispatch.qaBrowser;
+        const launchTarget = qaBrowser?.launchTarget ?? null;
+        const missingLaunchTarget = qaBrowser?.required === true && !hasLaunchTarget(launchTarget);
+        const browserSidecar = !missingLaunchTarget && qaBrowser?.required === true && launchTarget
+            ? deterministicBrowserSidecar(dispatch.workItem.id, launchTarget, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId)
+            : null;
+        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 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,
+                ownerType: dispatch.cycleRun.ownerType ?? undefined,
+                ownerId: dispatch.cycleRun.ownerId ?? undefined
+            }, expectedQaCompletionToolName(gate), deterministicQaGatePayload({
+                gate,
+                criterion,
+                summary,
+                missingLaunchTarget,
+                browserChecks,
+                sidecars
+            }));
+            const gateArtifact = await readQaGateArtifact(qaArtifactRootForDispatch(worktree.worktreePath, dispatch.workItem.id, dispatch), gate);
+            if (gateArtifact) {
+                await emitQaGateAccepted(context.emit, worktree.worktreePath, gateArtifact, nextQaGate(gate));
+            }
+        }
+        const qaArtifact = await readQaCompletionArtifactBundle(worktree.worktreePath, dispatch.workItem.id, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId);
+        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 emitQaStructuredEvents(context.emit, qaArtifact);
         await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
-            summary: "forge-bridge QA passed.",
+            summary: missingLaunchTarget ? "forge-bridge QA blocked." : "forge-bridge QA passed.",
             artifact: qaArtifact,
             artifacts: [qaArtifact]
         };
     }
     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";
@@ -416,6 +731,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",
@@ -476,6 +841,149 @@ function deterministicCompletionPayload(phase, dispatch, changesetBody) {
         ready_for_dev_test: true
     };
 }
+function deterministicArchitectPayload(dispatch) {
+    const planId = `architect-${dispatch.workItem.id.replace(/-/g, "")}`;
+    return {
+        status: "pass",
+        summary: "forge-bridge produced a deterministic Architect plan.",
+        implementation_plan: {
+            schema_version: 1,
+            plan_id: planId,
+            story_id: dispatch.workItem.id,
+            phases: [
+                { id: "phase-1", name: "Foundation", tasks: ["task-1"], gate: "phase-1-gate" }
+            ],
+            tasks: [
+                {
+                    id: "task-1",
+                    title: `Implement ${dispatch.workItem.title}`,
+                    phase: "phase-1",
+                    summary: "Deterministic bridge Architect task proving MCP artifact contract persistence.",
+                    acceptance_criteria: [dispatch.workItem.acceptanceCriteria || `Preserve story intent for ${dispatch.workItem.title}`],
+                    tests: [
+                        { command: "dotnet test /home/dillon/repos/Forge/Forge.sln --filter Architect", purpose: "Architect bridge contract regression" }
+                    ]
+                }
+            ],
+            dependencies: [],
+            phase_gates: [
+                { id: "phase-1-gate", phase: "phase-1", checks: ["Task tests pass", "Artifacts validate"] }
+            ]
+        },
+        qa_plan: {
+            schema_version: 1,
+            plan_id: planId,
+            final_qa: [
+                { id: "qa-1", coverage: `Verify Architect plan artifacts and pending approval status for ${dispatch.workItem.title}` }
+            ]
+        },
+        report_markdown: `# Architect Report\n\nWork item: ${dispatch.workItem.id}\nTitle: ${dispatch.workItem.title}\n\nVerdict: pass\n\nDeterministic bridge Architect plan produced for pending approval.\n`
+    };
+}
+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",
@@ -483,73 +991,66 @@ const qaArtifactFileNames = {
     verdict: "qa.verdict.json",
     report: "qa.report.md"
 };
-async function writeQaArtifacts(request) {
-    const artifactRoot = artifactRootFor(request.worktreePath, request.workItemId);
-    await fs.mkdir(artifactRoot, { recursive: true });
-    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: [
-            {
-                command: request.command,
-                exit_code: 0,
-                status: "pass",
-                summary: `${request.provider} QA completed successfully.`
-            }
-        ],
-        browser_checks: [],
-        notes: request.summary
-    });
-    const findingsJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        findings: [],
-        candidate_bugs: []
-    });
-    const verdictJson = jsonText({
-        schema_version: 1,
-        phase: "qa",
-        status: "pass",
-        summary: request.summary,
-        tested_acceptance_criteria: [criterion],
-        finding_ids: [],
-        candidate_bug_ids: [],
-        blocker_reason: 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");
+const qaGateArtifactFileNames = {
+    qa_plan: "qa.plan.json",
+    qa_regression: "qa.regression.json",
+    qa_api: "qa.api.json",
+    qa_manual_web: "qa.manual-web.json",
+    qa_bug_repro: "qa.bug-repro.json",
+    qa_findings: "qa.findings.json",
+    qa_verdict: "qa.verdict.json"
+};
+function hasLaunchTarget(target) {
+    return Boolean(target?.url?.trim()
+        || target?.ready_url?.trim()
+        || target?.command?.trim()
+        || (target?.routes ?? []).some((route) => route.trim().length > 0));
+}
+function deterministicBrowserSidecar(workItemId, target, ownerType, ownerId) {
+    const route = primaryLaunchRoute(target);
     return {
-        repoPath: request.worktreePath,
-        path: verdictPath,
-        verdictJson,
-        report,
-        producedBy: request.producedBy,
+        relativePath: qaArtifactRelativePath(workItemId, "qa/screenshots/deterministic-browser-check.txt", ownerType, ownerId),
+        content: `Deterministic Forge QA browser evidence\nRoute: ${route}\nConsole errors: []\nNetwork errors: []\nResponsive checks: desktop, mobile\n`
+    };
+}
+function deterministicBrowserCheck(target, screenshotPath) {
+    const route = primaryLaunchRoute(target);
+    return {
+        route,
+        url: route,
         status: "pass",
-        phase: "qa"
+        summary: "Deterministic browser QA exercised the configured launch target.",
+        actions: ["open launch target", "walk acceptance criteria", "check console/network summaries", "check responsive viewport"],
+        screenshots: [screenshotPath],
+        console_errors: [],
+        network_errors: [],
+        responsive_checks: ["desktop", "mobile"]
     };
 }
+function primaryLaunchRoute(target) {
+    return target.ready_url?.trim()
+        || target.url?.trim()
+        || target.routes.find((route) => route.trim().length > 0)?.trim()
+        || "app launch command";
+}
+async function writeQaSidecarFiles(worktreePath, files) {
+    const sidecars = [];
+    for (const file of files) {
+        const fullPath = path.resolve(worktreePath, file.relativePath);
+        const relativePath = path.relative(worktreePath, fullPath).split(path.sep).join("/");
+        if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+            throw new Error(`QA sidecar path must stay under the worktree: ${file.relativePath}`);
+        }
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, file.content, "utf8");
+        sidecars.push({
+            path: relativePath,
+            content_hash: sha256(file.content),
+            bytes: Buffer.byteLength(file.content, "utf8")
+        });
+    }
+    return sidecars;
+}
 async function emitQaArtifactRecorded(emit, worktreePath, artifact) {
     const relativePath = path.relative(worktreePath, artifact.path) || path.basename(artifact.path);
     await emit({
@@ -565,15 +1066,29 @@ async function emitQaArtifactRecorded(emit, worktreePath, artifact) {
         eventType: "phase_gate"
     });
 }
-async function readQaCompletionArtifactBundle(worktreePath, workItemId) {
-    const artifact = await readCompletionArtifact(worktreePath, workItemId, "qa");
-    if (!artifact || !await hasCompleteQaArtifactBundle(worktreePath, workItemId)) {
+async function readQaCompletionArtifactBundle(worktreePath, workItemId, ownerType, ownerId) {
+    const artifact = await readCompletionArtifact(worktreePath, workItemId, "qa", ownerType, ownerId);
+    if (!artifact || !await hasCompleteQaArtifactBundle(worktreePath, workItemId, ownerType, ownerId)) {
         return null;
     }
-    return artifact;
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    const planJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.plan), "utf8");
+    const evidenceJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.evidence), "utf8");
+    const findingsJson = await fs.readFile(path.join(artifactRoot, qaArtifactFileNames.findings), "utf8");
+    await validateQaBundleSidecarReferences(worktreePath, workItemId, ownerType, ownerId);
+    return {
+        ...artifact,
+        planJson,
+        evidenceJson,
+        findingsJson
+    };
 }
-async function hasCompleteQaArtifactBundle(worktreePath, workItemId) {
-    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+async function hasCompleteQaArtifactBundle(worktreePath, workItemId, ownerType, ownerId) {
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
     for (const fileName of Object.values(qaArtifactFileNames)) {
         try {
             const stat = await fs.stat(path.join(artifactRoot, fileName));
@@ -590,8 +1105,65 @@ async function hasCompleteQaArtifactBundle(worktreePath, workItemId) {
     }
     return true;
 }
-async function emitQaStructuredEvents(emit, worktreePath, workItemId, artifact) {
-    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+function enforceQaBrowserLaunchTargetGate(dispatch, artifact) {
+    const qaBrowser = dispatch.qaBrowser;
+    if (!qaBrowser?.required || hasLaunchTarget(qaBrowser.launchTarget ?? null)) {
+        return;
+    }
+    const verdict = parseJsonLine(artifact.verdictJson) ?? {};
+    const status = normalizedString(stringField(verdict, "status") ?? artifact.status ?? "");
+    const blockerReason = normalizedString(stringField(verdict, "blocker_reason") ?? "");
+    if (status !== "blocked" || blockerReason !== "missing_app_launch_target") {
+        throw new Error("QA browser testing is required but no app launch target was provided; provider must return blocked with blocker_reason missing_app_launch_target.");
+    }
+}
+async function validateQaBundleSidecarReferences(worktreePath, workItemId, ownerType, ownerId) {
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    const evidence = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.evidence));
+    const sidecars = arrayField(evidence, "sidecars");
+    if (sidecars.length === 0) {
+        return;
+    }
+    const qaSidecarRoot = path.resolve(artifactRoot, "qa");
+    for (const [index, sidecar] of sidecars.entries()) {
+        const sidecarPath = stringField(sidecar, "path");
+        const expectedHash = stringField(sidecar, "content_hash");
+        const expectedBytes = sidecar.bytes;
+        if (!sidecarPath || !expectedHash || typeof expectedBytes !== "number" || !Number.isFinite(expectedBytes) || expectedBytes <= 0) {
+            throw new Error(`QA sidecar ${index} must include path, content_hash, and positive bytes.`);
+        }
+        if (path.isAbsolute(sidecarPath)) {
+            throw new Error(`QA sidecar ${index} path must be relative to the worktree.`);
+        }
+        const fullPath = path.resolve(worktreePath, sidecarPath);
+        if (!isPathUnderRoot(qaSidecarRoot, fullPath)) {
+            const ownerDirectory = ownerType && ownerId && ownerType.trim().toLowerCase() === "story" ? "stories" : "work-items";
+            const ownerSegment = ownerType && ownerId ? ownerId : workItemId;
+            throw new Error(`QA sidecar ${index} path must be under .forge/${ownerDirectory}/${ownerSegment}/artifacts/qa/.`);
+        }
+        const stat = await fs.lstat(fullPath).catch((error) => {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                throw new Error(`QA sidecar ${index} file does not exist: ${sidecarPath}`);
+            }
+            throw error;
+        });
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`QA sidecar ${index} must reference a regular file.`);
+        }
+        await ensureNoSymbolicLinkPathSegments(qaSidecarRoot, path.dirname(fullPath), `QA sidecar ${index} path must not traverse symbolic links.`);
+        if (stat.size !== expectedBytes) {
+            throw new Error(`QA sidecar ${index} bytes do not match the referenced file.`);
+        }
+        const actualHash = await sha256File(fullPath);
+        if (actualHash !== expectedHash.trim().toLowerCase()) {
+            throw new Error(`QA sidecar ${index} content_hash does not match the referenced file.`);
+        }
+    }
+}
+async function emitQaStructuredEvents(emit, artifact) {
+    const artifactRoot = path.dirname(artifact.path);
     const plan = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.plan));
     const evidence = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.evidence));
     const findings = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.findings));
@@ -631,7 +1203,136 @@ async function emitQaStructuredEvents(emit, worktreePath, workItemId, artifact)
         eventType: status === "blocked" ? "qa_blocked" : "qa_complete"
     });
 }
+function qaArtifactRootForDispatch(worktreePath, workItemId, dispatch) {
+    return dispatch.cycleRun.ownerType && dispatch.cycleRun.ownerId
+        ? artifactRootForOwner(worktreePath, dispatch.cycleRun.ownerType, dispatch.cycleRun.ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+}
+async function readQaGateArtifact(artifactRoot, gate) {
+    const artifactPath = path.join(artifactRoot, qaGateArtifactFileNames[gate]);
+    try {
+        const stat = await fs.stat(artifactPath);
+        if (!stat.isFile()) {
+            return null;
+        }
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    const payload = await readJsonObjectFile(artifactPath);
+    return {
+        gate,
+        path: artifactPath,
+        status: stringField(payload, "status") ?? "unknown",
+        producedBy: stringField(payload, "produced_by") ?? stringField(payload, "producedBy") ?? undefined,
+        contentHash: stringField(payload, "content_hash") ?? undefined
+    };
+}
+function nextQaGate(gate) {
+    const index = qaCompletionGateOrder.indexOf(gate);
+    return index >= 0 ? qaCompletionGateOrder[index + 1] ?? null : null;
+}
+async function emitQaGateAccepted(emit, worktreePath, artifact, nextGate) {
+    const relativePath = path.relative(worktreePath, artifact.path).split(path.sep).join("/");
+    await emit({
+        role: "hook",
+        kind: artifact.status === "blocked" ? "error" : "checkpoint",
+        content: `phase_gate: ${artifact.gate} artifact accepted with status ${artifact.status}.`,
+        eventType: "phase_gate",
+        data: JSON.stringify({
+            phase: "qa",
+            qa_gate: artifact.gate,
+            status: artifact.status,
+            artifact_relative_paths: [relativePath],
+            content_hash: artifact.contentHash ?? null,
+            produced_by: artifact.producedBy ?? null
+        })
+    });
+    if (!nextGate) {
+        return;
+    }
+    await emit({
+        role: "hook",
+        kind: "checkpoint",
+        content: `phase_progression: ${artifact.gate} -> ${nextGate}`,
+        eventType: "phase_gate",
+        data: JSON.stringify({
+            phase: "qa",
+            from_gate: artifact.gate,
+            to_gate: nextGate
+        })
+    });
+}
 class LiveQaArtifactEmitter {
+    worktreePath;
+    workItemId;
+    dispatch;
+    emit;
+    emittedBundle = false;
+    emittedGates = new Set();
+    timer = null;
+    pending = Promise.resolve();
+    constructor(worktreePath, workItemId, dispatch, emit) {
+        this.worktreePath = worktreePath;
+        this.workItemId = workItemId;
+        this.dispatch = dispatch;
+        this.emit = emit;
+    }
+    start() {
+        void this.pollQueued();
+        this.timer = setInterval(() => {
+            void this.pollQueued();
+        }, 250);
+    }
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        await this.pollQueued();
+    }
+    hasEmitted() {
+        return this.emittedBundle;
+    }
+    pollQueued() {
+        this.pending = this.pending
+            .then(() => this.poll())
+            .catch(() => undefined);
+        return this.pending;
+    }
+    async poll() {
+        await this.emitAvailableGateEvents();
+        if (this.emittedBundle) {
+            return;
+        }
+        const artifact = await readQaCompletionArtifactBundle(this.worktreePath, this.workItemId, this.dispatch.cycleRun.ownerType, this.dispatch.cycleRun.ownerId);
+        if (!artifact) {
+            return;
+        }
+        enforceQaBrowserLaunchTargetGate(this.dispatch, artifact);
+        this.emittedBundle = true;
+        await emitQaArtifactRecorded(this.emit, this.worktreePath, artifact);
+        await emitQaStructuredEvents(this.emit, artifact);
+    }
+    async emitAvailableGateEvents() {
+        const artifactRoot = qaArtifactRootForDispatch(this.worktreePath, this.workItemId, this.dispatch);
+        for (const gate of qaCompletionGateOrder) {
+            if (this.emittedGates.has(gate)) {
+                continue;
+            }
+            const artifact = await readQaGateArtifact(artifactRoot, gate);
+            if (!artifact) {
+                return;
+            }
+            this.emittedGates.add(gate);
+            await emitQaGateAccepted(this.emit, this.worktreePath, artifact, nextQaGate(gate));
+        }
+    }
+}
+class LiveArchitectArtifactEmitter {
     worktreePath;
     workItemId;
     emit;
@@ -666,18 +1367,62 @@ class LiveQaArtifactEmitter {
         return this.pending;
     }
     async poll() {
-        if (this.emitted) {
+        if (this.emitted || !await hasCompleteArchitectArtifactBundle(this.worktreePath, this.workItemId)) {
             return;
         }
-        const artifact = await readQaCompletionArtifactBundle(this.worktreePath, this.workItemId);
+        const artifact = await readCompletionArtifact(this.worktreePath, this.workItemId, "architect");
         if (!artifact) {
             return;
         }
         this.emitted = true;
-        await emitQaArtifactRecorded(this.emit, this.worktreePath, artifact);
-        await emitQaStructuredEvents(this.emit, this.worktreePath, this.workItemId, artifact);
+        await emitCompletionArtifactRecorded(this.emit, this.worktreePath, artifact);
+        await emitArchitectStructuredEvents(this.emit, this.worktreePath, this.workItemId, artifact);
     }
 }
+async function hasCompleteArchitectArtifactBundle(worktreePath, workItemId) {
+    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+    for (const fileName of ["implementation.plan.json", "qa.plan.json", "architect.verdict.json", "architect.report.md"]) {
+        try {
+            const stat = await fs.stat(path.join(artifactRoot, fileName));
+            if (!stat.isFile()) {
+                return false;
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
+        }
+    }
+    return true;
+}
+async function emitArchitectStructuredEvents(emit, worktreePath, workItemId, artifact) {
+    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+    const implementationPlan = await readJsonObjectFile(path.join(artifactRoot, "implementation.plan.json"));
+    const qaPlan = await readJsonObjectFile(path.join(artifactRoot, "qa.plan.json"));
+    const verdict = parseJsonLine(artifact.verdictJson) ?? {};
+    const status = stringField(verdict, "status") ?? artifact.status ?? "unknown";
+    const planId = stringField(implementationPlan, "plan_id") ?? "unknown";
+    await emit({
+        role: "worker",
+        kind: "checkpoint",
+        content: `Architect plan recorded: ${planId} with ${arrayField(implementationPlan, "phases").length} phases and ${arrayField(implementationPlan, "tasks").length} tasks.`,
+        eventType: "architect_plan"
+    });
+    await emit({
+        role: "worker",
+        kind: "checkpoint",
+        content: `Architect QA seed recorded with ${arrayField(qaPlan, "final_qa").length} final QA items.`,
+        eventType: "architect_qa_seed"
+    });
+    await emit({
+        role: "hook",
+        kind: status === "pass" ? "checkpoint" : "error",
+        content: `architect_mcp_complete: ${status === "pass" ? "accepted" : "recorded"} - ${stringField(verdict, "summary") ?? "Architect completion payload recorded."}`,
+        eventType: "architect_mcp_complete"
+    });
+}
 async function readJsonObjectFile(filePath) {
     const content = await fs.readFile(filePath, "utf8").catch(() => "");
     return parseJsonLine(content) ?? {};
@@ -702,19 +1447,36 @@ function summarizeQaObject(source) {
         ?? stringField(source, "id")
         ?? JSON.stringify(source), 500);
 }
-function qaArtifactRelativePath(workItemId, fileName) {
+function qaArtifactRelativePath(workItemId, fileName, ownerType, ownerId) {
+    if (ownerType && ownerId) {
+        const ownerDirectory = ownerType.trim().toLowerCase() === "story" ? "stories" : "work-items";
+        return [".forge", ownerDirectory, ownerId, "artifacts", fileName].join("/");
+    }
     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({
+        role: "tool",
+        kind: "checkpoint",
+        content: `Forge completion tool validation passed for ${artifact.phase ?? "unknown"} (${artifact.status}).`,
+        eventType: "completion_tool_validation_passed",
+        data: JSON.stringify({
+            phase: artifact.phase ?? "unknown",
+            status: artifact.status,
+            artifact_relative_paths: [relativePath.split(path.sep).join("/")]
+        })
+    });
     await emit({
         role: "tool",
         kind: "tool_result",
         content: `Forge completion tool recorded ${artifact.phase ?? "unknown"} artifact ${relativePath} (${artifact.status}).`,
-        eventType: "completion_tool_artifact_recorded"
+        eventType: "completion_tool_artifact_recorded",
+        data: JSON.stringify({
+            phase: artifact.phase ?? "unknown",
+            status: artifact.status,
+            artifact_relative_paths: [relativePath.split(path.sep).join("/")]
+        })
     });
 }
 async function emitPhaseCompletionEvent(emit, artifact) {
@@ -742,7 +1504,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",
@@ -753,6 +1523,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 === "architect" || phase === "debug_repro" || phase === "debug_root_cause" || phase === "debug_fix" || phase === "debug_regression"
         ? phase
         : "implementation";
 }
@@ -764,13 +1535,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();
@@ -813,20 +1589,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") {
@@ -841,10 +1620,24 @@ async function readCompletionArtifactsForRun(worktreePath, workItemId, phase, de
     }
     return artifacts;
 }
-function providerRedactionEnv(dispatch) {
-    const env = completionRedactionEnv(exactRedactionSecrets(dispatch));
+function providerProcessEnv(dispatch) {
+    const env = {
+        ...completionRedactionEnv(exactRedactionSecrets(dispatch)),
+        ...providerCredentialEnv(dispatch)
+    };
     return Object.keys(env).length > 0 ? env : undefined;
 }
+function providerCredentialEnv(dispatch) {
+    const secret = dispatch.apiKeySecretGrant?.secret;
+    if (!secret || !dispatch.execution.requiresApiKeySecretGrant) {
+        return {};
+    }
+    const provider = dispatch.execution.provider.trim().toLowerCase();
+    if (provider === "codex" || provider === "openai") {
+        return { OPENAI_API_KEY: secret };
+    }
+    return {};
+}
 function exactRedactionSecrets(dispatch) {
     return dispatch.apiKeySecretGrant?.secret ? [dispatch.apiKeySecretGrant.secret] : [];
 }
@@ -867,7 +1660,7 @@ export class StreamingProviderProcessRunner {
         return await new Promise((resolve, reject) => {
             const child = spawn(launch.command, launch.args, {
                 cwd: request.cwd,
-                env: request.env ? { ...process.env, ...request.env } : undefined,
+                env: buildProviderChildEnvironment(request.env),
                 stdio: ["ignore", "pipe", "pipe"],
                 windowsHide: true
             });
@@ -1002,9 +1795,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 {
@@ -1022,12 +1812,69 @@ function isFakeWorkerModel(model) {
 function sha256(content) {
     return crypto.createHash("sha256").update(content).digest("hex");
 }
+function buildDraftPrompt(dispatch) {
+    const draft = dispatch.draft;
+    if (!draft) {
+        throw new Error("Draft prompt is missing.");
+    }
+    return `${draft.systemPrompt}
+
+Draft kind: ${draft.kind}
+
+${draft.userPrompt}
+
+Return ONLY the requested JSON object. Do not wrap it in markdown and do not modify files.`;
+}
+function extractJsonObject(content) {
+    let trimmed = content.trim();
+    if (trimmed.startsWith("```")) {
+        const firstNewline = trimmed.indexOf("\n");
+        const lastFence = trimmed.lastIndexOf("```");
+        if (firstNewline >= 0 && lastFence > firstNewline) {
+            trimmed = trimmed.slice(firstNewline + 1, lastFence).trim();
+        }
+    }
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    return start >= 0 && end >= start ? trimmed.slice(start, end + 1) : trimmed;
+}
+function summarizeStderr(stderr) {
+    const trimmed = stderr.trim();
+    return trimmed ? `: ${clip(trimmed, 1000)}` : "";
+}
+function deterministicDraftPayload(dispatch) {
+    const kind = dispatch.draft?.kind ?? "work_item";
+    if (kind === "work_order") {
+        return {
+            title: "Deterministic runner Work Order draft",
+            summary: "Forge Runner generated this deterministic Work Order draft.",
+            objective: "Validate runner-backed Draft generation.",
+            planningPacket: "Runner-backed draft generation returned a Work Order JSON payload.",
+            decompositionContext: "Use this deterministic fixture only in bridge tests.",
+            assumptions: ["Forge Runner dispatch is available."],
+            warnings: []
+        };
+    }
+    if (kind === "story") {
+        return {
+            title: "Deterministic runner Story draft",
+            description: "Forge Runner generated this deterministic Story draft.",
+            acceptanceCriteria: "Given runner-backed Draft generation, when Forge requests a Story draft, then JSON is returned.",
+            points: 3
+        };
+    }
+    return {
+        title: "Deterministic runner Work Item draft",
+        description: "Forge Runner generated this deterministic Work Item draft.",
+        acceptanceCriteria: "Given runner-backed Draft generation, when Forge requests a draft, then JSON is returned.",
+        reproSteps: "Run Draft with a Forge Runner provider selected.",
+        systemInfo: "forge-bridge deterministic provider",
+        points: 1
+    };
+}
 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();
 }
@@ -1036,16 +1883,19 @@ export function buildProviderCliCommand(dispatch, run) {
     const normalizedProvider = provider.toLowerCase();
     const model = dispatch.execution.model.trim();
     if (normalizedProvider === "codex") {
-        const args = ["exec"];
+        const args = run ? ["-s", codexSandboxModeForPlatform(), "-a", "never", "exec"] : ["exec"];
         if (run?.completionTools) {
             args.push(...codexMcpConfigArgs(run.completionTools));
         }
         args.push("--model", model);
         if (run) {
-            args.push("--json", "--dangerously-bypass-approvals-and-sandbox");
+            args.push("--json");
             if (run.worktreePath) {
                 args.push("--cd", run.worktreePath);
             }
+            if (run.skipGitRepoCheck) {
+                args.push("--skip-git-repo-check");
+            }
             args.push(run.prompt ?? "");
         }
         return { command: "codex", args };
@@ -1066,11 +1916,40 @@ export function buildProviderCliCommand(dispatch, run) {
     }
     return { command: provider, args };
 }
+export function codexSandboxModeForPlatform(platform = process.platform) {
+    return platform === "win32" ? "danger-full-access" : "workspace-write";
+}
+function buildArchitectPrompt(dispatch) {
+    return `You are Forge's Architect lane running locally in a prepared git worktree.
+
+Work item: ${dispatch.workItem.id} — ${dispatch.workItem.title}
+
+Plan only. Do not implement source changes, do not create Develop phase artifacts, and do not mark the spec approved.
+Read injected Forge context under .forge plus the repository shape, then produce a repo-grounded implementation DAG with task tests, phase gates, final QA coverage, and a pending-approval spec.
+${architectRevisionInstruction(dispatch)}
+Forge owns protocol files: write Architect artifacts only through the completion MCP tool.
+
+${completionPromptForPhase("architect")}
+
+Finish only after calling forge.complete_architect_plan with implementation_plan, qa_plan, status, summary, and report/report_markdown.`;
+}
+function architectRevisionInstruction(dispatch) {
+    if (!dispatch.architectRevision) {
+        return "";
+    }
+    return `
+Architect revision context:
+- Previous plan id: ${dispatch.architectRevision.priorPlanId}
+- Previous content hash: ${dispatch.architectRevision.priorContentHash}
+- Reviewer feedback: ${dispatch.architectRevision.feedback}
+Revise the prior plan in response to the feedback. Preserve accepted scope and only change what the feedback requires.`;
+}
 function buildImplementationPrompt(dispatch, phase = completionPhaseFromDispatch(dispatch)) {
     return `You are Forge's ${phase.replace(/_/g, " ")} phase runner running locally in a prepared git worktree.
 
 Read .forge/work-items/${dispatch.workItem.id}/spec.md and any prior phase artifacts required by this phase.
 ${phaseWorkInstruction(phase)}
+${qaReworkImplementationInstruction(dispatch)}
 Use the repository's existing conventions. Run relevant tests when practical.
 Forge owns protocol files: worktree prep, injected .forge commands/hooks/skills, phase verdict artifacts, reports, and commits.
 Read Forge-provided context under .forge when needed, but do not edit .forge files or create Forge verdict/report artifacts by hand.
@@ -1084,6 +1963,7 @@ function buildDevelopCyclePrompt(dispatch, phase = completionPhaseFromDispatch(d
 
 Read .forge/work-items/${dispatch.workItem.id}/spec.md, implement the work item, self-review the diff, then validate it in this same provider session.
 Start in the ${phase.replace(/_/g, " ")} phase. Do not stop after implementation if it passes; continue through self-review and validation using the next instruction returned by each completion tool.
+${qaReworkImplementationInstruction(dispatch)}
 Use the repository's existing conventions. Run relevant tests when practical.
 Forge owns protocol files: worktree prep, injected .forge commands/hooks/skills, phase verdict artifacts, reports, and commits.
 Read Forge-provided context under .forge when needed, but do not edit .forge files or create Forge verdict/report artifacts by hand.
@@ -1092,6 +1972,55 @@ ${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 "";
+    }
+    return `
+QA rework context:
+- Attempt ${dispatch.qaRework.attempt}/${dispatch.qaRework.maxAttempts}
+- Rework packet: ${dispatch.qaRework.packetPath}
+- 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.
+Use only these resolved_findings status values: resolved, disputed, or not_reproduced. Use resolved when the finding was fixed; do not use fixed.`;
+}
+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.
+Use only these resolved_findings status values: resolved, disputed, or not_reproduced. Use resolved when the finding was fixed; do not use fixed.`;
+}
+function qaReworkRetestInstruction(dispatch) {
+    if (!dispatch.qaRework) {
+        return "";
+    }
+    return `
+QA retest context:
+- Rework attempt ${dispatch.qaRework.attempt}/${dispatch.qaRework.maxAttempts}
+- Rework packet: ${dispatch.qaRework.packetPath}
+- Priority finding IDs: ${dispatch.qaRework.findingIds.join(", ")}
+Prioritize retesting the listed QA findings and their required regressions before deciding pass, needs_rework, or blocked.`;
+}
 function phaseWorkInstruction(phase) {
     if (phase === "self_review") {
         return "Review the implementation diff, apply safe fixes when needed, and record remaining risks explicitly.";
@@ -1101,9 +2030,64 @@ function phaseWorkInstruction(phase) {
     }
     return "Implement the work item and keep the change focused.";
 }
-function buildQaPrompt(dispatch) {
+function qaBrowserInstruction(dispatch) {
+    const qaBrowser = dispatch.qaBrowser;
+    if (!qaBrowser) {
+        return "Browser/app launch context: not provided by Forge.";
+    }
+    const launchTarget = qaBrowser.launchTarget;
+    if (qaBrowser.required && !hasLaunchTarget(launchTarget ?? null)) {
+        return `Browser/app launch context:\n- UI/browser QA is required for this item.\n- No app launch target was provided.\n- Return blocked with blocker_reason: missing_app_launch_target instead of pretending browser testing occurred.\n- Artifact sidecars path when available: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
+    }
+    if (!launchTarget) {
+        return `Browser/app launch context:\n- UI/browser QA is not required by Forge heuristics for this item.\n- If you determine browser testing is needed, return blocked with blocker_reason: missing_app_launch_target unless you can safely identify a launch target from the repo.\n- Browser sidecars path: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
+    }
+    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 storyQaInstruction(dispatch) {
+    const storyQa = dispatch.storyQa;
+    if (!storyQa) {
+        return "";
+    }
+    const childLines = storyQa.childTasks.map((child) => {
+        const dependencies = child.dependencyWorkItemIds.length > 0
+            ? child.dependencyWorkItemIds.join(", ")
+            : "none";
+        const validation = child.validationArtifact
+            ? `${child.validationArtifact.status} (${child.validationArtifact.path || "artifact path unavailable"})`
+            : "missing";
+        const childQa = child.qaArtifact
+            ? `${child.qaArtifact.status} (${child.qaArtifact.path || "artifact path unavailable"})`
+            : "not present";
+        return `- ${child.title} (${child.workItemId}, architect ${child.architectTaskId}, phase ${child.phaseId}/${child.phaseOrder}); deps: ${dependencies}; validation: ${validation}; child QA: ${childQa}`;
+    }).join("\n");
+    const finalQa = storyQa.finalQaChecks.length > 0
+        ? storyQa.finalQaChecks.map((check) => `- ${check}`).join("\n")
+        : "- No final QA checks were provided in qa.plan.final_qa.";
+    return `Story QA integration context:
+- Story work item: ${storyQa.storyWorkItemId}
+- Plan: ${storyQa.planId} / ${storyQa.planContentHash}
+- Story worktree: ${storyQa.worktreeKey}
+- Branch: ${storyQa.branch}
+- Architect implementation.plan.json provided: ${storyQa.implementationPlanJson ? "yes" : "no"}
+- Architect qa.plan.json provided: ${storyQa.qaPlanJson ? "yes" : "no"}
+Materialized child tasks and evidence:
+${childLines || "- No child tasks were provided."}
+Architect final QA checks:
+${finalQa}
+This is parent Story QA: inspect the integrated Story result, all current-plan child specs/evidence, and the final worktree state. Do not treat the final child task as separately signed off.`;
+}
+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:
@@ -1118,15 +2102,18 @@ ${dispatch.workItem.reproSteps || "Not provided."}
 System info / environment notes:
 ${dispatch.workItem.systemInfo || "Not provided."}
 
+${storyQaInstruction(dispatch)}
 Inspect the validated implementation and Forge artifacts under .forge/work-items/${dispatch.workItem.id}/artifacts/ when present, especially implementation, self-review, and validation evidence.
+${qaBrowserInstruction(dispatch)}
+${qaReworkRetestInstruction(dispatch)}
 QA is read-mostly: inspect code, run commands, and exercise browser/app flows when available, but do not edit product source or tests.
-Record concrete evidence. For UI/browser work, include browser_checks with URLs, actions, observed results, screenshots/traces when available, and console/network notes.
+Record concrete evidence. For UI/browser work, include browser_checks with URLs/routes, actions, observed results, screenshots/traces when available, console errors, failed network requests, and responsive checks. Store browser sidecars under .forge/work-items/${dispatch.workItem.id}/artifacts/qa/.
 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";
@@ -1141,6 +2128,34 @@ 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.
+After the push succeeds, Forge will resolve the addressed review threads through the pull request API.
+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();
@@ -1198,31 +2213,31 @@ class CursorStreamJsonState {
     consume(line) {
         const event = parseJsonLine(line);
         if (!event) {
-            return null;
+            return [];
         }
         const type = stringField(event, "type");
         if (type === "system" && stringField(event, "subtype") === "init") {
             this.sessionId = stringField(event, "session_id");
             if (this.sessionId && !this.emittedSession) {
                 this.emittedSession = true;
-                return {
-                    role: "runner",
-                    kind: "checkpoint",
-                    content: `Cursor session started: ${this.sessionId}.`,
-                    eventType: "provider_thread_started"
-                };
+                return [{
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: `Cursor session started: ${this.sessionId}.`,
+                        eventType: "provider_thread_started"
+                    }];
             }
         }
         if (type === "assistant") {
             const text = assistantMessageText(event);
             if (text) {
                 this.finalMessage = clip(text, 4000);
-                return {
-                    role: "assistant",
-                    kind: "message",
-                    content: this.finalMessage,
-                    eventType: "provider_message"
-                };
+                return [{
+                        role: "assistant",
+                        kind: "message",
+                        content: this.finalMessage,
+                        eventType: "provider_message"
+                    }];
             }
         }
         if (type === "tool_call") {
@@ -1231,23 +2246,23 @@ class CursorStreamJsonState {
             if (subtype === "started") {
                 const summary = formatCursorToolCallStarted(toolCall);
                 if (summary) {
-                    return {
-                        role: "worker",
-                        kind: "checkpoint",
-                        content: summary,
-                        eventType: "provider_tool_call"
-                    };
+                    return [{
+                            role: "worker",
+                            kind: "checkpoint",
+                            content: summary,
+                            eventType: "provider_tool_call"
+                        }];
                 }
             }
             if (subtype === "completed") {
                 const completed = formatCursorToolCallCompleted(toolCall);
                 if (completed) {
-                    return {
-                        role: "worker",
-                        kind: completed.kind,
-                        content: completed.content,
-                        eventType: completed.kind === "file_edit" ? "provider_file_edit" : "provider_tool_call"
-                    };
+                    return [{
+                            role: "worker",
+                            kind: completed.kind,
+                            content: completed.content,
+                            eventType: completed.kind === "file_edit" ? "provider_file_edit" : "provider_tool_call"
+                        }];
                 }
             }
         }
@@ -1259,14 +2274,14 @@ class CursorStreamJsonState {
             this.accumulateUsage(event);
         }
         if (type === "error" || (type === "result" && event.is_error === true)) {
-            return {
-                role: "runner",
-                kind: "error",
-                content: clip(line.trim(), 1000),
-                eventType: "provider_cli_error"
-            };
+            return [{
+                    role: "runner",
+                    kind: "error",
+                    content: clip(line.trim(), 1000),
+                    eventType: "provider_cli_error"
+                }];
         }
-        return null;
+        return [];
     }
     accumulateUsage(event) {
         const usage = objectField(event, "usage");
@@ -1397,37 +2412,37 @@ class CodexJsonState {
     consume(line) {
         const event = parseJsonLine(line);
         if (!event) {
-            return null;
+            return [];
         }
         const type = stringField(event, "type") ?? "";
         if (type === "thread.started") {
             this.threadId = stringField(event, "thread_id");
             if (this.threadId && !this.emittedThread) {
                 this.emittedThread = true;
-                return {
-                    role: "runner",
-                    kind: "checkpoint",
-                    content: `Codex thread started: ${this.threadId}.`,
-                    eventType: "provider_thread_started"
-                };
+                return [{
+                        role: "runner",
+                        kind: "checkpoint",
+                        content: `Codex thread started: ${this.threadId}.`,
+                        eventType: "provider_thread_started"
+                    }];
             }
         }
         if (type === "turn.completed") {
             this.accumulateUsage(event);
-            return {
-                role: "runner",
-                kind: "checkpoint",
-                content: "Codex turn completed.",
-                eventType: "provider_turn_completed"
-            };
+            return [{
+                    role: "runner",
+                    kind: "checkpoint",
+                    content: "Codex turn completed.",
+                    eventType: "provider_turn_completed"
+                }];
         }
         if (type === "turn.failed" || type === "error") {
-            return {
-                role: "runner",
-                kind: "error",
-                content: clip(line.trim(), 1000),
-                eventType: "provider_cli_error"
-            };
+            return [{
+                    role: "runner",
+                    kind: "error",
+                    content: clip(line.trim(), 1000),
+                    eventType: "provider_cli_error"
+                }];
         }
         if (type === "item.completed" || type === "item.updated") {
             const item = objectField(event, "item");
@@ -1436,28 +2451,32 @@ class CodexJsonState {
                 const text = stringField(item, "text");
                 if (text) {
                     this.finalMessage = clip(text, 4000);
-                    return {
-                        role: "assistant",
-                        kind: "message",
-                        content: this.finalMessage,
-                        eventType: "provider_message"
-                    };
+                    return [{
+                            role: "assistant",
+                            kind: "message",
+                            content: this.finalMessage,
+                            eventType: "provider_message"
+                        }];
                 }
             }
             if (itemType === "command_execution") {
                 const command = stringField(item, "command");
                 const status = stringField(item, "status");
                 if (command) {
-                    return {
-                        role: "worker",
-                        kind: "checkpoint",
-                        content: `Codex command ${status || "completed"}: ${clip(command, 500)}`,
-                        eventType: "provider_command"
-                    };
+                    return [{
+                            role: "worker",
+                            kind: "checkpoint",
+                            content: `Codex command ${status || "completed"}: ${clip(command, 500)}`,
+                            eventType: "provider_command"
+                        }];
                 }
             }
         }
-        return null;
+        const mcpEvents = formatCodexMcpToolCallEvents(type, event);
+        if (mcpEvents.length > 0) {
+            return mcpEvents;
+        }
+        return [];
     }
     accumulateUsage(event) {
         const usage = objectField(event, "usage");
@@ -1473,6 +2492,113 @@ class CodexJsonState {
         });
     }
 }
+function formatCodexMcpToolCallEvents(type, event) {
+    if (type !== "item.started" && type !== "item.updated" && type !== "item.completed") {
+        return [];
+    }
+    const item = objectField(event, "item");
+    const itemType = stringField(item, "type") ?? "";
+    const serverName = mcpServerName(item);
+    const toolName = mcpToolName(item);
+    const isMcpItem = itemType.toLowerCase().includes("mcp")
+        || Boolean(serverName)
+        || (toolName ? isForgeCompletionTool(toolName) || toolName.toLowerCase().includes("mcp") : false);
+    if (!isMcpItem || !toolName) {
+        return [];
+    }
+    const status = normalizedString(stringField(item, "status")
+        ?? stringField(event, "status")
+        ?? (type === "item.started" ? "started" : type === "item.completed" ? "completed" : "updated"));
+    const failed = status === "failed" || status === "error" || status === "cancelled" || Boolean(item.error);
+    const completed = failed || type === "item.completed" || status === "completed" || status === "succeeded" || status === "success";
+    const started = type === "item.started" || status === "started" || status === "running" || status === "in_progress";
+    const data = safeProviderMcpData(item, serverName ?? "unknown", toolName, status);
+    const label = `${serverName ?? "unknown"}.${toolName}`;
+    if (failed) {
+        const summary = mcpErrorSummary(item) ?? "MCP tool call failed.";
+        const events = [{
+                role: "tool",
+                kind: "error",
+                content: `MCP tool call failed: ${label} - ${summary}`,
+                eventType: "provider_mcp_call_failed",
+                data
+            }];
+        if (isForgeCompletionTool(toolName)) {
+            events.push({
+                role: "tool",
+                kind: "error",
+                content: `Forge completion tool validation failed: ${label} - ${summary}`,
+                eventType: "completion_tool_validation_failed",
+                data
+            });
+        }
+        return events;
+    }
+    if (completed) {
+        return [{
+                role: "tool",
+                kind: "checkpoint",
+                content: `MCP tool call completed: ${label}.`,
+                eventType: "provider_mcp_call_completed",
+                data
+            }];
+    }
+    if (started) {
+        return [{
+                role: "tool",
+                kind: "checkpoint",
+                content: `MCP tool call started: ${label}.`,
+                eventType: "provider_mcp_call_started",
+                data
+            }];
+    }
+    return [];
+}
+function mcpServerName(item) {
+    return stringField(item, "server")
+        ?? stringField(item, "server_name")
+        ?? stringField(item, "mcp_server")
+        ?? stringField(objectField(item, "mcp"), "server")
+        ?? stringField(objectField(item, "mcp"), "server_name");
+}
+function mcpToolName(item) {
+    return stringField(item, "tool")
+        ?? stringField(item, "tool_name")
+        ?? stringField(item, "name")
+        ?? stringField(objectField(item, "function"), "name")
+        ?? stringField(objectField(item, "mcp"), "tool")
+        ?? stringField(objectField(item, "mcp"), "tool_name");
+}
+function mcpErrorSummary(item) {
+    const direct = stringField(item, "error")
+        ?? stringField(item, "error_message")
+        ?? stringField(item, "message");
+    if (direct) {
+        return clip(direct, 600);
+    }
+    const error = objectField(item, "error");
+    return stringField(error, "message")
+        ?? stringField(error, "summary")
+        ?? stringField(objectField(item, "result"), "error")
+        ?? null;
+}
+function safeProviderMcpData(item, serverName, toolName, status) {
+    const elapsedMs = numericField(item, "elapsed_ms") ?? numericField(item, "duration_ms");
+    return JSON.stringify(stripUndefined({
+        server_name: serverName,
+        tool_name: toolName,
+        status,
+        elapsed_ms: elapsedMs,
+        error_summary: mcpErrorSummary(item)
+    }));
+}
+function isForgeCompletionTool(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    return normalized.startsWith("forge.complete_")
+        || normalized.startsWith("complete_")
+        || normalized.includes("forge.complete_")
+        || normalized.includes("complete_architect_plan");
+}
 function objectField(source, key) {
     const value = source[key];
     return value && typeof value === "object" && !Array.isArray(value)
@@ -1483,6 +2609,16 @@ function stringField(source, key) {
     const value = source[key];
     return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
+function numericField(source, key) {
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function normalizedString(value) {
+    return value.trim().toLowerCase().replace(/-/g, "_");
+}
 function isNodeError(error) {
     return error instanceof Error && "code" in error;
 }