@ivorycanvas/qamap 0.4.1 → 0.4.3

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,9 +223,10 @@ 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, validationSummary, selfCheck);
-        const runnableStatus = draftRunnableStatus(plan, flow, runner, validationSummary, executionBlockers, 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) {
             files.push({
@@ -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),
@@ -331,7 +336,7 @@ export async function generateE2eDraft(rootInput, options = {}) {
         files,
         actionSummary,
         readinessSummary: summarizeDraftReadiness(files, actionSummary),
-        nextSteps: buildDraftNextSteps(plan, runner),
+        nextSteps: buildDraftNextSteps(plan, runner, files),
     };
 }
 function buildCoverageTargets(kind, files, runner) {
@@ -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));
     }
@@ -1108,7 +1121,8 @@ function draftNeedsAssertionWork(selfCheck) {
         return true;
     }
     return selfCheck.checks.some((check) => (check.name === "Unresolved placeholders" && check.status !== "pass") ||
-        (check.name === "TODO comments" && check.status !== "pass"));
+        (check.name === "TODO comments" && check.status !== "pass") ||
+        (check.name === "Domain assertions" && check.status !== "pass"));
 }
 function runnerSetupGap(plan, runner) {
     if (runner === "playwright") {
@@ -1222,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,
@@ -1244,6 +1267,13 @@ function summarizeDraftReadiness(files, actionSummary) {
         totalTodos,
         filesWithExecutionBlockers,
         totalExecutionBlockers,
+        requiredScenarios,
+        recommendedScenarios,
+        reviewOnlyScenarios,
+        compiledScenarios,
+        partialScenarios,
+        notCompiledScenarios,
+        requiredScenarioGaps,
         topBlockers,
     };
 }
@@ -1921,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)}`);
             }
@@ -1999,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)) {
@@ -2041,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");
@@ -5420,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));
@@ -5434,7 +5587,7 @@ function draftStability(plan, flow) {
     }
     return "ready";
 }
-function draftExecutionBlockers(plan, flow, runner, validationSummary, 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) {
@@ -5446,15 +5599,20 @@ function draftExecutionBlockers(plan, flow, runner, validationSummary, selfCheck
     if (!verificationOnly && flow.fixtureReadiness.status === "missing") {
         blockers.push(flow.fixtureReadiness.nextActions[0] ?? flow.fixtureReadiness.reason);
     }
-    if (validationSummary.blockingGapCount > 0) {
-        blockers.push(`${validationSummary.blockingGapCount} blocking validation gap${validationSummary.blockingGapCount === 1 ? "" : "s"} ${validationSummary.blockingGapCount === 1 ? "remains" : "remain"}.`);
-    }
+    // Missing validation evidence describes the repository before this draft exists.
+    // Keep it as PR guidance, but do not treat it as proof that the generated file cannot execute.
     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, validationSummary, executionBlockers, selfCheck) {
+function draftRunnableStatus(plan, flow, runner, executionBlockers, selfCheck) {
     if (runner === "manual" || isVerificationOnlyFlow(flow)) {
         return "review-only";
     }
@@ -5462,9 +5620,8 @@ function draftRunnableStatus(plan, flow, runner, validationSummary, executionBlo
         return "review-only";
     }
     if (executionBlockers.length === 0 &&
-        validationSummary.blockingGapCount === 0 &&
         flow.missingTestability.length === 0 &&
-        (flow.fixtureReadiness.status === "ready" || flow.fixtureReadiness.status === "not-needed") &&
+        flow.fixtureReadiness.status !== "missing" &&
         selfCheck?.status === "pass") {
         return "runnable-candidate";
     }
@@ -5502,6 +5659,10 @@ function evaluatePlaywrightDraftSelfCheck(plan, flow, content, todoCount) {
     checks.push(draftSelfCheckItem("TODO comments", todoCount === 0 ? "pass" : "warning", todoCount === 0
         ? "No TODO comments remain in the generated draft."
         : `${todoCount} TODO marker${todoCount === 1 ? "" : "s"} remain for reviewer follow-up.`));
+    const weakSmokeAssertions = content.match(/expect\(page\.locator\(["']body["']\)\)\.toBeVisible\(\)/g)?.length ?? 0;
+    checks.push(draftSelfCheckItem("Domain assertions", weakSmokeAssertions === 0 ? "pass" : "warning", weakSmokeAssertions === 0
+        ? "The draft does not rely on body-only smoke assertions."
+        : `${weakSmokeAssertions} body-only smoke assertion${weakSmokeAssertions === 1 ? "" : "s"} must be replaced with observable domain outcomes.`));
     checks.push(draftSelfCheckItem("Execution profile", plan.executionProfile.confidence === "low" || plan.executionProfile.blockers.length > 0 ? "warning" : "pass", plan.executionProfile.confidence === "low" || plan.executionProfile.blockers.length > 0
         ? "Runner setup, base URL, launch command, or config evidence is incomplete."
         : "Runner setup evidence is strong enough for a local execution attempt."));
@@ -5735,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, "#");
@@ -5763,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 {
@@ -5846,8 +6016,10 @@ function buildPlaywrightDraft(plan, flow, addedDiffText = {}) {
     for (const step of draftExecutableSteps(flow, "playwright")) {
         const manifestCheck = manifestCheckForDraftStep(flow, step);
         const manifestBody = manifestCheck ? playwrightActionForManifestCheck(manifestCheck, step) : undefined;
-        const selector = manifestBody ? undefined : takeSelectorForStep(selectorQueue, step);
+        const failureBody = manifestBody ? undefined : playwrightFailureActionForStep(flow, step);
+        const selector = manifestBody || failureBody ? undefined : takeSelectorForStep(selectorQueue, step);
         const body = manifestBody ??
+            failureBody ??
             (selector
                 ? playwrightActionForStep(selector, playwrightLocator(selector), step)
                 : playwrightFallbackActionForStep(step));
@@ -5857,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:");
@@ -5881,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;
@@ -6833,19 +7077,24 @@ function formatDraftActionKindSummary(summary) {
         .map((item) => `${item.kind} ${item.total} (${item.required} required, ${item.recommended} recommended)`)
         .join(", ");
 }
-function buildDraftNextSteps(plan, runner) {
+function buildDraftNextSteps(plan, runner, files) {
     const steps = [];
+    const hasTodos = files.some((file) => (file.todoCount ?? 0) > 0);
     if (runner === "maestro") {
         steps.push(plan.executionProfile.appId
             ? `Use app id ${plan.executionProfile.appId} or export APP_ID before running Maestro.`
             : "Replace ${APP_ID} or export APP_ID before running Maestro.");
-        steps.push("Replace TODO text selectors with visible copy, testID, or accessibilityLabel selectors.");
+        if (hasTodos) {
+            steps.push("Replace TODO text selectors with visible copy, testID, or accessibilityLabel selectors.");
+        }
         steps.push(plan.executionProfile.startCommand
             ? `Launch the app with \`${plan.executionProfile.startCommand}\`, then run \`${plan.executionProfile.testCommand ?? "maestro test .maestro"}\`.`
             : `Run the app with the launch command that matches your simulator or device, then run \`${plan.executionProfile.testCommand ?? "maestro test .maestro"}\`.`);
     }
     else if (runner === "playwright") {
-        steps.push("Replace TODO locators with role, text, or data-testid locators from the app.");
+        if (hasTodos) {
+            steps.push("Replace TODO locators with role, text, or data-testid locators from the app.");
+        }
         if (plan.executionProfile.blockers.some((blocker) => /No Playwright config/i.test(blocker))) {
             steps.push(playwrightConfigGuidance(plan.executionProfile));
         }
@@ -7124,6 +7373,53 @@ function playwrightActionForStep(selector, locator, step) {
     body.push(`await ${locator}.click();`);
     return body;
 }
+function playwrightFailureActionForStep(flow, step) {
+    if (!isFailurePathStep(step)) {
+        return undefined;
+    }
+    const endpoint = playwrightFailureMockEndpoint(flow);
+    const actionSelector = flow.selectors.find((selector) => !isInputSelector(selector) && selectorCanDriveInteraction(selector));
+    const outcomeSelector = flow.selectors.find((selector) => selectorCanSupportAssertion(selector) && isFailureOutcomeText(selector.value));
+    if (!endpoint || !actionSelector || !outcomeSelector) {
+        return undefined;
+    }
+    const routePattern = playwrightMockRoutePattern(endpoint);
+    const status = failureResponseStatus(step);
+    return [
+        `// Step intent: ${step}`,
+        `await page.unroute("${quoteJs(routePattern)}");`,
+        `await page.route("${quoteJs(routePattern)}", async (route) => {`,
+        "  await route.fulfill({",
+        `    status: ${status},`,
+        '    contentType: "application/json",',
+        '    body: JSON.stringify({ error: "QAMap simulated failure" }),',
+        "  });",
+        "});",
+        `await ${playwrightLocator(actionSelector)}.click();`,
+        `await expect(${playwrightLocator(outcomeSelector)}).toBeVisible();`,
+    ];
+}
+function playwrightFailureMockEndpoint(flow) {
+    const observedEndpoints = observedEndpointsForFlow(flow);
+    return flow.fixtureReadiness.apiEndpoints.find((endpoint) => !endpointMatchesAny(endpoint, observedEndpoints));
+}
+function isFailurePathStep(step) {
+    return /\b(?:blocked|declined|denied|empty|error|failed|failure|invalid|rejected|timeout|unauthori[sz]ed)\b/i.test(step) ||
+        /(?:오류|실패|거절|권한|잘못|할 수 없)/.test(step);
+}
+function isFailureOutcomeText(value) {
+    return /\b(?:cannot|could not|declined|denied|error|failed|failure|invalid|rejected|try again|unauthori[sz]ed|unavailable)\b/i.test(value) ||
+        /(?:오류|실패|거절|권한|잘못|할 수 없)/.test(value);
+}
+function failureResponseStatus(step) {
+    if (/\b(?:denied|unauthori[sz]ed)\b/i.test(step) || /권한/.test(step)) {
+        return 401;
+    }
+    if (/\b(?:invalid|validation)\b/i.test(step) || /잘못/.test(step)) {
+        return 422;
+    }
+    return 500;
+}
 function manifestCheckForDraftStep(flow, step) {
     const checks = flow.manifestCheckMatches ?? [];
     const stepKey = normalizeManifestStepKey(step);