@loucompanion/forge-bridge 0.1.3-dev.6e59f152916f → 0.1.3-dev.ab8510b71f9b

package/dist/session/phase-completion.js

@@ -113,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",
@@ -308,7 +346,10 @@ export async function prepareCompletionToolRuntime(options) {
         qaCycle: usesQaCycleCompletion(options.dispatch),
         debugCycle: usesDebugCycleCompletion(options.dispatch),
         architectCycle: usesArchitectCycleCompletion(options.dispatch),
-        draftCycle: (options.dispatch.execution.lane.trim().toLowerCase() === "draft" || options.dispatch.cycleRun.kind.trim().toLowerCase() === "draft") && !isDecomposeDispatch(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 = {
@@ -388,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") {
@@ -395,8 +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" }\`.
-\`implementation_plan.tasks\` are Develop child tasks only: each task 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.
+\`{ "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.`;
@@ -429,6 +471,7 @@ 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") {
@@ -439,9 +482,9 @@ Complete the Draft cycle in order inside this same provider session:
 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(...)\`.
+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 Work Order JSON in \`draft_json\`.
+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") {
@@ -458,7 +501,7 @@ Required order:
 5. Follow the returned dependency-graph instruction, validate keys/dependencies/order, then call \`forge.complete_decompose_dependency_graph(...)\`.
 6. Follow the returned critic instruction, critique scope, DAG safety, manual reconciliation risk, and missing acceptance detail, then call \`forge.complete_decompose_critic(...)\`.
 7. Follow the returned proposal instruction, then call \`forge.complete_decompose_proposal(...)\` with final JSON in \`proposal_json\`.
-The final proposal tool writes \`decompose.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. The proposal_json object must contain summary, optional blockedReason, and candidates.`;
+The final proposal tool writes \`decompose.proposal.json\` under \`.forge/work-items/{workItemId}/artifacts/\`. The proposal_json object must contain summary, optional blockedReason, and candidates. Work Order-to-Feature candidates may include \`estimated_qa_scope\`; Feature-to-Story candidates should include \`qa_scope\` with schema_version 1 plus scheduleIndex, waveIndex, expectedOutput, handoffSummary, and dependencyReason for dependency handoff.`;
 }
 export function completionPromptForDebugCycle(currentGate = "debug_repro") {
     return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
@@ -511,7 +554,7 @@ export class CompletionToolServerSession {
                             : 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);
@@ -762,9 +805,7 @@ async function writeDecomposeGateCompletionArtifact(config, gate, toolName, inpu
     const status = normalizeDraftStatus(optionalString(payload, "status") ?? "pass");
     if (gate === "decompose_proposal") {
         const proposalJson = asRecord(payload["proposal_json"] ?? payload["decomposition_json"], "proposal_json");
-        if (!Array.isArray(proposalJson["candidates"])) {
-            throw new Error("proposal_json.candidates: expected array");
-        }
+        validateDecomposeProposalJson(proposalJson);
     }
     const redactedPayload = redactSecrets({ ...payload, status, phase: "decompose", gate, tool_name: toolName }, config.redactionSecrets ?? []);
     const root = artifactRootFor(config.worktreePath, config.workItemId);
@@ -796,11 +837,7 @@ async function writeDraftGateCompletionArtifact(config, gate, toolName, input) {
     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`);
-            }
-        }
+        validateDraftProposalJson(draftJson);
     }
     const redactedPayload = redactSecrets({ ...payload, status, phase: "draft", gate, tool_name: toolName }, config.redactionSecrets ?? []);
     const root = artifactRootFor(config.worktreePath, config.workItemId);
@@ -828,6 +865,67 @@ 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) {
@@ -1003,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({
@@ -1050,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,
@@ -1511,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) {
@@ -1566,7 +1666,7 @@ function completionToolNextInstructionForDraftGate(completedGate, status, nextGa
         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_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."
     };
@@ -1642,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.`;
     }
@@ -1665,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",
@@ -1687,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);
     }
@@ -1876,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],
@@ -1905,8 +2023,20 @@ function toolInputSchema(phase, qaGate = null) {
                     },
                     tasks: {
                         type: "array",
-                        description: "Required Develop child task list. Each task must include id and a non-empty tests array, and must require a focused repo/product implementation change. 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 }
+                        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",
@@ -1984,6 +2114,77 @@ 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" },
+            scheduleIndex: { type: "number", description: "Feature-to-Story total schedule order for dependency-safe execution." },
+            schedule_index: { type: "number", description: "Snake_case alias for scheduleIndex." },
+            waveIndex: { type: "number", description: "Feature-to-Story parallel wave number." },
+            wave_index: { type: "number", description: "Snake_case alias for waveIndex." },
+            featureScheduleIndex: { type: "number", description: "Optional ordering within the Feature." },
+            feature_schedule_index: { type: "number", description: "Snake_case alias for featureScheduleIndex." },
+            expectedOutput: { type: "string", description: "Durable output this Story should produce for dependents." },
+            expected_output: { type: "string", description: "Snake_case alias for expectedOutput." },
+            handoffSummary: { type: "string", description: "How dependent Stories should consume this Story output." },
+            handoff_summary: { type: "string", description: "Snake_case alias for handoffSummary." },
+            dependencyReason: { type: "string", description: "Why this Story depends on its dependsOn predecessors." },
+            dependency_reason: { type: "string", description: "Snake_case alias for dependencyReason." },
+            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({
@@ -2139,6 +2340,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" },
@@ -2418,6 +2649,7 @@ function validateArchitectPayloadShape(payload, status) {
         }
         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.`);
@@ -2439,6 +2671,123 @@ function validateArchitectTaskDevelopScope(task, taskId) {
         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);
@@ -2673,6 +3022,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.");
     }
@@ -3182,6 +3532,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) {

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

@@ -241,91 +241,110 @@ export class ProcessBackedProviderCliService {
             else {
                 context.signal?.addEventListener("abort", abortProvider, { once: true });
             }
-            const runPromise = this.processRunner.run({
-                command: command.command,
-                args: command.args,
-                cwd: tempDir,
-                env: providerProcessEnv(dispatch)
-            }, {
-                onStdoutLine: async (line) => {
-                    for (const event of outputState.consume(line)) {
-                        await context.emit(event);
+            try {
+                const runPromise = this.processRunner.run({
+                    command: command.command,
+                    args: command.args,
+                    cwd: tempDir,
+                    env: providerProcessEnv(dispatch)
+                }, {
+                    onStdoutLine: async (line) => {
+                        for (const event of outputState.consume(line)) {
+                            await context.emit(event);
+                        }
                     }
-                }
-            }, providerCancellation.signal);
-            let result;
-            let earlyProposalArtifact = null;
-            {
-                const terminal = await Promise.race([
-                    runPromise.then(value => ({ kind: "process", value })),
-                    waitForCompletionArtifact(tempDir, dispatch.workItem.id, decomposeDraft ? "decompose" : "draft", context.signal).then(value => ({ kind: "artifact", value }))
-                ]);
-                if (terminal.kind === "artifact") {
-                    earlyProposalArtifact = terminal.value;
-                    providerCancellation.abort();
-                    result = await runPromise.catch(() => ({ exitCode: 0, stdout: "", stderr: "" }));
+                }, providerCancellation.signal);
+                const artifactWaitCancellation = new AbortController();
+                const abortArtifactWait = () => artifactWaitCancellation.abort();
+                if (context.signal?.aborted) {
+                    abortArtifactWait();
                 }
                 else {
-                    result = terminal.value;
+                    context.signal?.addEventListener("abort", abortArtifactWait, { once: true });
                 }
-            }
-            context.signal?.removeEventListener("abort", abortProvider);
-            if (result.exitCode !== 0 && !earlyProposalArtifact) {
-                throw new Error(`Provider CLI exited with code ${result.exitCode}${summarizeStderr(result.stderr)}.`);
-            }
-            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);
-            if (decomposeDraft) {
-                await emitDecomposeGateArtifacts(context.emit, tempDir, dispatch.workItem.id);
-                const proposalArtifact = earlyProposalArtifact ?? await readCompletionArtifact(tempDir, dispatch.workItem.id, "decompose");
+                const artifactWaitPromise = waitForCompletionArtifact(tempDir, dispatch.workItem.id, decomposeDraft ? "decompose" : "draft", artifactWaitCancellation.signal);
+                let result;
+                let earlyProposalArtifact = null;
+                try {
+                    const terminal = await Promise.race([
+                        runPromise.then(value => ({ kind: "process", value })),
+                        artifactWaitPromise.then(value => ({ kind: "artifact", value }))
+                    ]);
+                    artifactWaitCancellation.abort();
+                    await artifactWaitPromise.catch(() => undefined);
+                    if (terminal.kind === "artifact") {
+                        earlyProposalArtifact = terminal.value;
+                        providerCancellation.abort();
+                        result = await runPromise.catch(() => ({ exitCode: 0, stdout: "", stderr: "" }));
+                    }
+                    else {
+                        result = terminal.value;
+                    }
+                }
+                finally {
+                    artifactWaitCancellation.abort();
+                    context.signal?.removeEventListener("abort", abortArtifactWait);
+                }
+                if (result.exitCode !== 0 && !earlyProposalArtifact) {
+                    throw new Error(`Provider CLI exited with code ${result.exitCode}${summarizeStderr(result.stderr)}.`);
+                }
+                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);
+                if (decomposeDraft) {
+                    await emitDecomposeGateArtifacts(context.emit, tempDir, dispatch.workItem.id);
+                    const proposalArtifact = earlyProposalArtifact ?? await readCompletionArtifact(tempDir, dispatch.workItem.id, "decompose");
+                    if (!proposalArtifact) {
+                        throw new Error("Provider CLI Decompose completed but did not call forge.complete_decompose_proposal.");
+                    }
+                    const proposal = parseJsonLine(proposalArtifact.verdictJson) ?? {};
+                    const proposalJson = proposal["proposal_json"] ?? proposal["decomposition_json"];
+                    if (!proposalJson || typeof proposalJson !== "object" || Array.isArray(proposalJson)) {
+                        throw new Error("Provider CLI Decompose completed but decompose.proposal.json did not contain proposal_json.");
+                    }
+                    const json = JSON.stringify(proposalJson);
+                    await context.emit({
+                        role: "assistant",
+                        kind: "message",
+                        content: json,
+                        eventType: "decompose_proposal"
+                    });
+                    return {
+                        summary: "Decomposition proposal generated through Forge Decompose completion cycle.",
+                        artifact: proposalArtifact,
+                        artifacts: [proposalArtifact]
+                    };
+                }
+                await emitDraftGateArtifacts(context.emit, tempDir, dispatch.workItem.id);
+                const proposalArtifact = earlyProposalArtifact ?? await readCompletionArtifact(tempDir, dispatch.workItem.id, "draft");
                 if (!proposalArtifact) {
-                    throw new Error("Provider CLI Decompose completed but did not call forge.complete_decompose_proposal.");
+                    throw new Error("Provider CLI Draft completed but did not call forge.complete_draft_proposal.");
                 }
                 const proposal = parseJsonLine(proposalArtifact.verdictJson) ?? {};
-                const proposalJson = proposal["proposal_json"] ?? proposal["decomposition_json"];
-                if (!proposalJson || typeof proposalJson !== "object" || Array.isArray(proposalJson)) {
-                    throw new Error("Provider CLI Decompose completed but decompose.proposal.json did not contain proposal_json.");
+                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 = JSON.stringify(proposalJson);
+                const json = JSON.stringify(draftJson);
                 await context.emit({
                     role: "assistant",
                     kind: "message",
                     content: json,
-                    eventType: "decompose_proposal"
+                    eventType: "draft_complete"
                 });
                 return {
-                    summary: "Decomposition proposal generated through Forge Decompose completion cycle.",
+                    summary: "Draft generated through Forge Draft completion cycle.",
                     artifact: proposalArtifact,
                     artifacts: [proposalArtifact]
                 };
             }
-            await emitDraftGateArtifacts(context.emit, tempDir, dispatch.workItem.id);
-            const proposalArtifact = earlyProposalArtifact ?? 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.");
+            finally {
+                context.signal?.removeEventListener("abort", abortProvider);
             }
-            const json = JSON.stringify(draftJson);
-            await context.emit({
-                role: "assistant",
-                kind: "message",
-                content: json,
-                eventType: "draft_complete"
-            });
-            return {
-                summary: "Draft generated through Forge Draft completion cycle.",
-                artifact: proposalArtifact,
-                artifacts: [proposalArtifact]
-            };
         }
         finally {
             await cleanupCompletionTools(completionTools, context.emit);
@@ -2168,10 +2187,33 @@ async function waitForCompletionArtifact(worktreePath, workItemId, phase, signal
         if (artifact) {
             return artifact;
         }
-        await new Promise((resolve) => setTimeout(resolve, 1000));
+        await delay(1000, signal);
     }
     throw new Error(`${phase} proposal artifact wait was cancelled.`);
 }
+async function delay(ms, signal) {
+    if (!signal) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+        return;
+    }
+    const abortSignal = signal;
+    if (abortSignal.aborted) {
+        return;
+    }
+    await new Promise((resolve) => {
+        const timeout = setTimeout(done, ms);
+        const abort = () => done();
+        function done() {
+            clearTimeout(timeout);
+            abortSignal.removeEventListener("abort", abort);
+            resolve();
+        }
+        abortSignal.addEventListener("abort", abort, { once: true });
+        if (abortSignal.aborted) {
+            done();
+        }
+    });
+}
 function deterministicDraftPayload(dispatch) {
     const kind = dispatch.draft?.kind ?? "work_item";
     if (kind === "work_order_decomposition") {
@@ -2321,6 +2363,7 @@ Work item: ${dispatch.workItem.id} — ${dispatch.workItem.title}
 Plan only. Do not implement source changes, do not create Develop phase artifacts, and do not mark the spec approved.
 Read injected Forge context under .forge plus the repository shape, then produce a repo-grounded implementation DAG with task tests, phase gates, final QA coverage, and a pending-approval spec.
 Implementation DAG tasks are Develop child tasks only: include focused repo/product implementation changes. Do not create child Develop tasks for parent-story QA, sign-off, materialized child inventory, child-count evidence, parent plan artifact checks, or final integrated acceptance proof; put those checks in qa_plan.final_qa.
+${architectDependencyInstruction(dispatch)}
 ${architectRevisionInstruction(dispatch)}
 Forge owns protocol files: write Architect artifacts only through the completion MCP tool.
 
@@ -2328,6 +2371,39 @@ ${completionPromptForPhase("architect")}
 
 Finish only after calling forge.complete_architect_plan with implementation_plan, qa_plan, status, summary, and report/report_markdown.`;
 }
+function architectDependencyInstruction(dispatch) {
+    if (!dispatch.architectDependencies || dispatch.architectDependencies.prerequisites.length === 0) {
+        return "";
+    }
+    const dependencies = dispatch.architectDependencies.prerequisites
+        .map((dependency, index) => {
+        const schedule = dependency.scheduleIndex === null || dependency.scheduleIndex === undefined
+            ? "schedule index unknown"
+            : `schedule index ${dependency.scheduleIndex}`;
+        const wave = dependency.waveIndex === null || dependency.waveIndex === undefined
+            ? "wave unknown"
+            : `wave ${dependency.waveIndex}`;
+        const featureSchedule = dependency.featureScheduleIndex === null || dependency.featureScheduleIndex === undefined
+            ? ""
+            : `, feature schedule ${dependency.featureScheduleIndex}`;
+        const outputSource = dependency.pullRequestNumber === null || dependency.pullRequestNumber === undefined
+            ? `manual completion on ${dependency.targetBranch}`
+            : `merged PR ${dependency.pullRequestNumber} into ${dependency.targetBranch}`;
+        return `${index + 1}. ${dependency.title} (${dependency.storyId}, ${schedule}, ${wave}${featureSchedule})
+   - Expected output: ${dependency.expectedOutput ?? "Predecessor output recorded by Work Order dependency graph."}
+   - Handoff summary: ${dependency.handoffSummary ?? "Use the predecessor implementation as the foundation for this story."}
+   - Dependency reason: ${dependency.dependencyReason ?? "This story depends on predecessor output."}
+   - Output source: ${outputSource}`;
+    })
+        .join("\n");
+    return `
+Dependency Schedule Context:
+This story is scheduled after predecessor work that should already be available on base branch ${dispatch.architectDependencies.baseBranch}.
+
+${dependencies}
+
+Use this predecessor output as foundation. Do not redesign or recreate predecessor scope. If the expected output is unavailable in the checkout/base branch, stop and report dependency_output_unavailable.`;
+}
 function architectRevisionInstruction(dispatch) {
     if (!dispatch.architectRevision) {
         return "";
@@ -2427,18 +2503,27 @@ function phaseWorkInstruction(phase) {
 }
 function qaBrowserInstruction(dispatch) {
     const qaBrowser = dispatch.qaBrowser;
+    const qaScope = dispatch.qaScope;
     if (!qaBrowser) {
         return "Browser/app launch context: not provided by Forge.";
     }
+    const scopeAuthority = qaScope
+        ? qaScope.source === "heuristic"
+            ? "Forge's transient heuristic fallback"
+            : "persisted QA scope"
+        : "Forge heuristics";
+    const scopeEvidence = qaScope
+        ? `\n- QA scope required evidence: ${qaScope.required_evidence.length > 0 ? qaScope.required_evidence.join(", ") : "none"}\n- QA scope not applicable: ${qaScope.not_applicable.length > 0 ? qaScope.not_applicable.join(", ") : "none"}${qaScope.rationale ? `\n- QA scope rationale: ${qaScope.rationale}` : ""}`
+        : "";
     const launchTarget = qaBrowser.launchTarget;
     if (qaBrowser.required && !hasLaunchTarget(launchTarget ?? null)) {
-        return `Browser/app launch context:\n- UI/browser QA is required for this item.\n- No app launch target was provided.\n- Return blocked with blocker_reason: missing_app_launch_target instead of pretending browser testing occurred.\n- Artifact sidecars path when available: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
+        return `Browser/app launch context:\n- UI/browser QA is required for this item by ${scopeAuthority}.\n- No app launch target was provided.\n- Return blocked with blocker_reason: missing_app_launch_target instead of pretending browser testing occurred.${scopeEvidence}\n- Artifact sidecars path when available: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
     }
     if (!launchTarget) {
-        return `Browser/app launch context:\n- UI/browser QA is not required by Forge heuristics for this item.\n- If you determine browser testing is needed, return blocked with blocker_reason: missing_app_launch_target unless you can safely identify a launch target from the repo.\n- Browser sidecars path: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
+        return `Browser/app launch context:\n- UI/browser QA is not required by ${scopeAuthority} for this item.\n- If you determine browser testing is needed, return blocked with blocker_reason: missing_app_launch_target unless you can safely identify a launch target from the repo.${scopeEvidence}\n- Browser sidecars path: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
     }
     const routes = launchTarget.routes.length > 0 ? launchTarget.routes.join(", ") : "not specified";
-    return `Browser/app launch context:\n- Browser QA required: ${qaBrowser.required ? "yes" : "no, unless the diff/AC requires it"}\n- URL: ${launchTarget.url || "not specified"}\n- Ready URL: ${launchTarget.ready_url || "not specified"}\n- Launch command: ${launchTarget.command || "not specified"}\n- Working directory: ${launchTarget.working_directory || "repo root"}\n- Routes to cover: ${routes}\n- Notes: ${launchTarget.notes || "none"}\n- Browser sidecars path: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
+    return `Browser/app launch context:\n- Browser QA required: ${qaBrowser.required ? `yes, by ${scopeAuthority}` : `no by ${scopeAuthority}, unless the diff/AC requires it`}\n- URL: ${launchTarget.url || "not specified"}\n- Ready URL: ${launchTarget.ready_url || "not specified"}\n- Launch command: ${launchTarget.command || "not specified"}\n- Working directory: ${launchTarget.working_directory || "repo root"}\n- Routes to cover: ${routes}\n- Notes: ${launchTarget.notes || "none"}${scopeEvidence}\n- Browser sidecars path: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
 }
 function storyQaInstruction(dispatch) {
     const storyQa = dispatch.storyQa;

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

@@ -13,8 +13,10 @@ export interface RunOnceDispatchPacket {
     readonly artifacts: readonly DispatchResolvedArtifact[];
     readonly warmPathOverrides?: readonly string[];
     readonly qaBrowser?: DispatchQaBrowserContext | null;
+    readonly qaScope?: DispatchQaScope | null;
     readonly qaRework?: DispatchQaReworkContext | null;
     readonly architectRevision?: DispatchArchitectRevisionContext | null;
+    readonly architectDependencies?: DispatchArchitectDependencyContext | null;
     readonly storyDevelop?: DispatchStoryDevelopContext | null;
     readonly storyQa?: DispatchStoryQaContext | null;
     readonly draft?: DispatchDraftPrompt | null;
@@ -32,6 +34,21 @@ export interface DispatchQaBrowserContext {
     readonly artifactsPath: string;
     readonly missingTargetReason?: string | null;
 }
+export interface DispatchQaScope {
+    readonly schema_version: number;
+    readonly surface: readonly string[];
+    readonly required_evidence: readonly string[];
+    readonly not_applicable: readonly string[];
+    readonly browser_required: boolean;
+    readonly api_required: boolean;
+    readonly source?: string | null;
+    readonly authority?: string | null;
+    readonly confidence?: string | null;
+    readonly confirmed_by_user?: boolean | null;
+    readonly locked?: boolean | null;
+    readonly derived_from?: Readonly<Record<string, unknown>> | null;
+    readonly rationale?: string | null;
+}
 export interface DispatchQaAppLaunchTarget {
     readonly url?: string | null;
     readonly command?: string | null;
@@ -53,6 +70,22 @@ export interface DispatchArchitectRevisionContext {
     readonly priorContentHash: string;
     readonly feedback: string;
 }
+export interface DispatchArchitectDependencyContext {
+    readonly baseBranch: string;
+    readonly prerequisites: readonly DispatchArchitectDependencyItemContext[];
+}
+export interface DispatchArchitectDependencyItemContext {
+    readonly storyId: string;
+    readonly title: string;
+    readonly scheduleIndex?: number | null;
+    readonly waveIndex?: number | null;
+    readonly featureScheduleIndex?: number | null;
+    readonly expectedOutput?: string | null;
+    readonly handoffSummary?: string | null;
+    readonly dependencyReason?: string | null;
+    readonly pullRequestNumber?: number | null;
+    readonly targetBranch: string;
+}
 export interface DispatchStoryDevelopContext {
     readonly storyWorkItemId: string;
     readonly planId: string;

package/dist/session/session.types.js

@@ -20,8 +20,10 @@ export function parseRunOnceDispatchPacket(value) {
         artifacts: parseArtifacts(packet.artifacts),
         warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides),
         qaBrowser: parseQaBrowser(packet.qaBrowser),
+        qaScope: parseQaScope(packet.qaScope ?? packet.qa_scope),
         qaRework: parseQaRework(packet.qaRework),
         architectRevision: parseArchitectRevision(packet.architectRevision),
+        architectDependencies: parseArchitectDependencies(packet.architectDependencies),
         storyDevelop: parseStoryDevelop(packet.storyDevelop),
         storyQa: parseStoryQa(packet.storyQa),
         draft: parseDraftPrompt(packet.draft)
@@ -197,6 +199,27 @@ function parseQaBrowser(value) {
         missingTargetReason: optionalString(qaBrowser, "missingTargetReason") ?? optionalString(qaBrowser, "missing_target_reason")
     };
 }
+function parseQaScope(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const qaScope = asObject(value, "qaScope");
+    return {
+        schema_version: requiredNumber(qaScope, "schema_version"),
+        surface: parseOptionalStringArray(qaScope.surface, "qaScope.surface"),
+        required_evidence: parseOptionalStringArray(qaScope.required_evidence, "qaScope.required_evidence"),
+        not_applicable: parseOptionalStringArray(qaScope.not_applicable, "qaScope.not_applicable"),
+        browser_required: optionalBoolean(qaScope, "browser_required") ?? optionalBoolean(qaScope, "browserRequired") ?? false,
+        api_required: optionalBoolean(qaScope, "api_required") ?? optionalBoolean(qaScope, "apiRequired") ?? false,
+        source: optionalString(qaScope, "source"),
+        authority: optionalString(qaScope, "authority"),
+        confidence: optionalString(qaScope, "confidence"),
+        confirmed_by_user: optionalBoolean(qaScope, "confirmed_by_user") ?? optionalBoolean(qaScope, "confirmedByUser"),
+        locked: optionalBoolean(qaScope, "locked"),
+        derived_from: parseOptionalObject(qaScope.derived_from ?? qaScope.derivedFrom, "qaScope.derived_from"),
+        rationale: optionalString(qaScope, "rationale")
+    };
+}
 function parseQaAppLaunchTarget(value) {
     if (value === undefined || value === null) {
         return null;
@@ -260,6 +283,34 @@ function parseArchitectRevision(value) {
         feedback: requiredString(revision, "feedback")
     };
 }
+function parseArchitectDependencies(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const context = asObject(value, "architectDependencies");
+    const prerequisites = context.prerequisites;
+    if (!Array.isArray(prerequisites)) {
+        throw new Error("architectDependencies.prerequisites must be an array.");
+    }
+    return {
+        baseBranch: requiredString(context, "baseBranch").trim(),
+        prerequisites: prerequisites.map((entry, index) => {
+            const prerequisite = asObject(entry, `architectDependencies.prerequisites[${index}]`);
+            return {
+                storyId: requiredString(prerequisite, "storyId").trim(),
+                title: requiredString(prerequisite, "title").trim(),
+                scheduleIndex: optionalNonNegativeInteger(prerequisite, "scheduleIndex"),
+                waveIndex: optionalNonNegativeInteger(prerequisite, "waveIndex"),
+                featureScheduleIndex: optionalNonNegativeInteger(prerequisite, "featureScheduleIndex"),
+                expectedOutput: optionalString(prerequisite, "expectedOutput"),
+                handoffSummary: optionalString(prerequisite, "handoffSummary"),
+                dependencyReason: optionalString(prerequisite, "dependencyReason"),
+                pullRequestNumber: optionalPositiveInteger(prerequisite, "pullRequestNumber"),
+                targetBranch: requiredString(prerequisite, "targetBranch").trim()
+            };
+        })
+    };
+}
 function parseStoryDevelop(value) {
     if (value === undefined || value === null) {
         return null;
@@ -376,6 +427,18 @@ function parseStringArray(value, label) {
         return entry.trim();
     });
 }
+function parseOptionalStringArray(value, label) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    return parseStringArray(value, label);
+}
+function parseOptionalObject(value, label) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    return asObject(value, label);
+}
 function parseArtifacts(value) {
     if (value === undefined || value === null) {
         return [];
@@ -447,6 +510,16 @@ function optionalPositiveInteger(source, key) {
     }
     return value;
 }
+function optionalNonNegativeInteger(source, key) {
+    const value = source[key];
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${key} must be a non-negative integer when provided.`);
+    }
+    return value;
+}
 function requiredNumber(source, key) {
     const value = source[key];
     if (typeof value !== "number" || !Number.isFinite(value)) {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.3-dev.6e59f152916f";
+export declare const forgeBridgeVersion = "0.1.3-dev.ab8510b71f9b";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.3-dev.6e59f152916f";
+export const forgeBridgeVersion = "0.1.3-dev.ab8510b71f9b";

package/dist/worktree/artifact-injector.js

@@ -36,19 +36,29 @@ const DRAFT_OPERATIONAL_SKILLS = new Set([
     "draft-repo-context",
     "draft-graph-context",
     "draft-product-scope",
-    "draft-work-order-plan",
     "draft-critic",
     "draft-proposal"
 ]);
+const DRAFT_WORK_ITEM_OPERATIONAL_SKILLS = new Set([
+    "draft-work-item-plan"
+]);
+const DRAFT_WORK_ORDER_OPERATIONAL_SKILLS = new Set([
+    "draft-work-order-plan"
+]);
 const DRAFT_OPERATIONAL_HOOKS = new Set([
     "draft-intent",
     "draft-repo-context",
     "draft-graph-context",
     "draft-product-scope",
-    "draft-work-order-plan",
     "draft-critic",
     "draft-proposal"
 ]);
+const DRAFT_WORK_ITEM_OPERATIONAL_HOOKS = new Set([
+    "draft-work-item-plan"
+]);
+const DRAFT_WORK_ORDER_OPERATIONAL_HOOKS = new Set([
+    "draft-work-order-plan"
+]);
 export async function injectWorktreeArtifacts(worktreePath, artifacts) {
     for (const artifact of artifacts) {
         await writeArtifact(worktreePath, artifact);
@@ -64,7 +74,7 @@ export function filterArtifactsForLane(artifacts, lane, phase) {
         return artifacts.filter((artifact) => shouldInjectArchitectArtifact(artifact, commandSlug));
     }
     if (normalizedLane === "draft") {
-        return artifacts.filter((artifact) => shouldInjectDraftArtifact(artifact, commandSlug));
+        return artifacts.filter((artifact) => shouldInjectDraftArtifact(artifact, commandSlug, phase));
     }
     return artifacts;
 }
@@ -142,7 +152,7 @@ function shouldInjectArchitectArtifact(artifact, commandSlug) {
             return false;
     }
 }
-function shouldInjectDraftArtifact(artifact, commandSlug) {
+function shouldInjectDraftArtifact(artifact, commandSlug, phase) {
     if (artifact.scope.trim().toLowerCase() !== "operational") {
         return false;
     }
@@ -151,13 +161,36 @@ function shouldInjectDraftArtifact(artifact, commandSlug) {
         case "command":
             return slug === commandSlug;
         case "skill":
-            return DRAFT_OPERATIONAL_SKILLS.has(slug);
+            return DRAFT_OPERATIONAL_SKILLS.has(slug) || draftPhaseSkills(phase).has(slug);
         case "hook":
-            return DRAFT_OPERATIONAL_HOOKS.has(slug);
+            return DRAFT_OPERATIONAL_HOOKS.has(slug) || draftPhaseHooks(phase).has(slug);
         default:
             return false;
     }
 }
+function draftPhaseSkills(phase) {
+    switch (normalizeDraftPhase(phase)) {
+        case "work_order":
+            return DRAFT_WORK_ORDER_OPERATIONAL_SKILLS;
+        case "story":
+            return DRAFT_WORK_ITEM_OPERATIONAL_SKILLS;
+        default:
+            return DRAFT_WORK_ITEM_OPERATIONAL_SKILLS;
+    }
+}
+function draftPhaseHooks(phase) {
+    switch (normalizeDraftPhase(phase)) {
+        case "work_order":
+            return DRAFT_WORK_ORDER_OPERATIONAL_HOOKS;
+        case "story":
+            return DRAFT_WORK_ITEM_OPERATIONAL_HOOKS;
+        default:
+            return DRAFT_WORK_ITEM_OPERATIONAL_HOOKS;
+    }
+}
+function normalizeDraftPhase(phase) {
+    return phase.trim().toLowerCase().replaceAll("-", "_");
+}
 export function buildSpecBody(laneCommand, workItem, phase = "implementation") {
     const prompt = laneCommand.body.replaceAll("{workItemId}", workItem.id);
     return `---

package/dist/worktree/worktree.service.d.ts

@@ -9,7 +9,8 @@ export declare class GitWorktreeService implements WorktreeService {
     private resolveRepoPath;
     private findExistingRepoPath;
     private resolveMatchingRepo;
-    private ensureBaseBranch;
+    private resolveBaseStartPoint;
+    private resetWorktreeToBase;
     private gitRefExists;
     private currentBranch;
     private ensureGitIdentity;

package/dist/worktree/worktree.service.js

@@ -14,7 +14,7 @@ export class GitWorktreeService {
         const baseBranch = normalizeBranchName(request.baseBranch, "develop");
         const repoPath = await this.resolveRepoPath(request.repo, allowedRoot, baseBranch);
         await this.ensureGitIdentity(repoPath);
-        await this.ensureBaseBranch(repoPath, baseBranch);
+        const baseStartPoint = await this.resolveBaseStartPoint(repoPath, baseBranch);
         const shortId = request.workItem.id.replace(/-/g, "").slice(0, 12);
         const kind = safeSegment(request.workItem.kind, "work-item");
         const fallbackWorktreeKey = `${kind}/${shortId}`;
@@ -30,7 +30,7 @@ export class GitWorktreeService {
         const exists = await directoryExists(worktreePath);
         let resolvedWorktreePath;
         if (!exists) {
-            await this.git.run(repoPath, ["worktree", "add", "-B", branchName, worktreePath, baseBranch]);
+            await this.git.run(repoPath, ["worktree", "add", "-B", branchName, worktreePath, baseStartPoint]);
             resolvedWorktreePath = await resolveExistingDirectoryPath(worktreePath);
         }
         else {
@@ -42,6 +42,9 @@ export class GitWorktreeService {
             if (currentBranch !== branchName) {
                 throw new Error(`Existing worktree ${resolvedWorktreePath} is on branch '${currentBranch}', expected '${branchName}'.`);
             }
+            if (shouldResetExistingWorktree(request)) {
+                await this.resetWorktreeToBase(resolvedWorktreePath, baseStartPoint);
+            }
         }
         await this.ensureGitIdentity(resolvedWorktreePath);
         await clearRunArtifactRoots(resolvedWorktreePath, request);
@@ -164,21 +167,27 @@ export class GitWorktreeService {
         const resolved = await resolveExistingDirectoryPath(candidate);
         return isSubPath(allowedRoot, resolved) ? resolved : null;
     }
-    async ensureBaseBranch(repoPath, baseBranch) {
-        if (await this.gitRefExists(repoPath, `refs/heads/${baseBranch}`)) {
-            return;
-        }
+    async resolveBaseStartPoint(repoPath, baseBranch) {
+        const localRef = `refs/heads/${baseBranch}`;
+        const remoteRef = `refs/remotes/origin/${baseBranch}`;
         const origin = await this.git.run(repoPath, ["remote", "get-url", "origin"]).catch(() => "");
-        if (origin.trim().length === 0) {
-            throw new Error(`Base branch '${baseBranch}' was not found in the local checkout.`);
+        if (origin.trim().length > 0) {
+            const fetched = await this.git.run(repoPath, ["fetch", "--prune", "origin"])
+                .then(() => true)
+                .catch(() => false);
+            if (fetched && await this.gitRefExists(repoPath, remoteRef)) {
+                return remoteRef;
+            }
         }
-        await this.git.run(repoPath, ["fetch", "origin", `${baseBranch}:refs/remotes/origin/${baseBranch}`]).catch(() => "");
-        if (await this.gitRefExists(repoPath, `refs/remotes/origin/${baseBranch}`)) {
-            await this.git.run(repoPath, ["branch", baseBranch, `refs/remotes/origin/${baseBranch}`]);
-            return;
+        if (await this.gitRefExists(repoPath, localRef)) {
+            return localRef;
         }
         throw new Error(`Base branch '${baseBranch}' was not found locally or on origin.`);
     }
+    async resetWorktreeToBase(worktreePath, baseStartPoint) {
+        await this.git.run(worktreePath, ["reset", "--hard", baseStartPoint]);
+        await this.git.run(worktreePath, ["clean", "-fd"]);
+    }
     async gitRefExists(repoPath, gitRef) {
         return this.git.run(repoPath, ["show-ref", "--verify", "--quiet", gitRef]).then(() => true).catch(() => false);
     }
@@ -269,6 +278,17 @@ function normalizeOwnerType(value) {
     }
     return null;
 }
+function shouldResetExistingWorktree(request) {
+    const lane = request.lane.trim().toLowerCase();
+    const phase = request.phase.trim().toLowerCase().replace(/-/g, "_");
+    if (lane === "develop" && (phase === "implementation" || phase === "self_review" || phase === "validation")) {
+        return false;
+    }
+    if (lane === "qa" || phase === "qa") {
+        return false;
+    }
+    return true;
+}
 function qaReworkPacketFileName(packetPath) {
     const normalized = packetPath.trim().replace(/\\/g, "/");
     const fileName = normalized.split("/").filter(Boolean).at(-1) ?? "";

package/package.json

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