@loucompanion/forge-bridge 0.1.3-dev.04a84914da09 → 0.1.3-dev.b6be5e7f9668

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",
@@ -391,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") {
@@ -398,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.`;
@@ -432,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") {
@@ -461,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.`;
 }
 export function completionPromptForDebugCycle(currentGate = "debug_repro") {
     return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
@@ -514,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);
@@ -765,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);
@@ -828,9 +866,23 @@ function normalizeDraftStatus(value) {
     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`);
@@ -843,6 +895,37 @@ function isDecompositionDraftJson(draftJson) {
         && 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) {
@@ -1018,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({
@@ -1065,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,
@@ -1526,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) {
@@ -1657,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.`;
     }
@@ -1680,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",
@@ -1702,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);
     }
@@ -1891,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],
@@ -1920,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",
@@ -1999,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({
@@ -2154,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" },
@@ -2433,6 +2637,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.`);
@@ -2454,6 +2659,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);
@@ -2688,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.");
     }
@@ -3197,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) {

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

@@ -2469,18 +2469,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,6 +13,7 @@ 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 storyDevelop?: DispatchStoryDevelopContext | null;
@@ -32,6 +33,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;

package/dist/session/session.types.js

@@ -20,6 +20,7 @@ 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),
         storyDevelop: parseStoryDevelop(packet.storyDevelop),
@@ -197,6 +198,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;
@@ -376,6 +398,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 [];

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.3-dev.04a84914da09";
+export declare const forgeBridgeVersion = "0.1.3-dev.b6be5e7f9668";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.3-dev.04a84914da09";
+export const forgeBridgeVersion = "0.1.3-dev.b6be5e7f9668";

package/package.json

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