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

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

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { redactSecrets } from "../shared/redaction/redaction.js";
@@ -12,8 +13,11 @@ export async function writeDecomposeGateCompletionArtifact(config, gate, toolNam
         validateDecomposeProposalJson(proposalJson);
     }
     const redactedPayload = redactSecrets({ ...payload, status, phase: "decompose", gate, tool_name: toolName }, config.redactionSecrets ?? []);
+    assertStructuralFieldsUnchanged(payload, redactedPayload);
+    if (gate === "decompose_proposal") {
+        validatePostRedaction(() => validateDecomposeProposalJson(asRecord(redactedPayload["proposal_json"] ?? redactedPayload["decomposition_json"], "proposal_json")));
+    }
     const root = artifactRootFor(config.worktreePath, config.workItemId);
-    await fs.mkdir(root, { recursive: true });
     const artifactPath = path.join(root, decomposeGateFileNames[gate]);
     const reportPath = gate === "decompose_proposal" ? path.join(root, phaseFiles.decompose.reportFileName) : path.join(root, `${gate}.md`);
     const verdictJson = jsonText(redactedPayload);
@@ -21,8 +25,10 @@ export async function writeDecomposeGateCompletionArtifact(config, gate, toolNam
 
 ${optionalString(redactedPayload, "summary") ?? "Decompose gate recorded."}
 `;
-    await writeFileAtomic(artifactPath, verdictJson);
-    await writeFileAtomic(reportPath, report);
+    await publishArtifactBundleAtomic(root, [
+        { fileName: path.basename(reportPath), content: report },
+        { fileName: path.basename(artifactPath), content: verdictJson }
+    ], path.basename(artifactPath));
     return {
         phase: "decompose",
         workItemId: config.workItemId,
@@ -44,14 +50,19 @@ export async function writeDraftGateCompletionArtifact(config, gate, toolName, i
         validateDraftProposalJson(draftJson);
     }
     const redactedPayload = redactSecrets({ ...payload, status, phase: "draft", gate, tool_name: toolName }, config.redactionSecrets ?? []);
+    assertStructuralFieldsUnchanged(payload, redactedPayload);
+    if (gate === "draft_proposal") {
+        validatePostRedaction(() => validateDraftProposalJson(asRecord(redactedPayload["draft_json"], "draft_json")));
+    }
     const root = artifactRootFor(config.worktreePath, config.workItemId);
-    await fs.mkdir(root, { recursive: true });
     const artifactPath = path.join(root, draftGateFileNames[gate]);
     const reportPath = gate === "draft_proposal" ? path.join(root, phaseFiles.draft.reportFileName) : path.join(root, `${gate}.md`);
     const verdictJson = jsonText(redactedPayload);
     const report = optionalString(redactedPayload, "report_markdown") ?? `# ${gate.replace(/_/g, " ")}\n\n${optionalString(redactedPayload, "summary") ?? "Draft gate recorded."}\n`;
-    await writeFileAtomic(artifactPath, verdictJson);
-    await writeFileAtomic(reportPath, report);
+    await publishArtifactBundleAtomic(root, [
+        { fileName: path.basename(reportPath), content: report },
+        { fileName: path.basename(artifactPath), content: verdictJson }
+    ], path.basename(artifactPath));
     return {
         phase: "draft",
         workItemId: config.workItemId,
@@ -148,6 +159,11 @@ export async function writeCompletionArtifact(config, toolName, input) {
     validatePayloadShape(phase, validationPayload);
     validateOptionalWorkItemId(validationPayload, config.workItemId);
     const redactedPayload = redactSecrets(validationPayload, config.redactionSecrets ?? []);
+    assertStructuralFieldsUnchanged(validationPayload, redactedPayload);
+    validatePostRedaction(() => {
+        validatePayloadShape(phase, redactedPayload);
+        validateOptionalWorkItemId(redactedPayload, config.workItemId);
+    });
     const producedBy = optionalString(redactedPayload, "produced_by")
         ?? optionalString(redactedPayload, "producedBy")
         ?? config.producedBy
@@ -175,9 +191,10 @@ export async function writeCompletionArtifact(config, toolName, input) {
     const report = reportMarkdown(redactedPayload, phase, status, producedBy, contentHash);
     const artifactPath = completionArtifactJsonPath(config.worktreePath, config.workItemId, phase);
     const reportPath = completionArtifactReportPath(config.worktreePath, config.workItemId, phase);
-    await fs.mkdir(path.dirname(artifactPath), { recursive: true });
-    await writeFileAtomic(artifactPath, artifactJson);
-    await writeFileAtomic(reportPath, report);
+    await publishArtifactBundleAtomic(path.dirname(artifactPath), [
+        { fileName: path.basename(reportPath), content: report },
+        { fileName: path.basename(artifactPath), content: artifactJson }
+    ], path.basename(artifactPath));
     return {
         phase,
         workItemId: config.workItemId,
@@ -215,11 +232,12 @@ export async function writeArchitectCompletionArtifact(config, payload, status,
         ...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`);
+    await publishArtifactBundleAtomic(artifactRoot, [
+        { fileName: path.basename(implementationPlanPath), content: jsonText(implementationPlan) },
+        { fileName: path.basename(qaPlanPath), content: jsonText(qaPlan) },
+        { fileName: path.basename(reportPath), content: `${report.trim()}\n` },
+        { fileName: path.basename(verdictPath), content: jsonText(verdict) }
+    ], path.basename(verdictPath));
     return {
         phase: "architect",
         workItemId: config.workItemId,
@@ -246,6 +264,16 @@ export async function writeQaGateCompletionArtifact(config, gate, input) {
         status,
         ...(validatedSidecars ? { sidecars: validatedSidecars } : {})
     }, config.redactionSecrets ?? []);
+    assertStructuralFieldsUnchanged(payload, redactedPayload);
+    validatePostRedaction(() => {
+        validateQaGatePayloadShape(gate, redactedPayload, status);
+        validateOptionalWorkItemId(redactedPayload, config.workItemId);
+    });
+    if (gate === "qa_manual_web") {
+        await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(redactedPayload, "sidecars", qaEvidenceSource(redactedPayload)), ownerFields.owner_type, ownerFields.owner_id).catch((error) => {
+            throw postRedactionValidationError(error);
+        });
+    }
     const producedBy = optionalString(redactedPayload, "produced_by")
         ?? optionalString(redactedPayload, "producedBy")
         ?? config.producedBy
@@ -269,7 +297,6 @@ export async function writeQaGateCompletionArtifact(config, gate, input) {
         ...artifactWithoutHash,
         content_hash: contentHash
     };
-    await fs.mkdir(artifactRoot, { recursive: true });
     await writeFileAtomic(artifactPath, jsonText(artifact));
     return {
         phase: "qa",
@@ -378,12 +405,13 @@ export async function writeQaCompletionArtifact(config, payload, status, produce
         content_hash: contentHash
     });
     const finalReport = reportMarkdown(payload, "qa", status, producedBy, contentHash);
-    await fs.mkdir(artifactRoot, { recursive: true });
-    await writeFileAtomic(planPath, planJson);
-    await writeFileAtomic(evidencePath, evidenceJson);
-    await writeFileAtomic(findingsPath, findingsJson);
-    await writeFileAtomic(verdictPath, verdictJson);
-    await writeFileAtomic(reportPath, finalReport);
+    await publishArtifactBundleAtomic(artifactRoot, [
+        { fileName: path.basename(planPath), content: planJson },
+        { fileName: path.basename(evidencePath), content: evidenceJson },
+        { fileName: path.basename(findingsPath), content: findingsJson },
+        { fileName: path.basename(reportPath), content: finalReport },
+        { fileName: path.basename(verdictPath), content: verdictJson }
+    ], path.basename(verdictPath));
     return {
         phase: "qa",
         workItemId: config.workItemId,
@@ -553,6 +581,7 @@ async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, o
         : artifactRootFor(worktreePath, workItemId);
     const qaSidecarRoot = path.resolve(artifactRoot, "qa");
     const validated = [];
+    const validatedByPath = new Map();
     for (const [index, sidecar] of sidecars.entries()) {
         if (!sidecar || typeof sidecar !== "object" || Array.isArray(sidecar)) {
             throw new Error(`sidecars[${index}] must be an object.`);
@@ -588,9 +617,19 @@ async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, o
         if (actualHash !== normalizeSha256ContentHash(contentHash)) {
             throw new Error(`sidecars[${index}].content_hash does not match the referenced file.`);
         }
+        const canonicalPath = path.relative(worktreePath, fullPath).split(path.sep).join("/");
+        const duplicateKey = canonicalPath.toLowerCase();
+        const existing = validatedByPath.get(duplicateKey);
+        if (existing) {
+            if (existing.contentHash !== actualHash || existing.bytes !== stat.size) {
+                throw new Error(`sidecars[${index}] conflicts with another payload for ${canonicalPath}.`);
+            }
+            continue;
+        }
+        validatedByPath.set(duplicateKey, { contentHash: actualHash, bytes: stat.size });
         validated.push({
             ...record,
-            path: path.relative(worktreePath, fullPath).split(path.sep).join("/"),
+            path: canonicalPath,
             content_hash: actualHash,
             bytes: stat.size
         });
@@ -625,3 +664,166 @@ export async function readCompletionArtifact(worktreePath, workItemId, phase, ow
         phase
     };
 }
+/**
+ * Stages a complete phase bundle outside the live artifact directory, then
+ * publishes its canonical verdict/marker last. Consumers treat the marker as
+ * the bundle's commit point, so they can observe either the old complete bundle
+ * or the new complete bundle, never a partially written set. A failed or
+ * cancelled publication rolls every touched file back before rejecting.
+ */
+export async function publishArtifactBundleAtomic(artifactRoot, files, commitFileName, options = {}) {
+    validateArtifactBundleFiles(files, commitFileName);
+    throwIfPublicationCancelled(options.signal);
+    const parent = path.dirname(artifactRoot);
+    const transactionId = `${process.pid}.${crypto.randomUUID()}`;
+    const stagingRoot = path.join(parent, `.${path.basename(artifactRoot)}.${transactionId}.publish`);
+    const backupRoot = path.join(stagingRoot, ".previous");
+    const orderedFiles = [
+        ...files.filter((file) => file.fileName !== commitFileName),
+        files.find((file) => file.fileName === commitFileName)
+    ];
+    const backedUp = new Set();
+    const published = new Set();
+    try {
+        await fs.mkdir(parent, { recursive: true });
+        await fs.mkdir(stagingRoot, { recursive: false });
+        for (const file of orderedFiles) {
+            throwIfPublicationCancelled(options.signal);
+            const handle = await fs.open(path.join(stagingRoot, file.fileName), "wx");
+            try {
+                await handle.writeFile(file.content, { encoding: "utf8", signal: options.signal });
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        throwIfPublicationCancelled(options.signal);
+        await fs.mkdir(artifactRoot, { recursive: true });
+        await fs.mkdir(backupRoot, { recursive: true });
+        // Hide the previous commit marker before changing any supporting file.
+        for (const fileName of [commitFileName, ...orderedFiles.map((file) => file.fileName).filter((name) => name !== commitFileName)]) {
+            const livePath = path.join(artifactRoot, fileName);
+            try {
+                await fs.rename(livePath, path.join(backupRoot, fileName));
+                backedUp.add(fileName);
+            }
+            catch (error) {
+                if (!isNodeError(error) || error.code !== "ENOENT") {
+                    throw error;
+                }
+            }
+        }
+        for (const [index, file] of orderedFiles.entries()) {
+            throwIfPublicationCancelled(options.signal);
+            await options.beforePublishFile?.(file.fileName, index);
+            await fs.rename(path.join(stagingRoot, file.fileName), path.join(artifactRoot, file.fileName));
+            published.add(file.fileName);
+        }
+    }
+    catch (error) {
+        const rollbackErrors = [];
+        for (const file of [...orderedFiles].reverse()) {
+            if (!published.has(file.fileName))
+                continue;
+            await fs.rm(path.join(artifactRoot, file.fileName), { force: true }).catch(() => {
+                rollbackErrors.push(file.fileName);
+            });
+        }
+        // Restore the previous marker last for the same observable commit boundary.
+        const restoreOrder = [
+            ...orderedFiles.filter((file) => file.fileName !== commitFileName),
+            orderedFiles.find((file) => file.fileName === commitFileName)
+        ];
+        for (const file of restoreOrder) {
+            if (!backedUp.has(file.fileName))
+                continue;
+            await fs.rename(path.join(backupRoot, file.fileName), path.join(artifactRoot, file.fileName)).catch(() => {
+                rollbackErrors.push(file.fileName);
+            });
+        }
+        if (rollbackErrors.length === 0
+            && error instanceof Error
+            && error.message.startsWith("artifact_atomic_publish_cancelled:")) {
+            throw error;
+        }
+        const suffix = rollbackErrors.length > 0 ? " Rollback did not restore every bundle file." : "";
+        throw new Error(`artifact_atomic_publish_failure: completion artifact bundle was not published.${suffix}`, { cause: error });
+    }
+    finally {
+        await fs.rm(stagingRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+function validateArtifactBundleFiles(files, commitFileName) {
+    if (files.length === 0 || !files.some((file) => file.fileName === commitFileName)) {
+        throw new Error("artifact_atomic_publish_failure: bundle commit file is missing.");
+    }
+    const names = new Set();
+    for (const file of files) {
+        if (!file.fileName || path.basename(file.fileName) !== file.fileName || names.has(file.fileName)) {
+            throw new Error("artifact_atomic_publish_failure: bundle file names must be unique safe base names.");
+        }
+        names.add(file.fileName);
+    }
+}
+function throwIfPublicationCancelled(signal) {
+    if (signal?.aborted) {
+        throw new Error("artifact_atomic_publish_cancelled: completion artifact bundle publication was cancelled.");
+    }
+}
+function validatePostRedaction(validate) {
+    try {
+        validate();
+    }
+    catch (error) {
+        throw postRedactionValidationError(error);
+    }
+}
+function postRedactionValidationError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(`artifact_post_redaction_validation_failed: ${message}`, { cause: error });
+}
+function assertStructuralFieldsUnchanged(original, redacted) {
+    if (structuralFieldFingerprint(original) !== structuralFieldFingerprint(redacted)) {
+        // This stable code is intentionally safe for telemetry: it does not include
+        // the structural value or any candidate secret.
+        throw new Error("artifact_redaction_changed_structural_field: redaction changed a structural identifier; the bundle was not published.");
+    }
+}
+function structuralFieldFingerprint(value, key = "", result = []) {
+    if (Array.isArray(value)) {
+        if (isStructuralFieldKey(key) && value.every((item) => item === null || typeof item !== "object")) {
+            result.push(stableStringify(value));
+        }
+        else {
+            for (const item of value)
+                structuralFieldFingerprint(item, key, result);
+        }
+        return result.join("\n");
+    }
+    if (!value || typeof value !== "object") {
+        if (isStructuralFieldKey(key))
+            result.push(stableStringify(value));
+        return result.join("\n");
+    }
+    for (const [childKey, child] of Object.entries(value)) {
+        if (isStructuralFieldKey(childKey)) {
+            result.push(`${childKey}:${stableStringify(child)}`);
+        }
+        else {
+            structuralFieldFingerprint(child, childKey, result);
+        }
+    }
+    return result.join("\n");
+}
+function isStructuralFieldKey(key) {
+    return key === "id"
+        || key === "before"
+        || key === "after"
+        || key === "from"
+        || key === "to"
+        || key === "tasks"
+        || key === "phases"
+        || /(?:^|_)(?:id|ids)$/i.test(key)
+        || /(?:Id|Ids)$/.test(key);
+}

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

@@ -10,7 +10,8 @@ export type ArchitectCompletionPhase = "architect";
 export type DraftCompletionPhase = "draft";
 export type DecomposeCompletionPhase = "decompose";
 export type CiRepairCompletionPhase = "ci_repair";
-export type CompletionPhase = DevelopCompletionPhase | "qa" | DebugCompletionPhase | ArchitectCompletionPhase | DraftCompletionPhase | DecomposeCompletionPhase | CiRepairCompletionPhase;
+export type CommentRepairCompletionPhase = "comment_repair";
+export type CompletionPhase = DevelopCompletionPhase | "qa" | DebugCompletionPhase | ArchitectCompletionPhase | DraftCompletionPhase | DecomposeCompletionPhase | CiRepairCompletionPhase | CommentRepairCompletionPhase;
 export type QaCompletionGate = "qa_plan" | "qa_regression" | "qa_api" | "qa_manual_web" | "qa_bug_repro" | "qa_findings" | "qa_verdict";
 export type DraftCompletionGate = "draft_intent" | "draft_repo_context" | "draft_graph_context" | "draft_product_scope" | "draft_work_order_plan" | "draft_critic" | "draft_proposal";
 export type DecomposeCompletionGate = "decompose_subject_intake" | "decompose_context_review" | "decompose_breakdown_strategy" | "decompose_child_items" | "decompose_dependency_graph" | "decompose_critic" | "decompose_proposal";
@@ -20,6 +21,7 @@ export interface CompletionToolRuntime {
     readonly args: readonly string[];
     readonly env: Readonly<Record<string, string>>;
     readonly cursorMcpConfigPath?: string | null;
+    readonly claudeMcpConfigPath?: string | null;
     cleanup(): Promise<void>;
 }
 export interface CompletionToolRuntimeOptions {
@@ -49,6 +51,13 @@ export interface CompletionToolCallResult {
         readonly text: string;
     }[];
     readonly structuredContent: CompletionArtifactReference & {
+        readonly artifact_written: true;
+        readonly artifact_receipt: {
+            readonly schema_version: 1;
+            readonly path: string;
+            readonly report_path: string;
+            readonly content_hash: string;
+        };
         readonly gate: {
             readonly phase: CompletionPhase;
             readonly qaGate?: QaCompletionGate;
@@ -100,6 +109,7 @@ export declare const qaFindingScopes: Set<string>;
 export declare const qaCandidateBugActions: Set<string>;
 export declare const qaScopeSurfaces: Set<string>;
 export declare const qaScopeEvidence: Set<string>;
+export declare const qaScopeCapabilities: Set<string>;
 export declare const qaScopeSources: Set<string>;
 export declare const qaScopeAuthorities: Set<string>;
 export declare const qaScopeConfidence: Set<string>;

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

@@ -33,6 +33,11 @@ export declare function requireField(payload: Record<string, unknown>, key: stri
 export declare function requireNonPassEvidence(payload: Record<string, unknown>): void;
 export declare function requireImplementationEvidence(payload: Record<string, unknown>): void;
 export declare function requirePassingCommands(payload: Record<string, unknown>): void;
+export declare class CompletionPayloadValidationError extends Error {
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+export declare function throwCompletionPayloadIssues(issues: readonly string[]): void;
 export declare function requireArray(payload: Record<string, unknown>, key: string): void;
 export declare function requireNonEmptyArray(payload: Record<string, unknown>, key: string): void;
 export declare function arrayLength(payload: Record<string, unknown>, key: string): number;

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

@@ -88,6 +88,9 @@ export function parseStrictCompletionPhase(value) {
     if (normalized === "ci_repair" || normalized === "pr_checks" || normalized === "repair_pr_checks") {
         return "ci_repair";
     }
+    if (normalized === "comment_repair" || normalized === "pr_comments" || normalized === "repair_pr_comments") {
+        return "comment_repair";
+    }
     return null;
 }
 export function normalizeDebugCompletionPhase(value) {
@@ -162,6 +165,9 @@ export function phaseFromToolName(toolName) {
     if (normalized === "forge.complete_ci_repair" || normalized === "complete_ci_repair") {
         return "ci_repair";
     }
+    if (normalized === "forge.complete_comment_repair" || normalized === "complete_comment_repair") {
+        return "comment_repair";
+    }
     if (draftGateFromToolName(toolName)) {
         return "draft";
     }
@@ -262,28 +268,45 @@ export function requirePassingCommands(payload) {
     if (commands.length === 0) {
         throw new Error("commands must include at least one deterministic validation command.");
     }
+    const issues = [];
     for (const [index, command] of commands.entries()) {
         if (!command || typeof command !== "object" || Array.isArray(command)) {
-            throw new Error(`commands[${index}] must be an object.`);
+            issues.push(`commands[${index}] must be an object.`);
+            continue;
         }
         const record = command;
         if (typeof record.command !== "string" || record.command.trim().length === 0) {
-            throw new Error(`commands[${index}].command must be a non-empty string.`);
+            issues.push(`commands[${index}].command must be a non-empty string.`);
         }
         if (typeof record.summary !== "string" || record.summary.trim().length === 0) {
-            throw new Error(`commands[${index}].summary must be a non-empty string.`);
+            issues.push(`commands[${index}].summary must be a non-empty string.`);
         }
         if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
-            throw new Error(`commands[${index}].exit_code must be a finite number.`);
+            issues.push(`commands[${index}].exit_code must be a finite number.`);
         }
-        if (record.exit_code !== 0) {
-            throw new Error(`commands[${index}].exit_code must be 0 when status is pass.`);
+        else if (record.exit_code !== 0) {
+            issues.push(`commands[${index}].exit_code must be 0 when status is pass.`);
         }
         const status = typeof record.status === "string" ? record.status.trim().toLowerCase() : "";
         if (status !== "pass") {
-            throw new Error(`commands[${index}].status must be pass.`);
+            issues.push(`commands[${index}].status must be pass.`);
         }
     }
+    throwCompletionPayloadIssues(issues);
+}
+export class CompletionPayloadValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`completion_payload_invalid: ${issues.length} correction${issues.length === 1 ? "" : "s"} required; no artifact was written.\n`
+            + issues.map(issue => `- ${issue}`).join("\n")
+            + "\nRepair every listed field and resubmit this gate once.");
+        this.issues = issues;
+        this.name = "CompletionPayloadValidationError";
+    }
+}
+export function throwCompletionPayloadIssues(issues) {
+    if (issues.length > 0)
+        throw new CompletionPayloadValidationError(issues);
 }
 export function requireArray(payload, key) {
     if (!Array.isArray(payload[key])) {

package/dist/session/phase-completion.js

@@ -133,6 +133,7 @@ export const qaScopeEvidence = new Set([
     "migration_check",
     "config_check"
 ]);
+export const qaScopeCapabilities = new Set(["docker_engine"]);
 export const qaScopeSources = new Set(["user", "draft", "decompose", "architect", "heuristic", "system"]);
 export const qaScopeAuthorities = new Set(["user", "decompose", "architect", "system"]);
 export const qaScopeConfidence = new Set(["explicit", "inferred"]);
@@ -140,6 +141,7 @@ export const qaScopeFields = new Set([
     "schema_version",
     "surface",
     "required_evidence",
+    "required_capabilities",
     "not_applicable",
     "browser_required",
     "api_required",
@@ -199,6 +201,10 @@ export const phaseFiles = {
     ci_repair: {
         jsonFileName: "ci-repair.handoff.json",
         reportFileName: "ci-repair.report.md"
+    },
+    comment_repair: {
+        jsonFileName: "comment-repair.handoff.json",
+        reportFileName: "comment-repair.report.md"
     }
 };
 export function completionPhaseFromDispatch(dispatch) {
@@ -231,6 +237,9 @@ export function normalizeCompletionPhase(value) {
     if (normalized === "ci_repair" || normalized === "pr_checks" || normalized === "repair_pr_checks") {
         return "ci_repair";
     }
+    if (normalized === "comment_repair" || normalized === "pr_comments" || normalized === "repair_pr_comments") {
+        return "comment_repair";
+    }
     return "implementation";
 }
 export function usesDevelopCycleCompletion(dispatch) {
@@ -284,9 +293,11 @@ export function completionToolNamesForPhase(phase) {
                 ? "complete_validation"
                 : phase === "ci_repair"
                     ? "complete_ci_repair"
-                    : phase === "architect"
-                        ? "complete_architect_plan"
-                        : "complete_qa";
+                    : phase === "comment_repair"
+                        ? "complete_comment_repair"
+                        : phase === "architect"
+                            ? "complete_architect_plan"
+                            : "complete_qa";
     return [`forge.${base}`, base];
 }
 export function completionToolNamesForQaGate(gate) {

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

@@ -17,8 +17,9 @@ Forge will mirror only the tool-written QA artifacts; reporting QA completion in
 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", "verification_scope": { "schema_version": 1, "surface": ["domain_contract"], "required_evidence": ["unit_tests"], "not_applicable": ["browser_manual", "api_http"], "browser_required": false, "api_required": false, "rationale": "Backend-only child task." }, "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" }\`.
+\`{ "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", "verification_scope": { "schema_version": 1, "surface": ["domain_contract"], "required_evidence": ["unit_tests"], "required_capabilities": [], "not_applicable": ["browser_manual", "api_http"], "browser_required": false, "api_required": false, "rationale": "Backend-only child task." }, "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 should include \`verification_scope\` describing task-level QA evidence, and 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.
+When a task's implementation or validation starts containers or otherwise needs the host Docker daemon, include \`"required_capabilities": ["docker_engine"]\` in its verification scope. Do not encode a database, image, or Docker version as a runner capability; the repository owns those versions.
 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.`;
@@ -58,7 +59,8 @@ Complete the QA cycle in order inside this same provider session. Start long, in
 6. Follow the returned findings instruction, then call \`forge.complete_qa_findings(...)\`.
 7. Follow the returned verdict instruction, then call \`forge.complete_qa_verdict(...)\`.
 Use \`status: "skipped"\` with a reason for gates that are not applicable. If a gate is blocked, keep moving through later gates as skipped due to the blocker and finish with a blocked verdict.
-On a managed host, start solution-wide \`dotnet test Forge.sln\` evidence through \`forge.start_managed_command\` with at least a 45-minute timeout. Do not poll it. Continue independent QA work, then call \`forge.wait_managed_command\` once; Forge keeps the session healthy and streams durable progress while that call waits. Include the returned \`managed_command_id\` in command evidence. The regression gate rejects generic-shell timeouts and non-terminal receipts for that command.
+On a managed host, use focused checks plus the relevant runner-authored \`forge.start_managed_verification\` profiles for normal Story QA; shard slow tiers when broader evidence is justified. Reserve the \`dotnet_solution\` profile for shared test/runtime infrastructure, Feature/PR integration, or an explicit QA-plan requirement. Use \`forge.start_managed_command\` only for other commands expected to exceed two minutes. Continue independent QA work, then call \`forge.wait_managed_command\` for the durable terminal receipt; if it returns \`command_continues=true\`, continue useful work or wait again after \`retry_after_ms\`. Do not poll \`forge.get_managed_command\`. Include the terminal \`managed_command_id\` in command evidence. Forge records live progress outside the provider transcript.
+For a negative assertion, make the command itself exit 0 when the forbidden condition is absent. In particular, raw \`rg\` exit 1 means no matches but cannot be submitted as passing evidence; wrap it so no match exits 0, a match fails, and tool errors remain failures. Before every completion call, ensure passing command records have \`exit_code: 0\`, \`status: "pass"\`, and a summary. A rejected call writes no artifact; repair every issue returned by Forge and resubmit the same gate once without probing the filesystem.
 The final verdict tool writes the canonical QA bundle under \`${artifactRoot}/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`qa.verdict.json\`, and \`qa.report.md\`.
 Include \`policy_warnings\` in the final verdict for non-blocking Forge policy or scope mismatches that should remain visible after QA.
 The legacy \`forge.complete_qa\` one-shot tool is not available in normal QA-cycle mode. Reporting QA completion in prose is not enough.`;
@@ -90,7 +92,7 @@ Required order:
 5. Follow the returned dependency-graph instruction, validate keys/dependencies/order, then call \`forge.complete_decompose_dependency_graph(...)\`.
 6. Follow the returned critic instruction, critique scope, DAG safety, manual reconciliation risk, and missing acceptance detail, then call \`forge.complete_decompose_critic(...)\`.
 7. Follow the returned proposal instruction, then call \`forge.complete_decompose_proposal(...)\` with final JSON in \`proposal_json\`.
-The final proposal tool writes \`decompose.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. The proposal_json object must contain summary, optional blockedReason, and candidates. Work Order-to-Feature candidates may include \`estimated_qa_scope\`; Feature-to-Story candidates should include \`qa_scope\` with schema_version 1 plus scheduleIndex, waveIndex, expectedOutput, handoffSummary, and dependencyReason for dependency handoff.`;
+The final proposal tool writes \`decompose.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. The proposal_json object must contain summary, optional blockedReason, and candidates. Work Order-to-Feature candidates may include \`estimated_qa_scope\`; Feature-to-Story candidates should include \`qa_scope\` with schema_version 1 plus scheduleIndex, waveIndex, expectedOutput, handoffSummary, and dependencyReason for dependency handoff. Set \`qa_scope.required_capabilities\` to \`["docker_engine"]\` when implementation or validation starts containers or needs a Docker daemon; repository-specific service and image versions do not belong in the runner capability name.`;
 }
 export function completionPromptForDebugCycle(currentGate = "debug_repro") {
     return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
@@ -116,13 +118,7 @@ export function nextDebugPhaseAfter(phase) {
 }
 export function completionToolNextInstruction(completedPhase, status, nextPhase) {
     if (completedPhase === "qa") {
-        if (status === "blocked") {
-            return "QA blocked. Forge recorded the blocker reason and will surface the run for human attention.";
-        }
-        if (status === "needs_rework") {
-            return "QA findings recorded. Forge has the structured evidence needed to route this work back for implementation rework.";
-        }
-        return "QA accepted. Forge has the structured evidence needed to move this work item to Sign-Off.";
+        return qaLocalCompletionInstruction(status);
     }
     if (completedPhase === "ci_repair") {
         return status === "pass"
@@ -164,13 +160,7 @@ export function completionToolNextInstructionForDraftGate(completedGate, status,
 }
 export function completionToolNextInstructionForQaGate(completedGate, status, nextGate) {
     if (!nextGate) {
-        if (status === "blocked") {
-            return "QA blocked. Forge recorded the blocker reason and will surface the run for human attention.";
-        }
-        if (status === "needs_rework") {
-            return "QA findings recorded. Forge has the structured evidence needed to route this work back for implementation rework.";
-        }
-        return "QA accepted. Forge has the structured evidence needed to move this work item to Sign-Off.";
+        return qaLocalCompletionInstruction(status);
     }
     const skipped = status === "skipped";
     const blocked = status === "blocked";
@@ -181,6 +171,15 @@ export function completionToolNextInstructionForQaGate(completedGate, status, ne
             : `${completedGate} accepted. Continue to ${nextGate}.`;
     return `${prefix} ${qaGateInstruction(nextGate)}`;
 }
+function qaLocalCompletionInstruction(status) {
+    if (status === "blocked") {
+        return "QA blocker recorded locally. API ingestion and validation are still pending before Forge can surface the run for human attention.";
+    }
+    if (status === "needs_rework") {
+        return "QA findings recorded locally. API ingestion and validation are still pending before Forge can route implementation rework.";
+    }
+    return "QA bundle recorded locally. API ingestion and validation are still pending; this receipt does not authorize Sign-Off.";
+}
 export function completionToolNextInstructionForDecomposeGate(completedGate, status, nextGate) {
     if (status !== "pass") {
         return `Stay in ${completedGate}, address the recorded blockers/rework, then call ${expectedDecomposeCompletionToolName(completedGate)} again.`;
@@ -217,7 +216,7 @@ export function completionToolNextInstructionForDebugGate(completedGate, status,
 function qaGateInstruction(gate) {
     switch (gate) {
         case "qa_regression":
-            return "Run or explicitly skip applicable regression/build/lint/typecheck/e2e checks, then call forge.complete_qa_regression. On a managed host, start solution-wide dotnet test Forge.sln early with forge.start_managed_command using at least a 45-minute timeout. Do not poll it: continue independent QA checks, then call forge.wait_managed_command once and include its terminal managed_command_id in command evidence. Forge keeps the session healthy and streams durable progress while that wait call is active. A reproduced failure outside the current diff and acceptance criteria may remain non-blocking only when the current item has independent passing evidence: preserve it as an out_of_scope_failure with candidate_bug_id, scope_evidence, acceptance_criteria_independent: true, and a failing focused repro command/exit code. Never classify an unexplained, in-scope, or infrastructure failure this way.";
+            return "Run or explicitly skip applicable regression/build/lint/typecheck/e2e checks, then call forge.complete_qa_regression. For normal Story QA, prefer focused checks and runner-authored forge.start_managed_verification tier profiles; reserve dotnet_solution for shared infrastructure, Feature/PR integration, or an explicit plan requirement. Use forge.start_managed_command only for other commands expected to exceed two minutes, continue independent QA, then call forge.wait_managed_command and include its terminal managed_command_id in command evidence. If the wait returns command_continues=true, continue useful work or wait again after retry_after_ms; do not poll get_managed_command. Normalize negative assertions so an expected no-match exits 0. A reproduced failure outside the current diff and acceptance criteria may remain non-blocking only when the current item has independent passing evidence: preserve it as an out_of_scope_failure with candidate_bug_id, scope_evidence, acceptance_criteria_independent: true, and a failing focused repro command/exit code. Never classify an unexplained, in-scope, or infrastructure failure this way.";
         case "qa_api":
             return "Run or explicitly skip applicable API/backend contract checks, then call forge.complete_qa_api.";
         case "qa_manual_web":

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

@@ -4,6 +4,7 @@ export declare function prepareCompletionToolRuntime(options: CompletionToolRunt
 export declare function buildCompletionToolServerArgs(config: CompletionToolServerConfig): readonly string[];
 export declare function codexMcpConfigArgs(runtime: CompletionToolRuntime): readonly string[];
 export declare function cursorMcpServerConfig(runtime: CompletionToolRuntime): unknown;
+export declare function claudeMcpServerConfig(runtime: CompletionToolRuntime): unknown;
 export declare function completionToolNamesForServer(config: CompletionToolServerConfig): readonly string[];
 export declare class CompletionToolServerSession {
     private readonly config;
@@ -27,7 +28,7 @@ export declare class CompletionToolServerSession {
     private advanceAfterQaGate;
     private advanceAfterDebugGate;
 }
-export declare function completionToolRuntimeEnvironment(runtimeEnvironment?: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+export declare function completionToolRuntimeEnvironment(runtimeEnvironment?: Readonly<Record<string, string>>, nativeTestPostgresFallbackPath?: string | null): Readonly<Record<string, string>>;
 /**
  * A solution-wide Forge test is long enough that a generic provider shell can
  * expire while VSTest is still healthy. On managed host attempts, only the
@@ -45,3 +46,4 @@ export declare function parseCompletionMcpArgs(argv: readonly string[]): {
     readonly error: string;
 };
 export declare function completionRedactionEnv(secrets: readonly string[]): Readonly<Record<string, string>>;
+export declare function completionToolRejectedResult(toolName: string, error: unknown): Readonly<Record<string, unknown>>;