@tea-agent/loop-agent 0.39.0-next.30 → 0.39.0-next.32

package/dist/workflows/dag/frontend-verification-trace.js

@@ -2,6 +2,18 @@ import { readFile, stat, writeFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, frontendImplementationContractSchema, } from "./frontend-implementation-contract.js";
 export const FRONTEND_VERIFICATION_TRACE_SCHEMA_ID = "frontend-verification-trace-v1";
+/**
+ * Shared marker for a project that exposes no usable verification command at
+ * generation time. The marker command runs (and logs not-run honestly), but it
+ * must never count as successful verification evidence: labels carrying this
+ * text are excluded from successful evidence and targets bound to it fail the
+ * trace gate instead of passing it.
+ */
+export const FRONTEND_NO_VERIFICATION_MARKER_TEXT = "No frontend verification command configured";
+export function isFrontendNoVerificationMarkerLabel(label) {
+    return label.includes(FRONTEND_NO_VERIFICATION_MARKER_TEXT);
+}
+export const FRONTEND_VERIFICATION_UNAVAILABLE_MESSAGE = `frontend verification unavailable: the only frozen static command is the no-op not-run marker (${FRONTEND_NO_VERIFICATION_MARKER_TEXT}); declare verification commands via task.json --verify or 执行约束.md and regenerate the DAG`;
 async function readJsonFile(filePath) {
     return JSON.parse(await readFile(filePath, "utf8"));
 }
