@ivorycanvas/qamap 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.4.3 - 2026-07-14
+
+### Added
+
+- Added evidence-ranked QA scenario routing. Each intent-backed scenario is now classified as `required`, `recommended`, or `review-only` from its priority, confidence, review requirement, and exact diff sources instead of treating every inferred path as equally actionable.
+- Added scenario-level automation receipts to human, JSON, and agent output. QAMap reports whether each selected scenario was `compiled`, `partial`, `not-compiled`, or `review-only`, including mapped step and assertion counts plus a concrete blocker when automation is incomplete.
+- Added benchmark contracts for selected-to-compiled coverage so public fixtures fail CI when required QA is proposed without a traceable automation handoff.
+
+### Changed
+
+- E2E readiness now includes required scenario compilation gaps. A syntactically valid draft cannot be promoted as runnable evidence when a required QA scenario was omitted or only partially mapped.
+- Playwright failure-path generation now requires an unchanged mockable endpoint boundary, an action selector related to the changed flow, and a repository-observed failure outcome before it emits executable setup, action, and assertion steps.
+- Contributor guidance now requires domain-neutral product rules, positive evidence combinations, negative controls, and unrelated fixture coverage before a specialized inference can enter the shared engine.
+
+### Fixed
+
+- Unrelated controls can no longer be reused merely because they are the first stable selector near a changed endpoint.
+- Maestro automation receipts now reflect commands and assertions that were actually generated instead of assuming coverage from the selected runner alone.
+
 ## 0.4.2 - 2026-07-13
 
 ### Added

package/README.md

