@tea-agent/loop-agent 0.17.1 → 0.18.0

package/dist/workflows/dag/backend-test-intake-context.js

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import { access } from "node:fs/promises";
+import path from "node:path";
+const MAX_SOURCE_EXCERPT_CHARS = 2000;
+export const BACKEND_TEST_DISCOVERY_EXCLUDED_DIRECTORIES = [
+    ".git",
+    ".harness",
+    ".env",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "coverage",
+    ".venv",
+    "venv",
+    "__pycache__",
+];
+const DISCOVERY_CANDIDATES = {
+    pytestConfig: ["pytest.ini", "pyproject.toml", "setup.cfg", "tox.ini"],
+    conftest: [
+        "conftest.py",
+        "tests/conftest.py",
+        "test/conftest.py",
+        "testcase/conftest.py",
+    ],
+    testRoot: ["tests", "test", "testcase", "src/tests", "app/tests"],
+    package: [
+        "package.json",
+        "pyproject.toml",
+        "requirements.txt",
+        "requirements-dev.txt",
+        "Pipfile",
+        "poetry.lock",
+    ],
+    serverEntry: [
+        "server.py",
+        "app.py",
+        "main.py",
+        "manage.py",
+        "src/server.py",
+        "src/main.py",
+        "app/main.py",
+        "server.js",
+        "server.ts",
+        "src/server.js",
+        "src/server.ts",
+    ],
+};
+function taskRelative(sources, filePath) {
+    return path.relative(sources.taskDir, filePath).replaceAll(path.sep, "/");
+}
+function repoRelativeReadPath(sources, filePath) {
+    if (!sources.repoRoot) {
+        return filePath.replaceAll(path.sep, "/");
+    }
+    const relative = path.relative(sources.repoRoot, filePath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`backend-test reference escapes repository root: ${filePath}`);
+    }
+    return relative.replaceAll(path.sep, "/");
+}
+function boundedExcerpt(markdown, sourcePath) {
+    const trimmed = markdown.trim();
+    if (trimmed.length <= MAX_SOURCE_EXCERPT_CHARS)
+        return trimmed;
+    const omitted = trimmed.length - MAX_SOURCE_EXCERPT_CHARS;
+    return `${trimmed.slice(0, MAX_SOURCE_EXCERPT_CHARS)}\n\n...[truncated for backend-test intake: showing first ${MAX_SOURCE_EXCERPT_CHARS} of ${trimmed.length} chars; omitted ${omitted} chars]\nFull derived source: ${sourcePath}`;
+}
+function inferRoleHints(referencePath) {
+    const normalized = referencePath.toLowerCase();
+    const hints = [];
+    const add = (hint) => {
+        if (!hints.includes(hint))
+            hints.push(hint);
+    };
+    if (/(acceptance|验收|criteria|ac[._-])/.test(normalized))
+        add("acceptance-criteria");
+    if (/(api|openapi|swagger|endpoint|接口)/.test(normalized))
+        add("api-contract");
+    if (/(schema|model|field|字段|数据)/.test(normalized))
+        add("data-contract");
+    if (/(rule|constraint|policy|规则|约束)/.test(normalized))
+        add("business-rule");
+    if (/(test|pytest|测试)/.test(normalized))
+        add("test-evidence");
+    if (hints.length === 0)
+        add("source-fact");
+    return hints;
+}
+async function discoverCandidatePaths(repoRoot) {
+    const candidates = {
+        pytestConfig: [],
+        conftest: [],
+        testRoot: [],
+        package: [],
+        serverEntry: [],
+    };
+    if (!repoRoot) {
+        return {
+            mode: "deterministic-fallback",
+            candidates,
+            excludedDirectories: [...BACKEND_TEST_DISCOVERY_EXCLUDED_DIRECTORIES],
+        };
+    }
+    for (const [kind, paths] of Object.entries(DISCOVERY_CANDIDATES)) {
+        for (const candidate of paths) {
+            try {
+                await access(path.join(repoRoot, candidate));
+                candidates[kind].push(candidate);
+            }
+            catch {
+                // A missing bounded candidate is not evidence and is omitted.
+            }
+        }
+    }
+    return {
+        mode: "filesystem",
+        candidates,
+        excludedDirectories: [...BACKEND_TEST_DISCOVERY_EXCLUDED_DIRECTORIES],
+    };
+}
+export async function buildBackendTestIntakeContext(sources) {
+    const requirementPath = taskRelative(sources, sources.requirementPath);
+    const constraintPath = taskRelative(sources, sources.constraintPath);
+    const parts = [
+        "## Derived task contract: 需求.md",
+        boundedExcerpt(sources.requirementMarkdown, requirementPath),
+    ];
+    if (sources.constraintMarkdown) {
+        parts.push("## Derived execution constraints: 执行约束.md", boundedExcerpt(sources.constraintMarkdown, constraintPath));
+    }
+    const referenceIndex = (sources.referenceDocuments ?? [])
+        .map((reference) => {
+        const relativePath = taskRelative(sources, reference.path);
+        return {
+            path: relativePath,
+            readPath: repoRelativeReadPath(sources, reference.path),
+            sha256: createHash("sha256").update(reference.markdown, "utf8").digest("hex"),
+            roleHints: inferRoleHints(relativePath),
+        };
+    })
+        .sort((left, right) => left.path.localeCompare(right.path));
+    return {
+        boundedSourceContext: parts.join("\n\n"),
+        referenceIndex,
+        projectDiscoverySeed: await discoverCandidatePaths(sources.repoRoot),
+    };
+}

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

