@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0-beta.0

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

@@ -1,4 +1,5 @@
-import { access, readdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { access, readdir, readFile, realpath, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { assertValidDagSpec } from "./validate.js";
@@ -14,6 +15,7 @@ import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { materializeTaskReferenceDocs } from "../../task/source-references.js";
 import { resolveVerifyPreset } from "../../executors/shell-verification.js";
 import { resolveExecutorModelMatrices } from "../../executors/model-routing.js";
+import { normalizeTaskRequirementText, resolveTaskDagTemplateSelection, } from "./task-demand-routing.js";
 const REQUIREMENT_FILE = "需求.md";
 const CONSTRAINT_FILE = "执行约束.md";
 const REFERENCE_DIRECTORY = "references";
@@ -148,6 +150,425 @@ const STANDARD_GLOBAL_CONSTRAINTS = [
     "exclusive implementer nodes must use narrow, concrete writeSet paths; never keep ** or repo root",
     `Replace ${IMPLEMENT_WRITESET_PLACEHOLDER} with concrete paths before executing the implementation writer`,
 ];
+// ---------------------------------------------------------------------------
+// Frontend Mock capability discovery & mode resolution
+// ---------------------------------------------------------------------------
+/** Evidence-based check: does package.json contain a mock-related script? */
+async function packageJsonHasMockScript(repoRoot) {
+    try {
+        const raw = await readFile(path.join(repoRoot, "package.json"), "utf-8");
+        const pkg = JSON.parse(raw);
+        const scripts = pkg.scripts ?? {};
+        const mockScripts = Object.keys(scripts).filter((name) => name === "mock" ||
+            name.startsWith("mock:") ||
+            name.startsWith("dev:mock") ||
+            /mock/i.test(name));
+        const verifyCommands = mockScripts
+            .filter((name) => /(?:test|check|verify|contract)/i.test(name))
+            .map((name) => ({
+            label: `npm run ${name}`,
+            args: ["npm", "run", name],
+            cwd: repoRoot,
+        }));
+        return {
+            hasScript: mockScripts.length > 0,
+            scriptNames: mockScripts,
+            verifyCommands,
+        };
+    }
+    catch {
+        return { hasScript: false, scriptNames: [], verifyCommands: [] };
+    }
+}
+/** Check whether a direct (non-transitive) dependency exists in package.json. */
+async function hasDirectDependency(repoRoot, depName) {
+    try {
+        const raw = await readFile(path.join(repoRoot, "package.json"), "utf-8");
+        const pkg = JSON.parse(raw);
+        const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+        return depName in deps;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check whether handler/fixture/bootstrap files exist for known mock frameworks. */
+async function discoverMockHandlerFiles(repoRoot, serviceRoot) {
+    const exactCandidates = [
+        ...[
+            "src/mocks/handlers.ts",
+            "src/mocks/handlers.js",
+            "src/mocks/browser.ts",
+            "src/mocks/browser.js",
+            "src/mocks/server.ts",
+            "src/mocks/server.js",
+            "mocks/handlers.ts",
+            "mocks/handlers.js",
+            "mocks/browser.ts",
+            "mocks/browser.js",
+        ].map((candidatePath) => ({ framework: "msw", path: candidatePath })),
+        ...["db.json", "mock/db.json", "src/mock/db.json"].map((candidatePath) => ({ framework: "json-server", path: candidatePath })),
+    ];
+    const directoryCandidates = [
+        ...(serviceRoot ? [{ path: serviceRoot }] : []),
+        { framework: "mockjs", path: "src/mock" },
+        { framework: "mockjs", path: "mock" },
+        { framework: "msw", path: "src/mocks" },
+        { framework: "msw", path: "mocks" },
+        { framework: "mirage", path: "src/mirage" },
+        { framework: "mirage", path: "mirage" },
+    ];
+    const foundPaths = new Set();
+    let foundFramework;
+    for (const candidate of exactCandidates) {
+        try {
+            await access(path.join(repoRoot, candidate.path));
+            foundPaths.add(candidate.path);
+            foundFramework ??= candidate.framework;
+        }
+        catch {
+            // Exact candidate does not exist.
+        }
+    }
+    async function collectFiles(directory, relativeDirectory) {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (foundPaths.size >= 24)
+                return;
+            const absoluteEntry = path.join(directory, entry.name);
+            const relativeEntry = path.posix.join(relativeDirectory.replace(/\\/g, "/"), entry.name);
+            if (entry.isDirectory()) {
+                await collectFiles(absoluteEntry, relativeEntry);
+            }
+            else if (entry.isFile()) {
+                foundPaths.add(relativeEntry);
+            }
+        }
+    }
+    for (const candidate of directoryCandidates) {
+        const before = foundPaths.size;
+        await collectFiles(path.join(repoRoot, candidate.path), candidate.path);
+        if (foundPaths.size > before && candidate.framework) {
+            foundFramework ??= candidate.framework;
+        }
+    }
+    return { framework: foundFramework, paths: [...foundPaths].sort() };
+}
+async function discoverMockBootstrapImports(repoRoot) {
+    const entryCandidates = [
+        "src/main.ts",
+        "src/main.tsx",
+        "src/main.js",
+        "src/main.jsx",
+        "src/index.ts",
+        "src/index.tsx",
+        "src/index.js",
+        "src/index.jsx",
+        "src/setupTests.ts",
+        "src/setupTests.js",
+        "test/setup.ts",
+        "test/setup.js",
+    ];
+    const imports = [];
+    for (const candidate of entryCandidates) {
+        try {
+            const content = await readFile(path.join(repoRoot, candidate), "utf-8");
+            if (/(?:from\s*|import\s*)["'][^"']*(?:mock|msw|mirage)[^"']*["']/i.test(content)) {
+                imports.push(candidate);
+            }
+        }
+        catch {
+            // Candidate entry does not exist or is unreadable.
+        }
+    }
+    return imports;
+}
+/**
+ * Deterministic frontend Mock capability discovery.
+ *
+ * Strong evidence (at least one must be hit to judge "present"):
+ * 1. package.json mock script + corresponding config/entry
+ * 2. Direct dependency (MSW, Mock.js, Mirage, json-server, Vite Mock plugin) + handler files
+ * 3. Application bootstrap imports project mock files
+ * 4. Project specs explicitly define mock service root, handler dir, and startup method
+ *
+ * Anti-evidence (cannot alone judge "present"):
+ * - lockfile-only or transitive dependency
+ * - test variable named "mock"
+ * - fixtures without service registration
+ * - neighboring project mock services
+ * - model-directory-name guessing
+ */
+export async function discoverFrontendMockCapability(repoRoot, taskConfig) {
+    const safetyViolation = await frontendMockServiceRootSafetyViolation(repoRoot, taskConfig);
+    if (safetyViolation) {
+        return {
+            status: "ambiguous",
+            serviceRoot: taskConfig.frontendMock?.serviceRoot,
+            safetyViolation,
+            evidencePaths: [],
+            verifyCommands: [],
+            reasons: [safetyViolation],
+        };
+    }
+    const evidencePaths = [];
+    const reasons = [];
+    let framework;
+    let serviceRoot;
+    let strongEvidenceCount = 0;
+    let ambiguousSignals = 0;
+    // 1. Check package.json mock scripts
+    const scriptResult = await packageJsonHasMockScript(repoRoot);
+    if (scriptResult.hasScript) {
+        reasons.push(`package.json has mock scripts: ${scriptResult.scriptNames.join(", ")}`);
+        evidencePaths.push("package.json");
+        // A script alone is not strong evidence unless we also find config/entry
+    }
+    // 2. Check for direct mock framework dependencies
+    const mockDeps = ["msw", "mockjs", "miragejs", "json-server", "vite-plugin-mock"];
+    const foundDeps = [];
+    for (const dep of mockDeps) {
+        if (await hasDirectDependency(repoRoot, dep)) {
+            foundDeps.push(dep);
+            evidencePaths.push(`package.json (${dep})`);
+        }
+    }
+    // 3. Check for handler/fixture/bootstrap files
+    const serviceRootHint = taskConfig.frontendMock?.serviceRoot;
+    const handlerResult = await discoverMockHandlerFiles(repoRoot, serviceRootHint);
+    const bootstrapImports = await discoverMockBootstrapImports(repoRoot);
+    if (handlerResult.framework) {
+        framework = handlerResult.framework;
+    }
+    if (handlerResult.paths.length > 0) {
+        evidencePaths.push(...handlerResult.paths);
+        reasons.push(`Mock handler/fixture paths found: ${handlerResult.paths.join(", ")}`);
+    }
+    if (bootstrapImports.length > 0) {
+        evidencePaths.push(...bootstrapImports);
+        reasons.push(`Application/test bootstrap imports Mock code: ${bootstrapImports.join(", ")}`);
+    }
+    // Evaluate strong evidence
+    // Case: direct dep + handler files
+    if (foundDeps.length > 0 && handlerResult.paths.length > 0) {
+        strongEvidenceCount++;
+        reasons.push(`Direct mock dependency (${foundDeps.join(", ")}) with handler files`);
+    }
+    // Case: mock script in package.json + corresponding config/entry
+    if (scriptResult.hasScript && handlerResult.paths.length > 0) {
+        strongEvidenceCount++;
+        reasons.push("Mock scripts and handler files both present");
+    }
+    if (bootstrapImports.length > 0 && handlerResult.paths.length > 0) {
+        strongEvidenceCount++;
+        reasons.push("Application/test bootstrap and project Mock files both present");
+    }
+    // Case: project specs define mock service root
+    if (taskConfig.frontendMock?.serviceRoot && handlerResult.paths.length > 0) {
+        strongEvidenceCount++;
+        serviceRoot = taskConfig.frontendMock.serviceRoot;
+        reasons.push(`task config specifies serviceRoot=${serviceRoot}`);
+    }
+    // Handle ambiguous: some signals but not enough for "present"
+    if (strongEvidenceCount === 0 &&
+        (foundDeps.length > 0 ||
+            scriptResult.hasScript ||
+            handlerResult.paths.length > 0 ||
+            bootstrapImports.length > 0)) {
+        ambiguousSignals++;
+        if (foundDeps.length > 0 && handlerResult.paths.length === 0) {
+            reasons.push(`Mock dependency found (${foundDeps.join(", ")}) but no handler/bootstrap files detected`);
+        }
+        if (scriptResult.hasScript && handlerResult.paths.length === 0 && foundDeps.length === 0) {
+            reasons.push("Mock scripts exist but no handler files or direct mock dependencies found");
+        }
+    }
+    // Build verify commands from task config
+    const configuredVerifyCommands = (taskConfig.frontendMock?.verifyCommands ?? []).map((cmd) => ({
+        label: cmd.label,
+        args: ["bash", "-lc", cmd.command],
+        cwd: repoRoot,
+        timeoutMs: cmd.timeoutMs,
+    }));
+    const verifyCommands = [...configuredVerifyCommands, ...scriptResult.verifyCommands]
+        .filter((command, index, commands) => commands.findIndex((candidate) => candidate.label === command.label) === index);
+    if (strongEvidenceCount > 0) {
+        return {
+            status: "present",
+            framework,
+            serviceRoot: serviceRoot ?? taskConfig.frontendMock?.serviceRoot,
+            evidencePaths,
+            verifyCommands,
+            reasons,
+        };
+    }
+    if (ambiguousSignals > 0) {
+        return {
+            status: "ambiguous",
+            framework,
+            serviceRoot: taskConfig.frontendMock?.serviceRoot,
+            evidencePaths,
+            verifyCommands,
+            reasons,
+        };
+    }
+    return {
+        status: "absent",
+        evidencePaths,
+        verifyCommands,
+        reasons: ["No mock service evidence found in project"],
+    };
+}
+function patternStaticPrefix(pattern) {
+    const normalized = pattern.replace(/\\/g, "/").replace(/^\.\//, "");
+    const wildcard = normalized.search(/[?*]/);
+    return (wildcard >= 0 ? normalized.slice(0, wildcard) : normalized).replace(/\/+$/, "");
+}
+function frontendMockServiceRootAllowed(taskConfig) {
+    const serviceRoot = taskConfig.frontendMock?.serviceRoot;
+    if (!serviceRoot)
+        return true;
+    const normalized = serviceRoot.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (normalized === "." ||
+        normalized === ".." ||
+        normalized.startsWith("../") ||
+        path.isAbsolute(serviceRoot) ||
+        /[?*]/.test(normalized)) {
+        return false;
+    }
+    const allowed = taskConfig.allowedPaths.some((allowedPath) => pathMatchesPattern(normalized, allowedPath) ||
+        pathMatchesPattern(`${normalized}/_probe_`, allowedPath));
+    if (!allowed)
+        return false;
+    return !mergeForbiddenPaths(taskConfig).some((forbiddenPath) => {
+        const forbiddenPrefix = patternStaticPrefix(forbiddenPath);
+        return (pathMatchesPattern(normalized, forbiddenPath) ||
+            (forbiddenPrefix.length > 0 &&
+                pathMatchesPattern(forbiddenPrefix, normalized)));
+    });
+}
+async function frontendMockServiceRootSafetyViolation(repoRoot, taskConfig) {
+    const serviceRoot = taskConfig.frontendMock?.serviceRoot;
+    if (!serviceRoot)
+        return undefined;
+    if (!frontendMockServiceRootAllowed(taskConfig)) {
+        return `frontendMock.serviceRoot is outside allowedPaths or overlaps forbiddenPaths: ${serviceRoot}`;
+    }
+    try {
+        const [repoRealPath, serviceRealPath] = await Promise.all([
+            realpath(repoRoot),
+            realpath(path.resolve(repoRoot, serviceRoot)),
+        ]);
+        const relativeRealPath = path.relative(repoRealPath, serviceRealPath);
+        if (relativeRealPath === ".." ||
+            relativeRealPath.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relativeRealPath)) {
+            return `frontendMock.serviceRoot resolves outside the repository: ${serviceRoot}`;
+        }
+        const normalizedRealPath = relativeRealPath.split(path.sep).join("/") || ".";
+        if (!frontendMockServiceRootAllowed({
+            ...taskConfig,
+            frontendMock: {
+                ...(taskConfig.frontendMock ?? { policy: "auto", verifyCommands: [] }),
+                serviceRoot: normalizedRealPath,
+            },
+        })) {
+            return `frontendMock.serviceRoot resolves outside its allowed boundary: ${serviceRoot}`;
+        }
+    }
+    catch (error) {
+        // A missing configured root is capability absence, not a path escape. The
+        // discovery pass below will report it without traversing another location.
+        if (error.code !== "ENOENT") {
+            return `frontendMock.serviceRoot safety could not be verified: ${serviceRoot}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Heuristic: does the task have interface/async data dependencies?
+ *
+ * Checks (in priority order):
+ * 1. taskConfig.frontendMock.policy === "required"
+ * 2. Requirement references API docs, schemas, endpoints
+ * 3. Acceptance criteria mention requests, async data, or service states
+ * 4. Contract/scout confirmed existing API call chain (not available at generation time)
+ */
+export function hasApiDependency(sources) {
+    if (sources.taskConfig.frontendMock?.policy === "required") {
+        return true;
+    }
+    const requirement = normalizeTaskRequirementText(sources.requirementMarkdown)
+        .replace(/`[^`\n]*`/g, " ");
+    const dependencyPatterns = [
+        /(?:接口文档|接口定义|接口协议|后端接口|服务端接口|接口联调|请求|响应|远程数据|异步数据|数据获取|模拟接口|模拟数据)/,
+        /(?<![A-Za-z0-9_])API(?![A-Za-z0-9_])/i,
+        /\b(?:endpoint|request|response|fetch|axios|schema|mock|backend\s+api|server\s+api)\b/i,
+    ];
+    const negationPatterns = [
+        /(?:不涉及|无需|不需要|不依赖|不调用|不请求|没有|禁止|不得).{0,16}(?:接口|后端|服务端|远程数据|异步数据|API)/i,
+        /\b(?:no|without|does\s+not|do\s+not|must\s+not)\b.{0,24}\b(?:api|endpoint|request|backend|server)\b/i,
+    ];
+    return requirement
+        .split(/[。！？!?；;，,\r\n]+/)
+        .map((clause) => clause.trim())
+        .filter(Boolean)
+        .some((clause) => !negationPatterns.some((pattern) => pattern.test(clause)) &&
+        dependencyPatterns.some((pattern) => pattern.test(clause)));
+}
+/**
+ * Resolve frontend Mock mode from capability seed, task config, and interface dependency analysis.
+ *
+ * Decision matrix (from docs/design/frontend-mock-data-workflow.md):
+ *
+ * | 接口/异步数据依赖 | 既有 Mock 服务 | policy | 结果 |
+ * |---|---|---|---|
+ * | 无 | 任意 | auto | not-required |
+ * | 有 | present | auto | required |
+ * | 有 | present/absent/ambiguous | auto | required (strategy chooses a safe mechanism) |
+ * | 任意 | present | required | required |
+ * | 任意 | absent/ambiguous | required | blocked |
+ * | 任意 | 任意 | disabled | not-required (if spec allows) else blocked |
+ */
+export function resolveFrontendMockMode(capability, taskConfig, hasApiDep) {
+    const policy = taskConfig.frontendMock?.policy ?? "auto";
+    const hasDeterministicMockVerification = capability.verifyCommands.length > 0;
+    if (capability.safetyViolation || !frontendMockServiceRootAllowed(taskConfig)) {
+        return "blocked";
+    }
+    // disabled policy: must respect project mock rules (can't override spec)
+    if (policy === "disabled") {
+        // When disabled but the project spec mandates mock, it's blocked
+        if (capability.status === "present") {
+            // Project has mock service; disabled is an explicit override that still allows not-required
+            return "not-required";
+        }
+        return "not-required";
+    }
+    // required policy
+    if (policy === "required") {
+        if (capability.status === "present" && hasDeterministicMockVerification) {
+            return "required";
+        }
+        return "blocked";
+    }
+    // auto policy
+    if (!hasApiDep) {
+        return "not-required";
+    }
+    // In auto mode, capability discovery is evidence for the strategy node, not
+    // a final mechanism decision. Projects without a native Mock service may use
+    // an existing browser interception harness or a reversible request adapter.
+    // The deterministic strategy gate blocks before the writer when none can be
+    // verified by the DAG's frozen static/behavior entrypoints.
+    return "required";
+}
 function mapTaskComplexity(complexity) {
     if (complexity === "small")
         return "LOW";
@@ -312,6 +733,10 @@ function markdownVerifyCommand(repoRoot, command) {
         label: command,
     };
 }
+function isSupportedMarkdownVerifyCommand(command) {
+    return (/^(npm|pnpm|yarn|bun)\s+(run\s+)?[a-z0-9:_-]+(?:\s.*)?$/i.test(command) ||
+        /^(npx|pnpm\s+exec|yarn\s+exec|bunx)\s+(vitest|jest|playwright|cypress|tsc|eslint)(?:\s.*)?$/i.test(command));
+}
 function extractFrontendVerifyCommandsFromMarkdown(input) {
     if (!input.repoRoot)
         return { staticCommands: [], behaviorCommands: [] };
@@ -328,8 +753,7 @@ function extractFrontendVerifyCommandsFromMarkdown(input) {
         const codeSpanCommands = Array.from(bulletless.matchAll(/`([^`]+)`/g), (match) => match[1].trim());
         const candidates = codeSpanCommands.length > 0 ? codeSpanCommands : [bulletless];
         for (const candidate of candidates) {
-            if (/^(npm|pnpm|yarn|bun)\s+(run\s+)?[a-z0-9:_-]+(?:\s.*)?$/i.test(candidate) ||
-                /^(npx|pnpm\s+exec|yarn\s+exec|bunx)\s+(vitest|jest|playwright|cypress|tsc|eslint)(?:\s.*)?$/i.test(candidate)) {
+            if (isSupportedMarkdownVerifyCommand(candidate)) {
                 commands.add(candidate);
             }
         }
@@ -350,6 +774,26 @@ function extractFrontendVerifyCommandsFromMarkdown(input) {
     }
     return { staticCommands, behaviorCommands };
 }
+function extractFrontendMockVerifyCommandsFromMarkdown(input) {
+    const commands = [];
+    const markdown = [
+        input.requirementMarkdown,
+        input.constraintMarkdown ?? "",
+    ].join("\n");
+    for (const line of markdown.split(/\r?\n/)) {
+        if (!/(?:mock|模拟服务|接口桩)/i.test(line))
+            continue;
+        for (const match of line.matchAll(/`([^`]+)`/g)) {
+            const commandText = match[1].trim();
+            if (!isSupportedMarkdownVerifyCommand(commandText))
+                continue;
+            const command = markdownVerifyCommand(input.repoRoot, commandText);
+            if (command)
+                commands.push(command);
+        }
+    }
+    return commands.filter((command, index, all) => all.findIndex((candidate) => candidate.args.join("\0") === command.args.join("\0")) === index);
+}
 function chooseFrontendVerifyCommands(input) {
     if (input.parsedCommands.length > 0) {
         return { commands: input.parsedCommands, commandSource: "inline" };
@@ -411,6 +855,39 @@ function toTaskRelativeSourcePath(sources, absolutePath) {
         .relative(sources.taskDir, absolutePath)
         .replaceAll(path.sep, "/");
 }
+function extractExplicitRequirementIds(...markdownInputs) {
+    const ids = [];
+    const seen = new Set();
+    for (const markdown of markdownInputs) {
+        if (!markdown)
+            continue;
+        for (const match of markdown.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;
+}
+function buildDagSourceBinding(sources) {
+    const sourceEntries = [
+        { kind: "requirement", path: sources.requirementPath, markdown: sources.requirementMarkdown },
+        ...(sources.constraintMarkdown ? [{ kind: "constraint", path: sources.constraintPath, markdown: sources.constraintMarkdown }] : []),
+        ...(sources.referenceDocuments ?? []).map((reference) => ({ kind: "reference", path: reference.path, markdown: reference.markdown })),
+    ];
+    return {
+        schemaVersion: 1,
+        taskId: sources.taskId,
+        sources: sourceEntries.map((source) => ({
+            kind: source.kind,
+            path: toTaskRelativeSourcePath(sources, source.path),
+            sha256: createHash("sha256").update(source.markdown, "utf8").digest("hex"),
+        })),
+        requirementIds: extractExplicitRequirementIds(sources.requirementMarkdown, sources.constraintMarkdown, ...(sources.referenceDocuments ?? []).map((reference) => reference.markdown)),
+    };
+}
 function buildSourceContextBlock(sources) {
     const requirementRef = toTaskRelativeSourcePath(sources, sources.requirementPath);
     const requirementExcerpt = excerptMarkdown(sources.requirementMarkdown, {
@@ -535,7 +1012,7 @@ export async function loadTaskHybridSources(repoRoot, taskId) {
     catch (error) {
         throw new Error(`failed to load verification commands for task "${taskId}": ${error instanceof Error ? error.message : String(error)}`);
     }
-    return {
+    const sources = {
         taskId,
         repoRoot,
         taskDir: paths.taskDir,
@@ -551,6 +1028,26 @@ export async function loadTaskHybridSources(repoRoot, taskId) {
         verifyCommands,
         sddEmbeddedSkills: await probeRepoLocalSddSkills(repoRoot),
     };
+    return sources;
+}
+async function prepareFrontendMockSources(sources) {
+    const repoRoot = sources.repoRoot ?? process.cwd();
+    const capability = await discoverFrontendMockCapability(repoRoot, sources.taskConfig);
+    const sourceMockVerifyCommands = extractFrontendMockVerifyCommandsFromMarkdown({
+        repoRoot,
+        requirementMarkdown: sources.requirementMarkdown,
+        constraintMarkdown: sources.constraintMarkdown,
+    });
+    for (const command of sourceMockVerifyCommands) {
+        if (!capability.verifyCommands.some((existing) => existing.args.join("\0") === command.args.join("\0"))) {
+            capability.verifyCommands.push(command);
+        }
+    }
+    return {
+        ...sources,
+        frontendMockCapability: capability,
+        frontendMockMode: resolveFrontendMockMode(capability, sources.taskConfig, hasApiDependency(sources)),
+    };
 }
 function mergeFinalVerifyCommands(repoRoot, taskConfig, adapterCommands) {
     const taskCommands = taskConfig.verifyCommands.map((command) => ({
@@ -758,12 +1255,282 @@ export function buildStandardHybridDagFromTask(sources) {
     assertValidDagSpec(spec);
     return spec;
 }
+function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, fixedVerificationContext, readOnlyPaths, forbiddenPaths) {
+    return {
+        id: "frontend-mock-assess-pi",
+        depends_on: ["frontend-contract-pi", "frontend-scout-pi"],
+        role: "planner",
+        executor: "pi",
+        complexity: "MED",
+        writePolicy: "read-only",
+        allowedPaths: readOnlyPaths,
+        forbiddenPaths,
+        skills: FRONTEND_IMPLEMENTATION_SKILLS,
+        outputContract: "Plain Markdown whose first non-empty line is MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked, followed by Mock Decision, API Contract Evidence, Specification Evidence, Service Evidence, Backend Readiness, Selection Evidence, Endpoint / Fixture Matrix, Activation, Target Files, Production Safety, Verification Plan, Real Integration Gap, and Blocking Issues. No file writes.",
+        subtask_prompt: [
+            "Perform read-only Mock assessment and select one safe frontend data strategy.",
+            "The first non-empty line must be exactly one of: MOCK_STRATEGY: native, MOCK_STRATEGY: browser-intercept, MOCK_STRATEGY: request-adapter, MOCK_STRATEGY: not-needed, or MOCK_STRATEGY: blocked.",
+            "Prefer an existing native Mock facility. Use browser-intercept only with an existing browser/e2e harness. When no Mock exists but the API layer is writable, use request-adapter by adding a minimal reversible adapter/DI seam within the approved writeSet; the real adapter must remain the production default.",
+            "Select not-needed only with positive evidence that no remote API is involved, a stable real backend will be exercised, or existing fixtures already cover the contract without changes. not-needed still requires the fixed behavior entrypoint to exercise applicable real or no-remote behavior verification. When configured policy is required, not-needed is forbidden.",
+            "Configured policy disabled requests no Mock but cannot override project specifications; if an actually-read project rule requires Mock, select blocked.",
+            "",
+            "## Required Output Sections:",
+            "- Mock Decision: required | not-required | blocked (with reasoning)",
+            "- API Contract Evidence and Specification Evidence: actual Mock/API/schema specs read (paths + excerpts)",
+            "- Service Evidence: detected Mock framework, service root, handler/fixture/bootstrap paths",
+            "- Backend Readiness and Selection Evidence: why the selected mechanism is available and appropriate",
+            "- Endpoint / Fixture Matrix: method/path, source, request, success, empty, error, permission, consumer, fixture/evidence",
+            "- Activation and Target Files: explicit dev/test activation and authorized implementation paths",
+            "- Production Safety: how Mock stays off and the real request remains default",
+            "- Verification Plan: map the strategy to the fixed entrypoints below; do not propose replacement shell commands",
+            "- Real Integration Gap: what remains unproved until the real backend is ready",
+            "- Blocking Issues: any spec gaps, path violations, missing verify commands, or conflicts",
+            "",
+            "## Rules:",
+            "- Read project Mock/API/schema specifications before making any judgment.",
+            "- Do not infer Mock service from lockfile-only or transitive dependency evidence.",
+            "- Output MOCK_STRATEGY: blocked if capability evidence conflicts, contract fields are missing/conflicting, paths or dependencies are unauthorized, specs were not actually read, sources conflict, production-default-off cannot be proven, the API layer is not writable for a new adapter, or the frozen entrypoints cannot verify the selected strategy.",
+            "- Never comment out or replace the real request with inline data, hard-code Mock enablement, import test mocks from a production entrypoint, invent API fields, or place secrets/real user data in fixtures.",
+            "- Mock-backed behavior evidence proves the documented frontend contract only; it never proves real API integration.",
+            "",
+            "Read-only: do not modify repository files.",
+            fixedVerificationContext,
+            sourceContext,
+            mockContextBlock,
+        ].join("\n\n"),
+    };
+}
+function buildFrontendMockContractGateNode(mockMode, configuredPolicy, readOnlyPaths, forbiddenPaths) {
+    // A generation-time blocked decision is a hard fail-closed contract. Keep a
+    // syntactically valid, impossible verdict so the shell gate can never pass
+    // regardless of what the assessment model emits.
+    const acceptedStrategies = mockMode === "blocked"
+        ? ["MOCK_STRATEGY: __blocked__"]
+        : configuredPolicy === "disabled"
+            ? ["MOCK_STRATEGY: not-needed"]
+            : [
+                "MOCK_STRATEGY: native",
+                "MOCK_STRATEGY: browser-intercept",
+                "MOCK_STRATEGY: request-adapter",
+                ...(configuredPolicy !== "required"
+                    ? ["MOCK_STRATEGY: not-needed"]
+                    : []),
+            ];
+    return {
+        id: "frontend-mock-contract-gate-shell",
+        depends_on: ["frontend-mock-assess-pi"],
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "read-only",
+        allowedPaths: readOnlyPaths,
+        forbiddenPaths,
+        outputContract: "Deterministic Mock contract gate: exit 0 only when frontend-mock-assess-pi selects an allowed non-blocked strategy. Does not authorize code writes.",
+        subtask_prompt: "Deterministic gate: block plan/design/implement when frontend-mock-assess-pi selected blocked, selected not-needed under explicit policy=required, or emitted malformed output. Failure route: ContractMismatch.",
+        shell: {
+            commands: [],
+            verdictGate: {
+                fromNodeId: "frontend-mock-assess-pi",
+                accept: acceptedStrategies,
+                label: "frontend mock contract",
+                lineMode: "first-non-empty",
+            },
+            cwd: ".",
+            timeoutMs: 60000,
+        },
+    };
+}
+function buildFrontendMockVerifyNode(sources, implementId, readOnlyPaths, forbiddenPaths) {
+    const capability = sources.frontendMockCapability;
+    const taskConfig = sources.taskConfig;
+    // Collect verify commands from task config, capability seed, and manifest
+    const verifyCommands = [];
+    // 1. Task config commands (highest priority)
+    for (const cmd of taskConfig.frontendMock?.verifyCommands ?? []) {
+        verifyCommands.push({
+            label: cmd.label,
+            args: ["bash", "-lc", cmd.command],
+            cwd: sources.repoRoot ?? ".",
+            timeoutMs: cmd.timeoutMs,
+        });
+    }
+    // 2. Capability seed commands (from discovery)
+    if (capability) {
+        for (const cmd of capability.verifyCommands) {
+            if (!verifyCommands.some((existing) => existing.label === cmd.label)) {
+                verifyCommands.push(cmd);
+            }
+        }
+    }
+    // Fail closed: no commands = no verify shell
+    const commands = verifyCommands.length > 0
+        ? buildVerifyShellCommands({
+            repoRoot: sources.repoRoot ?? ".",
+            commands: verifyCommands,
+            fallbackCommands: [],
+        })
+        : [];
+    return {
+        id: "frontend-mock-verify-shell",
+        depends_on: [implementId],
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "read-only",
+        allowedPaths: readOnlyPaths,
+        forbiddenPaths,
+        outputContract: "Archived shell stdout/stderr with exit codes for deterministic Mock-specific verification; no worktree writes.",
+        subtask_prompt: "Run deterministic Mock-specific verification (handler loading, endpoint matrix, fixture consumption, production boundary). Commands are frozen from generation-time trusted sources only.",
+        shell: {
+            commands,
+            verifyEvidence: buildVerifyEvidence({
+                phase: "intermediate",
+                quota: "full",
+                commandSource: commands.length > 0 ? "inline" : "adapter",
+                commands: verifyCommands.length > 0 ? verifyCommands : undefined,
+                fallbackCommands: [],
+            }),
+            cwd: ".",
+            timeoutMs: 300000,
+        },
+    };
+}
+function buildBlockedFrontendMockDag(sources, sourceContext, readOnlyPaths, forbiddenPaths, globalConstraints) {
+    const { taskConfig } = sources;
+    const mockContextBlock = resolveFrontendMockContextBlock(sources);
+    const spec = {
+        version: 3,
+        title: `Frontend implementation DAG (BLOCKED Mock): ${taskConfig.title}`,
+        runtimeContract: GENERATED_DAG_RUNTIME_CONTRACT,
+        outputLanguage: sources.outputLanguage ?? DEFAULT_DAG_OUTPUT_LANGUAGE,
+        objective: extractObjective(sources.requirementMarkdown, taskConfig.title),
+        successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
+        globalConstraints: [
+            ...globalConstraints,
+            "Mock contract is BLOCKED: writer nodes must not be reachable. Resolve blocking issues and re-generate DAG.",
+            "Do not execute any write, verify, or closeout nodes. The DAG ends at the Mock contract gate.",
+        ],
+        defaults: {
+            ...FRONTEND_DEFAULTS,
+            contextProfile: taskConfig.contextProfile,
+        },
+        skillsByRole: FRONTEND_SKILLS_BY_ROLE,
+        executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
+        tasks: [
+            {
+                id: "frontend-contract-pi",
+                depends_on: [],
+                role: "planner",
+                executor: "pi",
+                complexity: "MED",
+                writePolicy: "read-only",
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                skills: FRONTEND_IMPLEMENTATION_SKILLS,
+                outputContract: "Markdown contract with Scope, Non-goals, Acceptance Criteria, UI States, Target Runtime Environment, Risks, and Verification Expectations. No file writes.",
+                subtask_prompt: [
+                    "Read task source and produce a concise frontend implementation contract.",
+                    "Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations.",
+                    "Read-only: do not modify code, docs, artifacts, or repository files.",
+                    sourceContext,
+                ].join("\n\n"),
+            },
+            {
+                id: "frontend-scout-pi",
+                depends_on: ["frontend-contract-pi"],
+                role: "scout",
+                executor: "pi",
+                complexity: mapTaskComplexity(taskConfig.complexity),
+                writePolicy: "read-only",
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                skills: FRONTEND_IMPLEMENTATION_SKILLS,
+                outputContract: "Markdown scout report covering frontend stack, routes, components, styling system, existing design conventions, state/data flow, test entry points, reuse opportunities, and risks. No file writes.",
+                subtask_prompt: [
+                    "Inspect frontend code, routing, components, styles, package scripts, and tests.",
+                    "Return code and design observations, existing reuse opportunities, and verification entry points.",
+                    "Read-only: do not modify repository files.",
+                    sourceContext,
+                ].join("\n\n"),
+            },
+            buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, "No verification entrypoints were materialized because the generation-time Mock contract is blocked.", readOnlyPaths, forbiddenPaths),
+            buildFrontendMockContractGateNode("blocked", taskConfig.frontendMock?.policy ?? "auto", readOnlyPaths, forbiddenPaths),
+        ],
+    };
+    applyDefaultReadOnlyRetryPolicy(spec);
+    parseDagSpec(spec);
+    assertValidDagSpec(spec);
+    return spec;
+}
+function resolveFrontendMockContextBlock(sources) {
+    const capability = sources.frontendMockCapability;
+    const mode = sources.frontendMockMode ?? "not-required";
+    if (!capability)
+        return "";
+    const parts = [
+        "## Frontend Mock Context",
+        "",
+        `Configured Policy: ${sources.taskConfig.frontendMock?.policy ?? "auto"}`,
+        `Mock Decision: ${mode}`,
+        `Capability Status: ${capability.status}`,
+    ];
+    if (capability.framework) {
+        parts.push(`Detected Framework: ${capability.framework}`);
+    }
+    if (capability.serviceRoot) {
+        parts.push(`Service Root: ${capability.serviceRoot}`);
+    }
+    if (capability.evidencePaths.length > 0) {
+        parts.push(`Evidence Paths: ${capability.evidencePaths.join(", ")}`);
+    }
+    if (capability.verifyCommands.length > 0) {
+        parts.push(`Frozen Mock Verify Commands: ${capability.verifyCommands
+            .map((command) => command.label)
+            .join(", ")}`);
+    }
+    if (capability.safetyViolation) {
+        parts.push(`Safety Violation: ${capability.safetyViolation}`);
+    }
+    if (capability.reasons.length > 0) {
+        parts.push(`Reasons: ${capability.reasons.join("; ")}`);
+    }
+    if (mode === "required") {
+        parts.push("Mock-backed frontend verification is required. Prefer the detected native service; otherwise the assessment may select an existing browser interception harness or reversible request adapter. Any handler, fixture, adapter, and UI changes stay in the single frontend-implement-pi writeSet.");
+    }
+    if (mode === "not-required") {
+        parts.push("Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed only positively, or select a safe Mock strategy if an API dependency is confirmed.");
+    }
+    if (mode === "blocked") {
+        parts.push("Mock contract is blocked. The DAG must stop before any write node executes.");
+    }
+    return parts.join("\n");
+}
 function buildFrontendHybridDagFromTask(sources) {
     const { taskConfig } = sources;
+    const mockCapability = sources.frontendMockCapability ?? {
+        status: "absent",
+        evidencePaths: [],
+        verifyCommands: [],
+        reasons: ["Frontend Mock capability was not precomputed; assessment must verify repository evidence."],
+    };
+    const mockMode = sources.frontendMockMode ??
+        resolveFrontendMockMode(mockCapability, taskConfig, hasApiDependency(sources));
+    const frontendSources = {
+        ...sources,
+        frontendMockCapability: mockCapability,
+        frontendMockMode: mockMode,
+    };
     const forbiddenPaths = mergeForbiddenPaths(taskConfig);
     const implementPaths = resolveImplementPaths(taskConfig);
     const implementId = frontendImplementationNodeId();
     const sourceContext = buildSourceContextBlock(sources);
+    const mockContextBlock = resolveFrontendMockContextBlock(frontendSources);
+    const hasMockVerifyCommands = (taskConfig.frontendMock?.verifyCommands.length ?? 0) > 0 ||
+        mockCapability.verifyCommands.length > 0;
+    const requirementIds = buildDagSourceBinding(sources).requirementIds;
+    const requirementCoverageInstruction = requirementIds.length > 0
+        ? `Include a Requirement Coverage section that lists every exact source identifier: ${requirementIds.join(", ")}. Preserve each identifier verbatim and map it to concrete implementation and verification steps.`
+        : "";
     const strategy = resolveDagVerifyStrategy(taskConfig);
     const readOnlyPaths = taskConfig.allowedPaths.length > 0 ? taskConfig.allowedPaths : ["**"];
     const behaviorPaths = deriveFrontendBehaviorPaths(taskConfig);
@@ -777,9 +1544,16 @@ function buildFrontendHybridDagFromTask(sources) {
         "Final design gate pass is the only authorization for frontend implementation writes.",
         "Plan revision remains read-only and never edits business code.",
         "Design revision failures route to replan-and-rerun, never dev-fix.",
+        "Frontend planning must consume the read-only Mock assessment strategy produced after scouting; MOCK_STRATEGY: blocked must not pass the deterministic Mock contract gate.",
+        "Mock implementations must preserve the real request path as the default, require explicit test/dev activation, and never rely on commenting out the real request.",
+        "Mock-backed behavior evidence proves only the documented frontend contract, never real API integration.",
         "frontend-implementation DAGs must complete deterministic static verification and behavior verification before final review.",
         "frontend review must block closeout unless review verdict is exactly VERDICT: pass.",
     ];
+    // Guard: blocked mode — generate assessment-only DAG with no writer reachable
+    if (mockMode === "blocked") {
+        return buildBlockedFrontendMockDag(frontendSources, sourceContext, readOnlyPaths, forbiddenPaths, globalConstraints);
+    }
     const staticFallbackCommands = ["npm run typecheck", "npm run build"];
     const behaviorFallbackCommands = ["npm test"];
     const parsedFrontendVerifyCommands = extractFrontendVerifyCommandsFromMarkdown({
@@ -795,6 +1569,39 @@ function buildFrontendHybridDagFromTask(sources) {
         parsedCommands: parsedFrontendVerifyCommands.behaviorCommands,
         adapterCommands: sources.verifyCommands?.final,
     });
+    const staticShellCommands = buildVerifyShellCommands({
+        repoRoot: sources.repoRoot,
+        commands: staticVerifyCommands.commands,
+        fallbackCommands: staticFallbackCommands,
+    });
+    const behaviorShellCommands = buildVerifyShellCommands({
+        repoRoot: sources.repoRoot,
+        commands: behaviorVerifyCommands.commands,
+        fallbackCommands: behaviorFallbackCommands,
+    });
+    const staticVerifyEvidence = buildVerifyEvidence({
+        phase: "intermediate",
+        quota: strategy.intermediateQuota ?? "full",
+        commandSource: staticVerifyCommands.commandSource,
+        commands: staticVerifyCommands.commands,
+        fallbackCommands: staticFallbackCommands,
+    });
+    const behaviorVerifyEvidence = buildVerifyEvidence({
+        phase: "final",
+        quota: "full",
+        commandSource: behaviorVerifyCommands.commandSource,
+        commands: behaviorVerifyCommands.commands,
+        fallbackCommands: behaviorFallbackCommands,
+        finalFullRequired: true,
+    });
+    const fixedVerificationContext = [
+        "## Fixed frontend verification entrypoints",
+        "These shell entrypoints are fixed at DAG generation and are the only commands the static and behavior shell nodes execute. A strategy or plan may add tests behind an existing entrypoint inside writeSet, but must not invent or replace commands or assume subtask_prompt executes a command.",
+        `- Static command source: ${staticVerifyEvidence.commandSource}`,
+        ...staticVerifyEvidence.commandLabels.map((command) => `  - ${JSON.stringify(command)}`),
+        `- Behavior command source: ${behaviorVerifyEvidence.commandSource}`,
+        ...behaviorVerifyEvidence.commandLabels.map((command) => `  - ${JSON.stringify(command)}`),
+    ].join("\n");
     const spec = {
         version: 3,
         title: `Frontend implementation DAG: ${taskConfig.title}`,
@@ -846,9 +1653,17 @@ function buildFrontendHybridDagFromTask(sources) {
                     sourceContext,
                 ].join("\n\n"),
             },
+            // Mock assessment is always read-only and runs before planning.
+            buildFrontendMockAssessNode(frontendSources, sourceContext, mockContextBlock, fixedVerificationContext, readOnlyPaths, forbiddenPaths),
+            buildFrontendMockContractGateNode(mockMode, taskConfig.frontendMock?.policy ?? "auto", readOnlyPaths, forbiddenPaths),
             {
                 id: "frontend-plan-pi",
-                depends_on: ["frontend-scout-pi"],
+                depends_on: [
+                    "frontend-contract-pi",
+                    "frontend-scout-pi",
+                    "frontend-mock-assess-pi",
+                    "frontend-mock-contract-gate-shell",
+                ],
                 role: "planner",
                 executor: "pi",
                 complexity: "MED",
@@ -856,17 +1671,21 @@ function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "Markdown implementation plan with Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Dependency Policy, Verification Plan, and Residual Risks. No file writes.",
+                outputContract: "Markdown implementation plan with Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks. No file writes.",
                 subtask_prompt: [
-                    "Based on frontend-contract-pi and frontend-scout-pi, return a minimal frontend implementation plan.",
-                    "Include ordered steps, target files, UI state handling, styling/component strategy, interaction notes, dependency policy, and deterministic verification commands.",
+                    "Based on frontend-contract-pi, frontend-scout-pi, and the gated frontend-mock-assess-pi strategy, return a minimal frontend implementation plan.",
+                    "Carry the selected Mock / API strategy, endpoint/fixture mapping, explicit activation, production-default-off rule, verification commands, and Real Integration Gap into the plan.",
+                    "Include ordered steps, target files, UI state handling, styling/component strategy, interaction notes, Mock/API strategy, dependency policy, deterministic verification entrypoints, and residual risks. Use only the fixed entrypoints below; implementation may add tests behind them but cannot replace them.",
+                    requirementCoverageInstruction,
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
+                    fixedVerificationContext,
                     sourceContext,
+                    mockContextBlock,
                 ].join("\n\n"),
             },
             {
                 id: "frontend-design-gate-pi",
-                depends_on: ["frontend-plan-pi"],
+                depends_on: ["frontend-plan-pi", "frontend-mock-assess-pi"],
                 role: "reviewer",
                 executor: "pi",
                 complexity: "MED",
@@ -878,8 +1697,10 @@ function buildFrontendHybridDagFromTask(sources) {
                 subtask_prompt: [
                     "Audit the frontend plan before implementation.",
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
-                    "Request revision for missing applicable UI states, unsupported dependency additions, design-system drift without reason, weak interaction coverage, broad scope, or missing deterministic verification commands.",
+                    "Request revision when the Mock strategy is MOCK_STRATEGY: blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for the selected strategy. Mock strategies require Mock-backed evidence; not-needed requires applicable real or no-remote behavior evidence.",
+                    "Also request revision for missing applicable UI states, unsupported dependency additions, design-system drift without reason, weak interaction coverage, broad scope, inline fake data, schema drift, or missing deterministic verification commands.",
                     "Read-only: do not modify repository files.",
+                    fixedVerificationContext,
                     sourceContext,
                 ].join("\n\n"),
             },
@@ -908,7 +1729,12 @@ function buildFrontendHybridDagFromTask(sources) {
             },
             {
                 id: "frontend-plan-revision-pi",
-                depends_on: ["frontend-first-design-gate-shell", "frontend-plan-pi", "frontend-design-gate-pi"],
+                depends_on: [
+                    "frontend-first-design-gate-shell",
+                    "frontend-plan-pi",
+                    "frontend-design-gate-pi",
+                    "frontend-mock-assess-pi",
+                ],
                 role: "planner",
                 executor: "pi",
                 complexity: "MED",
@@ -916,22 +1742,49 @@ function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "Markdown revision plan (pass case: first line PASS_NO_REVISION_NEEDED with confirmation of original plan; request-revision case: complete revised implementation plan with corrections from design findings). No file writes.",
+                outputContract: "Markdown revision plan (pass case: first line PASS_NO_REVISION_NEEDED with Requirement Coverage confirmation; request-revision case: complete revised implementation plan with corrections from design findings and Requirement Coverage). No file writes.",
                 subtask_prompt: [
                     "Consume frontend-plan-pi (original plan) and frontend-design-gate-pi (first design review findings).",
                     "If the first design gate passed (VERDICT: pass from frontend-design-gate-pi), output exactly:",
                     "PASS_NO_REVISION_NEEDED",
                     "The original plan from frontend-plan-pi is confirmed and does not require changes.",
+                    "Then reproduce a complete Requirement Coverage section containing every explicit REQ-/BR-/AC- identifier from the authoritative task sources so this node is the single effective-plan evidence source for the deterministic coverage gate.",
                     "",
                     "If the first design gate requested revision (VERDICT: request-revision), produce a complete revised implementation plan that addresses every Required Plan Correction from the design findings.",
-                    "The revised plan must include Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Dependency Policy, Verification Plan, and Residual Risks.",
+                    "The revised plan must include Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks.",
+                    requirementCoverageInstruction,
+                    "Do not turn MOCK_STRATEGY: blocked into an implementable strategy without new repository or contract evidence that resolves every blocker.",
                     "Read-only: do not modify code, docs, artifacts, or repository files. This node revises the plan only.",
                     sourceContext,
                 ].join("\n\n"),
             },
+            ...(requirementIds.length > 0 ? [{
+                    id: "frontend-requirement-coverage-shell",
+                    depends_on: ["frontend-plan-revision-pi"],
+                    role: "verifier",
+                    executor: "shell",
+                    complexity: "LOW",
+                    writePolicy: "read-only",
+                    allowedPaths: readOnlyPaths,
+                    forbiddenPaths,
+                    outputContract: "Deterministic current-run evidence that the original or revised frontend plan retains every explicit REQ-/BR-/AC- identifier from the bound task sources.",
+                    subtask_prompt: "Block final design review when the current run's plan facts omit any explicit requirement identifier from the authoritative task sources.",
+                    shell: {
+                        commands: [],
+                        requirementCoverageGate: { fromNodeIds: ["frontend-plan-revision-pi"], requiredIds: requirementIds, label: "frontend requirement coverage" },
+                        cwd: ".",
+                        timeoutMs: 60000,
+                    },
+                }] : []),
             {
                 id: "frontend-final-design-review-pi",
-                depends_on: ["frontend-plan-revision-pi"],
+                depends_on: [
+                    "frontend-plan-revision-pi",
+                    "frontend-plan-pi",
+                    "frontend-design-gate-pi",
+                    "frontend-mock-assess-pi",
+                    ...(requirementIds.length > 0 ? ["frontend-requirement-coverage-shell"] : []),
+                ],
                 role: "reviewer",
                 executor: "pi",
                 complexity: "MED",
@@ -945,8 +1798,11 @@ function buildFrontendHybridDagFromTask(sources) {
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
                     "If frontend-plan-revision-pi returned PASS_NO_REVISION_NEEDED, confirm the original plan against all design constraints and task requirements. Re-verify that all applicable UI states are covered, dependencies are authorized, and deterministic verification commands are present.",
                     "If frontend-plan-revision-pi revised the plan, verify that every Required Plan Correction from the first design review has been fully addressed.",
+                    "Recheck the selected Mock / API strategy, contract-to-fixture mapping, authorized paths/dependencies, explicit activation, production-default-off behavior, behavior verification, and Real Integration Gap. MOCK_STRATEGY: blocked cannot receive VERDICT: pass.",
+                    "The frontend requirement coverage gate has verified that every explicit REQ-/BR-/AC- identifier remains present in the current-run plan evidence; review the mapped behavior rather than accepting identifier presence alone.",
                     "Request revision if any design gap remains, if corrections are incomplete, or if the revised plan introduces new unaddressed issues.",
                     "Read-only: do not modify repository files.",
+                    fixedVerificationContext,
                     sourceContext,
                 ].join("\n\n"),
             },
@@ -975,13 +1831,17 @@ function buildFrontendHybridDagFromTask(sources) {
             },
             {
                 id: implementId,
-                depends_on: ["frontend-final-design-gate-shell", "frontend-plan-revision-pi", "frontend-final-design-review-pi"],
+                depends_on: [
+                    "frontend-final-design-gate-shell",
+                    "frontend-plan-revision-pi",
+                    "frontend-final-design-review-pi",
+                    "frontend-plan-pi",
+                    "frontend-mock-assess-pi",
+                ],
                 role: "implementer",
                 executor: "pi",
                 toolProfile: "write",
-                complexity: taskConfig.complexity === "large"
-                    ? "HIGH"
-                    : "MED",
+                complexity: resolveWriterComplexity(taskConfig),
                 writePolicy: "exclusive",
                 writeSet: implementPaths.writeSet,
                 allowedPaths: implementPaths.allowedPaths,
@@ -990,14 +1850,25 @@ function buildFrontendHybridDagFromTask(sources) {
                 outputContract: "Markdown summary with Changed Files, Implemented Behavior, UI States Covered, Styling / Component Notes, Verification Attempted, and Residual Risks.",
                 subtask_prompt: [
                     "Implement the final approved frontend plan (from frontend-plan-revision-pi) with minimal focused changes.",
+                    "Implement only the approved Mock strategy from frontend-mock-assess-pi as carried through the approved plan. Preserve the real request path as the default, require explicit test/dev activation, and never comment out or replace the real request with inline data.",
                     "The frontend-final-design-review-pi verdict confirmed the plan is ready. Stay within writeSet and preserve unrelated files.",
+                    "For native, browser-intercept, or request-adapter, implement contract-aligned fixtures/states and a dev/test-only activation boundary in this same writer. For not-needed, do not add Mock files or a framework and state the positive reason.",
                     "Do not write root artifacts/** unless explicitly included in writeSet.",
+                    writerDeliveryContract(taskConfig),
                     sourceContext,
-                ].join("\n\n"),
+                    mockContextBlock,
+                ].filter((value) => Boolean(value)).join("\n\n"),
             },
+            // Optional dedicated Mock verification exists only when trusted commands
+            // were frozen at generation time. Behavior verification remains required.
+            ...(mockMode === "required" && hasMockVerifyCommands
+                ? [buildFrontendMockVerifyNode(frontendSources, implementId, readOnlyPaths, forbiddenPaths)]
+                : []),
             {
                 id: "frontend-static-verify-shell",
-                depends_on: [implementId],
+                depends_on: mockMode === "required" && hasMockVerifyCommands
+                    ? ["frontend-mock-verify-shell"]
+                    : [implementId],
                 role: "verifier",
                 executor: "shell",
                 complexity: "LOW",
@@ -1005,20 +1876,10 @@ function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 outputContract: "Archived shell stdout/stderr with exit codes for deterministic static verification; no worktree writes.",
-                subtask_prompt: "Run deterministic static verification for the frontend implementation.",
+                subtask_prompt: "Run deterministic static verification for the frontend implementation, including a production/default-real-path build with Mock activation off when Mock applies. Report only what the commands actually exercise.",
                 shell: {
-                    commands: buildVerifyShellCommands({
-                        repoRoot: sources.repoRoot,
-                        commands: staticVerifyCommands.commands,
-                        fallbackCommands: staticFallbackCommands,
-                    }),
-                    verifyEvidence: buildVerifyEvidence({
-                        phase: "intermediate",
-                        quota: strategy.intermediateQuota ?? "full",
-                        commandSource: staticVerifyCommands.commandSource,
-                        commands: staticVerifyCommands.commands,
-                        fallbackCommands: staticFallbackCommands,
-                    }),
+                    commands: staticShellCommands,
+                    verifyEvidence: staticVerifyEvidence,
                     cwd: ".",
                     timeoutMs: 300000,
                 },
@@ -1033,28 +1894,29 @@ function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: behaviorPaths,
                 forbiddenPaths,
                 outputContract: "Archived shell stdout/stderr with exit codes for deterministic behavior verification; no worktree writes.",
-                subtask_prompt: "Run deterministic behavior verification for frontend flows, states, and integration points.",
+                subtask_prompt: "Run the fixed deterministic behavior entrypoints for the selected strategy. For native, browser-intercept, or request-adapter, cover the approved Mock activation and applicable success/loading/empty/error states; for not-needed, exercise applicable real or no-remote behavior. Report only what the commands actually exercise.",
                 shell: {
-                    commands: buildVerifyShellCommands({
-                        repoRoot: sources.repoRoot,
-                        commands: behaviorVerifyCommands.commands,
-                        fallbackCommands: behaviorFallbackCommands,
-                    }),
-                    verifyEvidence: buildVerifyEvidence({
-                        phase: "final",
-                        quota: "full",
-                        commandSource: behaviorVerifyCommands.commandSource,
-                        commands: behaviorVerifyCommands.commands,
-                        fallbackCommands: behaviorFallbackCommands,
-                        finalFullRequired: true,
-                    }),
+                    commands: behaviorShellCommands,
+                    verifyEvidence: behaviorVerifyEvidence,
                     cwd: ".",
                     timeoutMs: 300000,
                 },
             },
             {
                 id: "frontend-review-pi",
-                depends_on: ["frontend-behavior-verify-shell"],
+                depends_on: [
+                    "frontend-static-verify-shell",
+                    "frontend-behavior-verify-shell",
+                    implementId,
+                    "frontend-contract-pi",
+                    "frontend-plan-pi",
+                    "frontend-plan-revision-pi",
+                    "frontend-final-design-review-pi",
+                    "frontend-mock-assess-pi",
+                    ...(mockMode === "required" && hasMockVerifyCommands
+                        ? ["frontend-mock-verify-shell"]
+                        : []),
+                ],
                 role: "reviewer",
                 executor: "pi",
                 complexity: "HIGH",
@@ -1067,8 +1929,13 @@ function buildFrontendHybridDagFromTask(sources) {
                     "Review the frontend implementation and verification evidence.",
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
                     "Any Critical or Important finding must force VERDICT: request-revision.",
+                    "Use the direct contract, original plan, revision/no-op result, and final design review to reconstruct the approved plan and design verdict; do not infer them from the implementation summary.",
+                    "Treat a commented-out real request, default-enabled Mock, production entrypoint importing test mocks, API/fixture contract drift, unauthorized Mock dependency/path, or missing behavior evidence for the selected strategy as at least Important. Mock strategies require Mock-backed evidence; not-needed requires applicable real or no-remote behavior evidence. Verify that the real request remains the default when Mock activation is absent.",
+                    "Inspect the production/default-real-path static evidence directly and require Mock activation to be off for that check.",
+                    "Distinguish Mock-backed evidence from real API integration evidence and preserve the Real Integration Gap when the backend was not exercised.",
                     "Review implementation quality, behavior/state coverage, verification evidence, and maintainability. Read-only: do not modify files.",
                     sourceContext,
+                    mockContextBlock,
                 ].join("\n\n"),
             },
             {
@@ -1096,7 +1963,16 @@ function buildFrontendHybridDagFromTask(sources) {
             },
             {
                 id: "frontend-closeout-pi",
-                depends_on: ["frontend-review-gate-shell"],
+                depends_on: [
+                    "frontend-review-gate-shell",
+                    "frontend-review-pi",
+                    "frontend-static-verify-shell",
+                    "frontend-behavior-verify-shell",
+                    "frontend-mock-assess-pi",
+                    ...(mockMode === "required" && hasMockVerifyCommands
+                        ? ["frontend-mock-verify-shell"]
+                        : []),
+                ],
                 role: "closeout",
                 executor: "pi",
                 complexity: "MED",
@@ -1106,11 +1982,13 @@ function buildFrontendHybridDagFromTask(sources) {
                     : ["**", "docs/**"],
                 forbiddenPaths,
                 skills: FRONTEND_VERIFICATION_SKILLS,
-                outputContract: "Markdown closeout summary with Changes, Verification Evidence, Review Result, Known Risks, and Follow-up. No file writes.",
+                outputContract: "Markdown closeout summary with Changes, Mock Decision / Strategy / Files / Verification / Production Boundary, Verification Evidence, Review Result, Frontend Status, Real Integration Status, Known Risks, and Follow-up. No file writes.",
                 subtask_prompt: [
-                    "Return a frontend closeout summary covering changes, verification evidence, review result, known risks, and follow-up.",
+                    "Return a frontend closeout summary covering Mock decision/strategy/files/verification/production boundary, changes, verification evidence, review result, known risks, and follow-up.",
+                    `When only Mock-backed evidence passed, state exactly Frontend status: mock-validated and Real integration: pending, summarize the Real Integration Gap, and name ${taskConfig.taskId}-real-api-integration-verify as the explicit follow-up task to create/run after backend readiness. This follow-up is not auto-created or auto-executed. Never describe Mock evidence as real API integration.`,
                     "Read-only: do not modify code, docs, artifacts, or .harness/dag-runs/.",
                     sourceContext,
+                    mockContextBlock,
                 ].join("\n\n"),
             },
         ],
@@ -1133,53 +2011,48 @@ function buildAnalyzeInputsNode(sources) {
         writePolicy: "read-only",
         allowedPaths: commonReadOnlyPaths(sources),
         forbiddenPaths: commonForbiddenPaths(sources),
-        outputContract: "Structured Markdown extracting core content from source documents. No file writes.",
+        outputContract: "Pure Backend Test Analysis v1 JSON object matching docs/templates/backend-test-analysis.schema.json. No Markdown prose and no file writes.",
         subtask_prompt: [
-            "Read the task source materials and extract the following structured content for downstream test generation.",
-            "",
-            "## Required Output Sections:",
-            "",
-            "### 1. API Endpoints",
-            "List all API endpoints: Method, Path, Description, Request params, Response format.",
-            "",
-            "### 2. Data Model",
-            "For each table/collection: fields, types, constraints, descriptions.",
-            "",
-            "### 3. Business Logic",
-            "Core business rules, validation rules, calculation formulas.",
-            "",
-            "### 4. State Transitions",
-            "State machines (e.g. order status: pending → paid → shipped → completed).",
-            "",
-            "### 5. Error Scenarios & Error Codes",
-            "All error codes, error messages, and when they occur.",
-            "",
-            "### 6. External Dependencies",
-            "Third-party services, databases, message queues. Include timeout settings if documented.",
-            "",
-            "### 7. Acceptance Criteria",
-            "Extract ALL acceptance criteria from 需求.md. Number them AC-001, AC-002, etc. If not explicitly listed, derive from functional requirements.",
-            "",
-            "### 8. Risk Areas",
-            "High-risk areas requiring extra test coverage.",
-            "",
-            "## Conditional Sections (include ONLY if mentioned in requirements):",
-            "- Authentication & Authorization: include ONLY if requirements mention auth mechanism (JWT, OAuth2, API Key, etc.)",
-            "- Timeout Handling: include ONLY if requirements mention timeout configuration or degradation strategy",
-            "- Concurrency & Idempotency: include ONLY if requirements mention concurrency, idempotency rules, or locking mechanisms",
-            "- State Transitions: include ONLY if requirements mention business state machines",
-            "- If not mentioned in requirements, do NOT include these sections",
-            "",
-            "This output will be used directly by downstream nodes. Be thorough and structured.",
+            "Read the task source materials and return exactly one JSON object matching Backend Test Analysis v1.",
+            "Do not wrap it in explanatory prose. A single fenced json block is tolerated, but pure JSON is preferred.",
+            "Copy taskId, requirementPath, requirementSha256, referencePaths, and requirementIds exactly from the DAG source binding shown below.",
+            "Preserve existing AC IDs. Do not invent endpoint methods, paths, fields, errors, boundaries, or business rules; record unknowns in evidenceGaps.",
+            "Use empty arrays for categories not documented. Never include credentials, tokens, private keys, or secret values.",
+            "Required top-level keys: schemaVersion, sourceBinding, acceptanceCriteria, endpoints, dataModels, businessRules, stateTransitions, boundaryConstraints, externalDependencies, risks, evidenceGaps.",
             "Read-only: do not modify code, docs, artifacts, or repository files.",
             buildSourceContextBlock(sources),
         ].join("\n\n"),
     };
 }
+function buildBackendTestAnalysisContractGateNode(sources) {
+    return {
+        id: "backend-test-analysis-contract-shell",
+        depends_on: ["analyze-inputs-pi"],
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "read-only",
+        allowedPaths: commonReadOnlyPaths(sources),
+        forbiddenPaths: commonForbiddenPaths(sources),
+        outputContract: "Validated run-owned Backend Test Analysis v1 artifact pointer, schema ID, and SHA-256.",
+        subtask_prompt: "Materialize and validate the backend-test analysis contract under the current DAG run.",
+        shell: {
+            commands: [],
+            jsonArtifactGate: {
+                fromNodeId: "analyze-inputs-pi",
+                schemaId: "backend-test-analysis-v1",
+                artifactName: "backend-test-analysis.json",
+                outputDir: "contracts",
+            },
+            cwd: ".",
+            timeoutMs: 60000,
+        },
+    };
+}
 function buildGenerateBackendFunctionalCasesNode(sources) {
     return {
         id: "generate-backend-functional-cases-pi",
-        depends_on: ["analyze-inputs-pi"],
+        depends_on: ["backend-test-analysis-contract-shell"],
         role: "implementer",
         executor: "pi",
         toolProfile: "write",
@@ -1191,7 +2064,7 @@ function buildGenerateBackendFunctionalCasesNode(sources) {
         // 注意：Pi 节点超时由 executor 层控制（默认 30 分钟）
         // 如需调整，在 harness.json 的 executors.pi 中配置 modelConfig.timeoutMs
         subtask_prompt: [
-            "Based on the upstream analyze-inputs-pi output, generate structured backend functional test cases.",
+            "Read the validated structured artifact pointer from backend-test-analysis-contract-shell and generate cases only from that JSON contract.", ,
             "",
             "## Output Steps (do in order):",
             "1. First, output a brief summary: how many modules, how many cases planned per module",
@@ -1206,9 +2079,9 @@ function buildGenerateBackendFunctionalCasesNode(sources) {
             "## Coverage Requirements:",
             "- Positive paths: happy path for each acceptance criterion",
             "- Negative paths: error scenarios (invalid input, not found, state violations)",
-            "- Boundary conditions: empty input, max length, edge values",
             "",
             "## Conditional Coverage (include ONLY if mentioned in upstream analysis):",
+            "- Boundary conditions: include ONLY if upstream analyze-inputs-pi mentions value ranges, length limits, numeric bounds, or format constraints",
             "- State transitions: include ONLY if upstream analyze-inputs-pi mentions state machine",
             "- Authentication scenarios: include ONLY if upstream analyze-inputs-pi mentions auth mechanism",
             "- Timeout scenarios: include ONLY if upstream analyze-inputs-pi mentions timeout handling",
@@ -1217,7 +2090,7 @@ function buildGenerateBackendFunctionalCasesNode(sources) {
             "",
             "## Constraints:",
             "- Stay within writeSet: testcase/md/**",
-            "- Do NOT re-read source documents — use the upstream analyze-inputs-pi output only",
+            "- Do NOT re-read source documents or fall back to free-form analysis — use the validated structured artifact only", ,
             "- Do not write root artifacts/**",
         ].join("\n\n"),
     };
@@ -1225,7 +2098,7 @@ function buildGenerateBackendFunctionalCasesNode(sources) {
 function buildReviewBackendCasesNode(sources) {
     return {
         id: "review-backend-cases-pi",
-        depends_on: ["generate-backend-functional-cases-pi"],
+        depends_on: ["generate-backend-functional-cases-pi", "backend-test-analysis-contract-shell"],
         role: "reviewer",
         executor: "pi",
         complexity: "HIGH",
@@ -1243,12 +2116,12 @@ function buildReviewBackendCasesNode(sources) {
             "- ID format: every case uses BE-<MODULE>-<NNN>",
             "- Positive coverage: each acceptance criterion (AC-xxx) has happy-path case",
             "- Negative coverage: error scenarios (invalid input, not found, state violations)",
-            "- Boundary coverage: edge cases (empty, max length, edge values)",
             "- Traceability: each AC maps to at least one case ID",
             "- Case structure: ID, Title, Precondition, Steps, Expected Result",
             "- No duplicate IDs across files",
             "",
             "## Conditional Coverage (check ONLY if mentioned in upstream analysis):",
+            "- Boundary coverage: check ONLY if analyze-inputs-pi mentions value ranges, length limits, numeric bounds, or format constraints",
             "- State transition coverage: check ONLY if analyze-inputs-pi mentions state machine",
             "- Authentication coverage: check ONLY if analyze-inputs-pi mentions auth mechanism",
             "- Timeout coverage: check ONLY if analyze-inputs-pi mentions timeout handling",
@@ -1266,7 +2139,7 @@ function buildReviewBackendCasesNode(sources) {
             "",
             "## Constraints:",
             "- Read-only: do not modify files",
-            "- Do NOT re-read source documents — use upstream analyze-inputs-pi output for acceptance criteria",
+            "- Read the validated backend-test analysis artifact pointer from upstream and use it for AC/source-binding coverage checks", ,
             "- Use testcase/md/ files for case review",
         ].join("\n\n"),
     };
@@ -1305,8 +2178,15 @@ function buildGenerateBackendPytestNode(sources) {
         toolProfile: "write",
         complexity: "HIGH",
         writePolicy: "exclusive",
-        writeSet: ["testcase/**/test_*.py"],
-        allowedPaths: ["testcase/**/test_*.py"],
+        // test_*.py plus optional helpers/factories under testcase/ (not conftest/config)
+        writeSet: [
+            "testcase/**/test_*.py",
+            "testcase/**/helpers/**",
+            "testcase/**/factories/**",
+        ],
+        // Union task allowedPaths with testcase/** so writeSet stays in scope even when
+        // task.json only lists product paths (e.g. ./src/**). Writes still gated by writeSet.
+        allowedPaths: Array.from(new Set([...commonReadOnlyPaths(sources), "testcase/**"])),
         forbiddenPaths: commonForbiddenPaths(sources),
         // 注意：Pi 节点超时由 executor 层控制（默认 30 分钟）
         // 如需调整，在 harness.json 的 executors.pi 中配置 modelConfig.timeoutMs
@@ -1325,26 +2205,94 @@ function buildGenerateBackendPytestNode(sources) {
             "",
             "## Implementation Rules:",
             "- Use assert statements, not unittest assertions",
-            "- Assert specific values, not just 'no exception'",
-            "- Use @pytest.mark.parametrize for boundary cases",
+            "- Use @pytest.mark.parametrize for boundary cases when the case defines edge values",
             "- Use markers: @pytest.mark.positive, @pytest.mark.negative, @pytest.mark.boundary",
             "",
+            "## Test Data Preparation Rules (MUST follow):",
+            "",
+            "### When Setup is Needed",
+            "Setup phase is REQUIRED only when test cases need pre-existing data:",
+            "- Query/Read APIs: need data to exist before querying",
+            "- Update/Delete APIs: need data to exist before modifying",
+            "- State transition tests: need data in specific state",
+            "",
+            "Setup phase is NOT needed for:",
+            "- Create APIs: testing the creation itself",
+            "- Validation tests: testing input validation with invalid data",
+            "",
+            "### Data Setup Strategy",
+            "When setup is needed:",
+            "1. Prefer function-scoped fixtures for isolation; use module/session scope only when cases explicitly share immutable fixtures",
+            "2. Prefer API-based setup from the upstream analyze-inputs-pi API list and reviewed cases",
+            "3. If a required helper/factory is missing, create NEW files only under testcase/**/helpers/** or testcase/**/factories/**",
+            "",
+            "### Data Construction Priority",
+            "1. API-first: construct data via documented APIs from analyze-inputs-pi / reviewed cases",
+            "2. Reuse existing conftest fixtures when present (read-only)",
+            "3. Direct DB writes are LAST RESORT and only if conftest already exposes a safe test DB fixture with rollback/isolation",
+            "4. If neither API nor safe DB fixture exists, skip the case with an explicit gap note — do NOT invent production DB credentials or write live data",
+            "",
+            "### API Data Construction",
+            "- Prefer the analyze-inputs-pi API Endpoints section and reviewed cases for method/path/fields",
+            "- Chain API calls only when cases document multi-step preconditions",
+            "- Store created resource IDs in fixtures for reuse",
+            "- Do NOT broadly search host route/controller trees for secrets, .env, private keys, or production configs",
+            "- Read host API definitions only when needed to resolve a field name already referenced by reviewed cases; stay out of credential/config paths",
+            "",
+            "### Database Data Construction (restricted)",
+            "- Allowed only via existing conftest test-DB fixtures with transaction rollback or equivalent isolation",
+            "- Never hardcode connection strings, passwords, tokens, or cloud credentials",
+            "- Never target production/shared non-test databases",
+            "- If isolation is unclear, report the gap instead of writing DB rows",
+            "",
+            "## Assertion Rules (MUST follow):",
+            "",
+            "### Positive Path",
+            "MUST assert ALL of the following:",
+            "1. HTTP status code: as defined in API spec (e.g. 200, 201)",
+            "2. Response structure: key fields exist in response body",
+            "3. Specific values: each field equals expected value from test case",
+            "4. Data type: each field is correct type",
+            "",
+            "### Negative Path",
+            "MUST assert ALL of the following:",
+            "1. HTTP status code: as defined in API spec (e.g. 400, 404, 500)",
+            "2. Error code field: field name from API spec (e.g. code, error_code, errcode, ret)",
+            "3. Error message field: field name from API spec (e.g. message, msg, errmsg, error)",
+            "",
+            "### Field Name Resolution",
+            "Field names MUST come from the upstream analyze-inputs-pi output (API Endpoints section) or reviewed cases, NOT guessed. For example:",
+            "- If API spec defines {\"ret\": 0, \"msg\": \"success\"}, assert response.json()['ret'] and response.json()['msg']",
+            "- If API spec defines {\"code\": 4001, \"message\": \"error\"}, assert response.json()['code'] and response.json()['message']",
+            "",
             "## Conditional Implementation (include ONLY if test cases exist):",
             "- Authentication tests: implement ONLY if testcase/md/ contains auth-related cases",
             "- Timeout tests: implement ONLY if testcase/md/ contains timeout-related cases",
+            "- Boundary tests: implement ONLY when cases define value ranges, length limits, or format constraints",
             "- Use @pytest.mark.auth for auth tests, @pytest.mark.timeout for timeout tests",
             "- If no such cases exist, do NOT add these tests",
             "",
             "## Constraints:",
-            "- Only create NEW files, do NOT modify existing framework files (conftest.py, pytest.ini, pyproject.toml)",
-            "- If filename exists, add suffix: test_order.py → test_order_01.py",
-            "- Stay within writeSet: testcase/**/test_*.py",
-            "- Do NOT re-read source documents — use the reviewed cases under testcase/md/ only",
+            "- Only create NEW files under writeSet: testcase/**/test_*.py, testcase/**/helpers/**, testcase/**/factories/**",
+            "- Do NOT modify existing framework files (conftest.py, pytest.ini, pyproject.toml, setup.cfg, __init__.py)",
+            "- If a test filename exists, add suffix: test_order.py → test_order_01.py",
+            "- Do NOT re-read source documents — use reviewed cases under testcase/md/ and upstream analyze-inputs-pi output only",
             "- Read existing conftest.py/pytest.ini to understand conventions, but do NOT modify them",
         ].join("\n\n"),
     };
 }
 function buildExecuteBackendPytestNode(sources) {
+    // Keep the target worktree read-only: JUnit is runner-owned evidence under
+    // the current DAG run and moves with active → completed/paused lifecycle.
+    const pytestCommand = [
+        'test -n "${HARNESS_DAG_RUN_DIR:-}" || { echo "missing HARNESS_DAG_RUN_DIR for backend pytest report" >&2; exit 2; }',
+        'REPORT="${HARNESS_DAG_RUN_DIR}/reports/backend-test-junit.xml"',
+        'mkdir -p "$(dirname "${REPORT}")"',
+        'PYTHONDONTWRITEBYTECODE=1 python -m pytest testcase/ -v -p no:cacheprovider --junitxml="${REPORT}"',
+        'STATUS=$?',
+        'printf "JUnit report: %s\\n" "${REPORT}"',
+        'exit "${STATUS}"',
+    ].join("; ");
     return {
         id: "execute-backend-pytest-shell",
         depends_on: ["generate-backend-pytest-pi"],
@@ -1354,19 +2302,15 @@ function buildExecuteBackendPytestNode(sources) {
         writePolicy: "read-only",
         allowedPaths: commonReadOnlyPaths(sources),
         forbiddenPaths: commonForbiddenPaths(sources),
-        outputContract: "Archived pytest stdout/stderr with exit codes and HTML report path; no source or test file modifications.",
-        subtask_prompt: "Run pytest for the backend test suite and capture results.",
+        outputContract: "Archived pytest stdout/stderr with exit codes; JUnit XML is runner-owned evidence at $HARNESS_DAG_RUN_DIR/reports/backend-test-junit.xml. Must not modify worktree files, testcase sources, production code, or assertions.",
+        subtask_prompt: "Run pytest for the backend test suite; write JUnit evidence only under the current HARNESS_DAG_RUN_DIR/reports/.",
         shell: {
-            commands: [
-                "python -m pytest testcase/ --html=reports/backend-test-report.html -v",
-            ],
+            commands: [pytestCommand],
             verifyEvidence: buildVerifyEvidence({
                 phase: "final",
                 quota: "full",
                 commandSource: "inline",
-                fallbackCommands: [
-                    "python -m pytest testcase/ --html=reports/backend-test-report.html -v",
-                ],
+                fallbackCommands: [pytestCommand],
                 finalFullRequired: true,
             }),
             cwd: ".",
@@ -1438,9 +2382,9 @@ function buildBackendTestHybridDag(sources) {
         ...STANDARD_GLOBAL_CONSTRAINTS,
         "backend-test-dag nodes must maintain traceability from requirements to functional cases to pytest automation.",
         "Functional test case IDs must use BE-<MODULE>-<NNN> format.",
-        "pytest execution must produce HTML reports under reports/.",
+        "pytest execution must keep the target worktree read-only and write machine-readable results only under the current HARNESS_DAG_RUN_DIR/reports/** (e.g. JUnit XML).",
         "pytest automation scripts must use test_ filename prefix for pytest discovery.",
-        "generate-backend-pytest-pi must only create new test files under testcase/; modifying existing framework files (conftest.py, pytest.ini, pyproject.toml) is forbidden.",
+        "generate-backend-pytest-pi may create only new files under testcase/**/test_*.py, testcase/**/helpers/**, and testcase/**/factories/**; modifying conftest.py, pytest.ini, pyproject.toml, or production code is forbidden.",
         "review-backend-cases-gate-shell must block pytest generation unless the review verdict is exactly VERDICT: pass.",
         "If a target test filename already exists under testcase/, add a numeric suffix (_01, _02, ...); never overwrite or append to existing files.",
         "execute-backend-pytest-shell must not modify test assertions or production code to make tests pass; test failures indicate potential implementation issues and must be reported honestly.",
@@ -1453,18 +2397,9 @@ function buildBackendTestHybridDag(sources) {
         objective: extractObjective(sources.requirementMarkdown, taskConfig.title),
         successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
         globalConstraints,
-        convergence: {
-            enabled: true,
-            maxPasses: 3,
-            stopOnVerdictPass: true,
-            stopOnHardVerifyPass: true,
-            pauseOnRegression: true,
-            chainNodeIds: [
-                "generate-backend-functional-cases-pi",
-                "review-backend-cases-pi",
-                "review-backend-cases-gate-shell",
-            ],
-        },
+        // No convergence loop: review gate is fail-closed. request-revision stops
+        // the DAG; regenerate after fixing cases. Controller still keys off
+        // hard-verify-shell, which this template does not include.
         defaults: {
             ...BACKEND_TEST_DEFAULTS,
             contextProfile: taskConfig.contextProfile,
@@ -1473,6 +2408,7 @@ function buildBackendTestHybridDag(sources) {
         executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
         tasks: [
             buildAnalyzeInputsNode(sources),
+            buildBackendTestAnalysisContractGateNode(sources),
             buildGenerateBackendFunctionalCasesNode(sources),
             buildReviewBackendCasesNode(sources),
             buildReviewBackendCasesGateNode(sources),
@@ -1487,6 +2423,104 @@ function buildBackendTestHybridDag(sources) {
     return spec;
 }
 // ---------------------------------------------------------------------------
+// Frontend browser-test RAG DAG template
+// ---------------------------------------------------------------------------
+function buildFrontendTestHybridDag(sources) {
+    const config = sources.taskConfig.frontendTest ?? { maxCasesPerBatch: 20 };
+    const hasFrontendTestWriteScope = sources.taskConfig.allowedPaths.some((pattern) => pattern === "testcase/frontend/**" || pattern === "testcase/**" || pattern === "**");
+    const hasReportWriteScope = sources.taskConfig.allowedPaths.some((pattern) => pattern === "docs/test-reports/**" || pattern === "docs/**" || pattern === "**");
+    if (!hasFrontendTestWriteScope || !hasReportWriteScope) {
+        throw new Error('frontend-test requires task.json allowedPaths to include both "testcase/frontend/**" and "docs/test-reports/**" (or explicit containing globs).');
+    }
+    const forbidden = commonForbiddenPaths(sources);
+    const ragWriteSet = ["testcase/frontend/rag/**"];
+    const casesWriteSet = ["testcase/frontend/cases/**"];
+    const evidenceRoot = "testcase/frontend/evidence";
+    const manifestValidation = [
+        "node -e",
+        JSON.stringify([
+            "const fs=require('fs'),path=require('path');",
+            "const file='testcase/frontend/cases/manifest.json'; if(!fs.existsSync(file)) throw new Error('missing '+file);",
+            "const manifest=JSON.parse(fs.readFileSync(file,'utf8')); if(manifest.schemaVersion!==1||!Array.isArray(manifest.cases)) throw new Error('invalid frontend case manifest');",
+            "const dims=new Set(['core','boundary','flow','backend']);",
+            "const seen=new Set(); const seenCasePath=new Set(); const seenEvidenceDir=new Set();",
+            "for(const c of manifest.cases){",
+            " if(!c||typeof c.caseId!=='string'||!/^FE-[A-Za-z0-9][A-Za-z0-9-]*$/.test(c.caseId)||seen.has(c.caseId)) throw new Error('invalid or duplicate caseId');",
+            " seen.add(c.caseId);",
+            " if(typeof c.dimension!=='string'||!dims.has(c.dimension)) throw new Error('invalid dimension');",
+            " if(!Array.isArray(c.acIds)||c.acIds.length===0||c.acIds.some(a=>typeof a!=='string'||!a.trim())) throw new Error('invalid acIds');",
+            " for(const k of ['casePath','evidenceDir']){ const v=c[k]; if(typeof v!=='string'||path.isAbsolute(v)||v.includes('..')) throw new Error('unsafe '+k); }",
+            " if(c.casePath!=='testcase/frontend/cases/'+c.caseId+'.md') throw new Error('casePath must match caseId');",
+            " if(!c.evidenceDir.startsWith('testcase/frontend/evidence/'+c.caseId+'/')) throw new Error('case path escapes frontend test roots');",
+            " if(seenCasePath.has(c.casePath)) throw new Error('duplicate casePath'); seenCasePath.add(c.casePath);",
+            " if(seenEvidenceDir.has(c.evidenceDir)) throw new Error('duplicate evidenceDir'); seenEvidenceDir.add(c.evidenceDir);",
+            "}",
+            "process.stdout.write(JSON.stringify({cases:manifest.cases}));",
+        ].join("")),
+    ].join(" ");
+    const spec = {
+        version: 3,
+        title: `Frontend test DAG: ${sources.taskConfig.title}`,
+        runtimeContract: GENERATED_DAG_RUNTIME_CONTRACT,
+        outputLanguage: sources.outputLanguage ?? DEFAULT_DAG_OUTPUT_LANGUAGE,
+        objective: extractObjective(sources.requirementMarkdown, sources.taskConfig.title),
+        successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
+        globalConstraints: [
+            ...sources.taskConfig.hardConstraints,
+            ...STANDARD_GLOBAL_CONSTRAINTS,
+            "frontend-test-dag generates Markdown cases and browser evidence only; it must not generate pytest or Playwright test source code.",
+            "Each browser case runs serially in a fresh Pi execution boundary. Persist its evidence before starting the next case.",
+            "Use only the declared isolated test environment. Production URLs, real credentials, and unauthorized data are blocked.",
+            "Browser startup for generated cases must be playwright-cli open --browser=chrome --headed <base-url>.",
+            "Token settings are post-case stop thresholds, never a hard provider token cap. Unstarted cases after a threshold are blocked: token-budget-exhausted.",
+        ],
+        defaults: { ...HYBRID_DEFAULTS, writePolicy: "read-only", contextProfile: sources.taskConfig.contextProfile },
+        skillsByRole: {
+            planner: ["loop-agent"], scout: ["playwright-cli"], implementer: ["playwright-cli-case-generator", "playwright-cli", "webapp-testing"], reviewer: ["requesting-code-review"], verifier: ["playwright-cli", "webapp-testing"], closeout: ["loop-agent", "verification-before-completion"],
+        },
+        executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
+        tasks: [
+            {
+                id: "retrieve-frontend-test-context-pi", depends_on: [], role: "planner", executor: "pi", toolProfile: "write", complexity: "HIGH", writePolicy: "exclusive", writeSet: ragWriteSet, allowedPaths: [...commonReadOnlyPaths(sources), ...ragWriteSet], forbiddenPaths: forbidden,
+                outputContract: "Write testcase/frontend/rag/context.md and coverage-map.md with traceable UI/API/test-environment facts.",
+                subtask_prompt: ["Build the frontend test RAG package.", "Read task source, relevant routes/components/API or Mock facts, existing tests, and execution contract. Write only testcase/frontend/rag/context.md and coverage-map.md.", "Record AC IDs, source paths, routes, states, roles, fixture/data prerequisites, API mapping status, risks, and isolated execution contract. Do not guess unavailable facts.", buildSourceContextBlock(sources)].join("\n\n"),
+            },
+            {
+                id: "generate-frontend-functional-cases-pi", depends_on: ["retrieve-frontend-test-context-pi"], role: "implementer", executor: "pi", toolProfile: "write", complexity: "HIGH", writePolicy: "exclusive", writeSet: casesWriteSet, allowedPaths: [...ragWriteSet, ...casesWriteSet], forbiddenPaths: forbidden,
+                outputContract: "Write executable Markdown frontend cases, index.md, and manifest.json schemaVersion 1; no test source code.",
+                subtask_prompt: ["Use skill playwright-cli-case-generator.", "Read only testcase/frontend/rag/context.md, testcase/frontend/rag/coverage-map.md, and existing testcase/frontend/cases/. Write only testcase/frontend/cases/**.", "Generate Markdown cases, index.md and manifest.json (schemaVersion 1; cases[] with caseId, casePath, dimension, acIds, evidenceDir). IDs use FE-<FEATURE>-<NNN>-<dimension>; dimensions core|boundary|flow|backend.", "Never infer API fields, constraints, SLA, credentials, or unrecorded test data. Do not create pytest or Playwright source. Every browser start command is: playwright-cli open --browser=chrome --headed <base-url>.", "Each case must be independent, declare its session/preconditions/data cleanup, UI assertions, evidence paths under testcase/frontend/evidence/<case-id>/, and mark unsafe/missing dependencies blocked."].join("\n\n"),
+            },
+            {
+                id: "review-frontend-cases-pi", depends_on: ["generate-frontend-functional-cases-pi"], role: "reviewer", executor: "pi", complexity: "HIGH", writePolicy: "read-only", allowedPaths: [...ragWriteSet, ...casesWriteSet], forbiddenPaths: forbidden,
+                outputContract: "First line VERDICT: pass or VERDICT: request-revision, followed by AC-to-case coverage and execution risk findings; no writes.", subtask_prompt: "Review only the RAG package and frontend Markdown cases. Verify traceability, independent execution, safe data/environment handling, manifest correctness, and evidence requirements. The verdict is advisory and does not block case execution.",
+            },
+            {
+                id: "materialize-frontend-case-manifest-shell", depends_on: ["review-frontend-cases-pi"], role: "verifier", executor: "shell", complexity: "LOW", writePolicy: "read-only", allowedPaths: casesWriteSet, forbiddenPaths: forbidden,
+                outputContract: "stdout is exactly JSON { cases: [...] } after deterministic frontend manifest validation.", subtask_prompt: "Validate and materialize the generated frontend case manifest.", shell: { commands: [manifestValidation], cwd: ".", timeoutMs: 120000 },
+            },
+            {
+                id: "execute-frontend-cases-map", depends_on: ["materialize-frontend-case-manifest-shell"], role: "verifier", executor: "static", complexity: "LOW", writePolicy: "none", allowedPaths: [], forbiddenPaths: forbidden,
+                outputContract: "Serial aggregate of case execution summaries, evidence paths, tokens, and token-budget blocked cases.", subtask_prompt: "Expand and execute the validated frontend case manifest serially.", static: { resultMarkdown: "Frontend case map expansion barrier." },
+                dynamicExpansion: { type: "map_agent", workflowNodeId: "execute-frontend-cases-map", itemsFrom: "$.nodes['materialize-frontend-case-manifest-shell'].output.cases", itemName: "case", maxItems: config.maxCasesPerBatch, maxExpandedNodes: config.maxCasesPerBatch, childIdPrefix: "execute-frontend-case", tokenBudget: { maxTokensPerCase: config.maxTokensPerCase, maxTotalTokens: config.maxTotalTokens }, childTask: {
+                        executor: "pi", role: "verifier", skills: ["playwright-cli", "webapp-testing"], toolProfile: "write", complexity: "MED", writePolicy: "exclusive", allowedPaths: ["testcase/frontend/cases/{{case.caseId}}.md", "testcase/frontend/rag/context.md", "testcase/frontend/rag/coverage-map.md", `${evidenceRoot}/{{case.caseId}}/**`], forbiddenPaths: forbidden, writeSet: [`${evidenceRoot}/{{case.caseId}}/**`], outputContract: "Compact JSON <=1200 characters with case status, evidence paths, error summary, and tokens.", subtaskPromptTemplate: ["Execute exactly case {{case.caseId}} from {{case.casePath}} using playwright-cli and webapp-testing. This is a fresh Pi session; do not use /new.", "Use only the declared isolated test environment. If CLI/browser/base URL/credentials/fixture isolation is missing, record blocked rather than installing tools or guessing.", "Use playwright-cli open --browser=chrome --headed <base-url>. Persist execution.md, case-result.json, screenshots/trace/video/logs under {{case.evidenceDir}} before returning.", "A business failed or blocked case is a recorded result, not a node failure. Close the session and return only compact JSON (<=1200 chars): {caseId,status,evidencePaths,errorSummary,tokens}."].join("\n\n")
+                    } },
+            },
+            {
+                id: "review-frontend-execution-pi", depends_on: ["execute-frontend-cases-map"], role: "reviewer", executor: "pi", complexity: "HIGH", writePolicy: "read-only", allowedPaths: ["testcase/frontend/**"], forbiddenPaths: forbidden,
+                outputContract: "Read-only AC-to-case-to-browser-evidence review, including failed, blocked and token-budget-exhausted cases.", subtask_prompt: "Review the frontend case aggregate and on-disk case/evidence artifacts. A passed case requires assertion plus screenshot or equivalent browser evidence; failed/blocked cases require reasons. Do not replace browser evidence with model conclusions.",
+            },
+            {
+                id: "frontend-test-retrospect-pi", depends_on: ["review-frontend-execution-pi"], role: "closeout", executor: "pi", toolProfile: "write", complexity: "MED", writePolicy: "exclusive", writeSet: ["docs/test-reports/**"], allowedPaths: ["testcase/frontend/**", "docs/test-reports/**"], forbiddenPaths: forbidden,
+                outputContract: "Write frontend-test-retrospect-<date>.md with coverage, pass/fail/blocked, risks, findings, and A/B/C/D rating.", subtask_prompt: "Write the frontend test retrospective under docs/test-reports/. Summarize coverage, passed/failed/blocked cases (including token-budget-exhausted), review findings, browser anomalies, residual risks, and A/B/C/D rating. Blocked cases never count as passed.",
+            },
+        ],
+    };
+    applyDefaultReadOnlyRetryPolicy(spec);
+    parseDagSpec(spec);
+    assertValidDagSpec(spec);
+    return spec;
+}
+// ---------------------------------------------------------------------------
 // Knowledge-sync DAG template
 // ---------------------------------------------------------------------------
 const KNOWLEDGE_SYNC_DEFAULTS = {
@@ -1501,6 +2535,104 @@ const KNOWLEDGE_SYNC_SKILLS_BY_ROLE = {
     verifier: ["verification-before-completion", "systematic-debugging"],
     closeout: ["loop-agent", "verification-before-completion"],
 };
+/**
+ * Deterministic aggregate gate: all listed review nodes must emit VERDICT: pass
+ * (first VERDICT: line in assistantText/stdout). Uses HARNESS_DAG_RUN_DIR JSON artifacts.
+ */
+export function buildMultiPerspectiveReviewAggregateScript(fromNodeIds, label) {
+    if (fromNodeIds.length === 0) {
+        throw new Error("multi-perspective aggregate requires at least one review node id");
+    }
+    const idsLiteral = JSON.stringify([...fromNodeIds]);
+    const labelLiteral = JSON.stringify(label);
+    return [
+        "node",
+        "-e",
+        JSON.stringify([
+            "const fs=require('fs');",
+            "const path=require('path');",
+            `const ids=${idsLiteral};`,
+            `const label=${labelLiteral};`,
+            "const runDir=process.env.HARNESS_DAG_RUN_DIR;",
+            "if(!runDir){ console.error(label+': missing HARNESS_DAG_RUN_DIR'); process.exit(1); }",
+            "function normalize(line){",
+            "  const t=String(line).trim();",
+            "  const m=t.match(/^\\*{1,3}\\s*(VERDICT:[^*]+?)\\s*\\*{1,3}$/);",
+            "  return (m?m[1]:t).trim();",
+            "}",
+            "function firstVerdict(text){",
+            "  for (const line of String(text||'').split(/\\r?\\n/)) {",
+            "    const n=normalize(line);",
+            "    if(/^VERDICT:/.test(n)) return n;",
+            "  }",
+            "  return '';",
+            "}",
+            "const failures=[];",
+            "for (const id of ids) {",
+            "  const file=path.join(runDir, id+'.json');",
+            "  if(!fs.existsSync(file)){ failures.push(id+': missing JSON '+file); continue; }",
+            "  let raw; try { raw=JSON.parse(fs.readFileSync(file,'utf8')); } catch(e){ failures.push(id+': invalid JSON'); continue; }",
+            "  const verdict=firstVerdict(raw.assistantText ?? raw.stdout ?? '');",
+            "  if(verdict!=='VERDICT: pass') failures.push(id+': '+(verdict||'missing VERDICT line'));",
+            "  else console.log(id+': VERDICT: pass');",
+            "}",
+            "if(failures.length){ console.error(label+' blocked:\\n'+failures.join('\\n')); process.exit(1); }",
+            "console.log(label+': all perspectives VERDICT: pass ('+ids.length+')');",
+        ].join("")),
+    ].join(" ");
+}
+function buildMultiPerspectiveReviewNodes(input) {
+    const reviewNodes = input.perspectives.map((p) => ({
+        id: `${input.nodePrefix}${p.id}-pi`,
+        depends_on: [...input.dependsOn],
+        role: "reviewer",
+        executor: "pi",
+        complexity: "HIGH",
+        writePolicy: "read-only",
+        allowedPaths: input.allowedPaths,
+        forbiddenPaths: commonForbiddenPaths(input.sources),
+        outputContract: `Plain Markdown; first non-empty line is VERDICT: pass or VERDICT: request-revision. Perspective: ${p.perspective}. No file writes.`,
+        subtask_prompt: [
+            `You are the **${p.perspective}** reviewer in a multi-perspective review panel.`,
+            "Other perspectives run in parallel; do not assume their conclusions. Stay in your role.",
+            "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
+            "Any Critical or Important finding in your domain must force VERDICT: request-revision.",
+            "Structure: VERDICT line, then Findings (Critical/Important/Minor), then Checked Items, then Residual Risks.",
+            "Cite concrete paths/ids as evidence. Read-only: do not modify files.",
+            ...input.sharedBrief,
+            "Focus for this perspective:",
+            ...p.focus.map((line) => `- ${line}`),
+            buildSourceContextBlock(input.sources),
+        ].join("\n\n"),
+    }));
+    const reviewIds = reviewNodes.map((n) => n.id);
+    const aggregateScript = buildMultiPerspectiveReviewAggregateScript(reviewIds, input.gateLabel);
+    const gateNode = {
+        id: input.gateId,
+        depends_on: reviewIds,
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "read-only",
+        allowedPaths: commonReadOnlyPaths(input.sources),
+        forbiddenPaths: commonForbiddenPaths(input.sources),
+        outputContract: `Deterministic multi-perspective gate: exit 0 only when every review node among ${reviewIds.join(", ")} emits VERDICT: pass.`,
+        subtask_prompt: `Aggregate gate for ${input.gateLabel}: all perspectives must pass before downstream apply/promote.`,
+        shell: {
+            commands: [aggregateScript],
+            verifyEvidence: buildVerifyEvidence({
+                phase: "final",
+                quota: "full",
+                commandSource: "inline",
+                fallbackCommands: [aggregateScript],
+                finalFullRequired: true,
+            }),
+            cwd: ".",
+            timeoutMs: 60000,
+        },
+    };
+    return [...reviewNodes, gateNode];
+}
 /** Safe Feature directory id: F-… without path separators. */
 const KNOWLEDGE_SYNC_FEATURE_ID_RE = /^F-[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export function assertSafeKnowledgeSyncFeatureId(featureId) {
@@ -1682,12 +2814,61 @@ function buildKnowledgeSyncValidateNode(sources, featureId) {
         },
     };
 }
+const KNOWLEDGE_SYNC_MULTI_REVIEW_PERSPECTIVES = [
+    {
+        id: "qa",
+        perspective: "QA / acceptance",
+        focus: [
+            "acceptanceVerdict and AC coverage vs evidencePointers",
+            "caseIndex completeness and non-invented pass results",
+            "defects registry consistency with open issues",
+        ],
+    },
+    {
+        id: "domain",
+        perspective: "domain / product",
+        focus: [
+            "requirement-delta risk and silent requirement rewrites",
+            "operations[] targets stay under the bound featureId",
+            "business meaning of coverage/matrix changes",
+        ],
+    },
+    {
+        id: "evidence",
+        perspective: "evidence / audit",
+        focus: [
+            "finalVerification authority is shell evidence, not prose",
+            "high-risk ops and gates.requireHumanIfHighRisk",
+            "draft schema fields and pointer-only log policy",
+        ],
+    },
+];
+function buildKnowledgeSyncMultiReviewNodes(sources, featureId) {
+    return buildMultiPerspectiveReviewNodes({
+        sources,
+        dependsOn: ["knowledge-sync-validate-shell"],
+        nodePrefix: "knowledge-sync-review-",
+        gateId: "knowledge-sync-multi-review-gate-shell",
+        gateLabel: "knowledge-sync multi-perspective review",
+        perspectives: KNOWLEDGE_SYNC_MULTI_REVIEW_PERSPECTIVES,
+        allowedPaths: [
+            ...commonReadOnlyPaths(sources),
+            `features/${featureId}/**`,
+            "docs/test-reports/**",
+        ],
+        sharedBrief: [
+            `Bound featureId: ${featureId}. Only review draft/ops for this Feature.`,
+            `Primary draft path: ${knowledgeSyncDraftRelPath(featureId)}.`,
+            "Apply is blocked until all perspectives pass. Do not approve fabricated verification pass.",
+        ],
+    });
+}
 function buildKnowledgeSyncApplyNode(sources, featureId) {
     const writeSet = knowledgeSyncWriteSet(featureId);
     const draftPath = knowledgeSyncDraftRelPath(featureId);
     return {
         id: "knowledge-sync-apply-pi",
-        depends_on: ["knowledge-sync-validate-shell"],
+        depends_on: ["knowledge-sync-multi-review-gate-shell"],
         role: "implementer",
         executor: "pi",
         toolProfile: "write",
@@ -1756,11 +2937,13 @@ function buildKnowledgeSyncHybridDag(sources) {
         ...STANDARD_GLOBAL_CONSTRAINTS,
         `knowledge-sync-dag is bound to featureId=${featureId}; writes only features/${featureId}/testing/**, features/${featureId}/requirement-delta.md, and docs/test-reports/**.`,
         "knowledge-sync must not modify other features/**, src/**, .harness/**, knowledge/testing/standards/**, or pytest framework files.",
-        "Apply is blocked unless knowledge-sync-validate-shell passes; final verification evidence remains the completion authority.",
+        "Apply is blocked unless knowledge-sync-validate-shell and multi-perspective review gate pass; final verification evidence remains the completion authority.",
+        "Multi-perspective review: QA/acceptance, domain/product, and evidence/audit must each emit VERDICT: pass before apply.",
         "High-risk requirement/acceptance body changes require human approval via requirement-delta; do not silently rewrite requirement.md.",
         "Raw shell logs stay as path pointers; knowledge base stores stable facts only.",
         "Prefer structured YAML/Markdown L1 knowledge pack over vector-store-only writes.",
     ];
+    const multiReview = buildKnowledgeSyncMultiReviewNodes(sources, featureId);
     const spec = {
         version: 2,
         title: `Knowledge-sync DAG (${featureId}): ${taskConfig.title}`,
@@ -1778,6 +2961,7 @@ function buildKnowledgeSyncHybridDag(sources) {
             buildKnowledgeSyncCollectNode(sources, featureId),
             buildKnowledgeSyncDraftNode(sources, featureId),
             buildKnowledgeSyncValidateNode(sources, featureId),
+            ...multiReview,
             buildKnowledgeSyncApplyNode(sources, featureId),
             buildKnowledgeSyncPointerNode(sources, featureId),
         ],
@@ -1991,51 +3175,55 @@ function buildKgBootstrapValidateNode(sources) {
         },
     };
 }
-function buildKgBootstrapReviewNode(sources) {
-    return {
-        id: "kg-bootstrap-review-pi",
-        depends_on: ["kg-bootstrap-validate-shell"],
-        role: "reviewer",
-        executor: "pi",
-        complexity: "HIGH",
-        writePolicy: "read-only",
-        allowedPaths: ["knowledge/bootstrap/**", "knowledge/**", "features/**", "docs/**"],
-        forbiddenPaths: commonForbiddenPaths(sources),
-        outputContract: "Plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision; human still promotes asserted entities.",
-        subtask_prompt: [
-            "Review staging knowledge-graph proposals for evidence quality, over-claiming, missing inventory coverage, and unsafe edges.",
-            "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
-            "pass means proposals are ready for human promotion consideration — it does NOT mark entities asserted.",
-            "request-revision if critical entities lack evidence, ids collide conceptually, or formal trees were written outside staging.",
-            "Read-only: do not modify files.",
-            buildSourceContextBlock(sources),
-        ].join("\n\n"),
-    };
-}
-function buildKgBootstrapReviewGateNode(sources) {
-    return {
-        id: "kg-bootstrap-review-gate-shell",
-        depends_on: ["kg-bootstrap-review-pi"],
-        role: "verifier",
-        executor: "shell",
-        complexity: "LOW",
-        writePolicy: "read-only",
-        allowedPaths: commonReadOnlyPaths(sources),
-        forbiddenPaths: commonForbiddenPaths(sources),
-        outputContract: "Deterministic gate: exit 0 only when kg-bootstrap-review-pi first verdict line is VERDICT: pass.",
-        subtask_prompt: "Block promote/materialize unless review verdict is pass.",
-        shell: {
-            commands: [],
-            verdictGate: {
-                fromNodeId: "kg-bootstrap-review-pi",
-                accept: ["VERDICT: pass"],
-                label: "kg-bootstrap-review",
-                lineMode: "first-verdict-line",
-            },
-            cwd: ".",
-            timeoutMs: 60000,
-        },
-    };
+const KG_BOOTSTRAP_MULTI_REVIEW_PERSPECTIVES = [
+    {
+        id: "structure",
+        perspective: "architecture / structure",
+        focus: [
+            "domain/service/module partition vs inventory candidates",
+            "id uniqueness and naming conventions",
+            "edges that create impossible or circular dependencies",
+        ],
+    },
+    {
+        id: "evidence",
+        perspective: "evidence / anti-hallucination",
+        focus: [
+            "every entity/edge has concrete evidence paths",
+            "no confidence: asserted in staging",
+            "no invented APIs or production details without files",
+        ],
+    },
+    {
+        id: "safety",
+        perspective: "write-boundary / promote safety",
+        focus: [
+            "writes stayed in knowledge/bootstrap/staging/** (and runs/**)",
+            "no formal knowledge/domains|services trees or graph indexes written by AI",
+            "incremental scope respected when update_mode: incremental",
+        ],
+    },
+];
+function buildKgBootstrapMultiReviewNodes(sources) {
+    return buildMultiPerspectiveReviewNodes({
+        sources,
+        dependsOn: ["kg-bootstrap-validate-shell"],
+        nodePrefix: "kg-bootstrap-review-",
+        gateId: "kg-bootstrap-multi-review-gate-shell",
+        gateLabel: "kg-bootstrap multi-perspective review",
+        perspectives: KG_BOOTSTRAP_MULTI_REVIEW_PERSPECTIVES,
+        allowedPaths: [
+            "knowledge/bootstrap/**",
+            "knowledge/**",
+            "features/**",
+            "docs/**",
+        ],
+        sharedBrief: [
+            "Review staging knowledge-graph proposals before promote.",
+            "pass means ready for promote consideration — it does NOT mark entities asserted.",
+            "request-revision if critical entities lack evidence, ids collide, or formal trees were written outside staging.",
+        ],
+    });
 }
 function buildKgBootstrapPromoteNode(sources) {
     const script = buildKgBootstrapInlineNodeScript([
@@ -2065,7 +3253,9 @@ function buildKgBootstrapPromoteNode(sources) {
         "if(fs.existsSync(linksDir)){",
         "  for(const f of fs.readdirSync(linksDir)){",
         "    if(!f.endsWith('.yaml')&&!f.endsWith('.yml')) continue;",
+        "    if(!/^F-[A-Za-z0-9][A-Za-z0-9._-]*\\.ya?ml$/.test(f)){ console.error('invalid feature link proposal filename: '+f); process.exit(1); }",
         "    const id=f.replace(/\\.ya?ml$/,'');",
+        "    if(id.includes('..')){ console.error('invalid feature link proposal filename: '+f); process.exit(1); }",
         "    const dest=path.join(root,'features',id,'knowledge-links.yaml');",
         "    if(!fs.existsSync(path.join(root,'features',id))) continue;",
         "    if(!fs.existsSync(dest)){ fs.mkdirSync(path.dirname(dest),{recursive:true}); fs.copyFileSync(path.join(linksDir,f),dest); copied++; }",
@@ -2075,7 +3265,7 @@ function buildKgBootstrapPromoteNode(sources) {
     ]);
     return {
         id: "kg-bootstrap-promote-shell",
-        depends_on: ["kg-bootstrap-review-gate-shell"],
+        depends_on: ["kg-bootstrap-multi-review-gate-shell"],
         role: "verifier",
         executor: "shell",
         complexity: "LOW",
@@ -2195,7 +3385,9 @@ function buildKnowledgeGraphBootstrapHybridDag(sources) {
         "Promote must not overwrite existing formal files (merge-new-only).",
         "Require knowledge/bootstrap/scope.yaml before propose (B0/B1 skeleton).",
         "Graph indexes are written only by materialize-shell, not by propose-pi.",
+        "Multi-perspective review (structure, evidence, safety) must all VERDICT: pass before promote.",
     ];
+    const multiReview = buildKgBootstrapMultiReviewNodes(sources);
     const spec = {
         version: 2,
         title: `Knowledge-graph bootstrap DAG: ${taskConfig.title}`,
@@ -2214,8 +3406,7 @@ function buildKnowledgeGraphBootstrapHybridDag(sources) {
             buildKgBootstrapInventoryNode(sources),
             buildKgBootstrapProposeNode(sources),
             buildKgBootstrapValidateNode(sources),
-            buildKgBootstrapReviewNode(sources),
-            buildKgBootstrapReviewGateNode(sources),
+            ...multiReview,
             buildKgBootstrapPromoteNode(sources),
             buildKgBootstrapMaterializeNode(sources),
         ],
@@ -2224,30 +3415,42 @@ function buildKnowledgeGraphBootstrapHybridDag(sources) {
     assertValidDagSpec(spec);
     return spec;
 }
+function buildHybridDagForTemplate(sources, template) {
+    let spec;
+    if (template === "frontend-implementation") {
+        spec = buildFrontendHybridDagFromTask(sources);
+    }
+    else if (template === "frontend-test-dag")
+        spec = buildFrontendTestHybridDag(sources);
+    else if (template === "backend-test-dag")
+        spec = buildBackendTestHybridDag(sources);
+    else if (template === "knowledge-sync-dag")
+        spec = buildKnowledgeSyncHybridDag(sources);
+    else if (template === "knowledge-graph-bootstrap-dag")
+        spec = buildKnowledgeGraphBootstrapHybridDag(sources);
+    else {
+        const standard = buildStandardHybridDagFromTask(sources);
+        if (template === "standard-dag")
+            spec = standard;
+        else if (template === "review-gated-dag")
+            spec = buildReviewGatedHybridDag(standard, sources);
+        else
+            spec = buildSupervisedHybridDag(standard, sources);
+    }
+    spec.sourceBinding = buildDagSourceBinding(sources);
+    parseDagSpec(spec);
+    assertValidDagSpec(spec);
+    return spec;
+}
 export function buildHybridDagFromTask(sources, options = {}) {
-    if (sources.taskConfig.taskKind === "frontend-implementation" ||
-        options.template === "frontend-implementation") {
-        return buildFrontendHybridDagFromTask(sources);
-    }
-    if (sources.taskConfig.taskKind === "backend-test" ||
-        options.template === "backend-test-dag") {
-        return buildBackendTestHybridDag(sources);
-    }
-    if (sources.taskConfig.taskKind === "knowledge-sync" ||
-        options.template === "knowledge-sync-dag") {
-        return buildKnowledgeSyncHybridDag(sources);
-    }
-    if (sources.taskConfig.taskKind === "knowledge-graph-bootstrap" ||
-        options.template === "knowledge-graph-bootstrap-dag") {
-        return buildKnowledgeGraphBootstrapHybridDag(sources);
-    }
-    const standard = buildStandardHybridDagFromTask(sources);
-    const template = options.template ?? "standard-dag";
-    if (template === "standard-dag")
-        return standard;
-    if (template === "review-gated-dag")
-        return buildReviewGatedHybridDag(standard, sources);
-    return buildSupervisedHybridDag(standard, sources);
+    const selection = resolveTaskDagTemplateSelection({
+        taskKind: sources.taskConfig.taskKind,
+        title: sources.taskConfig.title,
+        requirementMarkdown: sources.requirementMarkdown,
+        allowedPaths: sources.taskConfig.allowedPaths,
+        requestedTemplate: options.template,
+    });
+    return buildHybridDagForTemplate(sources, selection.template);
 }
 function cloneTask(task, patch = {}) {
     return { ...task, ...patch };
@@ -2635,8 +3838,19 @@ export function defaultHybridDagOutputPath(taskId) {
     return path.join(os.tmpdir(), `${taskId}-hybrid-dag.json`);
 }
 export async function writeHybridDagDraft(sources, outputPath, options = {}) {
-    const template = options.template ?? "standard-dag";
-    const spec = buildHybridDagFromTask(sources, { template });
+    const templateSelection = resolveTaskDagTemplateSelection({
+        taskKind: sources.taskConfig.taskKind,
+        title: sources.taskConfig.title,
+        requirementMarkdown: sources.requirementMarkdown,
+        allowedPaths: sources.taskConfig.allowedPaths,
+        requestedTemplate: options.template,
+    });
+    const template = templateSelection.template;
+    assertTaskAllowedPathsPreflight(sources.taskConfig);
+    const preparedSources = template === "frontend-implementation"
+        ? await prepareFrontendMockSources(sources)
+        : sources;
+    const spec = buildHybridDagForTemplate(preparedSources, template);
     await writeFile(outputPath, `${JSON.stringify(spec, null, 2)}\n`, "utf-8");
     return {
         taskId: sources.taskId,
@@ -2644,6 +3858,7 @@ export async function writeHybridDagDraft(sources, outputPath, options = {}) {
         taskCount: spec.tasks.length,
         nodeIds: spec.tasks.map((task) => task.id),
         template,
+        templateSelection,
     };
 }
 export async function initHybridDagFromTask(repoRoot, taskId, options = {}) {