@tea-agent/loop-agent 0.38.0 → 0.38.2

package/dist/executors/shell-executor.js

@@ -27,11 +27,13 @@ import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from
 import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } from "../workflows/dag/frontend-lint-baseline.js";
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
+import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
+import { backendTestGapDocSchema, ingestBackendTestGap, } from "../workflows/dag/backend-test-gap-fill.js";
 import { analyzeBackendTestCaseCoverage, analyzeBackendTestMarkdownPytestCorrespondence, materializeBackendTestCaseManifestFromFacts, } from "../workflows/dag/backend-test-case-coverage-analysis.js";
 import { materializeBackendTestResultFromPytestHtml, materializeBackendTestResultFromRunDir, parsePytestHtmlReport, } from "../workflows/dag/backend-test-result-contract.js";
-import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, resolveBackendTestMappedPytestScripts, collectJacocoCoverage, hasBlockingBackendMarkdownSafetyFindings, hasBlockingBackendMarkdownModuleStemFindings, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
+import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, resolveBackendTestMappedPytestScripts, collectJacocoCoverage, hasBlockingBackendMarkdownSafetyFindings, hasBlockingBackendMarkdownModuleStemFindings, inspectBackendTestEnvironment, markdownFiles, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
 import { applyDeterministicScenarioParamRepairs, assessBackendScenarioParamConsistency, classifyBackendTestFailureWithScenarioParam, readBackendScenarioParamFacts, renderBackendTestFailureAnalysis, writeBackendScenarioParamArtifacts, writeScenarioParamRepairAudit, } from "../workflows/dag/backend-test-scenario-param.js";
