@loucompanion/forge-bridge 0.1.1-dev.7d43998c4521 → 0.1.1-dev.9acab970e5d1

package/dist/session/phase-completion.js

@@ -0,0 +1,2350 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { redactSecrets } from "../shared/redaction/redaction.js";
+import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "./qa-sidecar-validation.js";
+const toolServerName = "forge";
+const completionRedactionSecretsEnv = "FORGE_COMPLETION_REDACTION_SECRETS";
+const completionPhaseOrder = ["implementation", "self_review", "validation"];
+export const debugCompletionPhaseOrder = [
+    "debug_repro",
+    "debug_root_cause",
+    "debug_fix",
+    "debug_regression"
+];
+export const qaCompletionGateOrder = [
+    "qa_plan",
+    "qa_regression",
+    "qa_api",
+    "qa_manual_web",
+    "qa_bug_repro",
+    "qa_findings",
+    "qa_verdict"
+];
+const qaGateFileNames = {
+    qa_plan: "qa.plan.json",
+    qa_regression: "qa.regression.json",
+    qa_api: "qa.api.json",
+    qa_manual_web: "qa.manual-web.json",
+    qa_bug_repro: "qa.bug-repro.json",
+    qa_findings: "qa.findings.json",
+    qa_verdict: "qa.verdict.json"
+};
+const qaGateToolNames = {
+    qa_plan: "complete_qa_plan",
+    qa_regression: "complete_qa_regression",
+    qa_api: "complete_qa_api",
+    qa_manual_web: "complete_qa_manual_web",
+    qa_bug_repro: "complete_qa_bug_repro",
+    qa_findings: "complete_qa_findings",
+    qa_verdict: "complete_qa_verdict"
+};
+const debugGateToolNames = {
+    debug_repro: "complete_debug_repro",
+    debug_root_cause: "complete_debug_root_cause",
+    debug_fix: "complete_debug_fix",
+    debug_regression: "complete_debug_regression"
+};
+const qaBlockerReasons = new Set([
+    "missing_app_launch_target",
+    "inconclusive",
+    "environment_failure",
+    "missing_validation_evidence",
+    "missing_worktree",
+    "runner_failure"
+]);
+const qaFindingSeverities = new Set(["critical", "major", "minor"]);
+const qaFindingScopes = new Set(["in_scope", "out_of_scope", "unclear"]);
+const qaCandidateBugActions = new Set(["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"]);
+const phaseFiles = {
+    implementation: {
+        jsonFileName: "implementation.completeness.json",
+        reportFileName: "implementation.report.md"
+    },
+    self_review: {
+        jsonFileName: "self-review.report.json",
+        reportFileName: "self-review.summary.md"
+    },
+    validation: {
+        jsonFileName: "validation.verdict.json",
+        reportFileName: "validation.report.md"
+    },
+    qa: {
+        jsonFileName: "qa.verdict.json",
+        reportFileName: "qa.report.md"
+    },
+    debug_repro: {
+        jsonFileName: "debug.repro.json",
+        reportFileName: "debug.report.md"
+    },
+    debug_root_cause: {
+        jsonFileName: "debug.root-cause.json",
+        reportFileName: "debug.report.md"
+    },
+    debug_fix: {
+        jsonFileName: "debug.fix.json",
+        reportFileName: "debug.report.md"
+    },
+    debug_regression: {
+        jsonFileName: "debug.regression.json",
+        reportFileName: "debug.report.md"
+    }
+};
+export function completionPhaseFromDispatch(dispatch) {
+    return normalizeCompletionPhase(dispatch.cycleRun.phase || dispatch.execution.lane || dispatch.execution.role);
+}
+export function normalizeCompletionPhase(value) {
+    const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
+    const debugPhase = normalizeDebugCompletionPhase(normalized);
+    if (debugPhase) {
+        return debugPhase;
+    }
+    if (normalized === "self_review" || normalized === "selfreview" || normalized === "review") {
+        return "self_review";
+    }
+    if (normalized === "validate" || normalized === "validation") {
+        return "validation";
+    }
+    if (normalized === "qa" || normalized === "quality_assurance" || normalized === "qualityassurance") {
+        return "qa";
+    }
+    return "implementation";
+}
+export function usesDevelopCycleCompletion(dispatch) {
+    const kind = dispatch.cycleRun.kind.trim().toLowerCase();
+    const role = dispatch.execution.role.trim().toLowerCase();
+    const lane = dispatch.execution.lane.trim().toLowerCase();
+    return kind === "develop"
+        && role === "develop"
+        && lane === "develop"
+        && completionPhaseFromDispatch(dispatch) === "implementation";
+}
+export function usesQaCycleCompletion(dispatch) {
+    const kind = dispatch.cycleRun.kind.trim().toLowerCase();
+    const role = dispatch.execution.role.trim().toLowerCase();
+    const lane = dispatch.execution.lane.trim().toLowerCase();
+    return kind === "qa"
+        && role === "qa"
+        && lane === "qa"
+        && completionPhaseFromDispatch(dispatch) === "qa";
+}
+export function usesDebugCycleCompletion(dispatch) {
+    const kind = dispatch.cycleRun.kind.trim().toLowerCase();
+    const role = dispatch.execution.role.trim().toLowerCase();
+    const lane = dispatch.execution.lane.trim().toLowerCase();
+    return kind === "debug"
+        && role === "debug"
+        && lane === "debug"
+        && isDebugCompletionPhase(completionPhaseFromDispatch(dispatch));
+}
+export function completionToolNamesForPhase(phase) {
+    if (isDebugCompletionPhase(phase)) {
+        return completionToolNamesForDebugGate(phase);
+    }
+    const base = phase === "implementation"
+        ? "complete_implementation"
+        : phase === "self_review"
+            ? "complete_self_review"
+            : phase === "validation"
+                ? "complete_validation"
+                : "complete_qa";
+    return [`forge.${base}`, base];
+}
+export function completionToolNamesForQaGate(gate) {
+    const base = qaGateToolNames[gate];
+    return [`forge.${base}`, base];
+}
+export function completionToolNamesForDebugGate(gate) {
+    const base = debugGateToolNames[gate];
+    return [`forge.${base}`, base];
+}
+export function expectedCompletionToolName(phase) {
+    return completionToolNamesForPhase(phase)[0];
+}
+export function expectedQaCompletionToolName(gate) {
+    return completionToolNamesForQaGate(gate)[0];
+}
+export function expectedDebugCompletionToolName(gate) {
+    return completionToolNamesForDebugGate(gate)[0];
+}
+export function artifactRootFor(worktreePath, workItemId) {
+    return path.join(worktreePath, ".forge", "work-items", safePathSegment(workItemId, "work item id"), "artifacts");
+}
+function artifactRootForOwner(worktreePath, ownerType, ownerId) {
+    return path.join(worktreePath, ".forge", artifactOwnerDirectory(ownerType), safePathSegment(ownerId, "owner id"), "artifacts");
+}
+export function completionArtifactJsonPath(worktreePath, workItemId, phase) {
+    return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].jsonFileName);
+}
+export function completionArtifactReportPath(worktreePath, workItemId, phase) {
+    return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].reportFileName);
+}
+export async function prepareCompletionToolRuntime(options) {
+    const phase = options.phase ?? completionPhaseFromDispatch(options.dispatch);
+    const worktreePath = path.resolve(options.worktree.worktreePath);
+    const workItemId = options.dispatch.workItem.id;
+    const ownerType = normalizedOwnerType(options.dispatch.cycleRun.ownerType) ?? "work_item";
+    const ownerId = options.dispatch.cycleRun.ownerId ?? workItemId;
+    const mcpArgs = buildCompletionToolServerArgs({
+        worktreePath,
+        workItemId,
+        ownerType,
+        ownerId,
+        phase,
+        producedBy: `${options.dispatch.execution.provider}-cli`,
+        developCycle: usesDevelopCycleCompletion(options.dispatch),
+        qaCycle: usesQaCycleCompletion(options.dispatch),
+        debugCycle: usesDebugCycleCompletion(options.dispatch)
+    });
+    const runtime = {
+        serverName: toolServerName,
+        command: process.execPath,
+        args: [forgeBridgeCliBinPath(), ...mcpArgs],
+        env: {},
+        cleanup: async () => undefined
+    };
+    if (options.dispatch.execution.provider.trim().toLowerCase() !== "cursor") {
+        return runtime;
+    }
+    return await prepareCursorCompletionToolRuntime(worktreePath, runtime);
+}
+export function buildCompletionToolServerArgs(config) {
+    const args = [
+        "mcp",
+        "--worktree",
+        path.resolve(config.worktreePath),
+        "--work-item-id",
+        config.workItemId,
+        "--phase",
+        config.phase,
+        "--produced-by",
+        config.producedBy ?? "forge-completion-tool"
+    ];
+    if (config.ownerType || config.ownerId) {
+        args.push("--owner-type", normalizedOwnerType(config.ownerType) ?? "work_item");
+        args.push("--owner-id", config.ownerId ?? config.workItemId);
+    }
+    if (config.developCycle) {
+        args.push("--develop-cycle");
+    }
+    if (config.qaCycle) {
+        args.push("--qa-cycle");
+    }
+    if (config.debugCycle) {
+        args.push("--debug-cycle");
+    }
+    return args;
+}
+export function codexMcpConfigArgs(runtime) {
+    const prefix = `mcp_servers.${runtime.serverName}`;
+    const args = [
+        "-c",
+        `${prefix}.command=${tomlString(runtime.command)}`,
+        "-c",
+        `${prefix}.args=${tomlStringArray(runtime.args)}`
+    ];
+    for (const [key, value] of Object.entries(runtime.env)) {
+        args.push("-c", `${prefix}.env.${key}=${tomlString(value)}`);
+    }
+    return args;
+}
+export function cursorMcpServerConfig(runtime) {
+    return {
+        command: runtime.command,
+        args: [...runtime.args],
+        env: runtime.env
+    };
+}
+export function completionPromptForPhase(phase) {
+    const toolName = expectedCompletionToolName(phase);
+    const alias = completionToolNamesForPhase(phase).find((name) => name !== toolName);
+    const artifactName = phaseFiles[phase].jsonFileName;
+    if (phase === "qa") {
+        return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write QA artifacts by hand. When QA is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required structured QA payload.
+That tool writes the durable QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`${artifactName}\`, and \`qa.report.md\`.
+Use \`status: "pass"\` only when the validated changes satisfy acceptance criteria with concrete evidence. Use \`status: "needs_rework"\` with actionable in-scope findings, or \`status: "blocked"\` with a concrete blocker_reason.
+Forge will mirror only the tool-written QA artifacts; reporting QA completion in prose is not enough.`;
+    }
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write phase artifacts by hand. When the phase is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required evidence payload.
+That tool writes \`.forge/work-items/{workItemId}/artifacts/${artifactName}\` and returns the artifact reference that Forge will mirror through the existing phase-artifact pipeline.
+If the work cannot pass, call the same tool with a non-pass status and explicit blockers instead of reporting completion in prose only.`;
+}
+export function completionPromptForDevelopCycle(phase) {
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write phase artifacts by hand. The tool server enforces phase order and starts this run in \`${phase}\`.
+Complete the dev cycle in order inside this same provider session:
+1. Call \`forge.complete_implementation(...)\` when implementation evidence is ready.
+2. Follow the returned self-review instruction, then call \`forge.complete_self_review(...)\`.
+3. Follow the returned validation instruction, then call \`forge.complete_validation(...)\`.
+Each tool writes the canonical artifact under \`.forge/work-items/{workItemId}/artifacts/\` and returns the next-phase instruction Forge expects you to follow.
+If the current phase cannot pass, call the current phase tool with a non-pass status and explicit blockers instead of reporting completion in prose only.`;
+}
+export function completionPromptForQaCycle(currentGate = "qa_plan") {
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write QA artifacts by hand. The tool server enforces QA gate order and starts this run at \`${currentGate}\`.
+Complete the QA cycle in order inside this same provider session:
+1. Call \`forge.complete_qa_plan(...)\` after the QA test plan/checklist is ready.
+2. Follow the returned regression instruction, then call \`forge.complete_qa_regression(...)\`.
+3. Follow the returned API/backend instruction, then call \`forge.complete_qa_api(...)\`.
+4. Follow the returned manual web instruction, then call \`forge.complete_qa_manual_web(...)\`.
+5. Follow the returned bug reproduction instruction, then call \`forge.complete_qa_bug_repro(...)\`.
+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.
+The final verdict tool writes the canonical QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`qa.verdict.json\`, and \`qa.report.md\`.
+The legacy \`forge.complete_qa\` one-shot tool is not available in normal QA-cycle mode. Reporting QA completion in prose is not enough.`;
+}
+export function completionPromptForDebugCycle(currentGate = "debug_repro") {
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write Debug artifacts by hand. The tool server enforces Debug gate order and starts this run at \`${currentGate}\`.
+Complete the Debug cycle in order inside this same provider session:
+1. Reproduce or tightly characterize the bug, then call \`forge.complete_debug_repro(...)\`.
+2. Follow the returned root-cause instruction, isolate evidence, then call \`forge.complete_debug_root_cause(...)\`.
+3. Follow the returned fix instruction, apply the smallest safe fix with regression coverage when practical, then call \`forge.complete_debug_fix(...)\`.
+4. Follow the returned regression instruction, prove the original repro is negative and the fix is QA-ready, then call \`forge.complete_debug_regression(...)\`.
+Each tool writes a canonical Debug artifact under \`.forge/work-items/{workItemId}/artifacts/\`: \`debug.repro.json\`, \`debug.root-cause.json\`, \`debug.fix.json\`, and \`debug.regression.json\` plus \`debug.report.md\` when report text is provided or generated.
+Use a non-pass status with explicit blockers when the current Debug gate cannot pass. Reporting Debug completion in prose is not enough; the relevant MCP completion tool is the transition request.`;
+}
+export function completionToolNamesForServer(config) {
+    return config.debugCycle
+        ? debugCompletionPhaseOrder.flatMap((gate) => completionToolNamesForDebugGate(gate))
+        : config.qaCycle
+            ? qaCompletionGateOrder.flatMap((gate) => completionToolNamesForQaGate(gate))
+            : config.developCycle
+                ? completionPhaseOrder.flatMap((phase) => completionToolNamesForPhase(phase))
+                : completionToolNamesForPhase(config.phase);
+}
+export class CompletionToolServerSession {
+    config;
+    currentPhase;
+    currentQaGate = "qa_plan";
+    completed = false;
+    constructor(config) {
+        this.config = config;
+        this.currentPhase = config.phase;
+    }
+    get instructions() {
+        return this.config.debugCycle
+            ? completionPromptForDebugCycle(asDebugCompletionPhase(this.currentPhase))
+            : this.config.qaCycle
+                ? completionPromptForQaCycle(this.currentQaGate)
+                : this.config.developCycle
+                    ? completionPromptForDevelopCycle(this.currentPhase)
+                    : completionPromptForPhase(this.currentPhase);
+    }
+    toolDefinitions() {
+        return completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name), qaGateFromToolName(name)));
+    }
+    async callTool(toolName, input) {
+        const requestedPhase = phaseFromToolName(toolName);
+        if (this.completed) {
+            throw new Error("Forge completion cycle is already complete; no more completion calls are accepted.");
+        }
+        if (this.config.debugCycle) {
+            return await this.callDebugGateTool(toolName, requestedPhase, input);
+        }
+        if (this.config.qaCycle) {
+            return await this.callQaGateTool(toolName, requestedPhase, input);
+        }
+        if (requestedPhase !== this.currentPhase) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge phase is ${this.currentPhase}.`);
+        }
+        const completedPhase = this.currentPhase;
+        const reference = await writeCompletionArtifact({ ...this.config, phase: completedPhase }, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const pass = status === "pass";
+        const nextPhase = pass
+            ? 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.`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Forge recorded ${reference.phase} completion artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}`
+                }
+            ],
+            structuredContent: {
+                ...reference,
+                gate: {
+                    phase: completedPhase,
+                    status,
+                    allowed: pass,
+                    reason
+                },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
+    async callDebugGateTool(toolName, requestedPhase, input) {
+        const currentDebugGate = asDebugCompletionPhase(this.currentPhase);
+        if (!isDebugCompletionPhase(requestedPhase)) {
+            throw new Error(`Tool ${toolName} is not available in Debug-cycle mode. Current Forge Debug gate is ${currentDebugGate}.`);
+        }
+        if (requestedPhase !== currentDebugGate) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge Debug gate is ${currentDebugGate}.`);
+        }
+        const completedGate = currentDebugGate;
+        const reference = await writeCompletionArtifact({ ...this.config, phase: completedGate }, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const pass = status === "pass";
+        const nextGate = pass ? this.advanceAfterDebugGate(completedGate) : completedGate;
+        const nextPhase = nextGate ?? "qa_ready";
+        const nextInstruction = completionToolNextInstructionForDebugGate(completedGate, status, nextGate);
+        const reason = pass
+            ? `${completedGate} artifact accepted${nextGate ? `; continue to ${nextGate}.` : "; Debug regression is QA-ready."}`
+            : `${completedGate} artifact recorded with status ${status}; rework is required before Debug progression.`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}`
+                }
+            ],
+            structuredContent: {
+                ...reference,
+                gate: {
+                    phase: completedGate,
+                    status,
+                    allowed: pass,
+                    reason
+                },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
+    async callQaGateTool(toolName, requestedPhase, input) {
+        const requestedGate = qaGateFromToolName(toolName);
+        if (requestedPhase !== "qa" || !requestedGate) {
+            throw new Error(`Tool ${toolName} is not available in QA-cycle mode. Current Forge QA gate is ${this.currentQaGate}.`);
+        }
+        if (requestedGate !== this.currentQaGate) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge QA gate is ${this.currentQaGate}.`);
+        }
+        const completedGate = this.currentQaGate;
+        const reference = await writeCompletionArtifact({ ...this.config, phase: "qa" }, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const nextGate = this.advanceAfterQaGate(completedGate);
+        const nextPhase = nextGate ? "qa" : "sign_off_ready";
+        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}.`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}`
+                }
+            ],
+            structuredContent: {
+                ...reference,
+                gate: {
+                    phase: "qa",
+                    qaGate: completedGate,
+                    status,
+                    allowed,
+                    reason
+                },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
+    advanceAfterPass(phase) {
+        if (phase === "qa") {
+            this.completed = true;
+            return "sign_off_ready";
+        }
+        if (isDebugCompletionPhase(phase)) {
+            return nextDebugPhaseAfter(phase) ?? "qa_ready";
+        }
+        const next = nextPhaseAfter(phase);
+        if (!this.config.developCycle) {
+            return next ?? "dev_test_ready";
+        }
+        if (next) {
+            this.currentPhase = next;
+            return next;
+        }
+        this.completed = true;
+        return "dev_test_ready";
+    }
+    advanceAfterQaGate(gate) {
+        const index = qaCompletionGateOrder.indexOf(gate);
+        const next = index >= 0 ? qaCompletionGateOrder[index + 1] ?? null : null;
+        if (next) {
+            this.currentQaGate = next;
+            return next;
+        }
+        this.completed = true;
+        return null;
+    }
+    advanceAfterDebugGate(gate) {
+        const index = debugCompletionPhaseOrder.indexOf(gate);
+        const next = index >= 0 ? debugCompletionPhaseOrder[index + 1] ?? null : null;
+        if (next) {
+            this.currentPhase = next;
+            return next;
+        }
+        this.completed = true;
+        return null;
+    }
+}
+export async function writeCompletionArtifact(config, toolName, input) {
+    const phase = phaseFromToolName(toolName);
+    if (phase !== config.phase) {
+        throw new Error(`Tool ${toolName} is not allowed for phase ${config.phase}.`);
+    }
+    const qaGate = qaGateFromToolName(toolName);
+    if (qaGate && qaGate !== "qa_verdict") {
+        return await writeQaGateCompletionArtifact(config, qaGate, input);
+    }
+    const payload = asRecord(input, "completion payload");
+    const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
+    const validationPayload = { ...payload, status };
+    validatePayloadShape(phase, validationPayload);
+    validateOptionalWorkItemId(validationPayload, config.workItemId);
+    const redactedPayload = redactSecrets(validationPayload, config.redactionSecrets ?? []);
+    const producedBy = optionalString(redactedPayload, "produced_by")
+        ?? optionalString(redactedPayload, "producedBy")
+        ?? config.producedBy
+        ?? "forge-completion-tool";
+    if (phase === "qa") {
+        return await writeQaCompletionArtifact(config, redactedPayload, status, producedBy);
+    }
+    const artifactWithoutHash = normalizeArtifactPayload(redactedPayload, {
+        phase,
+        workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
+        producedBy,
+        status
+    });
+    const contentHash = sha256(stableStringify(artifactWithoutHash));
+    const artifact = {
+        ...artifactWithoutHash,
+        content_hash: contentHash
+    };
+    const artifactJson = `${JSON.stringify(artifact, null, 2)}\n`;
+    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);
+    return {
+        phase,
+        workItemId: config.workItemId,
+        ...artifactReferenceOwnerFields(config),
+        repoPath: path.resolve(config.worktreePath),
+        path: artifactPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
+async function writeQaGateCompletionArtifact(config, gate, input) {
+    const payload = asRecord(input, "QA gate completion payload");
+    const status = normalizeQaGateStatus(requiredString(payload, "status"));
+    validateQaGatePayloadShape(gate, payload, status);
+    validateOptionalWorkItemId(payload, config.workItemId);
+    const redactedPayload = redactSecrets({ ...payload, status }, config.redactionSecrets ?? []);
+    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);
+    const fileName = qaGateFileNames[gate];
+    const artifactPath = path.join(artifactRoot, fileName);
+    const reportPath = path.join(artifactRoot, "qa.report.md");
+    const artifactWithoutHash = normalizeQaGateArtifactPayload(redactedPayload, {
+        gate,
+        workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
+        producedBy,
+        status
+    });
+    const contentHash = sha256(stableStringify(artifactWithoutHash));
+    const artifact = {
+        ...artifactWithoutHash,
+        content_hash: contentHash
+    };
+    await fs.mkdir(artifactRoot, { recursive: true });
+    await writeFileAtomic(artifactPath, jsonText(artifact));
+    return {
+        phase: "qa",
+        workItemId: config.workItemId,
+        ...artifactReferenceOwnerFields(config),
+        repoPath: path.resolve(config.worktreePath),
+        path: artifactPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
+async function writeQaCompletionArtifact(config, payload, status, producedBy) {
+    const ownerFields = artifactOwnerFields(config);
+    const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
+        ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
+        : artifactRootFor(config.worktreePath, config.workItemId);
+    const planPath = path.join(artifactRoot, "qa.plan.json");
+    const evidencePath = path.join(artifactRoot, "qa.evidence.json");
+    const findingsPath = path.join(artifactRoot, "qa.findings.json");
+    const verdictPath = path.join(artifactRoot, "qa.verdict.json");
+    const reportPath = path.join(artifactRoot, "qa.report.md");
+    const relativeEvidencePath = ownerFields.owner_type && ownerFields.owner_id
+        ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.evidence.json")
+        : qaArtifactRelativePath(config.workItemId, "qa.evidence.json");
+    const relativeFindingsPath = ownerFields.owner_type && ownerFields.owner_id
+        ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.findings.json")
+        : qaArtifactRelativePath(config.workItemId, "qa.findings.json");
+    const relativeReportPath = ownerFields.owner_type && ownerFields.owner_id
+        ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.report.md")
+        : qaArtifactRelativePath(config.workItemId, "qa.report.md");
+    const evidenceSource = qaEvidenceSource(payload);
+    const commands = qaArray(payload, "commands", evidenceSource);
+    const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
+    const sidecars = await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(payload, "sidecars", evidenceSource), ownerFields.owner_type, ownerFields.owner_id);
+    const notes = optionalString(payload, "notes") ?? optionalString(evidenceSource, "notes") ?? "";
+    const findings = qaObjectArray(payload, "findings");
+    const candidateBugs = qaObjectArray(payload, "candidate_bugs");
+    const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
+    const explicitFindingIds = qaStringArray(payload, "finding_ids");
+    const explicitCandidateBugIds = qaStringArray(payload, "candidate_bug_ids");
+    const blockerReason = optionalString(payload, "blocker_reason");
+    const checklist = qaStringArray(payload, "checklist");
+    const planJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        ...ownerFields,
+        checklist: checklist.length > 0 ? checklist : defaultQaChecklist(status),
+        acceptance_criteria: testedAcceptanceCriteria
+    });
+    const evidenceJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        ...ownerFields,
+        commands,
+        browser_checks: browserChecks,
+        sidecars,
+        notes
+    });
+    const findingsJson = jsonText({
+        schema_version: 1,
+        phase: "qa",
+        ...ownerFields,
+        findings,
+        candidate_bugs: candidateBugs
+    });
+    const findingIds = status === "pass"
+        ? []
+        : explicitFindingIds.length > 0
+            ? explicitFindingIds
+            : findings
+                .filter((finding) => normalizedString(finding.scope) === "in_scope")
+                .map((finding) => optionalString(finding, "id"))
+                .filter((id) => Boolean(id));
+    const candidateBugIds = explicitCandidateBugIds.length > 0
+        ? explicitCandidateBugIds
+        : candidateBugs
+            .map((candidateBug) => optionalString(candidateBug, "id"))
+            .filter((id) => Boolean(id));
+    const verdictWithoutHash = {
+        schema_version: numberOrDefault(payload.schema_version, 1),
+        phase: "qa",
+        ...ownerFields,
+        status,
+        summary: requiredString(payload, "summary"),
+        tested_acceptance_criteria: testedAcceptanceCriteria,
+        finding_ids: findingIds,
+        candidate_bug_ids: candidateBugIds,
+        blocker_reason: status === "blocked" ? normalizedString(blockerReason) : null,
+        evidence_path: relativeEvidencePath,
+        findings_path: relativeFindingsPath,
+        report_path: relativeReportPath,
+        produced_by: producedBy
+    };
+    const contentHash = sha256(stableStringify({
+        plan: JSON.parse(planJson),
+        evidence: JSON.parse(evidenceJson),
+        findings: JSON.parse(findingsJson),
+        verdict: verdictWithoutHash
+    }));
+    const verdictJson = jsonText({
+        ...verdictWithoutHash,
+        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);
+    return {
+        phase: "qa",
+        workItemId: config.workItemId,
+        ...artifactReferenceOwnerFields(config),
+        repoPath: path.resolve(config.worktreePath),
+        path: verdictPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
+async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, ownerType, ownerId) {
+    if (sidecars.length === 0) {
+        return [];
+    }
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    const qaSidecarRoot = path.resolve(artifactRoot, "qa");
+    const validated = [];
+    for (const [index, sidecar] of sidecars.entries()) {
+        if (!sidecar || typeof sidecar !== "object" || Array.isArray(sidecar)) {
+            throw new Error(`sidecars[${index}] must be an object.`);
+        }
+        const record = sidecar;
+        const sidecarPath = optionalString(record, "path");
+        const contentHash = optionalString(record, "content_hash");
+        const bytes = record.bytes;
+        if (!sidecarPath || !contentHash || typeof bytes !== "number" || !Number.isFinite(bytes) || bytes <= 0) {
+            throw new Error(`sidecars[${index}] must include path, content_hash, and positive bytes.`);
+        }
+        if (path.isAbsolute(sidecarPath)) {
+            throw new Error(`sidecars[${index}].path must be relative to the worktree.`);
+        }
+        const fullPath = path.resolve(worktreePath, sidecarPath);
+        if (!isPathUnderRoot(qaSidecarRoot, fullPath)) {
+            throw new Error(`sidecars[${index}].path must be under ${artifactOwnerRelativeRoot(ownerType, ownerId, workItemId)}/qa/.`);
+        }
+        const stat = await fs.lstat(fullPath).catch((error) => {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                throw new Error(`sidecars[${index}].path does not exist: ${sidecarPath}`);
+            }
+            throw error;
+        });
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`sidecars[${index}].path must reference a regular file.`);
+        }
+        await ensureNoSymbolicLinkPathSegments(qaSidecarRoot, path.dirname(fullPath), `sidecars[${index}].path must not traverse symbolic links.`);
+        if (stat.size !== bytes) {
+            throw new Error(`sidecars[${index}].bytes does not match the referenced file.`);
+        }
+        const actualHash = await sha256File(fullPath);
+        if (actualHash !== contentHash.trim().toLowerCase()) {
+            throw new Error(`sidecars[${index}].content_hash does not match the referenced file.`);
+        }
+        validated.push({
+            ...record,
+            path: path.relative(worktreePath, fullPath).split(path.sep).join("/"),
+            content_hash: actualHash,
+            bytes: stat.size
+        });
+    }
+    return validated;
+}
+export async function readCompletionArtifact(worktreePath, workItemId, phase) {
+    const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase);
+    const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase);
+    const verdictJson = await readOptionalFile(artifactPath);
+    if (verdictJson === null) {
+        return null;
+    }
+    const parsed = parseJsonObject(verdictJson, artifactPath);
+    const report = await readOptionalFile(reportPath) ?? fallbackReport(parsed, phase, artifactPath);
+    return {
+        repoPath: path.resolve(worktreePath),
+        path: artifactPath,
+        verdictJson,
+        report,
+        producedBy: optionalString(parsed, "produced_by") ?? optionalString(parsed, "producedBy") ?? "forge-completion-tool",
+        status: optionalString(parsed, "status") ?? "unknown",
+        phase
+    };
+}
+export async function runCompletionMcpServer(config) {
+    const session = new CompletionToolServerSession(config);
+    process.stdin.setEncoding("utf8");
+    let buffer = "";
+    for await (const chunk of process.stdin) {
+        buffer += chunk;
+        let newlineIndex = buffer.indexOf("\n");
+        while (newlineIndex >= 0) {
+            const rawLine = buffer.slice(0, newlineIndex).trim();
+            buffer = buffer.slice(newlineIndex + 1);
+            if (rawLine.length > 0) {
+                await handleJsonRpcLine(session, rawLine);
+            }
+            newlineIndex = buffer.indexOf("\n");
+        }
+    }
+    const trailing = buffer.trim();
+    if (trailing.length > 0) {
+        await handleJsonRpcLine(session, trailing);
+    }
+}
+export function parseCompletionMcpArgs(argv) {
+    let worktreePath = null;
+    let workItemId = null;
+    let phase = "implementation";
+    let ownerType;
+    let ownerId;
+    let producedBy;
+    let developCycle = false;
+    let qaCycle = false;
+    let debugCycle = false;
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--worktree") {
+            worktreePath = argv[++index] ?? null;
+        }
+        else if (arg === "--work-item-id") {
+            workItemId = argv[++index] ?? null;
+        }
+        else if (arg === "--owner-type") {
+            ownerType = normalizedOwnerType(argv[++index]);
+            if (!ownerType) {
+                return { ok: false, error: "mcp --owner-type must be work_item or story." };
+            }
+        }
+        else if (arg === "--owner-id") {
+            ownerId = argv[++index] ?? undefined;
+        }
+        else if (arg === "--phase") {
+            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, debug-repro, debug-root-cause, debug-fix, debug-regression." };
+            }
+            phase = parsedPhase;
+        }
+        else if (arg === "--produced-by") {
+            producedBy = argv[++index] ?? undefined;
+        }
+        else if (arg === "--develop-cycle") {
+            developCycle = true;
+        }
+        else if (arg === "--qa-cycle") {
+            qaCycle = true;
+        }
+        else if (arg === "--debug-cycle") {
+            debugCycle = true;
+        }
+        else {
+            return { ok: false, error: `Unknown mcp argument: ${arg}` };
+        }
+    }
+    if (!worktreePath?.trim() || !workItemId?.trim()) {
+        return { ok: false, error: "mcp requires --worktree and --work-item-id." };
+    }
+    if ([developCycle, qaCycle, debugCycle].filter(Boolean).length > 1) {
+        return { ok: false, error: "mcp accepts only one cycle mode." };
+    }
+    if (developCycle && !isDevelopCompletionPhase(phase)) {
+        return { ok: false, error: "mcp --develop-cycle requires --phase implementation, self-review, or validation." };
+    }
+    if (qaCycle && phase !== "qa") {
+        return { ok: false, error: "mcp --qa-cycle requires --phase qa." };
+    }
+    if (debugCycle && !isDebugCompletionPhase(phase)) {
+        return { ok: false, error: "mcp --debug-cycle requires --phase debug-repro, debug-root-cause, debug-fix, or debug-regression." };
+    }
+    return {
+        ok: true,
+        config: {
+            worktreePath: path.resolve(worktreePath),
+            workItemId,
+            ownerType,
+            ownerId,
+            phase,
+            producedBy,
+            redactionSecrets: parseCompletionRedactionSecrets(process.env[completionRedactionSecretsEnv]),
+            developCycle,
+            qaCycle,
+            debugCycle
+        }
+    };
+}
+export function completionRedactionEnv(secrets) {
+    const filtered = secrets.filter((secret) => secret.length > 0);
+    return filtered.length > 0
+        ? { [completionRedactionSecretsEnv]: JSON.stringify(filtered) }
+        : {};
+}
+async function prepareCursorCompletionToolRuntime(worktreePath, runtime) {
+    const cursorDir = path.join(worktreePath, ".cursor");
+    const configPath = path.join(cursorDir, "mcp.json");
+    const original = await fs.readFile(configPath, "utf8").then((content) => ({ existed: true, content }), () => ({ existed: false, content: "" }));
+    const existing = original.existed ? parseOptionalJsonObject(original.content, configPath) : {};
+    const servers = asMutableRecord(existing.mcpServers);
+    servers[runtime.serverName] = cursorMcpServerConfig(runtime);
+    const next = {
+        ...existing,
+        mcpServers: servers
+    };
+    await fs.mkdir(cursorDir, { recursive: true });
+    await writeFileAtomic(configPath, `${JSON.stringify(next, null, 2)}\n`);
+    return {
+        ...runtime,
+        cursorMcpConfigPath: configPath,
+        cleanup: async () => {
+            if (original.existed) {
+                await writeFileAtomic(configPath, original.content);
+            }
+            else {
+                await fs.rm(configPath, { force: true });
+                await fs.rmdir(cursorDir).catch(() => undefined);
+            }
+        }
+    };
+}
+async function handleJsonRpcLine(session, rawLine) {
+    let message;
+    try {
+        message = JSON.parse(rawLine);
+    }
+    catch (error) {
+        writeJsonRpc({ jsonrpc: "2.0", id: null, error: rpcError(-32700, errorMessage(error)) });
+        return;
+    }
+    const request = asJsonRpcMessage(message);
+    if (!request) {
+        writeJsonRpc({ jsonrpc: "2.0", id: null, error: rpcError(-32600, "Invalid JSON-RPC message.") });
+        return;
+    }
+    if (request.id === undefined) {
+        return;
+    }
+    try {
+        const result = await handleJsonRpcRequest(session, request.method, request.params);
+        writeJsonRpc({ jsonrpc: "2.0", id: request.id, result });
+    }
+    catch (error) {
+        writeJsonRpc({ jsonrpc: "2.0", id: request.id, error: rpcError(-32000, errorMessage(error)) });
+    }
+}
+async function handleJsonRpcRequest(session, method, params) {
+    if (method === "initialize") {
+        const initializeParams = params && typeof params === "object" && !Array.isArray(params)
+            ? params
+            : {};
+        return {
+            protocolVersion: typeof initializeParams.protocolVersion === "string" ? initializeParams.protocolVersion : "2025-06-18",
+            capabilities: {
+                tools: {}
+            },
+            serverInfo: {
+                name: "forge-completion-tools",
+                version: "0.1.0"
+            },
+            instructions: session.instructions
+        };
+    }
+    if (method === "ping") {
+        return {};
+    }
+    if (method === "tools/list") {
+        return {
+            tools: session.toolDefinitions()
+        };
+    }
+    if (method === "tools/call") {
+        const call = asRecord(params, "tools/call params");
+        const name = requiredString(call, "name");
+        const args = call.arguments ?? {};
+        return await session.callTool(name, args);
+    }
+    throw new Error(`Unsupported MCP method: ${method}`);
+}
+function toolDefinition(name, phase, qaGate = null) {
+    return {
+        name,
+        description: toolDescription(phase, qaGate),
+        inputSchema: toolInputSchema(phase, qaGate)
+    };
+}
+function nextPhaseAfter(phase) {
+    if (!isDevelopCompletionPhase(phase)) {
+        return null;
+    }
+    const index = completionPhaseOrder.indexOf(phase);
+    return index >= 0 ? completionPhaseOrder[index + 1] ?? null : null;
+}
+function nextDebugPhaseAfter(phase) {
+    const index = debugCompletionPhaseOrder.indexOf(phase);
+    return index >= 0 ? debugCompletionPhaseOrder[index + 1] ?? null : null;
+}
+function completionToolNextInstruction(completedPhase, status, nextPhase) {
+    if (completedPhase === "qa") {
+        if (status === "blocked") {
+            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.";
+    }
+    if (status !== "pass") {
+        return `Stay in ${completedPhase}, address the recorded blockers, then call ${expectedCompletionToolName(completedPhase)} again.`;
+    }
+    if (isDebugCompletionPhase(completedPhase)) {
+        const debugNext = isDebugCompletionPhase(nextPhase) ? nextPhase : null;
+        return completionToolNextInstructionForDebugGate(completedPhase, status, debugNext);
+    }
+    if (nextPhase === "self_review") {
+        return "Implementation accepted. Begin self-review: inspect the diff, apply safe fixes, and call forge.complete_self_review with review evidence.";
+    }
+    if (nextPhase === "validation") {
+        return "Self-review accepted. Begin validation: run deterministic checks, prove acceptance criteria, and call forge.complete_validation with command evidence.";
+    }
+    return "Validation accepted. Forge has the structured evidence needed to move this work item to QA.";
+}
+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.";
+    }
+    const skipped = status === "skipped";
+    const blocked = status === "blocked";
+    const prefix = blocked
+        ? `${completedGate} recorded a blocker. Continue through ${nextGate} and mark downstream gates skipped if the blocker prevents evidence collection.`
+        : skipped
+            ? `${completedGate} skipped. Continue to ${nextGate}.`
+            : `${completedGate} accepted. Continue to ${nextGate}.`;
+    return `${prefix} ${qaGateInstruction(nextGate)}`;
+}
+function completionToolNextInstructionForDebugGate(completedGate, status, nextGate) {
+    if (status !== "pass") {
+        return `Stay in ${completedGate}, address the recorded blockers, then call ${expectedDebugCompletionToolName(completedGate)} again.`;
+    }
+    if (nextGate === "debug_root_cause") {
+        return "Debug repro accepted. Begin root-cause analysis: connect the observed failure to code evidence and call forge.complete_debug_root_cause.";
+    }
+    if (nextGate === "debug_fix") {
+        return "Debug root cause accepted. Apply the smallest safe fix with regression coverage where practical, then call forge.complete_debug_fix.";
+    }
+    if (nextGate === "debug_regression") {
+        return "Debug fix accepted. Prove the original repro is negative, run targeted regression checks, and call forge.complete_debug_regression.";
+    }
+    return "Debug regression accepted. Forge has the structured evidence needed to move this bug fix to QA.";
+}
+function qaGateInstruction(gate) {
+    switch (gate) {
+        case "qa_regression":
+            return "Run or explicitly skip applicable regression/build/lint/typecheck/e2e checks, then call forge.complete_qa_regression.";
+        case "qa_api":
+            return "Run or explicitly skip applicable API/backend contract checks, then call forge.complete_qa_api.";
+        case "qa_manual_web":
+            return "Run or explicitly skip applicable browser/manual web checks, then call forge.complete_qa_manual_web.";
+        case "qa_bug_repro":
+            return "Reproduce or explicitly skip relevant defects/candidate bugs, then call forge.complete_qa_bug_repro.";
+        case "qa_findings":
+            return "Normalize observations into findings and candidate bugs, then call forge.complete_qa_findings.";
+        case "qa_verdict":
+            return "Assemble the final QA verdict from all prior gate evidence, then call forge.complete_qa_verdict.";
+        case "qa_plan":
+            return "Prepare the QA checklist, then call forge.complete_qa_plan.";
+    }
+}
+function toolDescription(phase, qaGate = null) {
+    if (qaGate) {
+        return qaGate === "qa_verdict"
+            ? "Complete the final Forge QA verdict by writing the canonical QA bundle with pass, needs_rework, or blocked evidence."
+            : `Complete the ${qaGate.replace(/_/g, " ")} QA gate by writing ${qaGateFileNames[qaGate]} before continuing to the next QA gate.`;
+    }
+    if (isDebugCompletionPhase(phase)) {
+        return `Complete the ${phase.replace(/_/g, " ")} Debug gate by writing ${phaseFiles[phase].jsonFileName} with structured bug-fix evidence before continuing.`;
+    }
+    if (phase === "implementation") {
+        return "Complete Forge implementation by writing implementation.completeness.json with scoped changed-file, verification, acceptance-criteria, gap, and next-phase evidence.";
+    }
+    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.";
+    }
+    if (phase === "qa") {
+        return "Complete Forge QA by writing qa.plan.json, qa.evidence.json, qa.findings.json, qa.verdict.json, and qa.report.md with structured pass, needs-rework, or blocked evidence.";
+    }
+    return "Complete Forge validation by writing validation.verdict.json with command, build/test/lint/design, drift, acceptance-criteria, and ready-for-dev-test evidence.";
+}
+function toolInputSchema(phase, qaGate = null) {
+    const baseProperties = {
+        status: {
+            type: "string",
+            enum: ["pass", "needs_rework", "fail", "failed"],
+            description: "Use pass only when the phase evidence satisfies Forge's gate. Use needs_rework/fail/failed with explicit blockers or findings otherwise."
+        },
+        summary: { type: "string", description: "Concise phase summary." },
+        report_markdown: { type: "string", description: "Optional human-readable report. Forge will generate a fallback report if omitted." },
+        blockers: {
+            type: "array",
+            description: "Required for non-pass status unless findings, failures, known_gaps, remaining_risks, or commands provide explicit evidence.",
+            items: evidenceObjectSchema(["reason"], {
+                reason: { type: "string" },
+                owner: { type: "string" },
+                next_step: { type: "string" }
+            })
+        }
+    };
+    if (qaGate && qaGate !== "qa_verdict") {
+        return qaGateToolInputSchema(qaGate);
+    }
+    if (isDebugCompletionPhase(phase)) {
+        return debugToolInputSchema(phase, baseProperties);
+    }
+    if (phase === "implementation") {
+        return objectToolSchema({
+            ...baseProperties,
+            plan: {
+                type: "array",
+                description: "Required for pass. Ordered implementation steps with status.",
+                items: evidenceObjectSchema(["step", "status"], {
+                    step: { type: "string" },
+                    status: { type: "string" },
+                    evidence: { type: "string" }
+                })
+            },
+            changed_files: {
+                type: "array",
+                description: "Required for pass. Must be non-empty unless known_gaps explains why.",
+                items: evidenceObjectSchema(["path", "summary"], {
+                    path: { type: "string" },
+                    summary: { type: "string" }
+                })
+            },
+            tests_added_or_updated: {
+                type: "array",
+                description: "Required for pass. Use an object explaining why no tests were needed for docs/config-only work if empty would be ambiguous.",
+                items: evidenceObjectSchema(["path", "summary"], {
+                    path: { type: "string" },
+                    summary: { type: "string" }
+                })
+            },
+            docs_added_or_updated: {
+                type: "array",
+                description: "Required for pass. Use an object explaining why no docs changed when appropriate.",
+                items: evidenceObjectSchema(["path", "summary"], {
+                    path: { type: "string" },
+                    summary: { type: "string" }
+                })
+            },
+            verification: {
+                type: "array",
+                description: "Implementation verification evidence. Objects should include command, exit_code, status, and summary when command-based.",
+                items: commandEvidenceSchema()
+            },
+            acceptance_criteria: acceptanceCriteriaSchema(),
+            known_gaps: {
+                type: "array",
+                description: "Required for pass, even when empty. If changed_files/tests/docs arrays are empty, explain why here.",
+                items: evidenceObjectSchema(["summary"], {
+                    summary: { type: "string" },
+                    impact: { type: "string" },
+                    follow_up: { type: "string" }
+                })
+            },
+            next_phase_context: {
+                description: "Required for pass. Context the self-review phase should carry forward."
+            }
+        }, ["status", "summary"], "For status pass, include plan, changed_files, tests_added_or_updated, docs_added_or_updated, acceptance_criteria, known_gaps, and next_phase_context. Acceptance criteria entries must use status: satisfied plus evidence.");
+    }
+    if (phase === "self_review") {
+        return objectToolSchema({
+            ...baseProperties,
+            reviewed_diff: { type: "boolean", description: "Required for pass. True after reviewing the implementation diff." },
+            findings: {
+                type: "array",
+                description: "Required for pass, even when empty. Include finding objects for issues discovered during review.",
+                items: evidenceObjectSchema(["severity", "summary", "status"], {
+                    severity: { type: "string" },
+                    summary: { type: "string" },
+                    status: { type: "string" },
+                    file: { type: "string" }
+                })
+            },
+            security_review: reviewSectionSchema(),
+            edge_case_review: reviewSectionSchema(),
+            design_review: {
+                ...reviewSectionSchema(),
+                properties: {
+                    ...reviewSectionProperties(),
+                    screenshots: { type: "array", items: evidenceObjectSchema(["path"], { path: { type: "string" }, summary: { type: "string" } }) }
+                }
+            },
+            deterministic_comparison: {
+                type: "object",
+                description: "Required for pass. Evidence that the reviewed diff matches the intended deterministic change.",
+                additionalProperties: true,
+                properties: {
+                    status: { type: "string" },
+                    command_or_tool: { type: "string" },
+                    notes: { type: "string" }
+                }
+            },
+            fixes_applied: {
+                type: "array",
+                description: "Required for pass, even when empty.",
+                items: evidenceObjectSchema(["summary"], { summary: { type: "string" }, path: { type: "string" } })
+            },
+            remaining_risks: {
+                type: "array",
+                description: "Required for pass, even when empty.",
+                items: evidenceObjectSchema(["summary"], { summary: { type: "string" }, mitigation: { type: "string" } })
+            }
+        }, ["status", "summary"], "For status pass, include reviewed_diff, findings, security_review, edge_case_review, design_review, deterministic_comparison, fixes_applied, and remaining_risks.");
+    }
+    if (phase === "qa") {
+        return objectToolSchema({
+            ...baseProperties,
+            status: {
+                type: "string",
+                enum: ["pass", "needs_rework", "blocked"],
+                description: "Use pass only when QA evidence satisfies acceptance criteria, needs_rework for actionable in-scope defects, or blocked for an inconclusive QA blocker."
+            },
+            checklist: {
+                type: "array",
+                description: "QA plan/checklist. Forge writes this to qa.plan.json; a default checklist is generated if omitted.",
+                items: { type: "string" }
+            },
+            tested_acceptance_criteria: {
+                type: "array",
+                description: "Required and non-empty for pass/needs_rework. Criteria actually tested by QA.",
+                items: { type: "string" }
+            },
+            commands: {
+                type: "array",
+                description: "Command evidence written to qa.evidence.json.",
+                items: commandEvidenceSchema()
+            },
+            browser_checks: {
+                type: "array",
+                description: "Browser/manual UI checks with URL or route, action, observed result, screenshot/trace references, console/network notes, and status.",
+                items: evidenceObjectSchema(["summary", "status"], {
+                    summary: { type: "string" },
+                    url: { type: "string" },
+                    route: { type: "string" },
+                    status: { type: "string" },
+                    screenshot: { type: "string" },
+                    trace: { type: "string" }
+                })
+            },
+            sidecars: {
+                type: "array",
+                description: "Optional QA sidecar files already written under .forge/work-items/<id>/artifacts/qa/ with path/content_hash/bytes metadata.",
+                items: evidenceObjectSchema(["path", "content_hash", "bytes"], {
+                    path: { type: "string" },
+                    content_hash: { type: "string" },
+                    bytes: { type: "number" }
+                })
+            },
+            notes: { type: "string", description: "Additional QA evidence notes." },
+            evidence: {
+                type: "object",
+                description: "Optional wrapper containing commands, browser_checks, and notes when a client prefers nested evidence."
+            },
+            findings: {
+                type: "array",
+                description: "QA findings. needs_rework requires at least one actionable in_scope finding.",
+                items: evidenceObjectSchema(["id", "severity", "scope", "title"], {
+                    id: { type: "string" },
+                    severity: { type: "string", enum: ["critical", "major", "minor"] },
+                    scope: { type: "string", enum: ["in_scope", "out_of_scope", "unclear"] },
+                    title: { type: "string" },
+                    acceptance_criteria: { type: "array", items: { type: "string" } },
+                    repro_steps: { type: "array", items: { type: "string" } },
+                    expected: { type: "string" },
+                    actual: { type: "string" },
+                    evidence: { type: "object" },
+                    likely_area: { type: "array", items: { type: "string" } },
+                    required_fix: { type: "string" },
+                    required_regression: { type: "string" }
+                })
+            },
+            candidate_bugs: {
+                type: "array",
+                description: "Out-of-scope/follow-up bug candidates. They do not block the current item unless attached as in-scope findings.",
+                items: evidenceObjectSchema(["id", "title", "suggested_action"], {
+                    id: { type: "string" },
+                    title: { type: "string" },
+                    severity: { type: "string" },
+                    scope_reason: { type: "string" },
+                    repro_steps: { type: "array", items: { type: "string" } },
+                    evidence: { type: "object" },
+                    suggested_action: { type: "string", enum: ["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"] }
+                })
+            },
+            blocker_reason: {
+                type: "string",
+                enum: [...qaBlockerReasons],
+                description: "Required when status is blocked."
+            }
+        }, ["status", "summary"], "For pass, include tested_acceptance_criteria plus concrete command/browser/note evidence. For needs_rework, include at least one actionable in_scope finding. For blocked, include blocker_reason.");
+    }
+    return objectToolSchema({
+        ...baseProperties,
+        commands: {
+            type: "array",
+            description: "Required for pass. Include at least one deterministic validation command with exit_code: 0 and status: pass.",
+            items: commandEvidenceSchema()
+        },
+        acceptance_criteria: acceptanceCriteriaSchema(),
+        build_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
+        test_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
+        lint_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
+        design_status: { type: "string", description: "Required for pass. pass/fail/needs_rework/not_applicable." },
+        drift_checks: {
+            type: "array",
+            description: "Required for pass. Deterministic checks for unintended drift.",
+            items: evidenceObjectSchema(["command_or_tool", "status", "summary"], {
+                command_or_tool: { type: "string" },
+                status: { type: "string" },
+                summary: { type: "string" }
+            })
+        },
+        ready_for_dev_test: { type: "boolean", description: "Required for pass and must be true." }
+    }, ["status", "summary"], "For status pass, commands must include at least one passing deterministic command, acceptance criteria entries must use status: satisfied plus evidence, and ready_for_dev_test must be true.");
+}
+function debugToolInputSchema(phase, baseProperties) {
+    if (phase === "debug_repro") {
+        return objectToolSchema({
+            ...baseProperties,
+            repro_steps: {
+                type: "array",
+                description: "Required for pass. Minimal reproduction or characterization steps.",
+                items: { type: "string" }
+            },
+            observed: { type: "string", description: "Observed failure behavior." },
+            expected: { type: "string", description: "Expected behavior." },
+            evidence: {
+                type: "array",
+                description: "Required for pass. Concrete logs, commands, screenshots, file refs, or characterization notes.",
+                items: { type: "object", additionalProperties: true }
+            }
+        }, ["status", "summary"], "For status pass, include repro_steps, observed, expected, and evidence.");
+    }
+    if (phase === "debug_root_cause") {
+        return objectToolSchema({
+            ...baseProperties,
+            root_cause: { type: "string", description: "Likely root cause tied to code or config evidence." },
+            evidence: {
+                type: "array",
+                description: "Required for pass. Concrete code/log/test evidence supporting the root cause.",
+                items: { type: "object", additionalProperties: true }
+            },
+            eliminated_alternatives: {
+                type: "array",
+                description: "Required for pass. Plausible alternatives checked or ruled out.",
+                items: { type: "object", additionalProperties: true }
+            },
+            risk_area: { type: "string", description: "Subsystem or behavior most at risk from the fix." }
+        }, ["status", "summary"], "For status pass, include root_cause, evidence, eliminated_alternatives, and risk_area.");
+    }
+    if (phase === "debug_fix") {
+        return objectToolSchema({
+            ...baseProperties,
+            changed_files: {
+                type: "array",
+                description: "Required for pass. Files changed by the bug fix.",
+                items: evidenceObjectSchema(["path", "summary"], { path: { type: "string" }, summary: { type: "string" } })
+            },
+            tests_added_or_updated: {
+                type: "array",
+                description: "Required for pass. Regression tests or checks added/updated, or justify omission in remaining_risks.",
+                items: evidenceObjectSchema(["path", "summary"], { path: { type: "string" }, summary: { type: "string" } })
+            },
+            remaining_risks: {
+                type: "array",
+                description: "Required for pass, even when empty. Include why no regression coverage changed when tests_added_or_updated is empty.",
+                items: evidenceObjectSchema(["summary"], { summary: { type: "string" }, mitigation: { type: "string" } })
+            },
+            resolved_findings: {
+                type: "array",
+                description: "Required for QA rework. Entries should include qa_id, status, summary, evidence, changed_files, tests_added_or_updated, and regression_evidence.",
+                items: { type: "object", additionalProperties: true }
+            }
+        }, ["status", "summary"], "For status pass, include changed_files, tests_added_or_updated, and remaining_risks.");
+    }
+    return objectToolSchema({
+        ...baseProperties,
+        commands: {
+            type: "array",
+            description: "Required for pass. Targeted regression/repro-negative commands with exit_code: 0 and status: pass.",
+            items: commandEvidenceSchema()
+        },
+        required_regressions: {
+            type: "array",
+            description: "Required for pass. Repro-negative and regression coverage checklist.",
+            items: { type: "string" }
+        },
+        build_status: { type: "string", description: "Required for pass. pass or not_applicable." },
+        test_status: { type: "string", description: "Required for pass. pass or not_applicable." },
+        repro_negative: { type: "boolean", description: "Required for pass and must be true after the original repro no longer fails." },
+        qa_ready: { type: "boolean", description: "Required for pass and must be true." }
+    }, ["status", "summary"], "For status pass, commands must include at least one passing deterministic debug regression check, repro_negative must be true, and qa_ready must be true.");
+}
+function qaGateToolInputSchema(gate) {
+    const baseProperties = {
+        status: {
+            type: "string",
+            enum: ["pass", "skipped", "blocked"],
+            description: "Use pass when this QA gate produced evidence, skipped when not applicable, or blocked when a prerequisite prevents this gate."
+        },
+        summary: { type: "string", description: "Concise QA gate summary." },
+        reason: { type: "string", description: "Required for skipped or blocked gates." },
+        blocker_reason: {
+            type: "string",
+            enum: [...qaBlockerReasons],
+            description: "Required when status is blocked."
+        }
+    };
+    if (gate === "qa_plan") {
+        return objectToolSchema({
+            ...baseProperties,
+            checklist: {
+                type: "array",
+                description: "Required for pass. QA checklist entries planned for this work item.",
+                items: { type: "string" }
+            },
+            acceptance_criteria: {
+                type: "array",
+                description: "Acceptance criteria selected for QA.",
+                items: { type: "string" }
+            }
+        }, ["status", "summary"], "Record the QA plan gate. Pass requires a non-empty checklist.");
+    }
+    if (gate === "qa_findings") {
+        return objectToolSchema({
+            ...baseProperties,
+            findings: {
+                type: "array",
+                description: "Normalized in-scope and out-of-scope QA findings.",
+                items: { type: "object", additionalProperties: true }
+            },
+            candidate_bugs: {
+                type: "array",
+                description: "Out-of-scope or follow-up candidates.",
+                items: { type: "object", additionalProperties: true }
+            }
+        }, ["status", "summary"], "Record normalized QA findings. Pass or skipped requires findings and candidate_bugs arrays, even when empty.");
+    }
+    return objectToolSchema({
+        ...baseProperties,
+        commands: {
+            type: "array",
+            description: "Command evidence for this gate when applicable.",
+            items: commandEvidenceSchema()
+        },
+        browser_checks: {
+            type: "array",
+            description: "Browser/manual evidence for this gate when applicable.",
+            items: { type: "object", additionalProperties: true }
+        },
+        notes: { type: "string", description: "Evidence notes for this gate." }
+    }, ["status", "summary"], "Record this QA evidence gate. Use skipped with a reason when the gate is not applicable.");
+}
+function objectToolSchema(properties, required, description) {
+    return {
+        type: "object",
+        additionalProperties: true,
+        description,
+        properties,
+        required: [...required]
+    };
+}
+function evidenceObjectSchema(required, properties) {
+    return {
+        type: "object",
+        additionalProperties: true,
+        properties,
+        required: [...required]
+    };
+}
+function commandEvidenceSchema() {
+    return evidenceObjectSchema(["command", "exit_code", "status", "summary"], {
+        command: { type: "string" },
+        exit_code: { type: "number" },
+        status: { type: "string" },
+        summary: { type: "string" }
+    });
+}
+function acceptanceCriteriaSchema() {
+    return {
+        type: "array",
+        description: "Required for pass. Every entry must be an object with status: satisfied and non-empty evidence.",
+        items: evidenceObjectSchema(["criterion", "evidence", "status"], {
+            criterion: { type: "string" },
+            evidence: { type: "string" },
+            status: { type: "string", enum: ["satisfied"] }
+        })
+    };
+}
+function reviewSectionSchema() {
+    return {
+        type: "object",
+        description: "Required for pass. Use status pass/fail/needs_rework/not_applicable plus notes.",
+        additionalProperties: true,
+        properties: reviewSectionProperties()
+    };
+}
+function reviewSectionProperties() {
+    return {
+        status: { type: "string" },
+        notes: { type: "string" }
+    };
+}
+function normalizeCompletionStatus(value, phase) {
+    const normalized = value.trim().toLowerCase().replace(/-/g, "_");
+    if (phase === "qa") {
+        const canonical = normalized === "needsrework" ? "needs_rework" : normalized;
+        if (canonical !== "pass" && canonical !== "needs_rework" && canonical !== "blocked") {
+            throw new Error("QA status must be pass, needs_rework, or blocked.");
+        }
+        return canonical;
+    }
+    const canonical = normalized === "blocked" || normalized === "needsrework"
+        ? "needs_rework"
+        : normalized === "failed"
+            ? "fail"
+            : normalized;
+    if (canonical !== "pass" && canonical !== "fail" && canonical !== "needs_rework") {
+        throw new Error("status must be pass, fail, or needs_rework.");
+    }
+    return canonical;
+}
+function normalizeQaGateStatus(value) {
+    const normalized = value.trim().toLowerCase().replace(/-/g, "_");
+    if (normalized !== "pass" && normalized !== "skipped" && normalized !== "blocked") {
+        throw new Error("QA gate status must be pass, skipped, or blocked.");
+    }
+    return normalized;
+}
+function validatePayloadShape(phase, payload) {
+    const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
+    if (!status) {
+        throw new Error("status is required.");
+    }
+    requireField(payload, "summary");
+    if (phase === "qa") {
+        validateQaPayloadShape(payload, status);
+        return;
+    }
+    const pass = status === "pass";
+    if (!pass) {
+        requireNonPassEvidence(payload);
+        return;
+    }
+    if (isDebugCompletionPhase(phase)) {
+        validateDebugPayloadShape(phase, payload);
+        return;
+    }
+    if (phase === "implementation") {
+        requireArray(payload, "plan");
+        requireArray(payload, "changed_files");
+        requireArray(payload, "tests_added_or_updated");
+        requireArray(payload, "docs_added_or_updated");
+        requireArray(payload, "acceptance_criteria");
+        requireArray(payload, "known_gaps");
+        requireField(payload, "next_phase_context");
+        requireImplementationEvidence(payload);
+        requireSatisfiedAcceptanceCriteria(payload);
+        return;
+    }
+    if (phase === "self_review") {
+        requireBoolean(payload, "reviewed_diff");
+        requireArray(payload, "findings");
+        requireObject(payload, "security_review");
+        requireObject(payload, "edge_case_review");
+        requireObject(payload, "design_review");
+        requireObject(payload, "deterministic_comparison");
+        requireArray(payload, "fixes_applied");
+        requireArray(payload, "remaining_risks");
+        return;
+    }
+    requireArray(payload, "commands");
+    requireArray(payload, "acceptance_criteria");
+    requireField(payload, "build_status");
+    requireField(payload, "test_status");
+    requireField(payload, "lint_status");
+    requireField(payload, "design_status");
+    requireArray(payload, "drift_checks");
+    requireBoolean(payload, "ready_for_dev_test");
+    if (payload.ready_for_dev_test !== true) {
+        throw new Error("validation pass requires ready_for_dev_test: true.");
+    }
+    requirePassingCommands(payload);
+    requireSatisfiedAcceptanceCriteria(payload);
+}
+function validateDebugPayloadShape(phase, payload) {
+    if (phase === "debug_repro") {
+        requireArray(payload, "repro_steps");
+        requireField(payload, "observed");
+        requireField(payload, "expected");
+        requireArray(payload, "evidence");
+        requireNonEmptyArray(payload, "repro_steps");
+        requireNonEmptyArray(payload, "evidence");
+        return;
+    }
+    if (phase === "debug_root_cause") {
+        requireField(payload, "root_cause");
+        requireArray(payload, "evidence");
+        requireArray(payload, "eliminated_alternatives");
+        requireField(payload, "risk_area");
+        requireNonEmptyArray(payload, "evidence");
+        return;
+    }
+    if (phase === "debug_fix") {
+        requireArray(payload, "changed_files");
+        requireArray(payload, "tests_added_or_updated");
+        requireArray(payload, "remaining_risks");
+        requireNonEmptyArray(payload, "changed_files");
+        if (arrayLength(payload, "tests_added_or_updated") === 0 && arrayLength(payload, "remaining_risks") === 0) {
+            throw new Error("tests_added_or_updated is empty; remaining_risks must explain why no regression coverage changed.");
+        }
+        return;
+    }
+    requireArray(payload, "commands");
+    requireArray(payload, "required_regressions");
+    requireField(payload, "build_status");
+    requireField(payload, "test_status");
+    requireBoolean(payload, "repro_negative");
+    requireBoolean(payload, "qa_ready");
+    if (payload.repro_negative !== true) {
+        throw new Error("debug_regression pass requires repro_negative: true.");
+    }
+    if (payload.qa_ready !== true) {
+        throw new Error("debug_regression pass requires qa_ready: true.");
+    }
+    requireAllowedStatus(payload, "build_status", ["pass", "not_applicable"]);
+    requireAllowedStatus(payload, "test_status", ["pass", "not_applicable"]);
+    requireNonEmptyArray(payload, "required_regressions");
+    requirePassingCommands(payload);
+}
+function validateQaGatePayloadShape(gate, payload, status) {
+    requireField(payload, "summary");
+    if (status === "skipped") {
+        requireField(payload, "reason");
+    }
+    if (status === "blocked") {
+        const reason = normalizedString(optionalString(payload, "blocker_reason"));
+        if (!qaBlockerReasons.has(reason)) {
+            throw new Error("QA gate blocked requires blocker_reason to be one of missing_app_launch_target, inconclusive, environment_failure, missing_validation_evidence, missing_worktree, or runner_failure.");
+        }
+    }
+    if (gate === "qa_plan" && status === "pass") {
+        const checklist = qaStringArray(payload, "checklist");
+        if (checklist.length === 0) {
+            throw new Error("complete_qa_plan pass requires checklist with at least one entry.");
+        }
+    }
+    if (gate === "qa_findings" && status !== "blocked") {
+        qaObjectArray(payload, "findings");
+        qaObjectArray(payload, "candidate_bugs");
+    }
+    if ((gate === "qa_regression" || gate === "qa_api") && status === "pass") {
+        const commands = qaArray(payload, "commands");
+        if (commands.length === 0) {
+            throw new Error(`${qaGateToolNames[gate]} pass requires commands with at least one entry.`);
+        }
+    }
+    if (gate === "qa_manual_web" && status === "pass") {
+        const browserChecks = qaArray(payload, "browser_checks");
+        const notes = optionalString(payload, "notes");
+        if (browserChecks.length === 0 && !notes) {
+            throw new Error(`${qaGateToolNames[gate]} pass requires browser_checks or notes.`);
+        }
+    }
+}
+function validateQaPayloadShape(payload, status) {
+    const evidenceSource = qaEvidenceSource(payload);
+    const commands = qaArray(payload, "commands", evidenceSource);
+    const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
+    const sidecars = qaArray(payload, "sidecars", evidenceSource);
+    const notes = optionalString(payload, "notes") ?? optionalString(evidenceSource, "notes") ?? "";
+    const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
+    const findings = qaObjectArray(payload, "findings");
+    const candidateBugs = qaObjectArray(payload, "candidate_bugs");
+    const explicitFindingIds = qaStringArray(payload, "finding_ids");
+    const explicitCandidateBugIds = qaStringArray(payload, "candidate_bug_ids");
+    if (payload.schema_version !== undefined && payload.schema_version !== 1) {
+        throw new Error("QA schema_version must be numeric 1 when provided.");
+    }
+    if (status === "pass" || status === "needs_rework") {
+        if (testedAcceptanceCriteria.length === 0) {
+            throw new Error("QA pass/needs_rework requires tested_acceptance_criteria with at least one criterion.");
+        }
+        if (commands.length === 0 && browserChecks.length === 0 && notes.length === 0) {
+            throw new Error("QA pass/needs_rework requires at least one command, browser check, or evidence note.");
+        }
+    }
+    for (const [index, command] of commands.entries()) {
+        requireEvidenceRecord(command, `commands[${index}]`);
+        const record = command;
+        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
+        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            throw new Error(`commands[${index}].exit_code is required.`);
+        }
+        if (status === "pass" && record.exit_code !== 0) {
+            throw new Error(`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.`);
+        }
+    }
+    for (const [index, browserCheck] of browserChecks.entries()) {
+        requireEvidenceRecord(browserCheck, `browser_checks[${index}]`);
+        const record = browserCheck;
+        requireNonEmptyStringRecord(record, "summary", `browser_checks[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `browser_checks[${index}].`);
+        const checkStatus = optionalString(record, "status");
+        if (status === "pass" && checkStatus && normalizedString(checkStatus) !== "pass") {
+            throw new Error(`browser_checks[${index}].status must be pass when QA status is pass.`);
+        }
+        if (!optionalString(record, "url") && !optionalString(record, "route")) {
+            throw new Error(`browser_checks[${index}] must include url or route.`);
+        }
+    }
+    for (const [index, sidecar] of sidecars.entries()) {
+        requireEvidenceRecord(sidecar, `sidecars[${index}]`);
+        const record = sidecar;
+        requireNonEmptyStringRecord(record, "path", `sidecars[${index}].`);
+        requireNonEmptyStringRecord(record, "content_hash", `sidecars[${index}].`);
+        if (typeof record.bytes !== "number" || !Number.isFinite(record.bytes) || record.bytes <= 0) {
+            throw new Error(`sidecars[${index}].bytes must be greater than 0.`);
+        }
+    }
+    for (const [index, finding] of findings.entries()) {
+        requireNonEmptyStringRecord(finding, "id", `findings[${index}].`);
+        requireNonEmptyStringRecord(finding, "title", `findings[${index}].`);
+        requireKnownStringRecord(finding, "severity", qaFindingSeverities, `findings[${index}].`);
+        requireKnownStringRecord(finding, "scope", qaFindingScopes, `findings[${index}].`);
+        if (normalizedString(finding.scope) === "in_scope") {
+            validateActionableQaFinding(finding, index);
+        }
+    }
+    for (const [index, candidateBug] of candidateBugs.entries()) {
+        requireNonEmptyStringRecord(candidateBug, "id", `candidate_bugs[${index}].`);
+        requireNonEmptyStringRecord(candidateBug, "title", `candidate_bugs[${index}].`);
+        requireKnownStringRecord(candidateBug, "suggested_action", qaCandidateBugActions, `candidate_bugs[${index}].`);
+    }
+    const inScopeFindingIds = findings
+        .filter((finding) => normalizedString(finding.scope) === "in_scope")
+        .map((finding) => optionalString(finding, "id"))
+        .filter((id) => Boolean(id));
+    for (const findingId of explicitFindingIds) {
+        if (!inScopeFindingIds.includes(findingId)) {
+            throw new Error(`QA finding_ids contains '${findingId}', but findings has no matching in-scope finding.`);
+        }
+    }
+    const candidateBugIds = candidateBugs
+        .map((candidateBug) => optionalString(candidateBug, "id"))
+        .filter((id) => Boolean(id));
+    for (const candidateBugId of explicitCandidateBugIds) {
+        if (!candidateBugIds.includes(candidateBugId)) {
+            throw new Error(`QA candidate_bug_ids contains '${candidateBugId}', but candidate_bugs has no matching candidate bug.`);
+        }
+    }
+    if (status === "pass") {
+        if (explicitFindingIds.length > 0 || inScopeFindingIds.length > 0) {
+            throw new Error("QA pass must not include in-scope finding_ids or in-scope findings.");
+        }
+        if (optionalString(payload, "blocker_reason")) {
+            throw new Error("QA pass must not include blocker_reason.");
+        }
+    }
+    if (status === "needs_rework") {
+        if (inScopeFindingIds.length === 0) {
+            throw new Error("QA needs_rework requires at least one actionable in-scope finding.");
+        }
+        if (optionalString(payload, "blocker_reason")) {
+            throw new Error("QA needs_rework must not include blocker_reason.");
+        }
+    }
+    if (status === "blocked") {
+        const reason = normalizedString(optionalString(payload, "blocker_reason"));
+        if (!qaBlockerReasons.has(reason)) {
+            throw new Error("QA blocked requires blocker_reason to be one of missing_app_launch_target, inconclusive, environment_failure, missing_validation_evidence, missing_worktree, or runner_failure.");
+        }
+    }
+}
+function validateActionableQaFinding(finding, index) {
+    const prefix = `findings[${index}].`;
+    requireNonEmptyStringArrayRecord(finding, "acceptance_criteria", prefix);
+    requireNonEmptyStringArrayRecord(finding, "repro_steps", prefix);
+    requireNonEmptyStringRecord(finding, "expected", prefix);
+    requireNonEmptyStringRecord(finding, "actual", prefix);
+    requireSubstantiveEvidenceRecord(finding, prefix);
+    requireNonEmptyStringArrayRecord(finding, "likely_area", prefix);
+    requireNonEmptyStringRecord(finding, "required_fix", prefix);
+    requireNonEmptyStringRecord(finding, "required_regression", prefix);
+}
+function validateOptionalWorkItemId(payload, expectedWorkItemId) {
+    const actual = optionalString(payload, "work_item_id") ?? optionalString(payload, "workItemId");
+    if (actual && actual !== expectedWorkItemId) {
+        throw new Error(`completion payload work item ${actual} does not match dispatch work item ${expectedWorkItemId}.`);
+    }
+}
+function normalizeArtifactPayload(payload, defaults) {
+    const normalized = stripUndefined({ ...payload });
+    delete normalized.report_markdown;
+    delete normalized.content_hash;
+    delete normalized.contentHash;
+    normalized.schema_version = numberOrDefault(normalized.schema_version, 1);
+    normalized.phase = defaults.phase;
+    normalized.work_item_id = defaults.workItemId;
+    const ownerFields = artifactOwnerFields(defaults);
+    Object.assign(normalized, ownerFields);
+    normalized.status = defaults.status;
+    normalized.produced_by = defaults.producedBy;
+    return normalized;
+}
+function normalizeQaGateArtifactPayload(payload, defaults) {
+    const normalized = stripUndefined({ ...payload });
+    delete normalized.report_markdown;
+    delete normalized.content_hash;
+    delete normalized.contentHash;
+    normalized.schema_version = numberOrDefault(normalized.schema_version, 1);
+    normalized.phase = "qa";
+    normalized.gate = defaults.gate;
+    normalized.work_item_id = defaults.workItemId;
+    const ownerFields = artifactOwnerFields(defaults);
+    Object.assign(normalized, ownerFields);
+    normalized.status = defaults.status;
+    normalized.produced_by = defaults.producedBy;
+    if (defaults.gate === "qa_plan") {
+        const checklist = qaStringArray(normalized, "checklist");
+        normalized.checklist = checklist.length > 0 ? checklist : defaultQaChecklist(defaults.status);
+        normalized.acceptance_criteria = qaStringArray(normalized, "acceptance_criteria");
+    }
+    if (defaults.gate === "qa_findings") {
+        normalized.findings = qaObjectArray(normalized, "findings");
+        normalized.candidate_bugs = qaObjectArray(normalized, "candidate_bugs");
+    }
+    return normalized;
+}
+function reportMarkdown(payload, phase, status, producedBy, contentHash) {
+    const explicit = optionalString(payload, "report_markdown");
+    if (explicit) {
+        return explicit.endsWith("\n") ? explicit : `${explicit}\n`;
+    }
+    const summary = optionalString(payload, "summary") ?? "No summary provided.";
+    return `# Forge ${phase.replace(/_/g, " ")} completion
+
+Status: ${status}
+Produced by: ${producedBy}
+Content hash: ${contentHash}
+
+## Summary
+
+${summary}
+`;
+}
+function parseStrictCompletionPhase(value) {
+    const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
+    const debugPhase = normalizeDebugCompletionPhase(normalized);
+    if (debugPhase) {
+        return debugPhase;
+    }
+    if (normalized === "implementation" || normalized === "implement" || normalized === "develop") {
+        return "implementation";
+    }
+    if (normalized === "self_review" || normalized === "selfreview" || normalized === "review") {
+        return "self_review";
+    }
+    if (normalized === "validate" || normalized === "validation") {
+        return "validation";
+    }
+    if (normalized === "qa" || normalized === "quality_assurance" || normalized === "qualityassurance") {
+        return "qa";
+    }
+    return null;
+}
+function normalizeDebugCompletionPhase(value) {
+    const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
+    switch (normalized) {
+        case "debug_repro":
+        case "debugrepro":
+        case "repro":
+        case "reproduce":
+            return "debug_repro";
+        case "debug_root_cause":
+        case "debugrootcause":
+        case "root_cause":
+        case "rootcause":
+            return "debug_root_cause";
+        case "debug_fix":
+        case "debugfix":
+        case "fix":
+            return "debug_fix";
+        case "debug_regression":
+        case "debugregression":
+        case "regression":
+            return "debug_regression";
+        default:
+            return null;
+    }
+}
+function isDevelopCompletionPhase(phase) {
+    return phase === "implementation" || phase === "self_review" || phase === "validation";
+}
+function isDebugCompletionPhase(phase) {
+    return debugCompletionPhaseOrder.includes(phase);
+}
+function asDebugCompletionPhase(phase) {
+    if (isDebugCompletionPhase(phase)) {
+        return phase;
+    }
+    throw new Error(`Expected Debug completion phase, got ${phase}.`);
+}
+function parseCompletionRedactionSecrets(raw) {
+    if (!raw?.trim()) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed.filter((value) => typeof value === "string" && value.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function phaseFromToolName(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    if (normalized === "forge.complete_implementation" || normalized === "complete_implementation") {
+        return "implementation";
+    }
+    if (normalized === "forge.complete_self_review" || normalized === "complete_self_review") {
+        return "self_review";
+    }
+    if (normalized === "forge.complete_validation" || normalized === "complete_validation") {
+        return "validation";
+    }
+    if (normalized === "forge.complete_qa" || normalized === "complete_qa") {
+        return "qa";
+    }
+    const debugGate = debugGateFromToolName(toolName);
+    if (debugGate) {
+        return debugGate;
+    }
+    if (qaGateFromToolName(toolName)) {
+        return "qa";
+    }
+    throw new Error(`Unknown Forge completion tool: ${toolName}`);
+}
+function debugGateFromToolName(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    for (const gate of debugCompletionPhaseOrder) {
+        const base = debugGateToolNames[gate];
+        if (normalized === `forge.${base}` || normalized === base) {
+            return gate;
+        }
+    }
+    return null;
+}
+function qaGateFromToolName(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    for (const gate of qaCompletionGateOrder) {
+        const base = qaGateToolNames[gate];
+        if (normalized === `forge.${base}` || normalized === base) {
+            return gate;
+        }
+    }
+    return null;
+}
+function requireField(payload, key) {
+    if (payload[key] === undefined || payload[key] === null || (typeof payload[key] === "string" && payload[key].trim().length === 0)) {
+        throw new Error(`${key} is required.`);
+    }
+}
+function requireNonPassEvidence(payload) {
+    const evidenceKeys = ["blockers", "known_gaps", "findings", "remaining_risks", "commands", "failures"];
+    const hasEvidence = evidenceKeys.some((key) => {
+        const value = payload[key];
+        if (typeof value === "string") {
+            return value.trim().length > 0;
+        }
+        if (Array.isArray(value)) {
+            return value.length > 0;
+        }
+        return Boolean(value && typeof value === "object");
+    });
+    if (!hasEvidence) {
+        throw new Error("non-pass completion requires explicit blockers, findings, failures, or known gaps.");
+    }
+}
+function requireImplementationEvidence(payload) {
+    const knownGaps = payload.known_gaps;
+    const hasKnownGap = Array.isArray(knownGaps) && knownGaps.length > 0;
+    for (const key of ["changed_files", "tests_added_or_updated", "docs_added_or_updated"]) {
+        const value = payload[key];
+        if (Array.isArray(value) && value.length === 0 && !hasKnownGap) {
+            throw new Error(`${key} is empty; known_gaps must explain why.`);
+        }
+    }
+}
+function requirePassingCommands(payload) {
+    const commands = payload.commands;
+    if (!Array.isArray(commands)) {
+        return;
+    }
+    if (commands.length === 0) {
+        throw new Error("commands must include at least one deterministic validation command.");
+    }
+    for (const [index, command] of commands.entries()) {
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            throw new Error(`commands[${index}] must be an object.`);
+        }
+        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.`);
+        }
+        if (typeof record.summary !== "string" || record.summary.trim().length === 0) {
+            throw new Error(`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.`);
+        }
+        if (record.exit_code !== 0) {
+            throw new Error(`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.`);
+        }
+    }
+}
+function requireArray(payload, key) {
+    if (!Array.isArray(payload[key])) {
+        throw new Error(`${key} must be an array.`);
+    }
+}
+function requireNonEmptyArray(payload, key) {
+    requireArray(payload, key);
+    if (arrayLength(payload, key) === 0) {
+        throw new Error(`${key} must include at least one value.`);
+    }
+}
+function arrayLength(payload, key) {
+    const value = payload[key];
+    return Array.isArray(value) ? value.length : 0;
+}
+function requireAllowedStatus(payload, key, allowed) {
+    const value = normalizedString(optionalString(payload, key));
+    if (!allowed.includes(value)) {
+        throw new Error(`${key} must be one of ${allowed.join(", ")}.`);
+    }
+}
+function requireObject(payload, key) {
+    const value = payload[key];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${key} must be an object.`);
+    }
+}
+function requireBoolean(payload, key) {
+    if (typeof payload[key] !== "boolean") {
+        throw new Error(`${key} must be a boolean.`);
+    }
+}
+function requireSatisfiedAcceptanceCriteria(payload) {
+    const criteria = payload.acceptance_criteria;
+    if (!Array.isArray(criteria)) {
+        return;
+    }
+    for (const [index, criterion] of criteria.entries()) {
+        if (!criterion || typeof criterion !== "object" || Array.isArray(criterion)) {
+            throw new Error(`acceptance_criteria[${index}] must be an object.`);
+        }
+        const record = criterion;
+        const status = optionalString(record, "status")?.toLowerCase();
+        const evidence = optionalString(record, "evidence");
+        if (status !== "satisfied" || !evidence) {
+            throw new Error(`acceptance_criteria[${index}] must be satisfied with evidence for status pass.`);
+        }
+    }
+}
+function qaEvidenceSource(payload) {
+    const evidence = payload.evidence;
+    return evidence && typeof evidence === "object" && !Array.isArray(evidence)
+        ? evidence
+        : {};
+}
+function qaArray(payload, key, fallback = {}) {
+    const value = payload[key] ?? fallback[key];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${key} must be an array.`);
+    }
+    return value;
+}
+function qaObjectArray(payload, key) {
+    return qaArray(payload, key).map((entry, index) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new Error(`${key}[${index}] must be an object.`);
+        }
+        return entry;
+    });
+}
+function qaStringArray(payload, key) {
+    const value = payload[key];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${key} must be an array.`);
+    }
+    return value.map((entry, index) => {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`${key}[${index}] must be a non-empty string.`);
+        }
+        return entry;
+    });
+}
+function requireEvidenceRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+}
+function requireNonEmptyStringRecord(source, key, prefix = "") {
+    if (!optionalString(source, key)) {
+        throw new Error(`${prefix}${key} is required.`);
+    }
+}
+function requireKnownStringRecord(source, key, allowed, prefix = "") {
+    const value = normalizedString(optionalString(source, key));
+    if (!allowed.has(value)) {
+        throw new Error(`${prefix}${key} must be one of ${[...allowed].sort().join(", ")}.`);
+    }
+}
+function requireNonEmptyStringArrayRecord(source, key, prefix = "") {
+    const value = source[key];
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${prefix}${key} must include at least one value.`);
+    }
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`${prefix}${key}[${index}] must be a non-empty string.`);
+        }
+    }
+}
+function requireSubstantiveEvidenceRecord(source, prefix = "") {
+    const evidence = source.evidence;
+    if (!evidence || typeof evidence !== "object" || Array.isArray(evidence)) {
+        throw new Error(`${prefix}evidence must be an object.`);
+    }
+    if (!Object.values(evidence).some(hasSubstantiveJsonValue)) {
+        throw new Error(`${prefix}evidence must include at least one concrete evidence reference or summary.`);
+    }
+}
+function hasSubstantiveJsonValue(value) {
+    if (typeof value === "string") {
+        return value.trim().length > 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    if (value && typeof value === "object") {
+        return Object.keys(value).length > 0;
+    }
+    return false;
+}
+function normalizedString(value) {
+    return typeof value === "string" ? value.trim().toLowerCase().replace(/-/g, "_") : "";
+}
+function normalizedOwnerType(value) {
+    const normalized = normalizedString(value);
+    return normalized === "work_item" || normalized === "story" ? normalized : undefined;
+}
+function artifactOwnerFields(config) {
+    const ownerType = normalizedOwnerType(config.ownerType);
+    const ownerId = config.ownerId?.trim();
+    if (!ownerType && !ownerId) {
+        return {};
+    }
+    return {
+        owner_type: ownerType ?? "work_item",
+        owner_id: ownerId || config.workItemId
+    };
+}
+function artifactReferenceOwnerFields(config) {
+    const owner = artifactOwnerFields(config);
+    return owner.owner_type && owner.owner_id
+        ? { ownerType: owner.owner_type, ownerId: owner.owner_id }
+        : {};
+}
+function artifactOwnerDirectory(ownerType) {
+    return normalizedOwnerType(ownerType) === "story" ? "stories" : "work-items";
+}
+function artifactOwnerRelativeRoot(ownerType, ownerId, workItemId) {
+    const owner = artifactOwnerFields({ workItemId, ownerType, ownerId });
+    return owner.owner_type && owner.owner_id
+        ? [".forge", artifactOwnerDirectory(owner.owner_type), owner.owner_id, "artifacts"].join("/")
+        : [".forge", "work-items", workItemId, "artifacts"].join("/");
+}
+function defaultQaChecklist(status) {
+    return [
+        "Review the validated work item against acceptance criteria.",
+        "Inspect implementation, self-review, and validation evidence when available.",
+        status === "blocked" ? "Record the blocker reason preventing a conclusive QA verdict." : "Record concrete QA evidence and findings."
+    ];
+}
+function qaArtifactRelativePath(workItemId, fileName) {
+    return [".forge", "work-items", workItemId, "artifacts", fileName].join("/");
+}
+function qaArtifactRelativePathForOwner(ownerType, ownerId, fileName) {
+    return [".forge", artifactOwnerDirectory(ownerType), ownerId, "artifacts", fileName].join("/");
+}
+function jsonText(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function fallbackReport(parsed, phase, artifactPath) {
+    return `# Forge ${phase.replace(/_/g, " ")} completion
+
+Artifact: ${artifactPath}
+Status: ${optionalString(parsed, "status") ?? "unknown"}
+`;
+}
+function parseJsonObject(content, label) {
+    try {
+        return asRecord(JSON.parse(content), label);
+    }
+    catch (error) {
+        throw new Error(`${label} is not valid JSON: ${errorMessage(error)}`);
+    }
+}
+function parseOptionalJsonObject(content, label) {
+    if (!content.trim()) {
+        return {};
+    }
+    return parseJsonObject(content, label);
+}
+function asRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+}
+function asMutableRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? { ...value }
+        : {};
+}
+function requiredString(source, key) {
+    const value = source[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${key} must be a non-empty string.`);
+    }
+    return value;
+}
+function optionalString(source, key) {
+    const value = source[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+function numberOrDefault(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function safePathSegment(value, label) {
+    if (!value.trim() || value.includes("/") || value.includes("\\") || value === "." || value === "..") {
+        throw new Error(`${label} is not a safe path segment.`);
+    }
+    return value;
+}
+async function readOptionalFile(filePath) {
+    return await fs.readFile(filePath, "utf8").catch((error) => {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    });
+}
+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`);
+    await fs.writeFile(tempPath, content, "utf8");
+    await fs.rename(tempPath, filePath);
+}
+function stableStringify(value) {
+    return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortJson);
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, sortJson(entry)]));
+    }
+    return value;
+}
+function sha256(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+function forgeBridgeCliBinPath() {
+    return fileURLToPath(new URL("../cli/bin.js", import.meta.url));
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function tomlStringArray(values) {
+    return `[${values.map(tomlString).join(", ")}]`;
+}
+function writeJsonRpc(message) {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+function rpcError(code, message) {
+    return { code, message };
+}
+function asJsonRpcMessage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const message = value;
+    if (message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+        return null;
+    }
+    const id = message.id;
+    return {
+        id: typeof id === "string" || typeof id === "number" || id === null ? id : undefined,
+        method: message.method,
+        params: message.params
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}