@tea-agent/loop-agent 0.39.0-beta.4 → 0.39.0-beta.6

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -209,7 +209,6 @@ export function loadFrontendImplementationContractJsonSchema(startDir = path.dir
         "mockApi",
         "designEvidence",
         "verificationTargets",
-        "evidenceGaps",
     ];
     const actualRequired = Array.isArray(schema.required) ? schema.required : [];
     const missing = expectedRequired.filter((key) => !actualRequired.includes(key));
@@ -279,7 +278,10 @@ const uiComponentChoiceSchema = z
     component: z.string().min(1),
     decision: z.enum(["specified", "reuse-existing", "new"]),
     specReference: uiComponentSpecReferenceSchema.nullable().optional(),
-    rationale: z.string().min(1),
+    // Optional: the decision enum already carries the semantic (specified →
+    // specReference, new → deviation, reuse-existing → no rationale needed).
+    // Omit for reuse-existing to keep plan output small.
+    rationale: z.string().min(1).optional(),
 })
     .strict();
 const uiComponentChoicesSchema = z.array(uiComponentChoiceSchema);
@@ -407,7 +409,7 @@ export const frontendImplementationContractSchema = z
         uiStates: z.array(z.string().min(1)),
     })
         .strict()).min(1),
-    evidenceGaps: z.array(gap),
+    evidenceGaps: z.array(gap).optional(),
     implementationSteps: z.array(z.string().min(1)).optional(),
     stylingStrategy: z.string().min(1).optional(),
     uiComponentChoices: uiComponentChoicesSchema.optional(),
