@loucompanion/forge-bridge 0.1.3-dev.d1ca67076aa9 → 0.1.3-dev.e7b62d8fdd33

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,
@@ -237,12 +255,29 @@ export async function writeQaGateCompletionArtifact(config, gate, input) {
     const status = normalizeQaGateStatus(requiredString(payload, "status"));
     validateQaGatePayloadShape(gate, payload, status);
     validateOptionalWorkItemId(payload, config.workItemId);
-    const redactedPayload = redactSecrets({ ...payload, status }, config.redactionSecrets ?? []);
+    const ownerFields = artifactOwnerFields(config);
+    const validatedSidecars = gate === "qa_manual_web"
+        ? await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(payload, "sidecars", qaEvidenceSource(payload)), ownerFields.owner_type, ownerFields.owner_id)
+        : null;
+    const redactedPayload = redactSecrets({
+        ...payload,
+        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
         ?? "forge-completion-tool";
-    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);
@@ -262,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",
@@ -371,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,
@@ -424,7 +459,7 @@ async function synthesizeQaCycleVerdictPayload(config, payload, status) {
     ]);
     merged.browser_checks = dedupeUnknownArray([
         ...qaArray(payload, "browser_checks", payloadEvidence),
-        ...evidenceGates.flatMap((gate) => qaArray(gate, "browser_checks"))
+        ...evidenceGates.flatMap((gate) => qaArray(gate, "browser_checks").map(normalizeInheritedQaBrowserCheck))
     ]);
     merged.sidecars = dedupeUnknownArray([
         ...qaArray(payload, "sidecars", payloadEvidence),
@@ -516,6 +551,27 @@ function dedupeStrings(values) {
     }
     return deduped;
 }
+function normalizeInheritedQaBrowserCheck(browserCheck) {
+    if (!browserCheck || typeof browserCheck !== "object" || Array.isArray(browserCheck)) {
+        return browserCheck;
+    }
+    const record = browserCheck;
+    if (optionalString(record, "summary")) {
+        return record;
+    }
+    const target = optionalString(record, "url") ?? optionalString(record, "route") ?? "the configured browser target";
+    const status = optionalString(record, "status") ?? "recorded";
+    return {
+        ...record,
+        summary: `Inherited browser check ${status} for ${target}.`
+    };
+}
+function normalizeSha256ContentHash(contentHash) {
+    const normalized = contentHash.trim().toLowerCase();
+    return normalized.startsWith("sha256:")
+        ? normalized.slice("sha256:".length)
+        : normalized;
+}
 async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, ownerType, ownerId) {
     if (sidecars.length === 0) {
         return [];
@@ -525,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.`);
@@ -557,12 +614,22 @@ async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, o
             throw new Error(`sidecars[${index}].bytes does not match the referenced file.`);
         }
         const actualHash = await sha256File(fullPath);
-        if (actualHash !== contentHash.trim().toLowerCase()) {
+        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
         });
@@ -597,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

@@ -9,7 +9,8 @@ export type DebugCompletionPhase = "debug_repro" | "debug_root_cause" | "debug_f
 export type ArchitectCompletionPhase = "architect";
 export type DraftCompletionPhase = "draft";
 export type DecomposeCompletionPhase = "decompose";
-export type CompletionPhase = DevelopCompletionPhase | "qa" | DebugCompletionPhase | ArchitectCompletionPhase | DraftCompletionPhase | DecomposeCompletionPhase;
+export type CiRepairCompletionPhase = "ci_repair";
+export type CompletionPhase = DevelopCompletionPhase | "qa" | DebugCompletionPhase | ArchitectCompletionPhase | DraftCompletionPhase | DecomposeCompletionPhase | CiRepairCompletionPhase;
 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";
@@ -25,6 +26,7 @@ export interface CompletionToolRuntimeOptions {
     readonly dispatch: RunOnceDispatchPacket;
     readonly worktree: WorktreeHandle;
     readonly phase?: CompletionPhase;
+    readonly runtimeEnvironment?: Readonly<Record<string, string>>;
 }
 export interface CompletionToolServerConfig {
     readonly worktreePath: string;
@@ -47,6 +49,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;
@@ -56,7 +65,7 @@ export interface CompletionToolCallResult {
             readonly allowed: boolean;
             readonly reason: string;
         };
-        readonly nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready";
+        readonly nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready" | "provider_checks_ready";
         readonly nextInstruction: string;
     };
 }
@@ -98,6 +107,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

@@ -85,6 +85,9 @@ export function parseStrictCompletionPhase(value) {
     if (normalized === "decompose" || normalized === "decomposition" || normalized === "work_order_decomposition" || normalized === "feature_decomposition") {
         return "decompose";
     }
+    if (normalized === "ci_repair" || normalized === "pr_checks" || normalized === "repair_pr_checks") {
+        return "ci_repair";
+    }
     return null;
 }
 export function normalizeDebugCompletionPhase(value) {
@@ -156,6 +159,9 @@ export function phaseFromToolName(toolName) {
     if (normalized === "forge.complete_architect_plan" || normalized === "complete_architect_plan") {
         return "architect";
     }
+    if (normalized === "forge.complete_ci_repair" || normalized === "complete_ci_repair") {
+        return "ci_repair";
+    }
     if (draftGateFromToolName(toolName)) {
         return "draft";
     }
@@ -256,28 +262,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])) {
@@ -600,9 +623,22 @@ export async function readOptionalFile(filePath) {
 }
 export async function writeFileAtomic(filePath, content) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
-    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
     await fs.writeFile(tempPath, content, "utf8");
-    await fs.rename(tempPath, filePath);
+    try {
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        if (process.platform !== "win32" || !isNodeError(error) || (error.code !== "EPERM" && error.code !== "EEXIST")) {
+            await fs.rm(tempPath, { force: true });
+            throw error;
+        }
+        // Windows rename does not reliably replace an existing destination. QA-cycle gates
+        // intentionally refresh canonical bundle files, so remove only the exact destination
+        // after the replacement temp file is durable, then complete the rename.
+        await fs.rm(filePath, { force: true });
+        await fs.rename(tempPath, filePath);
+    }
 }
 export function stableStringify(value) {
     return JSON.stringify(sortJson(value));
@@ -626,7 +662,12 @@ export function forgeBridgeCliBinPath() {
     return fileURLToPath(new URL("../cli/bin.js", import.meta.url));
 }
 export function tomlString(value) {
-    return JSON.stringify(value);
+    if (value.includes("'''")) {
+        throw new Error("Codex MCP configuration values cannot contain three consecutive apostrophes.");
+    }
+    // Codex config overrides pass through npm's PowerShell shim on Windows.
+    // Literal TOML strings survive that boundary; basic-string double quotes do not.
+    return `'''${value}'''`;
 }
 export function tomlStringArray(values) {
     return `[${values.map(tomlString).join(", ")}]`;

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",
@@ -195,6 +197,10 @@ export const phaseFiles = {
     decompose: {
         jsonFileName: "decompose.proposal.json",
         reportFileName: "decompose.report.md"
+    },
+    ci_repair: {
+        jsonFileName: "ci-repair.handoff.json",
+        reportFileName: "ci-repair.report.md"
     }
 };
 export function completionPhaseFromDispatch(dispatch) {
@@ -224,6 +230,9 @@ export function normalizeCompletionPhase(value) {
     if (normalized === "decompose" || normalized === "decomposition" || normalized === "work_order_decomposition" || normalized === "feature_decomposition") {
         return "decompose";
     }
+    if (normalized === "ci_repair" || normalized === "pr_checks" || normalized === "repair_pr_checks") {
+        return "ci_repair";
+    }
     return "implementation";
 }
 export function usesDevelopCycleCompletion(dispatch) {
@@ -275,9 +284,11 @@ export function completionToolNamesForPhase(phase) {
             ? "complete_self_review"
             : phase === "validation"
                 ? "complete_validation"
-                : phase === "architect"
-                    ? "complete_architect_plan"
-                    : "complete_qa";
+                : phase === "ci_repair"
+                    ? "complete_ci_repair"
+                    : phase === "architect"
+                        ? "complete_architect_plan"
+                        : "complete_qa";
     return [`forge.${base}`, base];
 }
 export function completionToolNamesForQaGate(gate) {

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

@@ -1,13 +1,13 @@
 import { type CompletionPhase, type DebugCompletionPhase, type DecomposeCompletionGate, type DevelopCompletionPhase, type DraftCompletionGate, type QaCompletionGate } from "./phase-completion.js";
-export declare function completionPromptForPhase(phase: CompletionPhase): string;
+export declare function completionPromptForPhase(phase: CompletionPhase, artifactRoot?: string): string;
 export declare function completionPromptForDevelopCycle(phase: CompletionPhase): string;
-export declare function completionPromptForQaCycle(currentGate?: QaCompletionGate): string;
+export declare function completionPromptForQaCycle(currentGate?: QaCompletionGate, artifactRoot?: string): string;
 export declare function completionPromptForDraftCycle(currentGate?: DraftCompletionGate): string;
 export declare function completionPromptForDecomposeCycle(currentGate?: DecomposeCompletionGate): string;
 export declare function completionPromptForDebugCycle(currentGate?: DebugCompletionPhase): string;
 export declare function nextPhaseAfter(phase: CompletionPhase): DevelopCompletionPhase | null;
 export declare function nextDebugPhaseAfter(phase: DebugCompletionPhase): DebugCompletionPhase | null;
-export declare function completionToolNextInstruction(completedPhase: CompletionPhase, status: string, nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready"): string;
+export declare function completionToolNextInstruction(completedPhase: CompletionPhase, status: string, nextPhase: CompletionPhase | "dev_test_ready" | "qa_ready" | "sign_off_ready" | "provider_checks_ready"): string;
 export declare function completionToolNextInstructionForDraftGate(completedGate: DraftCompletionGate, status: string, nextGate: DraftCompletionGate | null): string;
 export declare function completionToolNextInstructionForQaGate(completedGate: QaCompletionGate, status: string, nextGate: QaCompletionGate | null): string;
 export declare function completionToolNextInstructionForDecomposeGate(completedGate: DecomposeCompletionGate, status: string, nextGate: DecomposeCompletionGate | null): string;