@loucompanion/forge-bridge 0.1.1-dev.40fbc494669b → 0.1.1-dev.5093acd6bece

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

@@ -3,8 +3,10 @@ import type { WorktreeHandle } from "../worktree/worktree.types.js";
 export type DevelopCompletionPhase = "implementation" | "self_review" | "validation";
 export type DebugCompletionPhase = "debug_repro" | "debug_root_cause" | "debug_fix" | "debug_regression";
 export type ArchitectCompletionPhase = "architect";
-export type CompletionPhase = DevelopCompletionPhase | "qa" | DebugCompletionPhase | ArchitectCompletionPhase;
+export type DraftCompletionPhase = "draft";
+export type CompletionPhase = DevelopCompletionPhase | "qa" | DebugCompletionPhase | ArchitectCompletionPhase | DraftCompletionPhase;
 export type QaCompletionGate = "qa_plan" | "qa_regression" | "qa_api" | "qa_manual_web" | "qa_bug_repro" | "qa_findings" | "qa_verdict";
+export type DraftCompletionGate = "draft_intent" | "draft_repo_context" | "draft_graph_context" | "draft_product_scope" | "draft_work_order_plan" | "draft_critic" | "draft_proposal";
 export interface CompletionToolRuntime {
     readonly serverName: string;
     readonly command: string;
@@ -30,6 +32,7 @@ export interface CompletionToolServerConfig {
     readonly qaCycle?: boolean;
     readonly debugCycle?: boolean;
     readonly architectCycle?: boolean;
+    readonly draftCycle?: boolean;
 }
 export interface CompletionToolCallResult {
     readonly content: readonly {
@@ -40,6 +43,7 @@ export interface CompletionToolCallResult {
         readonly gate: {
             readonly phase: CompletionPhase;
             readonly qaGate?: QaCompletionGate;
+            readonly draftGate?: DraftCompletionGate;
             readonly status: string;
             readonly allowed: boolean;
             readonly reason: string;
@@ -62,6 +66,7 @@ export interface CompletionArtifactReference {
 }
 export declare const debugCompletionPhaseOrder: readonly DebugCompletionPhase[];
 export declare const qaCompletionGateOrder: readonly QaCompletionGate[];
+export declare const draftCompletionGateOrder: readonly DraftCompletionGate[];
 export declare function completionPhaseFromDispatch(dispatch: RunOnceDispatchPacket): CompletionPhase;
 export declare function normalizeCompletionPhase(value: string | null | undefined): CompletionPhase;
 export declare function usesDevelopCycleCompletion(dispatch: RunOnceDispatchPacket): boolean;
@@ -71,9 +76,11 @@ export declare function usesArchitectCycleCompletion(dispatch: RunOnceDispatchPa
 export declare function completionToolNamesForPhase(phase: CompletionPhase): readonly string[];
 export declare function completionToolNamesForQaGate(gate: QaCompletionGate): readonly string[];
 export declare function completionToolNamesForDebugGate(gate: DebugCompletionPhase): readonly string[];
+export declare function completionToolNamesForDraftGate(gate: DraftCompletionGate): readonly string[];
 export declare function expectedCompletionToolName(phase: CompletionPhase): string;
 export declare function expectedQaCompletionToolName(gate: QaCompletionGate): string;
 export declare function expectedDebugCompletionToolName(gate: DebugCompletionPhase): string;
+export declare function expectedDraftCompletionToolName(gate: DraftCompletionGate): string;
 export declare function artifactRootFor(worktreePath: string, workItemId: string): string;
 export declare function artifactRootForOwner(worktreePath: string, ownerType: string, ownerId: string): string;
 export declare function completionArtifactJsonPath(worktreePath: string, workItemId: string, phase: CompletionPhase, ownerType?: string | null, ownerId?: string | null): string;
@@ -85,20 +92,24 @@ export declare function cursorMcpServerConfig(runtime: CompletionToolRuntime): u
 export declare function completionPromptForPhase(phase: CompletionPhase): string;
 export declare function completionPromptForDevelopCycle(phase: CompletionPhase): string;
 export declare function completionPromptForQaCycle(currentGate?: QaCompletionGate): string;
+export declare function completionPromptForDraftCycle(currentGate?: DraftCompletionGate): string;
 export declare function completionPromptForDebugCycle(currentGate?: DebugCompletionPhase): string;
 export declare function completionToolNamesForServer(config: CompletionToolServerConfig): readonly string[];
 export declare class CompletionToolServerSession {
     private readonly config;
     private currentPhase;
     private currentQaGate;
+    private currentDraftGate;
     private completed;
     constructor(config: CompletionToolServerConfig);
     get instructions(): string;
     toolDefinitions(): readonly unknown[];
     callTool(toolName: string, input: unknown): Promise<CompletionToolCallResult>;
+    private callDraftGateTool;
     private callDebugGateTool;
     private callQaGateTool;
     private advanceAfterPass;
+    private advanceAfterDraftGate;
     private advanceAfterQaGate;
     private advanceAfterDebugGate;
 }

package/dist/session/phase-completion.js

@@ -22,6 +22,33 @@ export const qaCompletionGateOrder = [
     "qa_findings",
     "qa_verdict"
 ];
+export const draftCompletionGateOrder = [
+    "draft_intent",
+    "draft_repo_context",
+    "draft_graph_context",
+    "draft_product_scope",
+    "draft_work_order_plan",
+    "draft_critic",
+    "draft_proposal"
+];
+const draftGateFileNames = {
+    draft_intent: "draft.intent.json",
+    draft_repo_context: "draft.repo-context.json",
+    draft_graph_context: "draft.graph-context.json",
+    draft_product_scope: "draft.product-scope.json",
+    draft_work_order_plan: "draft.work-order-plan.json",
+    draft_critic: "draft.critic.json",
+    draft_proposal: "draft.proposal.json"
+};
+const draftGateToolNames = {
+    draft_intent: "complete_draft_intent",
+    draft_repo_context: "complete_draft_repo_context",
+    draft_graph_context: "complete_draft_graph_context",
+    draft_product_scope: "complete_draft_product_scope",
+    draft_work_order_plan: "complete_draft_work_order_plan",
+    draft_critic: "complete_draft_critic",
+    draft_proposal: "complete_draft_proposal"
+};
 const qaGateFileNames = {
     qa_plan: "qa.plan.json",
     qa_regression: "qa.regression.json",
@@ -95,6 +122,10 @@ const phaseFiles = {
     architect: {
         jsonFileName: "architect.verdict.json",
         reportFileName: "architect.report.md"
+    },
+    draft: {
+        jsonFileName: "draft.proposal.json",
+        reportFileName: "draft.report.md"
     }
 };
 export function completionPhaseFromDispatch(dispatch) {
@@ -118,6 +149,9 @@ export function normalizeCompletionPhase(value) {
     if (normalized === "architect" || normalized === "architect_plan" || normalized === "planning" || normalized === "plan") {
         return "architect";
     }
+    if (normalized === "draft" || normalized === "drafting" || normalized === "draft_work_order") {
+        return "draft";
+    }
     return "implementation";
 }
 export function usesDevelopCycleCompletion(dispatch) {
@@ -154,6 +188,9 @@ export function usesArchitectCycleCompletion(dispatch) {
     return kind === "architect" || role === "architect" || lane === "architect";
 }
 export function completionToolNamesForPhase(phase) {
+    if (phase === "draft") {
+        return completionToolNamesForDraftGate("draft_proposal");
+    }
     if (isDebugCompletionPhase(phase)) {
         return completionToolNamesForDebugGate(phase);
     }
@@ -176,6 +213,10 @@ export function completionToolNamesForDebugGate(gate) {
     const base = debugGateToolNames[gate];
     return [`forge.${base}`, base];
 }
+export function completionToolNamesForDraftGate(gate) {
+    const base = draftGateToolNames[gate];
+    return [`forge.${base}`, base];
+}
 export function expectedCompletionToolName(phase) {
     return completionToolNamesForPhase(phase)[0];
 }
@@ -185,6 +226,9 @@ export function expectedQaCompletionToolName(gate) {
 export function expectedDebugCompletionToolName(gate) {
     return completionToolNamesForDebugGate(gate)[0];
 }
+export function expectedDraftCompletionToolName(gate) {
+    return completionToolNamesForDraftGate(gate)[0];
+}
 export function artifactRootFor(worktreePath, workItemId) {
     return path.join(worktreePath, ".forge", "work-items", safePathSegment(workItemId, "work item id"), "artifacts");
 }
@@ -219,7 +263,8 @@ export async function prepareCompletionToolRuntime(options) {
         developCycle: usesDevelopCycleCompletion(options.dispatch),
         qaCycle: usesQaCycleCompletion(options.dispatch),
         debugCycle: usesDebugCycleCompletion(options.dispatch),
-        architectCycle: usesArchitectCycleCompletion(options.dispatch)
+        architectCycle: usesArchitectCycleCompletion(options.dispatch),
+        draftCycle: options.dispatch.execution.lane.trim().toLowerCase() === "draft" || options.dispatch.cycleRun.kind.trim().toLowerCase() === "draft"
     });
     const runtime = {
         serverName: toolServerName,
@@ -261,6 +306,9 @@ export function buildCompletionToolServerArgs(config) {
     if (config.architectCycle) {
         args.push("--architect-cycle");
     }
+    if (config.draftCycle) {
+        args.push("--draft-cycle");
+    }
     return args;
 }
 export function codexMcpConfigArgs(runtime) {
@@ -335,6 +383,19 @@ Use \`status: "skipped"\` with a reason for gates that are not applicable. If a
 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 completionPromptForDraftCycle(currentGate = "draft_intent") {
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not finish Draft by prose or raw JSON. The tool server enforces Draft gate order and starts at \`${currentGate}\`.
+Complete the Draft cycle in order inside this same provider session:
+1. Call \`forge.complete_draft_intent(...)\` after interpreting user intent and non-goals.
+2. Follow the returned repo-context instruction, inspect selected project/repo assumptions, then call \`forge.complete_draft_repo_context(...)\`.
+3. Follow the returned graph-context instruction, account for DAG/dependency placement, then call \`forge.complete_draft_graph_context(...)\`.
+4. Follow the returned product-scope instruction, choose product scope for the selected project, then call \`forge.complete_draft_product_scope(...)\`.
+5. Follow the returned work-order-plan instruction, draft Work Order fields and candidate feature boundaries, then call \`forge.complete_draft_work_order_plan(...)\`.
+6. Follow the returned critic instruction, critique literalism, wrong-project scope, and decomposition quality, then call \`forge.complete_draft_critic(...)\`.
+7. Follow the returned proposal instruction, then call \`forge.complete_draft_proposal(...)\` with the final Work Order JSON in \`draft_json\`.
+The final proposal tool writes \`draft.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. Reporting Draft 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}\`.
@@ -347,33 +408,38 @@ Each tool writes a canonical Debug artifact under \`.forge/work-items/{workItemI
 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))
-                : config.architectCycle
-                    ? completionToolNamesForPhase("architect")
-                    : completionToolNamesForPhase(config.phase);
+    return config.draftCycle
+        ? draftCompletionGateOrder.flatMap((gate) => completionToolNamesForDraftGate(gate))
+        : config.debugCycle
+            ? debugCompletionPhaseOrder.flatMap((gate) => completionToolNamesForDebugGate(gate))
+            : config.qaCycle
+                ? qaCompletionGateOrder.flatMap((gate) => completionToolNamesForQaGate(gate))
+                : config.developCycle
+                    ? completionPhaseOrder.flatMap((phase) => completionToolNamesForPhase(phase))
+                    : config.architectCycle
+                        ? completionToolNamesForPhase("architect")
+                        : completionToolNamesForPhase(config.phase);
 }
 export class CompletionToolServerSession {
     config;
     currentPhase;
     currentQaGate = "qa_plan";
+    currentDraftGate = "draft_intent";
     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);
+        return this.config.draftCycle
+            ? completionPromptForDraftCycle(this.currentDraftGate)
+            : 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)));
@@ -383,6 +449,9 @@ export class CompletionToolServerSession {
         if (this.completed) {
             throw new Error("Forge completion cycle is already complete; no more completion calls are accepted.");
         }
+        if (this.config.draftCycle) {
+            return await this.callDraftGateTool(toolName, requestedPhase, input);
+        }
         if (this.config.debugCycle) {
             return await this.callDebugGateTool(toolName, requestedPhase, input);
         }
@@ -423,6 +492,30 @@ export class CompletionToolServerSession {
             }
         };
     }
+    async callDraftGateTool(toolName, requestedPhase, input) {
+        const requestedGate = draftGateFromToolName(toolName);
+        if (requestedPhase !== "draft" || !requestedGate) {
+            throw new Error(`Tool ${toolName} is not available in Draft-cycle mode. Current Forge Draft gate is ${this.currentDraftGate}.`);
+        }
+        if (requestedGate !== this.currentDraftGate) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge Draft gate is ${this.currentDraftGate}.`);
+        }
+        const completedGate = this.currentDraftGate;
+        const reference = await writeDraftGateCompletionArtifact(this.config, completedGate, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const nextGate = this.advanceAfterDraftGate(completedGate);
+        const nextPhase = nextGate ? "draft" : "sign_off_ready";
+        const nextInstruction = completionToolNextInstructionForDraftGate(completedGate, status, nextGate);
+        return {
+            content: [{ type: "text", text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}` }],
+            structuredContent: {
+                ...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
+            }
+        };
+    }
     async callDebugGateTool(toolName, requestedPhase, input) {
         const currentDebugGate = asDebugCompletionPhase(this.currentPhase);
         if (!isDebugCompletionPhase(requestedPhase)) {
@@ -519,6 +612,16 @@ export class CompletionToolServerSession {
         this.completed = true;
         return "dev_test_ready";
     }
+    advanceAfterDraftGate(gate) {
+        const index = draftCompletionGateOrder.indexOf(gate);
+        const next = index >= 0 ? draftCompletionGateOrder[index + 1] ?? null : null;
+        if (next) {
+            this.currentDraftGate = next;
+            return next;
+        }
+        this.completed = true;
+        return null;
+    }
     advanceAfterQaGate(gate) {
         const index = qaCompletionGateOrder.indexOf(gate);
         const next = index >= 0 ? qaCompletionGateOrder[index + 1] ?? null : null;
@@ -540,6 +643,43 @@ export class CompletionToolServerSession {
         return null;
     }
 }
+async function writeDraftGateCompletionArtifact(config, gate, toolName, input) {
+    const payload = asRecord(input, "Draft completion payload");
+    const status = normalizeDraftStatus(optionalString(payload, "status") ?? "pass");
+    if (gate === "draft_proposal") {
+        const draftJson = asRecord(payload["draft_json"], "draft_json");
+        for (const key of ["title", "summary", "objective", "planningPacket", "decompositionContext"]) {
+            if (typeof draftJson[key] !== "string" || draftJson[key].trim().length === 0) {
+                throw new Error(`draft_json.${key}: expected non-empty string`);
+            }
+        }
+    }
+    const redactedPayload = redactSecrets({ ...payload, status, phase: "draft", gate, tool_name: toolName }, config.redactionSecrets ?? []);
+    const root = artifactRootFor(config.worktreePath, config.workItemId);
+    await fs.mkdir(root, { recursive: true });
+    const artifactPath = path.join(root, draftGateFileNames[gate]);
+    const reportPath = gate === "draft_proposal" ? path.join(root, phaseFiles.draft.reportFileName) : path.join(root, `${gate}.md`);
+    const verdictJson = jsonText(redactedPayload);
+    const report = optionalString(redactedPayload, "report_markdown") ?? `# ${gate.replace(/_/g, " ")}\n\n${optionalString(redactedPayload, "summary") ?? "Draft gate recorded."}\n`;
+    await writeFileAtomic(artifactPath, verdictJson);
+    await writeFileAtomic(reportPath, report);
+    return {
+        phase: "draft",
+        workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
+        repoPath: path.resolve(config.worktreePath),
+        path: artifactPath,
+        reportPath,
+        contentHash: sha256(verdictJson),
+        status,
+        producedBy: config.producedBy ?? "forge-completion-tool"
+    };
+}
+function normalizeDraftStatus(value) {
+    const normalized = value.trim().toLowerCase();
+    return normalized === "blocked" || normalized === "needs_revision" || normalized === "needs_rework" ? normalized : "pass";
+}
 export async function writeCompletionArtifact(config, toolName, input) {
     const phase = phaseFromToolName(toolName);
     if (phase !== config.phase) {
@@ -1037,6 +1177,7 @@ export function parseCompletionMcpArgs(argv) {
     let qaCycle = false;
     let debugCycle = false;
     let architectCycle = false;
+    let draftCycle = false;
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === "--worktree") {
@@ -1058,7 +1199,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, 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, debug-repro, debug-root-cause, debug-fix, debug-regression." };
             }
             phase = parsedPhase;
         }
@@ -1077,6 +1218,9 @@ export function parseCompletionMcpArgs(argv) {
         else if (arg === "--architect-cycle") {
             architectCycle = true;
         }
+        else if (arg === "--draft-cycle") {
+            draftCycle = true;
+        }
         else {
             return { ok: false, error: `Unknown mcp argument: ${arg}` };
         }
@@ -1084,7 +1228,7 @@ export function parseCompletionMcpArgs(argv) {
     if (!worktreePath?.trim() || !workItemId?.trim()) {
         return { ok: false, error: "mcp requires --worktree and --work-item-id." };
     }
-    if ([developCycle, qaCycle, debugCycle, architectCycle].filter(Boolean).length > 1) {
+    if ([developCycle, qaCycle, debugCycle, architectCycle, draftCycle].filter(Boolean).length > 1) {
         return { ok: false, error: "mcp accepts only one cycle mode." };
     }
     if (developCycle && !isDevelopCompletionPhase(phase)) {
@@ -1099,6 +1243,9 @@ export function parseCompletionMcpArgs(argv) {
     if (architectCycle && phase !== "architect") {
         return { ok: false, error: "mcp --architect-cycle requires --phase architect." };
     }
+    if (draftCycle && phase !== "draft") {
+        return { ok: false, error: "mcp --draft-cycle requires --phase draft." };
+    }
     return {
         ok: true,
         config: {
@@ -1112,7 +1259,8 @@ export function parseCompletionMcpArgs(argv) {
             developCycle,
             qaCycle,
             debugCycle,
-            architectCycle
+            architectCycle,
+            draftCycle
         }
     };
 }
@@ -1250,6 +1398,24 @@ function completionToolNextInstruction(completedPhase, status, nextPhase) {
     }
     return "Validation accepted. Forge has the structured evidence needed to move this work item to QA.";
 }
+function completionToolNextInstructionForDraftGate(completedGate, status, nextGate) {
+    if (status === "blocked") {
+        return `Stay in ${completedGate}; record the blocker and retry the same Draft gate when unblocked.`;
+    }
+    if (!nextGate) {
+        return "Draft proposal accepted. Forge has the structured Work Order draft JSON needed to populate the form.";
+    }
+    const instructions = {
+        draft_intent: "Capture intent/non-goals, then call forge.complete_draft_intent.",
+        draft_repo_context: "Inspect selected repo/project assumptions, then call forge.complete_draft_repo_context.",
+        draft_graph_context: "Account for DAG dependencies and placement, then call forge.complete_draft_graph_context.",
+        draft_product_scope: "Choose product scope for the selected project, then call forge.complete_draft_product_scope.",
+        draft_work_order_plan: "Draft Work Order fields and candidate Feature boundaries, then call forge.complete_draft_work_order_plan.",
+        draft_critic: "Critique literalism/wrong-project scope/decomposition risk, then call forge.complete_draft_critic.",
+        draft_proposal: "Submit final draft_json through forge.complete_draft_proposal."
+    };
+    return `${completedGate} accepted. Continue to ${nextGate}. ${instructions[nextGate]}`;
+}
 function completionToolNextInstructionForQaGate(completedGate, status, nextGate) {
     if (!nextGate) {
         if (status === "blocked") {
@@ -2529,6 +2695,9 @@ function parseStrictCompletionPhase(value) {
     if (normalized === "architect" || normalized === "architect_plan" || normalized === "planning" || normalized === "plan") {
         return "architect";
     }
+    if (normalized === "draft" || normalized === "drafting" || normalized === "draft_work_order") {
+        return "draft";
+    }
     return null;
 }
 function normalizeDebugCompletionPhase(value) {
@@ -2600,6 +2769,9 @@ function phaseFromToolName(toolName) {
     if (normalized === "forge.complete_architect_plan" || normalized === "complete_architect_plan") {
         return "architect";
     }
+    if (draftGateFromToolName(toolName)) {
+        return "draft";
+    }
     const debugGate = debugGateFromToolName(toolName);
     if (debugGate) {
         return debugGate;
@@ -2609,6 +2781,16 @@ function phaseFromToolName(toolName) {
     }
     throw new Error(`Unknown Forge completion tool: ${toolName}`);
 }
+function draftGateFromToolName(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    for (const gate of draftCompletionGateOrder) {
+        const base = draftGateToolNames[gate];
+        if (normalized === `forge.${base}` || normalized === base) {
+            return gate;
+        }
+    }
+    return null;
+}
 function debugGateFromToolName(toolName) {
     const normalized = toolName.trim().toLowerCase();
     for (const gate of debugCompletionPhaseOrder) {

package/dist/session/provider-cli/provider-cli.service.js

@@ -9,7 +9,7 @@ import { GitClient } from "../../shared/git/git.js";
 import { resolveCursorAgentDirectLaunch } from "../../shared/cursor-agent/cursor-agent.launch.js";
 import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "../qa-sidecar-validation.js";
 import { buildSpecBody, selectLaneCommand } from "../../worktree/artifact-injector.js";
-import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDebugCycle, completionPromptForDevelopCycle, completionPromptForPhase, completionPromptForQaCycle, completionRedactionEnv, expectedCompletionToolName, expectedDebugCompletionToolName, expectedQaCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDebugCycleCompletion, usesDevelopCycleCompletion, writeCompletionArtifact, artifactRootFor, artifactRootForOwner, debugCompletionPhaseOrder, qaCompletionGateOrder } from "../phase-completion.js";
+import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDebugCycle, completionPromptForDevelopCycle, completionPromptForDraftCycle, completionPromptForPhase, completionPromptForQaCycle, completionRedactionEnv, expectedCompletionToolName, expectedDebugCompletionToolName, expectedQaCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDebugCycleCompletion, usesDevelopCycleCompletion, writeCompletionArtifact, artifactRootFor, artifactRootForOwner, debugCompletionPhaseOrder, draftCompletionGateOrder, qaCompletionGateOrder } from "../phase-completion.js";
 import { addUsage, buildProviderUsageEvent, emptyUsage, hasUsage, readUsageNumber } from "./provider-usage.js";
 const fakeWorkerModel = "server-local-fake-worker";
 const execFileAsync = promisify(execFile);
@@ -189,17 +189,45 @@ export class ProcessBackedProviderCliService {
             throw new Error("Draft dispatch context is missing.");
         }
         const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "forge-bridge-draft-"));
+        const draftWorktree = {
+            repoPath: tempDir,
+            worktreePath: tempDir,
+            branchName: "draft",
+            baseBranch: dispatch.cycleRun.baseBranch || dispatch.repo.defaultBranch || "draft",
+            cleanupWorktrees: true
+        };
+        const metadataRoot = path.join(tempDir, ".forge", "work-items", dispatch.workItem.id);
+        await fs.mkdir(metadataRoot, { recursive: true });
+        await fs.writeFile(path.join(metadataRoot, "draft-input.json"), JSON.stringify(dispatch.draft, null, 2) + "\n", "utf8");
+        await fs.writeFile(path.join(metadataRoot, "spec.md"), buildDraftSpec(dispatch), "utf8");
+        const completionTools = await prepareCompletionToolRuntime({ dispatch, worktree: draftWorktree, phase: "draft" });
         const command = buildProviderCliCommand(dispatch, {
             worktreePath: tempDir,
             prompt: buildDraftPrompt(dispatch),
+            completionTools,
             skipGitRepoCheck: true
         });
+        const draftArtifactSlugs = dispatch.artifacts
+            .filter((artifact) => artifact.scope === "operational" && ["command", "skill", "hook"].includes(artifact.kind))
+            .map((artifact) => `${artifact.kind}:${artifact.slug}`);
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Draft artifacts injected: ${draftArtifactSlugs.length}${draftArtifactSlugs.length ? ` (${draftArtifactSlugs.join(", ")})` : ""}. Project: ${dispatch.draft.projectName ?? dispatch.repo.name}. Repo: ${dispatch.draft.repoName ?? dispatch.repo.name}.`,
+            eventType: "draft_artifacts_injected"
+        });
         await context.emit({
             role: "runner",
             kind: "checkpoint",
             content: `Starting provider CLI Draft: ${formatProviderCliCommand(command)}`,
             eventType: "provider_cli_started"
         });
+        await context.emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: "Forge Draft completion tools configured for draft_intent -> draft_repo_context -> draft_graph_context -> draft_product_scope -> draft_work_order_plan -> draft_critic -> draft_proposal; provider must call each MCP completion tool before exit.",
+            eventType: "completion_tools_configured"
+        });
         const outputState = createProviderOutputState(dispatch.execution.provider);
         try {
             const result = await this.processRunner.run({
@@ -217,23 +245,38 @@ export class ProcessBackedProviderCliService {
             if (result.exitCode !== 0) {
                 throw new Error(`Provider CLI exited with code ${result.exitCode}${summarizeStderr(result.stderr)}.`);
             }
-            const content = outputState.finalMessage ?? result.stdout.trim();
-            if (!content) {
-                throw new Error("Provider CLI completed without returning a draft.");
+            await context.emit({
+                role: "runner",
+                kind: "checkpoint",
+                content: `Provider CLI Draft completed: ${command.command} exit ${result.exitCode}${outputState.sessionLabel ? ` ${outputState.sessionLabel}` : ""}.`,
+                eventType: "provider_cli_completed"
+            });
+            await emitProviderUsageEvent(context.emit, dispatch, outputState);
+            await emitDraftGateArtifacts(context.emit, tempDir, dispatch.workItem.id);
+            const proposalArtifact = await readCompletionArtifact(tempDir, dispatch.workItem.id, "draft");
+            if (!proposalArtifact) {
+                throw new Error("Provider CLI Draft completed but did not call forge.complete_draft_proposal.");
+            }
+            const proposal = parseJsonLine(proposalArtifact.verdictJson) ?? {};
+            const draftJson = proposal["draft_json"];
+            if (!draftJson || typeof draftJson !== "object" || Array.isArray(draftJson)) {
+                throw new Error("Provider CLI Draft completed but draft.proposal.json did not contain draft_json.");
             }
-            const json = extractJsonObject(content);
+            const json = JSON.stringify(draftJson);
             await context.emit({
                 role: "assistant",
                 kind: "message",
                 content: json,
                 eventType: "draft_complete"
             });
-            await emitProviderUsageEvent(context.emit, dispatch, outputState);
             return {
-                summary: "Draft generated through Forge Runner."
+                summary: "Draft generated through Forge Draft completion cycle.",
+                artifact: proposalArtifact,
+                artifacts: [proposalArtifact]
             };
         }
         finally {
+            await cleanupCompletionTools(completionTools, context.emit);
             await fs.rm(tempDir, { recursive: true, force: true });
         }
     }
@@ -1900,6 +1943,67 @@ function isFakeWorkerModel(model) {
 function sha256(content) {
     return crypto.createHash("sha256").update(content).digest("hex");
 }
+function buildDraftSpec(dispatch) {
+    return `# Draft Generation Context
+
+Project: ${dispatch.draft?.projectName ?? dispatch.repo.name}
+Repository: ${dispatch.draft?.repoName ?? dispatch.repo.name}
+Draft kind: ${dispatch.draft?.kind ?? "draft"}
+
+## User Prompt
+
+${dispatch.draft?.userPrompt ?? ""}
+`;
+}
+async function emitDraftGateArtifacts(emit, worktreePath, workItemId) {
+    const draftArtifactFiles = {
+        draft_intent: "draft.intent.json",
+        draft_repo_context: "draft.repo-context.json",
+        draft_graph_context: "draft.graph-context.json",
+        draft_product_scope: "draft.product-scope.json",
+        draft_work_order_plan: "draft.work-order-plan.json",
+        draft_critic: "draft.critic.json",
+        draft_proposal: "draft.proposal.json"
+    };
+    for (const gate of draftCompletionGateOrder) {
+        const actualPath = path.join(worktreePath, ".forge", "work-items", workItemId, "artifacts", draftArtifactFiles[gate]);
+        if (!await fileExists(actualPath)) {
+            continue;
+        }
+        const relativePath = path.relative(worktreePath, actualPath).split(path.sep).join("/");
+        await emit({
+            role: "tool",
+            kind: "tool_result",
+            content: `Forge Draft completion tool recorded ${gate} artifact ${relativePath}.`,
+            eventType: "completion_tool_artifact_recorded",
+            data: JSON.stringify({ phase: "draft", draft_gate: gate, artifact_relative_paths: [relativePath] })
+        });
+        await emit({
+            role: "hook",
+            kind: "checkpoint",
+            content: `phase_gate: ${gate} artifact accepted with status pass.`,
+            eventType: "phase_gate"
+        });
+        const next = draftCompletionGateOrder[draftCompletionGateOrder.indexOf(gate) + 1];
+        if (next) {
+            await emit({
+                role: "hook",
+                kind: "checkpoint",
+                content: `phase_progression: ${gate} -> ${next}`,
+                eventType: "phase_gate"
+            });
+        }
+    }
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function buildDraftPrompt(dispatch) {
     const draft = dispatch.draft;
     if (!draft) {
@@ -1912,13 +2016,22 @@ function buildDraftPrompt(dispatch) {
     const artifactSection = draftArtifacts
         ? `\n\n# Injected Draft command/skills/hooks\n\n${draftArtifacts}`
         : "";
-    return `${draft.systemPrompt}${artifactSection}
+    const projectSection = [
+        draft.projectName ? `Project: ${draft.projectName}` : null,
+        draft.repoName ? `Repository: ${draft.repoName}` : null
+    ].filter(Boolean).join("\n");
+    const scopedProjectSection = projectSection ? `\n\n# Selected project context\n\n${projectSection}` : "";
+    return `${draft.systemPrompt}${scopedProjectSection}${artifactSection}
 
 Draft kind: ${draft.kind}
 
 ${draft.userPrompt}
 
-Return ONLY the requested JSON object. Do not wrap it in markdown and do not modify files.`;
+${completionPromptForDraftCycle("draft_intent")}
+
+Use the injected command/skills/hooks as lane instructions. You must call each Forge Draft MCP completion tool in order. Do not claim the Draft is complete until forge.complete_draft_proposal accepts the final draft_json.
+
+Do not modify source files.`;
 }
 function extractJsonObject(content) {
     let trimmed = content.trim();

package/dist/session/session.types.d.ts

@@ -23,6 +23,8 @@ export interface DispatchDraftPrompt {
     readonly kind: string;
     readonly systemPrompt: string;
     readonly userPrompt: string;
+    readonly projectName?: string | null;
+    readonly repoName?: string | null;
 }
 export interface DispatchQaBrowserContext {
     readonly required: boolean;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.1-dev.40fbc494669b";
+export declare const forgeBridgeVersion = "0.1.1-dev.5093acd6bece";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.1-dev.40fbc494669b";
+export const forgeBridgeVersion = "0.1.1-dev.5093acd6bece";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loucompanion/forge-bridge",
-  "version": "0.1.1-dev.40fbc494669b",
+  "version": "0.1.1-dev.5093acd6bece",
   "description": "Forge runner bridge CLI for connecting local developer machines to Forge dispatch.",
   "license": "UNLICENSED",
   "type": "module",