@@ -4,6 +4,8 @@
 [![npm version](https://img.shields.io/npm/v/@ivorycanvas/qamap.svg)](https://www.npmjs.com/package/@ivorycanvas/qamap)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+![QAMap: local PR QA design from commits and diffs](docs/assets/qamap-cover.png)
+
 **A local, zero-LLM PR QA designer. QAMap turns commit intent and code diffs into evidence-backed behavior lifecycles, missing QA, and deterministic automation drafts. No cloud. No source upload. No token.**
 
 QAMap reads commit subjects and bodies, git changes, project structure, selectors, existing tests, and optional repo QA memory, then answers the question every reviewer asks: *"What behavior did this PR intend to change, how does that behavior move through the product, and what should we verify before merge?"* Playwright, Maestro, and manual checklists are output adapters after that judgment, not the product recommendation itself.
@@ -26,7 +28,7 @@ Run one read-only command on a branch. A manifest and test runner are not requir
 pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD
 ```
 
-The report starts with the inferred behavior and keeps each proposed scenario connected to the commit or exact base/head diff line that caused it. Removed guards and validation remain visible as base-side evidence; each source is labeled `direct`, `supporting`, or `contextual` (trimmed from the committed lifecycle benchmark):
+The report starts with the inferred behavior and keeps each proposed scenario connected to the commit or exact base/head diff line that caused it. Removed guards and validation remain visible as base-side evidence; each source is labeled `direct`, `supporting`, or `contextual`. QAMap then shows two separate receipts: why the scenario was routed as `required`, `recommended`, or `review-only`, and whether the E2E adapter compiled it fully, partially, or not at all (trimmed from the committed lifecycle benchmark):
 
 ```txt
 Change intent: Submit notification preferences and show the saved state [high]
@@ -34,15 +36,21 @@ Behavior lifecycle: trigger -> state-change -> side-effect -> observable-outcome
 
 QA scenarios:
 - [critical] changed preference lifecycle (confidence: high)
+  - Routing: required — 3 supporting diff hunks
+  - E2E mapping: partial — steps 0/3, assertions 1/1
   - Source: src/pages/preferences.tsx:17, symbol onClick [supporting, head]
   - Source: src/pages/preferences.tsx:8, symbol setSaved [supporting, head]
   - Assert: the saved state becomes observable
 - [recommended] failure, timeout, and retry handling (confidence: medium; review required)
+  - Routing: recommended — 1 supporting diff hunk
+  - E2E mapping: not compiled — no deterministic failure compiler matched all required evidence
   - Source: src/pages/preferences.tsx:7, symbol fetch [supporting, head]
   - Assert: retries do not duplicate requests or side effects
 
 Optional automation:
 - Adapter candidate: Playwright
+- Scenario routing: 2 required, 2 recommended, 0 review-only
+- E2E mapping: 0 compiled, 1 partial, 3 not compiled
 - qamap e2e draft . --base origin/main --head HEAD
 ```
 
@@ -76,6 +84,7 @@ One minified JSON object (`schema: qamap.qa`) with change intents, lifecycle sta
 - **Judgment first, generation second.** Deciding *what deserves testing* for a given change is the missing layer. QAMap makes that judgment statically, deterministically, and locally for free.
 - **The repo remembers.** Team QA knowledge lives in `.qamap/manifest.yaml`, reviewed once and reused on every PR — instead of re-prompting an agent each session.
 - **Honest output.** Drafts state what blocks them from being trusted; changed endpoints are observed, never mocked away; generated specs never assert what cannot pass. Configuration, docs, generated artifacts, and changed tests stay in verification mode instead of fabricating a product-journey E2E.
+- **Selected is not compiled.** Every evidence-routed scenario keeps a static automation receipt. Required behavior that remains partial or not compiled lowers readiness instead of being hidden behind a smoke test. `compiled` still does not claim the application was executed.
 
 Positioning against recorders, LLM test generation, and impact-analysis tools: [where QAMap fits](docs/adoption.md#where-qamap-fits).
 

package/dist/e2e.d.ts

@@ -8,6 +8,7 @@ import type { LocalHistoryReference } from "./history.js";
 import type { CoverageEvidence, TestSuiteSummary } from "./test-evidence.js";
 import type { BehaviorGraph } from "./behavior.js";
 import type { BehaviorLifecycleStage, ChangeIntentAnalysis, ChangeIntentConfidence, ChangeIntentEvidence, IntentQaScenario } from "./change-intent.js";
+import type { QaScenarioDecision } from "./scenario-routing.js";
 export type E2eProjectType = "expo-react-native" | "react-native" | "web" | "api-service" | "design-tokens" | "data-catalog" | "cli" | "unknown";
 export type E2eRunnerName = "maestro" | "playwright" | "manual";
 export type E2eFlowKind = "ui" | "api" | "state" | "content" | "config" | "test-evidence" | "documentation" | "generated-artifact" | "artifact" | "catalog" | "command" | "domain" | "changed-file";
@@ -247,6 +248,23 @@ export interface E2eDraftFile {
     intentConfidence?: ChangeIntentConfidence;
     lifecycle?: BehaviorLifecycleStage[];
     qaScenarios?: IntentQaScenario[];
+    scenarioAutomation?: E2eScenarioAutomationReceipt[];
+}
+export type E2eScenarioAutomationStatus = "compiled" | "partial" | "not-compiled" | "review-only";
+export interface E2eScenarioAutomationReceipt {
+    scenarioId: string;
+    title: string;
+    kind: IntentQaScenario["kind"];
+    priority: IntentQaScenario["priority"];
+    decision: QaScenarioDecision;
+    status: E2eScenarioAutomationStatus;
+    requiredSourceCount: number;
+    referenceSourceCount: number;
+    mappedSteps: number;
+    totalSteps: number;
+    mappedAssertions: number;
+    totalAssertions: number;
+    blockers: string[];
 }
 export type E2eDraftActionKind = "assertion" | "fixture" | "manifest" | "runner" | "selector" | "setup" | "validation";
 export type E2eDraftActionPriority = "required" | "recommended";
@@ -299,6 +317,13 @@ export interface E2eDraftReadinessSummary {
     totalTodos: number;
     filesWithExecutionBlockers: number;
     totalExecutionBlockers: number;
+    requiredScenarios: number;
+    recommendedScenarios: number;
+    reviewOnlyScenarios: number;
+    compiledScenarios: number;
+    partialScenarios: number;
+    notCompiledScenarios: number;
+    requiredScenarioGaps: number;
     topBlockers: string[];
 }
 export declare function formatDraftReadinessStage(summary: Pick<E2eDraftReadinessSummary, "level" | "score">): string;

package/dist/e2e.js

@@ -14,6 +14,7 @@ import { loadCoreFlowManifest, matchCoreFlows } from "./flows.js";
 import { loadVerificationManifest, matchVerificationManifest } from "./manifest.js";
 import { collectTestSuiteInventory, evaluateFlowCoverageEvidence, summarizeTestSuiteInventory, } from "./test-evidence.js";
 import { addedDiffTextFromEvidence, collectAddedDiffEvidence, collectAddedDiffText, generateTestPlan, } from "./test-plan.js";
+import { routeQaScenario } from "./scenario-routing.js";
 import { TOOL_NAME, VERSION } from "./version.js";
 // Human reports render readiness as a stage on a fixed journey instead of a
 // verdict, so a first run reads as "you are at the start", not "you failed".
@@ -222,8 +223,9 @@ export async function generateE2eDraft(rootInput, options = {}) {
         const content = shouldSkip ? ((await readTextIfExists(filePath)) ?? "") : draftContentForFlow(plan, flow, runner, addedDiffText);
         const todoCount = countTodos(content);
         const selfCheck = evaluateDraftSelfCheck(plan, flow, runner, content, todoCount);
-        const actionItems = buildDraftActionItems(plan, flow, runner, validationSummary, promotionGuidance, selfCheck);
-        const executionBlockers = draftExecutionBlockers(plan, flow, runner, selfCheck);
+        const scenarioAutomation = buildScenarioAutomationReceipts(flow, runner, content, selfCheck);
+        const actionItems = buildDraftActionItems(plan, flow, runner, validationSummary, promotionGuidance, selfCheck, scenarioAutomation);
+        const executionBlockers = draftExecutionBlockers(plan, flow, runner, selfCheck, scenarioAutomation);
         const runnableStatus = draftRunnableStatus(plan, flow, runner, executionBlockers, selfCheck);
         const fileDetails = draftFileDetails(flow);
         if (dryRun) {
@@ -243,6 +245,7 @@ export async function generateE2eDraft(rootInput, options = {}) {
                 runnableStatus,
                 executionBlockers,
                 selfCheck,
+                scenarioAutomation,
                 todoCount,
                 entrypointCount: flow.entrypoints.length,
                 primaryEntrypoint: primaryEntrypointLabel(flow),
@@ -274,6 +277,7 @@ export async function generateE2eDraft(rootInput, options = {}) {
                 runnableStatus,
                 executionBlockers,
                 selfCheck,
+                scenarioAutomation,
                 todoCount,
                 entrypointCount: flow.entrypoints.length,
                 primaryEntrypoint: primaryEntrypointLabel(flow),
@@ -304,6 +308,7 @@ export async function generateE2eDraft(rootInput, options = {}) {
             runnableStatus,
             executionBlockers,
             selfCheck,
+            scenarioAutomation,
             todoCount,
             entrypointCount: flow.entrypoints.length,
             primaryEntrypoint: primaryEntrypointLabel(flow),
@@ -1019,7 +1024,7 @@ function buildDraftPromotionGuidance(flow) {
         action: "Create a domain or flow manifest after the first real user journey is identified.",
     };
 }
-function buildDraftActionItems(plan, flow, runner, validationSummary, promotionGuidance, selfCheck) {
+function buildDraftActionItems(plan, flow, runner, validationSummary, promotionGuidance, selfCheck, scenarioAutomation = []) {
     const items = [];
     const verificationOnly = isVerificationOnlyFlow(flow);
     const runnerGap = runnerSetupGap(plan, runner);
@@ -1061,6 +1066,14 @@ function buildDraftActionItems(plan, flow, runner, validationSummary, promotionG
     if (!verificationOnly && flow.steps.length > 0 && draftNeedsAssertionWork(selfCheck)) {
         items.push(draftActionItem("assertion", "required", "Replace starter smoke assertions with domain assertions", `Preserve the success signal "${flow.languageBrief.successSignal}" while replacing weak fallback interactions and generic expects.`));
     }
+    const requiredScenarioGaps = scenarioAutomation.filter((receipt) => receipt.decision === "required" && receipt.status !== "compiled");
+    if (!verificationOnly && requiredScenarioGaps.length > 0) {
+        const details = requiredScenarioGaps.slice(0, 3).map((receipt) => {
+            const blocker = receipt.blockers[0] ?? "the selected scenario has no executable action and assertion mapping";
+            return `"${receipt.title}" is ${receipt.status}: ${blocker}`;
+        });
+        items.push(draftActionItem("assertion", "required", "Compile required QA scenarios into executable coverage", details.join(" ")));
+    }
     if (!verificationOnly && selfCheck?.status === "fail") {
         items.push(draftActionItem("validation", "required", "Resolve generated draft self-check", selfCheck.blockers[0] ?? selfCheck.summary));
     }
@@ -1223,13 +1236,22 @@ function summarizeDraftReadiness(files, actionSummary) {
     const totalTodos = files.reduce((sum, file) => sum + (file.todoCount ?? 0), 0);
     const filesWithExecutionBlockers = files.filter((file) => (file.executionBlockers?.length ?? 0) > 0).length;
     const totalExecutionBlockers = files.reduce((sum, file) => sum + (file.executionBlockers?.length ?? 0), 0);
+    const scenarioAutomation = files.flatMap((file) => file.scenarioAutomation ?? []);
+    const requiredScenarios = scenarioAutomation.filter((receipt) => receipt.decision === "required").length;
+    const recommendedScenarios = scenarioAutomation.filter((receipt) => receipt.decision === "recommended").length;
+    const reviewOnlyScenarios = scenarioAutomation.filter((receipt) => receipt.decision === "review-only").length;
+    const compiledScenarios = scenarioAutomation.filter((receipt) => receipt.status === "compiled").length;
+    const partialScenarios = scenarioAutomation.filter((receipt) => receipt.status === "partial").length;
+    const notCompiledScenarios = scenarioAutomation.filter((receipt) => receipt.status === "not-compiled").length;
+    const requiredScenarioGaps = scenarioAutomation.filter((receipt) => receipt.decision === "required" && receipt.status !== "compiled").length;
     const topBlockers = topDraftReadinessBlockers(files);
     const statusScore = (runnableCandidates * 100 + nearRunnable * 75 + reviewOnly * 35) / totalFiles;
     const selfCheckPenalty = (selfCheckWarning * 10 + selfCheckFail * 25) / totalFiles;
     const requiredActionPenalty = Math.min(25, actionSummary.required * 3);
     const todoPenalty = Math.min(15, totalTodos);
     const blockerPenalty = Math.min(20, filesWithExecutionBlockers * 5);
-    const score = clampReadinessScore(Math.round(statusScore - selfCheckPenalty - requiredActionPenalty - todoPenalty - blockerPenalty));
+    const scenarioPenalty = Math.min(20, requiredScenarioGaps * 4);
+    const score = clampReadinessScore(Math.round(statusScore - selfCheckPenalty - requiredActionPenalty - todoPenalty - blockerPenalty - scenarioPenalty));
     const level = draftReadinessLevel(score, actionSummary.required, selfCheckFail, reviewOnly);
     return {
         score,
@@ -1245,6 +1267,13 @@ function summarizeDraftReadiness(files, actionSummary) {
         totalTodos,
         filesWithExecutionBlockers,
         totalExecutionBlockers,
+        requiredScenarios,
+        recommendedScenarios,
+        reviewOnlyScenarios,
+        compiledScenarios,
+        partialScenarios,
+        notCompiledScenarios,
+        requiredScenarioGaps,
         topBlockers,
     };
 }
@@ -1922,9 +1951,13 @@ function appendChangeIntentMarkdown(lines, analysis) {
             lines.push(`${index + 1}. **${stage.kind}**: ${escapeMarkdownInline(stage.label)} [${stage.confidence}]`);
         });
         lines.push("");
-        lines.push("Required QA scenarios:");
+        lines.push("Routed QA scenarios:");
         for (const scenario of intent.scenarios.slice(0, 4)) {
+            const routing = routeQaScenario(scenario);
             lines.push(`- **${scenario.priority} / ${scenario.kind}**: ${escapeMarkdownInline(scenario.title)}`);
+            lines.push(`  - Routing: ${routing.decision} - ${escapeMarkdownInline(routing.reason)}`);
+            lines.push(`  - Evidence: ${routing.requiredEvidence.length} required diff source${routing.requiredEvidence.length === 1 ? "" : "s"}, ` +
+                `${routing.referenceEvidence.length} reference source${routing.referenceEvidence.length === 1 ? "" : "s"}`);
             for (const step of scenario.steps.slice(0, 3)) {
                 lines.push(`  - Step: ${escapeMarkdownInline(step)}`);
             }
@@ -2000,6 +2033,11 @@ export function formatMarkdownE2eDraft(result) {
     lines.push(`- Self-checks: ${result.readinessSummary.selfCheckPass} pass, ${result.readinessSummary.selfCheckWarning} warning, ${result.readinessSummary.selfCheckFail} fail`);
     lines.push(`- TODO markers: ${result.readinessSummary.totalTodos} across ${result.readinessSummary.filesWithTodos} file${result.readinessSummary.filesWithTodos === 1 ? "" : "s"}`);
     lines.push(`- Execution blockers: ${result.readinessSummary.totalExecutionBlockers} across ${result.readinessSummary.filesWithExecutionBlockers} file${result.readinessSummary.filesWithExecutionBlockers === 1 ? "" : "s"}`);
+    lines.push(`- Scenario routing: ${result.readinessSummary.requiredScenarios} required, ` +
+        `${result.readinessSummary.recommendedScenarios} recommended, ${result.readinessSummary.reviewOnlyScenarios} review-only`);
+    lines.push(`- Scenario automation: ${result.readinessSummary.compiledScenarios} compiled, ` +
+        `${result.readinessSummary.partialScenarios} partial, ${result.readinessSummary.notCompiledScenarios} not compiled; ` +
+        `${result.readinessSummary.requiredScenarioGaps} required gap${result.readinessSummary.requiredScenarioGaps === 1 ? "" : "s"}`);
     if (result.readinessSummary.topBlockers.length > 0) {
         lines.push("- Top blockers:");
         for (const blocker of result.readinessSummary.topBlockers.slice(0, 3)) {
@@ -2042,6 +2080,22 @@ export function formatMarkdownE2eDraft(result) {
         }
         lines.push("");
     }
+    const filesWithScenarioAutomation = result.files.filter((file) => (file.scenarioAutomation?.length ?? 0) > 0);
+    if (filesWithScenarioAutomation.length > 0) {
+        lines.push("## Scenario Automation Receipts");
+        lines.push("");
+        for (const file of filesWithScenarioAutomation) {
+            lines.push(`- \`${escapeMarkdownInline(file.flowTitle)}\` (${escapeMarkdownInline(file.path)})`);
+            for (const receipt of file.scenarioAutomation ?? []) {
+                lines.push(`  - [${receipt.decision}] ${escapeMarkdownInline(receipt.title)}: ${receipt.status} ` +
+                    `(steps ${receipt.mappedSteps}/${receipt.totalSteps}, assertions ${receipt.mappedAssertions}/${receipt.totalAssertions})`);
+                for (const blocker of receipt.blockers.slice(0, 2)) {
+                    lines.push(`    - Blocker: ${escapeMarkdownInline(blocker)}`);
+                }
+            }
+        }
+        lines.push("");
+    }
     const filesWithActionItems = result.files.filter((file) => (file.actionItems?.length ?? 0) > 0);
     if (filesWithActionItems.length > 0) {
         lines.push("## Draft Action Items");
@@ -5421,6 +5475,104 @@ function draftFlowSource(flow) {
 function domainScenarioForFlow(flow) {
     return flow.domainScenario;
 }
+function buildScenarioAutomationReceipts(flow, runner, content, selfCheck) {
+    const scenarios = flow.qaScenarios ?? [];
+    if (scenarios.length === 0) {
+        return [];
+    }
+    const routedPlaywrightScenarios = runner === "playwright" ? playwrightRoutedScenarioDrafts(flow) : [];
+    const primaryContent = content.split("// Routed QA scenario:", 1)[0] ?? content;
+    return scenarios.map((scenario) => {
+        const selection = routeQaScenario(scenario);
+        const base = {
+            scenarioId: scenario.id,
+            title: scenario.title,
+            kind: scenario.kind,
+            priority: scenario.priority,
+            decision: selection.decision,
+            requiredSourceCount: selection.requiredEvidence.length,
+            referenceSourceCount: selection.referenceEvidence.length,
+            totalSteps: scenario.steps.length,
+            totalAssertions: scenario.assertions.length,
+        };
+        if (selection.decision === "review-only" || runner === "manual") {
+            return {
+                ...base,
+                status: "review-only",
+                mappedSteps: 0,
+                mappedAssertions: 0,
+                blockers: [
+                    selection.decision === "review-only"
+                        ? selection.reason
+                        : "The repository has no executable browser or device adapter for this scenario, so it remains review evidence.",
+                ],
+            };
+        }
+        if (scenario.kind !== "primary") {
+            const routed = routedPlaywrightScenarios.find((candidate) => candidate.scenarioId === scenario.id);
+            if (routed) {
+                const fullyMapped = routed.mappedSteps >= scenario.steps.length &&
+                    routed.mappedAssertions >= scenario.assertions.length;
+                const blockers = [
+                    routed.mappedSteps < scenario.steps.length
+                        ? `${scenario.steps.length - routed.mappedSteps} selected action step${scenario.steps.length - routed.mappedSteps === 1 ? "" : "s"} remain outside executable coverage.`
+                        : undefined,
+                    routed.mappedAssertions < scenario.assertions.length
+                        ? `${scenario.assertions.length - routed.mappedAssertions} selected assertion${scenario.assertions.length - routed.mappedAssertions === 1 ? "" : "s"} remain outside executable coverage.`
+                        : undefined,
+                ].filter((value) => Boolean(value));
+                return {
+                    ...base,
+                    status: fullyMapped ? "compiled" : "partial",
+                    mappedSteps: routed.mappedSteps,
+                    mappedAssertions: routed.mappedAssertions,
+                    blockers,
+                };
+            }
+            return {
+                ...base,
+                status: "not-compiled",
+                mappedSteps: 0,
+                mappedAssertions: 0,
+                blockers: [
+                    `No deterministic ${scenario.kind} compiler matched a repository entrypoint, action locator, fixture boundary, and observable outcome.`,
+                ],
+            };
+        }
+        return primaryScenarioAutomationReceipt(base, runner, primaryContent, scenario, selfCheck);
+    });
+}
+function primaryScenarioAutomationReceipt(base, runner, content, scenario, selfCheck) {
+    const mappedSteps = scenario.steps.filter((step) => content.includes(`Step intent: ${step}`)).length;
+    const assertionStepMarkers = scenario.assertions.filter((assertion) => content.includes(`Step intent: ${assertion}`)).length;
+    const executableAssertions = runner === "maestro"
+        ? content.match(/^- assertVisible:\s+(?!["']\.\*["']$).+$/gm)?.length ?? 0
+        : content.match(/await expect\((?!page\.locator\(["']body["']\))/g)?.length ?? 0;
+    const mappedAssertions = Math.min(assertionStepMarkers, executableAssertions);
+    const fallbackCount = content.match(/QAMap could not infer a stable (?:locator|Maestro selector)/g)?.length ?? 0;
+    const blockers = [];
+    if (selfCheck?.status === "fail") {
+        blockers.push(selfCheck.blockers[0] ?? selfCheck.summary);
+    }
+    if (mappedSteps < scenario.steps.length) {
+        blockers.push(`${scenario.steps.length - mappedSteps} selected action step${scenario.steps.length - mappedSteps === 1 ? "" : "s"} did not map to generated commands.`);
+    }
+    if (mappedAssertions < scenario.assertions.length) {
+        blockers.push(`${scenario.assertions.length - mappedAssertions} selected assertion${scenario.assertions.length - mappedAssertions === 1 ? "" : "s"} did not map to an observable generated assertion.`);
+    }
+    if (fallbackCount > 0) {
+        blockers.push(`${fallbackCount} generated step${fallbackCount === 1 ? "" : "s"} still use fallback smoke behavior.`);
+    }
+    const fullyMapped = selfCheck?.status !== "fail" && blockers.length === 0;
+    const partiallyMapped = mappedSteps > 0 || mappedAssertions > 0;
+    return {
+        ...base,
+        status: fullyMapped ? "compiled" : partiallyMapped ? "partial" : "not-compiled",
+        mappedSteps,
+        mappedAssertions,
+        blockers: uniqueStrings(blockers),
+    };
+}
 function draftStability(plan, flow) {
     const needsSelector = !isVerificationOnlyFlow(flow) && flow.missingTestability.length > 0;
     const needsSetup = plan.missingTestability.some((gap) => /No \.maestro|No Playwright config/i.test(gap));
@@ -5435,7 +5587,7 @@ function draftStability(plan, flow) {
     }
     return "ready";
 }
-function draftExecutionBlockers(plan, flow, runner, selfCheck) {
+function draftExecutionBlockers(plan, flow, runner, selfCheck, scenarioAutomation = []) {
     const verificationOnly = isVerificationOnlyFlow(flow);
     const blockers = verificationOnly ? [] : [...plan.executionProfile.blockers];
     if (!verificationOnly && runner !== "manual" && flow.entrypoints.length === 0) {
@@ -5452,6 +5604,12 @@ function draftExecutionBlockers(plan, flow, runner, selfCheck) {
     if (selfCheck?.status === "fail") {
         blockers.push(...selfCheck.blockers);
     }
+    if (!verificationOnly && runner !== "manual") {
+        for (const receipt of scenarioAutomation.filter((item) => item.decision === "required" && item.status !== "compiled")) {
+            blockers.push(`Required QA scenario "${receipt.title}" is ${receipt.status}: ` +
+                (receipt.blockers[0] ?? "no executable action and assertion mapping was produced."));
+        }
+    }
     return uniqueStrings(blockers).slice(0, 8);
 }
 function draftRunnableStatus(plan, flow, runner, executionBlockers, selfCheck) {
@@ -5738,6 +5896,9 @@ function buildMaestroDraft(plan, flow) {
     appendManifestMatchComments(lines, flow, "#");
     for (const step of draftExecutableSteps(flow, "maestro")) {
         const command = maestroCommandForStep(step, selectorQueue);
+        if (maestroCommandProvidesCoverage(command)) {
+            lines.push(`# Step intent: ${step}`);
+        }
         lines.push(...formatMaestroCommand(command));
     }
     appendDomainScenarioComments(lines, flow, "#");
@@ -5766,6 +5927,12 @@ function buildMaestroDraft(plan, flow) {
     lines.push("");
     return lines.join("\n");
 }
+function maestroCommandProvidesCoverage(command) {
+    if (command.kind === "comment") {
+        return false;
+    }
+    return command.kind !== "assertVisible" || command.value !== quoteYaml(".*");
+}
 function maestroCommandForStep(step, selectors) {
     if (isGestureStep(step)) {
         return {
@@ -5862,6 +6029,11 @@ function buildPlaywrightDraft(plan, flow, addedDiffText = {}) {
     appendDomainScenarioComments(lines, flow, "  //");
     appendPlaywrightCoverageComments(lines, flow);
     lines.push("});");
+    for (const routedScenario of playwrightRoutedScenarioDrafts(flow)) {
+        lines.push("");
+        lines.push(`// Routed QA scenario: ${routedScenario.scenarioId}`);
+        lines.push(...routedScenario.lines);
+    }
     if (flow.missingTestability.length > 0) {
         lines.push("");
         lines.push("// Testability gaps to address before this spec is stable:");
@@ -5886,6 +6058,73 @@ function buildPlaywrightDraft(plan, flow, addedDiffText = {}) {
     lines.push("");
     return lines.join("\n");
 }
+function playwrightRoutedScenarioDrafts(flow) {
+    const routeEntrypoint = primaryRouteEntrypoint(flow);
+    if (!routeEntrypoint) {
+        return [];
+    }
+    const routeDraft = buildPlaywrightRouteDraft(routeEntrypoint.value, flow.entrypoints);
+    if (routeDraft.params.length > 0) {
+        return [];
+    }
+    const endpoint = playwrightFailureMockEndpoint(flow);
+    if (!endpoint) {
+        return [];
+    }
+    const drafts = [];
+    for (const scenario of flow.qaScenarios ?? []) {
+        const selection = routeQaScenario(scenario);
+        if (scenario.kind !== "failure" || selection.decision === "review-only") {
+            continue;
+        }
+        const scenarioText = [scenario.title, ...scenario.steps, ...scenario.edgeCases].join(" ");
+        if (!isFailurePathStep(scenarioText)) {
+            continue;
+        }
+        const selectorContext = `${flow.title} ${scenarioText}`;
+        const actionSelector = routedScenarioSelector(flow.selectors, selectorContext, (selector) => !isInputSelector(selector) && selectorCanDriveInteraction(selector));
+        const outcomeSelector = routedScenarioSelector(flow.selectors, selectorContext, (selector) => selectorCanSupportAssertion(selector) && isFailureOutcomeText(selector.value));
+        if (!actionSelector || !outcomeSelector) {
+            continue;
+        }
+        const testName = `${flow.title}: ${scenario.title}`.replaceAll('"', "'");
+        const routePattern = playwrightMockRoutePattern(endpoint);
+        const status = failureResponseStatus(scenarioText);
+        drafts.push({
+            scenarioId: scenario.id,
+            mappedSteps: Math.min(1, scenario.steps.length),
+            mappedAssertions: Math.min(1, scenario.assertions.length),
+            lines: [
+                `test("${testName}", async ({ page }) => {`,
+                `  await page.route("${quoteJs(routePattern)}", async (route) => {`,
+                "    await route.fulfill({",
+                `      status: ${status},`,
+                '      contentType: "application/json",',
+                '      body: JSON.stringify({ error: "QAMap simulated failure" }),',
+                "    });",
+                "  });",
+                `  await page.goto(${routeDraft.expression});`,
+                `  await ${playwrightLocator(actionSelector)}.click();`,
+                `  await expect(${playwrightLocator(outcomeSelector)}).toBeVisible();`,
+                "});",
+            ],
+        });
+    }
+    return drafts;
+}
+function routedScenarioSelector(selectors, context, predicate) {
+    const keywords = keywordsForStep(context);
+    return selectors
+        .filter(predicate)
+        .map((selector) => ({
+        selector,
+        score: keywords.filter((keyword) => selector.value.toLowerCase().includes(keyword)).length,
+    }))
+        .filter((candidate) => candidate.score > 0)
+        .sort((left, right) => right.score - left.score ||
+        Number(Boolean(right.selector.addedInDiff)) - Number(Boolean(left.selector.addedInDiff)) ||
+        left.selector.value.localeCompare(right.selector.value))[0]?.selector;
+}
 function draftExecutableSteps(flow, runner) {
     const executableSteps = flow.steps.filter((step) => !shouldSkipDraftStep(step, flow, runner));
     return executableSteps.length > 0 ? executableSteps : flow.steps;