-import { assessBackendPytestCollection, assessMissingBackendPytestScripts, assessPriorityOnlyBackendPytestModules, assertBackendTestExecutionReadinessFresh, buildBackendPytestAssetInventory, materializeBackendTestExecutionReadiness, materializeEffectiveBackendPytestCollection, readBackendPytestCollectionFacts, readBackendTestExecutionReadiness, writeBackendPytestCollectionArtifacts, } from "../workflows/dag/backend-test-pytest-collection.js";
+import { assessBackendPytestCollection, assessMissingBackendPytestScripts, assessPriorityOnlyBackendPytestModules, assertBackendTestExecutionReadinessFresh, buildBackendPytestAssetInventory, buildBackendTestItemEligibility, materializeBackendTestExecutionReadiness, materializeEffectiveBackendPytestCollection, readBackendPytestCollectionFacts, readBackendTestExecutionReadiness, writeBackendPytestCollectionArtifacts, } from "../workflows/dag/backend-test-pytest-collection.js";
 import { computeL5ReportMetrics } from "../workflows/dag/l5-report-metrics.js";
 import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBackendTestClassification, } from "../workflows/dag/backend-test-classification-contract.js";
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
@@ -48,6 +50,7 @@ async function runBackendScenarioParamPreflight(input) {
         phase: "initial",
         repairAttempt: 0,
         strictScenarioParamGate: input.strictScenarioParamGate,
+        layout: input.layout,
     });
     const initialArtifacts = await writeBackendScenarioParamArtifacts({
         runDir: input.runDir,
@@ -73,6 +76,7 @@ async function runBackendScenarioParamPreflight(input) {
             phase: "final",
             repairAttempt: 1,
             strictScenarioParamGate: input.strictScenarioParamGate,
+            layout: input.layout,
         });
         finalFacts = reassessed.facts;
         finalMarkdown = reassessed.markdown;
@@ -492,11 +496,114 @@ async function readAdvisoryRunReport(reportsDir, filename, title) {
 async function executeBackendTestPipeline(input, meta) {
     const pipeline = input.task.shell?.backendTestPipeline;
     const started = Date.now();
+    // Plan A: prefer the frozen layout carried by the compiled spec; fall back
+    // to the historical default for hand-written legacy DAGs.
+    const backendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
+        ? {
+            testRoot: meta.spec.backendTestLayout.testRoot,
+            markdownRel: meta.spec.backendTestLayout.markdownRel,
+            scriptRel: meta.spec.backendTestLayout.scriptRel,
+        }
+        : undefined);
     try {
         if (!pipeline)
             throw new Error("missing backend-test pipeline id");
         const outputs = [];
-        if (pipeline === "markdown-environment") {
+        if (pipeline === "ingest-backend-test-gap") {
+            // Plan D: deterministic gap ingest. Identity (taskId + requirement
+            // sha256) is fail-closed; a mismatched plan blocks every writer.
+            const gapDocRel = meta.spec.globalConstraints
+                ?.map((item) => /^backendTestGapDoc=(.+)$/i.exec(item.trim())?.[1])
+                .find(Boolean);
+            const binding = meta.spec.sourceBinding;
+            const requirementSha256 = binding?.sources.find((s) => s.kind === "requirement")?.sha256 ?? "";
+            if (!gapDocRel || !binding || !requirementSha256) {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: "backend-test gap ingest requires the bound gap document path and the task source binding with a requirement sha256",
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            const gapDocAbs = path.join(input.cwd, ...gapDocRel.split("/"));
+            let parsed;
+            try {
+                parsed = JSON.parse(await readFile(gapDocAbs, "utf8"));
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: `backend-test gap document is unreadable JSON at ${gapDocRel}: ${error instanceof Error ? error.message : String(error)}`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            const doc = backendTestGapDocSchema.safeParse(parsed);
+            if (!doc.success) {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: `invalid backend-test-gap-v1 document: ${doc.error.issues
+                        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+                        .join("; ")}`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+            // previous N6 facts (may be absent on a fresh checkout)
+            const factsPath = path.join(input.cwd, "contracts", "backend-test-case-coverage-facts.json");
+            let previousMissingSlots;
+            let previousCoveredSlots;
+            try {
+                const facts = JSON.parse(await readFile(factsPath, "utf8"));
+                previousMissingSlots = facts.scenarioPartitions?.missingSlots;
+                previousCoveredSlots = (facts.rules ?? []).flatMap((rule) => rule.coveredTestPoints ?? []);
+            }
+            catch {
+                // no previous facts in the workspace: the gap doc alone drives the plan
+            }
+            // module index comes from the README on disk
+            let existingModuleStems = [];
+            try {
+                const files = await markdownFiles(input.cwd, backendLayout);
+                existingModuleStems = files
+                    .map((file) => path.basename(file, ".md"))
+                    .filter((stem) => stem.toLowerCase() !== "readme");
+            }
+            catch {
+                // no markdown tree: every slot becomes a conflict
+            }
+            const plan = ingestBackendTestGap({
+                gapDoc: doc.data,
+                previousMissingSlots,
+                previousCoveredSlots,
+                existingModuleStems,
+                sharedSetupPath: meta.spec.backendTestSharedSetup?.path ?? null,
+                layout: backendLayout,
+                taskId: binding.taskId,
+                requirementSha256,
+            });
+            const contractsDir = path.join(meta.runDir, "contracts");
+            await mkdir(contractsDir, { recursive: true });
+            const planPath = path.join(contractsDir, "backend-test-gap-plan-v1.json");
+            await writeFile(planPath, JSON.stringify(plan, null, 2), "utf8");
+            outputs.push(`gapPlan=${planPath}`, `gapPlanStatus=${plan.status}`);
+            if (plan.status === "error") {
+                return {
+                    ok: false,
+                    stdout: outputs.join("\n"),
+                    stderr: [
+                        "backend-test gap ingest failed closed (identity/conflicts):",
+                        ...plan.conflicts,
+                    ].join("\n"),
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+        }
+        else if (pipeline === "markdown-environment") {
             const results = await executePipelineCommands(input, meta);
             if (!results.every((result) => result.ok)) {
                 const failure = results.find((result) => !result.ok);
@@ -530,6 +637,8 @@ async function executeBackendTestPipeline(input, meta) {
                     environmentMarkdown,
                     requiredRequirementIds,
                     sourceBinding: meta.spec.sourceBinding,
+                    layout: backendLayout,
+                    sharedSetup: meta.spec.backendTestSharedSetup ?? null,
                 });
             }
             catch (error) {
@@ -583,6 +692,7 @@ async function executeBackendTestPipeline(input, meta) {
                 const coverage = await analyzeBackendTestCaseCoverage({
                     workspaceRoot: input.cwd,
                     sourceBinding: normalizedBinding,
+                    layout: backendLayout,
                 });
                 const coveragePath = await writeRunReport(meta.runDir, "backend-test-case-coverage-analysis.md", coverage.markdown);
                 const contractsDir = path.join(meta.runDir, "contracts");
@@ -590,6 +700,23 @@ async function executeBackendTestPipeline(input, meta) {
                 const factsPath = path.join(contractsDir, "backend-test-case-coverage-facts.json");
                 await writeFile(factsPath, JSON.stringify(coverage.facts, null, 2), "utf8");
                 outputs.push(`caseCoverage=${coveragePath}`, `caseCoverageFacts=${factsPath}`, coverage.markdown);
+                // Plan C: scenario-partition slot coverage is fail-closed. General
+                // coverage findings stay advisory, but a declared filter axis missing
+                // an each-value/omitted slot or its complement slot must block pytest
+                // generation until the Markdown declares the slot.
+                const partitionBlocking = coverage.facts.findings.filter((finding) => /^(?:MISSING_PARTITION|MISSING_PARTITION_SLOT|MISSING_COMPLEMENT_SLOT|MISSING_PARTITION_TABLE)/.test(finding));
+                if (partitionBlocking.length > 0) {
+                    return {
+                        ok: false,
+                        stdout: outputs.join("\n\n"),
+                        stderr: [
+                            "backend-test scenario partitions are incomplete (fail-closed):",
+                            ...partitionBlocking,
+                        ].join("\n"),
+                        failureCategory: "invalid-output",
+                        durationMs: Date.now() - started,
+                    };
+                }
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -606,9 +733,9 @@ async function executeBackendTestPipeline(input, meta) {
             }
         }
         else if (pipeline === "markdown-collection-assess") {
-            const resolution = await resolveBackendTestMappedPytestScripts(input.cwd);
+            const resolution = await resolveBackendTestMappedPytestScripts(input.cwd, backendLayout);
             let facts;
-            const preflightInventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false });
+            const preflightInventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false, layout: backendLayout });
             const priorityOnlyFacts = assessPriorityOnlyBackendPytestModules({
                 phase: "initial",
                 mappedScripts: resolution.expectedScripts,
@@ -618,7 +745,7 @@ async function executeBackendTestPipeline(input, meta) {
                 facts = priorityOnlyFacts;
             }
             else if (resolution.missingScripts.length > 0) {
-                const inventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false });
+                const inventory = await buildBackendPytestAssetInventory(input.cwd, resolution.existingScripts, { requireMappedScripts: false, layout: backendLayout });
                 facts = assessMissingBackendPytestScripts({
                     mappedScripts: resolution.expectedScripts,
                     existingMappedScripts: resolution.existingScripts,
@@ -632,10 +759,11 @@ async function executeBackendTestPipeline(input, meta) {
                 const scenario = await runBackendScenarioParamPreflight({
                     workspaceRoot: input.cwd,
                     runDir: meta.runDir,
+                    layout: backendLayout,
                     strictScenarioParamGate: Boolean((meta.spec.globalConstraints ?? []).some((item) => /strictScenarioParamGate\s*=\s*true/i.test(item))),
                 });
                 outputs.push(...scenario.outputs);
-                const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts);
+                const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts, { layout: backendLayout });
                 const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
                 const targets = mappedScripts.map(shellQuote).join(" ");
                 const command = `PYTHONDONTWRITEBYTECODE=1 python -m pytest --collect-only -q -p no:cacheprovider ${targets}`;
@@ -669,6 +797,7 @@ async function executeBackendTestPipeline(input, meta) {
                     fixtureResolution = { exitCode: fixtureResult.exitCode ?? 2, stdout: fixtureResult.stdout, stderr: fixtureResult.stderr };
                 }
                 facts = assessBackendPytestCollection({
+                    layout: backendLayout,
                     phase: "initial",
                     mappedScripts,
                     inventory,
@@ -678,6 +807,43 @@ async function executeBackendTestPipeline(input, meta) {
                     fixtureResolution,
                 });
             }
+            try {
+                const correspondence = await analyzeBackendTestMarkdownPytestCorrespondence({
+                    workspaceRoot: input.cwd,
+                    layout: backendLayout,
+                    taskId: meta.spec.sourceBinding?.taskId ?? "unbound",
+                });
+                const correspondenceReportPath = await writeRunReport(meta.runDir, "backend-test-markdown-pytest-correspondence-initial.md", correspondence.markdown);
+                const contractsDir = path.join(meta.runDir, "contracts");
+                await mkdir(contractsDir, { recursive: true });
+                const correspondenceFactsPath = path.join(contractsDir, "backend-test-markdown-pytest-correspondence-initial.json");
+                await writeFile(correspondenceFactsPath, JSON.stringify(correspondence.facts, null, 2), "utf8");
+                outputs.push(`initialCorrespondence=${correspondenceReportPath}`, `initialCorrespondenceFacts=${correspondenceFactsPath}`);
+                if (correspondence.facts.status === "FAIL" && facts.status === "PASS") {
+                    const correspondenceRepairPaths = Array.from(new Set(correspondence.facts.entries
+                        .filter((entry) => entry.status !== "EXACT_1_TO_1")
+                        .flatMap((entry) => [entry.expectedScript, ...entry.actualScripts])
+                        .filter((candidate) => candidate.startsWith("testcase/") && candidate.endsWith(".py")))).sort();
+                    if (correspondenceRepairPaths.length > 0) {
+                        facts.status = "REPAIRABLE";
+                        facts.repairEligible = true;
+                        facts.repairPaths = Array.from(new Set([...facts.repairPaths, ...correspondenceRepairPaths])).sort();
+                        facts.findings.push({
+                            kind: "markdown-pytest-correspondence",
+                            classification: "test-asset-defect",
+                            repairability: "repairable",
+                            detail: correspondence.facts.entries
+                                .filter((entry) => entry.status !== "EXACT_1_TO_1")
+                                .flatMap((entry) => entry.findings)
+                                .join("; ")
+                                .slice(0, 12_000) || "Markdown-to-pytest correspondence is incomplete",
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                outputs.push(`initialCorrespondence=UNAVAILABLE: ${error instanceof Error ? error.message : String(error)}`);
+            }
             const artifacts = await writeBackendPytestCollectionArtifacts({
                 runDir: meta.runDir,
                 stem: "initial",
@@ -715,10 +881,11 @@ async function executeBackendTestPipeline(input, meta) {
                 const scenario = await runBackendScenarioParamPreflight({
                     workspaceRoot: input.cwd,
                     runDir: meta.runDir,
+                    layout: backendLayout,
                     strictScenarioParamGate: Boolean((meta.spec.globalConstraints ?? []).some((item) => /strictScenarioParamGate\s*=\s*true/i.test(item))),
                 });
                 outputs.push(...scenario.outputs);
-                const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts);
+                const inventory = await buildBackendPytestAssetInventory(input.cwd, mappedScripts, { layout: backendLayout });
                 const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
                 const targets = mappedScripts.map(shellQuote).join(" ");
                 const command = `PYTHONDONTWRITEBYTECODE=1 python -m pytest --collect-only -q -p no:cacheprovider ${targets}`;
@@ -753,6 +920,7 @@ async function executeBackendTestPipeline(input, meta) {
                     fixtureResolution = { exitCode: fixtureResult.exitCode ?? 2, stdout: fixtureResult.stdout, stderr: fixtureResult.stderr };
                 }
                 const finalFacts = assessBackendPytestCollection({
+                    layout: backendLayout,
                     phase: "final",
                     mappedScripts,
                     inventory,
@@ -776,12 +944,57 @@ async function executeBackendTestPipeline(input, meta) {
                 facts: effective,
             });
             const scenarioFacts = await readBackendScenarioParamFacts(path.join(meta.runDir, "contracts", "backend-test-scenario-param-consistency-facts.json"));
+            const correspondence = meta.spec.sourceBinding
+                ? await analyzeBackendTestMarkdownPytestCorrespondence({
+                    workspaceRoot: input.cwd,
+                    layout: backendLayout,
+                    taskId: meta.spec.sourceBinding.taskId,
+                })
+                : undefined;
+            const eligibility = correspondence
+                ? buildBackendTestItemEligibility(effective.collectedItemIds, {
+                    correspondenceEntries: correspondence.facts.entries,
+                    scenarioEntries: scenarioFacts.entries,
+                })
+                : { eligibleItemIds: effective.collectedItemIds, excludedItems: [] };
+            const eligibilityInputHashes = Object.fromEntries((correspondence?.facts.inputFiles ?? []).map((item) => [item.path, item.sha256]));
+            const eligibilityFactsPath = path.join(meta.runDir, "contracts", "backend-test-execution-eligibility.json");
+            await mkdir(path.dirname(eligibilityFactsPath), { recursive: true });
+            await writeFile(eligibilityFactsPath, `${JSON.stringify({
+                schemaId: "backend-test-execution-eligibility-v1",
+                status: eligibility.eligibleItemIds.length === 0 ? "BLOCKED" : eligibility.excludedItems.length > 0 ? "PARTIAL" : "PASS",
+                collectedItemCount: effective.collectedItemIds.length,
+                eligibleItemCount: eligibility.eligibleItemIds.length,
+                excludedItemCount: eligibility.excludedItems.length,
+                eligibleItemIds: eligibility.eligibleItemIds,
+                excludedItems: eligibility.excludedItems,
+                inputHashes: eligibilityInputHashes,
+            }, null, 2)}\n`, "utf8");
+            const eligibilityReportPath = await writeRunReport(meta.runDir, "backend-test-execution-eligibility.md", [
+                "# Backend Test Execution Eligibility",
+                "",
+                "## Status",
+                "",
+                eligibility.eligibleItemIds.length === 0 ? "BLOCKED" : eligibility.excludedItems.length > 0 ? "PARTIAL" : "PASS",
+                "",
+                `- Collected items: ${effective.collectedItemIds.length}`,
+                `- Eligible items: ${eligibility.eligibleItemIds.length}`,
+                `- Excluded items: ${eligibility.excludedItems.length}`,
+                "",
+                "## Excluded Items",
+                "",
+                ...(eligibility.excludedItems.length > 0 ? eligibility.excludedItems.map((item) => `- \`${item.itemId}\` (${item.caseId ?? "unknown Case"}): ${item.reasons.join("; ")}`) : ["- None"]),
+                "",
+            ].join("\n"));
+            outputs.push(`executionEligibility=${eligibilityReportPath}`, `executionEligibilityFacts=${eligibilityFactsPath}`);
             const readiness = await materializeBackendTestExecutionReadiness({
                 runDir: meta.runDir,
                 workspaceRoot: input.cwd,
                 effective,
                 scenarioParamStatus: scenarioFacts.overallStatus,
                 scenarioParamRepairAttempt: scenarioFacts.repairAttempt,
+                eligibility,
+                eligibilityInputHashes,
             });
             return {
                 ok: true,
@@ -792,6 +1005,8 @@ async function executeBackendTestPipeline(input, meta) {
                     collectedItemCount: effective.collectedItemCount,
                     fixtureResolutionStatus: effective.fixtureResolutionStatus,
                     executionReadinessStatus: readiness.status,
+                    eligibleItemCount: readiness.eligibleItemIds.length,
+                    excludedItemCount: readiness.excludedItems.length,
                     factsPath: "contracts/backend-test-pytest-collection-effective.json",
                     readinessPath: "contracts/backend-test-execution-readiness.json",
                     reportPath: artifacts.reportPath,
@@ -826,6 +1041,7 @@ async function executeBackendTestPipeline(input, meta) {
             try {
                 const correspondence = await analyzeBackendTestMarkdownPytestCorrespondence({
                     workspaceRoot: input.cwd,
+                    layout: backendLayout,
                     taskId: sourceBinding.taskId,
                 });
                 const correspondencePath = await writeRunReport(meta.runDir, "backend-test-markdown-pytest-correspondence.md", correspondence.markdown);
@@ -888,9 +1104,32 @@ async function executeBackendTestPipeline(input, meta) {
         else if (pipeline === "markdown-execute-html") {
             const executionReadiness = await readBackendTestExecutionReadiness(path.join(meta.runDir, "contracts", "backend-test-execution-readiness.json"));
             await assertBackendTestExecutionReadinessFresh(input.cwd, executionReadiness);
-            const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);
-            const shellQuote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
-            const pytestTargets = mappedScripts.map(shellQuote).join(" ");
+            const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd, backendLayout);
+            let eligibleItemIds = executionReadiness.eligibleItemIds;
+            // Plan D gap-fill executeScope=affected: when a gap plan exists in
+            // this run, prefer the newly planned items (pytest node ids contain
+            // the TP slot id) plus every collected item of the patched modules;
+            // scope=all keeps the full eligible set.
+            const affectedScope = meta.spec.globalConstraints?.some((item) => /^backendTestExecuteScope=affected$/i.test(item.trim())) ?? false;
+            if (affectedScope) {
+                try {
+                    const plan = JSON.parse(await readFile(path.join(meta.runDir, "contracts", "backend-test-gap-plan-v1.json"), "utf8"));
+                    const newPoints = new Set(plan.newTestPoints ?? []);
+                    const modules = new Set((plan.targetModules ?? []).map((stem) => `test_${stem}.py`));
+                    const affected = eligibleItemIds.filter((id) => modules.size === 0 ||
+                        [...modules].some((script) => id.includes(script)) ||
+                        [...newPoints].some((point) => id.includes(point)));
+                    if (affected.length > 0)
+                        eligibleItemIds = affected;
+                }
+                catch {
+                    // no gap plan in this run: execute the full eligible set
+                }
+            }
+            const pytestTargetsRelative = "reports/backend-test-pytest-targets.txt";
+            const pytestTargetsAbsolute = path.join(meta.runDir, pytestTargetsRelative);
+            await writeFile(pytestTargetsAbsolute, `${eligibleItemIds.join("\n")}\n`, "utf8");
+            const pytestTargetsArg = `@\"\${HARNESS_DAG_RUN_DIR}/${pytestTargetsRelative}\"`;
             // Split into short bash -c commands (aligned with markdown-environment).
             // A single ultra-long compound command has been observed on Windows to
             // exit 0xC0000142 (STATUS_DLL_INIT_FAILED) in ~40ms with empty stdout/
@@ -967,8 +1206,10 @@ async function executeBackendTestPipeline(input, meta) {
                 'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
                 'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" | tee -a "${DIAG_FILE}" >&2; exit 127; fi',
                 'echo "STEP=pytest-run"',
-                `echo "- pytestCommand: python -m pytest ${mappedScripts.join(" ")} -v -p no:cacheprovider --html=reports/backend-test.html --self-contained-html" >> "\${DIAG_FILE}"`,
-                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 "\${PYTHON_BIN}" -m pytest ${pytestTargets} -v -p no:cacheprovider --html="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" --self-contained-html`,
+                `echo "- pytestCommand: python -m pytest <${eligibleItemIds.length} eligibility-authorized-items> -v -p no:cacheprovider --html=reports/backend-test.html --self-contained-html" >> "\${DIAG_FILE}"`,
+                `echo "- eligibleItemCount: ${eligibleItemIds.length}" >> "\${DIAG_FILE}"`,
+                `echo "- excludedItemCount: ${executionReadiness.excludedItems.length}" >> "\${DIAG_FILE}"`,
+                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 "\${PYTHON_BIN}" -m pytest ${pytestTargetsArg} -v -p no:cacheprovider --html="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.html" --self-contained-html`,
                 "STATUS=$?",
                 'printf "%s" "${STATUS}" > "${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt"',
                 'echo "- pytestExitCode: ${STATUS}" >> "${DIAG_FILE}"',
@@ -1053,11 +1294,13 @@ async function executeBackendTestPipeline(input, meta) {
                 htmlContent: pytestHtmlContent,
                 pytestExitCode,
             });
-            const cases = await collectBackendTestHumanCaseCatalog(input.cwd);
+            const cases = await collectBackendTestHumanCaseCatalog(input.cwd, backendLayout);
             const caseValidationSummary = await readRequiredRunReport(reportsDir, "backend-md-case-validation.md");
             const caseCoverageSummary = await readAdvisoryRunReport(reportsDir, "backend-test-case-coverage-analysis.md", "Backend Test Case Coverage Analysis");
             const traceabilitySummary = await readRequiredRunReport(reportsDir, "backend-test-traceability.md");
-            const correspondenceSummary = await readAdvisoryRunReport(reportsDir, "backend-test-markdown-pytest-correspondence.md", "Backend Test Markdown → pytest Correspondence");
+            const correspondenceSummaryBase = await readAdvisoryRunReport(reportsDir, "backend-test-markdown-pytest-correspondence.md", "Backend Test Markdown → pytest Correspondence");
+            const eligibilitySummary = await readAdvisoryRunReport(reportsDir, "backend-test-execution-eligibility.md", "Backend Test Execution Eligibility");
+            const correspondenceSummary = `${correspondenceSummaryBase.trim()}\n\n${eligibilitySummary.trim()}\n`;
             const htmlContent = renderBackendTestHtml({
                 title: meta.spec.title,
                 parsed,
@@ -1245,6 +1488,7 @@ async function executeBackendTestPipeline(input, meta) {
                 fromNodeId: "backend-test-execution-envelope",
                 artifactName: "backend-test-execution.json",
                 outputDir: "contracts",
+                allowedTestRoot: backendLayout.testRoot,
             });
             outputs.push(`analysis=${analysis.path}`, `execution=${execution.path}`);
         }
@@ -1360,6 +1604,7 @@ async function executeBackendTestPipeline(input, meta) {
                 artifactName: "backend-test-result-initial.json",
                 outputDir: "contracts",
                 junitRelativePath: "reports/backend-test-initial-junit.xml",
+                testRoot: backendLayout.testRoot,
             });
             outputs.push(...results.map((result) => result.stdout), `result=${artifact.path}`);
         }
@@ -2246,6 +2491,13 @@ export async function executeDagShellNode(input, meta) {
     }
     if (shell?.jsonArtifactGate) {
         const started = Date.now();
+        const backendLayout = resolveBackendTestLayout(meta.spec.backendTestLayout
+            ? {
+                testRoot: meta.spec.backendTestLayout.testRoot,
+                markdownRel: meta.spec.backendTestLayout.markdownRel,
+                scriptRel: meta.spec.backendTestLayout.scriptRel,
+            }
+            : undefined);
         try {
             const gate = shell.jsonArtifactGate;
             const sourceNodeId = gate.fallbackFromNodeIds?.length
@@ -2273,6 +2525,7 @@ export async function executeDagShellNode(input, meta) {
                         fromNodeId: sourceNodeId,
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
+                        allowedTestRoot: backendLayout.testRoot,
                     });
                     break;
                 case "backend-test-result-v1":
@@ -2282,6 +2535,7 @@ export async function executeDagShellNode(input, meta) {
                         artifactName: gate.artifactName,
                         outputDir: gate.outputDir,
                         junitRelativePath: gate.junitRelativePath,
+                        testRoot: backendLayout.testRoot,
                     });
                     break;
                 case "backend-test-classification-v1":

package/dist/infrastructure/harness/atomic-write.js

@@ -1,13 +1,14 @@
 import { copyFile, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { assertHarnessWriteAllowed, } from "./completed-facts-guard.js";
+let atomicWriteSequence = 0;
 async function writeAtomic(targetPath, content, options) {
     assertHarnessWriteAllowed(targetPath, options);
     const resolved = options?.repoRoot && !path.isAbsolute(targetPath)
         ? path.resolve(options.repoRoot, targetPath)
         : path.resolve(targetPath);
     await mkdir(path.dirname(resolved), { recursive: true });
-    const tempPath = `${resolved}.${process.pid}.tmp`;
+    const tempPath = `${resolved}.${process.pid}.${(atomicWriteSequence += 1)}.tmp`;
     try {
         await writeFile(tempPath, content, "utf-8");
         try {

package/dist/shared/openspec-spec.js

@@ -14,6 +14,30 @@ export const OPENSPEC_SPEC_DIRS = [
 ];
 /** Allowed spec file extensions (case-insensitive). */
 export const OPENSPEC_SPEC_EXT_RE = /\.(md|mdx|json|yaml|yml)$/i;
+/**
+ * Default governance subtree excluded from candidate discovery. Aligned with
+ * init.ts's DEFAULT_GOVERNANCE_ROOT; discovery derives the real root from
+ * harness.json.governanceRoot and falls back to this value.
+ */
+export const DEFAULT_OPENSPEC_GOVERNANCE_ROOT = "ai_workspace/loop-agent";
+/**
+ * Explicit safety ceiling for auto-discovered openspec candidates (>=200).
+ * Reaching the cap is reported via DagSpec.advisories, never silently dropped.
+ */
+export const MAX_OPENSPEC_CANDIDATE_PATHS = 200;
+/**
+ * Returns `true` when `filePath` is the governance subtree itself or any path
+ * under it. `filePath` must be a repo-relative POSIX path (backslashes are
+ * normalised internally). Comparison is case-sensitive, matching the other
+ * predicates in this module.
+ */
+export function isGovernanceSubtreePath(filePath, governanceRoot) {
+    const normalized = filePath.replaceAll("\\", "/");
+    const root = governanceRoot.replaceAll("\\", "/").replace(/\/+$/, "");
+    if (!root)
+        return false;
+    return normalized === root || normalized.startsWith(root + "/");
+}
 /**
  * Returns `true` when `filePath` is inside one of the canonical frontend spec
  * directories.  `filePath` must be a repo-relative POSIX path (backslashes are
@@ -47,3 +71,55 @@ export function isOpenspecSpecSearchTarget(value) {
     const normalized = value.replaceAll("\\", "/");
     return /(?:^|[^A-Za-z0-9_.-])(?:openspec\/(?:schemas|project-specs)|ai_workspace)(?:\/|$)/.test(normalized);
 }
+/** Normalizes a free-form path token to a repo-relative POSIX path or null. */
+function normalizeCitationToken(raw) {
+    let token = raw.trim();
+    token = token.replace(/^[<"'`(\[\s]+|[>"'`)\]\s]+$/g, "");
+    // Strip trailing punctuation that is not part of a filename.
+    token = token.replace(/[),.;:!?]+$/g, "");
+    const hashIndex = token.indexOf("#");
+    if (hashIndex >= 0)
+        token = token.slice(0, hashIndex);
+    token = token.replace(/\\/g, "/");
+    if (!token)
+        return null;
+    return token;
+}
+/**
+ * Deterministically extracts repo-relative openspec spec paths explicitly cited
+ * in task-source markdown (requirement + execution constraint). Pure function,
+ * no IO.
+ *
+ * Scanned sources, in order:
+ * - backtick inline code spans (`path`)
+ * - markdown link targets ([text](path))
+ * - bare path tokens under openspec/ or ai_workspace/
+ *
+ * Every token is normalized to POSIX, stripped of a trailing `#fragment`,
+ * filtered through `isOpenspecSpecFilePath`, and excluded when it falls inside
+ * the governance subtree (matching `listOpenspecDiscovery`'s exclusion口径).
+ * Results are deduped and sorted.
+ */
+export function extractTaskSourceOpenspecPaths(markdown, governanceRoot = DEFAULT_OPENSPEC_GOVERNANCE_ROOT) {
+    if (!markdown)
+        return [];
+    const raw = new Set();
+    const collect = (token) => {
+        const normalized = normalizeCitationToken(token);
+        if (normalized)
+            raw.add(normalized);
+    };
+    for (const match of markdown.matchAll(/`([^`\n]+)`/g)) {
+        collect(match[1] ?? "");
+    }
+    for (const match of markdown.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)) {
+        collect(match[1] ?? "");
+    }
+    for (const match of markdown.matchAll(/(?:^|[\s"'([>])((?:openspec|ai_workspace)\/[A-Za-z0-9._/-]+)/g)) {
+        collect(match[1] ?? "");
+    }
+    return [...raw]
+        .filter((token) => isOpenspecSpecFilePath(token) &&
+        !isGovernanceSubtreePath(token, governanceRoot))
+        .sort();
+}