@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/workflows/dag/backend-test-writer-completeness.js

@@ -0,0 +1,1058 @@
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { BACKEND_TEST_MAX_MODULE_COUNT, isOpaqueHashBackendTestModuleStem, isPriorityOnlyBackendTestModuleStem, } from "./backend-test-module-stem.js";
+import { resolveBackendTestLayout, } from "./backend-test-layout.js";
+/**
+ * Maps a backend-test generation writer task id to its writer-progress role.
+ * Returns undefined for nodes that are not completeness-gated generators.
+ *
+ * Recognizes both the legacy single-node literal ids
+ * (`generate-backend-md-cases-pi` / `generate-backend-pytest-pi`) and the
+ * map_agent sharded child ids (`generate-backend-md-case-0001` /
+ * `generate-backend-pytest-case-0001`). The literal fallback keeps hand-
+ * written test DAGs that bypass buildHybridDagFromTask green.
+ */
+export function backendTestWriterProgressRoleForTask(taskId) {
+    if (!taskId)
+        return undefined;
+    if (taskId === "generate-backend-md-cases-pi" ||
+        taskId === "generate-backend-md-plan-pi" ||
+        taskId.startsWith("generate-backend-md-case-"))
+        return "md-generate";
+    if (taskId === "generate-backend-pytest-pi" ||
+        taskId === "generate-backend-pytest-plan-pi" ||
+        taskId.startsWith("generate-backend-pytest-case-"))
+        return "pytest-generate";
+    return undefined;
+}
+import { expectedBackendTestPytestScriptForMarkdownModule, normalizeBackendTestModuleStem, } from "./backend-test-markdown-workflow.js";
+export const BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID = "backend-test-writer-progress-v1";
+export const BACKEND_TEST_OUTPUT_LIMIT_RECOVERY_REPORT = "backend-test-output-limit-recovery.md";
+const progressSchema = z
+    .object({
+    schemaId: z.literal(BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID),
+    role: z.enum(["md-generate", "pytest-generate", "report"]),
+    status: z.enum(["PASS", "RECOVERABLE", "NON_RECOVERABLE"]),
+    expectedPaths: z.array(z.string()),
+    actualPaths: z.array(z.string()),
+    missingPaths: z.array(z.string()),
+    brokenPaths: z.array(z.string()),
+    targetPaths: z.array(z.string()),
+    issues: z.array(z
+        .object({
+        code: z.enum(["T3", "T4", "T5", "T6"]),
+        path: z.string().optional(),
+        detail: z.string(),
+        recoverable: z.boolean(),
+    })
+        .strict()),
+})
+    .strict();
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function orderedUnique(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+function hasMarkdownTable(section, headerNeedle) {
+    const lines = section
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .split("\n");
+    // A markdown table header row must itself be a pipe-delimited row (start
+    // and end with `|`) AND be immediately followed by a separator row
+    // (`|---|`). Find the first row that satisfies both and contains the
+    // needle, so a Coverage Scope data cell like `| Affected Rule Keys |`
+    // (which mentions the needle but is not a header) does not shadow the
+    // real Coverage Matrix header further down.
+    const headerIndex = lines.findIndex((line, index) => {
+        const trimmed = line.trim();
+        const next = (lines[index + 1] ?? "").trim();
+        return (trimmed.startsWith("|") &&
+            trimmed.endsWith("|") &&
+            /^\|[-: |]+$/.test(next) &&
+            /-{3,}/.test(next) &&
+            line.toLowerCase().includes(headerNeedle.toLowerCase()));
+    });
+    if (headerIndex < 0)
+        return false;
+    const header = lines[headerIndex] ?? "";
+    const separator = lines[headerIndex + 1] ?? "";
+    return (header.includes("|") &&
+        /-{3,}/.test(separator) &&
+        separator.includes("|"));
+}
+/**
+ * A README module stem must be a stable lowercase business stem such as
+ * `health` or `resource_notes`. Reject tokens that are purely numeric, look
+ * like Case IDs, or were clearly lifted from prose examples (e.g. `1`,
+ * `9`, `BE-RN-001`). This prevents the completeness gate from inventing
+ * phantom missing modules when the model discusses forbidden filenames
+ * ("do not create 1.md / 9.md") inside the README body.
+ */
+function moduleStemInvalidReason(raw) {
+    if (!raw)
+        return "invalid-syntax";
+    const stem = normalizeBackendTestModuleStem(raw);
+    if (isPriorityOnlyBackendTestModuleStem(stem))
+        return "priority-only-module-stem";
+    if (isOpaqueHashBackendTestModuleStem(stem))
+        return "opaque-hash-module-stem";
+    if (stem.toLowerCase() === "readme")
+        return "reserved-module-stem";
+    if (!/^[a-z][a-z0-9_]*$/.test(stem))
+        return "invalid-syntax";
+    if (/^(?:be|tp|ac|req|br)[_-]/i.test(stem))
+        return "case-like-module-stem";
+    return undefined;
+}
+function looksLikeValidModuleStem(raw) {
+    return moduleStemInvalidReason(raw) === undefined;
+}
+function extractCanonicalModuleIndexSection(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 === 0) {
+        return { section: "", structureIssues: ["missing-module-index"] };
+    }
+    if (headings.length > 1) {
+        return { section: "", structureIssues: ["duplicate-module-index"] };
+    }
+    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;
+    return { section: lines.slice(start, end).join("\n"), structureIssues: [] };
+}
+/** Inspect only candidates inside the unique exact `## Module Index` section. */
+export function inspectModuleStemsFromReadme(readme) {
+    const extracted = extractCanonicalModuleIndexSection(readme);
+    const candidates = [];
+    const tableRowLines = extracted.section.split("\n").filter((line) => line.includes("|"));
+    for (const line of tableRowLines) {
+        for (const match of line.matchAll(/`?testcase\/md\/([A-Za-z0-9_.-]+)\.md`?/g)) {
+            candidates.push(match[1]);
+        }
+        for (const match of line.matchAll(/\|\s*`?([A-Za-z0-9_.-]+)`?\s*\|\s*`?testcase\/test_/g)) {
+            const raw = match[1];
+            if (looksLikeValidModuleStem(raw) || moduleStemInvalidReason(raw) !== "invalid-syntax") {
+                candidates.push(raw);
+            }
+        }
+    }
+    for (const match of extracted.section.matchAll(/\[[^\]]+\]\(\.\/([A-Za-z0-9_.-]+)\.md\)/g)) {
+        candidates.push(match[1]);
+    }
+    const uniqueCandidates = orderedUnique(candidates);
+    const invalid = uniqueCandidates.flatMap((raw) => {
+        const reasonCode = moduleStemInvalidReason(raw);
+        return reasonCode
+            ? [{ raw, normalized: normalizeBackendTestModuleStem(raw), reasonCode }]
+            : [];
+    });
+    const validStems = orderedUnique(uniqueCandidates
+        .filter(looksLikeValidModuleStem)
+        .map((stem) => normalizeBackendTestModuleStem(stem)));
+    const structureIssues = [...extracted.structureIssues];
+    if (validStems.length > BACKEND_TEST_MAX_MODULE_COUNT) {
+        structureIssues.push(`excessive-module-count: ${validStems.length} > ${BACKEND_TEST_MAX_MODULE_COUNT}`);
+    }
+    return {
+        candidates: uniqueCandidates,
+        validStems,
+        invalid,
+        structureIssues,
+    };
+}
+/**
+ * Exported for reuse by callers that only need the trusted shard set.
+ * Completeness gates must use inspectModuleStemsFromReadme so invalid
+ * authoritative candidates cannot be silently dropped.
+ */
+export function extractModuleStemsFromReadme(readme) {
+    return inspectModuleStemsFromReadme(readme).validStems;
+}
+async function listMarkdownModules(workspaceRoot, layout) {
+    const resolved = layout ?? resolveBackendTestLayout(undefined);
+    const root = path.join(workspaceRoot, ...resolved.markdownDir.split("/"));
+    if (!(await exists(root)))
+        return [];
+    const entries = await readdir(root, { withFileTypes: true });
+    return orderedUnique(entries
+        .filter((entry) => entry.isFile() &&
+        entry.name.toLowerCase().endsWith(".md") &&
+        entry.name.toLowerCase() !== "readme.md")
+        .map((entry) => path.posix.join(resolved.markdownDir, entry.name.replaceAll("\\", "/"))));
+}
+/**
+ * Recursively list `.py` file paths relative to `dirRoot` (forward slashes).
+ * Used by the pytest plan-node completeness check to discover shared
+ * helpers/factories resources.
+ */
+async function listPythonFiles(dirRoot) {
+    if (!(await exists(dirRoot)))
+        return [];
+    const out = [];
+    const walk = async (rel) => {
+        const absolute = path.join(dirRoot, rel);
+        const entries = await readdir(absolute, { withFileTypes: true });
+        for (const entry of entries) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(childRel);
+            }
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith(".py")) {
+                out.push(childRel.replaceAll("\\", "/"));
+            }
+        }
+    };
+    await walk("");
+    return orderedUnique(out);
+}
+const MODULE_REQUIRED_SECTIONS = [
+    "\u8986\u76d6\u89c4\u5219",
+    "\u6d4b\u8bd5\u70b9",
+    "\u573a\u666f\u7c7b\u578b",
+    "\u524d\u7f6e\u6761\u4ef6",
+    "\u64cd\u4f5c\u6b65\u9aa4",
+    "\u9884\u671f\u7ed3\u679c",
+    "\u81ea\u52a8\u5316\u6620\u5c04",
+];
+/**
+ * Structural check for a backend-test Markdown module file. Returns structured
+ * reasons instead of a bare boolean so the Completeness Gate T5 detail and the
+ * retry prompt can tell the model exactly what is wrong (empty file / wrong
+ * case heading level / invalid case id format / missing sections). This avoids
+ * the "model cannot fix what it does not know" retry death-loop.
+ */
+function moduleStructurallyComplete(markdown) {
+    if (!markdown.trim()) {
+        return { ok: false, reasons: ["file is empty"] };
+    }
+    const h2CaseMatch = /^##\s+BE-[A-Z0-9_-]+-\d{2,3}\b/m.exec(markdown);
+    if (!h2CaseMatch) {
+        // Distinguish "wrong level (### or ####)" from "invalid format / no case at all"
+        // so the retry hint is actionable.
+        const wrongLevel = /^#{3,4}\s+BE-[A-Z0-9_-]+-\d{2,3}\b/m.exec(markdown);
+        if (wrongLevel) {
+            const hashes = /^#+/.exec(wrongLevel[0])?.[0].length ?? 3;
+            return {
+                ok: false,
+                reasons: [
+                    `case heading at wrong level: found '${hashes > 3 ? "####" : "###"} ${wrongLevel[0].replace(/^#+\s+/, "")}', require exactly 2 hashes '## BE-<MODULE>-<NNN>'`,
+                ],
+            };
+        }
+        const anyCaseId = /^#{2,4}\s+BE-[A-Z0-9_-]+-\d{1,4}/m.exec(markdown);
+        if (anyCaseId) {
+            return {
+                ok: false,
+                reasons: [
+                    `invalid case heading format: '${anyCaseId[0].replace(/^#+\s+/, "")}' (need exactly 2-3 digit zero-padded NNN, e.g. BE-MOD-001)`,
+                ],
+            };
+        }
+        return {
+            ok: false,
+            reasons: [
+                "no h2 case heading found (require exactly '## BE-<MODULE>-<NNN>')",
+            ],
+        };
+    }
+    const missing = MODULE_REQUIRED_SECTIONS.filter((heading) => !markdown.includes(`### ${heading}`));
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            reasons: [`missing required sections: [${missing.join(", ")}]`],
+        };
+    }
+    return { ok: true, reasons: [] };
+}
+function moduleStructuralDetail(result) {
+    if (result.ok)
+        return "module file is structurally complete";
+    return `module file is empty or has structural issues: ${result.reasons.join("; ")}`;
+}
+function pythonStructureOutsideStrings(source) {
+    const input = source.replace(/\r\n/g, "\n");
+    let output = "";
+    let index = 0;
+    let quote;
+    let triple = false;
+    let comment = false;
+    while (index < input.length) {
+        const char = input[index];
+        if (comment) {
+            if (char === "\n") {
+                comment = false;
+                output += "\n";
+            }
+            else
+                output += " ";
+            index += 1;
+            continue;
+        }
+        if (quote) {
+            if (char === "\\") {
+                output += " ";
+                if (index + 1 < input.length)
+                    output += input[index + 1] === "\n" ? "\n" : " ";
+                index += 2;
+                continue;
+            }
+            if (triple && input.slice(index, index + 3) === quote.repeat(3)) {
+                output += "   ";
+                index += 3;
+                quote = undefined;
+                triple = false;
+                continue;
+            }
+            if (!triple && char === quote) {
+                output += " ";
+                index += 1;
+                quote = undefined;
+                continue;
+            }
+            if (!triple && char === "\n")
+                return { text: output, stringsClosed: false };
+            output += char === "\n" ? "\n" : " ";
+            index += 1;
+            continue;
+        }
+        if (char === "#") {
+            comment = true;
+            output += " ";
+            index += 1;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            triple = input.slice(index, index + 3) === char.repeat(3);
+            output += triple ? "   " : " ";
+            index += triple ? 3 : 1;
+            continue;
+        }
+        output += char;
+        index += 1;
+    }
+    return { text: output, stringsClosed: quote === undefined };
+}
+function pythonParseable(source) {
+    const normalized = source.replace(/\r\n/g, "\n");
+    if (!normalized.trim())
+        return false;
+    if (/^\s*(?:def|class|import|from)\b/m.test(normalized) === false)
+        return false;
+    const structural = pythonStructureOutsideStrings(normalized);
+    if (!structural.stringsClosed)
+        return false;
+    const text = structural.text;
+    const openParens = (text.match(/\(/g) ?? []).length;
+    const closeParens = (text.match(/\)/g) ?? []).length;
+    const openBrackets = (text.match(/\[/g) ?? []).length;
+    const closeBrackets = (text.match(/\]/g) ?? []).length;
+    const openBraces = (text.match(/\{/g) ?? []).length;
+    const closeBraces = (text.match(/\}/g) ?? []).length;
+    if (openParens !== closeParens)
+        return false;
+    if (openBrackets !== closeBrackets)
+        return false;
+    if (openBraces !== closeBraces)
+        return false;
+    return true;
+}
+/**
+ * Forbidden generated shared helper/factory namespaces for the self-contained
+ * pytest module contract. A self-contained testcase/test_*.py child must not
+ * import from generated shared namespaces such as `testcase_helpers`,
+ * `testcase.helpers`, or `testcase.factories`; those belong to the pytest plan
+ * node's shared resources, not to a per-module pytest script. Rejecting such
+ * imports early (before pytest collection) gives an actionable, recoverable
+ * incomplete-write-set signal carrying the exact module target path.
+ */
+export const FORBIDDEN_GENERATED_IMPORT_NAMESPACES = [
+    "testcase_helpers",
+    "testcase.helpers",
+    "testcase.factories",
+];
+const FORBIDDEN_GENERATED_IMPORT_PATTERN = /^\s*(?:from\s+(testcase_helpers|testcase\.helpers|testcase\.factories)\b|import\s+(testcase_helpers|testcase\.helpers|testcase\.factories)\b)/gm;
+/**
+ * Scan Python source for imports from forbidden generated shared namespaces.
+ * Anchored at line start with a word boundary so `testcase.helpers_other` or a
+ * substring inside a docstring sentence is not falsely flagged. Returns the
+ * list of offending namespace module names (deduplicated, order-preserving).
+ */
+export function findForbiddenGeneratedImports(source) {
+    const hits = [];
+    const seen = new Set();
+    for (const match of source.matchAll(FORBIDDEN_GENERATED_IMPORT_PATTERN)) {
+        const ns = (match[1] ?? match[2]);
+        if (!seen.has(ns)) {
+            seen.add(ns);
+            hits.push(ns);
+        }
+    }
+    return hits;
+}
+/**
+ * Looser Python validity check for shared helpers/factories emitted by the
+ * pytest plan node. Unlike pythonParseable, it does NOT require balanced
+ * brackets/braces: shared pytest resources legitimately contain fixture
+ * strings with unbalanced delimiters (e.g. a malformed-JSON test payload
+ * `return "{bad json"`). Only verifies the file is non-empty, declares a
+ * Python construct (def/class/import/from), and has balanced triple quotes.
+ */
+function looksLikeValidPythonModule(source) {
+    const text = source.replace(/\r\n/g, "\n");
+    if (!text.trim())
+        return false;
+    if (/^\s*(?:def|class|import|from)\b/m.test(text) === false)
+        return false;
+    return pythonStructureOutsideStrings(text).stringsClosed;
+}
+export function buildOutputLimitRecoveryPrompt(input) {
+    return buildOutputLimitRecoverySection(input);
+}
+/**
+ * Build an inline `<retry_instruction>` block embedding the exact target
+ * paths. Used by {@link buildAttemptPrompt} so a continuation attempt does
+ * not depend on reading `.harness/**` (which is forbidden for Pi writers).
+ */
+export function buildOutputLimitRecoverySection(input) {
+    const hasDiagnostics = !!input.diagnostics && Object.keys(input.diagnostics).length > 0;
+    const pathsBlock = hasDiagnostics
+        ? input.targetPaths
+            .map((p) => {
+            const reasons = (input.diagnostics?.[p] ?? []).slice(0, 3);
+            if (reasons.length === 0)
+                return `  - ${p}`;
+            const issueLines = reasons.map((r) => `        - ${r}`).join("\n");
+            return `  - ${p}\n      issues:\n${issueLines}`;
+        })
+            .join("\n")
+        : input.targetPaths.length > 0
+            ? input.targetPaths.map((item) => `  - ${item}`).join("\n")
+            : "  - (none)";
+    return [
+        "<retry_instruction>",
+        `OUTPUT_LIMIT_RECOVERY attempt=${input.attempt}/${input.maxAttempts}`,
+        `reason=${input.reason}`,
+        "target_paths_only:",
+        pathsBlock,
+        "Rules:",
+        "- Continue or repair ONLY listed paths; do not delete or shrink in-scope cases/rules/TPs.",
+        "- One file per write/edit; no chat dump of full bodies.",
+        "- Prefer edit/append for truncated files; rewrite a file only if unparseable or empty.",
+        ...(hasDiagnostics
+            ? ["- Fix the exact structural issues listed under each path; do not change unrelated content."]
+            : []),
+        "- After targets are complete, short IMPLEMENTATION_OUTCOME only.",
+        "- Do not mark already-satisfied if any target_path still missing or structurally broken.",
+        "- Preserve quality invariants: no scope shrink, no skip/xfail, no secret-shaped samples.",
+        "</retry_instruction>",
+    ].join("\n");
+}
+/**
+ * Load the most recent writer-progress facts from the run dir for a given
+ * generation writer task id, so the next attempt's prompt can embed concrete
+ * target paths instead of asking the model to read a forbidden `.harness/**`
+ * path. Returns undefined when no progress facts exist yet (first retry of
+ * a session, or a non-completeness failure).
+ */
+export async function loadBackendTestWriterProgressForRetry(runDir, taskId) {
+    const role = backendTestWriterProgressRoleForTask(taskId);
+    if (!role)
+        return undefined;
+    const factsPath = path.join(runDir, "contracts", `backend-test-writer-progress-${role}.json`);
+    try {
+        const raw = await readFile(factsPath, "utf8");
+        return progressSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Per-shard-child completeness assessment for map_agent children
+ * (generate-backend-md-case-NNNN / generate-backend-pytest-case-NNNN).
+ *
+ * Unlike the workspace-wide {@link assessBackendTestMdWriterCompleteness} /
+ * {@link assessBackendTestPytestWriterCompleteness} gates (which run for the
+ * legacy single-node writers and for the post-map review/validate nodes), a
+ * sharded child owns ONLY the single file in its rendered writeSet. Running
+ * the workspace-wide gate mid-map would flag every not-yet-written sibling
+ * module as a recoverable miss and loop. This function scopes the gate to the
+ * child's own target file(s): md children are checked for structural
+ * completeness, pytest children for parseability. Sibling modules are ignored.
+ */
+export async function assessBackendTestShardChildCompleteness(input) {
+    const role = input.role;
+    const targetPaths = input.writeSet
+        .map((entry) => entry.trim().replace(/\\/g, "/").replace(/^\.\//, ""))
+        .filter((entry) => entry.length > 0);
+    const issues = [];
+    const actualPaths = [];
+    const missingPaths = [];
+    const brokenPaths = [];
+    for (const target of targetPaths) {
+        // Rendered map-child writeSet entries are concrete (e.g.
+        // testcase/md/health.md / testcase/test_orders.py); glob-only entries are
+        // not produced for these children.
+        if (target.includes("*"))
+            continue;
+        const absolute = path.join(input.workspaceRoot, target);
+        if (!(await exists(absolute))) {
+            missingPaths.push(target);
+            issues.push({
+                code: "T3",
+                path: target,
+                detail: `shard child target ${target} was not written`,
+                recoverable: true,
+            });
+            continue;
+        }
+        actualPaths.push(target);
+        const body = await readFile(absolute, "utf8");
+        if (role === "md-generate") {
+            const structural = moduleStructurallyComplete(body);
+            if (!structural.ok) {
+                brokenPaths.push(target);
+                issues.push({
+                    code: "T5",
+                    path: target,
+                    detail: moduleStructuralDetail(structural),
+                    recoverable: true,
+                });
+            }
+        }
+        else {
+            if (!pythonParseable(body)) {
+                brokenPaths.push(target);
+                issues.push({
+                    code: "T5",
+                    path: target,
+                    detail: "pytest script appears truncated or unparseable",
+                    recoverable: true,
+                });
+            }
+            const forbidden = findForbiddenGeneratedImports(body);
+            if (forbidden.length > 0) {
+                if (!brokenPaths.includes(target))
+                    brokenPaths.push(target);
+                issues.push({
+                    code: "T5",
+                    path: target,
+                    detail: `forbidden import from ${forbidden.join(", ")} in ${target}; self-contained pytest module must not import generated shared helper/factory namespaces`,
+                    recoverable: true,
+                });
+            }
+        }
+    }
+    const recoverableTargets = orderedUnique([...missingPaths, ...brokenPaths]);
+    const status = recoverableTargets.length > 0 || issues.length > 0 ? "RECOVERABLE" : "PASS";
+    return {
+        schemaId: BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID,
+        role,
+        status,
+        expectedPaths: orderedUnique(targetPaths),
+        actualPaths: orderedUnique(actualPaths),
+        missingPaths: orderedUnique(missingPaths),
+        brokenPaths: orderedUnique(brokenPaths),
+        targetPaths: recoverableTargets,
+        issues,
+    };
+}
+export async function assessBackendTestMdWriterCompleteness(workspaceRoot, layout) {
+    const resolved = layout ?? resolveBackendTestLayout(undefined);
+    const readmeRel = resolved.readmePath;
+    const issues = [];
+    const expectedPaths = [readmeRel];
+    const actualPaths = [];
+    const missingPaths = [];
+    const brokenPaths = [];
+    const readmePath = path.join(workspaceRoot, ...readmeRel.split("/"));
+    let readme = "";
+    if (!(await exists(readmePath))) {
+        missingPaths.push(readmeRel);
+        issues.push({
+            code: "T3",
+            path: readmeRel,
+            detail: "README.md is missing",
+            recoverable: true,
+        });
+    }
+    else {
+        actualPaths.push(readmeRel);
+        readme = await readFile(readmePath, "utf8");
+        if (!readme.includes("## Coverage Scope")) {
+            brokenPaths.push(readmeRel);
+            issues.push({
+                code: "T5",
+                path: readmeRel,
+                detail: "README.md is missing ## Coverage Scope",
+                recoverable: true,
+            });
+        }
+        if (!readme.includes("## Coverage Matrix") ||
+            !hasMarkdownTable(readme, "Rule Key")) {
+            if (!brokenPaths.includes(readmeRel)) {
+                brokenPaths.push(readmeRel);
+            }
+            issues.push({
+                code: "T5",
+                path: readmeRel,
+                detail: "README.md Coverage Matrix table is missing or broken",
+                recoverable: true,
+            });
+        }
+    }
+    const indexedStems = extractModuleStemsFromReadme(readme);
+    const existingModules = await listMarkdownModules(workspaceRoot, resolved);
+    const existingByStem = new Map(existingModules.map((rel) => [
+        normalizeBackendTestModuleStem(path.posix.basename(rel)),
+        rel,
+    ]));
+    for (const stem of indexedStems) {
+        const rel = `${resolved.markdownDir}/${stem}.md`;
+        expectedPaths.push(rel);
+        const existing = existingByStem.get(stem);
+        if (!existing) {
+            missingPaths.push(rel);
+            issues.push({
+                code: "T3",
+                path: rel,
+                detail: `module file missing for README index stem ${stem}`,
+                recoverable: true,
+            });
+            continue;
+        }
+        actualPaths.push(existing);
+        const body = await readFile(path.join(workspaceRoot, existing), "utf8");
+        const structural = moduleStructurallyComplete(body);
+        if (!structural.ok) {
+            brokenPaths.push(existing);
+            issues.push({
+                code: "T5",
+                path: existing,
+                detail: moduleStructuralDetail(structural),
+                recoverable: true,
+            });
+        }
+    }
+    for (const rel of existingModules) {
+        if (!actualPaths.includes(rel))
+            actualPaths.push(rel);
+        const body = await readFile(path.join(workspaceRoot, rel), "utf8");
+        const structural = moduleStructurallyComplete(body);
+        if (!structural.ok && !brokenPaths.includes(rel)) {
+            brokenPaths.push(rel);
+            issues.push({
+                code: "T5",
+                path: rel,
+                detail: moduleStructuralDetail(structural),
+                recoverable: true,
+            });
+        }
+    }
+    if (existingModules.length === 0 &&
+        indexedStems.length === 0 &&
+        (await exists(readmePath))) {
+        issues.push({
+            code: "T3",
+            detail: "no module Markdown files were produced",
+            recoverable: true,
+        });
+    }
+    const targetPaths = orderedUnique([...missingPaths, ...brokenPaths]);
+    const nonRecoverable = issues.some((issue) => !issue.recoverable);
+    const status = nonRecoverable
+        ? "NON_RECOVERABLE"
+        : targetPaths.length > 0 || issues.length > 0
+            ? "RECOVERABLE"
+            : "PASS";
+    return {
+        schemaId: BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID,
+        role: "md-generate",
+        status,
+        expectedPaths: orderedUnique(expectedPaths),
+        actualPaths: orderedUnique(actualPaths),
+        missingPaths: orderedUnique(missingPaths),
+        brokenPaths: orderedUnique(brokenPaths),
+        targetPaths,
+        issues,
+    };
+}
+export async function assessBackendTestPytestWriterCompleteness(workspaceRoot, layout) {
+    const resolved = layout ?? resolveBackendTestLayout(undefined);
+    const issues = [];
+    const expectedPaths = [];
+    const actualPaths = [];
+    const missingPaths = [];
+    const brokenPaths = [];
+    const modules = await listMarkdownModules(workspaceRoot, resolved);
+    for (const moduleRel of modules) {
+        const expected = expectedBackendTestPytestScriptForMarkdownModule(path.posix.basename(moduleRel), resolved);
+        expectedPaths.push(expected);
+        const absolute = path.join(workspaceRoot, expected);
+        if (!(await exists(absolute))) {
+            missingPaths.push(expected);
+            issues.push({
+                code: "T3",
+                path: expected,
+                detail: `mapped pytest script missing for ${moduleRel}`,
+                recoverable: true,
+            });
+            continue;
+        }
+        actualPaths.push(expected);
+        const source = await readFile(absolute, "utf8");
+        if (!pythonParseable(source)) {
+            brokenPaths.push(expected);
+            issues.push({
+                code: "T5",
+                path: expected,
+                detail: "pytest script appears truncated or unparseable",
+                recoverable: true,
+            });
+            continue;
+        }
+        const forbidden = findForbiddenGeneratedImports(source);
+        if (forbidden.length > 0) {
+            brokenPaths.push(expected);
+            issues.push({
+                code: "T5",
+                path: expected,
+                detail: `forbidden import from ${forbidden.join(", ")} in ${expected}; self-contained pytest module must not import generated shared helper/factory namespaces`,
+                recoverable: true,
+            });
+            continue;
+        }
+        const markdown = await readFile(path.join(workspaceRoot, moduleRel), "utf8");
+        const caseIds = orderedUnique([...markdown.matchAll(/\bBE-[A-Z0-9_-]+-\d{2,3}\b/g)].map((item) => item[0]));
+        const primaryHints = orderedUnique([
+            ...markdown.matchAll(/primary\s*symbol\s*[:：]\s*`?([A-Za-z0-9_]+)`?/gi),
+        ].map((item) => item[1]));
+        for (const symbol of primaryHints) {
+            if (!source.includes(symbol)) {
+                brokenPaths.push(expected);
+                issues.push({
+                    code: "T5",
+                    path: expected,
+                    detail: `primary symbol ${symbol} not found in mapped script`,
+                    recoverable: true,
+                });
+                break;
+            }
+        }
+        if (caseIds.length > 0 &&
+            !caseIds.some((caseId) => source.includes(caseId) || source.includes(caseId.replaceAll("-", "_")))) {
+            brokenPaths.push(expected);
+            issues.push({
+                code: "T5",
+                path: expected,
+                detail: "no Markdown Case ID found in mapped pytest script",
+                recoverable: true,
+            });
+        }
+    }
+    const targetPaths = orderedUnique([...missingPaths, ...brokenPaths]);
+    const status = targetPaths.length > 0 || issues.length > 0 ? "RECOVERABLE" : "PASS";
+    return {
+        schemaId: BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID,
+        role: "pytest-generate",
+        status,
+        expectedPaths: orderedUnique(expectedPaths),
+        actualPaths: orderedUnique(actualPaths),
+        missingPaths: orderedUnique(missingPaths),
+        brokenPaths: orderedUnique(brokenPaths),
+        targetPaths,
+        issues,
+    };
+}
+export function classifyBackendTestWriterCompletenessFailure(progress) {
+    if (progress.status === "PASS") {
+        return {
+            failureCategory: "invalid-output",
+            reason: "T4",
+            recoverable: false,
+        };
+    }
+    if (progress.status === "NON_RECOVERABLE") {
+        return {
+            failureCategory: "invalid-output",
+            reason: "T6",
+            recoverable: false,
+        };
+    }
+    const preferred = progress.issues.find((issue) => issue.code === "T5")?.code ??
+        progress.issues.find((issue) => issue.code === "T3")?.code ??
+        progress.issues.find((issue) => issue.code === "T4")?.code ??
+        "T3";
+    return {
+        failureCategory: "incomplete-write-set",
+        reason: preferred,
+        recoverable: true,
+    };
+}
+export async function writeBackendTestWriterProgressArtifacts(input) {
+    const contractsDir = path.join(input.runDir, "contracts");
+    await mkdir(contractsDir, { recursive: true });
+    const factsPath = path.join(contractsDir, `backend-test-writer-progress-${input.progress.role}.json`);
+    const parsed = progressSchema.parse(input.progress);
+    await writeFile(factsPath, JSON.stringify(parsed, null, 2), "utf8");
+    if (input.progress.status === "PASS") {
+        return { factsPath };
+    }
+    const reportsDir = path.join(input.runDir, "reports");
+    await mkdir(reportsDir, { recursive: true });
+    const reportPath = path.join(reportsDir, BACKEND_TEST_OUTPUT_LIMIT_RECOVERY_REPORT);
+    const attempt = input.attempt ?? 1;
+    const maxAttempts = input.maxAttempts ?? 3;
+    const classification = classifyBackendTestWriterCompletenessFailure(input.progress);
+    const body = [
+        "# Backend-test Output Limit Recovery",
+        "",
+        `- Role: ${input.progress.role}`,
+        `- Status: ${input.progress.status}`,
+        `- Attempt: ${attempt}/${maxAttempts}`,
+        `- Reason: ${classification.reason}`,
+        `- Recoverable: ${classification.recoverable}`,
+        "",
+        "## Target paths",
+        "",
+        ...(input.progress.targetPaths.length
+            ? input.progress.targetPaths.map((item) => `- ${item}`)
+            : ["- (none)"]),
+        "",
+        "## Issues",
+        "",
+        ...(input.progress.issues.length
+            ? input.progress.issues.map((issue) => `- [${issue.code}] ${issue.path ?? "(workspace)"}: ${issue.detail}`)
+            : ["- None"]),
+        "",
+        `<!-- sha256:${createHash("sha256").update(JSON.stringify(parsed)).digest("hex")} -->`,
+        "",
+    ].join("\n");
+    await writeFile(reportPath, body, "utf8");
+    return { factsPath, reportPath };
+}
+export function isBackendTestCompletenessRetryCandidate(task) {
+    if (task.executor !== "pi" || task.role !== "implementer")
+        return false;
+    if (task.toolProfile !== "write" || task.writePolicy !== "exclusive") {
+        return false;
+    }
+    if ((task.writeSet?.length ?? 0) === 0)
+        return false;
+    if (task.writerOutcomePolicy?.type !== "implementation-outcome-v1") {
+        return false;
+    }
+    return (task.id === "generate-backend-md-cases-pi" ||
+        task.id === "generate-backend-pytest-pi" ||
+        task.id === "generate-backend-md-plan-pi" ||
+        task.id === "generate-backend-pytest-plan-pi" ||
+        // Plan D gap-fill patch writers share the same Completeness Gate retry
+        // contract as full-chain writers.
+        task.id === "patch-backend-readme-matrix-pi" ||
+        (task.id?.startsWith("patch-backend-md-case-") ?? false) ||
+        (task.id?.startsWith("patch-backend-pytest-case-") ?? false) ||
+        (task.id?.startsWith("generate-backend-md-case-") ?? false) ||
+        (task.id?.startsWith("generate-backend-pytest-case-") ?? false));
+}
+/**
+ * Is this task a materialized map_agent shard child (as opposed to the legacy
+ * single-node generator)? Shard children must scope the Completeness Gate to
+ * their own rendered writeSet rather than the whole workspace.
+ */
+export function isBackendTestShardChildTask(task) {
+    return Boolean(task.id?.startsWith("generate-backend-md-case-") ||
+        task.id?.startsWith("generate-backend-pytest-case-"));
+}
+/**
+ * Is this task the README-only plan node of the map-sharded md topology?
+ * The plan node writes testcase/md/README.md alone; module case cards are
+ * produced by the downstream map_agent children, so the Completeness Gate
+ * must NOT require module files to exist at plan time.
+ */
+export function isBackendTestMdPlanTask(task) {
+    return task.id === "generate-backend-md-plan-pi";
+}
+/**
+ * Is this task the shared-resources plan node of the map-sharded pytest
+ * topology? The plan node writes helpers/factories only; per-module pytest
+ * scripts are produced by the downstream map_agent children, so the Gate
+ * must NOT require mapped pytest scripts to exist at plan time.
+ */
+export function isBackendTestPytestPlanTask(task) {
+    return task.id === "generate-backend-pytest-plan-pi";
+}
+/**
+ * Plan-node completeness for the md topology: verify the README itself is
+ * structurally complete (Coverage Scope, Coverage Matrix, a non-empty module
+ * index), WITHOUT requiring the indexed module files to exist yet — those are
+ * written by the downstream map_agent shard children.
+ */
+export async function assessBackendTestMdPlanCompleteness(workspaceRoot, layout) {
+    const resolvedPlan = layout ?? resolveBackendTestLayout(undefined);
+    const planReadmeRel = resolvedPlan.readmePath;
+    const issues = [];
+    const expectedPaths = [planReadmeRel];
+    const actualPaths = [];
+    const missingPaths = [];
+    const brokenPaths = [];
+    const readmePath = path.join(workspaceRoot, ...planReadmeRel.split("/"));
+    if (!(await exists(readmePath))) {
+        missingPaths.push(planReadmeRel);
+        issues.push({
+            code: "T3",
+            path: planReadmeRel,
+            detail: "README.md is missing",
+            recoverable: true,
+        });
+    }
+    else {
+        actualPaths.push(planReadmeRel);
+        const readme = await readFile(readmePath, "utf8");
+        if (!readme.includes("## Coverage Scope")) {
+            brokenPaths.push(planReadmeRel);
+            issues.push({
+                code: "T5",
+                path: planReadmeRel,
+                detail: "README.md is missing ## Coverage Scope",
+                recoverable: true,
+            });
+        }
+        if (!readme.includes("## Coverage Matrix") ||
+            !hasMarkdownTable(readme, "Rule Key")) {
+            if (!brokenPaths.includes(planReadmeRel)) {
+                brokenPaths.push(planReadmeRel);
+            }
+            issues.push({
+                code: "T5",
+                path: planReadmeRel,
+                detail: "README.md Coverage Matrix table is missing or broken",
+                recoverable: true,
+            });
+        }
+        // The README must advertise a non-empty module index so the downstream
+        // manifest shell has stems to shard; the indexed module files themselves
+        // are produced by map_agent children and are NOT required here.
+        const stemInspection = inspectModuleStemsFromReadme(readme);
+        const indexedStems = stemInspection.validStems;
+        for (const structureIssue of stemInspection.structureIssues) {
+            if (!brokenPaths.includes(planReadmeRel)) {
+                brokenPaths.push(planReadmeRel);
+            }
+            issues.push({
+                code: "T5",
+                path: planReadmeRel,
+                detail: structureIssue,
+                recoverable: true,
+            });
+        }
+        for (const invalid of stemInspection.invalid) {
+            if (!brokenPaths.includes(planReadmeRel)) {
+                brokenPaths.push(planReadmeRel);
+            }
+            issues.push({
+                code: "T5",
+                path: planReadmeRel,
+                detail: `${invalid.reasonCode}: ${invalid.normalized}; use a stable lowercase business resource/domain stem`,
+                recoverable: true,
+            });
+        }
+        if (indexedStems.length === 0) {
+            if (!brokenPaths.includes(planReadmeRel)) {
+                brokenPaths.push(planReadmeRel);
+            }
+            issues.push({
+                code: "T5",
+                path: planReadmeRel,
+                detail: "README.md module index is empty; downstream map_agent has no stems to shard",
+                recoverable: true,
+            });
+        }
+    }
+    const targetPaths = orderedUnique([...missingPaths, ...brokenPaths]);
+    const status = targetPaths.length > 0 ? "RECOVERABLE" : "PASS";
+    return {
+        schemaId: BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID,
+        role: "md-generate",
+        status,
+        expectedPaths: orderedUnique(expectedPaths),
+        actualPaths: orderedUnique(actualPaths),
+        missingPaths: orderedUnique(missingPaths),
+        brokenPaths: orderedUnique(brokenPaths),
+        targetPaths,
+        issues,
+    };
+}
+/**
+ * Plan-node completeness for the pytest topology: verify the shared
+ * helpers/factories resources were produced and are Python-parseable, WITHOUT
+ * requiring per-module pytest scripts to exist yet — those are written by the
+ * downstream map_agent shard children.
+ */
+export async function assessBackendTestPytestPlanCompleteness(workspaceRoot, layout) {
+    const resolvedPlan = layout ?? resolveBackendTestLayout(undefined);
+    const issues = [];
+    const expectedPaths = [];
+    const actualPaths = [];
+    const missingPaths = [];
+    const brokenPaths = [];
+    // Discover shared pytest resources under <testRoot>/**/helpers/** and
+    // <testRoot>/**/factories/** (the plan node writeSet globs).
+    const candidates = [];
+    for (const dir of [`${resolvedPlan.testRoot}/helpers`, `${resolvedPlan.testRoot}/factories`]) {
+        const absolute = path.join(workspaceRoot, dir);
+        if (await exists(absolute)) {
+            for (const file of await listPythonFiles(absolute)) {
+                candidates.push(`${dir}/${file}`);
+            }
+        }
+    }
+    if (candidates.length === 0) {
+        issues.push({
+            code: "T3",
+            detail: "no shared helpers/factories were produced; pytest plan must emit at least one shared resource",
+            recoverable: true,
+        });
+    }
+    for (const rel of candidates) {
+        expectedPaths.push(rel);
+        actualPaths.push(rel);
+        const body = await readFile(path.join(workspaceRoot, rel), "utf8");
+        if (!looksLikeValidPythonModule(body)) {
+            brokenPaths.push(rel);
+            issues.push({
+                code: "T5",
+                path: rel,
+                detail: "shared pytest resource appears truncated or unparseable",
+                recoverable: true,
+            });
+        }
+    }
+    const targetPaths = orderedUnique([...missingPaths, ...brokenPaths]);
+    const status = targetPaths.length > 0 || issues.length > 0 ? "RECOVERABLE" : "PASS";
+    return {
+        schemaId: BACKEND_TEST_WRITER_PROGRESS_SCHEMA_ID,
+        role: "pytest-generate",
+        status,
+        expectedPaths: orderedUnique(expectedPaths),
+        actualPaths: orderedUnique(actualPaths),
+        missingPaths: orderedUnique(missingPaths),
+        brokenPaths: orderedUnique(brokenPaths),
+        targetPaths,
+        issues,
+    };
+}