@loucompanion/forge-bridge 0.1.3-dev.9bc5014a2270 → 0.1.3-dev.a58d7cd1092f

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

@@ -1,13 +1,13 @@
 import { completionPhaseOrder, completionToolNamesForPhase, debugCompletionPhaseOrder, expectedCompletionToolName, expectedDebugCompletionToolName, expectedDecomposeCompletionToolName, phaseFiles, toolServerName } from "./phase-completion.js";
 import { isDebugCompletionPhase, isDevelopCompletionPhase } from "./phase-completion.validation.js";
-export function completionPromptForPhase(phase) {
+export function completionPromptForPhase(phase, artifactRoot = ".forge/work-items/{workItemId}/artifacts") {
     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\`.
+That tool writes the durable QA bundle under \`${artifactRoot}/\`: \`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.
 Include \`policy_warnings\` for non-blocking Forge policy or scope mismatches that should remain visible after QA.
 Forge will mirror only the tool-written QA artifacts; reporting QA completion in prose is not enough.`;
@@ -17,11 +17,20 @@ Forge will mirror only the tool-written QA artifacts; reporting QA completion in
 Do not write Architect artifacts by hand. When the plan is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the full structured Architect planning payload.
 That tool writes \`.forge/work-items/{workItemId}/artifacts/implementation.plan.json\`, \`qa.plan.json\`, \`${artifactName}\`, and \`architect.report.md\`.
 The payload must put \`phases\`, \`tasks\`, \`dependencies\`, and \`phase_gates\` as top-level fields inside \`implementation_plan\`, for example:
-\`{ "status": "pass", "summary": "...", "implementation_plan": { "schema_version": 1, "plan_id": "plan-...", "phases": [{ "id": "phase-1", "tasks": ["task-1"], "gate": "gate-1" }], "tasks": [{ "id": "task-1", "verification_scope": { "schema_version": 1, "surface": ["domain_contract"], "required_evidence": ["unit_tests"], "not_applicable": ["browser_manual", "api_http"], "browser_required": false, "api_required": false, "rationale": "Backend-only child task." }, "tests": [{ "command": "npm test" }] }], "dependencies": [], "phase_gates": [{ "id": "gate-1", "phase": "phase-1" }] }, "qa_plan": { "schema_version": 1, "final_qa": [{ "id": "qa-1", "coverage": "..." }] }, "report_markdown": "# Architect Report" }\`.
+\`{ "status": "pass", "summary": "...", "implementation_plan": { "schema_version": 1, "plan_id": "plan-...", "phases": [{ "id": "phase-1", "tasks": ["task-1"], "gate": "gate-1" }], "tasks": [{ "id": "task-1", "verification_scope": { "schema_version": 1, "surface": ["domain_contract"], "required_evidence": ["unit_tests"], "required_capabilities": [], "not_applicable": ["browser_manual", "api_http"], "browser_required": false, "api_required": false, "rationale": "Backend-only child task." }, "tests": [{ "command": "npm test" }] }], "dependencies": [], "phase_gates": [{ "id": "gate-1", "phase": "phase-1" }] }, "qa_plan": { "schema_version": 1, "final_qa": [{ "id": "qa-1", "coverage": "..." }] }, "report_markdown": "# Architect Report" }\`.
 \`implementation_plan.tasks\` are Develop child tasks only: each task should include \`verification_scope\` describing task-level QA evidence, and must require a focused repo/product implementation change. Put parent-story QA, sign-off, child-count/materialization inventory, parent plan artifact checks, and final integrated acceptance proof in \`qa_plan.final_qa\`, not as child Develop tasks.
+When a task's implementation or validation starts containers or otherwise needs the host Docker daemon, include \`"required_capabilities": ["docker_engine"]\` in its verification scope. Do not encode a database, image, or Docker version as a runner capability; the repository owns those versions.
 Dependency entries use canonical \`before\` and \`after\` task ids, for example \`{ "before": "task-1", "after": "task-2" }\`. Forge accepts \`from\`/\`to\` only as aliases and normalizes them before writing artifacts.
 Use \`status: "pass"\` for a valid pending-approval plan, \`needs_revision\` when story/design input must change, or \`blocked\` with a concrete blocker.
 Forge will mirror only the tool-written Architect artifacts; reporting the plan in prose is not enough.`;
+    }
+    if (phase === "ci_repair") {
+        return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Read the generated \`.forge/work-items/{workItemId}/ci-repair.readiness.json\` before running validation.
+Do not write the CI-repair handoff by hand. After the repair and locally equivalent validation are complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""}.
+That tool validates failed-check inspection, root cause, scoped changes, narrow proof, every failed-job guard/test/drift step, provider-only classifications, broader validation, remaining risk, provider state, and push readiness.
+It writes \`.forge/work-items/{workItemId}/artifacts/${artifactName}\`. Forge Bridge will not commit, push, or report CI repair success until this gate passes.
+For a step classified \`provider_only\`, include the exact reason and provider check that will supply the missing proof. Do not weaken or delete the provider check.`;
     }
     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.
@@ -38,10 +47,10 @@ Complete the dev cycle in order inside this same provider session:
 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") {
+export function completionPromptForQaCycle(currentGate = "qa_plan", artifactRoot = ".forge/work-items/{workItemId}/artifacts") {
     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:
+Complete the QA cycle in order inside this same provider session. Start long, independent regression verification as early as practical, continue API/source/manual review while it runs, and wait for its receipt only when those independent checks are complete:
 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(...)\`.
@@ -50,7 +59,9 @@ Complete the QA cycle in order inside this same provider session:
 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\`.
+On a managed host, use focused checks plus the relevant runner-authored \`forge.start_managed_verification\` profiles for normal Story QA; shard slow tiers when broader evidence is justified. Reserve the \`dotnet_solution\` profile for shared test/runtime infrastructure, Feature/PR integration, or an explicit QA-plan requirement. Use \`forge.start_managed_command\` only for other commands expected to exceed two minutes. Continue independent QA work, then call \`forge.wait_managed_command\` for the durable terminal receipt; if it returns \`command_continues=true\`, continue useful work or wait again after \`retry_after_ms\`. Do not poll \`forge.get_managed_command\`. Include the terminal \`managed_command_id\` in command evidence. Forge records live progress outside the provider transcript.
+For a negative assertion, make the command itself exit 0 when the forbidden condition is absent. In particular, raw \`rg\` exit 1 means no matches but cannot be submitted as passing evidence; wrap it so no match exits 0, a match fails, and tool errors remain failures. Before every completion call, ensure passing command records have \`exit_code: 0\`, \`status: "pass"\`, and a summary. A rejected call writes no artifact; repair every issue returned by Forge and resubmit the same gate once without probing the filesystem.
+The final verdict tool writes the canonical QA bundle under \`${artifactRoot}/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`qa.verdict.json\`, and \`qa.report.md\`.
 Include \`policy_warnings\` in the final verdict for non-blocking Forge policy or scope mismatches that should remain visible after QA.
 The legacy \`forge.complete_qa\` one-shot tool is not available in normal QA-cycle mode. Reporting QA completion in prose is not enough.`;
 }
@@ -81,7 +92,7 @@ Required order:
 5. Follow the returned dependency-graph instruction, validate keys/dependencies/order, then call \`forge.complete_decompose_dependency_graph(...)\`.
 6. Follow the returned critic instruction, critique scope, DAG safety, manual reconciliation risk, and missing acceptance detail, then call \`forge.complete_decompose_critic(...)\`.
 7. Follow the returned proposal instruction, then call \`forge.complete_decompose_proposal(...)\` with final JSON in \`proposal_json\`.
-The final proposal tool writes \`decompose.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. The proposal_json object must contain summary, optional blockedReason, and candidates. Work Order-to-Feature candidates may include \`estimated_qa_scope\`; Feature-to-Story candidates should include \`qa_scope\` with schema_version 1 plus scheduleIndex, waveIndex, expectedOutput, handoffSummary, and dependencyReason for dependency handoff.`;
+The final proposal tool writes \`decompose.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. The proposal_json object must contain summary, optional blockedReason, and candidates. Work Order-to-Feature candidates may include \`estimated_qa_scope\`; Feature-to-Story candidates should include \`qa_scope\` with schema_version 1 plus scheduleIndex, waveIndex, expectedOutput, handoffSummary, and dependencyReason for dependency handoff. Set \`qa_scope.required_capabilities\` to \`["docker_engine"]\` when implementation or validation starts containers or needs a Docker daemon; repository-specific service and image versions do not belong in the runner capability name.`;
 }
 export function completionPromptForDebugCycle(currentGate = "debug_repro") {
     return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
@@ -115,6 +126,11 @@ export function completionToolNextInstruction(completedPhase, status, nextPhase)
         }
         return "QA accepted. Forge has the structured evidence needed to move this work item to Sign-Off.";
     }
