@loucompanion/forge-bridge 0.1.1-dev.f599637d804e → 0.1.3-dev.2c3feac3af65

package/dist/session/phase-completion.js

@@ -22,6 +22,60 @@ 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"
+];
+export const decomposeCompletionGateOrder = [
+    "decompose_subject_intake",
+    "decompose_context_review",
+    "decompose_breakdown_strategy",
+    "decompose_child_items",
+    "decompose_dependency_graph",
+    "decompose_critic",
+    "decompose_proposal"
+];
+const decomposeGateFileNames = {
+    decompose_subject_intake: "decompose.subject-intake.json",
+    decompose_context_review: "decompose.context-review.json",
+    decompose_breakdown_strategy: "decompose.breakdown-strategy.json",
+    decompose_child_items: "decompose.child-items.json",
+    decompose_dependency_graph: "decompose.dependency-graph.json",
+    decompose_critic: "decompose.critic.json",
+    decompose_proposal: "decompose.proposal.json"
+};
+const decomposeGateToolNames = {
+    decompose_subject_intake: "complete_decompose_subject_intake",
+    decompose_context_review: "complete_decompose_context_review",
+    decompose_breakdown_strategy: "complete_decompose_breakdown_strategy",
+    decompose_child_items: "complete_decompose_child_items",
+    decompose_dependency_graph: "complete_decompose_dependency_graph",
+    decompose_critic: "complete_decompose_critic",
+    decompose_proposal: "complete_decompose_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",
@@ -59,6 +113,44 @@ const resolvedFindingStatuses = new Set(resolvedFindingStatusValues);
 const qaFindingSeverities = new Set(["critical", "major", "minor"]);
 const qaFindingScopes = new Set(["in_scope", "out_of_scope", "unclear"]);
 const qaCandidateBugActions = new Set(["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"]);
+const qaScopeSurfaces = new Set([
+    "domain_contract",
+    "backend_persistence",
+    "api_route",
+    "ui_browser",
+    "infra_config",
+    "data_migration",
+    "test_only",
+    "documentation"
+]);
+const qaScopeEvidence = new Set([
+    "release_build",
+    "unit_tests",
+    "console_harness",
+    "source_scope_review",
+    "api_http",
+    "browser_manual",
+    "migration_check",
+    "config_check"
+]);
+const qaScopeSources = new Set(["user", "draft", "decompose", "architect", "heuristic", "system"]);
+const qaScopeAuthorities = new Set(["user", "decompose", "architect", "system"]);
+const qaScopeConfidence = new Set(["explicit", "inferred"]);
+const qaScopeFields = new Set([
+    "schema_version",
+    "surface",
+    "required_evidence",
+    "not_applicable",
+    "browser_required",
+    "api_required",
+    "source",
+    "authority",
+    "confidence",
+    "confirmed_by_user",
+    "locked",
+    "derived_from",
+    "rationale"
+]);
 const phaseFiles = {
     implementation: {
         jsonFileName: "implementation.completeness.json",
@@ -95,6 +187,14 @@ const phaseFiles = {
     architect: {
         jsonFileName: "architect.verdict.json",
         reportFileName: "architect.report.md"
+    },
+    draft: {
+        jsonFileName: "draft.proposal.json",
+        reportFileName: "draft.report.md"
+    },
+    decompose: {
+        jsonFileName: "decompose.proposal.json",
+        reportFileName: "decompose.report.md"
     }
 };
 export function completionPhaseFromDispatch(dispatch) {
@@ -118,6 +218,12 @@ 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";
+    }
+    if (normalized === "decompose" || normalized === "decomposition" || normalized === "work_order_decomposition" || normalized === "feature_decomposition") {
+        return "decompose";
+    }
     return "implementation";
 }
 export function usesDevelopCycleCompletion(dispatch) {
@@ -154,6 +260,12 @@ export function usesArchitectCycleCompletion(dispatch) {
     return kind === "architect" || role === "architect" || lane === "architect";
 }
 export function completionToolNamesForPhase(phase) {
+    if (phase === "draft") {
+        return completionToolNamesForDraftGate("draft_proposal");
+    }
+    if (phase === "decompose") {
+        return completionToolNamesForDecomposeGate("decompose_proposal");
+    }
     if (isDebugCompletionPhase(phase)) {
         return completionToolNamesForDebugGate(phase);
     }
@@ -176,6 +288,14 @@ 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 completionToolNamesForDecomposeGate(gate) {
+    const base = decomposeGateToolNames[gate];
+    return [`forge.${base}`, base];
+}
 export function expectedCompletionToolName(phase) {
     return completionToolNamesForPhase(phase)[0];
 }
@@ -185,6 +305,12 @@ export function expectedQaCompletionToolName(gate) {
 export function expectedDebugCompletionToolName(gate) {
     return completionToolNamesForDebugGate(gate)[0];
 }
+export function expectedDraftCompletionToolName(gate) {
+    return completionToolNamesForDraftGate(gate)[0];
+}
+export function expectedDecomposeCompletionToolName(gate) {
+    return completionToolNamesForDecomposeGate(gate)[0];
+}
 export function artifactRootFor(worktreePath, workItemId) {
     return path.join(worktreePath, ".forge", "work-items", safePathSegment(workItemId, "work item id"), "artifacts");
 }
@@ -219,7 +345,12 @@ 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: (phase === "draft"
+            || options.dispatch.execution.lane.trim().toLowerCase() === "draft"
+            || options.dispatch.cycleRun.kind.trim().toLowerCase() === "draft")
+            && !isDecomposeDispatch(options.dispatch),
+        decomposeCycle: isDecomposeDispatch(options.dispatch)
     });
     const runtime = {
         serverName: toolServerName,
@@ -261,6 +392,12 @@ export function buildCompletionToolServerArgs(config) {
     if (config.architectCycle) {
         args.push("--architect-cycle");
     }
+    if (config.draftCycle) {
+        args.push("--draft-cycle");
+    }
+    if (config.decomposeCycle) {
+        args.push("--decompose-cycle");
+    }
     return args;
 }
 export function codexMcpConfigArgs(runtime) {
@@ -292,6 +429,7 @@ export function completionPromptForPhase(phase) {
 Do not write QA artifacts by hand. When QA is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required structured QA payload.
 That tool writes the durable QA bundle under \`.forge/work-items/{workItemId}/artifacts/\`: \`qa.plan.json\`, \`qa.evidence.json\`, \`qa.findings.json\`, \`${artifactName}\`, and \`qa.report.md\`.
 Use \`status: "pass"\` only when the validated changes satisfy acceptance criteria with concrete evidence. Use \`status: "needs_rework"\` with actionable in-scope findings, or \`status: "blocked"\` with a concrete blocker_reason.
+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.`;
     }
     if (phase === "architect") {
@@ -299,7 +437,8 @@ 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", "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"], "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.
 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.`;
@@ -332,8 +471,38 @@ Complete the QA cycle in order inside this same provider session:
 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\`.
+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.`;
 }
+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 draft-plan instruction, draft the requested final JSON shape for the current Draft kind, 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 Draft JSON payload 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 completionPromptForDecomposeCycle(currentGate = "decompose_subject_intake") {
+    return `# Forge Decompose completion cycle
+You must complete the Decompose gates in order using the Forge MCP tools. Reporting progress in prose is not enough.
+
+Current gate: ${currentGate}
+
+Required order:
+1. Call \`forge.complete_decompose_subject_intake(...)\` after identifying the Work Order/Feature subject, scope, and non-goals.
+2. Follow the returned context-review instruction, inspect injected project/repo/dependency context, then call \`forge.complete_decompose_context_review(...)\`.
+3. Follow the returned breakdown-strategy instruction, choose safe Feature/Story boundaries, then call \`forge.complete_decompose_breakdown_strategy(...)\`.
+4. Follow the returned child-items instruction, draft candidate child items, then call \`forge.complete_decompose_child_items(...)\`.
+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.`;
+}
 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}\`.
@@ -346,42 +515,58 @@ 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.decomposeCycle
+        ? decomposeCompletionGateOrder.flatMap((gate) => completionToolNamesForDecomposeGate(gate))
+        : 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";
+    currentDecomposeGate = "decompose_subject_intake";
     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.decomposeCycle
+            ? completionPromptForDecomposeCycle(this.currentDecomposeGate)
+            : 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)));
+        return completionToolNamesForServer(this.config).map((name) => toolDefinition(name, phaseFromToolName(name), qaGateFromToolName(name), decomposeGateFromToolName(name)));
     }
     async callTool(toolName, input) {
         const requestedPhase = phaseFromToolName(toolName);
         if (this.completed) {
             throw new Error("Forge completion cycle is already complete; no more completion calls are accepted.");
         }
+        if (this.config.decomposeCycle) {
+            return await this.callDecomposeGateTool(toolName, requestedPhase, input);
+        }
+        if (this.config.draftCycle) {
+            return await this.callDraftGateTool(toolName, requestedPhase, input);
+        }
         if (this.config.debugCycle) {
             return await this.callDebugGateTool(toolName, requestedPhase, input);
         }
@@ -422,6 +607,62 @@ export class CompletionToolServerSession {
             }
         };
     }
+    async callDecomposeGateTool(toolName, requestedPhase, input) {
+        const requestedGate = decomposeGateFromToolName(toolName);
+        if (requestedPhase !== "decompose" || !requestedGate) {
+            throw new Error(`Tool ${toolName} is not available in Decompose-cycle mode. Current Forge Decompose gate is ${this.currentDecomposeGate}.`);
+        }
+        if (requestedGate !== this.currentDecomposeGate) {
+            throw new Error(`Tool ${toolName} is out of order. Current Forge Decompose gate is ${this.currentDecomposeGate}.`);
+        }
+        const completedGate = this.currentDecomposeGate;
+        const reference = await writeDecomposeGateCompletionArtifact(this.config, completedGate, toolName, input);
+        const status = reference.status.trim().toLowerCase();
+        const pass = status === "pass";
+        const nextGate = pass ? this.advanceAfterDecomposeGate(completedGate) : completedGate;
+        const nextPhase = pass
+            ? (nextGate ? "decompose" : "sign_off_ready")
+            : "decompose";
+        const nextInstruction = completionToolNextInstructionForDecomposeGate(completedGate, status, nextGate);
+        const reason = pass
+            ? nextGate
+                ? `${completedGate} artifact accepted; continue to ${nextGate}.`
+                : `Decompose proposal artifact accepted with status ${status}.`
+            : `${completedGate} artifact recorded with status ${status}; rework is required before continuing.`;
+        return {
+            content: [{ type: "text", text: `Forge recorded ${completedGate} artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}). ${nextInstruction}` }],
+            structuredContent: {
+                ...reference,
+                gate: { phase: "decompose", decomposeGate: completedGate, status, allowed: pass, reason },
+                nextPhase,
+                nextInstruction
+            }
+        };
+    }
+    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)) {
@@ -518,6 +759,26 @@ export class CompletionToolServerSession {
         this.completed = true;
         return "dev_test_ready";
     }
+    advanceAfterDecomposeGate(gate) {
+        const index = decomposeCompletionGateOrder.indexOf(gate);
+        const next = index >= 0 ? decomposeCompletionGateOrder[index + 1] ?? null : null;
+        if (next) {
+            this.currentDecomposeGate = next;
+            return next;
+        }
+        this.completed = true;
+        return null;
+    }
+    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;
@@ -539,6 +800,132 @@ export class CompletionToolServerSession {
         return null;
     }
 }
+async function writeDecomposeGateCompletionArtifact(config, gate, toolName, input) {
+    const payload = asRecord(input, "Decompose completion payload");
+    const status = normalizeDraftStatus(optionalString(payload, "status") ?? "pass");
+    if (gate === "decompose_proposal") {
+        const proposalJson = asRecord(payload["proposal_json"] ?? payload["decomposition_json"], "proposal_json");
+        validateDecomposeProposalJson(proposalJson);
+    }
+    const redactedPayload = redactSecrets({ ...payload, status, phase: "decompose", gate, tool_name: toolName }, config.redactionSecrets ?? []);
+    const root = artifactRootFor(config.worktreePath, config.workItemId);
+    await fs.mkdir(root, { recursive: true });
+    const artifactPath = path.join(root, decomposeGateFileNames[gate]);
+    const reportPath = gate === "decompose_proposal" ? path.join(root, phaseFiles.decompose.reportFileName) : path.join(root, `${gate}.md`);
+    const verdictJson = jsonText(redactedPayload);
+    const report = optionalString(redactedPayload, "report_markdown") ?? `# ${gate.replace(/_/g, " ")}
+
+${optionalString(redactedPayload, "summary") ?? "Decompose gate recorded."}
+`;
+    await writeFileAtomic(artifactPath, verdictJson);
+    await writeFileAtomic(reportPath, report);
+    return {
+        phase: "decompose",
+        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"
+    };
+}
+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");
+        validateDraftProposalJson(draftJson);
+    }
+    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";
+}
+function validateDraftProposalJson(draftJson) {
+    if (draftJson.suggested_qa_scope !== undefined && draftJson.suggested_qa_scope !== null) {
+        if (!draftJson.suggested_qa_scope || typeof draftJson.suggested_qa_scope !== "object" || Array.isArray(draftJson.suggested_qa_scope)) {
+            throw new Error("draft_json.suggested_qa_scope: expected object when present.");
+        }
+        validateQaScopeRecord(draftJson.suggested_qa_scope, "draft_json.suggested_qa_scope");
+    }
+    if (isDecompositionDraftJson(draftJson)) {
+        return;
+    }
+    if (isWorkItemDraftJson(draftJson)) {
+        for (const key of ["title", "description", "acceptanceCriteria"]) {
+            if (typeof draftJson[key] !== "string" || draftJson[key].trim().length === 0) {
+                throw new Error(`draft_json.${key}: expected non-empty string`);
+            }
+        }
+        return;
+    }
+    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`);
+        }
+    }
+}
+function isDecompositionDraftJson(draftJson) {
+    const summary = draftJson["summary"];
+    return typeof summary === "string"
+        && summary.trim().length > 0
+        && Array.isArray(draftJson["candidates"]);
+}
+function isWorkItemDraftJson(draftJson) {
+    return typeof draftJson.title === "string"
+        && typeof draftJson.description === "string"
+        && typeof draftJson.acceptanceCriteria === "string";
+}
+function validateDecomposeProposalJson(proposalJson) {
+    const candidates = proposalJson.candidates;
+    if (!Array.isArray(candidates)) {
+        throw new Error("proposal_json.candidates: expected array");
+    }
+    for (const [index, candidate] of candidates.entries()) {
+        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+            throw new Error(`proposal_json.candidates[${index}]: expected object.`);
+        }
+        const record = candidate;
+        validateOptionalCandidateQaScope(record, "estimated_qa_scope", `proposal_json.candidates[${index}].estimated_qa_scope`);
+        validateOptionalCandidateQaScope(record, "estimatedQaScope", `proposal_json.candidates[${index}].estimatedQaScope`);
+        validateOptionalCandidateQaScope(record, "qa_scope", `proposal_json.candidates[${index}].qa_scope`);
+        validateOptionalCandidateQaScope(record, "qaScope", `proposal_json.candidates[${index}].qaScope`);
+    }
+}
+function validateOptionalCandidateQaScope(candidate, key, pathLabel) {
+    const value = candidate[key];
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${pathLabel}: expected object when present.`);
+    }
+    validateQaScopeRecord(value, pathLabel);
+}
 export async function writeCompletionArtifact(config, toolName, input) {
     const phase = phaseFromToolName(toolName);
     if (phase !== config.phase) {
@@ -550,7 +937,10 @@ export async function writeCompletionArtifact(config, toolName, input) {
     }
     const payload = asRecord(input, "completion payload");
     const status = normalizeCompletionStatus(requiredString(payload, "status"), phase);
-    const validationPayload = { ...payload, status };
+    let validationPayload = { ...payload, status };
+    if (config.qaCycle && qaGate === "qa_verdict") {
+        validationPayload = await synthesizeQaCycleVerdictPayload(config, validationPayload, status);
+    }
     validatePayloadShape(phase, validationPayload);
     validateOptionalWorkItemId(validationPayload, config.workItemId);
     const redactedPayload = redactSecrets(validationPayload, config.redactionSecrets ?? []);
@@ -711,6 +1101,7 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
     const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
     const explicitFindingIds = qaStringArray(payload, "finding_ids");
     const explicitCandidateBugIds = qaStringArray(payload, "candidate_bug_ids");
+    const policyWarnings = qaPolicyWarnings(payload);
     const blockerReason = optionalString(payload, "blocker_reason");
     const checklist = qaStringArray(payload, "checklist");
     const planJson = jsonText({
@@ -758,6 +1149,7 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
         tested_acceptance_criteria: testedAcceptanceCriteria,
         finding_ids: findingIds,
         candidate_bug_ids: candidateBugIds,
+        policy_warnings: policyWarnings,
         blocker_reason: status === "blocked" ? normalizedString(blockerReason) : null,
         evidence_path: relativeEvidencePath,
         findings_path: relativeFindingsPath,
@@ -793,6 +1185,133 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
         producedBy
     };
 }
+async function synthesizeQaCycleVerdictPayload(config, payload, status) {
+    const qaPlan = await readQaGateArtifact(config, "qa_plan");
+    const qaRegression = await readQaGateArtifact(config, "qa_regression");
+    const qaApi = await readQaGateArtifact(config, "qa_api");
+    const qaManualWeb = await readQaGateArtifact(config, "qa_manual_web");
+    const qaBugRepro = await readQaGateArtifact(config, "qa_bug_repro");
+    const qaFindings = await readQaGateArtifact(config, "qa_findings");
+    const evidenceGates = [qaRegression, qaApi, qaManualWeb, qaBugRepro];
+    const payloadEvidence = qaEvidenceSource(payload);
+    const merged = { ...payload };
+    const checklist = qaStringArray(payload, "checklist");
+    if (checklist.length === 0) {
+        const plannedChecklist = qaStringArray(qaPlan, "checklist");
+        merged.checklist = plannedChecklist.length > 0 ? plannedChecklist : defaultQaChecklist(status);
+    }
+    const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
+    if (testedAcceptanceCriteria.length === 0) {
+        const plannedAcceptanceCriteria = qaStringArray(qaPlan, "acceptance_criteria");
+        const payloadAcceptanceCriteria = qaStringArray(payload, "acceptance_criteria");
+        const acceptanceCriteria = plannedAcceptanceCriteria.length > 0 ? plannedAcceptanceCriteria : payloadAcceptanceCriteria;
+        if (acceptanceCriteria.length > 0) {
+            merged.tested_acceptance_criteria = acceptanceCriteria;
+        }
+    }
+    const payloadCommands = qaArray(payload, "commands", payloadEvidence);
+    const inheritedCommands = evidenceGates.flatMap((gate) => qaArray(gate, "commands"));
+    const inheritedDiagnosticCommandNotes = status === "pass"
+        ? qaNonPassingCommandNotes(inheritedCommands)
+        : [];
+    merged.commands = dedupeUnknownArray([
+        ...payloadCommands,
+        ...(status === "pass" ? inheritedCommands.filter(isQaPassingCommandEvidence) : inheritedCommands)
+    ]);
+    merged.browser_checks = dedupeUnknownArray([
+        ...qaArray(payload, "browser_checks", payloadEvidence),
+        ...evidenceGates.flatMap((gate) => qaArray(gate, "browser_checks"))
+    ]);
+    merged.sidecars = dedupeUnknownArray([
+        ...qaArray(payload, "sidecars", payloadEvidence),
+        ...evidenceGates.flatMap((gate) => qaArray(gate, "sidecars"))
+    ]);
+    const notes = dedupeStrings([
+        optionalString(payload, "notes"),
+        optionalString(payloadEvidence, "notes"),
+        ...evidenceGates.map((gate) => optionalString(gate, "notes")),
+        ...inheritedDiagnosticCommandNotes
+    ]);
+    if (notes.length > 0) {
+        merged.notes = notes.join("\n");
+    }
+    merged.findings = mergeQaObjectArraysById(qaObjectArray(payload, "findings"), qaObjectArray(qaFindings, "findings"));
+    merged.candidate_bugs = mergeQaObjectArraysById(qaObjectArray(payload, "candidate_bugs"), qaObjectArray(qaFindings, "candidate_bugs"));
+    return merged;
+}
+async function readQaGateArtifact(config, gate) {
+    const ownerFields = artifactOwnerFields(config);
+    const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
+        ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
+        : artifactRootFor(config.worktreePath, config.workItemId);
+    const artifactPath = path.join(artifactRoot, qaGateFileNames[gate]);
+    const content = await readOptionalFile(artifactPath);
+    return content === null ? {} : parseOptionalJsonObject(content, qaGateFileNames[gate]);
+}
+function dedupeUnknownArray(values) {
+    const seen = new Set();
+    const deduped = [];
+    for (const value of values) {
+        const key = stableStringify(value);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(value);
+    }
+    return deduped;
+}
+function isQaPassingCommandEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return record.exit_code === 0 && normalizedString(record.status) === "pass";
+}
+function qaNonPassingCommandNotes(values) {
+    return values
+        .filter((value) => !isQaPassingCommandEvidence(value))
+        .map((value, index) => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return `QA diagnostic command ${index + 1} was omitted from pass evidence because it was not a structured passing command.`;
+        }
+        const record = value;
+        const command = optionalString(record, "command") ?? "<missing command>";
+        const status = optionalString(record, "status") ?? "<missing status>";
+        const exitCode = typeof record.exit_code === "number" && Number.isFinite(record.exit_code)
+            ? String(record.exit_code)
+            : "<missing exit_code>";
+        const summary = optionalString(record, "summary");
+        return `QA diagnostic command omitted from pass evidence: ${command} (status ${status}, exit_code ${exitCode})${summary ? ` — ${summary}` : ""}.`;
+    });
+}
+function mergeQaObjectArraysById(primary, fallback) {
+    const seen = new Set();
+    const merged = [];
+    for (const value of [...primary, ...fallback]) {
+        const id = optionalString(value, "id");
+        const key = id ? `id:${id}` : stableStringify(value);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        merged.push(value);
+    }
+    return merged;
+}
+function dedupeStrings(values) {
+    const seen = new Set();
+    const deduped = [];
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (!trimmed || seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        deduped.push(trimmed);
+    }
+    return deduped;
+}
 async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, ownerType, ownerId) {
     if (sidecars.length === 0) {
         return [];
@@ -855,10 +1374,19 @@ export async function readCompletionArtifact(worktreePath, workItemId, phase, ow
     }
     const parsed = parseJsonObject(verdictJson, artifactPath);
     const report = await readOptionalFile(reportPath) ?? fallbackReport(parsed, phase, artifactPath);
+    const artifactRoot = path.dirname(artifactPath);
+    const implementationPlanJson = phase === "architect"
+        ? await readOptionalFile(path.join(artifactRoot, "implementation.plan.json"))
+        : null;
+    const qaPlanJson = phase === "architect"
+        ? await readOptionalFile(path.join(artifactRoot, "qa.plan.json"))
+        : null;
     return {
         repoPath: path.resolve(worktreePath),
         path: artifactPath,
         verdictJson,
+        implementationPlanJson,
+        qaPlanJson,
         report,
         producedBy: optionalString(parsed, "produced_by") ?? optionalString(parsed, "producedBy") ?? "forge-completion-tool",
         status: optionalString(parsed, "status") ?? "unknown",
@@ -897,6 +1425,8 @@ export function parseCompletionMcpArgs(argv) {
     let qaCycle = false;
     let debugCycle = false;
     let architectCycle = false;
+    let draftCycle = false;
+    let decomposeCycle = false;
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === "--worktree") {
@@ -918,7 +1448,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;
         }
@@ -937,6 +1467,12 @@ export function parseCompletionMcpArgs(argv) {
         else if (arg === "--architect-cycle") {
             architectCycle = true;
         }
+        else if (arg === "--draft-cycle") {
+            draftCycle = true;
+        }
+        else if (arg === "--decompose-cycle") {
+            decomposeCycle = true;
+        }
         else {
             return { ok: false, error: `Unknown mcp argument: ${arg}` };
         }
@@ -944,7 +1480,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, decomposeCycle].filter(Boolean).length > 1) {
         return { ok: false, error: "mcp accepts only one cycle mode." };
     }
     if (developCycle && !isDevelopCompletionPhase(phase)) {
@@ -959,6 +1495,12 @@ 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." };
+    }
+    if (decomposeCycle && phase !== "decompose") {
+        return { ok: false, error: "mcp --decompose-cycle requires --phase decompose." };
+    }
     return {
         ok: true,
         config: {
@@ -972,7 +1514,9 @@ export function parseCompletionMcpArgs(argv) {
             developCycle,
             qaCycle,
             debugCycle,
-            architectCycle
+            architectCycle,
+            draftCycle,
+            decomposeCycle
         }
     };
 }
@@ -1067,11 +1611,11 @@ async function handleJsonRpcRequest(session, method, params) {
     }
     throw new Error(`Unsupported MCP method: ${method}`);
 }
-function toolDefinition(name, phase, qaGate = null) {
+function toolDefinition(name, phase, qaGate = null, decomposeGate = null) {
     return {
         name,
-        description: toolDescription(phase, qaGate),
-        inputSchema: toolInputSchema(phase, qaGate)
+        description: toolDescription(phase, qaGate, decomposeGate),
+        inputSchema: toolInputSchema(phase, qaGate, decomposeGate)
     };
 }
 function nextPhaseAfter(phase) {
@@ -1110,6 +1654,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 the current Draft kind's plan fields, 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") {
@@ -1129,6 +1691,24 @@ function completionToolNextInstructionForQaGate(completedGate, status, nextGate)
             : `${completedGate} accepted. Continue to ${nextGate}.`;
     return `${prefix} ${qaGateInstruction(nextGate)}`;
 }
+function completionToolNextInstructionForDecomposeGate(completedGate, status, nextGate) {
+    if (status !== "pass") {
+        return `Stay in ${completedGate}, address the recorded blockers/rework, then call ${expectedDecomposeCompletionToolName(completedGate)} again.`;
+    }
+    if (!nextGate) {
+        return "Decompose proposal accepted. Forge has the structured child-item proposal JSON needed to populate the proposal row.";
+    }
+    const nextInstructions = {
+        decompose_subject_intake: "Capture subject/scope, then call forge.complete_decompose_subject_intake.",
+        decompose_context_review: "Review project/repo/dependency context, then call forge.complete_decompose_context_review.",
+        decompose_breakdown_strategy: "Choose safe child boundaries, then call forge.complete_decompose_breakdown_strategy.",
+        decompose_child_items: "Draft child candidates, then call forge.complete_decompose_child_items.",
+        decompose_dependency_graph: "Validate dependency DAG, then call forge.complete_decompose_dependency_graph.",
+        decompose_critic: "Critique the decomposition, then call forge.complete_decompose_critic.",
+        decompose_proposal: "Submit final proposal_json through forge.complete_decompose_proposal."
+    };
+    return `${completedGate} accepted. ${nextInstructions[nextGate]}`;
+}
 function completionToolNextInstructionForDebugGate(completedGate, status, nextGate) {
     if (status !== "pass") {
         return `Stay in ${completedGate}, address the recorded blockers, then call ${expectedDebugCompletionToolName(completedGate)} again.`;
@@ -1162,12 +1742,17 @@ function qaGateInstruction(gate) {
             return "Prepare the QA checklist, then call forge.complete_qa_plan.";
     }
 }
-function toolDescription(phase, qaGate = null) {
+function toolDescription(phase, qaGate = null, decomposeGate = null) {
     if (qaGate) {
         return qaGate === "qa_verdict"
             ? "Complete the final Forge QA verdict by writing the canonical QA bundle with pass, needs_rework, or blocked evidence."
             : `Complete the ${qaGate.replace(/_/g, " ")} QA gate by writing ${qaGateFileNames[qaGate]} before continuing to the next QA gate.`;
     }
+    if (decomposeGate) {
+        return decomposeGate === "decompose_proposal"
+            ? "Complete the Forge Decompose proposal by writing decompose.proposal.json with candidate child items and optional structured QA scopes."
+            : `Complete the ${decomposeGate.replace(/_/g, " ")} Decompose gate by writing ${decomposeGateFileNames[decomposeGate]} before continuing.`;
+    }
     if (isDebugCompletionPhase(phase)) {
         return `Complete the ${phase.replace(/_/g, " ")} Debug gate by writing ${phaseFiles[phase].jsonFileName} with structured bug-fix evidence before continuing.`;
     }
@@ -1185,7 +1770,7 @@ function toolDescription(phase, qaGate = null) {
     }
     return "Complete Forge validation by writing validation.verdict.json with command, build/test/lint/design, drift, acceptance-criteria, and ready-for-dev-test evidence.";
 }
-function toolInputSchema(phase, qaGate = null) {
+function toolInputSchema(phase, qaGate = null, decomposeGate = null) {
     const baseProperties = {
         status: {
             type: "string",
@@ -1207,6 +1792,9 @@ function toolInputSchema(phase, qaGate = null) {
     if (qaGate && qaGate !== "qa_verdict") {
         return qaGateToolInputSchema(qaGate);
     }
+    if (decomposeGate) {
+        return decomposeGateToolInputSchema(decomposeGate, baseProperties);
+    }
     if (isDebugCompletionPhase(phase)) {
         return debugToolInputSchema(phase, baseProperties);
     }
@@ -1232,7 +1820,7 @@ function toolInputSchema(phase, qaGate = null) {
             },
             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.",
+                description: "Required for pass. Use an object explaining why no tests were needed for documentation/config-only work if empty would be ambiguous.",
                 items: evidenceObjectSchema(["path", "summary"], {
                     path: { type: "string" },
                     summary: { type: "string" }
@@ -1396,6 +1984,16 @@ function toolInputSchema(phase, qaGate = null) {
                     suggested_action: { type: "string", enum: ["create_bug", "create_follow_up", "accept_risk", "attach_to_current_item"] }
                 })
             },
+            policy_warnings: {
+                type: "array",
+                description: "Non-blocking Forge policy or scope warnings surfaced with the QA verdict.",
+                items: evidenceObjectSchema(["code", "message"], {
+                    code: { type: "string" },
+                    message: { type: "string" },
+                    severity: { type: "string" },
+                    evidence: { type: "object" }
+                })
+            },
             blocker_reason: {
                 type: "string",
                 enum: [...qaBlockerReasons],
@@ -1425,8 +2023,20 @@ function toolInputSchema(phase, qaGate = null) {
                     },
                     tasks: {
                         type: "array",
-                        description: "Required task list. Each task must include id and a non-empty tests array.",
-                        items: { type: "object", additionalProperties: true }
+                        description: "Required Develop child task list. Each task must include id, a non-empty tests array, and should include verification_scope for task-level QA evidence. Do not put parent-story QA/sign-off, child-count/materialization inventory, parent plan artifact checks, or final acceptance proof here; those belong in qa_plan.final_qa.",
+                        items: {
+                            type: "object",
+                            additionalProperties: true,
+                            properties: {
+                                id: { type: "string" },
+                                title: { type: "string" },
+                                verification_scope: qaScopeSchema("Task-level QA/verification scope for the materialized child task."),
+                                tests: {
+                                    type: "array",
+                                    items: { type: "object", additionalProperties: true }
+                                }
+                            }
+                        }
                     },
                     dependencies: {
                         type: "array",
@@ -1504,6 +2114,65 @@ function toolInputSchema(phase, qaGate = null) {
         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 decomposeGateToolInputSchema(gate, baseProperties) {
+    if (gate !== "decompose_proposal") {
+        return objectToolSchema({
+            ...baseProperties,
+            findings: {
+                type: "array",
+                description: "Optional issues, constraints, or risks discovered in this Decompose gate.",
+                items: { type: "object", additionalProperties: true }
+            }
+        }, ["status", "summary"], `Record the ${gate.replace(/_/g, " ")} Decompose gate before continuing.`);
+    }
+    const candidateSchema = {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+            origin: { type: "string" },
+            key: { type: "string" },
+            title: { type: "string" },
+            summary: { type: "string" },
+            description: { type: "string" },
+            acceptanceCriteria: { type: "string" },
+            planningPacket: { type: "string" },
+            sortOrder: { type: "number" },
+            points: { type: "number" },
+            dependsOn: { type: "array", items: { type: "string" } },
+            estimatedQaScope: qaScopeSchema("Work Order-to-Feature planning QA estimate. This is not dispatch-authoritative QA scope."),
+            estimated_qa_scope: qaScopeSchema("Work Order-to-Feature planning QA estimate. Snake_case alias for estimatedQaScope."),
+            qaScope: qaScopeSchema("Feature-to-Story QA scope that becomes Story-level QA scope after proposal approval."),
+            qa_scope: qaScopeSchema("Feature-to-Story QA scope. Snake_case alias for qaScope.")
+        }
+    };
+    const proposalSchema = {
+        type: "object",
+        additionalProperties: true,
+        description: "Final Decompose proposal JSON. Must include candidates, and may include blockedReason.",
+        properties: {
+            summary: { type: "string" },
+            blockedReason: { type: "string" },
+            blocked_reason: { type: "string" },
+            candidates: {
+                type: "array",
+                items: candidateSchema
+            }
+        }
+    };
+    return objectToolSchema({
+        ...baseProperties,
+        status: {
+            type: "string",
+            enum: ["pass", "needs_rework", "blocked"],
+            description: "Use pass only when the Decompose proposal is ready for user sign-off."
+        },
+        proposal_json: proposalSchema,
+        decomposition_json: {
+            ...proposalSchema,
+            description: "Alias for proposal_json when a client cannot send proposal_json."
+        }
+    }, ["status", "summary"], "For the final Decompose proposal, include proposal_json with a candidates array. Work Order-to-Feature candidates may include estimatedQaScope/estimated_qa_scope; Feature-to-Story candidates may include qaScope/qa_scope.");
+}
 function debugToolInputSchema(phase, baseProperties) {
     if (phase === "debug_repro") {
         return objectToolSchema({
@@ -1659,6 +2328,36 @@ function evidenceObjectSchema(required, properties) {
         required: [...required]
     };
 }
+function qaScopeSchema(description) {
+    return {
+        type: "object",
+        additionalProperties: false,
+        description,
+        properties: {
+            schema_version: { type: "number", enum: [1] },
+            surface: { type: "array", items: { type: "string", enum: [...qaScopeSurfaces] } },
+            required_evidence: { type: "array", items: { type: "string", enum: [...qaScopeEvidence] } },
+            not_applicable: { type: "array", items: { type: "string", enum: [...qaScopeEvidence] } },
+            browser_required: { type: "boolean" },
+            api_required: { type: "boolean" },
+            source: { type: "string", enum: [...qaScopeSources] },
+            authority: { type: "string", enum: [...qaScopeAuthorities] },
+            confidence: { type: "string", enum: [...qaScopeConfidence] },
+            confirmed_by_user: { type: "boolean" },
+            locked: { type: "boolean" },
+            derived_from: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    work_item_id: { type: "string" },
+                    mode: { type: "string" }
+                }
+            },
+            rationale: { type: "string" }
+        },
+        required: ["schema_version", "required_evidence", "not_applicable"]
+    };
+}
 function commandEvidenceSchema() {
     return evidenceObjectSchema(["command", "exit_code", "status", "summary"], {
         command: { type: "string" },
@@ -1881,6 +2580,7 @@ function validateQaGatePayloadShape(gate, payload, status) {
         if (commands.length === 0) {
             throw new Error(`${qaGateToolNames[gate]} pass requires commands with at least one entry.`);
         }
+        validateQaGatePassingCommands(commands);
     }
     if (gate === "qa_manual_web" && status === "pass") {
         const browserChecks = qaArray(payload, "browser_checks");
@@ -1890,6 +2590,24 @@ function validateQaGatePayloadShape(gate, payload, status) {
         }
     }
 }
+function validateQaGatePassingCommands(commands) {
+    for (const [index, command] of commands.entries()) {
+        requireEvidenceRecord(command, `commands[${index}]`);
+        const record = command;
+        requireNonEmptyStringRecord(record, "command", `commands[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `commands[${index}].`);
+        requireNonEmptyStringRecord(record, "summary", `commands[${index}].`);
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            throw new Error(`commands[${index}].exit_code is required.`);
+        }
+        if (record.exit_code !== 0) {
+            throw new Error(`commands[${index}].exit_code must be 0 when QA gate status is pass.`);
+        }
+        if (normalizedString(record.status) !== "pass") {
+            throw new Error(`commands[${index}].status must be pass when QA gate status is pass.`);
+        }
+    }
+}
 function validateArchitectPayloadShape(payload, status) {
     if (status !== "pass") {
         requireArchitectNonPassEvidence(payload);
@@ -1918,6 +2636,8 @@ function validateArchitectPayloadShape(payload, status) {
             throw new Error(`implementation_plan.tasks: duplicate task id '${taskId}'.`);
         }
         taskIds.add(taskId);
+        validateArchitectTaskDevelopScope(taskRecord, taskId);
+        validateArchitectVerificationScope(taskRecord, taskId);
         requireArchitectArray(taskRecord, "tests", payload, { path: `implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests` });
         if (arrayLength(taskRecord, "tests") === 0) {
             throw new Error(`implementation_plan.tasks[${optionalString(taskRecord, "id") ?? "?"}].tests: expected non-empty array; correction: include task-specific verification.`);
@@ -1930,6 +2650,241 @@ function validateArchitectPayloadShape(payload, status) {
         throw new Error("qa_plan.final_qa: expected non-empty array; correction: include final QA coverage for the completed plan.");
     }
 }
+function validateArchitectTaskDevelopScope(task, taskId) {
+    const explicitScope = firstOptionalString(task, ["execution_scope", "scope", "task_scope", "task_type", "lane", "kind", "type"]);
+    if (isStoryQaScope(explicitScope)) {
+        throw new Error(`implementation_plan.tasks[${taskId}]: story QA/sign-off work must not be materialized as a Develop child task; correction: move this coverage to qa_plan.final_qa and keep implementation_plan.tasks limited to repo/product changes.`);
+    }
+    if (looksLikeStoryLevelVerificationTask(architectTaskScopeText(task))) {
+        throw new Error(`implementation_plan.tasks[${taskId}]: parent-story materialization or sign-off verification belongs in qa_plan.final_qa, not implementation_plan.tasks; correction: keep child tasks focused on implementation work and put child-count/parent-plan artifact checks in final QA coverage.`);
+    }
+}
+function validateArchitectVerificationScope(task, taskId) {
+    const value = task.verification_scope;
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`implementation_plan.tasks[${taskId}].verification_scope: expected object when present.`);
+    }
+    validateQaScopeRecord(value, `implementation_plan.tasks[${taskId}].verification_scope`);
+}
+function validateQaScopeRecord(scope, pathLabel) {
+    for (const key of Object.keys(scope)) {
+        if (!qaScopeFields.has(key)) {
+            throw new Error(`${pathLabel}.${key}: unsupported QA scope field.`);
+        }
+    }
+    if (scope.schema_version !== 1) {
+        throw new Error(`${pathLabel}.schema_version must be numeric 1.`);
+    }
+    const surface = qaScopeStringArray(scope, "surface", pathLabel, qaScopeSurfaces);
+    const requiredEvidence = qaScopeStringArray(scope, "required_evidence", pathLabel, qaScopeEvidence);
+    const notApplicable = qaScopeStringArray(scope, "not_applicable", pathLabel, qaScopeEvidence);
+    const requiredSet = new Set(requiredEvidence);
+    for (const evidence of notApplicable) {
+        if (requiredSet.has(evidence)) {
+            throw new Error(`${pathLabel}: '${evidence}' cannot be both required and not applicable.`);
+        }
+    }
+    const browserRequired = requiredSet.has("browser_manual");
+    const apiRequired = requiredSet.has("api_http");
+    validateOptionalBoolean(scope, "browser_required", pathLabel, browserRequired);
+    validateOptionalBoolean(scope, "api_required", pathLabel, apiRequired);
+    validateOptionalBoolean(scope, "confirmed_by_user", pathLabel);
+    validateOptionalBoolean(scope, "locked", pathLabel);
+    if (surface.includes("ui_browser") && !browserRequired) {
+        throw new Error(`${pathLabel}.surface ui_browser requires browser_manual evidence.`);
+    }
+    if (surface.includes("api_route") && !apiRequired) {
+        throw new Error(`${pathLabel}.surface api_route requires api_http evidence.`);
+    }
+    validateOptionalKnownString(scope, "source", pathLabel, qaScopeSources);
+    validateOptionalKnownString(scope, "authority", pathLabel, qaScopeAuthorities);
+    validateOptionalKnownString(scope, "confidence", pathLabel, qaScopeConfidence);
+    if (scope.rationale !== undefined && scope.rationale !== null && typeof scope.rationale !== "string") {
+        throw new Error(`${pathLabel}.rationale must be a string.`);
+    }
+    validateOptionalQaScopeDerivedFrom(scope, pathLabel);
+}
+function qaScopeStringArray(scope, key, pathLabel, allowed) {
+    const value = scope[key];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${pathLabel}.${key} must be an array.`);
+    }
+    const normalized = [];
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`${pathLabel}.${key}[${index}] must be a non-empty string.`);
+        }
+        const candidate = entry.trim().toLowerCase();
+        if (!allowed.has(candidate)) {
+            throw new Error(`${pathLabel}.${key}[${index}] value '${candidate}' is unsupported.`);
+        }
+        if (!normalized.includes(candidate)) {
+            normalized.push(candidate);
+        }
+    }
+    return normalized;
+}
+function validateOptionalBoolean(scope, key, pathLabel, expected) {
+    const value = scope[key];
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error(`${pathLabel}.${key} must be boolean.`);
+    }
+    if (expected !== undefined && value !== expected) {
+        throw new Error(`${pathLabel}.${key} must match required_evidence.`);
+    }
+}
+function validateOptionalKnownString(scope, key, pathLabel, allowed) {
+    const value = scope[key];
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${pathLabel}.${key} must be a non-empty string.`);
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!allowed.has(normalized)) {
+        throw new Error(`${pathLabel}.${key} value '${normalized}' is unsupported.`);
+    }
+}
+function validateOptionalQaScopeDerivedFrom(scope, pathLabel) {
+    const value = scope.derived_from;
+    if (value === undefined || value === null) {
+        return;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${pathLabel}.derived_from must be an object.`);
+    }
+    const derivedFrom = value;
+    for (const key of Object.keys(derivedFrom)) {
+        if (key !== "work_item_id" && key !== "mode") {
+            throw new Error(`${pathLabel}.derived_from.${key}: unsupported QA scope provenance field.`);
+        }
+    }
+    if (derivedFrom.work_item_id !== undefined && derivedFrom.work_item_id !== null && typeof derivedFrom.work_item_id !== "string") {
+        throw new Error(`${pathLabel}.derived_from.work_item_id must be a string.`);
+    }
+    if (derivedFrom.mode !== undefined && derivedFrom.mode !== null && typeof derivedFrom.mode !== "string") {
+        throw new Error(`${pathLabel}.derived_from.mode must be a string.`);
+    }
+}
+function firstOptionalString(record, keys) {
+    for (const key of keys) {
+        const value = optionalString(record, key);
+        if (value) {
+            return value;
+        }
+    }
+    return null;
+}
+function isStoryQaScope(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase().replace(/[\s-]+/g, "_");
+    return [
+        "qa",
+        "story_qa",
+        "final_qa",
+        "sign_off",
+        "signoff",
+        "story_sign_off",
+        "story_verification",
+        "story_validation"
+    ].includes(normalized);
+}
+function architectTaskScopeText(task) {
+    const parts = [];
+    for (const key of ["id", "title", "summary", "phase", "phase_id"]) {
+        appendOptionalString(parts, task, key);
+    }
+    for (const key of ["acceptance_criteria", "expected_paths", "touched_surfaces", "implementation_notes"]) {
+        appendOptionalStringArray(parts, task, key);
+    }
+    const tests = task.tests;
+    if (Array.isArray(tests)) {
+        for (const test of tests) {
+            if (!test || typeof test !== "object" || Array.isArray(test)) {
+                continue;
+            }
+            const record = test;
+            for (const key of ["id", "command", "purpose", "target", "expected"]) {
+                appendOptionalString(parts, record, key);
+            }
+            appendOptionalStringArray(parts, record, "steps");
+        }
+    }
+    return parts.join(" ");
+}
+function appendOptionalString(parts, record, key) {
+    const value = optionalString(record, key);
+    if (value) {
+        parts.push(value);
+    }
+}
+function appendOptionalStringArray(parts, record, key) {
+    const value = record[key];
+    if (!Array.isArray(value)) {
+        return;
+    }
+    for (const entry of value) {
+        if (typeof entry === "string" && entry.trim().length > 0) {
+            parts.push(entry.trim());
+        }
+    }
+}
+function looksLikeStoryLevelVerificationTask(text) {
+    if (!text.trim()) {
+        return false;
+    }
+    const normalized = text.toLowerCase();
+    const verificationWords = [
+        "verify",
+        "verification",
+        "validate",
+        "validation",
+        "inspect",
+        "audit",
+        "check",
+        "confirm",
+        "prove",
+        "evidence",
+        "sign-off",
+        "sign off"
+    ];
+    if (!verificationWords.some((word) => normalized.includes(word))) {
+        return false;
+    }
+    return [
+        "materialization",
+        "materialized child",
+        "child inventory",
+        "child work-item",
+        "child work item",
+        "created task count",
+        "created_task_count",
+        "parent plan",
+        "parent story",
+        "story sign-off",
+        "story sign off",
+        ".forge/work-items",
+        ".forge\\work-items",
+        ".forge/stories",
+        ".forge\\stories",
+        "implementation.plan.json",
+        "qa.plan.json",
+        "architect plan artifact",
+        "child spec"
+    ].some((needle) => normalized.includes(needle));
+}
 function validateAndNormalizeArchitectDependencies(implementationPlan, taskIds) {
     const dependencies = implementationPlan.dependencies;
     const edges = new Map();
@@ -2055,6 +3010,7 @@ function validateQaPayloadShape(payload, status) {
     const candidateBugs = qaObjectArray(payload, "candidate_bugs");
     const explicitFindingIds = qaStringArray(payload, "finding_ids");
     const explicitCandidateBugIds = qaStringArray(payload, "candidate_bug_ids");
+    qaPolicyWarnings(payload);
     if (payload.schema_version !== undefined && payload.schema_version !== 1) {
         throw new Error("QA schema_version must be numeric 1 when provided.");
     }
@@ -2251,6 +3207,12 @@ 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";
+    }
+    if (normalized === "decompose" || normalized === "decomposition" || normalized === "work_order_decomposition" || normalized === "feature_decomposition") {
+        return "decompose";
+    }
     return null;
 }
 function normalizeDebugCompletionPhase(value) {
@@ -2322,6 +3284,12 @@ function phaseFromToolName(toolName) {
     if (normalized === "forge.complete_architect_plan" || normalized === "complete_architect_plan") {
         return "architect";
     }
+    if (draftGateFromToolName(toolName)) {
+        return "draft";
+    }
+    if (decomposeGateFromToolName(toolName)) {
+        return "decompose";
+    }
     const debugGate = debugGateFromToolName(toolName);
     if (debugGate) {
         return debugGate;
@@ -2331,6 +3299,32 @@ 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 decomposeGateFromToolName(toolName) {
+    for (const gate of decomposeCompletionGateOrder) {
+        const base = decomposeGateToolNames[gate];
+        if (toolName === base || toolName === `forge.${base}`) {
+            return gate;
+        }
+    }
+    return null;
+}
+function isDecomposeDispatch(dispatch) {
+    const draftKind = dispatch.draft?.kind?.trim().toLowerCase();
+    return dispatch.execution.lane.trim().toLowerCase() === "decompose"
+        || dispatch.session.lane.trim().toLowerCase() === "decompose"
+        || draftKind === "work_order_decomposition"
+        || draftKind === "feature_decomposition";
+}
 function debugGateFromToolName(toolName) {
     const normalized = toolName.trim().toLowerCase();
     for (const gate of debugCompletionPhaseOrder) {
@@ -2526,6 +3520,27 @@ function qaObjectArray(payload, key) {
         return entry;
     });
 }
+function qaPolicyWarnings(payload) {
+    return qaArray(payload, "policy_warnings").map((entry, index) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new Error(`policy_warnings[${index}] must be an object.`);
+        }
+        const warning = entry;
+        const prefix = `policy_warnings[${index}].`;
+        requireNonEmptyStringRecord(warning, "code", prefix);
+        requireNonEmptyStringRecord(warning, "message", prefix);
+        const normalized = {
+            ...warning,
+            code: optionalString(warning, "code"),
+            message: optionalString(warning, "message")
+        };
+        if (warning.severity !== undefined && warning.severity !== null) {
+            requireNonEmptyStringRecord(warning, "severity", prefix);
+            normalized.severity = optionalString(warning, "severity");
+        }
+        return normalized;
+    });
+}
 function qaStringArray(payload, key) {
     const value = payload[key];
     if (value === undefined || value === null) {