@tea-agent/loop-agent 0.40.0-next.1 → 0.40.0-next.11

package/dist/workflows/dag/backend-test-markdown-workflow.js

@@ -200,14 +200,170 @@ export async function inspectBackendTestEnvironment(input) {
         serverEntries,
     };
 }
+/**
+ * Filenames declared by the canonical `## Module Index` section of the backend
+ * README. Only a unique exact `## Module Index` heading is authoritative; a
+ * missing/duplicate section yields an empty declaration set (callers then fall
+ * back to the whole directory so legacy workspaces without a manifest keep
+ * their prior behaviour). Reads `[x](./x.md)`, `` `testcase/md/<x>.md` `` and
+ * inline `x.md` tokens inside the section; README.md itself is never a module.
+ */
+export function extractDeclaredModuleIndexFilenames(readme) {
+    const lines = readme
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .split("\n");
+    const headings = lines.flatMap((line, index) => line.trim() === "## Module Index" ? [index] : []);
+    if (headings.length !== 1)
+        return [];
+    const start = headings[0] + 1;
+    const relativeEnd = lines
+        .slice(start)
+        .findIndex((line) => /^##\s+\S/.test(line.trim()));
+    const end = relativeEnd < 0 ? lines.length : start + relativeEnd;
+    const section = lines.slice(start, end).join("\n");
+    return unique([...section.matchAll(/`?[A-Za-z0-9_.-]+\.md`?/g)]
+        .map((match) => match[0].replaceAll("`", ""))
+        .filter((name) => name.toLowerCase() !== "readme.md"));
+}
+/**
+ * Count exact `## Module Index` headings in the backend README.
+ */
+function moduleIndexHeadingCountIn(readme) {
+    return readme
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .split("\n")
+        .filter((line) => line.trim() === "## Module Index").length;
+}
+/**
+ * Machine-readable fail-closed finding for an invalid backend-test Module Index.
+ * These are distinct states (missing/unreadable/duplicate/empty-unparsable) so a
+ * stripped Module Index can never silently fall back to a whole-directory scan.
+ */
+export function backendManifestStatusFinding(manifestStatus, moduleIndexHeadingCount = 0) {
+    switch (manifestStatus) {
+        case "missing":
+            return "README is missing; backend-test current round fails closed without a declarative Module Index";
+        case "unreadable":
+            return "README is unreadable; backend-test current round fails closed without a usable Module Index";
+        case "duplicate":
+            return moduleIndexHeadingCount === 0
+                ? "README Module Index heading is missing; backend-test current round fails closed without a declarative Module Index"
+                : `duplicate ## Module Index heading (${moduleIndexHeadingCount} occurrences); backend-test current round fails closed without a unique Module Index`;
+        case "empty-unparsable":
+            return "README Module Index is empty/unparsable; backend-test current round fails closed with no declared module";
+        case "valid":
+            return "";
+    }
+}
+/**
+ * Resolve the current-round Markdown module manifest. The README `## Module
+ * Index` is the authoritative source for which module files belong to this
+ * round. Fail closed on every non-`valid` state (missing/unreadable/duplicate/
+ * empty-unparsable): the backend-test current round must NEVER re-scan the whole
+ * directory, or historical `.md` files could leak back into Case/coverage/
+ * partition facts.
+ *
+ * - `manifestStatus==="valid"`   — unique heading with >= 1 declared `.md` file.
+ * - `missing`                     — README file does not exist.
+ * - `unreadable`                  — README exists but could not be read.
+ * - `duplicate`                   — README has 0 or duplicate `## Module Index`.
+ * - `empty-unparsable`            — unique heading but no `.md` filename parsed.
+ * - `declaredMdFiles`  — declared filenames that exist on disk (relative paths).
+ * - `declaredMissing`  — declared filenames with no file on disk (fail-closed
+ *   evidence, never silently dropped).
+ * - `unmanifested`     — existing `.md` files that the Module Index does not
+ *   declare (non-silent advisory; they must not enter Case/coverage/partition).
+ */
+export async function resolveBackendTestManifestModules(workspaceRoot, layout) {
+    const resolved = layout ?? resolveBackendTestLayout(undefined);
+    const readmePath = path.join(workspaceRoot, ...resolved.readmePath.split("/"));
+    const invalid = (manifestStatus, moduleIndexHeadingCount) => ({
+        hasManifest: false,
+        manifestStatus,
+        moduleIndexHeadingCount,
+        declaredStems: [],
+        declaredMdFiles: [],
+        declaredMissing: [],
+        unmanifested: [],
+    });
+    let readme = "";
+    if (await exists(readmePath)) {
+        try {
+            readme = await readFile(readmePath, "utf8");
+        }
+        catch {
+            // Unreadable README is fail-closed (not silently treated as no manifest).
+            return invalid("unreadable", 0);
+        }
+    }
+    else {
+        return invalid("missing", 0);
+    }
+    const moduleIndexHeadingCount = moduleIndexHeadingCountIn(readme);
+    if (moduleIndexHeadingCount !== 1) {
+        return invalid("duplicate", moduleIndexHeadingCount);
+    }
+    const declaredStems = extractDeclaredModuleIndexFilenames(readme);
+    if (declaredStems.length === 0) {
+        return invalid("empty-unparsable", moduleIndexHeadingCount);
+    }
+    const hasManifest = true;
+    const directory = path.join(workspaceRoot, ...resolved.markdownDir.split("/"));
+    let existingNames = [];
+    try {
+        existingNames = (await readdir(directory, { withFileTypes: true }))
+            .filter((entry) => entry.isFile() &&
+            entry.name.toLowerCase().endsWith(".md") &&
+            entry.name.toLowerCase() !== "readme.md")
+            .map((entry) => entry.name);
+    }
+    catch {
+        // missing markdown directory -> no existing modules
+    }
+    const declaredByLower = new Map();
+    for (const name of declaredStems) {
+        const base = path.posix.basename(name);
+        declaredByLower.set(base.toLowerCase(), base);
+    }
+    const declaredMdFiles = [];
+    const declaredMissing = [];
+    for (const base of declaredByLower.values()) {
+        const disk = existingNames.find((name) => name.toLowerCase() === base.toLowerCase());
+        if (disk)
+            declaredMdFiles.push(`${resolved.markdownDir}/${disk}`);
+        else
+            declaredMissing.push(`${resolved.markdownDir}/${base}`);
+    }
+    const unmanifested = existingNames
+        .filter((name) => !declaredByLower.has(name.toLowerCase()))
+        .map((name) => `${resolved.markdownDir}/${name}`);
+    return {
+        hasManifest,
+        manifestStatus: "valid",
+        moduleIndexHeadingCount,
+        declaredStems,
+        declaredMdFiles: declaredMdFiles.sort(),
+        declaredMissing: declaredMissing.sort(),
+        unmanifested: unmanifested.sort(),
+    };
+}
 export async function markdownFiles(root, layout) {
     const resolved = layout ?? resolveBackendTestLayout(undefined);
     const directory = path.join(root, ...resolved.markdownDir.split("/"));
     const entries = await readdir(directory, { withFileTypes: true });
-    return entries
+    const all = entries
         .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"))
         .map((entry) => path.join(directory, entry.name))
         .sort();
+    const manifest = await resolveBackendTestManifestModules(root, resolved);
+    if (manifest.manifestStatus !== "valid")
+        return [];
+    const declaredAbs = new Set(manifest.declaredMdFiles.map((rel) => path.join(root, ...rel.split("/")).toLowerCase()));
+    return all
+        .filter((file) => declaredAbs.has(file.toLowerCase()))
+        .sort();
 }
 function canonicalBackendCaseId(value) {
     const upper = value.toUpperCase();
@@ -453,6 +609,17 @@ export async function validateBackendMarkdownCases(input) {
     const readme = path.join(input.workspaceRoot, ...layout.readmePath.split("/"));
     if (!(await exists(readme)))
         findings.push(`missing ${layout.readmePath}`);
+    const manifest = await resolveBackendTestManifestModules(input.workspaceRoot, layout);
+    // Fail closed on README Module Index entries that were declared but never
+    // materialized — never let a declared module silently vanish from the round.
+    if (manifest.declaredMissing.length > 0) {
+        findings.push(`declared Markdown module is missing (Module Index): ${manifest.declaredMissing.join(", ")}`);
+    }
+    // Fail closed on every non-valid Module Index state: without a valid unique
+    // Module Index the current round must not re-scan historical `.md` files.
+    if (manifest.manifestStatus !== "valid") {
+        findings.push(backendManifestStatusFinding(manifest.manifestStatus, manifest.moduleIndexHeadingCount));
+    }
     const moduleFiles = files.filter((file) => path.basename(file).toLowerCase() !== "readme.md");
     if (moduleFiles.length === 0)
         findings.push(`no ${layout.markdownDir} module case file found`);
@@ -562,6 +729,7 @@ export async function validateBackendMarkdownCases(input) {
         `- Cases: ${caseCount}`,
         `- Covered AC IDs: ${[...coveredAc].sort().join(", ") || "none"}`,
         `- Environment evidence present: ${input.environmentMarkdown.trim() ? "yes" : "no"}`,
+        `- Manifest scope: ${manifest.manifestStatus === "valid" ? "declared-modules" : `fails-closed:${manifest.manifestStatus}`} (declared-missing=${manifest.declaredMissing.length}, unmanifested-advisory=${manifest.unmanifested.length}, module-index-heading-count=${manifest.moduleIndexHeadingCount})`,
         `- Findings: ${findings.length}`,
         "- Required sections: Preconditions/前置条件, Steps/操作步骤, Expected Results/预期结果",
         "- Source-reference validity check: not applied",
@@ -583,6 +751,13 @@ export async function validateBackendMarkdownCases(input) {
             ? safetyFindings.map((finding) => `- ${finding}`)
             : ["- No secret-shaped values detected."]),
         "",
+        "## Unmanifested Markdown Modules",
+        "",
+        "- Advisory: existing .md files not declared by the README Module Index are excluded from this round's Case/coverage/partition scope.",
+        ...(manifest.unmanifested.length > 0
+            ? manifest.unmanifested.map((item) => `- ${item}`)
+            : ["- None"]),
+        "",
         "## Findings",
         "",
         ...(findings.length > 0 ? findings.map((finding) => `- ${finding}`) : ["- None"]),

package/dist/workflows/dag/backend-test-pytest-collection.js

@@ -20,6 +20,14 @@ export const backendPytestCollectionFindingSchema = z.object({
     classification: z.literal("test-asset-defect"),
     repairability: z.enum(["repairable", "blocked"]),
     detail: z.string().min(1),
+    caseId: z.string().min(1).optional(),
+    reasonCodes: z.array(z.string().min(1)).optional(),
+    repairPaths: z.array(z.string().min(1)).optional(),
+    payloadExpectedPaths: z.array(z.string()).optional(),
+    payloadObservedPaths: z.array(z.string()).optional(),
+    payloadMissingPaths: z.array(z.string()).optional(),
+    payloadUnexpectedPaths: z.array(z.string()).optional(),
+    payloadEnumMismatches: z.array(z.string()).optional(),
 }).strict();
 export const backendPytestCollectionFactsSchema = z.object({
     schemaId: z.literal("backend-test-pytest-collection-v3"),
@@ -61,11 +69,22 @@ export const backendPytestCollectionFactsSchema = z.object({
         context.addIssue({ code: z.ZodIssueCode.custom, message: "backend pytest fixture resolution without an attempt cannot have an exit code" });
     }
 });
+const backendTestScenarioParamDiagnosticSchema = z.object({
+    reasonCode: z.enum(["SCENARIO_PARAM_MISMATCH", "SCENARIO_PARAM_UNDETERMINED"]),
+    tpId: z.string().min(1).max(256),
+    field: z.string().min(1).max(256).optional(),
+    expectedRaw: z.string().max(512).optional(),
+    observedRaw: z.string().max(512),
+    expectedNormalized: z.string().max(512).optional(),
+    observedNormalized: z.string().max(512).optional(),
+    sourceLocation: z.string().max(512).optional(),
+}).strict();
 const backendTestExcludedItemSchema = z.object({
     itemId: z.string().min(1),
     caseId: z.string().optional(),
     symbol: z.string().optional(),
     reasons: z.array(z.string().min(1)).min(1),
+    scenarioParamDiagnostics: z.array(backendTestScenarioParamDiagnosticSchema).max(16).optional(),
 }).strict();
 export const backendTestExecutionReadinessSchema = z.object({
     schemaId: z.literal("backend-test-execution-readiness-v2"),
@@ -81,6 +100,14 @@ export const backendTestExecutionReadinessSchema = z.object({
     collectedItemIds: z.array(z.string()),
     eligibleItemIds: z.array(z.string()),
     excludedItems: z.array(backendTestExcludedItemSchema),
+    exclusionSummary: z.object({
+        excludedItemCount: z.number().int().min(0),
+        excludedCaseCount: z.number().int().min(0),
+        excludedByReason: z.record(z.string(), z.number().int().min(1)),
+        excludedByCase: z.record(z.string(), z.number().int().min(1)),
+    }).strict(),
+    pytestSpawned: z.literal(false),
+    businessTestBodyExecutedCount: z.literal(0),
     fixtureIssues: z.array(z.string()),
     assetHashes: z.record(z.string(), z.string().regex(SHA256)),
     eligibilityInputHashes: z.record(z.string(), z.string().regex(SHA256)),
@@ -131,6 +158,23 @@ function normalizeHazardOccurrenceIdentity(line) {
     // Unclosed quote or no out-of-string `#`: do not invent a comment boundary.
     return trimmed;
 }
+/**
+ * Bare `__NNN_*` helper module names imported by a Python source snippet.
+ * Only the head token of an `import`/`from` statement is considered a module
+ * name; dotted submodules (`__551_manager_helpers.x`) collapse to the head.
+ */
+function importedBareHelperModules(source) {
+    const names = [];
+    const seen = new Set();
+    for (const match of normalizeSourceNewlines(source).matchAll(/\b(?:import|from)\s+([A-Za-z0-9_.]+)/g)) {
+        const head = match[1].split(".")[0];
+        if (/^__\d+[A-Za-z0-9_]*$/.test(head) && !seen.has(head)) {
+            seen.add(head);
+            names.push(head);
+        }
+    }
+    return names;
+}
 function listPatternOccurrences(source, patternSource, flags = "") {
     const normalized = normalizeSourceNewlines(source);
     const pattern = new RegExp(patternSource, flags.includes("g") ? flags : `${flags}g`);
@@ -221,6 +265,8 @@ export async function buildBackendPytestAssetInventory(workspaceRoot, mappedScri
     const inputHashes = {};
     const hazardOccurrenceCounts = {};
     const hazardOccurrences = {};
+    const scriptBareImports = {};
+    const mappedScriptSet = new Set(normalizedScripts);
     for (const file of assetFiles) {
         const bytes = await readFile(path.resolve(workspaceRoot, file));
         const source = bytes.toString("utf8");
@@ -228,8 +274,10 @@ export async function buildBackendPytestAssetInventory(workspaceRoot, mappedScri
         const lists = scanRepairHazardOccurrenceLists(source);
         hazardOccurrences[file] = lists;
         hazardOccurrenceCounts[file] = Object.fromEntries(Object.entries(lists).map(([label, identities]) => [label, identities.length]));
+        if (mappedScriptSet.has(file))
+            scriptBareImports[file] = importedBareHelperModules(source);
     }
-    return { mappedScripts: normalizedScripts, assetFiles, inputHashes, hazardOccurrenceCounts, hazardOccurrences };
+    return { mappedScripts: normalizedScripts, assetFiles, inputHashes, hazardOccurrenceCounts, hazardOccurrences, scriptBareImports };
 }
 function bounded(value) {
     const normalized = value.replaceAll(/(Bearer|Basic)\s+[A-Za-z0-9._~+\/-]+/gi, "$1 [REDACTED]");
@@ -237,13 +285,14 @@ function bounded(value) {
         ? normalized
         : `${normalized.slice(0, MAX_DIAGNOSTIC_CHARS)}\n...[truncated]`;
 }
-function collectionItems(stdout) {
+function collectionItems(stdout, layout) {
+    const rootPrefix = `${(layout ?? resolveBackendTestLayout(undefined)).testRoot}/`;
     return [...new Set(stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => {
             if (!line.includes("::"))
                 return false;
             if (/^(ERROR|FAILED|E\s+)/.test(line))
                 return false;
-            return /^testcase\//.test(line.replaceAll("\\", "/"));
+            return line.replaceAll("\\", "/").startsWith(rootPrefix);
         }).map((line) => line.replaceAll("\\", "/")))];
 }
 function escapeRegExp(value) {
@@ -308,8 +357,68 @@ function classifyFixtureResolutionFailure(output, layout) {
         repairPaths: paths,
     };
 }
-function classifyCollectionFailure(output) {
+/**
+ * Generated-local bare helper module signatures found in the bound pytest
+ * asset inventory. A file such as `testcase/__551_manager_helpers.py` in the
+ * test root/script dir is generated-local: when collection reports
+ * `No module named '__551_manager_helpers'`, the defect can be precisely
+ * attributed to the generated mapped script instead of a missing third-party
+ * package.
+ */
+function generatedLocalBareHelperNames(inventory) {
+    if (!inventory)
+        return [];
+    const names = [];
+    for (const file of inventory.assetFiles) {
+        const stem = path.posix.basename(file).replace(/\.py$/, "");
+        if (/^__\d+[A-Za-z0-9_]*$/.test(stem))
+            names.push(stem);
+    }
+    return [...new Set(names)];
+}
+function classifyCollectionFailure(output, evidence) {
     const normalized = output.replaceAll("\\", "/");
+    const helperNames = generatedLocalBareHelperNames(evidence?.inventory);
+    const helperByLower = new Map(helperNames.map((name) => [name.toLowerCase(), name]));
+    // A bare `__NNN_...` module import that collection cannot find is only a
+    // candidate generated-local helper signature. REPAIRABLE requires two
+    // deterministic pieces of evidence: (1) a helper asset of the same name in
+    // the bound inventory, and (2) at least one mapped generated script whose
+    // source truly imports that bare module. Without both — or when attribution
+    // is impossible — fail closed as BLOCKED so an un-attributable dependency
+    // error is never widened into a repair. Genuine third-party modules (no
+    // `__NNN_` signature) stay BLOCKED below.
+    const missingModule = /No module named ['\"]([^'\"]+)['\"]/i.exec(normalized)?.[1];
+    if (missingModule && /^__\d+[A-Za-z0-9_]*$/.test(missingModule)) {
+        const helperAsset = helperByLower.get(missingModule.toLowerCase());
+        const inventory = evidence?.inventory;
+        const scriptBareImports = inventory?.scriptBareImports ?? {};
+        const missingLower = missingModule.toLowerCase();
+        const importedByMappedScript = inventory
+            ? inventory.mappedScripts.some((script) => (scriptBareImports[script] ?? []).some((name) => name.toLowerCase() === missingLower))
+            : false;
+        if (helperAsset && importedByMappedScript && inventory) {
+            const repairPaths = [...new Set([
+                    ...(helperAsset
+                        ? inventory.assetFiles.filter((file) => path.posix.basename(file).replace(/\.py$/, "") === helperAsset)
+                        : []),
+                    ...inventory.mappedScripts,
+                ])].sort();
+            return {
+                status: "REPAIRABLE",
+                kind: "missing-generated-local-helper",
+                detail: `generated testcase asset imports missing bare generated-local helper module ${missingModule}; inline the helper or remove the generated shared dependency`,
+                repairPaths,
+            };
+        }
+        return {
+            status: "BLOCKED",
+            kind: "missing-generated-local-helper-without-evidence",
+            detail: helperAsset
+                ? `missing bare generated-local helper module ${missingModule} has a name match but no mapped generated script imports it (no precise generated-local attribution)`
+                : `missing bare __NNN_* module ${missingModule} has no generated-local helper asset in the bound inventory (cannot be precisely attributed)`,
+        };
+    }
     const blockedPatterns = [
         [/No module named ['\"](?!testcase(?:\.|['\"]))/i, "missing-third-party-module"],
         [/pytest(?:_|-)plugin|pluggy|unknown hook|unrecognized arguments/i, "pytest-plugin-or-config"],
@@ -335,7 +444,7 @@ function classifyCollectionFailure(output) {
     return { status: "BLOCKED", kind: "unclassified-collection-error", detail: "collection failure cannot be safely attributed to generated testcase assets" };
 }
 export function assessBackendPytestCollection(input) {
-    const items = collectionItems(input.stdout);
+    const items = collectionItems(input.stdout, input.layout);
     const fixtureResolution = input.fixtureResolution ?? { exitCode: 0, stdout: "fixture resolution assumed by direct assessor", stderr: "" };
     if (input.exitCode === 0 && fixtureResolution.exitCode === 0) {
         return backendPytestCollectionFactsSchema.parse({
@@ -401,7 +510,7 @@ export function assessBackendPytestCollection(input) {
             fixtureStderrExcerpt: bounded(fixtureResolution.stderr),
         });
     }
-    const classification = classifyCollectionFailure(`${input.stdout}\n${input.stderr}`);
+    const classification = classifyCollectionFailure(`${input.stdout}\n${input.stderr}`, { layout: input.layout, inventory: input.inventory });
     return backendPytestCollectionFactsSchema.parse({
         schemaId: "backend-test-pytest-collection-v3",
         phase: input.phase,
@@ -412,7 +521,9 @@ export function assessBackendPytestCollection(input) {
         fixtureResolutionAttempted: false,
         fixtureResolutionStatus: "NOT_RUN",
         fixtureResolutionExitCode: null,
-        repairPaths: testcasePythonPaths(`${input.stdout}\n${input.stderr}`),
+        repairPaths: classification.repairPaths && classification.repairPaths.length > 0
+            ? classification.repairPaths
+            : testcasePythonPaths(`${input.stdout}\n${input.stderr}`),
         mappedScripts: input.inventory.mappedScripts,
         existingMappedScripts: input.inventory.mappedScripts,
         missingMappedScripts: [],
@@ -618,6 +729,7 @@ export function buildBackendTestItemEligibility(collectedItemIds, input) {
         const parameterTokens = orderedUnique((itemId.match(/TP-[A-Z0-9-]+/g) ?? []));
         const mapping = input.correspondenceEntries.find((entry) => symbol && (entry.declaredPrimarySymbol === symbol || entry.pytestSymbols.includes(symbol)));
         const reasons = [];
+        const scenarioParamDiagnostics = [];
         if (!mapping)
             reasons.push("no exact Markdown Case/primary-symbol correspondence");
         if (mapping && mapping.status !== "EXACT_1_TO_1")
@@ -640,13 +752,30 @@ export function buildBackendTestItemEligibility(collectedItemIds, input) {
             // or observed Python payload shape.
             const normalizedField = entry.field?.toLowerCase();
             const fieldIsPayloadBound = Boolean(normalizedField && payloadPaths.some((item) => item === normalizedField || item.endsWith(`.${normalizedField}`)));
-            if (fieldIsPayloadBound && entry.status !== "MATCH")
+            if (fieldIsPayloadBound && entry.status !== "MATCH") {
                 reasons.push(`scenario-param ${entry.tpId} field ${entry.field} is ${entry.status}`);
+                scenarioParamDiagnostics.push({
+                    reasonCode: entry.status === "MISMATCH" ? "SCENARIO_PARAM_MISMATCH" : "SCENARIO_PARAM_UNDETERMINED",
+                    tpId: entry.tpId,
+                    ...(entry.field ? { field: entry.field } : {}),
+                    ...(entry.expectedRaw !== undefined ? { expectedRaw: entry.expectedRaw.slice(0, 512) } : {}),
+                    observedRaw: (entry.observedRaw ?? "unavailable").slice(0, 512),
+                    ...(entry.expectedNormalized !== undefined ? { expectedNormalized: entry.expectedNormalized.slice(0, 512) } : {}),
+                    ...(entry.observedNormalized !== undefined ? { observedNormalized: entry.observedNormalized.slice(0, 512) } : {}),
+                    ...(entry.sourceLocation ? { sourceLocation: entry.sourceLocation.slice(0, 512) } : {}),
+                });
+            }
         }
         if (reasons.length === 0)
             eligibleItemIds.push(itemId);
         else
-            excludedItems.push({ itemId, ...(mapping?.caseId ? { caseId: mapping.caseId } : {}), ...(symbol ? { symbol } : {}), reasons: orderedUnique(reasons) });
+            excludedItems.push({
+                itemId,
+                ...(mapping?.caseId ? { caseId: mapping.caseId } : {}),
+                ...(symbol ? { symbol } : {}),
+                reasons: orderedUnique(reasons),
+                ...(scenarioParamDiagnostics.length > 0 ? { scenarioParamDiagnostics: scenarioParamDiagnostics.slice(0, 16) } : {}),
+            });
     }
     return { eligibleItemIds, excludedItems };
 }
@@ -657,7 +786,7 @@ export async function materializeBackendTestExecutionReadiness(input) {
     if (input.effective.phase !== "effective" || input.effective.status !== "PASS" || input.effective.fixtureResolutionStatus !== "PASS") {
         throw new Error("backend-test execution readiness requires effective collection and fixture-resolution PASS");
     }
-    const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.effective.mappedScripts);
+    const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.effective.mappedScripts, { layout: input.layout });
     assertSameInventory(input.effective, current);
     const eligibility = input.eligibility ?? { eligibleItemIds: input.effective.collectedItemIds, excludedItems: [] };
     const status = eligibility.eligibleItemIds.length === 0
@@ -679,6 +808,9 @@ export async function materializeBackendTestExecutionReadiness(input) {
         collectedItemIds: input.effective.collectedItemIds,
         eligibleItemIds: eligibility.eligibleItemIds,
         excludedItems: eligibility.excludedItems,
+        exclusionSummary: summarizeBackendTestExclusions(eligibility.excludedItems),
+        pytestSpawned: false,
+        businessTestBodyExecutedCount: 0,
         fixtureIssues: input.effective.findings.filter((item) => /fixture/i.test(item.kind)).map((item) => item.detail),
         assetHashes: input.effective.inputHashes,
         eligibilityInputHashes: input.eligibilityInputHashes ?? {},
@@ -694,6 +826,26 @@ export async function readBackendTestExecutionReadiness(filePath) {
 function formatReadinessCounts(readiness) {
     return `mapped=${readiness.mappedScripts.length} collected=${readiness.collectedItemIds.length} eligible=${readiness.eligibleItemIds.length} excluded=${readiness.excludedItems.length}`;
 }
+export function summarizeBackendTestExclusions(excludedItems) {
+    const reasonCounts = new Map();
+    const caseCounts = new Map();
+    for (const item of excludedItems) {
+        if (item.caseId)
+            caseCounts.set(item.caseId, (caseCounts.get(item.caseId) ?? 0) + 1);
+        for (const reason of item.reasons) {
+            const category = classifyExclusionReason(reason);
+            reasonCounts.set(category, (reasonCounts.get(category) ?? 0) + 1);
+        }
+    }
+    return {
+        excludedItemCount: excludedItems.length,
+        excludedCaseCount: caseCounts.size,
+        excludedByReason: Object.fromEntries(READINESS_EXCLUSION_CATEGORIES
+            .filter((category) => (reasonCounts.get(category) ?? 0) > 0)
+            .map((category) => [category, reasonCounts.get(category)])),
+        excludedByCase: Object.fromEntries([...caseCounts.entries()].sort(([left], [right]) => left.localeCompare(right))),
+    };
+}
 export function classifyExclusionReason(reason) {
     if (reason === "no exact Markdown Case/primary-symbol correspondence")
         return "correspondence-missing";
@@ -756,7 +908,7 @@ async function firstUnreadableAssetPath(workspaceRoot, readiness) {
     }
     return undefined;
 }
-export async function assertBackendTestExecutionReadinessFresh(workspaceRoot, readiness) {
+export async function assertBackendTestExecutionReadinessFresh(workspaceRoot, readiness, layout) {
     if (!["PASS", "PARTIAL"].includes(readiness.status)) {
         const counts = formatReadinessCounts(readiness);
         const reasonTally = readiness.eligibleItemIds.length === 0 && readiness.excludedItems.length > 0
@@ -779,7 +931,7 @@ export async function assertBackendTestExecutionReadinessFresh(workspaceRoot, re
     }
     let current;
     try {
-        current = await buildBackendPytestAssetInventory(workspaceRoot, readiness.mappedScripts);
+        current = await buildBackendPytestAssetInventory(workspaceRoot, readiness.mappedScripts, { layout });
     }
     catch {
         const fallbackPath = [...readiness.mappedScripts].sort()[0] ?? Object.keys(readiness.assetHashes).sort()[0] ?? "unknown";
@@ -814,11 +966,11 @@ export async function assertBackendTestExecutionReadinessFresh(workspaceRoot, re
         }
     }
 }
-export async function assertBackendPytestCollectionFresh(workspaceRoot, effective) {
+export async function assertBackendPytestCollectionFresh(workspaceRoot, effective, layout) {
     if (effective.phase !== "effective" || effective.status !== "PASS") {
         throw new Error("backend pytest execution requires effective collection PASS facts");
     }
-    const current = await buildBackendPytestAssetInventory(workspaceRoot, effective.mappedScripts);
+    const current = await buildBackendPytestAssetInventory(workspaceRoot, effective.mappedScripts, { layout });
     const priorityOnly = priorityOnlyBackendPytestScripts(current.assetFiles);
     if (priorityOnly.length > 0)
         throw new Error(`priority-only-pytest-module: ${priorityOnly.join(", ")}`);
@@ -826,7 +978,7 @@ export async function assertBackendPytestCollectionFresh(workspaceRoot, effectiv
 }
 export async function materializeEffectiveBackendPytestCollection(input) {
     if (input.initial.status === "PASS") {
-        const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.initial.mappedScripts);
+        const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.initial.mappedScripts, { layout: input.layout });
         const priorityOnly = priorityOnlyBackendPytestScripts(current.assetFiles);
         if (priorityOnly.length > 0)
             throw new Error(`priority-only-pytest-module: ${priorityOnly.join(", ")}`);
@@ -844,7 +996,7 @@ export async function materializeEffectiveBackendPytestCollection(input) {
     if (input.final.status !== "PASS")
         throw new Error("backend pytest collection still fails after bounded repair");
     await assertBackendPytestRepairSafety(input.workspaceRoot, input.initial, input.final);
-    const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.final.mappedScripts);
+    const current = await buildBackendPytestAssetInventory(input.workspaceRoot, input.final.mappedScripts, { layout: input.layout });
     const priorityOnly = priorityOnlyBackendPytestScripts(current.assetFiles);
     if (priorityOnly.length > 0)
         throw new Error(`priority-only-pytest-module: ${priorityOnly.join(", ")}`);

package/dist/workflows/dag/backend-test-result-contract.js

@@ -70,6 +70,7 @@ export const backendTestResultContractSchema = z
     schemaVersion: z.literal(1),
     /** Process-level status of the pytest invocation. Task Pool: use with outcome. */
     executionStatus: backendTestExecutionStatusSchema,
+    pytestSpawned: z.literal(true),
     pytestExitCode: z.number().int().min(0).max(255),
     collectionStatus: backendTestCollectionStatusSchema,
     /** Total tests counted from JUnit (or 0 when report unavailable). */
@@ -659,6 +660,7 @@ export function deriveBackendTestResult(input) {
         const result = {
             schemaVersion: 1,
             executionStatus,
+            pytestSpawned: true,
             pytestExitCode: input.pytestExitCode,
             collectionStatus: "unknown",
             tests: 0,
@@ -733,6 +735,7 @@ export function deriveBackendTestResult(input) {
     const result = {
         schemaVersion: 1,
         executionStatus,
+        pytestSpawned: true,
         pytestExitCode: exit,
         collectionStatus,
         tests: parsed.tests,
@@ -936,6 +939,7 @@ export async function materializeBackendTestResultFromPytestHtml(input) {
     const result = backendTestResultContractSchema.parse({
         schemaVersion: 1,
         executionStatus,
+        pytestSpawned: true,
         pytestExitCode: exit,
         collectionStatus,
         tests: parsed.tests,