+    if (completedPhase === "ci_repair") {
+        return status === "pass"
+            ? "CI repair handoff accepted. Forge Bridge may now commit, push, and return the PR to provider checks."
+            : "Stay in CI repair, address the exact missing evidence returned by this gate, then call forge.complete_ci_repair again.";
+    }
     if (status !== "pass") {
         return `Stay in ${completedPhase}, address the recorded blockers, then call ${expectedCompletionToolName(completedPhase)} again.`;
     }
@@ -203,7 +219,7 @@ export function completionToolNextInstructionForDebugGate(completedGate, status,
 function qaGateInstruction(gate) {
     switch (gate) {
         case "qa_regression":
-            return "Run or explicitly skip applicable regression/build/lint/typecheck/e2e checks, then call forge.complete_qa_regression.";
+            return "Run or explicitly skip applicable regression/build/lint/typecheck/e2e checks, then call forge.complete_qa_regression. For normal Story QA, prefer focused checks and runner-authored forge.start_managed_verification tier profiles; reserve dotnet_solution for shared infrastructure, Feature/PR integration, or an explicit plan requirement. Use forge.start_managed_command only for other commands expected to exceed two minutes, continue independent QA, then call forge.wait_managed_command and include its terminal managed_command_id in command evidence. If the wait returns command_continues=true, continue useful work or wait again after retry_after_ms; do not poll get_managed_command. Normalize negative assertions so an expected no-match exits 0. A reproduced failure outside the current diff and acceptance criteria may remain non-blocking only when the current item has independent passing evidence: preserve it as an out_of_scope_failure with candidate_bug_id, scope_evidence, acceptance_criteria_independent: true, and a failing focused repro command/exit code. Never classify an unexplained, in-scope, or infrastructure failure this way.";
         case "qa_api":
             return "Run or explicitly skip applicable API/backend contract checks, then call forge.complete_qa_api.";
         case "qa_manual_web":

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

@@ -1,4 +1,5 @@
 import { type CompletionToolCallResult, type CompletionToolRuntime, type CompletionToolRuntimeOptions, type CompletionToolServerConfig } from "./phase-completion.js";
+import { type ManagedAttemptToolResult } from "./managed-attempt-tools.js";
 export declare function prepareCompletionToolRuntime(options: CompletionToolRuntimeOptions): Promise<CompletionToolRuntime>;
 export declare function buildCompletionToolServerArgs(config: CompletionToolServerConfig): readonly string[];
 export declare function codexMcpConfigArgs(runtime: CompletionToolRuntime): readonly string[];
@@ -10,11 +11,12 @@ export declare class CompletionToolServerSession {
     private currentQaGate;
     private currentDraftGate;
     private currentDecomposeGate;
+    private readonly managedCommandReceipts;
     private completed;
     constructor(config: CompletionToolServerConfig);
     get instructions(): string;
     toolDefinitions(): readonly unknown[];
-    callTool(toolName: string, input: unknown): Promise<CompletionToolCallResult>;
+    callTool(toolName: string, input: unknown): Promise<CompletionToolCallResult | ManagedAttemptToolResult>;
     private callDecomposeGateTool;
     private callDraftGateTool;
     private callDebugGateTool;
@@ -25,6 +27,15 @@ export declare class CompletionToolServerSession {
     private advanceAfterQaGate;
     private advanceAfterDebugGate;
 }
+export declare function completionToolRuntimeEnvironment(runtimeEnvironment?: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+/**
+ * A solution-wide Forge test is long enough that a generic provider shell can
+ * expire while VSTest is still healthy. On managed host attempts, only the
+ * attempt-owned command runner can prove the exact process outcome and clean
+ * up its process tree. Keep this check at the completion gate so prompt drift
+ * cannot turn an arbitrary shell timeout into a QA blocker.
+ */
+export declare function assertManagedQaRegressionEvidence(input: unknown, receipts: readonly Readonly<Record<string, unknown>>[]): void;
 export declare function runCompletionMcpServer(config: CompletionToolServerConfig): Promise<void>;
 export declare function parseCompletionMcpArgs(argv: readonly string[]): {
     readonly ok: true;
@@ -34,3 +45,4 @@ export declare function parseCompletionMcpArgs(argv: readonly string[]): {
     readonly error: string;
 };
 export declare function completionRedactionEnv(secrets: readonly string[]): Readonly<Record<string, string>>;
+export declare function completionToolRejectedResult(toolName: string, error: unknown): Readonly<Record<string, unknown>>;

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

@@ -1,10 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { completionPhaseFromDispatch, completionPhaseOrder, completionRedactionSecretsEnv, completionToolNamesForDebugGate, completionToolNamesForDecomposeGate, completionToolNamesForDraftGate, completionToolNamesForPhase, completionToolNamesForQaGate, debugCompletionPhaseOrder, decomposeCompletionGateOrder, draftCompletionGateOrder, qaCompletionGateOrder, toolServerName, usesArchitectCycleCompletion, usesDebugCycleCompletion, usesDevelopCycleCompletion, usesQaCycleCompletion } from "./phase-completion.js";
-import { asDebugCompletionPhase, asJsonRpcMessage, asMutableRecord, asRecord, decomposeGateFromToolName, draftGateFromToolName, errorMessage, forgeBridgeCliBinPath, isDebugCompletionPhase, isDecomposeDispatch, isDevelopCompletionPhase, normalizedOwnerType, parseCompletionRedactionSecrets, parseOptionalJsonObject, parseStrictCompletionPhase, phaseFromToolName, qaGateFromToolName, requiredString, rpcError, tomlString, tomlStringArray, writeFileAtomic, writeJsonRpc } from "./phase-completion.validation.js";
+import { CompletionPayloadValidationError, asDebugCompletionPhase, asJsonRpcMessage, asMutableRecord, asRecord, artifactOwnerRelativeRoot, decomposeGateFromToolName, draftGateFromToolName, errorMessage, forgeBridgeCliBinPath, isDebugCompletionPhase, isDecomposeDispatch, isDevelopCompletionPhase, normalizedOwnerType, parseCompletionRedactionSecrets, parseOptionalJsonObject, parseStrictCompletionPhase, phaseFromToolName, qaGateFromToolName, requiredString, rpcError, tomlString, tomlStringArray, writeFileAtomic, writeJsonRpc } from "./phase-completion.validation.js";
 import { completionPromptForDebugCycle, completionPromptForDecomposeCycle, completionPromptForDevelopCycle, completionPromptForDraftCycle, completionPromptForPhase, completionPromptForQaCycle, completionToolNextInstruction, completionToolNextInstructionForDebugGate, completionToolNextInstructionForDecomposeGate, completionToolNextInstructionForDraftGate, completionToolNextInstructionForQaGate, nextDebugPhaseAfter, nextPhaseAfter } from "./phase-completion.prompts.js";
 import { toolDescription, toolInputSchema } from "./phase-completion.schemas.js";
 import { writeCompletionArtifact, writeDecomposeGateCompletionArtifact, writeDraftGateCompletionArtifact } from "./phase-completion.artifacts.js";
+import { callManagedAttemptTool, isManagedAttemptTool, managedAttemptToolDefinition, managedAttemptToolNames, } from "./managed-attempt-tools.js";
 export async function prepareCompletionToolRuntime(options) {
     const phase = options.phase ?? completionPhaseFromDispatch(options.dispatch);
     const worktreePath = path.resolve(options.worktree.worktreePath);
@@ -32,7 +33,7 @@ export async function prepareCompletionToolRuntime(options) {
         serverName: toolServerName,
         command: process.execPath,
         args: [forgeBridgeCliBinPath(), ...mcpArgs],
-        env: {},
+        env: completionToolRuntimeEnvironment(options.runtimeEnvironment),
         cleanup: async () => undefined
     };
     if (options.dispatch.execution.provider.trim().toLowerCase() !== "cursor") {
@@ -82,7 +83,11 @@ export function codexMcpConfigArgs(runtime) {
         "-c",
         `${prefix}.command=${tomlString(runtime.command)}`,
         "-c",
-        `${prefix}.args=${tomlStringArray(runtime.args)}`
+        `${prefix}.args=${tomlStringArray(runtime.args)}`,
+        "-c",
+        `${prefix}.default_tools_approval_mode=${tomlString("approve")}`,
+        "-c",
+        `${prefix}.tool_timeout_sec=7200`
     ];
     for (const [key, value] of Object.entries(runtime.env)) {
         args.push("-c", `${prefix}.env.${key}=${tomlString(value)}`);
@@ -117,6 +122,7 @@ export class CompletionToolServerSession {
     currentQaGate = "qa_plan";
     currentDraftGate = "draft_intent";
     currentDecomposeGate = "decompose_subject_intake";
+    managedCommandReceipts = [];
     completed = false;
     constructor(config) {
         this.config = config;
@@ -130,15 +136,28 @@ export class CompletionToolServerSession {
                 : this.config.debugCycle
                     ? completionPromptForDebugCycle(asDebugCompletionPhase(this.currentPhase))
                     : this.config.qaCycle
-                        ? completionPromptForQaCycle(this.currentQaGate)
+                        ? completionPromptForQaCycle(this.currentQaGate, artifactOwnerRelativeRoot(this.config.ownerType, this.config.ownerId, this.config.workItemId))
                         : this.config.developCycle
                             ? completionPromptForDevelopCycle(this.currentPhase)
-                            : completionPromptForPhase(this.currentPhase);
+                            : completionPromptForPhase(this.currentPhase, artifactOwnerRelativeRoot(this.config.ownerType, this.config.ownerId, this.config.workItemId));
     }
     toolDefinitions() {
-        return completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name), qaGateFromToolName(name), decomposeGateFromToolName(name)));
+        const completionTools = completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name), qaGateFromToolName(name), decomposeGateFromToolName(name)));
+        return managedAttemptToolsAvailable()
+            ? [...completionTools, ...managedAttemptToolNames.map(managedAttemptToolDefinition)]
+            : completionTools;
     }
     async callTool(toolName, input) {
+        if (isManagedAttemptTool(toolName)) {
+            if (!managedAttemptToolsAvailable()) {
+                throw new Error("Forge managed-attempt tools require an active managed host runtime.");
+            }
+            const result = await callManagedAttemptTool(toolName, input, this.config.worktreePath);
+            if (Array.isArray(result.structuredContent.command)) {
+                this.managedCommandReceipts.push(result.structuredContent);
+            }
+            return result;
+        }
         const requestedPhase = phaseFromToolName(toolName);
         if (this.completed) {
             throw new Error("Forge completion cycle is already complete; no more completion calls are accepted.");
@@ -178,6 +197,7 @@ export class CompletionToolServerSession {
             ],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: {
                     phase: completedPhase,
                     status,
@@ -215,6 +235,7 @@ export class CompletionToolServerSession {
             content: [{ type: "text", text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}` }],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: { phase: "decompose", decomposeGate: completedGate, status, allowed: pass, reason },
                 nextPhase,
                 nextInstruction
@@ -239,6 +260,7 @@ export class CompletionToolServerSession {
             content: [{ type: "text", text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}` }],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: { phase: "draft", draftGate: completedGate, status, allowed: status !== "blocked", reason: nextGate ? `${completedGate} artifact accepted; continue to ${nextGate}.` : `Draft proposal artifact accepted with status ${status}.` },
                 nextPhase,
                 nextInstruction
@@ -272,6 +294,7 @@ export class CompletionToolServerSession {
             ],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: {
                     phase: completedGate,
                     status,
@@ -292,6 +315,9 @@ export class CompletionToolServerSession {
             throw new Error(`Tool ${toolName} is out of order. Current Forge QA gate is ${this.currentQaGate}.`);
         }
         const completedGate = this.currentQaGate;
+        if (completedGate === "qa_regression" && managedAttemptToolsAvailable()) {
+            assertManagedQaRegressionEvidence(input, this.managedCommandReceipts);
+        }
         const reference = await writeCompletionArtifact({ ...this.config, phase: "qa" }, toolName, input);
         const status = reference.status.trim().toLowerCase();
         const nextGate = this.advanceAfterQaGate(completedGate);
@@ -310,6 +336,7 @@ export class CompletionToolServerSession {
             ],
             structuredContent: {
                 ...reference,
+                ...acceptedArtifactReceipt(reference),
                 gate: {
                     phase: "qa",
                     qaGate: completedGate,
@@ -327,6 +354,10 @@ export class CompletionToolServerSession {
             this.completed = true;
             return "sign_off_ready";
         }
+        if (phase === "ci_repair") {
+            this.completed = true;
+            return "provider_checks_ready";
+        }
         if (isDebugCompletionPhase(phase)) {
             return nextDebugPhaseAfter(phase) ?? "qa_ready";
         }
@@ -382,6 +413,118 @@ export class CompletionToolServerSession {
         return null;
     }
 }
+const completionToolRuntimeEnvironmentNames = [
+    "FORGE_RUNTIME_MODE",
+    "FORGE_RESOURCE_LEASE_ID",
+    "FORGE_DISPATCH_ATTEMPT_ID",
+    "FORGE_E2E_OWNERSHIP_MODE",
+    "FORGE_E2E_OWNERSHIP_TOKEN",
+    "FORGE_WORKTREE_PATH",
+    "FORGE_LOG_DIR",
+    "FORGE_CACHE_DIR",
+    "FORGE_TEST_OUTPUT_DIR",
+    "FORGE_ATTEMPT_DATABASE_SCHEMA",
+    "FORGE_ATTEMPT_DATABASE_READINESS_PATH",
+    "FORGE_CI_REPAIR_READINESS_PATH",
+    "FORGE_CI_REPAIR_HANDOFF_PATH",
+    "FORGE_CI_REPAIR_PROVIDER_ONLY_SPECS",
+    "FORGE_PLAYWRIGHT_CONFIG",
+    "FORGE_E2E_API_URL",
+    "FORGE_E2E_WEB_URL",
+    "PLAYWRIGHT_BROWSERS_PATH",
+    "FORGE_TMPDIR",
+    "NPM_CONFIG_CACHE",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+];
+export function completionToolRuntimeEnvironment(runtimeEnvironment) {
+    if (!runtimeEnvironment)
+        return {};
+    const env = {};
+    for (const name of completionToolRuntimeEnvironmentNames) {
+        const value = runtimeEnvironment[name]?.trim();
+        if (value)
+            env[name] = value;
+    }
+    return env;
+}
+const minimumManagedSolutionTestTimeoutMs = 45 * 60 * 1000;
+/**
+ * A solution-wide Forge test is long enough that a generic provider shell can
+ * expire while VSTest is still healthy. On managed host attempts, only the
+ * attempt-owned command runner can prove the exact process outcome and clean
+ * up its process tree. Keep this check at the completion gate so prompt drift
+ * cannot turn an arbitrary shell timeout into a QA blocker.
+ */
+export function assertManagedQaRegressionEvidence(input, receipts) {
+    const payload = asRecord(input, "QA regression completion payload");
+    const nestedEvidence = asMutableRecord(payload.evidence);
+    const commands = payload.commands ?? nestedEvidence.commands;
+    if (!Array.isArray(commands))
+        return;
+    for (const [index, entry] of commands.entries()) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const command = entry.command;
+        if (typeof command !== "string" || !isForgeSolutionTestCommand(command))
+            continue;
+        const managedCommandId = entry.managed_command_id;
+        if (typeof managedCommandId !== "string" || !managedCommandId.trim()) {
+            throw new Error(`qa_regression_managed_command_id_required: commands[${index}] runs the solution-wide Forge test. `
+                + "Run it with forge.start_managed_command, continue independent work, then call forge.wait_managed_command for a transport-safe receipt. "
+                + "If command_continues=true, continue useful work or wait again after retry_after_ms. Include the terminal managed_command_id in this command evidence.");
+        }
+        const matchingReceipts = receipts.filter((receipt) => {
+            const tokens = receipt.command;
+            return receipt.command_id === managedCommandId
+                && Array.isArray(tokens)
+                && tokens.every((token) => typeof token === "string")
+                && isForgeSolutionTestCommand(tokens.join(" "));
+        });
+        if (matchingReceipts.length === 0) {
+            throw new Error(`qa_regression_managed_command_required: commands[${index}] runs the solution-wide Forge test. `
+                + "Run it with forge.start_managed_command, continue independent work, then call forge.wait_managed_command for a transport-safe receipt. "
+                + "If command_continues=true, continue useful work or wait again after retry_after_ms. Include its matching terminal managed_command_id; generic-shell timeout evidence is not accepted on a managed host.");
+        }
+        const terminalReceipts = matchingReceipts.filter((receipt) => typeof receipt.status === "string" && [
+            "pass",
+            "fail",
+            "timed_out",
+            "timeout_termination_failed",
+            "runner_error",
+        ].includes(receipt.status));
+        if (terminalReceipts.length === 0) {
+            throw new Error(`qa_regression_managed_command_in_progress: commands[${index}] has not produced a terminal managed receipt. `
+                + "Call forge.wait_managed_command. If command_continues=true, continue useful work or wait again after retry_after_ms; resubmit this gate only after the receipt is terminal.");
+        }
+        const adequateReceipt = terminalReceipts.some((receipt) => {
+            if (receipt.timed_out !== true)
+                return true;
+            return typeof receipt.timeout_ms === "number"
+                && receipt.timeout_ms >= minimumManagedSolutionTestTimeoutMs
+                && receipt.process_tree_terminated === true;
+        });
+        if (!adequateReceipt) {
+            throw new Error(`qa_regression_managed_timeout_too_short: commands[${index}] timed out before the minimum `
+                + `${minimumManagedSolutionTestTimeoutMs}ms solution-test budget. Rerun it with forge.start_managed_command `
+                + "using at least a 45-minute timeout and resubmit this gate.");
+        }
+    }
+}
+function isForgeSolutionTestCommand(command) {
+    const normalized = command.trim().toLowerCase().replaceAll("\\", "/");
+    return normalized.includes("dotnet")
+        && /(?:^|\s)test(?:\s|$)/u.test(normalized)
+        && /(?:^|[\s/"'])forge\.sln(?:[\s"']|$)/u.test(normalized);
+}
+function managedAttemptToolsAvailable() {
+    return process.env.FORGE_RUNTIME_MODE === "host"
+        && Boolean(process.env.FORGE_RESOURCE_LEASE_ID?.trim())
+        && Boolean(process.env.FORGE_DISPATCH_ATTEMPT_ID?.trim())
+        && Boolean(process.env.FORGE_LOG_DIR?.trim())
+        && Boolean(process.env.FORGE_TEST_OUTPUT_DIR?.trim());
+}
 export async function runCompletionMcpServer(config) {
     const session = new CompletionToolServerSession(config);
     process.stdin.setEncoding("utf8");
@@ -437,7 +580,7 @@ export function parseCompletionMcpArgs(argv) {
             const rawPhase = argv[++index];
             const parsedPhase = parseStrictCompletionPhase(rawPhase);
             if (!parsedPhase) {
-                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation, qa, architect, draft, debug-repro, debug-root-cause, debug-fix, debug-regression." };
+                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation, qa, architect, draft, decompose, ci-repair, debug-repro, debug-root-cause, debug-fix, debug-regression." };
             }
             phase = parsedPhase;
         }
@@ -596,10 +739,48 @@ async function handleJsonRpcRequest(session, method, params) {
         const call = asRecord(params, "tools/call params");
         const name = requiredString(call, "name");
         const args = call.arguments ?? {};
-        return await session.callTool(name, args);
+        try {
+            return await session.callTool(name, args);
+        }
+        catch (error) {
+            if (isManagedAttemptTool(name))
+                throw error;
+            return completionToolRejectedResult(name, error);
+        }
     }
     throw new Error(`Unsupported MCP method: ${method}`);
 }
+export function completionToolRejectedResult(toolName, error) {
+    const issues = error instanceof CompletionPayloadValidationError
+        ? [...error.issues]
+        : [errorMessage(error)];
+    const repairInstruction = "Repair every listed issue and resubmit this same gate once. Do not inspect the artifact path: rejected calls never write or replace completion artifacts.";
+    return {
+        content: [{
+                type: "text",
+                text: `Forge rejected ${toolName}. No artifact was written.\n${issues.map(issue => `- ${issue}`).join("\n")}\n${repairInstruction}`,
+            }],
+        structuredContent: {
+            status: "rejected",
+            tool_name: toolName,
+            artifact_written: false,
+            issues,
+            repair_instruction: repairInstruction,
+        },
+        isError: true,
+    };
+}
+function acceptedArtifactReceipt(reference) {
+    return {
+        artifact_written: true,
+        artifact_receipt: {
+            schema_version: 1,
+            path: reference.path,
+            report_path: reference.reportPath,
+            content_hash: reference.contentHash,
+        },
+    };
+}
 function toolDefinition(name, phase, qaGate = null, decomposeGate = null) {
     return {
         name,

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

@@ -16,6 +16,9 @@ export function toolDescription(phase, qaGate = null, decomposeGate = null) {
     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 === "ci_repair") {
+        return "Complete Forge CI repair by writing ci-repair.handoff.json with failed-check, root-cause, scoped-change, workflow-equivalence, validation, provider-state, and push-readiness evidence.";
+    }
     if (phase === "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.";
     }
@@ -55,6 +58,94 @@ export function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
     if (isDebugCompletionPhase(phase)) {
         return debugToolInputSchema(phase, baseProperties);
     }
+    if (phase === "ci_repair") {
+        return objectToolSchema({
+            ...baseProperties,
+            failed_checks: {
+                type: "array",
+                description: "Required and non-empty for pass. Provider check/job/step evidence inspected before repair.",
+                items: evidenceObjectSchema(["name", "provider_state"], {
+                    name: { type: "string" },
+                    provider_state: { type: "string" },
+                    workflow: { type: "string" },
+                    job: { type: "string" },
+                    step: { type: "string" },
+                    details_url: { type: "string" },
+                    evidence: { type: "string" }
+                })
+            },
+            root_cause: {
+                type: "object",
+                description: "Required for pass. Include classification, summary, and concrete evidence.",
+                additionalProperties: true,
+                properties: {
+                    classification: { type: "string" },
+                    summary: { type: "string" },
+                    evidence: { type: "array", items: { type: "string" } }
+                }
+            },
+            changed_files: {
+                type: "array",
+                description: "Files changed by the repair. May be empty only when no_code_action explains the provider-only action or blocker.",
+                items: evidenceObjectSchema(["path", "summary"], {
+                    path: { type: "string" },
+                    summary: { type: "string" }
+                })
+            },
+            no_code_action: {
+                type: "object",
+                description: "Required when changed_files is empty. Describe the evidence-backed provider action or blocker.",
+                additionalProperties: true,
+                properties: {
+                    action: { type: "string" },
+                    reason: { type: "string" },
+                    evidence: { type: "string" }
+                }
+            },
+            narrow_validation: {
+                type: "array",
+                description: "Required and non-empty for pass. The focused failing command or evidence-backed substitute.",
+                items: commandEvidenceSchema()
+            },
+            workflow_validation: {
+                type: "array",
+                description: "Required and non-empty for pass. Each failed-job guard/test/drift step with local equivalence supported, substitute, or provider_only.",
+                items: evidenceObjectSchema(["step", "equivalence", "status"], {
+                    step: { type: "string" },
+                    equivalence: { type: "string", enum: ["supported", "substitute", "provider_only"] },
+                    command: { type: "string" },
+                    exit_code: { type: "number" },
+                    status: { type: "string" },
+                    summary: { type: "string" },
+                    reason: { type: "string" },
+                    substitute: { type: "string" }
+                })
+            },
+            broader_validation: {
+                type: "array",
+                description: "Required and non-empty for pass. Normal validation covering every touched compiled/tested surface.",
+                items: commandEvidenceSchema()
+            },
+            remaining_risks: {
+                type: "array",
+                description: "Required for pass, even when empty.",
+                items: evidenceObjectSchema(["summary"], {
+                    summary: { type: "string" },
+                    mitigation: { type: "string" },
+                    owner: { type: "string" }
+                })
+            },
+            provider_state: {
+                type: "string",
+                enum: ["ready_for_rerun", "rerun_requested", "checks_pending", "still_failing", "blocked_by_provider"],
+                description: "Provider state after local validation and before Forge-owned publication."
+            },
+            ready_for_push: {
+                type: "boolean",
+                description: "Required for pass and must be true. Forge Bridge performs the commit/push only after this gate passes."
+            }
+        }, ["status", "summary"], "For status pass, include failed_checks, root_cause, changed_files or no_code_action, narrow_validation, workflow_validation, broader_validation, remaining_risks, provider_state, and ready_for_push: true.");
+    }
     if (phase === "implementation") {
         return objectToolSchema({
             ...baseProperties,
@@ -130,7 +221,10 @@ export function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
                     file: { type: "string" }
                 })
             },
-            security_review: reviewSectionSchema(),
+            security_review: {
+                ...reviewSectionSchema(),
+                description: "Required for pass. Use pass after review, or not_applicable only with notes explaining why the change has no security-relevant surface."
+            },
             edge_case_review: reviewSectionSchema(),
             design_review: {
                 ...reviewSectionSchema(),
@@ -198,7 +292,7 @@ export function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
             },
             sidecars: {
                 type: "array",
-                description: "Optional QA sidecar files already written under .forge/work-items/<id>/artifacts/qa/ with path/content_hash/bytes metadata.",
+                description: "Optional QA sidecar files already written under the dispatch-provided QA artifacts path with path/content_hash/bytes metadata.",
                 items: evidenceObjectSchema(["path", "content_hash", "bytes"], {
                     path: { type: "string" },
                     content_hash: { type: "string" },
@@ -628,6 +722,11 @@ function qaScopeSchema(description) {
             schema_version: { type: "number", enum: [1] },
             surface: { type: "array", items: { type: "string", enum: [...qaScopeSurfaces] } },
             required_evidence: { type: "array", items: { type: "string", enum: [...qaScopeEvidence] } },
+            required_capabilities: {
+                type: "array",
+                description: "Runner facilities required by implementation and validation. Use docker_engine when tests or project services require access to a Docker daemon, even when the agent itself runs in a managed host worktree.",
+                items: { type: "string", enum: ["docker_engine"] }
+            },
             not_applicable: { type: "array", items: { type: "string", enum: [...qaScopeEvidence] } },
             browser_required: { type: "boolean" },
             api_required: { type: "boolean" },
@@ -652,9 +751,23 @@ function qaScopeSchema(description) {
 function commandEvidenceSchema() {
     return evidenceObjectSchema(["command", "exit_code", "status", "summary"], {
         command: { type: "string" },
-        exit_code: { type: "number" },
+        managed_command_id: { type: "string", description: "Receipt ID returned by forge.start_managed_command after forge.wait_managed_command reports a terminal receipt. A transport-safe wait can return command_continues=true; wait again after retry_after_ms before submitting the gate." },
+        exit_code: { type: ["number", "null"], description: "Process exit code, or null when the managed runner timed out or could not launch the process." },
         status: { type: "string" },
-        summary: { type: "string" }
+        summary: { type: "string" },
+        classification: {
+            type: "string",
+            enum: ["out_of_scope_failure", "baseline_failure"],
+            description: "Only for a verified non-blocking failure in a passing QA regression gate. Never use for an in-scope or unexplained failure."
+        },
+        candidate_bug_id: { type: "string", description: "Required for a classified non-blocking failure; links the preserved failure to candidate_bugs." },
+        scope_evidence: { type: "string", description: "Required proof that the failing surface is outside the current acceptance criteria and changed-file scope." },
+        acceptance_criteria_independent: { type: "boolean", description: "Required and true only when the current item can be judged independently of this failure." },
+        repro_command: { type: "string", description: "Required for out_of_scope_failure; focused command that reproduced the unrelated failure." },
+        repro_exit_code: { type: "number", description: "Required non-zero focused repro exit code for out_of_scope_failure." },
+        baseline_ref: { type: "string", description: "Required for baseline_failure; immutable ref where the same failure was observed." },
+        baseline_exit_code: { type: "number", description: "Required non-zero baseline command exit code for baseline_failure." },
+        failure_signature_match: { type: "boolean", description: "Required and true for baseline_failure after matching failing test/error signatures." }
     });
 }
 function resolvedFindingSchema() {

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

@@ -2,9 +2,12 @@ import { type CompletionPhase, type DebugCompletionPhase, type QaCompletionGate
 export declare function normalizeCompletionStatus(value: string, phase?: CompletionPhase): string;
 export declare function normalizeQaGateStatus(value: string): string;
 export declare function validatePayloadShape(phase: CompletionPhase, payload: Record<string, unknown>): void;
+export declare function validateCiRepairPayloadShape(payload: Record<string, unknown>): void;
 export declare function validateDebugPayloadShape(phase: DebugCompletionPhase, payload: Record<string, unknown>): void;
 export declare function validateQaGatePayloadShape(gate: QaCompletionGate, payload: Record<string, unknown>, status: string): void;
-export declare function validateQaGatePassingCommands(commands: readonly unknown[]): void;
+export declare function validateQaGatePassingCommands(commands: readonly unknown[], options?: {
+    readonly allowClassifiedNonBlockingFailures?: boolean;
+}): void;
 export declare function validateArchitectPayloadShape(payload: Record<string, unknown>, status: string): void;
 export declare function validateArchitectTaskDevelopScope(task: Record<string, unknown>, taskId: string): void;
 export declare function validateArchitectVerificationScope(task: Record<string, unknown>, taskId: string): void;