@loucompanion/forge-bridge 0.1.1-dev.2ac58b6f94ce → 0.1.1-dev.2d1a116ca78d

package/dist/session/phase-completion.js

@@ -7,6 +7,12 @@ import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from ".
 const toolServerName = "forge";
 const completionRedactionSecretsEnv = "FORGE_COMPLETION_REDACTION_SECRETS";
 const completionPhaseOrder = ["implementation", "self_review", "validation"];
+export const debugCompletionPhaseOrder = [
+    "debug_repro",
+    "debug_root_cause",
+    "debug_fix",
+    "debug_regression"
+];
 export const qaCompletionGateOrder = [
     "qa_plan",
     "qa_regression",
@@ -34,6 +40,12 @@ const qaGateToolNames = {
     qa_findings: "complete_qa_findings",
     qa_verdict: "complete_qa_verdict"
 };
+const debugGateToolNames = {
+    debug_repro: "complete_debug_repro",
+    debug_root_cause: "complete_debug_root_cause",
+    debug_fix: "complete_debug_fix",
+    debug_regression: "complete_debug_regression"
+};
 const qaBlockerReasons = new Set([
     "missing_app_launch_target",
     "inconclusive",
@@ -42,6 +54,8 @@ const qaBlockerReasons = new Set([
     "missing_worktree",
     "runner_failure"
 ]);
+const resolvedFindingStatusValues = ["resolved", "disputed", "not_reproduced"];
+const resolvedFindingStatuses = new Set(resolvedFindingStatusValues);
 const qaFindingSeverities = new Set(["critical", "major", "minor"]);
 const qaFindingScopes = new Set(["in_scope", "out_of_scope", "unclear"]);
 const qaCandidateBugActions = new Set(["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"]);
@@ -61,6 +75,26 @@ const phaseFiles = {
     qa: {
         jsonFileName: "qa.verdict.json",
         reportFileName: "qa.report.md"
+    },
+    debug_repro: {
+        jsonFileName: "debug.repro.json",
+        reportFileName: "debug.report.md"
+    },
+    debug_root_cause: {
+        jsonFileName: "debug.root-cause.json",
+        reportFileName: "debug.report.md"
+    },
+    debug_fix: {
+        jsonFileName: "debug.fix.json",
+        reportFileName: "debug.report.md"
+    },
+    debug_regression: {
+        jsonFileName: "debug.regression.json",
+        reportFileName: "debug.report.md"
+    },
+    architect: {
+        jsonFileName: "architect.verdict.json",
+        reportFileName: "architect.report.md"
     }
 };
 export function completionPhaseFromDispatch(dispatch) {
@@ -68,6 +102,10 @@ export function completionPhaseFromDispatch(dispatch) {
 }
 export function normalizeCompletionPhase(value) {
     const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
+    const debugPhase = normalizeDebugCompletionPhase(normalized);
+    if (debugPhase) {
+        return debugPhase;
+    }
     if (normalized === "self_review" || normalized === "selfreview" || normalized === "review") {
         return "self_review";
     }
@@ -77,6 +115,9 @@ export function normalizeCompletionPhase(value) {
     if (normalized === "qa" || normalized === "quality_assurance" || normalized === "qualityassurance") {
         return "qa";
     }
+    if (normalized === "architect" || normalized === "architect_plan" || normalized === "planning" || normalized === "plan") {
+        return "architect";
+    }
     return "implementation";
 }
 export function usesDevelopCycleCompletion(dispatch) {
@@ -97,37 +138,70 @@ export function usesQaCycleCompletion(dispatch) {
         && lane === "qa"
         && completionPhaseFromDispatch(dispatch) === "qa";
 }
+export function usesDebugCycleCompletion(dispatch) {
+    const kind = dispatch.cycleRun.kind.trim().toLowerCase();
+    const role = dispatch.execution.role.trim().toLowerCase();
+    const lane = dispatch.execution.lane.trim().toLowerCase();
+    return kind === "debug"
+        && role === "debug"
+        && lane === "debug"
+        && isDebugCompletionPhase(completionPhaseFromDispatch(dispatch));
+}
+export function usesArchitectCycleCompletion(dispatch) {
+    const kind = dispatch.cycleRun.kind.trim().toLowerCase();
+    const role = dispatch.execution.role.trim().toLowerCase();
+    const lane = dispatch.execution.lane.trim().toLowerCase();
+    return kind === "architect" || role === "architect" || lane === "architect";
+}
 export function completionToolNamesForPhase(phase) {
+    if (isDebugCompletionPhase(phase)) {
+        return completionToolNamesForDebugGate(phase);
+    }
     const base = phase === "implementation"
         ? "complete_implementation"
         : phase === "self_review"
             ? "complete_self_review"
             : phase === "validation"
                 ? "complete_validation"
-                : "complete_qa";
+                : phase === "architect"
+                    ? "complete_architect_plan"
+                    : "complete_qa";
     return [`forge.${base}`, base];
 }
 export function completionToolNamesForQaGate(gate) {
     const base = qaGateToolNames[gate];
     return [`forge.${base}`, base];
 }
+export function completionToolNamesForDebugGate(gate) {
+    const base = debugGateToolNames[gate];
+    return [`forge.${base}`, base];
+}
 export function expectedCompletionToolName(phase) {
     return completionToolNamesForPhase(phase)[0];
 }
 export function expectedQaCompletionToolName(gate) {
     return completionToolNamesForQaGate(gate)[0];
 }
+export function expectedDebugCompletionToolName(gate) {
+    return completionToolNamesForDebugGate(gate)[0];
+}
 export function artifactRootFor(worktreePath, workItemId) {
     return path.join(worktreePath, ".forge", "work-items", safePathSegment(workItemId, "work item id"), "artifacts");
 }
-function artifactRootForOwner(worktreePath, ownerType, ownerId) {
+export function artifactRootForOwner(worktreePath, ownerType, ownerId) {
     return path.join(worktreePath, ".forge", artifactOwnerDirectory(ownerType), safePathSegment(ownerId, "owner id"), "artifacts");
 }
-export function completionArtifactJsonPath(worktreePath, workItemId, phase) {
-    return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].jsonFileName);
+export function completionArtifactJsonPath(worktreePath, workItemId, phase, ownerType, ownerId) {
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    return path.join(artifactRoot, phaseFiles[phase].jsonFileName);
 }
-export function completionArtifactReportPath(worktreePath, workItemId, phase) {
-    return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].reportFileName);
+export function completionArtifactReportPath(worktreePath, workItemId, phase, ownerType, ownerId) {
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    return path.join(artifactRoot, phaseFiles[phase].reportFileName);
 }
 export async function prepareCompletionToolRuntime(options) {
     const phase = options.phase ?? completionPhaseFromDispatch(options.dispatch);
@@ -143,7 +217,9 @@ export async function prepareCompletionToolRuntime(options) {
         phase,
         producedBy: `${options.dispatch.execution.provider}-cli`,
         developCycle: usesDevelopCycleCompletion(options.dispatch),
-        qaCycle: usesQaCycleCompletion(options.dispatch)
+        qaCycle: usesQaCycleCompletion(options.dispatch),
+        debugCycle: usesDebugCycleCompletion(options.dispatch),
+        architectCycle: usesArchitectCycleCompletion(options.dispatch)
     });
     const runtime = {
         serverName: toolServerName,
@@ -179,6 +255,12 @@ export function buildCompletionToolServerArgs(config) {
     if (config.qaCycle) {
         args.push("--qa-cycle");
     }
+    if (config.debugCycle) {
+        args.push("--debug-cycle");
+    }
+    if (config.architectCycle) {
+        args.push("--architect-cycle");
+    }
     return args;
 }
 export function codexMcpConfigArgs(runtime) {
@@ -211,6 +293,17 @@ Do not write QA artifacts by hand. When QA is complete, call \`${toolName}(...)\
 That tool writes the durable QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`${artifactName}\`, and \`qa.report.md\`.
 Use \`status: "pass"\` only when the validated changes satisfy acceptance criteria with concrete evidence. Use \`status: "needs_rework"\` with actionable in-scope findings, or \`status: "blocked"\` with a concrete blocker_reason.
 Forge will mirror only the tool-written QA artifacts; reporting QA completion in prose is not enough.`;
+    }
+    if (phase === "architect") {
+        return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write Architect artifacts by hand. When the plan is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the full structured Architect planning payload.
+That tool writes \`.forge/work-items/{workItemId}/artifacts/implementation.plan.json\`, \`qa.plan.json\`, \`${artifactName}\`, and \`architect.report.md\`.
+The payload must put \`phases\`, \`tasks\`, \`dependencies\`, and \`phase_gates\` as top-level fields inside \`implementation_plan\`, for example:
+\`{ "status": "pass", "summary": "...", "implementation_plan": { "schema_version": 1, "plan_id": "plan-...", "phases": [{ "id": "phase-1", "tasks": ["task-1"], "gate": "gate-1" }], "tasks": [{ "id": "task-1", "tests": [{ "command": "npm test" }] }], "dependencies": [], "phase_gates": [{ "id": "gate-1", "phase": "phase-1" }] }, "qa_plan": { "schema_version": 1, "final_qa": [{ "id": "qa-1", "coverage": "..." }] }, "report_markdown": "# Architect Report" }\`.
+\`implementation_plan.tasks\` are Develop child tasks only: each task must require a focused repo/product implementation change. Put parent-story QA, sign-off, child-count/materialization inventory, parent plan artifact checks, and final integrated acceptance proof in \`qa_plan.final_qa\`, not as child Develop tasks.
+Dependency entries use canonical \`before\` and \`after\` task ids, for example \`{ "before": "task-1", "after": "task-2" }\`. Forge accepts \`from\`/\`to\` only as aliases and normalizes them before writing artifacts.
+Use \`status: "pass"\` for a valid pending-approval plan, \`needs_revision\` when story/design input must change, or \`blocked\` with a concrete blocker.
+Forge will mirror only the tool-written Architect artifacts; reporting the plan in prose is not enough.`;
     }
     return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
 Do not write phase artifacts by hand. When the phase is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required evidence payload.
@@ -242,12 +335,27 @@ Use \`status: "skipped"\` with a reason for gates that are not applicable. If a
 The final verdict tool writes the canonical QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`qa.verdict.json\`, and \`qa.report.md\`.
 The legacy \`forge.complete_qa\` one-shot tool is not available in normal QA-cycle mode. Reporting QA completion in prose is not enough.`;
 }
+export function completionPromptForDebugCycle(currentGate = "debug_repro") {
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write Debug artifacts by hand. The tool server enforces Debug gate order and starts this run at \`${currentGate}\`.
+Complete the Debug cycle in order inside this same provider session:
+1. Reproduce or tightly characterize the bug, then call \`forge.complete_debug_repro(...)\`.
+2. Follow the returned root-cause instruction, isolate evidence, then call \`forge.complete_debug_root_cause(...)\`.
+3. Follow the returned fix instruction, apply the smallest safe fix with regression coverage when practical, then call \`forge.complete_debug_fix(...)\`.
+4. Follow the returned regression instruction, prove the original repro is negative and the fix is QA-ready, then call \`forge.complete_debug_regression(...)\`.
+Each tool writes a canonical Debug artifact under \`.forge/work-items/{workItemId}/artifacts/\`: \`debug.repro.json\`, \`debug.root-cause.json\`, \`debug.fix.json\`, and \`debug.regression.json\` plus \`debug.report.md\` when report text is provided or generated.
+Use a non-pass status with explicit blockers when the current Debug gate cannot pass. Reporting Debug completion in prose is not enough; the relevant MCP completion tool is the transition request.`;
+}
 export function completionToolNamesForServer(config) {
-    return config.qaCycle
-        ? qaCompletionGateOrder.flatMap((gate) => completionToolNamesForQaGate(gate))
-        : config.developCycle
-            ? completionPhaseOrder.flatMap((phase) => completionToolNamesForPhase(phase))
-            : completionToolNamesForPhase(config.phase);
+    return config.debugCycle
+        ? debugCompletionPhaseOrder.flatMap((gate) => completionToolNamesForDebugGate(gate))
+        : config.qaCycle
+            ? qaCompletionGateOrder.flatMap((gate) => completionToolNamesForQaGate(gate))
+            : config.developCycle
+                ? completionPhaseOrder.flatMap((phase) => completionToolNamesForPhase(phase))
+                : config.architectCycle
+                    ? completionToolNamesForPhase("architect")
+                    : completionToolNamesForPhase(config.phase);
 }
 export class CompletionToolServerSession {
     config;
@@ -259,11 +367,13 @@ export class CompletionToolServerSession {
         this.currentPhase = config.phase;
     }
     get instructions() {
-        return this.config.qaCycle
-            ? completionPromptForQaCycle(this.currentQaGate)
-            : this.config.developCycle
-                ? completionPromptForDevelopCycle(this.currentPhase)
-                : completionPromptForPhase(this.currentPhase);
+        return this.config.debugCycle
+            ? completionPromptForDebugCycle(asDebugCompletionPhase(this.currentPhase))
+            : this.config.qaCycle
+                ? completionPromptForQaCycle(this.currentQaGate)
+                : this.config.developCycle
+                    ? completionPromptForDevelopCycle(this.currentPhase)
+                    : completionPromptForPhase(this.currentPhase);
     }
     toolDefinitions() {
         return completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name), qaGateFromToolName(name)));
@@ -273,6 +383,9 @@ export class CompletionToolServerSession {
         if (this.completed) {
             throw new Error("Forge completion cycle is already complete; no more completion calls are accepted.");
         }
+        if (this.config.debugCycle) {
+            return await this.callDebugGateTool(toolName, requestedPhase, input);
+        }
         if (this.config.qaCycle) {
             return await this.callQaGateTool(toolName, requestedPhase, input);
         }
@@ -310,6 +423,44 @@ export class CompletionToolServerSession {
             }
         };
     }
+    async callDebugGateTool(toolName, requestedPhase, input) {
+        const currentDebugGate = asDebugCompletionPhase(this.currentPhase);
+        if (!isDebugCompletionPhase(requestedPhase)) {
+            throw new Error(`Tool ${toolName} is not available in Debug-cycle mode. Current Forge Debug gate is ${currentDebugGate}.`);
+        }
+        if (requestedPhase !== currentDebugGate) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge Debug gate is ${currentDebugGate}.`);
+        }
+        const completedGate = currentDebugGate;
+        const reference = await writeCompletionArtifact({ ...this.config, phase: completedGate }, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const pass = status === "pass";
+        const nextGate = pass ? this.advanceAfterDebugGate(completedGate) : completedGate;
+        const nextPhase = nextGate ?? "qa_ready";
+        const nextInstruction = completionToolNextInstructionForDebugGate(completedGate, status, nextGate);
+        const reason = pass
+            ? `${completedGate} artifact accepted${nextGate ? `; continue to ${nextGate}.` : "; Debug regression is QA-ready."}`
+            : `${completedGate} artifact recorded with status ${status}; rework is required before Debug progression.`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}`
+                }
+            ],
+            structuredContent: {
+                ...reference,
+                gate: {
+                    phase: completedGate,
+                    status,
+                    allowed: pass,
+                    reason
+                },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
     async callQaGateTool(toolName, requestedPhase, input) {
         const requestedGate = qaGateFromToolName(toolName);
         if (requestedPhase !== "qa" || !requestedGate) {
@@ -354,6 +505,9 @@ export class CompletionToolServerSession {
             this.completed = true;
             return "sign_off_ready";
         }
+        if (isDebugCompletionPhase(phase)) {
+            return nextDebugPhaseAfter(phase) ?? "qa_ready";
+        }
         const next = nextPhaseAfter(phase);
         if (!this.config.developCycle) {
             return next ?? "dev_test_ready";
@@ -375,6 +529,16 @@ export class CompletionToolServerSession {
         this.completed = true;
         return null;
     }
+    advanceAfterDebugGate(gate) {
+        const index = debugCompletionPhaseOrder.indexOf(gate);
+        const next = index >= 0 ? debugCompletionPhaseOrder[index + 1] ?? null : null;
+        if (next) {
+            this.currentPhase = next;
+            return next;
+        }
+        this.completed = true;
+        return null;
+    }
 }
 export async function writeCompletionArtifact(config, toolName, input) {
     const phase = phaseFromToolName(toolName);
@@ -387,7 +551,10 @@ export async function writeCompletionArtifact(config, toolName, input) {
     }
     const payload = asRecord(input, "completion payload");
     const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
-    const validationPayload = { ...payload, status };
+    let validationPayload = { ...payload, status };
+    if (config.qaCycle && qaGate === "qa_verdict") {
+        validationPayload = await synthesizeQaCycleVerdictPayload(config, validationPayload, status);
+    }
     validatePayloadShape(phase, validationPayload);
     validateOptionalWorkItemId(validationPayload, config.workItemId);
     const redactedPayload = redactSecrets(validationPayload, config.redactionSecrets ?? []);
@@ -398,6 +565,9 @@ export async function writeCompletionArtifact(config, toolName, input) {
     if (phase === "qa") {
         return await writeQaCompletionArtifact(config, redactedPayload, status, producedBy);
     }
+    if (phase === "architect") {
+        return await writeArchitectCompletionArtifact(config, redactedPayload, status, producedBy);
+    }
     const artifactWithoutHash = normalizeArtifactPayload(redactedPayload, {
         phase,
         workItemId: config.workItemId,
@@ -430,6 +600,48 @@ export async function writeCompletionArtifact(config, toolName, input) {
         producedBy
     };
 }
+async function writeArchitectCompletionArtifact(config, payload, status, producedBy) {
+    const ownerFields = artifactOwnerFields(config);
+    const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
+        ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
+        : artifactRootFor(config.worktreePath, config.workItemId);
+    const implementationPlanPath = path.join(artifactRoot, "implementation.plan.json");
+    const qaPlanPath = path.join(artifactRoot, "qa.plan.json");
+    const verdictPath = path.join(artifactRoot, "architect.verdict.json");
+    const reportPath = path.join(artifactRoot, "architect.report.md");
+    const implementationPlan = requiredRecord(payload, "implementation_plan");
+    const qaPlan = requiredRecord(payload, "qa_plan");
+    const report = optionalString(payload, "report") ?? optionalString(payload, "report_markdown") ?? reportMarkdown(payload, "architect", status, producedBy, "pending");
+    const artifactWithoutHash = normalizeArtifactPayload(payload, {
+        phase: "architect",
+        workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
+        producedBy,
+        status
+    });
+    const contentHash = sha256(stableStringify(artifactWithoutHash));
+    const verdict = {
+        ...artifactWithoutHash,
+        content_hash: contentHash
+    };
+    await fs.mkdir(artifactRoot, { recursive: true });
+    await writeFileAtomic(implementationPlanPath, jsonText(implementationPlan));
+    await writeFileAtomic(qaPlanPath, jsonText(qaPlan));
+    await writeFileAtomic(verdictPath, jsonText(verdict));
+    await writeFileAtomic(reportPath, `${report.trim()}\n`);
+    return {
+        phase: "architect",
+        workItemId: config.workItemId,
+        ...artifactReferenceOwnerFields(config),
+        repoPath: path.resolve(config.worktreePath),
+        path: verdictPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
 async function writeQaGateCompletionArtifact(config, gate, input) {
     const payload = asRecord(input, "QA gate completion payload");
     const status = normalizeQaGateStatus(requiredString(payload, "status"));
@@ -585,6 +797,133 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
         producedBy
     };
 }
+async function synthesizeQaCycleVerdictPayload(config, payload, status) {
+    const qaPlan = await readQaGateArtifact(config, "qa_plan");
+    const qaRegression = await readQaGateArtifact(config, "qa_regression");
+    const qaApi = await readQaGateArtifact(config, "qa_api");
+    const qaManualWeb = await readQaGateArtifact(config, "qa_manual_web");
+    const qaBugRepro = await readQaGateArtifact(config, "qa_bug_repro");
+    const qaFindings = await readQaGateArtifact(config, "qa_findings");
+    const evidenceGates = [qaRegression, qaApi, qaManualWeb, qaBugRepro];
+    const payloadEvidence = qaEvidenceSource(payload);
+    const merged = { ...payload };
+    const checklist = qaStringArray(payload, "checklist");
+    if (checklist.length === 0) {
+        const plannedChecklist = qaStringArray(qaPlan, "checklist");
+        merged.checklist = plannedChecklist.length > 0 ? plannedChecklist : defaultQaChecklist(status);
+    }
+    const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
+    if (testedAcceptanceCriteria.length === 0) {
+        const plannedAcceptanceCriteria = qaStringArray(qaPlan, "acceptance_criteria");
+        const payloadAcceptanceCriteria = qaStringArray(payload, "acceptance_criteria");
+        const acceptanceCriteria = plannedAcceptanceCriteria.length > 0 ? plannedAcceptanceCriteria : payloadAcceptanceCriteria;
+        if (acceptanceCriteria.length > 0) {
+            merged.tested_acceptance_criteria = acceptanceCriteria;
+        }
+    }
+    const payloadCommands = qaArray(payload, "commands", payloadEvidence);
+    const inheritedCommands = evidenceGates.flatMap((gate) => qaArray(gate, "commands"));
+    const inheritedDiagnosticCommandNotes = status === "pass"
+        ? qaNonPassingCommandNotes(inheritedCommands)
+        : [];
+    merged.commands = dedupeUnknownArray([
+        ...payloadCommands,
+        ...(status === "pass" ? inheritedCommands.filter(isQaPassingCommandEvidence) : inheritedCommands)
+    ]);
+    merged.browser_checks = dedupeUnknownArray([
+        ...qaArray(payload, "browser_checks", payloadEvidence),
+        ...evidenceGates.flatMap((gate) => qaArray(gate, "browser_checks"))
+    ]);
+    merged.sidecars = dedupeUnknownArray([
+        ...qaArray(payload, "sidecars", payloadEvidence),
+        ...evidenceGates.flatMap((gate) => qaArray(gate, "sidecars"))
+    ]);
+    const notes = dedupeStrings([
+        optionalString(payload, "notes"),
+        optionalString(payloadEvidence, "notes"),
+        ...evidenceGates.map((gate) => optionalString(gate, "notes")),
+        ...inheritedDiagnosticCommandNotes
+    ]);
+    if (notes.length > 0) {
+        merged.notes = notes.join("\n");
+    }
+    merged.findings = mergeQaObjectArraysById(qaObjectArray(payload, "findings"), qaObjectArray(qaFindings, "findings"));
+    merged.candidate_bugs = mergeQaObjectArraysById(qaObjectArray(payload, "candidate_bugs"), qaObjectArray(qaFindings, "candidate_bugs"));
+    return merged;
+}
+async function readQaGateArtifact(config, gate) {
+    const ownerFields = artifactOwnerFields(config);
+    const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
+        ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
+        : artifactRootFor(config.worktreePath, config.workItemId);
+    const artifactPath = path.join(artifactRoot, qaGateFileNames[gate]);
+    const content = await readOptionalFile(artifactPath);
+    return content === null ? {} : parseOptionalJsonObject(content, qaGateFileNames[gate]);
+}
+function dedupeUnknownArray(values) {
+    const seen = new Set();
+    const deduped = [];
+    for (const value of values) {
+        const key = stableStringify(value);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(value);
+    }
+    return deduped;
+}
+function isQaPassingCommandEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return record.exit_code === 0 && normalizedString(record.status) === "pass";
+}
+function qaNonPassingCommandNotes(values) {
+    return values
+        .filter((value) => !isQaPassingCommandEvidence(value))
+        .map((value, index) => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return `QA diagnostic command ${index + 1} was omitted from pass evidence because it was not a structured passing command.`;
+        }
+        const record = value;
+        const command = optionalString(record, "command") ?? "<missing command>";
+        const status = optionalString(record, "status") ?? "<missing status>";
+        const exitCode = typeof record.exit_code === "number" && Number.isFinite(record.exit_code)
+            ? String(record.exit_code)
+            : "<missing exit_code>";
+        const summary = optionalString(record, "summary");
+        return `QA diagnostic command omitted from pass evidence: ${command} (status ${status}, exit_code ${exitCode})${summary ? ` — ${summary}` : ""}.`;
+    });
+}
+function mergeQaObjectArraysById(primary, fallback) {
+    const seen = new Set();
+    const merged = [];
+    for (const value of [...primary, ...fallback]) {
+        const id = optionalString(value, "id");
+        const key = id ? `id:${id}` : stableStringify(value);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        merged.push(value);
+    }
+    return merged;
+}
+function dedupeStrings(values) {
+    const seen = new Set();
+    const deduped = [];
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (!trimmed || seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        deduped.push(trimmed);
+    }
+    return deduped;
+}
 async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, ownerType, ownerId) {
     if (sidecars.length === 0) {
         return [];
@@ -638,19 +977,28 @@ async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, o
     }
     return validated;
 }
-export async function readCompletionArtifact(worktreePath, workItemId, phase) {
-    const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase);
-    const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase);
+export async function readCompletionArtifact(worktreePath, workItemId, phase, ownerType, ownerId) {
+    const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase, ownerType, ownerId);
+    const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase, ownerType, ownerId);
     const verdictJson = await readOptionalFile(artifactPath);
     if (verdictJson === null) {
         return null;
     }
     const parsed = parseJsonObject(verdictJson, artifactPath);
     const report = await readOptionalFile(reportPath) ?? fallbackReport(parsed, phase, artifactPath);
+    const artifactRoot = path.dirname(artifactPath);
+    const implementationPlanJson = phase === "architect"
+        ? await readOptionalFile(path.join(artifactRoot, "implementation.plan.json"))
+        : null;
+    const qaPlanJson = phase === "architect"
+        ? await readOptionalFile(path.join(artifactRoot, "qa.plan.json"))
+        : null;
     return {
         repoPath: path.resolve(worktreePath),
         path: artifactPath,
         verdictJson,
+        implementationPlanJson,
+        qaPlanJson,
         report,
         producedBy: optionalString(parsed, "produced_by") ?? optionalString(parsed, "producedBy") ?? "forge-completion-tool",
         status: optionalString(parsed, "status") ?? "unknown",
@@ -687,6 +1035,8 @@ export function parseCompletionMcpArgs(argv) {
     let producedBy;
     let developCycle = false;
     let qaCycle = false;
+    let debugCycle = false;
+    let architectCycle = false;
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === "--worktree") {
@@ -708,7 +1058,7 @@ export function parseCompletionMcpArgs(argv) {
             const rawPhase = argv[++index];
             const parsedPhase = parseStrictCompletionPhase(rawPhase);
             if (!parsedPhase) {
-                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation, qa." };
+                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation, qa, architect, debug-repro, debug-root-cause, debug-fix, debug-regression." };
             }
             phase = parsedPhase;
         }
@@ -721,6 +1071,12 @@ export function parseCompletionMcpArgs(argv) {
         else if (arg === "--qa-cycle") {
             qaCycle = true;
         }
+        else if (arg === "--debug-cycle") {
+            debugCycle = true;
+        }
+        else if (arg === "--architect-cycle") {
+            architectCycle = true;
+        }
         else {
             return { ok: false, error: `Unknown mcp argument: ${arg}` };
         }
@@ -728,12 +1084,21 @@ export function parseCompletionMcpArgs(argv) {
     if (!worktreePath?.trim() || !workItemId?.trim()) {
         return { ok: false, error: "mcp requires --worktree and --work-item-id." };
     }
-    if (developCycle && qaCycle) {
+    if ([developCycle, qaCycle, debugCycle, architectCycle].filter(Boolean).length > 1) {
         return { ok: false, error: "mcp accepts only one cycle mode." };
     }
+    if (developCycle && !isDevelopCompletionPhase(phase)) {
+        return { ok: false, error: "mcp --develop-cycle requires --phase implementation, self-review, or validation." };
+    }
     if (qaCycle && phase !== "qa") {
         return { ok: false, error: "mcp --qa-cycle requires --phase qa." };
     }
+    if (debugCycle && !isDebugCompletionPhase(phase)) {
+        return { ok: false, error: "mcp --debug-cycle requires --phase debug-repro, debug-root-cause, debug-fix, or debug-regression." };
+    }
+    if (architectCycle && phase !== "architect") {
+        return { ok: false, error: "mcp --architect-cycle requires --phase architect." };
+    }
     return {
         ok: true,
         config: {
@@ -745,7 +1110,9 @@ export function parseCompletionMcpArgs(argv) {
             producedBy,
             redactionSecrets: parseCompletionRedactionSecrets(process.env[completionRedactionSecretsEnv]),
             developCycle,
-            qaCycle
+            qaCycle,
+            debugCycle,
+            architectCycle
         }
     };
 }
@@ -848,9 +1215,16 @@ function toolDefinition(name, phase, qaGate = null) {
     };
 }
 function nextPhaseAfter(phase) {
+    if (!isDevelopCompletionPhase(phase)) {
+        return null;
+    }
     const index = completionPhaseOrder.indexOf(phase);
     return index >= 0 ? completionPhaseOrder[index + 1] ?? null : null;
 }
+function nextDebugPhaseAfter(phase) {
+    const index = debugCompletionPhaseOrder.indexOf(phase);
+    return index >= 0 ? debugCompletionPhaseOrder[index + 1] ?? null : null;
+}
 function completionToolNextInstruction(completedPhase, status, nextPhase) {
     if (completedPhase === "qa") {
         if (status === "blocked") {
@@ -864,6 +1238,10 @@ function completionToolNextInstruction(completedPhase, status, nextPhase) {
     if (status !== "pass") {
         return `Stay in ${completedPhase}, address the recorded blockers, then call ${expectedCompletionToolName(completedPhase)} again.`;
     }
+    if (isDebugCompletionPhase(completedPhase)) {
+        const debugNext = isDebugCompletionPhase(nextPhase) ? nextPhase : null;
+        return completionToolNextInstructionForDebugGate(completedPhase, status, debugNext);
+    }
     if (nextPhase === "self_review") {
         return "Implementation accepted. Begin self-review: inspect the diff, apply safe fixes, and call forge.complete_self_review with review evidence.";
     }
@@ -891,6 +1269,21 @@ function completionToolNextInstructionForQaGate(completedGate, status, nextGate)
             : `${completedGate} accepted. Continue to ${nextGate}.`;
     return `${prefix} ${qaGateInstruction(nextGate)}`;
 }
+function completionToolNextInstructionForDebugGate(completedGate, status, nextGate) {
+    if (status !== "pass") {
+        return `Stay in ${completedGate}, address the recorded blockers, then call ${expectedDebugCompletionToolName(completedGate)} again.`;
+    }
+    if (nextGate === "debug_root_cause") {
+        return "Debug repro accepted. Begin root-cause analysis: connect the observed failure to code evidence and call forge.complete_debug_root_cause.";
+    }
+    if (nextGate === "debug_fix") {
+        return "Debug root cause accepted. Apply the smallest safe fix with regression coverage where practical, then call forge.complete_debug_fix.";
+    }
+    if (nextGate === "debug_regression") {
+        return "Debug fix accepted. Prove the original repro is negative, run targeted regression checks, and call forge.complete_debug_regression.";
+    }
+    return "Debug regression accepted. Forge has the structured evidence needed to move this bug fix to QA.";
+}
 function qaGateInstruction(gate) {
     switch (gate) {
         case "qa_regression":
@@ -915,6 +1308,9 @@ function toolDescription(phase, qaGate = null) {
             ? "Complete the final Forge QA verdict by writing the canonical QA bundle with pass, needs_rework, or blocked evidence."
             : `Complete the ${qaGate.replace(/_/g, " ")} QA gate by writing ${qaGateFileNames[qaGate]} before continuing to the next QA gate.`;
     }
+    if (isDebugCompletionPhase(phase)) {
+        return `Complete the ${phase.replace(/_/g, " ")} Debug gate by writing ${phaseFiles[phase].jsonFileName} with structured bug-fix evidence before continuing.`;
+    }
     if (phase === "implementation") {
         return "Complete Forge implementation by writing implementation.completeness.json with scoped changed-file, verification, acceptance-criteria, gap, and next-phase evidence.";
     }
@@ -924,6 +1320,9 @@ function toolDescription(phase, qaGate = null) {
     if (phase === "qa") {
         return "Complete Forge QA by writing qa.plan.json, qa.evidence.json, qa.findings.json, qa.verdict.json, and qa.report.md with structured pass, needs-rework, or blocked evidence.";
     }
+    if (phase === "architect") {
+        return "Complete Forge Architect planning by writing implementation.plan.json, qa.plan.json, architect.verdict.json, and architect.report.md with a pending-approval plan or explicit revision/blocker reasons.";
+    }
     return "Complete Forge validation by writing validation.verdict.json with command, build/test/lint/design, drift, acceptance-criteria, and ready-for-dev-test evidence.";
 }
 function toolInputSchema(phase, qaGate = null) {
@@ -948,6 +1347,9 @@ function toolInputSchema(phase, qaGate = null) {
     if (qaGate && qaGate !== "qa_verdict") {
         return qaGateToolInputSchema(qaGate);
     }
+    if (isDebugCompletionPhase(phase)) {
+        return debugToolInputSchema(phase, baseProperties);
+    }
     if (phase === "implementation") {
         return objectToolSchema({
             ...baseProperties,
@@ -970,7 +1372,7 @@ function toolInputSchema(phase, qaGate = null) {
             },
             tests_added_or_updated: {
                 type: "array",
-                description: "Required for pass. Use an object explaining why no tests were needed for docs/config-only work if empty would be ambiguous.",
+                description: "Required for pass. Use an object explaining why no tests were needed for documentation/config-only work if empty would be ambiguous.",
                 items: evidenceObjectSchema(["path", "summary"], {
                     path: { type: "string" },
                     summary: { type: "string" }
@@ -1001,6 +1403,11 @@ function toolInputSchema(phase, qaGate = null) {
             },
             next_phase_context: {
                 description: "Required for pass. Context the self-review phase should carry forward."
+            },
+            resolved_findings: {
+                type: "array",
+                description: "Required for QA rework. Each entry must use status resolved, disputed, or not_reproduced.",
+                items: resolvedFindingSchema()
             }
         }, ["status", "summary"], "For status pass, include plan, changed_files, tests_added_or_updated, docs_added_or_updated, acceptance_criteria, known_gaps, and next_phase_context. Acceptance criteria entries must use status: satisfied plus evidence.");
     }
@@ -1136,6 +1543,83 @@ function toolInputSchema(phase, qaGate = null) {
             }
         }, ["status", "summary"], "For pass, include tested_acceptance_criteria plus concrete command/browser/note evidence. For needs_rework, include at least one actionable in_scope finding. For blocked, include blocker_reason.");
     }
+    if (phase === "architect") {
+        return objectToolSchema({
+            status: {
+                type: "string",
+                enum: ["pass", "needs_revision", "blocked"],
+                description: "Use pass only for a complete pending-approval Architect plan. Use needs_revision for fixable story/design/repo gaps, or blocked for missing required context or decisions."
+            },
+            summary: { type: "string", description: "Concise Architect plan verdict summary." },
+            implementation_plan: {
+                type: "object",
+                description: "Required for pass. Top-level fields inside this object must include schema_version, plan_id, phases, tasks, dependencies, and phase_gates.",
+                additionalProperties: true,
+                properties: {
+                    schema_version: { type: "number", enum: [1] },
+                    plan_id: { type: "string" },
+                    phases: {
+                        type: "array",
+                        description: "Required top-level implementation_plan.phases array.",
+                        items: { type: "object", additionalProperties: true }
+                    },
+                    tasks: {
+                        type: "array",
+                        description: "Required Develop child task list. Each task must include id and a non-empty tests array, and must require a focused repo/product implementation change. Do not put parent-story QA/sign-off, child-count/materialization inventory, parent plan artifact checks, or final acceptance proof here; those belong in qa_plan.final_qa.",
+                        items: { type: "object", additionalProperties: true }
+                    },
+                    dependencies: {
+                        type: "array",
+                        description: "Required dependency edge array. Use [] when no task dependencies exist. Each edge should use before and after task ids; from/to are accepted only as aliases and normalized before writing artifacts.",
+                        items: {
+                            type: "object",
+                            additionalProperties: true,
+                            properties: {
+                                id: { type: "string" },
+                                before: { type: "string", description: "Task id that must complete first." },
+                                after: { type: "string", description: "Task id that depends on before." },
+                                from: { type: "string", description: "Alias for before." },
+                                to: { type: "string", description: "Alias for after." },
+                                type: { type: "string" },
+                                rationale: { type: "string" }
+                            }
+                        }
+                    },
+                    phase_gates: {
+                        type: "array",
+                        description: "Required non-empty phase gate array.",
+                        items: { type: "object", additionalProperties: true }
+                    }
+                }
+            },
+            qa_plan: {
+                type: "object",
+                description: "Required for pass. Must include schema_version: 1 and non-empty final_qa coverage.",
+                additionalProperties: true,
+                properties: {
+                    schema_version: { type: "number", enum: [1] },
+                    final_qa: {
+                        type: "array",
+                        description: "Required non-empty final QA coverage array.",
+                        items: { type: "object", additionalProperties: true }
+                    }
+                }
+            },
+            report_markdown: { type: "string", description: "Human-readable Architect report. Use report as an alias only when the client cannot send report_markdown." },
+            report: { type: "string", description: "Alias for report_markdown." },
+            blockers: baseProperties.blockers,
+            revision_questions: {
+                type: "array",
+                description: "Required for needs_revision when blockers are not used.",
+                items: { type: "string" }
+            },
+            revision_reasons: {
+                type: "array",
+                description: "Concrete reasons that prevent pass status.",
+                items: { type: "string" }
+            }
+        }, ["status", "summary"], "For status pass, include implementation_plan and qa_plan at the top level of the MCP tool arguments. implementation_plan.phases must be a top-level array inside implementation_plan, not nested under another object.");
+    }
     return objectToolSchema({
         ...baseProperties,
         commands: {
@@ -1160,6 +1644,84 @@ function toolInputSchema(phase, qaGate = null) {
         ready_for_dev_test: { type: "boolean", description: "Required for pass and must be true." }
     }, ["status", "summary"], "For status pass, commands must include at least one passing deterministic command, acceptance criteria entries must use status: satisfied plus evidence, and ready_for_dev_test must be true.");
 }
+function debugToolInputSchema(phase, baseProperties) {
+    if (phase === "debug_repro") {
+        return objectToolSchema({
+            ...baseProperties,
+            repro_steps: {
+                type: "array",
+                description: "Required for pass. Minimal reproduction or characterization steps.",
+                items: { type: "string" }
+            },
+            observed: { type: "string", description: "Observed failure behavior." },
+            expected: { type: "string", description: "Expected behavior." },
+            evidence: {
+                type: "array",
+                description: "Required for pass. Concrete logs, commands, screenshots, file refs, or characterization notes.",
+                items: { type: "object", additionalProperties: true }
+            }
+        }, ["status", "summary"], "For status pass, include repro_steps, observed, expected, and evidence.");
+    }
+    if (phase === "debug_root_cause") {
+        return objectToolSchema({
+            ...baseProperties,
+            root_cause: { type: "string", description: "Likely root cause tied to code or config evidence." },
+            evidence: {
+                type: "array",
+                description: "Required for pass. Concrete code/log/test evidence supporting the root cause.",
+                items: { type: "object", additionalProperties: true }
+            },
+            eliminated_alternatives: {
+                type: "array",
+                description: "Required for pass. Plausible alternatives checked or ruled out.",
+                items: { type: "object", additionalProperties: true }
+            },
+            risk_area: { type: "string", description: "Subsystem or behavior most at risk from the fix." }
+        }, ["status", "summary"], "For status pass, include root_cause, evidence, eliminated_alternatives, and risk_area.");
+    }
+    if (phase === "debug_fix") {
+        return objectToolSchema({
+            ...baseProperties,
+            changed_files: {
+                type: "array",
+                description: "Required for pass. Files changed by the bug fix.",
+                items: evidenceObjectSchema(["path", "summary"], { path: { type: "string" }, summary: { type: "string" } })
+            },
+            tests_added_or_updated: {
+                type: "array",
+                description: "Required for pass. Regression tests or checks added/updated, or justify omission in remaining_risks.",
+                items: evidenceObjectSchema(["path", "summary"], { path: { type: "string" }, summary: { type: "string" } })
+            },
+            remaining_risks: {
+                type: "array",
+                description: "Required for pass, even when empty. Include why no regression coverage changed when tests_added_or_updated is empty.",
+                items: evidenceObjectSchema(["summary"], { summary: { type: "string" }, mitigation: { type: "string" } })
+            },
+            resolved_findings: {
+                type: "array",
+                description: "Required for QA rework. Each entry must use status resolved, disputed, or not_reproduced.",
+                items: resolvedFindingSchema()
+            }
+        }, ["status", "summary"], "For status pass, include changed_files, tests_added_or_updated, and remaining_risks.");
+    }
+    return objectToolSchema({
+        ...baseProperties,
+        commands: {
+            type: "array",
+            description: "Required for pass. Targeted regression/repro-negative commands with exit_code: 0 and status: pass.",
+            items: commandEvidenceSchema()
+        },
+        required_regressions: {
+            type: "array",
+            description: "Required for pass. Repro-negative and regression coverage checklist.",
+            items: { type: "string" }
+        },
+        build_status: { type: "string", description: "Required for pass. pass or not_applicable." },
+        test_status: { type: "string", description: "Required for pass. pass or not_applicable." },
+        repro_negative: { type: "boolean", description: "Required for pass and must be true after the original repro no longer fails." },
+        qa_ready: { type: "boolean", description: "Required for pass and must be true." }
+    }, ["status", "summary"], "For status pass, commands must include at least one passing deterministic debug regression check, repro_negative must be true, and qa_ready must be true.");
+}
 function qaGateToolInputSchema(gate) {
     const baseProperties = {
         status: {
@@ -1245,6 +1807,29 @@ function commandEvidenceSchema() {
         summary: { type: "string" }
     });
 }
+function resolvedFindingSchema() {
+    return evidenceObjectSchema([
+        "qa_id",
+        "status",
+        "summary",
+        "evidence",
+        "changed_files",
+        "tests_added_or_updated",
+        "regression_evidence"
+    ], {
+        qa_id: { type: "string" },
+        status: {
+            type: "string",
+            enum: [...resolvedFindingStatusValues],
+            description: "Use resolved when fixed, disputed when the QA finding is incorrect/out-of-scope, or not_reproduced when retesting cannot reproduce it."
+        },
+        summary: { type: "string" },
+        evidence: { description: "Concrete evidence for the resolution." },
+        changed_files: { type: "array", description: "Required and non-empty when status is resolved." },
+        tests_added_or_updated: { type: "array", description: "Required and non-empty when status is resolved." },
+        regression_evidence: { description: "Concrete regression evidence for this QA finding." }
+    });
+}
 function acceptanceCriteriaSchema() {
     return {
         type: "array",
@@ -1279,6 +1864,13 @@ function normalizeCompletionStatus(value, phase) {
         }
         return canonical;
     }
+    if (phase === "architect") {
+        const canonical = normalized === "needsrevision" ? "needs_revision" : normalized;
+        if (canonical !== "pass" && canonical !== "needs_revision" && canonical !== "blocked") {
+            throw new Error("Architect status must be pass, needs_revision, or blocked.");
+        }
+        return canonical;
+    }
     const canonical = normalized === "blocked" || normalized === "needsrework"
         ? "needs_rework"
         : normalized === "failed"
@@ -1306,11 +1898,19 @@ function validatePayloadShape(phase, payload) {
         validateQaPayloadShape(payload, status);
         return;
     }
+    if (phase === "architect") {
+        validateArchitectPayloadShape(payload, status);
+        return;
+    }
     const pass = status === "pass";
     if (!pass) {
         requireNonPassEvidence(payload);
         return;
     }
+    if (isDebugCompletionPhase(phase)) {
+        validateDebugPayloadShape(phase, payload);
+        return;
+    }
     if (phase === "implementation") {
         requireArray(payload, "plan");
         requireArray(payload, "changed_files");
@@ -1321,6 +1921,7 @@ function validatePayloadShape(phase, payload) {
         requireField(payload, "next_phase_context");
         requireImplementationEvidence(payload);
         requireSatisfiedAcceptanceCriteria(payload);
+        validateResolvedFindings(payload);
         return;
     }
     if (phase === "self_review") {
@@ -1348,6 +1949,52 @@ function validatePayloadShape(phase, payload) {
     requirePassingCommands(payload);
     requireSatisfiedAcceptanceCriteria(payload);
 }
+function validateDebugPayloadShape(phase, payload) {
+    if (phase === "debug_repro") {
+        requireArray(payload, "repro_steps");
+        requireField(payload, "observed");
+        requireField(payload, "expected");
+        requireArray(payload, "evidence");
+        requireNonEmptyArray(payload, "repro_steps");
+        requireNonEmptyArray(payload, "evidence");
+        return;
+    }
+    if (phase === "debug_root_cause") {
+        requireField(payload, "root_cause");
+        requireArray(payload, "evidence");
+        requireArray(payload, "eliminated_alternatives");
+        requireField(payload, "risk_area");
+        requireNonEmptyArray(payload, "evidence");
+        return;
+    }
+    if (phase === "debug_fix") {
+        requireArray(payload, "changed_files");
+        requireArray(payload, "tests_added_or_updated");
+        requireArray(payload, "remaining_risks");
+        requireNonEmptyArray(payload, "changed_files");
+        if (arrayLength(payload, "tests_added_or_updated") === 0 && arrayLength(payload, "remaining_risks") === 0) {
+            throw new Error("tests_added_or_updated is empty; remaining_risks must explain why no regression coverage changed.");
+        }
+        validateResolvedFindings(payload);
+        return;
+    }
+    requireArray(payload, "commands");
+    requireArray(payload, "required_regressions");
+    requireField(payload, "build_status");
+    requireField(payload, "test_status");
+    requireBoolean(payload, "repro_negative");
+    requireBoolean(payload, "qa_ready");
+    if (payload.repro_negative !== true) {
+        throw new Error("debug_regression pass requires repro_negative: true.");
+    }
+    if (payload.qa_ready !== true) {
+        throw new Error("debug_regression pass requires qa_ready: true.");
+    }
+    requireAllowedStatus(payload, "build_status", ["pass", "not_applicable"]);
+    requireAllowedStatus(payload, "test_status", ["pass", "not_applicable"]);
+    requireNonEmptyArray(payload, "required_regressions");
+    requirePassingCommands(payload);
+}
 function validateQaGatePayloadShape(gate, payload, status) {
     requireField(payload, "summary");
     if (status === "skipped") {
@@ -1374,6 +2021,7 @@ function validateQaGatePayloadShape(gate, payload, status) {
         if (commands.length === 0) {
             throw new Error(`${qaGateToolNames[gate]} pass requires commands with at least one entry.`);
         }
+        validateQaGatePassingCommands(commands);
     }
     if (gate === "qa_manual_web" && status === "pass") {
         const browserChecks = qaArray(payload, "browser_checks");
@@ -1383,6 +2031,297 @@ function validateQaGatePayloadShape(gate, payload, status) {
         }
     }
 }
+function validateQaGatePassingCommands(commands) {
+    for (const [index, command] of commands.entries()) {
+        requireEvidenceRecord(command, `commands[${index}]`);
+        const record = command;
+        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
+        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            throw new Error(`commands[${index}].exit_code is required.`);
+        }
+        if (record.exit_code !== 0) {
+            throw new Error(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
+        }
+        if (normalizedString(record.status) !== "pass") {
+            throw new Error(`commands[${index}].status must be pass when QA gate status is pass.`);
+        }
+    }
+}
+function validateArchitectPayloadShape(payload, status) {
+    if (status !== "pass") {
+        requireArchitectNonPassEvidence(payload);
+        return;
+    }
+    const implementationPlan = requiredRecord(payload, "implementation_plan");
+    const qaPlan = requiredRecord(payload, "qa_plan");
+    requireNumericOne(implementationPlan, "schema_version", "implementation_plan.schema_version");
+    requireNonEmptyStringRecord(implementationPlan, "plan_id", "implementation_plan.");
+    requireArchitectArray(implementationPlan, "phases", payload);
+    requireArchitectArray(implementationPlan, "tasks", payload);
+    requireArchitectArray(implementationPlan, "dependencies", payload, { allowEmpty: true });
+    requireArchitectArray(implementationPlan, "phase_gates", payload);
+    if (arrayLength(implementationPlan, "tasks") === 0) {
+        throw new Error("implementation_plan.tasks: expected non-empty array; correction: include at least one task with id and tests.");
+    }
+    const taskIds = new Set();
+    for (const task of implementationPlan.tasks) {
+        if (!task || typeof task !== "object" || Array.isArray(task)) {
+            throw new Error("implementation_plan.tasks[]: expected object entries; correction: each task must be an object with id and tests.");
+        }
+        const taskRecord = task;
+        requireNonEmptyStringRecord(taskRecord, "id", "implementation_plan.tasks[].");
+        const taskId = optionalString(taskRecord, "id") ?? "";
+        if (taskIds.has(taskId)) {
+            throw new Error(`implementation_plan.tasks: duplicate task id '${taskId}'.`);
+        }
+        taskIds.add(taskId);
+        validateArchitectTaskDevelopScope(taskRecord, taskId);
+        requireArchitectArray(taskRecord, "tests", payload, { path: `implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests` });
+        if (arrayLength(taskRecord, "tests") === 0) {
+            throw new Error(`implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests: expected non-empty array; correction: include task-specific verification.`);
+        }
+    }
+    validateAndNormalizeArchitectDependencies(implementationPlan, taskIds);
+    requireNumericOne(qaPlan, "schema_version", "qa_plan.schema_version");
+    requireArchitectArray(qaPlan, "final_qa", payload, { path: "qa_plan.final_qa" });
+    if (arrayLength(qaPlan, "final_qa") === 0) {
+        throw new Error("qa_plan.final_qa: expected non-empty array; correction: include final QA coverage for the completed plan.");
+    }
+}
+function validateArchitectTaskDevelopScope(task, taskId) {
+    const explicitScope = firstOptionalString(task, ["execution_scope", "scope", "task_scope", "task_type", "lane", "kind", "type"]);
+    if (isStoryQaScope(explicitScope)) {
+        throw new Error(`implementation_plan.tasks[${taskId}]: story QA/sign-off work must not be materialized as a Develop child task; correction: move this coverage to qa_plan.final_qa and keep implementation_plan.tasks limited to repo/product changes.`);
+    }
+    if (looksLikeStoryLevelVerificationTask(architectTaskScopeText(task))) {
+        throw new Error(`implementation_plan.tasks[${taskId}]: parent-story materialization or sign-off verification belongs in qa_plan.final_qa, not implementation_plan.tasks; correction: keep child tasks focused on implementation work and put child-count/parent-plan artifact checks in final QA coverage.`);
+    }
+}
+function firstOptionalString(record, keys) {
+    for (const key of keys) {
+        const value = optionalString(record, key);
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+function isStoryQaScope(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase().replace(/[\s-]+/g, "_");
+    return [
+        "qa",
+        "story_qa",
+        "final_qa",
+        "sign_off",
+        "signoff",
+        "story_sign_off",
+        "story_verification",
+        "story_validation"
+    ].includes(normalized);
+}
+function architectTaskScopeText(task) {
+    const parts = [];
+    for (const key of ["id", "title", "summary", "phase", "phase_id"]) {
+        appendOptionalString(parts, task, key);
+    }
+    for (const key of ["acceptance_criteria", "expected_paths", "touched_surfaces", "implementation_notes"]) {
+        appendOptionalStringArray(parts, task, key);
+    }
+    const tests = task.tests;
+    if (Array.isArray(tests)) {
+        for (const test of tests) {
+            if (!test || typeof test !== "object" || Array.isArray(test)) {
+                continue;
+            }
+            const record = test;
+            for (const key of ["id", "command", "purpose", "target", "expected"]) {
+                appendOptionalString(parts, record, key);
+            }
+            appendOptionalStringArray(parts, record, "steps");
+        }
+    }
+    return parts.join(" ");
+}
+function appendOptionalString(parts, record, key) {
+    const value = optionalString(record, key);
+    if (value) {
+        parts.push(value);
+    }
+}
+function appendOptionalStringArray(parts, record, key) {
+    const value = record[key];
+    if (!Array.isArray(value)) {
+        return;
+    }
+    for (const entry of value) {
+        if (typeof entry === "string" && entry.trim().length > 0) {
+            parts.push(entry.trim());
+        }
+    }
+}
+function looksLikeStoryLevelVerificationTask(text) {
+    if (!text.trim()) {
+        return false;
+    }
+    const normalized = text.toLowerCase();
+    const verificationWords = [
+        "verify",
+        "verification",
+        "validate",
+        "validation",
+        "inspect",
+        "audit",
+        "check",
+        "confirm",
+        "prove",
+        "evidence",
+        "sign-off",
+        "sign off"
+    ];
+    if (!verificationWords.some((word) => normalized.includes(word))) {
+        return false;
+    }
+    return [
+        "materialization",
+        "materialized child",
+        "child inventory",
+        "child work-item",
+        "child work item",
+        "created task count",
+        "created_task_count",
+        "parent plan",
+        "parent story",
+        "story sign-off",
+        "story sign off",
+        ".forge/work-items",
+        ".forge\\work-items",
+        ".forge/stories",
+        ".forge\\stories",
+        "implementation.plan.json",
+        "qa.plan.json",
+        "architect plan artifact",
+        "child spec"
+    ].some((needle) => normalized.includes(needle));
+}
+function validateAndNormalizeArchitectDependencies(implementationPlan, taskIds) {
+    const dependencies = implementationPlan.dependencies;
+    const edges = new Map();
+    for (const taskId of taskIds) {
+        edges.set(taskId, []);
+    }
+    const normalizedDependencies = [];
+    for (const [index, dependency] of dependencies.entries()) {
+        if (!dependency || typeof dependency !== "object" || Array.isArray(dependency)) {
+            throw new Error("implementation_plan.dependencies[]: expected object entries; correction: each dependency must be an object with before and after task ids.");
+        }
+        const record = dependency;
+        const before = architectDependencyEndpoint(record, index, "before", "from");
+        const after = architectDependencyEndpoint(record, index, "after", "to");
+        if (!taskIds.has(before) || !taskIds.has(after)) {
+            throw new Error("implementation_plan.dependencies: dependency references an unknown task id.");
+        }
+        const normalized = stripUndefined({
+            ...record,
+            before,
+            after,
+            from: undefined,
+            to: undefined
+        });
+        normalizedDependencies.push(normalized);
+        edges.get(before)?.push(after);
+    }
+    implementationPlan.dependencies = normalizedDependencies;
+    if (hasArchitectDependencyCycle(edges)) {
+        throw new Error("implementation_plan.dependencies: expected acyclic graph; correction: remove or revise cyclic task dependencies.");
+    }
+}
+function architectDependencyEndpoint(dependency, index, canonicalKey, aliasKey) {
+    const canonical = optionalString(dependency, canonicalKey);
+    const alias = optionalString(dependency, aliasKey);
+    if (canonical && alias && canonical !== alias) {
+        throw new Error(`implementation_plan.dependencies[${index}].${canonicalKey}: conflicts with ${aliasKey}; correction: use one task id for ${canonicalKey}.`);
+    }
+    const value = canonical ?? alias;
+    if (!value) {
+        throw new Error(`implementation_plan.dependencies[${index}].${canonicalKey}: expected string; correction: use before and after task ids for each dependency.`);
+    }
+    return value;
+}
+function hasArchitectDependencyCycle(edges) {
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (node) => {
+        if (visited.has(node)) {
+            return false;
+        }
+        if (visiting.has(node)) {
+            return true;
+        }
+        visiting.add(node);
+        for (const next of edges.get(node) ?? []) {
+            if (visit(next)) {
+                return true;
+            }
+        }
+        visiting.delete(node);
+        visited.add(node);
+        return false;
+    };
+    for (const node of edges.keys()) {
+        if (visit(node)) {
+            return true;
+        }
+    }
+    return false;
+}
+function requireArchitectNonPassEvidence(payload) {
+    const evidenceKeys = ["blockers", "revision_questions", "revision_reasons", "known_gaps", "findings", "remaining_risks", "failures"];
+    const hasEvidence = evidenceKeys.some((key) => {
+        const value = payload[key];
+        if (typeof value === "string") {
+            return value.trim().length > 0;
+        }
+        if (Array.isArray(value)) {
+            return value.length > 0;
+        }
+        return Boolean(value && typeof value === "object");
+    });
+    if (!hasEvidence) {
+        throw new Error("status: non-pass Architect completion requires blockers, revision_questions, revision_reasons, findings, failures, or known_gaps; correction: explain why the plan cannot pass.");
+    }
+}
+function requireArchitectArray(source, key, rootPayload, options = {}) {
+    const pathLabel = options.path ?? `implementation_plan.${key}`;
+    if (!Array.isArray(source[key])) {
+        const nestedHint = architectNestedArrayHint(rootPayload, key);
+        throw new Error(`${pathLabel}: expected array${key === "phases" ? " as a top-level field inside implementation_plan" : ""}; correction: ${nestedHint ?? `set ${pathLabel} to an array${options.allowEmpty ? " (use [] when none exist)" : " with at least one entry"}.`}`);
+    }
+    if (!options.allowEmpty && arrayLength(source, key) === 0) {
+        throw new Error(`${pathLabel}: expected non-empty array; correction: include at least one entry.`);
+    }
+}
+function architectNestedArrayHint(rootPayload, key) {
+    if (Array.isArray(rootPayload[key])) {
+        return `move top-level ${key} into implementation_plan.${key}.`;
+    }
+    const implementationPlan = rootPayload.implementation_plan;
+    if (!implementationPlan || typeof implementationPlan !== "object" || Array.isArray(implementationPlan)) {
+        return null;
+    }
+    const plan = implementationPlan;
+    for (const container of ["plan", "dag", "implementation_dag", "implementationPlan", "implementation_plan"]) {
+        const nested = plan[container];
+        if (nested && typeof nested === "object" && !Array.isArray(nested) && Array.isArray(nested[key])) {
+            return `move implementation_plan.${container}.${key} to implementation_plan.${key}.`;
+        }
+    }
+    return null;
+}
 function validateQaPayloadShape(payload, status) {
     const evidenceSource = qaEvidenceSource(payload);
     const commands = qaArray(payload, "commands", evidenceSource);
@@ -1571,6 +2510,10 @@ ${summary}
 }
 function parseStrictCompletionPhase(value) {
     const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
+    const debugPhase = normalizeDebugCompletionPhase(normalized);
+    if (debugPhase) {
+        return debugPhase;
+    }
     if (normalized === "implementation" || normalized === "implement" || normalized === "develop") {
         return "implementation";
     }
@@ -1583,8 +2526,48 @@ function parseStrictCompletionPhase(value) {
     if (normalized === "qa" || normalized === "quality_assurance" || normalized === "qualityassurance") {
         return "qa";
     }
+    if (normalized === "architect" || normalized === "architect_plan" || normalized === "planning" || normalized === "plan") {
+        return "architect";
+    }
     return null;
 }
+function normalizeDebugCompletionPhase(value) {
+    const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
+    switch (normalized) {
+        case "debug_repro":
+        case "debugrepro":
+        case "repro":
+        case "reproduce":
+            return "debug_repro";
+        case "debug_root_cause":
+        case "debugrootcause":
+        case "root_cause":
+        case "rootcause":
+            return "debug_root_cause";
+        case "debug_fix":
+        case "debugfix":
+        case "fix":
+            return "debug_fix";
+        case "debug_regression":
+        case "debugregression":
+        case "regression":
+            return "debug_regression";
+        default:
+            return null;
+    }
+}
+function isDevelopCompletionPhase(phase) {
+    return phase === "implementation" || phase === "self_review" || phase === "validation";
+}
+function isDebugCompletionPhase(phase) {
+    return debugCompletionPhaseOrder.includes(phase);
+}
+function asDebugCompletionPhase(phase) {
+    if (isDebugCompletionPhase(phase)) {
+        return phase;
+    }
+    throw new Error(`Expected Debug completion phase, got ${phase}.`);
+}
 function parseCompletionRedactionSecrets(raw) {
     if (!raw?.trim()) {
         return [];
@@ -1614,11 +2597,28 @@ function phaseFromToolName(toolName) {
     if (normalized === "forge.complete_qa" || normalized === "complete_qa") {
         return "qa";
     }
+    if (normalized === "forge.complete_architect_plan" || normalized === "complete_architect_plan") {
+        return "architect";
+    }
+    const debugGate = debugGateFromToolName(toolName);
+    if (debugGate) {
+        return debugGate;
+    }
     if (qaGateFromToolName(toolName)) {
         return "qa";
     }
     throw new Error(`Unknown Forge completion tool: ${toolName}`);
 }
+function debugGateFromToolName(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    for (const gate of debugCompletionPhaseOrder) {
+        const base = debugGateToolNames[gate];
+        if (normalized === `forge.${base}` || normalized === base) {
+            return gate;
+        }
+    }
+    return null;
+}
 function qaGateFromToolName(toolName) {
     const normalized = toolName.trim().toLowerCase();
     for (const gate of qaCompletionGateOrder) {
@@ -1696,17 +2696,42 @@ function requireArray(payload, key) {
         throw new Error(`${key} must be an array.`);
     }
 }
+function requireNonEmptyArray(payload, key) {
+    requireArray(payload, key);
+    if (arrayLength(payload, key) === 0) {
+        throw new Error(`${key} must include at least one value.`);
+    }
+}
+function arrayLength(payload, key) {
+    const value = payload[key];
+    return Array.isArray(value) ? value.length : 0;
+}
+function requireAllowedStatus(payload, key, allowed) {
+    const value = normalizedString(optionalString(payload, key));
+    if (!allowed.includes(value)) {
+        throw new Error(`${key} must be one of ${allowed.join(", ")}.`);
+    }
+}
 function requireObject(payload, key) {
     const value = payload[key];
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`${key} must be an object.`);
     }
 }
+function requiredRecord(payload, key) {
+    requireObject(payload, key);
+    return payload[key];
+}
 function requireBoolean(payload, key) {
     if (typeof payload[key] !== "boolean") {
         throw new Error(`${key} must be a boolean.`);
     }
 }
+function requireNumericOne(payload, key, pathLabel) {
+    if (payload[key] !== 1) {
+        throw new Error(`${pathLabel}: expected numeric 1; correction: set ${pathLabel} to 1.`);
+    }
+}
 function requireSatisfiedAcceptanceCriteria(payload) {
     const criteria = payload.acceptance_criteria;
     if (!Array.isArray(criteria)) {
@@ -1724,6 +2749,37 @@ function requireSatisfiedAcceptanceCriteria(payload) {
         }
     }
 }
+function validateResolvedFindings(payload) {
+    const resolvedFindings = payload.resolved_findings;
+    if (resolvedFindings === undefined || resolvedFindings === null) {
+        return;
+    }
+    if (!Array.isArray(resolvedFindings)) {
+        throw new Error("resolved_findings must be an array.");
+    }
+    for (const [index, finding] of resolvedFindings.entries()) {
+        const prefix = `resolved_findings[${index}].`;
+        if (!finding || typeof finding !== "object" || Array.isArray(finding)) {
+            throw new Error(`resolved_findings[${index}] must be an object.`);
+        }
+        const record = finding;
+        requireNonEmptyStringRecord(record, "qa_id", prefix);
+        requireKnownStringRecord(record, "status", resolvedFindingStatuses, prefix);
+        requireNonEmptyStringRecord(record, "summary", prefix);
+        requireSubstantiveValueRecord(record, "evidence", prefix);
+        requireArrayRecord(record, "changed_files", prefix);
+        requireArrayRecord(record, "tests_added_or_updated", prefix);
+        requireSubstantiveValueRecord(record, "regression_evidence", prefix);
+        if (normalizedString(record.status) === "resolved") {
+            if (record.changed_files.length === 0) {
+                throw new Error(`${prefix}changed_files must include at least one changed file for resolved QA findings.`);
+            }
+            if (record.tests_added_or_updated.length === 0) {
+                throw new Error(`${prefix}tests_added_or_updated must include at least one regression test for resolved QA findings.`);
+            }
+        }
+    }
+}
 function qaEvidenceSource(payload) {
     const evidence = payload.evidence;
     return evidence && typeof evidence === "object" && !Array.isArray(evidence)
@@ -1773,6 +2829,11 @@ function requireNonEmptyStringRecord(source, key, prefix = "") {
         throw new Error(`${prefix}${key} is required.`);
     }
 }
+function requireArrayRecord(source, key, prefix = "") {
+    if (!Array.isArray(source[key])) {
+        throw new Error(`${prefix}${key} must be an array.`);
+    }
+}
 function requireKnownStringRecord(source, key, allowed, prefix = "") {
     const value = normalizedString(optionalString(source, key));
     if (!allowed.has(value)) {
@@ -1790,6 +2851,11 @@ function requireNonEmptyStringArrayRecord(source, key, prefix = "") {
         }
     }
 }
+function requireSubstantiveValueRecord(source, key, prefix = "") {
+    if (!hasSubstantiveJsonValue(source[key])) {
+        throw new Error(`${prefix}${key} must include at least one concrete evidence reference or summary.`);
+    }
+}
 function requireSubstantiveEvidenceRecord(source, prefix = "") {
     const evidence = source.evidence;
     if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) {
@@ -1872,7 +2938,7 @@ function parseJsonObject(content, label) {
         return asRecord(JSON.parse(content), label);
     }
     catch (error) {
-        throw new Error(`${label} is not valid JSON: ${errorMessage(error)}`);
+        throw new Error(`${label} is not valid JSON: ${errorMessage(error)}`, { cause: error });
     }
 }
 function parseOptionalJsonObject(content, label) {