@@ -1687,7 +1689,7 @@ export async function analyzeFrontendImplementationContract(input) {
     if (!result.success)
         fail("retryable-invalid", `invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`, candidateJsonSha256);
     const blockingGaps = [
-        ...result.data.evidenceGaps,
+        ...(result.data.evidenceGaps ?? []),
         ...result.data.requirements.flatMap((item) => item.evidenceGap ? [item.evidenceGap] : []),
     ].filter((item) => item.blocking);
     if (blockingGaps.length > 0)
@@ -1696,7 +1698,7 @@ export async function analyzeFrontendImplementationContract(input) {
             .join(", ")}`, candidateJsonSha256);
     for (const requirementId of canonicalBinding.requirementIds)
         if (!result.data.requirements.some((item) => item.id === requirementId) &&
-            !result.data.evidenceGaps.some((item) => item.requirementId === requirementId))
+            !(result.data.evidenceGaps ?? []).some((item) => item.requirementId === requirementId))
             fail("blocked", `frontend contract does not cover ${requirementId}`, candidateJsonSha256);
     return {
         canonical: result.data,
@@ -1728,6 +1730,9 @@ const PLAN_LEDGER_FACT_KINDS_FOR_COMPILE = [
     "mock-api",
     "design-deviation",
     "dependency",
+    "plan-requirement",
+    "plan-verification-target",
+    "plan-evidence-gap",
 ];
 /**
  * Restore the editable RFC 7386 plan patch from a committed plan ledger.

package/dist/workflows/dag/frontend-plan-render.js

@@ -54,9 +54,6 @@ export function renderFrontendPlanMarkdown(contract) {
         "## Requirement Coverage",
         requirementsCoverage(contract),
         "",
-        "## Implementation Steps",
-        bulletList(contract.implementationSteps) || "_(not specified)_",
-        "",
         "## Target Files",
         bulletList(contract.targets.files) || "_(none)_",
         "",

package/dist/workflows/dag/frontend-shadow-dual-write.js

@@ -232,6 +232,9 @@ export const PLAN_LEDGER_FACT_KINDS = [
     "mock-api",
     "design-deviation",
     "dependency",
+    "plan-requirement",
+    "plan-verification-target",
+    "plan-evidence-gap",
 ];
 function skeletonTargetFiles(skeleton) {
     if (!isRecord(skeleton))
@@ -288,15 +291,17 @@ export function assemblePlanPatchFromCommittedFacts(records) {
         if (routes.length > 0)
             patch.targets = { routes };
     }
-    const componentChoice = facts.find((fact) => fact.kind === "component-choice");
-    if (componentChoice) {
-        if (Array.isArray(componentChoice.uiComponentChoices)) {
-            patch.uiComponentChoices = componentChoice.uiComponentChoices.filter(isRecord);
-        }
-        const stylingStrategy = asString(componentChoice.stylingStrategy);
-        if (stylingStrategy)
-            patch.stylingStrategy = stylingStrategy;
-    }
+    const componentChoices = facts.filter((fact) => fact.kind === "component-choice");
+    const collectedChoices = componentChoices.flatMap((fact) => Array.isArray(fact.uiComponentChoices)
+        ? fact.uiComponentChoices.filter(isRecord)
+        : []);
+    const stylingStrategy = componentChoices
+        .map((fact) => asString(fact.stylingStrategy))
+        .find((value) => value.length > 0);
+    if (collectedChoices.length > 0)
+        patch.uiComponentChoices = collectedChoices;
+    if (stylingStrategy)
+        patch.stylingStrategy = stylingStrategy;
     const stateFlow = facts.find((fact) => fact.kind === "state-flow");
     if (stateFlow) {
         if (Array.isArray(stateFlow.uiStates)) {
@@ -320,6 +325,41 @@ export function assemblePlanPatchFromCommittedFacts(records) {
     const dependencyPolicy = asString(dependency?.policy);
     if (dependencyPolicy)
         patch.dependencyPolicy = dependencyPolicy;
+    // Requirements / verification targets / evidence gaps / implementation
+    // steps arrive as individual facts (one per record_plan_* call) so a large
+    // plan never exceeds a single model output budget. Aggregate them in
+    // ledger order.
+    const requirements = facts
+        .filter((fact) => fact.kind === "plan-requirement")
+        .map((fact) => fact.entry)
+        .filter(isRecord)
+        .map((entry) => {
+        // The canonical contract schema requires a non-empty
+        // expectedOutcome, but the plan should not be forced to re-write
+        // full outcome prose for every requirement (the contract node
+        // already captured requirement semantics). Derive a deterministic
+        // placeholder from the requirement id when omitted.
+        if (isRecord(entry) && !asString(entry.expectedOutcome)) {
+            const id = asString(entry.id) || "requirement";
+            return { ...entry, expectedOutcome: `implied by contract: ${id}` };
+        }
+        return entry;
+    });
+    if (requirements.length > 0)
+        patch.requirements = requirements;
+    const verificationTargets = facts
+        .filter((fact) => fact.kind === "plan-verification-target")
+        .map((fact) => fact.entry)
+        .filter(isRecord);
+    if (verificationTargets.length > 0) {
+        patch.verificationTargets = verificationTargets;
+    }
+    const evidenceGaps = facts
+        .filter((fact) => fact.kind === "plan-evidence-gap")
+        .map((fact) => fact.entry)
+        .filter(isRecord);
+    if (evidenceGaps.length > 0)
+        patch.evidenceGaps = evidenceGaps;
     return Object.keys(patch).length > 0 ? patch : undefined;
 }
 /** Derive the 7 origin=plan ledger facts from an editable patch. Skeleton
@@ -460,7 +500,8 @@ function planLedgerFactsFromCommittedRecords(records) {
         .filter((fact) => isRecord(fact) &&
         fact.origin === "plan" &&
         typeof fact.kind === "string" &&
-        PLAN_LEDGER_FACT_KINDS.includes(fact.kind));
+        PLAN_LEDGER_FACT_KINDS.includes(fact.kind))
+        .map((fact) => fact);
 }
 export async function loadCommittedPlanLedgerFacts(runDir, nodeId = "frontend-plan-pi") {
     const { readTypedEventStoreFromJsonl } = await import("./frontend-typed-event-store.js");

package/dist/workflows/dag/frontend-test-case-checklist.js

@@ -2,6 +2,7 @@ import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { isPlaywrightCliCommand } from "../../shared/playwright-cli-command-policy.js";
 import { isTruncatedFrontendAcId, isTruncatedWhenUndeclaredFrontendAcId, } from "./frontend-test-result-contract.js";
+import { defaultFrontendTestLayout, frontendTestCasePath, } from "./frontend-test-layout.js";
 const COMMAND_FENCE_LANGUAGE = /^(?:|bash|sh|shell|zsh|fish|console|terminal|command|cmd|powershell|pwsh|javascript|js|typescript|ts|python|py)$/i;
 const LIST_ITEM = /^\s*(?:[-+*]|\d+[.)])\s+(.+)$/;
 const INDENTED_CODE = /^(?: {4,}|\t+)(\S.*)$/;
@@ -290,7 +291,8 @@ function commandGateIssue(input) {
     };
 }
 export async function validateFrontendCaseChecklist(input) {
-    const root = path.join(input.workspaceRoot, "testcase/frontend/cases");
+    const layout = input.layout ?? defaultFrontendTestLayout();
+    const root = path.join(input.workspaceRoot, layout.casesDir);
     const draft = path.join(root, "manifest.draft.json");
     const final = path.join(root, "manifest.json");
     const manifestPath = await exists(draft) ? draft : await exists(final) ? final : "";
@@ -319,7 +321,7 @@ export async function validateFrontendCaseChecklist(input) {
         if (typeof item?.caseId === "string" && /^AC-/i.test(item.caseId))
             issues.push({ ruleId: "case-id-is-ac", caseId: id, detail: "caseId must not be an acceptance id" });
         const casePath = typeof item?.casePath === "string" ? item.casePath : "";
-        const expectedPath = typeof item?.caseId === "string" ? `testcase/frontend/cases/${item.caseId}.md` : "";
+        const expectedPath = typeof item?.caseId === "string" ? frontendTestCasePath(layout, item.caseId) : "";
         const absolute = path.resolve(input.workspaceRoot, casePath);
         const relative = path.relative(input.workspaceRoot, absolute);
         if (!casePath || relative.startsWith("..") || path.isAbsolute(relative) || !(await exists(absolute))) {

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

@@ -1,6 +1,7 @@
 import { readFile, rename, unlink, writeFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { isTruncatedFrontendAcId, isTruncatedWhenUndeclaredFrontendAcId, } from "./frontend-test-result-contract.js";
+import { defaultFrontendTestLayout, frontendTestCasePath, frontendTestEvidenceDir, frontendTestManifestDraftPath, frontendTestManifestPath, } from "./frontend-test-layout.js";
 const DIMENSIONS = new Set(["core", "boundary", "flow", "backend"]);
 function fail(ruleId, detail) {
     const msg = JSON.stringify({ ruleId, detail: String(detail ?? "") });
@@ -19,8 +20,9 @@ function fail(ruleId, detail) {
  * present). When empty, ac-id-shape still applies.
  */
 export async function materializeFrontendTestCaseManifest(input) {
-    const draft = path.join(input.workspaceRoot, "testcase/frontend/cases/manifest.draft.json");
-    const file = path.join(input.workspaceRoot, "testcase/frontend/cases/manifest.json");
+    const layout = input.layout ?? defaultFrontendTestLayout();
+    const draft = path.join(input.workspaceRoot, frontendTestManifestDraftPath(layout));
+    const file = path.join(input.workspaceRoot, frontendTestManifestPath(layout));
     const tmp = `${file}.tmp`;
     const maxCases = input.maxCases ?? 32;
     const declaredAc = new Set(input.declaredAcIds ?? []);
@@ -71,8 +73,8 @@ export async function materializeFrontendTestCaseManifest(input) {
                 fail("unknown-ac", `${ac} not in sourceBinding; repair generator input or AC list`);
             acIds.push(ac);
         }
-        const casePath = `testcase/frontend/cases/${c.caseId}.md`;
-        const evidenceDir = `testcase/frontend/evidence/${c.caseId}/`;
+        const casePath = frontendTestCasePath(layout, c.caseId);
+        const evidenceDir = frontendTestEvidenceDir(layout, c.caseId);
         for (const [k, v] of [
             ["casePath", casePath],
             ["evidenceDir", evidenceDir],

package/dist/workflows/dag/frontend-test-case-quality.js

@@ -1,6 +1,7 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { markdownSection } from "./frontend-test-markdown.js";
+import { defaultFrontendTestLayout, frontendTestCasePath, } from "./frontend-test-layout.js";
 const CASE_ID = /^FE-[A-Za-z0-9]+-\d{3}-(?:core|boundary|flow|backend)$/i;
 const AC_ID = /^AC(?:-[A-Z0-9]+)+$/i;
 const PLACEHOLDER = /\b(?:TODO|TBD|FIXME)\b|结果正确|页面正常|按实际情况处理|验证成功/i;
@@ -15,7 +16,8 @@ const SECTION_ALIASES = {
 function hasList(value) { return /^\s*(?:\d+[.)]|[-*+])\s+\S+/m.test(value); }
 function hasAssertion(value) { return /(?:status|状态|包含|显示|等于|为|可见|不可见|跳转|错误|成功|失败|should|expect|assert|must)/i.test(value); }
 export async function validateFrontendCaseContent(input) {
-    const root = path.join(input.workspaceRoot, "testcase/frontend/cases");
+    const layout = input.layout ?? defaultFrontendTestLayout();
+    const root = path.join(input.workspaceRoot, layout.casesDir);
     const manifestPath = path.join(root, "manifest.json");
     const findings = [];
     let manifest;
@@ -49,7 +51,7 @@ export async function validateFrontendCaseContent(input) {
                     findings.push({ ruleId: "unknown-ac", caseId: id, detail: `${ac} is not declared by the task` });
             }
         }
-        const file = path.join(input.workspaceRoot, item?.casePath || `testcase/frontend/cases/${id}.md`);
+        const file = path.join(input.workspaceRoot, item?.casePath || frontendTestCasePath(layout, id));
         let body = "";
         try {
             body = await readFile(file, "utf8");
@@ -89,7 +91,8 @@ function render(findings) {
 }
 export async function writeFrontendCaseQualityReports(input) {
     const result = await validateFrontendCaseContent(input);
-    const dir = path.join(input.workspaceRoot, input.outputDir ?? "testcase/frontend/reports");
+    const layout = input.layout ?? defaultFrontendTestLayout();
+    const dir = path.join(input.workspaceRoot, input.outputDir ?? layout.reportsDir);
     await mkdir(dir, { recursive: true });
     await writeFile(path.join(dir, "frontend-test-case-quality-advisory.md"), result.markdown, "utf8");
     await writeFile(path.join(dir, "frontend-test-case-quality-advisory.html"), result.html, "utf8");

package/dist/workflows/dag/frontend-test-environment-probe.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { defaultFrontendTestLayout, frontendTestContextRel, frontendTestProbeRel, } from "./frontend-test-layout.js";
 export const FRONTEND_TEST_CONTEXT_REL = "testcase/frontend/rag/context.md";
 export const FRONTEND_TEST_PROBE_REL = "testcase/frontend/rag/environment-probe.json";
 const CONNECTION_REFUSED_HINT = "被测服务未在 baseUrl 监听（connection refused）。请先启动本地前端（例如 scripts/serve.sh 或项目约定的 npm start），确认可访问后再从 materialize-frontend-test-execution-shell 续跑。";
@@ -65,9 +66,9 @@ function resolveBaseUrl(context) {
     }
     return null;
 }
-async function writeProbe(workspaceRoot, probe) {
-    const probePath = path.join(workspaceRoot, FRONTEND_TEST_PROBE_REL);
-    const contextPath = path.join(workspaceRoot, FRONTEND_TEST_CONTEXT_REL);
+async function writeProbe(workspaceRoot, probe, layout) {
+    const probePath = path.join(workspaceRoot, frontendTestProbeRel(layout));
+    const contextPath = path.join(workspaceRoot, frontendTestContextRel(layout));
     await mkdir(path.dirname(probePath), { recursive: true });
     await writeFile(probePath, `${JSON.stringify(probe, null, 2)}\n`, "utf8");
     let context = "";
@@ -84,14 +85,16 @@ async function writeProbe(workspaceRoot, probe) {
     await writeFile(contextPath, next, "utf8");
 }
 export async function probeFrontendTestEnvironment(input) {
+    const layout = input.layout ?? defaultFrontendTestLayout();
     const curl = input.curl ?? defaultCurlRunner;
-    const contextPath = path.join(input.workspaceRoot, FRONTEND_TEST_CONTEXT_REL);
+    const contextRel = frontendTestContextRel(layout);
+    const contextPath = path.join(input.workspaceRoot, contextRel);
     let context;
     try {
         context = await readFile(contextPath, "utf8");
     }
     catch {
-        return { ok: false, stderr: `missing ${FRONTEND_TEST_CONTEXT_REL}` };
+        return { ok: false, stderr: `missing ${contextRel}` };
     }
     const rawUrl = resolveBaseUrl(context);
     if (!rawUrl) {
@@ -139,7 +142,7 @@ export async function probeFrontendTestEnvironment(input) {
             ...(extra.hint ? { hint: extra.hint } : {}),
             ...(extra.baseUrlSource ? { baseUrlSource: extra.baseUrlSource } : {}),
         };
-        await writeProbe(input.workspaceRoot, probe);
+        await writeProbe(input.workspaceRoot, probe, layout);
         const payload = {
             blockedReason: reason,
             baseUrl: probe.baseUrlRedacted,
@@ -218,7 +221,7 @@ export async function probeFrontendTestEnvironment(input) {
         curlExit: result.status,
         errorClass: null,
     };
-    await writeProbe(input.workspaceRoot, probe);
+    await writeProbe(input.workspaceRoot, probe, layout);
     return {
         ok: true,
         stdout: `frontend-test-execution-v1 validated contextBaseUrl=${safe} source=${baseUrlSource} probe=reachable method=${used} httpStatus=${statusNum}`,

package/dist/workflows/dag/frontend-test-html-report.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { frontendTestResultContractSchema } from "./frontend-test-result-contract.js";
+import { defaultFrontendTestLayout, } from "./frontend-test-layout.js";
 function escapeHtml(value) {
     return String(value ?? "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 }
@@ -80,7 +81,8 @@ async function writePairAtomic(markdownPath, markdown, htmlPath, html) {
 export async function renderFrontendTestHtmlReport(input) {
     const resultPath = path.join(input.runDir, "contracts", "frontend-test-result.json");
     const result = frontendTestResultContractSchema.parse(JSON.parse(await readFile(resultPath, "utf8")));
-    const outputDir = path.join(input.workspaceRoot, "testcase", "frontend", "reports");
+    const layout = input.layout ?? defaultFrontendTestLayout();
+    const outputDir = path.join(input.workspaceRoot, layout.reportsDir);
     const markdownPath = path.join(outputDir, "frontend-test-report.md");
     const htmlPath = path.join(outputDir, "frontend-test-report.html");
     const outcomeLabel = result.outcome === "passed" ? "测试通过" : result.outcome === "failed" ? "测试失败" : "测试未完成";

package/dist/workflows/dag/frontend-test-l5-report.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { frontendTestResultContractSchema, } from "./frontend-test-result-contract.js";
+import { defaultFrontendTestLayout, } from "./frontend-test-layout.js";
 function ratioMetric(numerator, denominator, threshold, label) {
     if (denominator === 0) {
         return { numerator, denominator, ratio: null, threshold, status: "unavailable", reason: `${label}-denominator-is-zero` };
@@ -169,7 +170,8 @@ export async function renderFrontendTestL5Report(input) {
     const resultPath = path.join(input.runDir, "contracts", "frontend-test-result.json");
     const result = frontendTestResultContractSchema.parse(JSON.parse(await readFile(resultPath, "utf8")));
     const metrics = computeFrontendL5ReportMetrics(result);
-    const outputDir = path.join(input.workspaceRoot, "testcase", "frontend", "reports");
+    const layout = input.layout ?? defaultFrontendTestLayout();
+    const outputDir = path.join(input.workspaceRoot, layout.reportsDir);
     const markdownPath = path.join(outputDir, "frontend-test-l5-dashboard.md");
     const htmlPath = path.join(outputDir, "frontend-test-l5-dashboard.html");
     await writePairAtomic(markdownPath, renderMarkdown(result, metrics), htmlPath, renderHtml(result, metrics));

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

@@ -0,0 +1,159 @@
+import path from "node:path";
+/**
+ * Frontend-test artifact layout (configurable testRoot).
+ *
+ * Resolved once from `task.frontendTest.testRoot` at DAG compile time and
+ * frozen on the spec for the whole run. Writers, gates, Playwright fences
+ * and TaskSpec allowedPaths all derive from this single object.
+ *
+ * Default layout keeps the historical frozen contract:
+ *   testcase/frontend/rag/**
+ *   testcase/frontend/cases/**
+ *   testcase/frontend/evidence/**
+ *   testcase/frontend/reports/**
+ *   testcase/frontend/fixtures/**
+ */
+export const FRONTEND_TEST_DEFAULT_TEST_ROOT = "testcase/frontend";
+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(`frontendTest.${label} must not be empty`);
+    if (trimmed.includes("\\")) {
+        throw new Error(`frontendTest.${label} must use forward slashes: ${value}`);
+    }
+    if (path.isAbsolute(trimmed) || /^[A-Za-z]:/.test(trimmed)) {
+        throw new Error(`frontendTest.${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(`frontendTest.${label} must not contain "." or ".." segments: ${value}`);
+    }
+    if (segments.some((segment) => segment.startsWith("."))) {
+        throw new Error(`frontendTest.${label} must not target hidden directories: ${value}`);
+    }
+    if (segments.some((segment) => !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(segment))) {
+        throw new Error(`frontendTest.${label} contains unsafe path segments: ${value}`);
+    }
+    return segments.join("/");
+}
+function assertTestRootAllowed(testRoot) {
+    const topSegment = testRoot.split("/")[0];
+    if (FORBIDDEN_TEST_ROOT_PREFIXES.some((forbidden) => topSegment === forbidden || topSegment.startsWith(`${forbidden}.`))) {
+        throw new Error(`frontendTest.testRoot must not target production/governance trees: ${testRoot}`);
+    }
+    if (topSegment.startsWith(".")) {
+        throw new Error(`frontendTest.testRoot must not target hidden directories: ${testRoot}`);
+    }
+}
+/**
+ * Resolve the frozen frontend-test artifact layout from task config.
+ * Throws on unsafe or ambiguous configuration (fail-closed).
+ */
+export function resolveFrontendTestLayout(config) {
+    const testRoot = config?.testRoot === undefined || config?.testRoot === null
+        ? FRONTEND_TEST_DEFAULT_TEST_ROOT
+        : normalizeRelPosix(config.testRoot, "testRoot");
+    assertTestRootAllowed(testRoot);
+    const isDefault = testRoot === FRONTEND_TEST_DEFAULT_TEST_ROOT;
+    return {
+        testRoot,
+        ragDir: `${testRoot}/rag`,
+        casesDir: `${testRoot}/cases`,
+        evidenceDir: `${testRoot}/evidence`,
+        reportsDir: `${testRoot}/reports`,
+        fixturesDir: `${testRoot}/fixtures`,
+        isDefault,
+    };
+}
+/** Historical default layout. Old DAGs without frontendTestLayout use this. */
+export function defaultFrontendTestLayout() {
+    return resolveFrontendTestLayout(undefined);
+}
+export function frontendTestLayoutFromSpec(spec) {
+    const frozen = spec?.frontendTestLayout;
+    if (!frozen)
+        return defaultFrontendTestLayout();
+    return resolveFrontendTestLayout({ testRoot: frozen.testRoot });
+}
+const DEFAULT_PREFIX = `${FRONTEND_TEST_DEFAULT_TEST_ROOT}/`;
+/**
+ * Longest-prefix rewrite of historical `testcase/frontend/` paths.
+ * No-op when layout.isDefault so default DAGs stay byte-identical.
+ * Never replaces the short token `testcase/` (would collide with backend-test).
+ */
+export function applyFrontendTestLayoutToText(text, layout) {
+    if (layout.isDefault)
+        return text;
+    const replacement = `${layout.testRoot}/`;
+    let output = "";
+    for (let i = 0; i < text.length;) {
+        if (text.startsWith(replacement, i)) {
+            output += replacement;
+            i += replacement.length;
+            continue;
+        }
+        if (text.startsWith(DEFAULT_PREFIX, i)) {
+            output += replacement;
+            i += DEFAULT_PREFIX.length;
+            continue;
+        }
+        output += text[i];
+        i += 1;
+    }
+    return output;
+}
+export function frontendTestCasePath(layout, caseId) {
+    return `${layout.casesDir}/${caseId}.md`;
+}
+export function frontendTestEvidenceDir(layout, caseId) {
+    return `${layout.evidenceDir}/${caseId}/`;
+}
+export function frontendTestEvidencePrefix(layout, caseId) {
+    return `${layout.evidenceDir}/${caseId}`;
+}
+export function frontendTestManifestPath(layout) {
+    return `${layout.casesDir}/manifest.json`;
+}
+export function frontendTestManifestDraftPath(layout) {
+    return `${layout.casesDir}/manifest.draft.json`;
+}
+export function frontendTestContextRel(layout) {
+    return `${layout.ragDir}/context.md`;
+}
+export function frontendTestCoverageMapRel(layout) {
+    return `${layout.ragDir}/coverage-map.md`;
+}
+export function frontendTestProbeRel(layout) {
+    return `${layout.ragDir}/environment-probe.json`;
+}
+export function frontendTestStandardScenariosRel(layout) {
+    return `${layout.ragDir}/standard-scenarios.v1.json`;
+}
+export function frontendTestUiAnchorsRel(layout) {
+    return `${layout.ragDir}/ui-anchors.md`;
+}
+export function escapeRegexLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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

