@loucompanion/forge-bridge 0.1.1-dev.32d4dd5874ee → 0.1.1-dev.4f31cdd58cac

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

@@ -19,6 +19,24 @@ export interface CompletionToolServerConfig {
     readonly workItemId: string;
     readonly phase: CompletionPhase;
     readonly producedBy?: string;
+    readonly redactionSecrets?: readonly string[];
+    readonly developCycle?: boolean;
+}
+export interface CompletionToolCallResult {
+    readonly content: readonly {
+        readonly type: "text";
+        readonly text: string;
+    }[];
+    readonly structuredContent: CompletionArtifactReference & {
+        readonly gate: {
+            readonly phase: CompletionPhase;
+            readonly status: string;
+            readonly allowed: boolean;
+            readonly reason: string;
+        };
+        readonly nextPhase: CompletionPhase | "dev_test_ready";
+        readonly nextInstruction: string;
+    };
 }
 export interface CompletionArtifactReference {
     readonly phase: CompletionPhase;
@@ -32,6 +50,7 @@ export interface CompletionArtifactReference {
 }
 export declare function completionPhaseFromDispatch(dispatch: RunOnceDispatchPacket): CompletionPhase;
 export declare function normalizeCompletionPhase(value: string | null | undefined): CompletionPhase;
+export declare function usesDevelopCycleCompletion(dispatch: RunOnceDispatchPacket): boolean;
 export declare function completionToolNamesForPhase(phase: CompletionPhase): readonly string[];
 export declare function expectedCompletionToolName(phase: CompletionPhase): string;
 export declare function artifactRootFor(worktreePath: string, workItemId: string): string;
@@ -42,6 +61,18 @@ export declare function buildCompletionToolServerArgs(config: CompletionToolServ
 export declare function codexMcpConfigArgs(runtime: CompletionToolRuntime): readonly string[];
 export declare function cursorMcpServerConfig(runtime: CompletionToolRuntime): unknown;
 export declare function completionPromptForPhase(phase: CompletionPhase): string;
+export declare function completionPromptForDevelopCycle(phase: CompletionPhase): string;
+export declare function completionToolNamesForServer(config: CompletionToolServerConfig): readonly string[];
+export declare class CompletionToolServerSession {
+    private readonly config;
+    private currentPhase;
+    private completed;
+    constructor(config: CompletionToolServerConfig);
+    get instructions(): string;
+    toolDefinitions(): readonly unknown[];
+    callTool(toolName: string, input: unknown): Promise<CompletionToolCallResult>;
+    private advanceAfterPass;
+}
 export declare function writeCompletionArtifact(config: CompletionToolServerConfig, toolName: string, input: unknown): Promise<CompletionArtifactReference>;
 export declare function readCompletionArtifact(worktreePath: string, workItemId: string, phase: CompletionPhase): Promise<RunnerDispatchArtifact | null>;
 export declare function runCompletionMcpServer(config: CompletionToolServerConfig): Promise<void>;
@@ -52,3 +83,4 @@ export declare function parseCompletionMcpArgs(argv: readonly string[]): {
     readonly ok: false;
     readonly error: string;
 };
+export declare function completionRedactionEnv(secrets: readonly string[]): Readonly<Record<string, string>>;

package/dist/session/phase-completion.js

@@ -2,7 +2,10 @@ 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";
 const toolServerName = "forge";
+const completionRedactionSecretsEnv = "FORGE_COMPLETION_REDACTION_SECRETS";
+const completionPhaseOrder = ["implementation", "self_review", "validation"];
 const phaseFiles = {
     implementation: {
         jsonFileName: "implementation.completeness.json",
@@ -30,6 +33,15 @@ export function normalizeCompletionPhase(value) {
     }
     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 completionToolNamesForPhase(phase) {
     const base = phase === "implementation"
         ? "complete_implementation"
@@ -58,7 +70,8 @@ export async function prepareCompletionToolRuntime(options) {
         worktreePath,
         workItemId,
         phase,
-        producedBy: `${options.dispatch.execution.provider}-cli`
+        producedBy: `${options.dispatch.execution.provider}-cli`,
+        developCycle: usesDevelopCycleCompletion(options.dispatch)
     });
     const runtime = {
         serverName: toolServerName,
@@ -73,7 +86,7 @@ export async function prepareCompletionToolRuntime(options) {
     return await prepareCursorCompletionToolRuntime(worktreePath, runtime);
 }
 export function buildCompletionToolServerArgs(config) {
-    return [
+    const args = [
         "mcp",
         "--worktree",
         path.resolve(config.worktreePath),
@@ -84,6 +97,10 @@ export function buildCompletionToolServerArgs(config) {
         "--produced-by",
         config.producedBy ?? "forge-completion-tool"
     ];
+    if (config.developCycle) {
+        args.push("--develop-cycle");
+    }
+    return args;
 }
 export function codexMcpConfigArgs(runtime) {
     const prefix = `mcp_servers.${runtime.serverName}`;
@@ -114,20 +131,105 @@ Do not write phase artifacts by hand. When the phase is complete, call \`${toolN
 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 completionToolNamesForServer(config) {
+    return config.developCycle
+        ? completionPhaseOrder.flatMap((phase) => completionToolNamesForPhase(phase))
+        : completionToolNamesForPhase(config.phase);
+}
+export class CompletionToolServerSession {
+    config;
+    currentPhase;
+    completed = false;
+    constructor(config) {
+        this.config = config;
+        this.currentPhase = config.phase;
+    }
+    get instructions() {
+        return this.config.developCycle
+            ? completionPromptForDevelopCycle(this.currentPhase)
+            : completionPromptForPhase(this.currentPhase);
+    }
+    toolDefinitions() {
+        return completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name)));
+    }
+    async callTool(toolName, input) {
+        const requestedPhase = phaseFromToolName(toolName);
+        if (this.completed) {
+            throw new Error("Forge develop cycle is already complete; no more phase completion calls are accepted.");
+        }
+        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
+            }
+        };
+    }
+    advanceAfterPass(phase) {
+        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";
+    }
+}
 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 payload = asRecord(input, "completion payload");
-    validatePayloadShape(phase, payload);
-    validateOptionalWorkItemId(payload, config.workItemId);
-    const producedBy = optionalString(payload, "produced_by")
-        ?? optionalString(payload, "producedBy")
+    const status = normalizeCompletionStatus(requiredString(payload, "status"));
+    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";
-    const status = requiredString(payload, "status").trim().toLowerCase();
-    const artifactWithoutHash = normalizeArtifactPayload(payload, {
+    const artifactWithoutHash = normalizeArtifactPayload(redactedPayload, {
         phase,
         workItemId: config.workItemId,
         producedBy,
@@ -139,7 +241,7 @@ export async function writeCompletionArtifact(config, toolName, input) {
         content_hash: contentHash
     };
     const artifactJson = `${JSON.stringify(artifact, null, 2)}\n`;
-    const report = reportMarkdown(payload, phase, status, producedBy, contentHash);
+    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 });
@@ -176,6 +278,7 @@ export async function readCompletionArtifact(worktreePath, workItemId, phase) {
     };
 }
 export async function runCompletionMcpServer(config) {
+    const session = new CompletionToolServerSession(config);
     process.stdin.setEncoding("utf8");
     let buffer = "";
     for await (const chunk of process.stdin) {
@@ -185,14 +288,14 @@ export async function runCompletionMcpServer(config) {
             const rawLine = buffer.slice(0, newlineIndex).trim();
             buffer = buffer.slice(newlineIndex + 1);
             if (rawLine.length > 0) {
-                await handleJsonRpcLine(config, rawLine);
+                await handleJsonRpcLine(session, rawLine);
             }
             newlineIndex = buffer.indexOf("\n");
         }
     }
     const trailing = buffer.trim();
     if (trailing.length > 0) {
-        await handleJsonRpcLine(config, trailing);
+        await handleJsonRpcLine(session, trailing);
     }
 }
 export function parseCompletionMcpArgs(argv) {
@@ -200,6 +303,7 @@ export function parseCompletionMcpArgs(argv) {
     let workItemId = null;
     let phase = "implementation";
     let producedBy;
+    let developCycle = false;
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === "--worktree") {
@@ -219,6 +323,9 @@ export function parseCompletionMcpArgs(argv) {
         else if (arg === "--produced-by") {
             producedBy = argv[++index] ?? undefined;
         }
+        else if (arg === "--develop-cycle") {
+            developCycle = true;
+        }
         else {
             return { ok: false, error: `Unknown mcp argument: ${arg}` };
         }
@@ -232,10 +339,18 @@ export function parseCompletionMcpArgs(argv) {
             worktreePath: path.resolve(worktreePath),
             workItemId,
             phase,
-            producedBy
+            producedBy,
+            redactionSecrets: parseCompletionRedactionSecrets(process.env[completionRedactionSecretsEnv]),
+            developCycle
         }
     };
 }
+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");
@@ -263,7 +378,7 @@ async function prepareCursorCompletionToolRuntime(worktreePath, runtime) {
         }
     };
 }
-async function handleJsonRpcLine(config, rawLine) {
+async function handleJsonRpcLine(session, rawLine) {
     let message;
     try {
         message = JSON.parse(rawLine);
@@ -281,14 +396,14 @@ async function handleJsonRpcLine(config, rawLine) {
         return;
     }
     try {
-        const result = await handleJsonRpcRequest(config, request.method, request.params);
+        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(config, method, params) {
+async function handleJsonRpcRequest(session, method, params) {
     if (method === "initialize") {
         const initializeParams = params && typeof params === "object" && !Array.isArray(params)
             ? params
@@ -302,7 +417,7 @@ async function handleJsonRpcRequest(config, method, params) {
                 name: "forge-completion-tools",
                 version: "0.1.0"
             },
-            instructions: completionPromptForPhase(config.phase)
+            instructions: session.instructions
         };
     }
     if (method === "ping") {
@@ -310,23 +425,14 @@ async function handleJsonRpcRequest(config, method, params) {
     }
     if (method === "tools/list") {
         return {
-            tools: completionToolNamesForPhase(config.phase).map((name) => toolDefinition(name, config.phase))
+            tools: session.toolDefinitions()
         };
     }
     if (method === "tools/call") {
         const call = asRecord(params, "tools/call params");
         const name = requiredString(call, "name");
         const args = call.arguments ?? {};
-        const reference = await writeCompletionArtifact(config, name, args);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Forge recorded ${reference.phase} completion artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}).`
-                }
-            ],
-            structuredContent: reference
-        };
+        return await session.callTool(name, args);
     }
     throw new Error(`Unsupported MCP method: ${method}`);
 }
@@ -337,6 +443,22 @@ function toolDefinition(name, phase) {
         inputSchema: toolInputSchema(phase)
     };
 }
+function nextPhaseAfter(phase) {
+    const index = completionPhaseOrder.indexOf(phase);
+    return index >= 0 ? completionPhaseOrder[index + 1] ?? null : null;
+}
+function completionToolNextInstruction(completedPhase, status, nextPhase) {
+    if (status !== "pass") {
+        return `Stay in ${completedPhase}, address the recorded blockers, then call ${expectedCompletionToolName(completedPhase)} again.`;
+    }
+    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 Dev Test.";
+}
 function toolDescription(phase) {
     if (phase === "implementation") {
         return "Complete Forge implementation by writing implementation.completeness.json with scoped changed-file, verification, acceptance-criteria, gap, and next-phase evidence.";
@@ -347,69 +469,213 @@ function toolDescription(phase) {
     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) {
-    const base = {
-        type: "object",
-        additionalProperties: true,
-        properties: {
-            status: { type: "string", enum: ["pass", "blocked", "fail", "failed"] },
-            summary: { type: "string" },
-            report_markdown: { type: "string" },
-            blockers: { type: "array" }
+    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."
         },
-        required: ["status", "summary"]
+        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 (phase === "implementation") {
-        return {
-            ...base,
-            properties: {
-                ...base.properties,
-                plan: { type: "array" },
-                changed_files: { type: "array" },
-                tests_added_or_updated: { type: "array" },
-                docs_added_or_updated: { type: "array" },
-                verification: { type: "array" },
-                acceptance_criteria: { type: "array" },
-                known_gaps: { type: "array" },
-                next_phase_context: {}
+        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" }
+                })
             },
-            required: ["status", "summary"]
-        };
+            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 {
-            ...base,
-            properties: {
-                ...base.properties,
-                reviewed_diff: { type: "boolean" },
-                findings: { type: "array" },
-                security_review: { type: "object" },
-                edge_case_review: { type: "object" },
-                design_review: { type: "object" },
-                deterministic_comparison: { type: "object" },
-                fixes_applied: { type: "array" },
-                remaining_risks: { type: "array" }
+        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" }
+                })
             },
-            required: ["status", "summary"]
-        };
-    }
-    return {
-        ...base,
-        properties: {
-            ...base.properties,
-            commands: { type: "array" },
-            acceptance_criteria: { type: "array" },
-            build_status: { type: "string" },
-            test_status: { type: "string" },
-            lint_status: { type: "string" },
-            design_status: { type: "string" },
-            drift_checks: { type: "array" },
-            ready_for_dev_test: { type: "boolean" }
+            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.");
+    }
+    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" }
+            })
         },
-        required: ["status", "summary"]
+        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 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) {
+    const normalized = value.trim().toLowerCase().replace(/-/g, "_");
+    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 validatePayloadShape(phase, payload) {
-    const status = requiredString(payload, "status").trim().toLowerCase();
+    const status = normalizeCompletionStatus(requiredString(payload, "status"));
     if (!status) {
         throw new Error("status is required.");
     }
@@ -504,6 +770,21 @@ function parseStrictCompletionPhase(value) {
     }
     return null;
 }
+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") {

package/dist/session/provider-cli/provider-cli.service.d.ts

@@ -11,6 +11,7 @@ export interface ProviderProcessRunRequest {
     readonly command: string;
     readonly args: readonly string[];
     readonly cwd: string;
+    readonly env?: Readonly<Record<string, string>>;
 }
 export interface ProviderProcessRunResult {
     readonly exitCode: number;