@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.bfa11ebe98c6

package/dist/session/phase-completion.runtime.js

@@ -1,8 +1,10 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { completionPhaseFromDispatch, completionPhaseOrder, completionRedactionSecretsEnv, completionToolNamesForDebugGate, completionToolNamesForDecomposeGate, completionToolNamesForDraftGate, completionToolNamesForPhase, completionToolNamesForQaGate, debugCompletionPhaseOrder, decomposeCompletionGateOrder, draftCompletionGateOrder, qaCompletionGateOrder, toolServerName, usesArchitectCycleCompletion, usesDebugCycleCompletion, usesDevelopCycleCompletion, usesQaCycleCompletion } from "./phase-completion.js";
-import { asDebugCompletionPhase, asJsonRpcMessage, asMutableRecord, asRecord, artifactOwnerRelativeRoot, decomposeGateFromToolName, draftGateFromToolName, errorMessage, forgeBridgeCliBinPath, isDebugCompletionPhase, isDecomposeDispatch, isDevelopCompletionPhase, normalizedOwnerType, parseCompletionRedactionSecrets, parseOptionalJsonObject, parseStrictCompletionPhase, phaseFromToolName, qaGateFromToolName, requiredString, rpcError, tomlString, tomlStringArray, writeFileAtomic, writeJsonRpc } from "./phase-completion.validation.js";
+import { CompletionPayloadValidationError, asDebugCompletionPhase, asJsonRpcMessage, asMutableRecord, asRecord, artifactOwnerRelativeRoot, decomposeGateFromToolName, draftGateFromToolName, errorMessage, forgeBridgeCliBinPath, isDebugCompletionPhase, isDecomposeDispatch, isDevelopCompletionPhase, normalizedOwnerType, parseCompletionRedactionSecrets, parseOptionalJsonObject, parseStrictCompletionPhase, phaseFromToolName, qaGateFromToolName, requiredString, rpcError, tomlString, tomlStringArray, writeFileAtomic, writeJsonRpc } from "./phase-completion.validation.js";
 import { completionPromptForDebugCycle, completionPromptForDecomposeCycle, completionPromptForDevelopCycle, completionPromptForDraftCycle, completionPromptForPhase, completionPromptForQaCycle, completionToolNextInstruction, completionToolNextInstructionForDebugGate, completionToolNextInstructionForDecomposeGate, completionToolNextInstructionForDraftGate, completionToolNextInstructionForQaGate, nextDebugPhaseAfter, nextPhaseAfter } from "./phase-completion.prompts.js";
+import { configuredNativeTestPostgresFallbackPath, nativeTestPostgresFallbackConfigEnvironment, } from "../runtime/native-test-postgres-fallback.js";
 import { toolDescription, toolInputSchema } from "./phase-completion.schemas.js";
 import { writeCompletionArtifact, writeDecomposeGateCompletionArtifact, writeDraftGateCompletionArtifact } from "./phase-completion.artifacts.js";
 import { callManagedAttemptTool, isManagedAttemptTool, managedAttemptToolDefinition, managedAttemptToolNames, } from "./managed-attempt-tools.js";
@@ -33,13 +35,17 @@ export async function prepareCompletionToolRuntime(options) {
         serverName: toolServerName,
         command: process.execPath,
         args: [forgeBridgeCliBinPath(), ...mcpArgs],
-        env: completionToolRuntimeEnvironment(options.runtimeEnvironment),
+        env: completionToolRuntimeEnvironment(options.runtimeEnvironment, configuredNativeTestPostgresFallbackPath()),
         cleanup: async () => undefined
     };
