@tea-agent/loop-agent 0.38.1 → 0.38.3

package/dist/workflows/dag/backend-test-case-manifest.js

@@ -149,6 +149,10 @@ export const backendTestCaseManifestSchema = z
         crossCuttingTestPointCount: z.number().int().min(0),
         unclassifiedTestPointCount: z.number().int().min(0),
         duplicateBindingTestPointCount: z.number().int().min(0),
+        payloadSafeCount: z.number().int().min(0),
+        payloadUnsafeCount: z.number().int().min(0),
+        payloadUnavailableCount: z.number().int().min(0),
+        duplicateExecutionSignatureCount: z.number().int().min(0),
     }).strict().optional(),
     artifactRefs: z.object({
         caseCoverageFacts: z.object({ path: z.string().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/).optional() }).strict(),

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

@@ -369,8 +369,13 @@ function seedLocalServerFixture(fixtures, managedStart) {
         },
     ];
 }
-/** Drop empty managedCommand strings; omit block when not managed-command. */
-export function sanitizeBackendTestExecutionInput(value) {
+/**
+ * Drop empty managedCommand strings; omit block when not managed-command.
+ * With a configured backendTest layout, `allowedTestRoot` keeps the configured
+ * automation root stable instead of remapping every scout-chosen root to the
+ * frozen historical default.
+ */
+export function sanitizeBackendTestExecutionInput(value, options = {}) {
     const record = asRecord(value);
     if (!record)
         return value;
@@ -404,17 +409,17 @@ export function sanitizeBackendTestExecutionInput(value) {
             normalizedRoot.includes("..") ||
             normalizedRoot.includes("\\") ||
             /^[A-Za-z]:/.test(normalizedRoot);
-        if (!looksUnsafe &&
-            normalizedRoot !== BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT) {
+        const frozenRoot = options.allowedTestRoot ?? BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT;
+        if (!looksUnsafe && normalizedRoot !== frozenRoot) {
             const gaps = Array.isArray(next.evidenceGaps)
                 ? [...next.evidenceGaps]
                 : [];
             gaps.push({
-                description: `scout testRoot=${normalizedRoot} remapped to frozen adapter root ${BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT}`,
+                description: `scout testRoot=${normalizedRoot} remapped to frozen adapter root ${frozenRoot}`,
                 sourceRef: "adapter:backend-test-execution",
             });
             next.evidenceGaps = gaps;
-            next.testRoot = BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT;
+            next.testRoot = frozenRoot;
         }
     }
     // Local node/npm managed-command is not hosted by the clean-env pytest shell.
@@ -455,8 +460,8 @@ export function sanitizeBackendTestExecutionInput(value) {
     }
     return next;
 }
-export function coerceBackendTestExecutionInput(value) {
-    const sanitized = sanitizeBackendTestExecutionInput(value);
+export function coerceBackendTestExecutionInput(value, options = {}) {
+    const sanitized = sanitizeBackendTestExecutionInput(value, options);
     const direct = backendTestExecutionContractSchema.safeParse(sanitized);
     if (direct.success)
         return direct.data;
@@ -626,7 +631,11 @@ export async function materializeBackendTestExecutionContract(input) {
     catch (error) {
         throw new Error(`invalid-output: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const candidates = [coerceBackendTestExecutionInput(parsed)];
+    const candidates = [
+        coerceBackendTestExecutionInput(parsed, {
+            allowedTestRoot: input.allowedTestRoot,
+        }),
+    ];
     let accepted = null;
     let lastSchemaError = "invalid execution contract";
     let lastSecretError = "";

package/dist/workflows/dag/backend-test-gap-fill.js

@@ -0,0 +1,205 @@
+import { z } from "zod";
+import { createHash } from "node:crypto";
+/**
+ * Plan D: deterministic gap-fill planning for backend-test.
+ *
+ * A `backend-test-gap-v1` document lists missing scenario slots/cases for an
+ * already-executed backend-test task. The deterministic ingest unions the
+ * document rows with the previous N6 coverage facts `missingSlots` and emits
+ * a `backend-test-gap-plan-v1.json` work order. Writers only patch the
+ * planned files; Case IDs are never renumbered and a second run over an
+ * already-satisfied plan returns alreadyPresent without touching assets.
+ */
+export const BACKEND_TEST_GAP_DOC_SCHEMA_ID = "backend-test-gap-v1";
+export const BACKEND_TEST_GAP_PLAN_SCHEMA_ID = "backend-test-gap-plan-v1";
+const SLOT_ID = /^(?:TP-SP-[A-Z0-9._-]+|TP-[A-Z0-9._-]+)$/;
+const CASE_ID = /^BE-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}$/;
+export const backendTestGapDocSchema = z
+    .object({
+    schemaId: z.literal(BACKEND_TEST_GAP_DOC_SCHEMA_ID),
+    /** Must equal the original backend-test taskId. */
+    taskId: z.string().min(1),
+    /** sha256 of the original requirement document (identity check). */
+    requirementSha256: z.string().regex(/^[0-9a-f]{64}$/),
+    missingSlots: z
+        .array(z.object({
+        slotId: z.string().regex(SLOT_ID),
+        /** Markdown module stem that owns (or should own) the slot. */
+        moduleStem: z.string().min(1),
+        reason: z.string().min(1),
+        /** Optional: the Case to extend with the variant. */
+        caseId: z.string().regex(CASE_ID).optional(),
+    }))
+        .default([]),
+})
+    .strict();
+export const backendTestGapPlanSchema = z
+    .object({
+    schemaId: z.literal(BACKEND_TEST_GAP_PLAN_SCHEMA_ID),
+    taskId: z.string().min(1),
+    requirementSha256: z.string().regex(/^[0-9a-f]{64}$/),
+    status: z.enum(["planned", "already-satisfied", "error"]),
+    /** Module stems that need a Markdown/pytest patch. */
+    targetModules: z.array(z.string().min(1)),
+    /** Slot IDs to add (doc ∪ facts minus already-covered). */
+    newTestPoints: z.array(z.string()),
+    /** Shared setup refs already used by target modules (plan B). */
+    reuseSetupRefs: z.array(z.string()),
+    /** Doc rows conflicting with bound evidence; never written. */
+    conflicts: z.array(z.string()),
+    /** Doc rows whose slots are already covered; no file changes. */
+    alreadyPresent: z.array(z.string()),
+    /** Exact files writers may touch (README + module md + module py). */
+    targetPaths: z.array(z.string()),
+    issues: z.array(z.string()),
+})
+    .strict();
+function modulePaths(layout, stem) {
+    return [
+        `${layout.markdownDir}/${stem}.md`,
+        `${layout.scriptDir}/test_${stem}.py`,
+    ];
+}
+/**
+ * Deterministic ingest. Fail-closed rules:
+ * - taskId/requirement hash mismatch → status=error, no targetPaths.
+ * - slot referencing a module stem absent from the existing module index →
+ *   conflict (gap-fill never adds new Module Index modules).
+ * - slot already covered per previous facts → alreadyPresent, not planned.
+ */
+export function ingestBackendTestGap(input) {
+    const issues = [];
+    if (input.gapDoc.taskId !== input.taskId) {
+        return {
+            schemaId: BACKEND_TEST_GAP_PLAN_SCHEMA_ID,
+            taskId: input.taskId,
+            requirementSha256: input.requirementSha256,
+            status: "error",
+            targetModules: [],
+            newTestPoints: [],
+            reuseSetupRefs: [],
+            conflicts: [
+                `gap-doc taskId ${input.gapDoc.taskId} does not match task ${input.taskId}`,
+            ],
+            alreadyPresent: [],
+            targetPaths: [],
+            issues: ["identity mismatch: refusing to plan any writer work"],
+        };
+    }
+    if (input.gapDoc.requirementSha256 !== input.requirementSha256) {
+        return {
+            schemaId: BACKEND_TEST_GAP_PLAN_SCHEMA_ID,
+            taskId: input.taskId,
+            requirementSha256: input.requirementSha256,
+            status: "error",
+            targetModules: [],
+            newTestPoints: [],
+            reuseSetupRefs: [],
+            conflicts: [
+                "gap-doc requirementSha256 does not match the task requirement",
+            ],
+            alreadyPresent: [],
+            targetPaths: [],
+            issues: ["identity mismatch: refusing to plan any writer work"],
+        };
+    }
+    const covered = new Set(input.previousCoveredSlots ?? []);
+    const existing = new Set(input.existingModuleStems);
+    const docUnion = new Map();
+    const conflicts = [];
+    const alreadyPresent = [];
+    for (const row of input.gapDoc.missingSlots) {
+        if (covered.has(row.slotId)) {
+            alreadyPresent.push(row.slotId);
+            continue;
+        }
+        if (!existing.has(row.moduleStem)) {
+            conflicts.push(`${row.slotId}: module stem ${row.moduleStem} is not in the existing Module Index; gap-fill never adds new modules (run full mode for new business domains)`);
+            continue;
+        }
+        docUnion.set(row.slotId, {
+            moduleStem: row.moduleStem,
+            caseId: row.caseId,
+            source: "doc",
+        });
+    }
+    // facts-derived missing slots: attach to the partition's module when the
+    // slot token maps to an existing module stem heuristically; unknown owner
+    // stays a conflict rather than a guess.
+    for (const slotId of input.previousMissingSlots ?? []) {
+        if (docUnion.has(slotId) || covered.has(slotId))
+            continue;
+        const owner = inferSlotOwnerModule(slotId, existing);
+        if (!owner) {
+            conflicts.push(`${slotId}: previous facts report the slot missing but no existing module owns it; add the module stem to the gap doc`);
+            continue;
+        }
+        docUnion.set(slotId, { moduleStem: owner, source: "facts" });
+    }
+    const planned = [...docUnion.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const targetModules = [...new Set(planned.map(([, v]) => v.moduleStem))].sort();
+    const targetPaths = targetModules.length
+        ? [
+            input.layout.readmePath,
+            ...targetModules.flatMap((stem) => modulePaths(input.layout, stem)),
+        ]
+        : [];
+    return {
+        schemaId: BACKEND_TEST_GAP_PLAN_SCHEMA_ID,
+        taskId: input.taskId,
+        requirementSha256: input.requirementSha256,
+        status: planned.length === 0 ? "already-satisfied" : "planned",
+        targetModules,
+        newTestPoints: planned.map(([slotId]) => slotId),
+        reuseSetupRefs: input.sharedSetupPath ? [input.sharedSetupPath] : [],
+        conflicts,
+        alreadyPresent: [...new Set(alreadyPresent)].sort(),
+        targetPaths,
+        issues,
+    };
+}
+/**
+ * Map a TP-SP-<OPERATION>-<AXIS>-... slot to an existing module stem. The
+ * heuristic is intentionally conservative: an exact stem match of the
+ * operation token against existing stems (e.g. slot TP-SP-RESOURCES-TYPE-X
+ * with stem "resources"). No match → null (conflict, not a guess).
+ */
+const HTTP_METHOD_TOKENS = new Set([
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "head",
+    "options",
+]);
+export function inferSlotOwnerModule(slotId, existingStems) {
+    const match = /^TP-SP-([A-Z0-9-]+)-[A-Z0-9-]+$/.exec(slotId);
+    if (!match)
+        return null;
+    const tokens = match[1].split("-");
+    const starts = [0];
+    if (tokens[0] && HTTP_METHOD_TOKENS.has(tokens[0].toLowerCase())) {
+        starts.push(1);
+        if (tokens[1]?.toLowerCase() === "api")
+            starts.push(2);
+    }
+    else if (tokens[0]?.toLowerCase() === "api") {
+        starts.push(1);
+    }
+    // Prefer the LONGEST remaining prefix that matches an existing stem so
+    // "resource-notes" wins over a prefix-only accident.
+    for (const start of starts) {
+        for (let cut = tokens.length; cut > start; cut--) {
+            const candidate = tokens.slice(start, cut).join("-").toLowerCase();
+            for (const stem of existingStems) {
+                if (stem.toLowerCase().replace(/_/g, "-") === candidate)
+                    return stem;
+            }
+        }
+    }
+    return null;
+}
+export function hashRequirement(markdown) {
+    return createHash("sha256").update(markdown, "utf8").digest("hex");
+}

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

@@ -47,6 +47,33 @@ const DISCOVERY_CANDIDATES = {
         "src/server.ts",
     ],
 };
+/**
+ * Resolve the single authoritative user shared-setup document.
+ * `backendTest.sharedSetupDoc` (task-relative, e.g. "source/shared-setup.md")
+ * wins when present; otherwise exactly one reference whose roleHints include
+ * `shared-setup` may bind. Multiple shared-setup references are fail-closed:
+ * the caller must pin one document explicitly.
+ */
+export function resolveBackendTestSharedSetup(sources, referenceIndex, options = {}) {
+    const explicit = options.sharedSetupDoc?.trim();
+    if (explicit) {
+        const normalized = explicit.replaceAll("\\", "/");
+        const hit = referenceIndex.find((entry) => entry.path === normalized);
+        if (!hit) {
+            throw new Error(`backendTest.sharedSetupDoc "${explicit}" is not a bound reference document`);
+        }
+        return { path: hit.path, readPath: hit.readPath, sha256: hit.sha256 };
+    }
+    const hinted = referenceIndex.filter((entry) => entry.roleHints.includes("shared-setup"));
+    if (hinted.length > 1) {
+        throw new Error(`multiple shared-setup reference documents bound (${hinted
+            .map((entry) => entry.path)
+            .join(", ")}); pin one via backendTest.sharedSetupDoc`);
+    }
+    return hinted[0]
+        ? { path: hinted[0].path, readPath: hinted[0].readPath, sha256: hinted[0].sha256 }
+        : null;
+}
 function taskRelative(sources, filePath) {
     return path.relative(sources.taskDir, filePath).replaceAll(path.sep, "/");
 }
@@ -81,6 +108,8 @@ function inferRoleHints(referencePath) {
         add("business-rule");
     if (/(test|pytest|测试)/.test(normalized))
         add("test-evidence");
+    if (/(公共前置|shared[-_. ]?setup|前置操作)/.test(normalized))
+        add("shared-setup");
     if (hints.length === 0)
         add("source-fact");
     return hints;
@@ -142,5 +171,8 @@ export async function buildBackendTestIntakeContext(sources) {
         boundedSourceContext: parts.join("\n\n"),
         referenceIndex,
         projectDiscoverySeed: await discoverCandidatePaths(sources.repoRoot),
+        sharedSetup: resolveBackendTestSharedSetup(sources, referenceIndex, {
+            sharedSetupDoc: sources.taskConfig?.backendTest?.sharedSetupDoc,
+        }),
     };
 }

package/dist/workflows/dag/backend-test-layout.js

@@ -0,0 +1,133 @@
+import path from "node:path";
+/**
+ * Backend-test artifact layout (plan A: configurable test asset paths).
+ *
+ * The layout is resolved once from `task.backendTest` at DAG compile time and
+ * frozen for the whole run. Every generated path (README, module Markdown,
+ * pytest module script, pytest target) is derived from this single source so
+ * writers, gates, analyzers and the executor can never disagree about where
+ * backend-test assets live.
+ *
+ * Default layout keeps the historical frozen contract:
+ *   testcase/md/README.md
+ *   testcase/md/<stem>.md
+ *   testcase/test_<stem>.py
+ *   pytest target: testcase/
+ */
+export const BACKEND_TEST_DEFAULT_TEST_ROOT = "testcase";
+export const BACKEND_TEST_DEFAULT_MARKDOWN_REL = "md";
+export const BACKEND_TEST_DEFAULT_SCRIPT_REL = ".";
+/** Repository roots that must never be configured as backend-test test roots. */
+const FORBIDDEN_TEST_ROOT_PREFIXES = [
+    "src",
+    "app",
+    "lib",
+    "apps",
+    "packages",
+    ".harness",
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    "docs",
+    "website",
+    "scripts",
+    "test",
+    "smoke",
+    "knowledge",
+    "features",
+    "dogfood",
+    "examples",
+    "bin",
+];
+function normalizeRelPosix(value, label) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(`backendTest.${label} must not be empty`);
+    if (trimmed.includes("\\")) {
+        throw new Error(`backendTest.${label} must use forward slashes: ${value}`);
+    }
+    if (path.isAbsolute(trimmed) || /^[A-Za-z]:/.test(trimmed)) {
+        throw new Error(`backendTest.${label} must be a repository-relative path: ${value}`);
+    }
+    const segments = trimmed.split("/").filter((segment) => segment.length > 0);
+    if (segments.some((segment) => segment === ".." || segment === ".")) {
+        throw new Error(`backendTest.${label} must not contain "." or ".." segments: ${value}`);
+    }
+    if (segments.some((segment) => !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(segment))) {
+        throw new Error(`backendTest.${label} contains unsafe path segments: ${value}`);
+    }
+    return segments.join("/");
+}
+function normalizeMarkdownRel(value) {
+    const trimmed = value.trim();
+    if (trimmed === "" || trimmed === ".") {
+        throw new Error("backendTest.markdownRel must be a named subdirectory (not '.'): testcase root itself is reserved for pytest scripts and run reports");
+    }
+    return normalizeRelPosix(value, "markdownRel");
+}
+function normalizeOptionalRel(value, fallback, label) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "string") {
+        throw new Error(`backendTest.${label} must be a string`);
+    }
+    if (value.trim() === "" || value.trim() === ".")
+        return ".";
+    return normalizeRelPosix(value, label);
+}
+function assertTestRootAllowed(testRoot) {
+    const topSegment = testRoot.split("/")[0];
+    if (FORBIDDEN_TEST_ROOT_PREFIXES.some((forbidden) => topSegment === forbidden || topSegment.startsWith(`${forbidden}.`))) {
+        throw new Error(`backendTest.testRoot must not target production/governance trees: ${testRoot}`);
+    }
+    if (topSegment.startsWith(".")) {
+        throw new Error(`backendTest.testRoot must not target hidden directories: ${testRoot}`);
+    }
+}
+/**
+ * Resolve the frozen backend-test artifact layout from task config.
+ * Throws on unsafe or ambiguous configuration (fail-closed).
+ */
+export function resolveBackendTestLayout(config) {
+    const testRoot = config?.testRoot === undefined || config?.testRoot === null
+        ? BACKEND_TEST_DEFAULT_TEST_ROOT
+        : normalizeRelPosix(config.testRoot, "testRoot");
+    assertTestRootAllowed(testRoot);
+    const markdownRel = config?.markdownRel === undefined || config?.markdownRel === null
+        ? BACKEND_TEST_DEFAULT_MARKDOWN_REL
+        : normalizeMarkdownRel(config.markdownRel);
+    if (markdownRel === ".") {
+        throw new Error("backendTest.markdownRel must be a named subdirectory (not '.'): testcase root itself is reserved for pytest scripts and run reports");
+    }
+    const scriptRel = config?.scriptRel === undefined || config?.scriptRel === null
+        ? BACKEND_TEST_DEFAULT_SCRIPT_REL
+        : normalizeOptionalRel(config.scriptRel, ".", "scriptRel");
+    const markdownDir = `${testRoot}/${markdownRel}`;
+    const scriptDir = scriptRel === "." ? testRoot : `${testRoot}/${scriptRel}`;
+    const readmePath = `${markdownDir}/README.md`;
+    const isDefault = testRoot === BACKEND_TEST_DEFAULT_TEST_ROOT &&
+        markdownRel === BACKEND_TEST_DEFAULT_MARKDOWN_REL &&
+        scriptRel === BACKEND_TEST_DEFAULT_SCRIPT_REL;
+    return {
+        testRoot,
+        markdownRel,
+        scriptRel,
+        markdownDir,
+        scriptDir,
+        readmePath,
+        isDefault,
+    };
+}
+/** Markdown module path for a normalized module stem, e.g. "testcase/md/health.md". */
+export function backendTestModuleMarkdownPath(layout, stem) {
+    return `${layout.markdownDir}/${stem}.md`;
+}
+/** Pytest module path for a normalized module stem, e.g. "testcase/test_health.py". */
+export function backendTestModulePytestPath(layout, stem) {
+    return `${layout.scriptDir}/test_${stem}.py`;
+}
+/** pytest CLI target directory with trailing slash, e.g. "testcase/". */
+export function backendTestPytestTarget(layout) {
+    return `${layout.testRoot}/`;
+}