@@ -6,6 +6,7 @@ import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-s
 import { readPlaywrightCliReceipts, summarizePlaywrightCliReceipts, } from "../../executors/pi-playwright-cli-tool.js";
 import { validateFrontendCaseContent } from "./frontend-test-case-quality.js";
 import { markdownH1Title, markdownList, markdownSection, } from "./frontend-test-markdown.js";
+import { defaultFrontendTestLayout, frontendTestEvidencePrefix, frontendTestManifestPath, } from "./frontend-test-layout.js";
 export const FRONTEND_TEST_RESULT_SCHEMA_ID = "frontend-test-result-v1";
 /**
  * Truncated acceptance-id shapes observed in generator output: a bare
@@ -124,12 +125,14 @@ function isSafeEvidenceShellPath(value) {
  * backslash interpretation for the former long `node -e` command.
  */
 export async function validateFrontendCaseEvidence(input) {
-    const manifestPath = path.join(input.workspaceRoot, "testcase/frontend/cases/manifest.json");
+    const layout = input.layout ?? defaultFrontendTestLayout();
+    const manifestRel = frontendTestManifestPath(layout);
+    const manifestPath = path.join(input.workspaceRoot, manifestRel);
     try {
         await stat(manifestPath);
     }
     catch {
-        throw new Error("missing testcase/frontend/cases/manifest.json");
+        throw new Error(`missing ${manifestRel}`);
     }
     let manifest;
     try {
@@ -147,7 +150,7 @@ export async function validateFrontendCaseEvidence(input) {
         const item = rawCase;
         const id = typeof item?.caseId === "string" ? item.caseId : "?";
         const dir = item?.evidenceDir;
-        const prefix = `testcase/frontend/evidence/${id}`;
+        const prefix = frontendTestEvidencePrefix(layout, id);
         if (!item ||
             typeof item.caseId !== "string" ||
             typeof dir !== "string" ||
@@ -191,12 +194,15 @@ export async function validateFrontendCaseEvidence(input) {
                     continue;
                 }
                 const currentPrefix = `${prefix}/`;
-                if (evidencePath.startsWith("testcase/frontend/evidence/") && !evidencePath.startsWith(currentPrefix)) {
+                if ((evidencePath.startsWith(`${layout.evidenceDir}/`) ||
+                    evidencePath.startsWith("testcase/frontend/evidence/")) &&
+                    !evidencePath.startsWith(currentPrefix)) {
                     hardFail = true;
                     issues.push({ ruleId: "cross-case-evidence-path", caseId: id, detail: evidencePath });
                     continue;
                 }
-                const target = evidencePath.startsWith("testcase/")
+                const target = evidencePath.startsWith(`${layout.testRoot}/`) ||
+                    evidencePath.startsWith("testcase/")
                     ? path.join(input.workspaceRoot, evidencePath)
                     : path.join(input.workspaceRoot, dir, evidencePath);
                 if (!(await isNonEmptyFile(target))) {
@@ -343,8 +349,10 @@ function sha256(content) {
  * headings. Numbered and bulleted lists are extracted; a missing 测试目的
  * falls back to the case H1 title.
  */
-async function readFrontendCaseContent(workspaceRoot, casePath) {
-    if (!safeRelativePathSchema.safeParse(casePath).success || !casePath.startsWith("testcase/frontend/cases/")) {
+async function readFrontendCaseContent(workspaceRoot, casePath, layout) {
+    if (!safeRelativePathSchema.safeParse(casePath).success ||
+        !(casePath.startsWith(`${layout.casesDir}/`) ||
+            casePath.startsWith("testcase/frontend/cases/"))) {
         throw new Error(`unsafe frontend case path: ${casePath}`);
     }
     const body = await readFile(path.resolve(workspaceRoot, casePath), "utf8");
@@ -397,7 +405,7 @@ function assertInside(root, candidate, label) {
         throw new Error(`${label} escapes its allowed root`);
     }
 }
-async function readEvidenceFile(repoRoot, evidenceRoot, relative) {
+async function readEvidenceFile(repoRoot, evidenceRoot, relative, layout) {
     if (!safeRelativePathSchema.safeParse(relative).success) {
         throw new Error(`unsafe evidence path: ${relative}`);
     }
@@ -409,12 +417,16 @@ async function readEvidenceFile(repoRoot, evidenceRoot, relative) {
     const normalized = relative;
     const evidenceRootRel = path.relative(repoRootResolved, evidenceRootResolved).replaceAll("\\", "/");
     const isCurrentCaseRepoPath = normalized === evidenceRootRel || normalized.startsWith(`${evidenceRootRel}/`);
-    const isRepoRelative = normalized.startsWith("testcase/") && !isCurrentCaseRepoPath;
+    const isRepoRelative = (normalized.startsWith(`${layout.testRoot}/`) ||
+        normalized.startsWith("testcase/")) &&
+        !isCurrentCaseRepoPath;
     const absolute = isRepoRelative
         ? path.resolve(repoRootResolved, normalized)
         : path.resolve(evidenceRootResolved, normalized);
     assertInside(repoRootResolved, absolute, "evidence path");
-    if (isRepoRelative && normalized.startsWith("testcase/frontend/evidence/")) {
+    if (isRepoRelative &&
+        (normalized.startsWith(`${layout.evidenceDir}/`) ||
+            normalized.startsWith("testcase/frontend/evidence/"))) {
         throw new Error(`evidence path escapes evidence root: ${relative}`);
     }
     if (!isRepoRelative)
@@ -437,7 +449,8 @@ export async function materializeFrontendTestResult(input) {
     if (!sourceBinding?.taskId || !sourceBinding.sources?.length) {
         throw new Error("frontend-test result requires frozen sourceBinding");
     }
-    const manifestPath = "testcase/frontend/cases/manifest.json";
+    const layout = input.layout ?? defaultFrontendTestLayout();
+    const manifestPath = frontendTestManifestPath(layout);
     const manifestAbsolute = path.resolve(input.workspaceRoot, manifestPath);
     let manifest;
     try {
@@ -453,6 +466,7 @@ export async function materializeFrontendTestResult(input) {
     const contentQuality = await validateFrontendCaseContent({
         workspaceRoot: input.workspaceRoot,
         requiredAcIds: sourceBinding.requirementIds ?? [],
+        layout,
     });
     advisoryFindings.push(...contentQuality.findings);
     const requiredIds = new Set(sourceBinding.requirementIds ?? []);
@@ -464,7 +478,7 @@ export async function materializeFrontendTestResult(input) {
             advisoryFindings.push({ ruleId: "invalid-manifest-case", detail: "manifest case is missing caseId, acIds, or evidenceDir" });
             continue;
         }
-        const evidencePrefix = `testcase/frontend/evidence/${item.caseId}`;
+        const evidencePrefix = frontendTestEvidencePrefix(layout, item.caseId);
         if (!(item.evidenceDir === evidencePrefix || item.evidenceDir.startsWith(`${evidencePrefix}/`))) {
             throw new Error(`unsafe evidenceDir for ${item.caseId}`);
         }
@@ -495,7 +509,7 @@ export async function materializeFrontendTestResult(input) {
             if (typeof evidencePath !== "string" || evidencePath === "execution.md" && evidence.some((entry) => entry.path.endsWith("/execution.md")))
                 continue;
             try {
-                evidence.push(await readEvidenceFile(input.workspaceRoot, evidenceRoot, evidencePath));
+                evidence.push(await readEvidenceFile(input.workspaceRoot, evidenceRoot, evidencePath, layout));
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -541,7 +555,7 @@ export async function materializeFrontendTestResult(input) {
                 }
             }
         }
-        const { caseContent, testPoints } = await readFrontendCaseContent(input.workspaceRoot, item.casePath);
+        const { caseContent, testPoints } = await readFrontendCaseContent(input.workspaceRoot, item.casePath, layout);
         // Parse bounded fixed sections from execution.md. Missing optional
         // summary/steps are advisory only and never downgrade a passed status.
         let executionSummary = "";