@@ -0,0 +1,528 @@
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+const CASE_ID = /\bBE-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}\b/g;
+const AC_ID = /\bAC-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/g;
+const SECRET = /(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|authorization)\s*[:=]\s*\S+/i;
+const PLACEHOLDER = /\b(?:TODO|TBD|FIXME)\b|后续补充|暂不实现|接口正常|结果正确|按实际情况处理/i;
+const REQUIRED_CASE_SECTIONS = [
+    "Acceptance Criteria",
+    "Source References",
+    "Preconditions",
+    "Steps",
+    "Expected Results",
+    "Automation Notes",
+];
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function existingPaths(root, candidates) {
+    const found = [];
+    for (const candidate of candidates) {
+        if (await exists(path.join(root, candidate)))
+            found.push(candidate);
+    }
+    return found;
+}
+function unique(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+export function requiredBackendMarkdownCaseAcIds(criteria) {
+    const downstreamEvidence = /(?:pytest|junit|html|stdout|stderr|traceability|追溯|一一映射|一一追溯|执行并产生|执行结果|测试报告|失败分类|证据)/i;
+    return unique([...criteria]
+        .filter((criterion) => !downstreamEvidence.test(criterion))
+        .flatMap((criterion) => criterion.match(/\bAC-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/g) ?? []));
+}
+function extractFixtures(markdown) {
+    return unique([
+        ...markdown.matchAll(/(?:@pytest\.fixture(?:\([^)]*\))?\s*(?:\r?\n)+\s*def\s+|def\s+)([A-Za-z_][A-Za-z0-9_]*)\s*\(/g),
+    ]
+        .map((match) => match[1])
+        .filter(Boolean));
+}
+export async function inspectBackendTestEnvironment(input) {
+    const pytestConfigs = await existingPaths(input.workspaceRoot, [
+        "pytest.ini",
+        "pyproject.toml",
+        "setup.cfg",
+        "tox.ini",
+    ]);
+    const testRoots = await existingPaths(input.workspaceRoot, [
+        "testcase",
+        "tests",
+        "test",
+        "src/tests",
+        "app/tests",
+    ]);
+    const conftestFiles = await existingPaths(input.workspaceRoot, [
+        "conftest.py",
+        "testcase/conftest.py",
+        "tests/conftest.py",
+        "test/conftest.py",
+    ]);
+    const serverEntries = await existingPaths(input.workspaceRoot, [
+        "server.py",
+        "app.py",
+        "main.py",
+        "manage.py",
+        "src/server.py",
+        "src/main.py",
+        "app/main.py",
+        "server.js",
+        "server.ts",
+        "src/server.js",
+        "src/server.ts",
+    ]);
+    const fixtures = [];
+    for (const relativePath of conftestFiles) {
+        const content = await readFile(path.join(input.workspaceRoot, relativePath), "utf8");
+        if (SECRET.test(content)) {
+            // Do not copy conftest content into evidence. Fixture names are still safe to discover.
+        }
+        fixtures.push(...extractFixtures(content));
+    }
+    const htmlRenderer = /--html\b/.test(input.pytestHelp)
+        ? "pytest-html --self-contained-html"
+        : "loop-agent built-in JUnit-to-HTML";
+    const warnings = [
+        ...(pytestConfigs.length === 0
+            ? ["No explicit pytest configuration file was found."]
+            : []),
+        ...(conftestFiles.length === 0
+            ? ["No bounded conftest.py candidate was found."]
+            : []),
+        ...(serverEntries.length === 0
+            ? [
+                "No bounded server entry candidate was found; Markdown cases must document an external or library target explicitly.",
+            ]
+            : []),
+    ];
+    const lines = [
+        "# Backend Test Environment",
+        "",
+        "## Status",
+        "",
+        "PASS",
+        "",
+        "## Runtime",
+        "",
+        `- Python: ${input.pythonVersion.trim()}`,
+        `- Pytest: ${input.pytestVersion.trim()}`,
+        "- Shell environment: clean",
+        "",
+        "## Project Discovery",
+        "",
+        `- Pytest config: ${pytestConfigs.join(", ") || "not found"}`,
+        `- Existing test roots: ${testRoots.join(", ") || "not found (testcase will be generated)"}`,
+        `- Conftest files: ${conftestFiles.join(", ") || "not found"}`,
+        `- Server entry candidates: ${serverEntries.join(", ") || "not found"}`,
+        `- Fixtures: ${unique(fixtures).join(", ") || "none discovered"}`,
+        "",
+        "## HTML Report",
+        "",
+        `- Selected renderer: ${htmlRenderer}`,
+        "",
+        "## Bounded Discovery Policy",
+        "",
+        "- No .env value, credential file, dependency tree, build output, coverage output, or runtime directory was inspected.",
+        "- External readiness must be represented by an explicitly configured verify command or a documented safe health endpoint; secret values are never printed.",
+        "",
+        "## Warnings",
+        "",
+        ...(warnings.length > 0
+            ? warnings.map((warning) => `- ${warning}`)
+            : ["- None"]),
+    ];
+    return {
+        markdown: `${lines.join("\n")}\n`,
+        fixtures: unique(fixtures),
+        pytestConfigs,
+        testRoots,
+        conftestFiles,
+        serverEntries,
+    };
+}
+async function markdownFiles(root) {
+    const directory = path.join(root, "testcase", "md");
+    const entries = await readdir(directory, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"))
+        .map((entry) => path.join(directory, entry.name))
+        .sort();
+}
+function splitCases(markdown) {
+    const headings = [
+        ...markdown.matchAll(/^##\s+(BE-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3})\b.*$/gm),
+    ];
+    return headings.map((match, index) => ({
+        id: match[1],
+        body: markdown.slice(match.index, headings[index + 1]?.index ?? markdown.length),
+    }));
+}
+function sectionBody(body, heading) {
+    const marker = new RegExp(`^###\\s+${heading}\\s*$`, "mi");
+    const match = marker.exec(body);
+    if (!match)
+        return "";
+    const remainder = body.slice(match.index + match[0].length);
+    const next = /^###\s+/m.exec(remainder);
+    return remainder.slice(0, next?.index ?? remainder.length);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isTaskRelativeSourcePath(value) {
+    return /^source\/(?:需求\.md|执行约束\.md|references\/[^\s`'"()[\]{}（）。，；：#]+)$/.test(value);
+}
+function extractLegacySourceReferences(sourceSection) {
+    const inlineCode = [
+        ...sourceSection.matchAll(/`(source\/(?:需求\.md|执行约束\.md|references\/[^`\r\n]+))`/g),
+    ].map((match) => match[1].trim());
+    const plain = [
+        ...sourceSection.matchAll(/(?:^|[\s('"（])(source\/(?:需求\.md|执行约束\.md|references\/[^\s`'"()[\]{}（）。，；：#]+))(?=$|[\s`'"()（）\]，。；：#])/gm),
+    ].map((match) => match[1]);
+    return unique([...inlineCode, ...plain].filter(isTaskRelativeSourcePath));
+}
+function extractSourceReferences(input) {
+    const citedPaths = extractLegacySourceReferences(input.sourceSection);
+    if (!input.sourceBinding) {
+        return citedPaths;
+    }
+    const boundMatches = input.sourceBinding.sources
+        .map((source) => source.path)
+        .filter(isTaskRelativeSourcePath)
+        .filter((sourcePath) => {
+        const escaped = escapeRegExp(sourcePath);
+        return new RegExp(`(?:^|[\\s(\`'\"（])${escaped}(?=$|[\\s)\`'\"）\\]，。；：#])`, "m").test(input.sourceSection);
+    });
+    // Preserve explicitly cited unknown paths so resolveBoundSourceReference()
+    // rejects them instead of silently accepting a nearby bound prefix.
+    return unique([...boundMatches, ...citedPaths]);
+}
+function hasNumberedListItem(value) {
+    return /^\s*\d+[.)]\s+\S+/m.test(value);
+}
+function hasAssertableExpectedResult(value) {
+    return /^\s*(?:\d+[.)]|[-*+])\s+\S+/m.test(value);
+}
+function resolveBoundSourceReference(input) {
+    if (!input.sourceBinding) {
+        return path.join(input.workspaceRoot, input.sourceRef);
+    }
+    const member = input.sourceBinding.sources.find((source) => source.path === input.sourceRef);
+    if (!member) {
+        throw new Error(`source reference is not present in DAG sourceBinding: ${input.sourceRef}`);
+    }
+    const taskRoot = path.join(input.workspaceRoot, ".harness", "tasks", input.sourceBinding.taskId);
+    const resolved = path.resolve(taskRoot, member.path);
+    const relative = path.relative(taskRoot, resolved);
+    if (relative.startsWith("..") ||
+        path.isAbsolute(relative)) {
+        throw new Error(`unsafe task-relative source path: ${input.sourceRef}`);
+    }
+    return resolved;
+}
+function leadingWhitespace(value) {
+    return value.match(/^\s*/)?.[0].length ?? 0;
+}
+function isCleanupStatement(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return true;
+    if (/^(?:with|if)\b/.test(trimmed))
+        return false;
+    if (/\b(?:assert|pytest\.fail|raise)\b/.test(trimmed))
+        return false;
+    return /(?:^|[._])(?:cleanup|clean_up|teardown|delete|remove|close|release|rollback|disconnect|dispose|unlink)(?:[_(.]|$)/i.test(trimmed);
+}
+function findUnsafeSwallowedException(source) {
+    const lines = source.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const exceptMatch = lines[index].match(/^(\s*)except(?:\s+([^:]+))?\s*:\s*(?:(pass)\s*)?(?:#.*)?$/);
+        if (!exceptMatch)
+            continue;
+        const indent = exceptMatch[1].length;
+        const inlinePass = exceptMatch[3] === "pass";
+        let handlerIndex = index + 1;
+        while (!inlinePass &&
+            handlerIndex < lines.length &&
+            (!lines[handlerIndex].trim() || lines[handlerIndex].trim().startsWith("#"))) {
+            handlerIndex += 1;
+        }
+        if (!inlinePass &&
+            (handlerIndex >= lines.length ||
+                leadingWhitespace(lines[handlerIndex]) <= indent ||
+                lines[handlerIndex].trim() !== "pass")) {
+            continue;
+        }
+        const exceptionType = exceptMatch[2]?.trim() || "bare except";
+        if (exceptionType !== "requests.RequestException") {
+            return exceptionType;
+        }
+        let tryIndex = index - 1;
+        while (tryIndex >= 0) {
+            const candidate = lines[tryIndex];
+            if (!candidate.trim() || candidate.trim().startsWith("#")) {
+                tryIndex -= 1;
+                continue;
+            }
+            if (leadingWhitespace(candidate) === indent &&
+                candidate.trim() === "try:") {
+                break;
+            }
+            if (leadingWhitespace(candidate) <= indent)
+                break;
+            tryIndex -= 1;
+        }
+        if (tryIndex < 0 || lines[tryIndex].trim() !== "try:") {
+            return exceptionType;
+        }
+        const tryBody = lines.slice(tryIndex + 1, index);
+        const executable = tryBody.filter((line) => line.trim() && !line.trim().startsWith("#"));
+        if (executable.length === 0 ||
+            executable.some((line) => leadingWhitespace(line) <= indent || !isCleanupStatement(line))) {
+            return exceptionType;
+        }
+    }
+    return null;
+}
+export async function validateBackendMarkdownCases(input) {
+    const files = await markdownFiles(input.workspaceRoot);
+    const readme = path.join(input.workspaceRoot, "testcase", "md", "README.md");
+    if (!(await exists(readme)))
+        throw new Error("missing testcase/md/README.md");
+    const moduleFiles = files.filter((file) => path.basename(file).toLowerCase() !== "readme.md");
+    if (moduleFiles.length === 0)
+        throw new Error("no testcase/md module case file found");
+    const seen = new Map();
+    const coveredAc = new Set();
+    let caseCount = 0;
+    for (const file of moduleFiles) {
+        const markdown = await readFile(file, "utf8");
+        if (!markdown.trim())
+            throw new Error(`empty Markdown case file: ${path.relative(input.workspaceRoot, file)}`);
+        if (SECRET.test(markdown))
+            throw new Error(`secret-shaped content in ${path.relative(input.workspaceRoot, file)}`);
+        if (PLACEHOLDER.test(markdown))
+            throw new Error(`placeholder or non-assertable wording in ${path.relative(input.workspaceRoot, file)}`);
+        const cases = splitCases(markdown);
+        if (cases.length === 0)
+            throw new Error(`no BE-<MODULE>-<NNN> case heading in ${path.relative(input.workspaceRoot, file)}`);
+        for (const testCase of cases) {
+            caseCount += 1;
+            const previous = seen.get(testCase.id);
+            if (previous)
+                throw new Error(`duplicate case id ${testCase.id}: ${previous} and ${path.relative(input.workspaceRoot, file)}`);
+            seen.set(testCase.id, path.relative(input.workspaceRoot, file).replaceAll(path.sep, "/"));
+            for (const section of REQUIRED_CASE_SECTIONS) {
+                if (!new RegExp(`^###\\s+${section}\\s*$`, "mi").test(testCase.body)) {
+                    throw new Error(`${testCase.id} missing section: ${section}`);
+                }
+            }
+            const acIds = unique(testCase.body.match(AC_ID) ?? []);
+            if (acIds.length === 0)
+                throw new Error(`${testCase.id} has no AC-* reference`);
+            acIds.forEach((id) => coveredAc.add(id));
+            const sourceSection = sectionBody(testCase.body, "Source References");
+            const sourceRefs = extractSourceReferences({
+                sourceSection,
+                sourceBinding: input.sourceBinding,
+            });
+            if (sourceRefs.length === 0) {
+                throw new Error(`${testCase.id} has no task-relative source reference`);
+            }
+            for (const sourceRef of sourceRefs) {
+                if (/\.env(?:\.|$)|credential|secret/i.test(sourceRef)) {
+                    throw new Error(`${testCase.id} references a forbidden source path: ${sourceRef}`);
+                }
+                const resolvedSourcePath = resolveBoundSourceReference({
+                    workspaceRoot: input.workspaceRoot,
+                    sourceRef,
+                    sourceBinding: input.sourceBinding,
+                });
+                if (!(await exists(resolvedSourcePath))) {
+                    throw new Error(`${testCase.id} references a missing source path: ${sourceRef}`);
+                }
+            }
+            const steps = sectionBody(testCase.body, "Steps");
+            const expected = sectionBody(testCase.body, "Expected Results");
+            if (!hasNumberedListItem(steps))
+                throw new Error(`${testCase.id} has no numbered executable step`);
+            if (!hasAssertableExpectedResult(expected))
+                throw new Error(`${testCase.id} has no structured expected result`);
+        }
+    }
+    const missing = input.requiredRequirementIds.filter((id) => !coveredAc.has(id));
+    if (missing.length > 0)
+        throw new Error(`required AC IDs are not covered by final Markdown cases: ${missing.join(", ")}`);
+    const report = [
+        "# Backend Markdown Case Validation",
+        "",
+        "## Status",
+        "",
+        "PASS",
+        "",
+        `- Markdown files: ${files.length}`,
+        `- Module files: ${moduleFiles.length}`,
+        `- Cases: ${caseCount}`,
+        `- Covered AC IDs: ${[...coveredAc].sort().join(", ") || "none"}`,
+        `- Environment evidence present: ${input.environmentMarkdown.trim() ? "yes" : "no"}`,
+        "- Duplicate case IDs: 0",
+        "- Secret-shaped findings: 0",
+    ];
+    return `${report.join("\n")}\n`;
+}
+export async function validateBackendMarkdownTraceability(workspaceRoot) {
+    const files = await markdownFiles(workspaceRoot);
+    const markdownIds = new Set();
+    for (const file of files) {
+        const content = await readFile(file, "utf8");
+        for (const id of content.match(CASE_ID) ?? [])
+            markdownIds.add(id);
+    }
+    const testcaseRoot = path.join(workspaceRoot, "testcase");
+    const pythonFiles = [];
+    async function walk(directory) {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const absolute = path.join(directory, entry.name);
+            if (entry.isDirectory())
+                await walk(absolute);
+            else if (/^test_.*\.py$/i.test(entry.name))
+                pythonFiles.push(absolute);
+        }
+    }
+    await walk(testcaseRoot);
+    const symbols = new Map();
+    for (const file of pythonFiles) {
+        const content = await readFile(file, "utf8");
+        if (/pytest\.(?:skip|xfail)\s*\(|@pytest\.mark\.(?:skip|xfail)\b/.test(content)) {
+            throw new Error(`skip/xfail is forbidden in generated backend pytest: ${path.relative(workspaceRoot, file)}`);
+        }
+        const unsafeSwallowedException = findUnsafeSwallowedException(content);
+        if (unsafeSwallowedException) {
+            throw new Error(`swallowed exception is forbidden in generated backend pytest: ${path.relative(workspaceRoot, file)} (${unsafeSwallowedException})`);
+        }
+        for (const match of content.matchAll(/^(?:async\s+)?def\s+(test_[A-Za-z0-9_]+)\s*\([^)]*\)\s*(?:->\s*[^:\r\n]+)?\s*:/gm)) {
+            const symbol = match[1];
+            const matchingMarkdownIds = [...markdownIds].filter((caseId) => {
+                const prefix = `test_${caseId.replaceAll("-", "_")}`;
+                return symbol === prefix || symbol.startsWith(`${prefix}_`);
+            });
+            if (matchingMarkdownIds.length > 1) {
+                throw new Error(`pytest symbol matches multiple Markdown Case IDs: ${symbol} -> ${matchingMarkdownIds.join(",")}`);
+            }
+            const fallback = symbol.match(/^test_(BE(?:_[A-Z0-9]+)+?_\d{3})(?:_|$)/i);
+            const id = matchingMarkdownIds[0] ??
+                (fallback
+                    ? fallback[1].replaceAll("_", "-").toUpperCase()
+                    : undefined);
+            if (!id)
+                continue;
+            const bucket = symbols.get(id) ?? [];
+            bucket.push(`${path.relative(workspaceRoot, file).replaceAll(path.sep, "/")}#${symbol}`);
+            symbols.set(id, bucket);
+            const tail = content.slice(match.index + match[0].length, match.index + match[0].length + 500);
+            if (!new RegExp(`^[\\s\\r\\n]*(?:[rRuUfF]{0,2})?[\"']{3}[^\n]*${id}`, "m").test(tail)) {
+                throw new Error(`${id} pytest symbol is missing a matching first-line docstring: ${bucket.at(-1)}`);
+            }
+        }
+    }
+    const missing = [...markdownIds].filter((id) => !symbols.has(id));
+    const duplicates = [...symbols]
+        .filter(([, refs]) => refs.length !== 1)
+        .map(([id]) => id);
+    const extra = [...symbols.keys()].filter((id) => !markdownIds.has(id));
+    if (missing.length || duplicates.length || extra.length) {
+        throw new Error(`traceability mismatch: missing=${missing.join(",") || "none"}; duplicates=${duplicates.join(",") || "none"}; extra=${extra.join(",") || "none"}`);
+    }
+    return ([
+        "# Backend Test Traceability",
+        "",
+        "## Status",
+        "",
+        "PASS",
+        "",
+        `- Markdown Case IDs: ${markdownIds.size}`,
+        `- Pytest symbols: ${symbols.size}`,
+        `- Matched symbols: ${symbols.size}`,
+        "- Missing mappings: 0",
+        "- Extra symbols: 0",
+        "- Duplicate symbols: 0",
+        "- skip/xfail findings: 0",
+    ].join("\n") + "\n");
+}
+export function redactBackendTestOutput(value) {
+    return value
+        .replace(/((?:password|passwd|secret|token|api[_-]?key|authorization)\s*[:=]\s*)\S+/gi, "$1[REDACTED]")
+        .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]");
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+export function renderBackendTestHtml(input) {
+    const passRate = input.parsed.tests > 0 ? input.parsed.passed / input.parsed.tests : 0;
+    const failures = input.parsed.failures.length
+        ? input.parsed.failures
+            .map((failure) => `<tr><td>${escapeHtml(failure.name)}</td><td>${escapeHtml(failure.kind)}</td><td><pre>${escapeHtml(failure.message)}</pre></td></tr>`)
+            .join("")
+        : '<tr><td colspan="3">No failures</td></tr>';
+    return `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><title>${escapeHtml(input.title)}</title><style>body{font-family:system-ui,"Microsoft YaHei",sans-serif;margin:2rem;color:#172033}h1,h2{color:#17365d}.cards{display:grid;grid-template-columns:repeat(3,minmax(8rem,1fr));gap:.75rem}.card{padding:1rem;border:1px solid #ccd6e0;border-radius:.5rem;background:#f7f9fc}.bad{color:#b42318}table{width:100%;border-collapse:collapse}th,td{border:1px solid #ccd6e0;padding:.55rem;text-align:left;vertical-align:top}pre{white-space:pre-wrap;max-height:18rem;overflow:auto}</style></head><body><h1>${escapeHtml(input.title)}</h1><div class="cards"><div class="card">Total<br><strong>${input.parsed.tests}</strong></div><div class="card">Passed<br><strong>${input.parsed.passed}</strong></div><div class="card bad">Failed/Error<br><strong>${input.parsed.failed + input.parsed.errors}</strong></div><div class="card">Skipped<br><strong>${input.parsed.skipped}</strong></div><div class="card">Pass rate<br><strong>${(passRate * 100).toFixed(2)}%</strong></div><div class="card">Duration<br><strong>${input.parsed.durationMs ?? "unavailable"} ms</strong></div></div><h2>Environment</h2><pre>${escapeHtml(input.environmentSummary.slice(0, 4000))}</pre><h2>Traceability</h2><pre>${escapeHtml(input.traceabilitySummary.slice(0, 4000))}</pre><h2>Failures</h2><table><thead><tr><th>Test</th><th>Kind</th><th>Summary</th></tr></thead><tbody>${failures}</tbody></table></body></html>`;
+}
+export function renderBackendTestFacts(input) {
+    const passRate = input.parsed.tests > 0 ? input.parsed.passed / input.parsed.tests : 0;
+    return ([
+        "# Backend Test Execution Facts",
+        "",
+        "## Execution",
+        "",
+        `- Status: ${input.pytestExitCode === 0 ? "passed" : "completed-with-failures"}`,
+        `- Pytest exit code: ${input.pytestExitCode}`,
+        `- Duration: ${input.parsed.durationMs ?? "unavailable"} ms`,
+        "- JUnit valid: yes",
+        "- HTML valid: yes",
+        "",
+        "## Counts",
+        "",
+        `- Total: ${input.parsed.tests}`,
+        `- Passed: ${input.parsed.passed}`,
+        `- Failed: ${input.parsed.failed}`,
+        `- Errors: ${input.parsed.errors}`,
+        `- Skipped: ${input.parsed.skipped}`,
+        `- Pass rate: ${(passRate * 100).toFixed(2)}%`,
+        "",
+        "## Evidence",
+        "",
+        `- JUnit: ${input.junitRelativePath}`,
+        `- JUnit SHA-256: ${createHash("sha256").update(input.junitContent).digest("hex")}`,
+        `- HTML: ${input.htmlRelativePath}`,
+        `- HTML SHA-256: ${createHash("sha256").update(input.htmlContent).digest("hex")}`,
+        "",
+        "## Failed Tests",
+        "",
+        ...(input.parsed.failures.length > 0
+            ? input.parsed.failures.map((failure) => `- ${failure.name} [${failure.kind}]: ${failure.message}`)
+            : ["- None"]),
+        "",
+        "## Maturity Evidence",
+        "",
+        "- Code coverage: unavailable unless a separate validated coverage artifact exists.",
+        "- Stability: unavailable unless at least five independent runs are recorded.",
+    ].join("\n") + "\n");
+}
+export async function writeRunReport(runDir, fileName, content) {
+    const reportsDir = path.join(runDir, "reports");
+    await mkdir(reportsDir, { recursive: true });
+    const absolute = path.join(reportsDir, fileName);
+    await writeFile(absolute, content, "utf8");
+    return absolute;
+}