-    if (options.dispatch.execution.provider.trim().toLowerCase() !== "cursor") {
-        return runtime;
+    const provider = options.dispatch.execution.provider.trim().toLowerCase();
+    if (provider === "cursor") {
+        return await prepareCursorCompletionToolRuntime(worktreePath, runtime);
     }
-    return await prepareCursorCompletionToolRuntime(worktreePath, runtime);
+    if (provider === "claude") {
+        return await prepareClaudeCompletionToolRuntime(runtime);
+    }
+    return runtime;
 }
 export function buildCompletionToolServerArgs(config) {
     const args = [
@@ -101,6 +107,14 @@ export function cursorMcpServerConfig(runtime) {
         env: runtime.env
     };
 }
+export function claudeMcpServerConfig(runtime) {
+    return {
+        type: "stdio",
+        command: runtime.command,
+        args: [...runtime.args],
+        env: runtime.env
+    };
+}
 export function completionToolNamesForServer(config) {
     return config.decomposeCycle
         ? decomposeCompletionGateOrder.flatMap((gate) => completionToolNamesForDecomposeGate(gate))
@@ -185,9 +199,11 @@ export class CompletionToolServerSession {
             ? this.advanceAfterPass(completedPhase)
             : completedPhase;
         const nextInstruction = completionToolNextInstruction(completedPhase, status, nextPhase);
-        const reason = pass
-            ? `${completedPhase} completion artifact accepted.`
-            : `${completedPhase} completion artifact recorded with status ${status}; rework is required before phase progression.`;
+        const reason = completedPhase === "qa"
+            ? `QA artifact recorded locally with status ${status}; API ingestion and acceptance are pending.`
+            : pass
+                ? `${completedPhase} completion artifact accepted.`
+                : `${completedPhase} completion artifact recorded with status ${status}; rework is required before phase progression.`;
         return {
             content: [
                 {
@@ -197,6 +213,7 @@ export class CompletionToolServerSession {
             ],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: {
                     phase: completedPhase,
                     status,
@@ -234,6 +251,7 @@ export class CompletionToolServerSession {
             content: [{ type: "text", text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}` }],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: { phase: "decompose", decomposeGate: completedGate, status, allowed: pass, reason },
                 nextPhase,
                 nextInstruction
@@ -258,6 +276,7 @@ export class CompletionToolServerSession {
             content: [{ type: "text", text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}` }],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: { phase: "draft", draftGate: completedGate, status, allowed: status !== "blocked", reason: nextGate ? `${completedGate} artifact accepted; continue to ${nextGate}.` : `Draft proposal artifact accepted with status ${status}.` },
                 nextPhase,
                 nextInstruction
@@ -291,6 +310,7 @@ export class CompletionToolServerSession {
             ],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: {
                     phase: completedGate,
                     status,
@@ -321,8 +341,8 @@ export class CompletionToolServerSession {
         const nextInstruction = completionToolNextInstructionForQaGate(completedGate, status, nextGate);
         const allowed = status !== "blocked";
         const reason = nextGate
-            ? `${completedGate} artifact accepted; continue to ${nextGate}.`
-            : `QA verdict artifact accepted with status ${status}.`;
+            ? `${completedGate} artifact accepted locally; continue to ${nextGate}.`
+            : `QA verdict artifact recorded locally with status ${status}; API ingestion and acceptance are pending.`;
         return {
             content: [
                 {
@@ -332,6 +352,7 @@ export class CompletionToolServerSession {
             ],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: {
                     phase: "qa",
                     qaGate: completedGate,
@@ -412,14 +433,28 @@ const completionToolRuntimeEnvironmentNames = [
     "FORGE_RUNTIME_MODE",
     "FORGE_RESOURCE_LEASE_ID",
     "FORGE_DISPATCH_ATTEMPT_ID",
+    "FORGE_E2E_OWNERSHIP_MODE",
+    "FORGE_E2E_OWNERSHIP_TOKEN",
+    "FORGE_WORKTREE_PATH",
     "FORGE_LOG_DIR",
+    "FORGE_CACHE_DIR",
     "FORGE_TEST_OUTPUT_DIR",
+    "FORGE_ATTEMPT_DATABASE_SCHEMA",
+    "FORGE_ATTEMPT_DATABASE_READINESS_PATH",
+    "FORGE_CI_REPAIR_READINESS_PATH",
+    "FORGE_CI_REPAIR_HANDOFF_PATH",
+    "FORGE_CI_REPAIR_PROVIDER_ONLY_SPECS",
+    "FORGE_PLAYWRIGHT_CONFIG",
+    "FORGE_E2E_API_URL",
+    "FORGE_E2E_WEB_URL",
+    "PLAYWRIGHT_BROWSERS_PATH",
     "FORGE_TMPDIR",
+    "NPM_CONFIG_CACHE",
     "TMPDIR",
     "TMP",
     "TEMP",
 ];
-export function completionToolRuntimeEnvironment(runtimeEnvironment) {
+export function completionToolRuntimeEnvironment(runtimeEnvironment, nativeTestPostgresFallbackPath) {
     if (!runtimeEnvironment)
         return {};
     const env = {};
@@ -428,6 +463,11 @@ export function completionToolRuntimeEnvironment(runtimeEnvironment) {
         if (value)
             env[name] = value;
     }
+    // Managed verification reads the operator's native test cluster only through
+    // this explicit path, and only while Docker is unavailable.
+    if (nativeTestPostgresFallbackPath) {
+        env[nativeTestPostgresFallbackConfigEnvironment] = nativeTestPostgresFallbackPath;
+    }
     return env;
 }
 const minimumManagedSolutionTestTimeoutMs = 45 * 60 * 1000;
@@ -453,7 +493,8 @@ export function assertManagedQaRegressionEvidence(input, receipts) {
         const managedCommandId = entry.managed_command_id;
         if (typeof managedCommandId !== "string" || !managedCommandId.trim()) {
             throw new Error(`qa_regression_managed_command_id_required: commands[${index}] runs the solution-wide Forge test. `
-                + "Run it with forge.start_managed_command, continue independent work, call forge.wait_managed_command once for the terminal receipt, and include the returned managed_command_id in this command evidence.");
+                + "Run it with forge.start_managed_command, continue independent work, then call forge.wait_managed_command for a transport-safe receipt. "
+                + "If command_continues=true, continue useful work or wait again after retry_after_ms. Include the terminal managed_command_id in this command evidence.");
         }
         const matchingReceipts = receipts.filter((receipt) => {
             const tokens = receipt.command;
@@ -464,7 +505,8 @@ export function assertManagedQaRegressionEvidence(input, receipts) {
         });
         if (matchingReceipts.length === 0) {
             throw new Error(`qa_regression_managed_command_required: commands[${index}] runs the solution-wide Forge test. `
-                + "Run it with forge.start_managed_command, continue independent work, call forge.wait_managed_command once for the terminal receipt, and include its matching managed_command_id; generic-shell timeout evidence is not accepted on a managed host.");
+                + "Run it with forge.start_managed_command, continue independent work, then call forge.wait_managed_command for a transport-safe receipt. "
+                + "If command_continues=true, continue useful work or wait again after retry_after_ms. Include its matching terminal managed_command_id; generic-shell timeout evidence is not accepted on a managed host.");
         }
         const terminalReceipts = matchingReceipts.filter((receipt) => typeof receipt.status === "string" && [
             "pass",
@@ -475,7 +517,7 @@ export function assertManagedQaRegressionEvidence(input, receipts) {
         ].includes(receipt.status));
         if (terminalReceipts.length === 0) {
             throw new Error(`qa_regression_managed_command_in_progress: commands[${index}] has not produced a terminal managed receipt. `
-                + "Call forge.wait_managed_command once for its terminal receipt, then resubmit this gate.");
+                + "Call forge.wait_managed_command. If command_continues=true, continue useful work or wait again after retry_after_ms; resubmit this gate only after the receipt is terminal.");
         }
         const adequateReceipt = terminalReceipts.some((receipt) => {
             if (receipt.timed_out !== true)
@@ -559,7 +601,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, architect, draft, decompose, ci-repair, debug-repro, debug-root-cause, debug-fix, debug-regression." };
+                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation, qa, architect, draft, decompose, ci-repair, comment-repair, debug-repro, debug-root-cause, debug-fix, debug-regression." };
             }
             phase = parsedPhase;
         }
@@ -664,6 +706,28 @@ async function prepareCursorCompletionToolRuntime(worktreePath, runtime) {
         }
     };
 }
+/**
+ * Claude Code takes MCP servers from `--mcp-config <file>`. The file lives in an attempt-owned
+ * temp directory (never the worktree) because its env block can carry redaction secrets, and
+ * passing the JSON inline would not survive Windows shim quoting.
+ */
+async function prepareClaudeCompletionToolRuntime(runtime) {
+    const configDir = await fs.mkdtemp(path.join(os.tmpdir(), "forge-claude-mcp-"));
+    const configPath = path.join(configDir, "mcp.json");
+    const config = {
+        mcpServers: {
+            [runtime.serverName]: claudeMcpServerConfig(runtime)
+        }
+    };
+    await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return {
+        ...runtime,
+        claudeMcpConfigPath: configPath,
+        cleanup: async () => {
+            await fs.rm(configDir, { recursive: true, force: true });
+        }
+    };
+}
 async function handleJsonRpcLine(session, rawLine) {
     let message;
     try {
@@ -718,10 +782,48 @@ async function handleJsonRpcRequest(session, method, params) {
         const call = asRecord(params, "tools/call params");
         const name = requiredString(call, "name");
         const args = call.arguments ?? {};
-        return await session.callTool(name, args);
+        try {
+            return await session.callTool(name, args);
+        }
+        catch (error) {
+            if (isManagedAttemptTool(name))
+                throw error;
+            return completionToolRejectedResult(name, error);
+        }
     }
     throw new Error(`Unsupported MCP method: ${method}`);
 }
+export function completionToolRejectedResult(toolName, error) {
+    const issues = error instanceof CompletionPayloadValidationError
+        ? [...error.issues]
+        : [errorMessage(error)];
+    const repairInstruction = "Repair every listed issue and resubmit this same gate once. Do not inspect the artifact path: rejected calls never write or replace completion artifacts.";
+    return {
+        content: [{
+                type: "text",
+                text: `Forge rejected ${toolName}. No artifact was written.\n${issues.map(issue => `- ${issue}`).join("\n")}\n${repairInstruction}`,
+            }],
+        structuredContent: {
+            status: "rejected",
+            tool_name: toolName,
+            artifact_written: false,
+            issues,
+            repair_instruction: repairInstruction,
+        },
+        isError: true,
+    };
+}
+function acceptedArtifactReceipt(reference) {
+    return {
+        artifact_written: true,
+        artifact_receipt: {
+            schema_version: 1,
+            path: reference.path,
+            report_path: reference.reportPath,
+            content_hash: reference.contentHash,
+        },
+    };
+}
 function toolDefinition(name, phase, qaGate = null, decomposeGate = null) {
     return {
         name,

package/dist/session/phase-completion.schemas.js

@@ -19,6 +19,9 @@ export function toolDescription(phase, qaGate = null, decomposeGate = null) {
     if (phase === "ci_repair") {
         return "Complete Forge CI repair by writing ci-repair.handoff.json with failed-check, root-cause, scoped-change, workflow-equivalence, validation, provider-state, and push-readiness evidence.";
     }
+    if (phase === "comment_repair") {
+        return "Complete Forge pull-request comment repair by recording one evidence-backed disposition for every actionable finding in the dispatch snapshot.";
+    }
     if (phase === "self_review") {
         return "Complete Forge self-review by writing self-review.report.json with diff review, findings, security, edge-case, design, deterministic-comparison, fixes, and remaining-risk evidence.";
     }
@@ -146,6 +149,42 @@ export function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
             }
         }, ["status", "summary"], "For status pass, include failed_checks, root_cause, changed_files or no_code_action, narrow_validation, workflow_validation, broader_validation, remaining_risks, provider_state, and ready_for_push: true.");
     }
+    if (phase === "comment_repair") {
+        return objectToolSchema({
+            ...baseProperties,
+            repair_head_sha: { type: "string", description: "Exact pull-request head from the dispatch snapshot." },
+            repair_issue_key: { type: "string", description: "Exact review issue key from the dispatch snapshot." },
+            dispositions: {
+                type: "array",
+                description: "Exactly one outcome for every actionable dispatch finding; conversation-only comments are omitted.",
+                items: evidenceObjectSchema(["claim_id", "kind", "body_sha256", "disposition", "evidence"], {
+                    claim_id: { type: "string" },
+                    kind: { type: "string", enum: ["review_thread", "review_body", "issue_comment"] },
+                    body_sha256: { type: "string" },
+                    disposition: { type: "string", enum: ["fixed", "rejected", "already_addressed", "needs_decision", "accepted_transfer", "owned_elsewhere"] },
+                    accepted_transfer: { type: "object", properties: {
+                            amendment_id: { type: "string" }, version: { type: "integer", minimum: 1 }, content_hash: { type: "string" },
+                            target_work_item_id: { type: "string" }, obligation_reference: { type: "string" },
+                        }, required: ["amendment_id", "version", "content_hash", "target_work_item_id", "obligation_reference"], additionalProperties: false },
+                    owned_elsewhere: { type: "object", description: "Another open Story in this Work Order whose accepted acceptance criteria already require the requested change.", properties: {
+                            target_work_item_id: { type: "string" },
+                            quoted_obligation: { type: "string", description: "Verbatim passage (at least 40 characters) from that Story's acceptance criteria that covers the finding." },
+                        }, required: ["target_work_item_id", "quoted_obligation"], additionalProperties: false },
+                    evidence: { type: "string" }
+                })
+            },
+            changed_files: {
+                type: "array",
+                description: "Files changed for fixed findings. May be empty when every finding is rejected, already addressed, or needs a decision.",
+                items: evidenceObjectSchema(["path", "summary"], { path: { type: "string" }, summary: { type: "string" } })
+            },
+            validation: {
+                type: "array",
+                description: "Scoped verification evidence. May be empty only when no source change was made.",
+                items: commandEvidenceSchema()
+            }
+        }, ["status", "summary", "repair_head_sha", "repair_issue_key", "dispositions", "changed_files", "validation"], "Use status pass after every actionable finding has an evidence-backed disposition. Rejected and needs_decision are legitimate outcomes and must not be disguised as code changes.");
+    }
     if (phase === "implementation") {
         return objectToolSchema({
             ...baseProperties,
@@ -221,7 +260,10 @@ export function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
                     file: { type: "string" }
                 })
             },
-            security_review: reviewSectionSchema(),
+            security_review: {
+                ...reviewSectionSchema(),
+                description: "Required for pass. Use pass after review, or not_applicable only with notes explaining why the change has no security-relevant surface."
+            },
             edge_case_review: reviewSectionSchema(),
             design_review: {
                 ...reviewSectionSchema(),
@@ -719,6 +761,11 @@ function qaScopeSchema(description) {
             schema_version: { type: "number", enum: [1] },
             surface: { type: "array", items: { type: "string", enum: [...qaScopeSurfaces] } },
             required_evidence: { type: "array", items: { type: "string", enum: [...qaScopeEvidence] } },
+            required_capabilities: {
+                type: "array",
+                description: "Runner facilities required by implementation and validation. Use docker_engine when tests or project services require access to a Docker daemon, even when the agent itself runs in a managed host worktree.",
+                items: { type: "string", enum: ["docker_engine"] }
+            },
             not_applicable: { type: "array", items: { type: "string", enum: [...qaScopeEvidence] } },
             browser_required: { type: "boolean" },
             api_required: { type: "boolean" },
@@ -743,7 +790,7 @@ function qaScopeSchema(description) {
 function commandEvidenceSchema() {
     return evidenceObjectSchema(["command", "exit_code", "status", "summary"], {
         command: { type: "string" },
-        managed_command_id: { type: "string", description: "Receipt ID returned by forge.start_managed_command and completed through one forge.wait_managed_command call for managed-host evidence." },
+        managed_command_id: { type: "string", description: "Receipt ID returned by forge.start_managed_command after forge.wait_managed_command reports a terminal receipt. A transport-safe wait can return command_continues=true; wait again after retry_after_ms before submitting the gate." },
         exit_code: { type: ["number", "null"], description: "Process exit code, or null when the managed runner timed out or could not launch the process." },
         status: { type: "string" },
         summary: { type: "string" },

package/dist/session/phase-completion.validation.d.ts

@@ -2,6 +2,7 @@ import { type CompletionPhase, type DebugCompletionPhase, type QaCompletionGate
 export declare function normalizeCompletionStatus(value: string, phase?: CompletionPhase): string;
 export declare function normalizeQaGateStatus(value: string): string;
 export declare function validatePayloadShape(phase: CompletionPhase, payload: Record<string, unknown>): void;
+export declare function validateCommentRepairPayloadShape(payload: Record<string, unknown>): void;
 export declare function validateCiRepairPayloadShape(payload: Record<string, unknown>): void;
 export declare function validateDebugPayloadShape(phase: DebugCompletionPhase, payload: Record<string, unknown>): void;
 export declare function validateQaGatePayloadShape(gate: QaCompletionGate, payload: Record<string, unknown>, status: string): void;

package/dist/session/phase-completion.validation.js

@@ -1,4 +1,4 @@
-import { qaBlockerReasons, qaCandidateBugActions, qaFindingScopes, qaFindingSeverities, qaGateToolNames, qaScopeAuthorities, qaScopeConfidence, qaScopeEvidence, qaScopeFields, qaScopeSources, qaScopeSurfaces } from "./phase-completion.js";
+import { qaBlockerReasons, qaCandidateBugActions, qaFindingScopes, qaFindingSeverities, qaGateToolNames, qaScopeAuthorities, qaScopeCapabilities, qaScopeConfidence, qaScopeEvidence, qaScopeFields, qaScopeSources, qaScopeSurfaces } from "./phase-completion.js";
 export function normalizeCompletionStatus(value, phase) {
     const normalized = value.trim().toLowerCase().replace(/-/g, "_");
     if (phase === "qa") {
@@ -55,6 +55,10 @@ export function validatePayloadShape(phase, payload) {
         validateCiRepairPayloadShape(payload);
         return;
     }
+    if (phase === "comment_repair") {
+        validateCommentRepairPayloadShape(payload);
+        return;
+    }
     if (isDebugCompletionPhase(phase)) {
         validateDebugPayloadShape(phase, payload);
         return;
@@ -101,6 +105,65 @@ export function validatePayloadShape(phase, payload) {
     requirePassingCommands(payload);
     requireSatisfiedAcceptanceCriteria(payload);
 }
+export function validateCommentRepairPayloadShape(payload) {
+    requireNonEmptyStringRecord(payload, "repair_head_sha", "");
+    requireNonEmptyStringRecord(payload, "repair_issue_key", "");
+    requireArray(payload, "dispositions");
+    requireNonEmptyArray(payload, "dispositions");
+    const seen = new Set();
+    let hasFixed = false;
+    for (const [index, entry] of payload.dispositions.entries()) {
+        requireEvidenceRecord(entry, `dispositions[${index}]`);
+        const record = entry;
+        for (const key of ["claim_id", "kind", "body_sha256", "disposition", "evidence"]) {
+            requireNonEmptyStringRecord(record, key, `dispositions[${index}].`);
+        }
+        requireKnownStringRecord(record, "kind", new Set(["review_thread", "review_body", "issue_comment"]), `dispositions[${index}].`);
+        requireKnownStringRecord(record, "disposition", new Set(["fixed", "rejected", "already_addressed", "needs_decision", "accepted_transfer", "owned_elsewhere"]), `dispositions[${index}].`);
+        if (record.disposition === "owned_elsewhere") {
+            const receipt = record.owned_elsewhere;
+            if (!receipt || typeof receipt !== "object" || Array.isArray(receipt))
+                throw new Error("owned_elsewhere requires the owning Story and its quoted obligation; server verification remains mandatory.");
+            const owner = receipt;
+            if (typeof owner.target_work_item_id !== "string" || !owner.target_work_item_id.trim())
+                throw new Error("owned_elsewhere.target_work_item_id is required.");
+            if (typeof owner.quoted_obligation !== "string" || owner.quoted_obligation.trim().length < 40)
+                throw new Error("owned_elsewhere.quoted_obligation must quote at least 40 characters of the owning Story's acceptance criteria.");
+        }
+        if (record.disposition === "accepted_transfer") {
+            const receipt = record.accepted_transfer;
+            if (!receipt || typeof receipt !== "object" || Array.isArray(receipt))
+                throw new Error("accepted_transfer requires an approved amendment receipt; server verification remains mandatory.");
+            const transfer = receipt;
+            for (const key of ["amendment_id", "content_hash", "target_work_item_id", "obligation_reference"]) {
+                if (typeof transfer[key] !== "string" || !transfer[key].trim())
+                    throw new Error(`accepted_transfer.${key} is required.`);
+            }
+            if (!Number.isInteger(transfer.version) || Number(transfer.version) < 1)
+                throw new Error("accepted_transfer.version must be positive.");
+        }
+        const identity = `${normalizedString(optionalString(record, "kind"))}:${optionalString(record, "claim_id")}:${normalizedString(optionalString(record, "body_sha256"))}`;
+        if (seen.has(identity))
+            throw new Error(`dispositions[${index}] duplicates finding ${identity}.`);
+        seen.add(identity);
+        hasFixed ||= normalizedString(optionalString(record, "disposition")) === "fixed";
+    }
+    requireArray(payload, "changed_files");
+    requireArray(payload, "validation");
+    for (const [index, changedFile] of payload.changed_files.entries()) {
+        requireEvidenceRecord(changedFile, `changed_files[${index}]`);
+        const record = changedFile;
+        requireNonEmptyStringRecord(record, "path", `changed_files[${index}].`);
+        requireNonEmptyStringRecord(record, "summary", `changed_files[${index}].`);
+    }
+    if (hasFixed && arrayLength(payload, "changed_files") === 0) {
+        throw new Error("fixed comment dispositions require changed_files evidence.");
+    }
+    if (arrayLength(payload, "changed_files") > 0) {
+        requireNonEmptyArray(payload, "validation");
+        validateQaGatePassingCommands(payload.validation);
+    }
+}
 export function validateCiRepairPayloadShape(payload) {
     requireArray(payload, "failed_checks");
     requireNonEmptyArray(payload, "failed_checks");
@@ -252,29 +315,43 @@ export function validateQaGatePayloadShape(gate, payload, status) {
     }
 }
 export function validateQaGatePassingCommands(commands, options = {}) {
+    const issues = [];
     for (const [index, command] of commands.entries()) {
-        requireEvidenceRecord(command, `commands[${index}]`);
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            issues.push(`commands[${index}] must be an object.`);
+            continue;
+        }
         const record = command;
-        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (!optionalString(record, "command"))
+            issues.push(`commands[${index}].command is required.`);
+        if (!optionalString(record, "status"))
+            issues.push(`commands[${index}].status is required.`);
+        if (!optionalString(record, "summary"))
+            issues.push(`commands[${index}].summary is required.`);
         if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
-            throw new Error(`commands[${index}].exit_code is required.`);
+            issues.push(`commands[${index}].exit_code is required.`);
+            continue;
         }
         const passed = record.exit_code === 0 && normalizedString(record.status) === "pass";
         if (!passed
             && options.allowClassifiedNonBlockingFailures
             && optionalString(record, "classification")) {
-            validateClassifiedNonBlockingQaFailure(record, index);
+            try {
+                validateClassifiedNonBlockingQaFailure(record, index);
+            }
+            catch (error) {
+                issues.push(error instanceof Error ? error.message : String(error));
+            }
             continue;
         }
         if (record.exit_code !== 0) {
-            throw new Error(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
+            issues.push(`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.`);
+            issues.push(`commands[${index}].status must be pass when QA gate status is pass.`);
         }
     }
+    throwCompletionPayloadIssues(issues);
 }
 function validateClassifiedNonBlockingQaFailure(record, index) {
     const classification = normalizedString(optionalString(record, "classification"));
@@ -318,18 +395,22 @@ export function validateArchitectPayloadShape(payload, status) {
         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) {
+    const taskIndexById = new Map();
+    for (const [taskIndex, task] of implementationPlan.tasks.entries()) {
         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}'.`);
+        const firstTaskIndex = taskIndexById.get(taskId);
+        if (firstTaskIndex !== undefined) {
+            throw new Error(`implementation_plan.tasks[${taskIndex}].id duplicates implementation_plan.tasks[${firstTaskIndex}].id '${taskId}'; correction: assign the duplicate a unique stable task id, update every phase/dependency reference to that task, and resubmit forge.complete_architect_plan.`);
         }
         taskIds.add(taskId);
+        taskIndexById.set(taskId, taskIndex);
         validateArchitectTaskDevelopScope(taskRecord, taskId);
+        requireNonEmptyStringArrayRecord(taskRecord, "acceptance_criteria", `implementation_plan.tasks[${taskId}].`);
         validateArchitectVerificationScope(taskRecord, taskId);
         requireArchitectArray(taskRecord, "tests", payload, { path: `implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests` });
         if (arrayLength(taskRecord, "tests") === 0) {
@@ -373,6 +454,7 @@ export function validateQaScopeRecord(scope, pathLabel) {
     }
     const surface = qaScopeStringArray(scope, "surface", pathLabel, qaScopeSurfaces);
     const requiredEvidence = qaScopeStringArray(scope, "required_evidence", pathLabel, qaScopeEvidence);
+    qaScopeStringArray(scope, "required_capabilities", pathLabel, qaScopeCapabilities);
     const notApplicable = qaScopeStringArray(scope, "not_applicable", pathLabel, qaScopeEvidence);
     const requiredSet = new Set(requiredEvidence);
     for (const evidence of notApplicable) {
@@ -715,22 +797,30 @@ export function validateQaPayloadShape(payload, status) {
             throw new Error("QA pass/needs_rework requires at least one command, browser check, or evidence note.");
         }
     }
+    const commandIssues = [];
     for (const [index, command] of commands.entries()) {
-        requireEvidenceRecord(command, `commands[${index}]`);
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            commandIssues.push(`commands[${index}] must be an object.`);
+            continue;
+        }
         const record = command;
-        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
-        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (!optionalString(record, "command"))
+            commandIssues.push(`commands[${index}].command is required.`);
+        if (!optionalString(record, "status"))
+            commandIssues.push(`commands[${index}].status is required.`);
+        if (!optionalString(record, "summary"))
+            commandIssues.push(`commands[${index}].summary is required.`);
         if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
-            throw new Error(`commands[${index}].exit_code is required.`);
+            commandIssues.push(`commands[${index}].exit_code is required.`);
         }
-        if (status === "pass" && record.exit_code !== 0) {
-            throw new Error(`commands[${index}].exit_code must be 0 when QA status is pass.`);
+        else if (status === "pass" && record.exit_code !== 0) {
+            commandIssues.push(`commands[${index}].exit_code must be 0 when QA status is pass.`);
         }
         if (status === "pass" && normalizedString(record.status) !== "pass") {
-            throw new Error(`commands[${index}].status must be pass when QA status is pass.`);
+            commandIssues.push(`commands[${index}].status must be pass when QA status is pass.`);
         }
     }
+    throwCompletionPayloadIssues(commandIssues);
     for (const [index, browserCheck] of browserChecks.entries()) {
         requireEvidenceRecord(browserCheck, `browser_checks[${index}]`);
         const record = browserCheck;
@@ -824,5 +914,5 @@ export function validateOptionalWorkItemId(payload, expectedWorkItemId) {
         throw new Error(`completion payload work item ${actual} does not match dispatch work item ${expectedWorkItemId}.`);
     }
 }
-import { requireField, requireNonPassEvidence, requireImplementationEvidence, requirePassingCommands, requireArray, requireNonEmptyArray, arrayLength, requireAllowedStatus, requireObject, requiredRecord, requireBoolean, requireNumericOne, requireSatisfiedAcceptanceCriteria, validateResolvedFindings, isDebugCompletionPhase, qaEvidenceSource, qaArray, qaObjectArray, qaPolicyWarnings, qaStringArray, requireEvidenceRecord, requireNonEmptyStringRecord, requireKnownStringRecord, requireNonEmptyStringArrayRecord, requireSubstantiveEvidenceRecord, normalizedString, requiredString, optionalString, stripUndefined, } from "./phase-completion.helpers.js";
+import { requireField, requireNonPassEvidence, requireImplementationEvidence, requirePassingCommands, requireArray, requireNonEmptyArray, arrayLength, requireAllowedStatus, requireObject, requiredRecord, requireBoolean, requireNumericOne, requireSatisfiedAcceptanceCriteria, validateResolvedFindings, isDebugCompletionPhase, qaEvidenceSource, qaArray, qaObjectArray, qaPolicyWarnings, qaStringArray, requireEvidenceRecord, requireNonEmptyStringRecord, requireKnownStringRecord, requireNonEmptyStringArrayRecord, requireSubstantiveEvidenceRecord, normalizedString, requiredString, optionalString, stripUndefined, throwCompletionPayloadIssues, } from "./phase-completion.helpers.js";
 export * from "./phase-completion.helpers.js";