@@ -52,7 +64,14 @@ export async function evaluateVerificationTargets(input) {
     const hardIssues = [];
     for (const target of input.contract.verificationTargets) {
         const issues = [];
-        const owners = input.labelOwners.get(target.commandLabel);
+        if (isFrontendNoVerificationMarkerLabel(target.commandLabel)) {
+            // A target bound to the not-run marker has no verification behind it;
+            // passing it would let the run finish green without any check.
+            issues.push(`${target.id}: ${FRONTEND_VERIFICATION_UNAVAILABLE_MESSAGE}`);
+        }
+        const owners = isFrontendNoVerificationMarkerLabel(target.commandLabel)
+            ? []
+            : (input.labelOwners.get(target.commandLabel) ?? []);
         if (!owners?.length) {
             issues.push(`commandLabel not executed in current-run frozen evidence: ${target.commandLabel}`);
         }
@@ -189,11 +208,17 @@ export async function runFrontendVerificationTraceGate(input) {
         throw new Error("trace: selected Mock strategy requires successful Mock verification commands");
     }
     if (input.evidence) {
-        if (input.evidence.static.commandLabels.length === 0) {
-            throw new Error("trace: no successful static verification commands in current run");
+        // The no-op not-run marker never counts as successful verification
+        // evidence, even if it executed with exit code 0.
+        const effectiveStaticLabels = input.evidence.static.commandLabels.filter((label) => !isFrontendNoVerificationMarkerLabel(label));
+        const effectiveBehaviorLabels = input.evidence.behavior.commandLabels.filter((label) => !isFrontendNoVerificationMarkerLabel(label));
+        if (effectiveStaticLabels.length === 0) {
+            throw new Error(input.evidence.static.commandLabels.length > 0
+                ? `trace: ${FRONTEND_VERIFICATION_UNAVAILABLE_MESSAGE}`
+                : "trace: no successful static verification commands in current run");
         }
         if (requiresBehaviorVerification &&
-            input.evidence.behavior.commandLabels.length === 0) {
+            effectiveBehaviorLabels.length === 0) {
             throw new Error("trace: no successful behavior verification commands in current run");
         }
     }

package/dist/workflows/dag/init-hybrid.js

@@ -28,12 +28,14 @@ import { resolveExecutorModelMatrices } from "../../executors/model-routing.js";
 import { normalizeTaskRequirementText, resolveTaskDagTemplateSelection, } from "./task-demand-routing.js";
 import { BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT, buildBackendTestExecutionPreflightShellSnippet, } from "./backend-test-execution-contract.js";
 import { resolveBackendTestLayout, } from "./backend-test-layout.js";
+import { applyFrontendTestLayoutToText, resolveFrontendTestLayout, } from "./frontend-test-layout.js";
 import { buildBackendTestOutcomeGateShellSnippet } from "./backend-test-result-contract.js";
 import { buildBackendTestIntakeContext } from "./backend-test-intake-context.js";
 import { buildFrontendTestOutcomeGateShellSnippet } from "./frontend-test-result-contract.js";
 import { classifyFrontendRisk, } from "./frontend-risk.js";
 import { discoverFrontendProjectCapability, } from "./frontend-project-capability.js";
 import { buildFrontendImplementationContractSkeleton, FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID, loadFrontendImplementationContractJsonSchema, } from "./frontend-implementation-contract.js";
+import { FRONTEND_NO_VERIFICATION_MARKER_TEXT } from "./frontend-verification-trace.js";
 import { serializeDagTaskSourcePath } from "../../task/dag-source-paths.js";
 const REQUIREMENT_FILE = "需求.md";
 const CONSTRAINT_FILE = "执行约束.md";
@@ -1281,11 +1283,15 @@ function deriveParallelScoutPaths(taskConfig) {
                 : allowed,
     };
 }
+const FRONTEND_NO_STATIC_VERIFICATION_MARKER = `node -e "console.log('${FRONTEND_NO_VERIFICATION_MARKER_TEXT}; static/behavior verification not-run')"`;
 /**
  * Resolve frontend verification fallbacks from the target project's own
  * package scripts. The DAG builder is also used by unit fixtures without a
- * package.json, so those fixtures retain the historical generic fallback.
- * Real projects never inherit loop-agent's commands when package.json exists.
+ * repoRoot, so those fixtures retain the historical generic fallback. A real
+ * project (repoRoot set) without a readable package.json has no scripts to
+ * invoke; the generic fallback would only inject commands guaranteed to fail
+ * at verify time, so such projects fall through to the tsc probe and may end
+ * up with no fallback commands plus a generation-time advisory.
  */
 async function discoverFrontendFallbackVerifyCommands(repoRoot) {
     const genericFallback = {
@@ -1302,10 +1308,8 @@ async function discoverFrontendFallbackVerifyCommands(repoRoot) {
         }
     }
     catch {
-        return genericFallback;
+        // No readable manifest: leave scripts unset and keep probing.
     }
-    if (!scripts)
-        return genericFallback;
     let packageManager = "npm";
     for (const [lockfile, manager] of [
         ["pnpm-lock.yaml", "pnpm"],
@@ -1382,19 +1386,66 @@ function toDagSourcePath(sources, absolutePath) {
         absolutePath,
     });
 }
-function extractExplicitRequirementIds(...markdownInputs) {
+/**
+ * Declaration-line shapes that assert a requirement id: list items
+ * ("- AC-1: ..."), numbered/ordered acceptance entries ("1. AC-1 ...",
+ * "1、AC-1"), table rows ("| AC-1 | ..."), and explicit key/value or
+ * heading declarations ("AC-1：...", "id: AC-1"). Ids that merely appear
+ * inside narrative prose (e.g. a fixture run id mentioned in background:
+ * "夹具 run 2026-08-23-req-f03535aa 已存在") are incidental mentions, not
+ * declared requirements, and must not pollute sourceBinding.requirementIds.
+ */
+const REQUIREMENT_ID_DECLARATION_LINE = /^\s*(?:[-+*]\s+|\d+[.、)）]\s*|\|\s*)?(?:[-A-Z0-9]+\s*[::]\s*)?(?:\*\*)?(?:REQ|BR|AC)-/i;
+function isRequirementIdDeclarationLine(line) {
+    return REQUIREMENT_ID_DECLARATION_LINE.test(line);
+}
+function extractExplicitRequirementIds(requirementMarkdown, ...fallbackMarkdown) {
     const ids = [];
     const seen = new Set();
-    for (const markdown of markdownInputs) {
+    const collect = (markdown, declarationsOnly) => {
         if (!markdown)
-            continue;
-        for (const match of markdown.matchAll(/\b(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/gi)) {
+            return;
+        const source = declarationsOnly
+            ? markdown
+                .split(/\r?\n/)
+                .filter((line) => isRequirementIdDeclarationLine(line))
+                .join("\n")
+            : markdown;
+        for (const match of source.matchAll(/\b(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/gi)) {
             const id = match[0].toUpperCase();
             if (!seen.has(id)) {
                 seen.add(id);
                 ids.push(id);
             }
         }
+    };
+    // The requirement document itself is human-authored acceptance prose:
+    // only declaration lines declare requirements there. If the document has
+    // no declaration-shaped lines at all (minimal free-form tasks like
+    // "covers AC-001"), fall back to its full text so bindings never go
+    // missing for unstructured input. References and constraints are bound
+    // documents (acceptance yaml, analysis docs) whose ids are authoritative
+    // wherever they appear — keep full scan for them.
+    const declarationLines = requirementMarkdown
+        .split(/\r?\n/)
+        .filter((line) => isRequirementIdDeclarationLine(line));
+    collect(requirementMarkdown, declarationLines.length > 0);
+    for (const markdown of fallbackMarkdown) {
+        if (markdown)
+            collect(markdown, false);
+    }
+    return ids;
+}
+/** Extract ids from an explicit authoritative section (full scan inside it). */
+function extractSectionRequirementIds(sectionMarkdown) {
+    const ids = [];
+    const seen = new Set();
+    for (const match of sectionMarkdown.matchAll(/\b(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/gi)) {
+        const id = match[0].toUpperCase();
+        if (!seen.has(id)) {
+            seen.add(id);
+            ids.push(id);
+        }
     }
     return ids;
 }
@@ -1408,7 +1459,7 @@ export function extractTaskScopedRequirementIds(requirementMarkdown, ...fallback
     // Without it, preserve legacy full-scan behavior (requirement + references).
     const sectionMatch = requirementMarkdown.match(/(?:^|\n)##\s*Acceptance References\s*\n([\s\S]*?)(?=\n##\s+|\n#\s+|$)/i);
     if (sectionMatch?.[1]) {
-        const fromSection = extractExplicitRequirementIds(sectionMatch[1]);
+        const fromSection = extractSectionRequirementIds(sectionMatch[1]);
         if (fromSection.length > 0)
             return fromSection;
     }
@@ -2530,7 +2581,14 @@ async function buildFrontendHybridDagFromTask(sources) {
         return buildBlockedFrontendMockDag(frontendSources, readOnlyPaths, forbiddenPaths, globalConstraints, blockedReason);
     }
     const fallbackVerifyCommands = await discoverFrontendFallbackVerifyCommands(sources.repoRoot);
-    const staticFallbackCommands = fallbackVerifyCommands.staticCommands;
+    // The verification bundle schema requires at least one static command. When
+    // a real project exposes no usable verification command at all, run an
+    // explicit no-op marker instead of a command that is guaranteed to fail:
+    // the trace then records not-run honestly and the advisory asks the task
+    // to declare verification commands and regenerate.
+    const staticFallbackCommands = fallbackVerifyCommands.staticCommands.length > 0
+        ? fallbackVerifyCommands.staticCommands
+        : [FRONTEND_NO_STATIC_VERIFICATION_MARKER];
     const behaviorFallbackCommands = fallbackVerifyCommands.behaviorCommands;
     const parsedFrontendVerifyCommands = extractFrontendVerifyCommandsFromMarkdown({
         repoRoot: sources.repoRoot,
@@ -2629,6 +2687,11 @@ async function buildFrontendHybridDagFromTask(sources) {
         ...behaviorVerifyEvidence.commandLabels.map((command) => `  - ${JSON.stringify(command)}`),
     ].join("\n");
     const advisories = [];
+    if (!hasDeclaredFrontendVerification &&
+        fallbackVerifyCommands.staticCommands.length === 0 &&
+        fallbackVerifyCommands.behaviorCommands.length === 0) {
+        advisories.push("未发现可用的前端验证命令：目标项目没有可读取的 package.json scripts，也未探测到本地 TypeScript，verify 节点将没有静态/行为命令可执行。请在 task.json --verify 或执行约束.md 的验证约束中显式声明命令（例如 node --check src/app.js），然后重新生成 DAG。");
+    }
     if (frontendSourceMentionsMock(frontendSources) &&
         frontendMockStrategyMustBeNotNeeded(frontendSources)) {
         advisories.push("auto 模式已将 Mock 策略收窄为 not-needed：任务源提到接口/API/Mock 需求，但仓库无确认 Mock 能力或无确定性 Mock 验证命令。若项目规范要求 Mock，请声明 frontendMock.verifyCommands 或 policy:required 后重新生成 DAG。");
@@ -4736,11 +4799,57 @@ function applyBackendTestLayoutToDagSpec(spec, layout) {
     spec.successCriteria = spec.successCriteria?.map(rewrite);
     spec.backendTestLayout = layout;
 }
+/** Rewrite layout-dependent strings across a compiled frontend-test DAG spec. */
+function applyFrontendTestLayoutToDagSpec(spec, layout) {
+    if (layout.isDefault) {
+        spec.frontendTestLayout = layout;
+        return;
+    }
+    const rewrite = (value) => applyFrontendTestLayoutToText(value, layout);
+    for (const task of spec.tasks) {
+        task.subtask_prompt = rewrite(task.subtask_prompt);
+        if (task.outputContract)
+            task.outputContract = rewrite(task.outputContract);
+        task.writeSet = task.writeSet?.map(rewrite);
+        task.allowedPaths = task.allowedPaths?.map(rewrite);
+        task.forbiddenPaths = task.forbiddenPaths?.map(rewrite);
+        if (task.dynamicExpansion?.childTask) {
+            const child = task.dynamicExpansion.childTask;
+            if (typeof child.subtaskPromptTemplate === "string") {
+                child.subtaskPromptTemplate = rewrite(child.subtaskPromptTemplate);
+            }
+            if (typeof child.outputContract === "string") {
+                child.outputContract = rewrite(child.outputContract);
+            }
+            if (Array.isArray(child.allowedPaths)) {
+                child.allowedPaths = child.allowedPaths.map((entry) => typeof entry === "string" ? rewrite(entry) : entry);
+            }
+            if (Array.isArray(child.writeSet)) {
+                child.writeSet = child.writeSet.map((entry) => typeof entry === "string" ? rewrite(entry) : entry);
+            }
+            if (Array.isArray(child.forbiddenPaths)) {
+                child.forbiddenPaths = child.forbiddenPaths.map((entry) => typeof entry === "string" ? rewrite(entry) : entry);
+            }
+        }
+        if (task.shell?.commands) {
+            task.shell.commands = task.shell.commands.map(rewrite);
+        }
+    }
+    spec.globalConstraints = spec.globalConstraints?.map(rewrite);
+    spec.successCriteria = spec.successCriteria?.map(rewrite);
+    spec.frontendTestLayout = layout;
+}
+function allowedPathsCoverFrontendTestRoot(allowedPaths, testRoot) {
+    const probe = `${testRoot}/_layout_probe_`;
+    return allowedPaths.some((pattern) => pathMatchesPattern(testRoot, pattern) ||
+        pathMatchesPattern(probe, pattern));
+}
 // ---------------------------------------------------------------------------
 // Frontend browser-test RAG DAG template
 // ---------------------------------------------------------------------------
 function buildFrontendTestHybridDag(sources) {
     const rawFrontendTest = sources.taskConfig.frontendTest;
+    const layout = resolveFrontendTestLayout(rawFrontendTest);
     const config = {
         // Default 32: common FE suites cover ~24 AC with multi-dimension cases; 20 caused map maxExpandedNodes failures.
         maxCasesPerBatch: rawFrontendTest?.maxCasesPerBatch ?? 32,
@@ -4762,28 +4871,32 @@ function buildFrontendTestHybridDag(sources) {
     };
     const declaredRequirementIds = buildDagSourceBinding(sources).requirementIds;
     const declaredAcIds = declaredRequirementIds.filter((id) => /^AC(?:-[A-Z0-9]+)+$/i.test(id));
+    // Optional project-local UI anchor ledger: only mention it in prompts when it
+    // exists so ledger-less projects keep generating without noise.
+    const hasUiAnchorsLedger = Boolean(sources.repoRoot &&
+        existsSync(path.join(sources.repoRoot, layout.ragDir, "ui-anchors.md")));
+    const uiAnchorsLedgerInstruction = hasUiAnchorsLedger
+        ? `Also read ${layout.ragDir}/ui-anchors.md (UI anchor ledger). Every passing find assertion in generated cases must quote a ledger row whose 状态 is 有效 for the matching page x state section; rows marked 不可断言/失效 must not be used as passing assertions. When an AC names a control absent from the ledger section for that state, emit a blocked case note (blockedReason unique-control-unavailable) instead of exploratory find steps, and follow ledger 备注 alternatives (split-node short literals) exactly.`
+        : "";
     const reviewMode = config.reviewMode;
     const blockingReview = reviewMode === "blocking";
     const strictOutcomeGate = config.strictOutcomeGate;
     const maxRerunAttempts = config.maxRerunAttempts;
     const enableRetrospect = config.reports?.retrospect === true;
     const enableL5Report = config.reports?.l5 !== false;
-    const hasFrontendTestWriteScope = sources.taskConfig.allowedPaths.some((pattern) => pattern === "testcase/frontend/**" ||
-        pattern === "testcase/**" ||
-        pattern === "**");
-    if (!hasFrontendTestWriteScope) {
-        throw new Error('frontend-test requires task.json allowedPaths to include "testcase/frontend/**" (or an explicit containing glob).');
+    if (!allowedPathsCoverFrontendTestRoot(sources.taskConfig.allowedPaths, layout.testRoot)) {
+        throw new Error(`frontend-test requires task.json allowedPaths to cover "${layout.testRoot}/**" (or an explicit containing glob).`);
     }
     const forbidden = commonForbiddenPaths(sources);
-    const ragWriteSet = ["testcase/frontend/rag/**"];
+    const ragWriteSet = [`${layout.ragDir}/**`];
     const caseDraftWriteSet = [
-        "testcase/frontend/cases/FE-*.md",
-        "testcase/frontend/cases/index.md",
-        "testcase/frontend/cases/manifest.draft.json",
+        `${layout.casesDir}/FE-*.md`,
+        `${layout.casesDir}/index.md`,
+        `${layout.casesDir}/manifest.draft.json`,
     ];
     // The shell materializer alone owns the final manifest boundary.
-    const casesWriteSet = ["testcase/frontend/cases/**"];
-    const evidenceRoot = "testcase/frontend/evidence";
+    const casesWriteSet = [`${layout.casesDir}/**`];
+    const evidenceRoot = layout.evidenceDir;
     const declaredAcIdsLiteral = JSON.stringify(declaredAcIds);
     const maxCasesPerBatchLiteral = String(config.maxCasesPerBatch);
     const checklistScript = [
@@ -4802,6 +4915,8 @@ function buildFrontendTestHybridDag(sources) {
         "const caseIdRe=/^FE-[A-Za-z0-9][A-Za-z0-9-]*$/;",
         ,
         "const acIdRe=/^AC(?:-[A-Z0-9]+)+$/i;",
+        "const truncatedAcRe=/^AC-FE-[A-Z]+$/i;",
+        "const truncatedUndeclaredAcRe=/^(?:AC-\\d{3}|AC-FE-[A-Z]+)$/i;",
         "for(const c of manifest.cases){",
         " const id=c&&c.caseId||'?';",
         " if(typeof c.caseId!=='string'||!caseIdRe.test(c.caseId))issues.push({ruleId:'case-id-shape',caseId:id,detail:'caseId must be FE-<FEATURE>-<NNN>-<dimension>, never AC-FE-*'});",
@@ -4820,6 +4935,7 @@ function buildFrontendTestHybridDag(sources) {
         "   if(typeof ac!=='string'){issues.push({ruleId:'ac-id-shape',caseId:id,detail:String(ac)+' must look like AC-FE-001'});continue;}",
         "   if(/^FE-/i.test(ac)){issues.push({ruleId:'ac-id-is-case',caseId:id,detail:ac+' looks like caseId; acIds must be AC-*'});continue;}",
         "   if(!acIdRe.test(ac)){issues.push({ruleId:'ac-id-shape',caseId:id,detail:ac+' must look like AC-FE-001'});continue;}",
+        "   if(truncatedAcRe.test(ac)||(declaredAc.size===0&&truncatedUndeclaredAcRe.test(ac))){issues.push({ruleId:'ac-id-truncated',caseId:id,detail:ac+' is a truncated acceptance id (missing feature prefix or sequence number)'});continue;}",
         "   if(declaredAc.size>0&&!declaredAc.has(ac))issues.push({ruleId:'unknown-ac',caseId:id,detail:ac+' not in task sourceBinding.requirementIds'});",
         "  }",
         " }",
@@ -4851,6 +4967,8 @@ function buildFrontendTestHybridDag(sources) {
             `const declaredAc=new Set(${declaredAcIdsLiteral});`,
             "const seen=new Set(); const seenCasePath=new Set(); const seenEvidenceDir=new Set();",
             "const acIdRe=/^AC(?:-[A-Z0-9]+)+$/i;",
+            "const truncatedAcRe=/^AC-FE-[A-Z]+$/i;",
+            "const truncatedUndeclaredAcRe=/^(?:AC-\\d{3}|AC-FE-[A-Z]+)$/i;",
             "for(const c of manifest.cases){",
             " if(!c||typeof c.caseId!=='string'||!/^FE-[A-Za-z0-9][A-Za-z0-9-]*$/.test(c.caseId)) fail('case-id-shape','caseId must be FE-*, never AC-FE-*: '+String(c&&c.caseId));",
             " if(/^AC-/i.test(c.caseId)) fail('case-id-is-ac','caseId must not be an acceptance id: '+c.caseId);",
@@ -4858,7 +4976,7 @@ function buildFrontendTestHybridDag(sources) {
             " seen.add(c.caseId);",
             " if(typeof c.dimension!=='string'||!dims.has(c.dimension)) fail('invalid-dimension',String(c.dimension));",
             " if(!Array.isArray(c.acIds)||c.acIds.length===0||c.acIds.some(a=>typeof a!=='string'||!a.trim())) fail('ac-mapping','invalid acIds for '+c.caseId);",
-            " for(const ac of c.acIds){ if(!acIdRe.test(ac)) fail('ac-id-shape','acIds entry must be AC-* acceptance id, not caseId: '+ac); if(declaredAc.size>0&&!declaredAc.has(ac)) fail('unknown-ac',ac+' not in sourceBinding; repair generator input or AC list'); }",
+            " for(const ac of c.acIds){ if(!acIdRe.test(ac)) fail('ac-id-shape','acIds entry must be AC-* acceptance id, not caseId: '+ac); if(truncatedAcRe.test(ac)||(declaredAc.size===0&&truncatedUndeclaredAcRe.test(ac))) fail('ac-id-truncated','acIds entry is a truncated acceptance id (missing feature prefix or sequence number): '+ac); if(declaredAc.size>0&&!declaredAc.has(ac)) fail('unknown-ac',ac+' not in sourceBinding; repair generator input or AC list'); }",
             " c.casePath='testcase/frontend/cases/'+c.caseId+'.md';",
             " c.evidenceDir='testcase/frontend/evidence/'+c.caseId+'/';",
             " for(const k of ['casePath','evidenceDir']){ const v=c[k]; if(typeof v!=='string'||path.isAbsolute(v)||v.includes('..')) fail('unsafe-path',k+': '+String(v)); }",
@@ -4983,6 +5101,7 @@ function buildFrontendTestHybridDag(sources) {
             subtask_prompt: [
                 "Use skill playwright-cli-case-generator.",
                 "Read testcase/frontend/rag/standard-scenarios.v1.json and cover priority=must scenarios (or record GAP in coverage-map). Include ## 测试点 and ## 测试步骤 in each case.",
+                ...(uiAnchorsLedgerInstruction ? [uiAnchorsLedgerInstruction] : []),
                 "Read only testcase/frontend/rag/context.md, testcase/frontend/rag/coverage-map.md, and the draft case paths testcase/frontend/cases/FE-*.md, testcase/frontend/cases/index.md, and testcase/frontend/cases/manifest.draft.json. Write only those same draft paths. Do not write testcase/frontend/cases/manifest.json.",
                 "Generate Markdown cases, index.md and manifest.draft.json (schemaVersion 1; cases[] with caseId, casePath, dimension, acIds, evidenceDir).",
                 "HARD ID CONTRACT (do not confuse these):",
@@ -5142,7 +5261,7 @@ function buildFrontendTestHybridDag(sources) {
                 subtaskPromptTemplate: [
                     "Primary job: EXECUTE case {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session; do not use /new). playwright-cli-only: never bare Playwright CLI/API/test runner; no fallback.",
                     "Use the structured playwright_cli tool for every browser action. Do not request or search for bash. Do not execute raw shell commands. Translate each playwright-cli line in the case Markdown into one playwright_cli tool call ({command, args?, timeoutSeconds?}).",
-                    "1) Read the concrete baseUrl from testcase/frontend/rag/context.md; it has already passed the environment shell safety/reachability gate. Start browser ONLY via playwright_cli command=open with args [--browser=chrome, <that-concrete-baseUrl>] (default session only; no -s=). 2) Dynamic refs: eX/eY in case Markdown are documentation placeholders, never tool args. Immediately before every structured playwright_cli call that references an element, parse the current real eNN from the immediately preceding latest snapshot and pass only that real eNN; never send literal `eX`/`eY`. A new snapshot invalidates prior refs, so never reuse stale refs. File outputs are canonical: screenshot args [--filename, final.png] (or [e5, --filename, final.png] for a real target), PDF args [--filename, final.pdf], and snapshot writes a file only with [--filename, snapshot.txt]; snapshot without filename is response-only. Never use --path, --output, --file, or any output path as a positional target. Follow case steps with snapshot before element refs using only playwright_cli. A passed case requires this same child receipt order: successful open → successful find → controller post-execution cleanup. Only successful find is a meaningful assertion; snapshot, goto, screenshot, request/console, click/fill and other ordinary interactions cannot establish passed authority. 3) Only when preflight or playwright_cli tool explicitly fails may you write blocked evidence (blockedReason playwright-cli-unavailable | frontend-base-url-unreachable); never invent CLI-unavailable solely because bash is absent. 4) For U/D: enforce current-user ownership / create-or-mock-or-blocked; never mutate other users' data.",
+                    "1) Read the concrete baseUrl from testcase/frontend/rag/context.md; it has already passed the environment shell safety/reachability gate. Start browser ONLY via playwright_cli command=open with args [--browser=chrome, <that-concrete-baseUrl>] (default session only; no -s=). 2) Dynamic refs: eX/eY in case Markdown are documentation placeholders, never tool args. Immediately before every structured playwright_cli call that references an element, parse the current real eNN from the immediately preceding latest snapshot and pass only that real eNN; never send literal `eX`/`eY`. A new snapshot invalidates prior refs, so never reuse stale refs. File outputs are canonical: screenshot args [--filename, final.png] (or [e5, --filename, final.png] for a real target), PDF args [--filename, final.pdf], and snapshot writes a file only with [--filename, snapshot.txt]; snapshot without filename is response-only. Never use --path, --output, --file, or any output path as a positional target. Follow case steps with snapshot before element refs using only playwright_cli. A passed case requires this same child receipt order: successful open → successful find → controller post-execution cleanup. Only successful find is a meaningful assertion; snapshot, goto, screenshot, request/console, click/fill and other ordinary interactions cannot establish passed authority. 3) Only when preflight or playwright_cli tool explicitly fails may you write blocked evidence (blockedReason playwright-cli-unavailable | frontend-base-url-unreachable); never invent CLI-unavailable solely because bash is absent. Unique-control early stop: when an AC names a specific control that is absent from the first post-navigation snapshot after reaching the required state (and no setup-required gate appeared), do ONE find with the case's literal as evidence; if it returns 0 matches, record status=blocked with blockedReason unique-control-unavailable citing that single find - do NOT re-explore with alternative literals, repeated snapshots, navigation detours, or rerun loops. 4) For U/D: enforce current-user ownership / create-or-mock-or-blocked; never mutate other users' data.",
                     "Always write {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json with caseId={{case.caseId}}, status passed|failed|blocked, evidencePaths (relative under evidenceDir). blocked needs non-empty blockedReason. After writing, self-check the same contract; if self-check fails, rewrite both files as status=blocked blockedReason=invalid-evidence-shape (never leave missing/malformed evidence).",
                     "Business failed/blocked is a recorded result, not a node failure. Close browser via playwright_cli command=close. Return compact JSON (<=1200 chars): {caseId,status,evidencePaths,errorSummary,tokens}.",
                 ].join("\n\n"),
@@ -5165,7 +5284,7 @@ function buildFrontendTestHybridDag(sources) {
             "const manifestPath='testcase/frontend/cases/manifest.json';",
             "if(!fs.existsSync(manifestPath)){process.stdout.write(JSON.stringify({cases:[]}));process.exit(0);}",
             "const manifest=JSON.parse(fs.readFileSync(manifestPath,'utf8'));const cases=[];",
-            "for(const c of (manifest.cases||[])){const evidenceDir=(c.evidenceDir||('testcase/frontend/evidence/'+c.caseId+'/')).replace(/\\/+$/,'')+'/';const resultPath=path.join(evidenceDir,'case-result.json');const execPath=path.join(evidenceDir,'execution.md');let reason=null;let attempt=0;let missing=false;if(!fs.existsSync(resultPath)){missing=true;reason='missing-result-files';}else{try{const r=JSON.parse(fs.readFileSync(resultPath,'utf8'));attempt=Number(r.rerunAttempt||0)||0;if(r.status==='blocked')reason='blocked';if(!r.status){missing=true;reason='missing-result-files';}}catch(_){missing=true;reason='missing-result-files';}}if(!fs.existsSync(execPath)&&reason!=='blocked'){missing=true;reason=reason||'missing-result-files';}const should=(reason==='blocked'||missing)&&attempt<" + String(round) + ";if(should){cases.push({caseId:c.caseId,casePath:c.casePath||('testcase/frontend/cases/'+c.caseId+'.md'),evidenceDir,dimension:c.dimension||'core',acIds:c.acIds||[],rerunAttempt:attempt+1,reason:reason||'blocked'});}}",
+            "for(const c of (manifest.cases||[])){const evidenceDir=(c.evidenceDir||('testcase/frontend/evidence/'+c.caseId+'/')).replace(/\\/+$/,'')+'/';const resultPath=path.join(evidenceDir,'case-result.json');const execPath=path.join(evidenceDir,'execution.md');let reason=null;let attempt=0;let missing=false;if(!fs.existsSync(resultPath)){missing=true;reason='missing-result-files';}else{try{const r=JSON.parse(fs.readFileSync(resultPath,'utf8'));attempt=Number(r.rerunAttempt||0)||0;if(r.status==='blocked')reason='blocked';if(r.status==='failed')reason='failed-retry';if(!r.status){missing=true;reason='missing-result-files';}}catch(_){missing=true;reason='missing-result-files';}}if(!fs.existsSync(execPath)&&reason!=='blocked'){missing=true;reason=reason||'missing-result-files';}const should=(reason==='blocked'||reason==='failed-retry'||missing)&&attempt<" + String(round) + ";if(should){cases.push({caseId:c.caseId,casePath:c.casePath||('testcase/frontend/cases/'+c.caseId+'.md'),evidenceDir,dimension:c.dimension||'core',acIds:c.acIds||[],rerunAttempt:attempt+1,reason:reason||'blocked'});}}",
             `fs.mkdirSync('testcase/frontend/evidence',{recursive:true});fs.writeFileSync('testcase/frontend/evidence/${candidateArtifact}',JSON.stringify({schemaVersion:1,cases},null,2)+'\\n');process.stdout.write(JSON.stringify({cases}));`,
         ].join("");
         tasks.push({
@@ -5233,6 +5352,7 @@ function buildFrontendTestHybridDag(sources) {
                         "RERUN attempt {{case.rerunAttempt}} for {{case.caseId}} (reason={{case.reason}}). Rewrite the authoritative execution.md and case-result.json; its final status replaces the earlier case result.",
                         "Primary job: EXECUTE case {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session). Use structured playwright_cli only; headless open.",
                         "Read the concrete baseUrl from testcase/frontend/rag/context.md and start via playwright_cli command=open with args [--browser=chrome, <that-concrete-baseUrl>]. Passed requires open → find → cleanup receipts.",
+                        "Unique-control early stop: if the first post-navigation snapshot lacks the control an AC names (and no setup-required gate appeared), one find returning 0 matches is sufficient evidence - write status=blocked blockedReason unique-control-unavailable instead of exploratory retries.",
                         "Always write {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json with caseId, status, evidencePaths, rerunAttempt={{case.rerunAttempt}}. Write fixed sections `### 执行摘要` and `### 实际执行步骤` to execution.md when available.",
                     ].join("\n\n"),
                 },
@@ -5368,6 +5488,7 @@ function buildFrontendTestHybridDag(sources) {
         verifyStrategy: resolveDagVerifyStrategy(sources.taskConfig),
         tasks,
     };
+    applyFrontendTestLayoutToDagSpec(spec, layout);
     applyDefaultReadOnlyRetryPolicy(spec);
     parseDagSpec(spec);
     assertValidDagSpec(spec);

package/dist/workflows/dag/types.js

@@ -978,6 +978,18 @@ export const dagSpecSchema = z
         isDefault: z.boolean(),
     })
         .optional(),
+    /** Frozen frontend-test artifact layout; absent = historical testcase/frontend/ layout. */
+    frontendTestLayout: z
+        .object({
+        testRoot: z.string(),
+        ragDir: z.string(),
+        casesDir: z.string(),
+        evidenceDir: z.string(),
+        reportsDir: z.string(),
+        fixturesDir: z.string(),
+        isDefault: z.boolean(),
+    })
+        .optional(),
     /** Bound user shared-setup document (plan B); absent = no shared setup references expected. */
     backendTestSharedSetup: z
         .object({

package/dist/workflows/dag/validate.js

@@ -5,6 +5,7 @@ import { resolveRepairTaskForGate } from "./repair-artifact.js";
 import { topoSortToRanks } from "./topo.js";
 import { isSafeReadOnlyPiRetryCandidate, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "./retry-policy.js";
 import { isBackendTestCompletenessRetryCandidate } from "./backend-test-writer-completeness.js";
+import { defaultFrontendTestLayout, frontendTestLayoutFromSpec, } from "./frontend-test-layout.js";
 const GOVERNANCE_WARNING_TYPES = new Set([
     "read-only-missing-artifacts-forbidden",
     "read-only-prompt-mentions-artifact-writes",
@@ -680,22 +681,23 @@ function validateWriterOutcomePolicyTaskConfig(task, issues) {
         });
     }
 }
-function isFrontendEvidenceWriteSet(writeSet) {
+function isFrontendEvidenceWriteSet(writeSet, layout = defaultFrontendTestLayout()) {
     const entries = writeSet ?? [];
     if (entries.length === 0)
         return false;
+    const prefix = `${layout.evidenceDir}/`;
+    const glob = `${layout.evidenceDir}/**`;
     return entries.every((entry) => {
         const normalized = entry.trim().replace(/\\/g, "/").replace(/^\.\//, "");
-        return (normalized === "testcase/frontend/evidence/**" ||
-            normalized.startsWith("testcase/frontend/evidence/"));
+        return normalized === glob || normalized.startsWith(prefix);
     });
 }
-function isFrontendBrowserExecutorTask(task) {
+function isFrontendBrowserExecutorTask(task, layout = defaultFrontendTestLayout()) {
     const skills = task.skills ?? [];
     return (task.executor === "pi" &&
         task.toolProfile === "write" &&
         skills.includes("playwright-cli") &&
-        isFrontendEvidenceWriteSet(task.writeSet));
+        isFrontendEvidenceWriteSet(task.writeSet, layout));
 }
 function taskMentionsPlaywrightCliContract(task) {
     const prompt = `${task.subtask_prompt}\n${task.outputContract ?? ""}`;
@@ -707,10 +709,11 @@ function taskMentionsPlaywrightCliContract(task) {
  * - capability is granted without skill/prompt contract or outside evidence writeSet
  * - non-browser nodes receive command capability
  */
-function validateCommandPolicyTaskConfig(task, issues) {
+function validateCommandPolicyTaskConfig(task, issues, spec) {
+    const layout = frontendTestLayoutFromSpec(spec);
     const policy = resolveDagCommandPolicy(task.commandPolicy);
     const allowsPlaywright = dagCommandPolicyAllows(task.commandPolicy, "playwright-cli");
-    const isBrowserExecutor = isFrontendBrowserExecutorTask(task);
+    const isBrowserExecutor = isFrontendBrowserExecutorTask(task, layout);
     if (isBrowserExecutor && !allowsPlaywright) {
         issues.push({
             type: "invalid-command-policy",
@@ -741,10 +744,10 @@ function validateCommandPolicyTaskConfig(task, issues) {
                 message: `task ${task.id} playwright-cli command capability requires prompt/outputContract to reference playwright_cli`,
             });
         }
-        if (!isFrontendEvidenceWriteSet(task.writeSet)) {
+        if (!isFrontendEvidenceWriteSet(task.writeSet, layout)) {
             issues.push({
                 type: "invalid-command-policy",
-                message: `task ${task.id} playwright-cli command capability requires frontend evidence writeSet under testcase/frontend/evidence/`,
+                message: `task ${task.id} playwright-cli command capability requires frontend evidence writeSet under ${layout.evidenceDir}/`,
             });
         }
         if (task.toolProfile !== "write") {
@@ -755,7 +758,7 @@ function validateCommandPolicyTaskConfig(task, issues) {
         }
     }
 }
-function validateDynamicChildCommandPolicy(task, issues) {
+function validateDynamicChildCommandPolicy(task, issues, spec) {
     const expansion = task.dynamicExpansion;
     if (!expansion)
         return;
@@ -776,7 +779,7 @@ function validateDynamicChildCommandPolicy(task, issues) {
         writeSet: child.writeSet,
         outputContract: child.outputContract,
     };
-    validateCommandPolicyTaskConfig(synthetic, issues);
+    validateCommandPolicyTaskConfig(synthetic, issues, spec);
 }
 function validateDecisionGateTaskConfig(task, issues) {
     if (!task.decisionGate?.enabled) {
@@ -883,12 +886,13 @@ export function collectForbiddenExecutorIssues(spec, forbiddenExecutors) {
     }));
 }
 /** Revalidate a rendered dynamic child before it enters state or executes. */
-export function assertValidMaterializedDagTask(task) {
+export function assertValidMaterializedDagTask(task, parentSpec) {
     const issues = [];
-    // A minimal v2 carrier makes write-policy validation strict while avoiding
-    // unrelated parent graph/rank checks.  Dynamic templates are validated at
-    // init; this guards values introduced by {{item}} rendering.
-    const spec = { version: 2, tasks: [task] };
+    const spec = {
+        version: 2,
+        tasks: [task],
+        frontendTestLayout: parentSpec?.frontendTestLayout,
+    };
     validateTaskWritePolicy(task, spec, issues);
     validateShellTaskConfig(task, spec, issues);
     validateStaticTaskConfig(task, issues);
@@ -896,7 +900,7 @@ export function assertValidMaterializedDagTask(task) {
     validateRetryPolicyTaskConfig(task, issues);
     validateOutputProtocolTaskConfig(task, issues);
     validateWriterOutcomePolicyTaskConfig(task, issues);
-    validateCommandPolicyTaskConfig(task, issues);
+    validateCommandPolicyTaskConfig(task, issues, spec);
     if (issues.length > 0) {
         throw new Error(`invalid materialized dynamic child ${task.id}: ${issues.map((issue) => issue.message).join("; ")}`);
     }
@@ -952,8 +956,8 @@ export function validateDagSpec(spec) {
         validateRetryPolicyTaskConfig(task, issues);
         validateOutputProtocolTaskConfig(task, issues);
         validateWriterOutcomePolicyTaskConfig(task, issues);
-        validateCommandPolicyTaskConfig(task, issues);
-        validateDynamicChildCommandPolicy(task, issues);
+        validateCommandPolicyTaskConfig(task, issues, spec);
+        validateDynamicChildCommandPolicy(task, issues, spec);
         validateProjectGovernanceTaskConfig(task, spec, issues);
         validatePiExtensionsTaskConfig(task, issues);
         validateFailureAwareDependsOn(task, spec, issues);

package/docs/templates/frontend-test-case-checklist.md

@@ -15,7 +15,7 @@ LLM review (when `frontendTest.reviewMode=blocking`) must not invent blocking ru
 | `unknown-ac` | When task `sourceBinding.requirementIds` lists ACs, every `acIds` entry must be in that set |
 | `case-id-shape` | `caseId` matches `FE-<FEATURE>-<NNN>-...` (never `AC-FE-*`) |
 | `case-id-is-ac` | Do not use acceptance id as `caseId` / filename |
-| `case-path-mismatch` | `casePath === testcase/frontend/cases/{caseId}.md` |
+| `case-path-mismatch` | `casePath === {casesDir}/{caseId}.md`（默认 `testcase/frontend/cases/{caseId}.md`） |
 | `case-file-missing` | `casePath` exists |
 
 ## Tool guidance (non-blocking)
@@ -40,5 +40,5 @@ LLM review (when `frontendTest.reviewMode=blocking`) must not invent blocking ru
 
 ## Pipeline vs quality
 
-- **Pipeline acceptance**: final `testcase/frontend/reports/frontend-test-retrospect-*.md` exists after result materialize
+- **Pipeline acceptance**: final `{reportsDir}/frontend-test-retrospect-*.md` exists after result materialize (default `testcase/frontend/reports/`)
 - **Quality**: `frontend-test-result-v1.outcome=passed` with 0 blocked/failed (opt-in via `frontendTest.strictOutcomeGate`)

package/harness.json

@@ -82,9 +82,9 @@
   "executors": {
     "pi": {
       "description": "Pi 负责规划、评审、诊断；当 DAG toolProfile=write 时也可做有界写入。模型按复杂度三档配置，支持 provider/model 字符串或带 thinking 的对象；斜杠前为 Pi provider，后为 modelId，勿只写裸 modelId。",
-      "LOW": "wizard-local/minimax-m3",
-      "MED": "wizard-local/grok-4.6",
-      "HIGH": "wizard-local/gpt-5.6-sol"
+      "LOW": "deepseek/deepseek-v4-flash",
+      "MED": "deepseek/deepseek-v4-flash",
+      "HIGH": "deepseek/deepseek-v4-flash"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.39.0-next.30",
+  "version": "0.39.0-next.32",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",