@tea-agent/loop-agent 0.21.0 → 0.22.0

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

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { access, readdir, readFile, realpath, writeFile, } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { assertValidDagSpec } from "./validate.js";
@@ -829,6 +830,9 @@ function extractFrontendMockVerifyCommandsFromMarkdown(input) {
     return commands.filter((command, index, all) => all.findIndex((candidate) => candidate.args.join("\0") === command.args.join("\0")) === index);
 }
 function chooseFrontendVerifyCommands(input) {
+    if (input.explicitCommands && input.explicitCommands.length > 0) {
+        return { commands: input.explicitCommands, commandSource: "inline" };
+    }
     if (input.parsedCommands.length > 0) {
         return { commands: input.parsedCommands, commandSource: "inline" };
     }
@@ -837,6 +841,36 @@ function chooseFrontendVerifyCommands(input) {
     }
     return { commandSource: "inline" };
 }
+function classifyFrontendVerifyCommand(command) {
+    return /\b(typecheck|check-types|lint|eslint|tsc|build|check)\b/i.test(command) ||
+        /\bscripts[\\/]+ci(?:-tests)?\.sh\b/i.test(command)
+        ? "static"
+        : "behavior";
+}
+function buildExplicitFrontendVerifyCommands(taskConfig, repoRoot) {
+    const staticCommands = [];
+    const behaviorCommands = [];
+    if (!repoRoot)
+        return { staticCommands, behaviorCommands };
+    for (const command of taskConfig.verifyCommands) {
+        const verifyCommand = {
+            args: ["bash", "-lc", command.command],
+            cwd: repoRoot,
+            label: command.label,
+            timeoutMs: command.timeoutMs,
+        };
+        if (classifyFrontendVerifyCommand(command.command) === "static") {
+            staticCommands.push(verifyCommand);
+        }
+        else {
+            behaviorCommands.push(verifyCommand);
+        }
+    }
+    return { staticCommands, behaviorCommands };
+}
+function verifyCommandKey(command) {
+    return `${command.cwd}\0${command.args.join("\0")}`;
+}
 function resolveDagVerifyStrategy(taskConfig) {
     return {
         intermediateQuota: taskConfig.dagVerifyStrategy?.intermediateQuota ?? taskConfig.verifyQuota,
@@ -851,19 +885,80 @@ function buildVerifyEvidence(input) {
         commandSource: input.commandSource,
         commandCount: input.commands?.length ?? input.fallbackCommands.length,
         commandLabels: input.commands?.map((command) => command.label) ?? input.fallbackCommands,
+        commandTexts: input.commandTexts ?? [],
         finalFullRequired: input.finalFullRequired,
     };
 }
+function isFrontendLintVerifyCommand(command) {
+    const text = `${command.label}\n${command.args.join(" ")}`;
+    return /\b(?:lint|eslint)\b/i.test(text);
+}
+function isManagedCiWrapperVerifyCommand(command) {
+    const text = `${command.label}\n${command.args.join(" ")}`.replaceAll("\\", "/");
+    return /\bscripts\/ci(?:-tests)?\.sh\b/.test(text);
+}
+function repoHasNpmScript(repoRoot, scriptName) {
+    if (!repoRoot)
+        return false;
+    const packagePath = path.join(repoRoot, "package.json");
+    if (!existsSync(packagePath))
+        return false;
+    try {
+        const decoded = JSON.parse(readFileSync(packagePath, "utf8"));
+        return typeof decoded.scripts?.[scriptName] === "string";
+    }
+    catch {
+        return false;
+    }
+}
+function partitionFrontendStaticVerifyCommands(input) {
+    const commands = input.commands ?? [];
+    const lintCommands = commands.filter(isFrontendLintVerifyCommand);
+    const staticCommands = commands.filter((command) => !isFrontendLintVerifyCommand(command));
+    if (lintCommands.length === 0 &&
+        commands.some(isManagedCiWrapperVerifyCommand) &&
+        repoHasNpmScript(input.repoRoot, "lint")) {
+        lintCommands.push({
+            args: ["npm", "run", "lint"],
+            cwd: input.repoRoot,
+            label: "npm run lint",
+        });
+    }
+    return {
+        lint: {
+            ...(lintCommands.length > 0 ? { commands: lintCommands } : {}),
+            commandSource: input.commandSource,
+        },
+        static: {
+            ...(staticCommands.length > 0 ? { commands: staticCommands } : {}),
+            commandSource: input.commandSource,
+        },
+    };
+}
+function isFrontendTestPathPattern(entry) {
+    const segments = entry.replaceAll("\\", "/").split("/");
+    return segments.some((segment) => /^(?:test|tests|spec|specs|e2e|__tests__|__specs__)$/i.test(segment));
+}
+function replaceSourceSegmentWithTestSegment(entry) {
+    const normalized = entry.replaceAll("\\", "/");
+    const segments = normalized.split("/");
+    const sourceIndex = segments.findIndex((segment) => /^(?:src|source|app|lib)$/i.test(segment));
+    if (sourceIndex < 0)
+        return null;
+    const testSegments = [...segments];
+    testSegments[sourceIndex] = "test";
+    return testSegments.join("/");
+}
 function deriveParallelScoutPaths(taskConfig) {
     const allowed = taskConfig.allowedPaths;
     if (allowed.length === 0) {
         return { srcPaths: ["**"], testPaths: ["**"] };
     }
-    const srcPaths = allowed.filter((entry) => !entry.includes("/test/"));
-    const explicitTestPaths = allowed.filter((entry) => entry.includes("/test/"));
+    const srcPaths = allowed.filter((entry) => !isFrontendTestPathPattern(entry));
+    const explicitTestPaths = allowed.filter(isFrontendTestPathPattern);
     const derivedTestPaths = allowed
-        .filter((entry) => entry.includes("/src/"))
-        .map((entry) => entry.replace("/src/", "/test/"));
+        .map(replaceSourceSegmentWithTestSegment)
+        .filter((entry) => Boolean(entry));
     return {
         srcPaths: srcPaths.length > 0 ? srcPaths : allowed,
         testPaths: explicitTestPaths.length > 0
@@ -873,6 +968,80 @@ function deriveParallelScoutPaths(taskConfig) {
                 : allowed,
     };
 }
+/**
+ * Resolve frontend verification fallbacks from the target project's own
+ * package scripts. The DAG builder is also used by unit fixtures without a
+ * package.json, so those fixtures retain the historical generic fallback.
+ * Real projects never inherit loop-agent's commands when package.json exists.
+ */
+async function discoverFrontendFallbackVerifyCommands(repoRoot) {
+    const genericFallback = {
+        staticCommands: ["npm run typecheck", "npm run build"],
+        behaviorCommands: ["npm test"],
+    };
+    if (!repoRoot)
+        return genericFallback;
+    let scripts;
+    try {
+        const packageJson = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf8"));
+        if (packageJson.scripts && typeof packageJson.scripts === "object") {
+            scripts = packageJson.scripts;
+        }
+    }
+    catch {
+        return genericFallback;
+    }
+    if (!scripts)
+        return genericFallback;
+    let packageManager = "npm";
+    for (const [lockfile, manager] of [
+        ["pnpm-lock.yaml", "pnpm"],
+        ["yarn.lock", "yarn"],
+        ["bun.lockb", "bun"],
+        ["bun.lock", "bun"],
+    ]) {
+        try {
+            await access(path.join(repoRoot, lockfile));
+            packageManager = manager;
+            break;
+        }
+        catch {
+            // Try the next package-manager marker.
+        }
+    }
+    const commandForScript = (script) => script === "test"
+        ? `${packageManager} test`
+        : `${packageManager} run ${script}`;
+    const hasScript = (script) => typeof scripts?.[script] === "string" &&
+        String(scripts[script]).trim().length > 0;
+    const firstExisting = (names) => {
+        const selected = [];
+        for (const name of names) {
+            if (hasScript(name) && !selected.includes(name))
+                selected.push(name);
+        }
+        return selected.map(commandForScript);
+    };
+    const staticCommands = firstExisting([
+        "typecheck",
+        "check-types",
+        "lint",
+        "check",
+        "build",
+    ]);
+    const behaviorCommands = firstExisting([
+        "test:unit",
+        "test:frontend",
+        "test:component",
+        "test",
+        "test:e2e",
+        "e2e",
+    ]);
+    return {
+        staticCommands: staticCommands.length > 0 ? staticCommands : behaviorCommands,
+        behaviorCommands: behaviorCommands.length > 0 ? behaviorCommands : staticCommands,
+    };
+}
 function deriveFrontendBehaviorPaths(taskConfig) {
     if (taskConfig.allowedPaths.length === 0)
         return ["**"];
@@ -1507,6 +1676,7 @@ function buildFrontendMockVerifyNode(sources, implementId, readOnlyPaths, forbid
                 commandSource: commands.length > 0 ? "inline" : "adapter",
                 commands: verifyCommands.length > 0 ? verifyCommands : undefined,
                 fallbackCommands: [],
+                commandTexts: commands,
             }),
             cwd: ".",
             timeoutMs: 300000,
@@ -1688,7 +1858,7 @@ function pruneFrontendTasksForRisk(tasks, risk) {
         return { ...task, depends_on };
     });
 }
-function buildFrontendHybridDagFromTask(sources) {
+async function buildFrontendHybridDagFromTask(sources) {
     const { taskConfig } = sources;
     const mockCapability = sources.frontendMockCapability ?? {
         status: "absent",
@@ -1756,6 +1926,8 @@ function buildFrontendHybridDagFromTask(sources) {
             "- verificationTargets is a TOP-LEVEL required array",
             "- uiStates items use name/applicable/expectedBehavior/implementationTargets/verificationTargetIds/notApplicableReason",
             "- mockApi.productionDefaultOff must always be true (including strategy: not-needed)",
+            "- All implementation files, verification files, symbols, and commands must be discovered from the current target workspace and current task. Never copy paths, symbols, or commands from the loop-agent repository, an example task, or prior run output.",
+            "- Use relative POSIX paths rooted at the target workspace. Do not assume a particular src/test directory layout; preserve the target project's actual app/, packages/, spec/, __tests__, or other layout.",
         ].join("\n");
     })();
     const sourceContext = [
@@ -1797,26 +1969,42 @@ function buildFrontendHybridDagFromTask(sources) {
     if (mockMode === "blocked") {
         return buildBlockedFrontendMockDag(frontendSources, readOnlyPaths, forbiddenPaths, globalConstraints);
     }
-    const staticFallbackCommands = ["npm run typecheck", "npm run build"];
-    const behaviorFallbackCommands = ["npm test"];
+    const fallbackVerifyCommands = await discoverFrontendFallbackVerifyCommands(sources.repoRoot);
+    const staticFallbackCommands = fallbackVerifyCommands.staticCommands;
+    const behaviorFallbackCommands = fallbackVerifyCommands.behaviorCommands;
     const parsedFrontendVerifyCommands = extractFrontendVerifyCommandsFromMarkdown({
         repoRoot: sources.repoRoot,
         requirementMarkdown: sources.requirementMarkdown,
         constraintMarkdown: sources.constraintMarkdown,
     });
+    const explicitFrontendVerifyCommands = buildExplicitFrontendVerifyCommands(taskConfig, sources.repoRoot);
+    const explicitCommandKeys = new Set([...explicitFrontendVerifyCommands.staticCommands, ...explicitFrontendVerifyCommands.behaviorCommands].map(verifyCommandKey));
+    const adapterVerifyCommands = (sources.verifyCommands?.final ?? []).filter((command) => !explicitCommandKeys.has(verifyCommandKey(command)));
     const staticVerifyCommands = chooseFrontendVerifyCommands({
+        explicitCommands: explicitFrontendVerifyCommands.staticCommands,
         parsedCommands: parsedFrontendVerifyCommands.staticCommands,
-        adapterCommands: sources.verifyCommands?.intermediate,
+        adapterCommands: adapterVerifyCommands,
+    });
+    const partitionedStaticVerifyCommands = partitionFrontendStaticVerifyCommands({
+        repoRoot: sources.repoRoot,
+        commands: staticVerifyCommands.commands,
+        commandSource: staticVerifyCommands.commandSource,
     });
     const behaviorVerifyCommands = chooseFrontendVerifyCommands({
+        explicitCommands: explicitFrontendVerifyCommands.behaviorCommands,
         parsedCommands: parsedFrontendVerifyCommands.behaviorCommands,
-        adapterCommands: sources.verifyCommands?.final,
+        adapterCommands: adapterVerifyCommands,
     });
     const staticShellCommands = buildVerifyShellCommands({
         repoRoot: sources.repoRoot,
-        commands: staticVerifyCommands.commands,
+        commands: partitionedStaticVerifyCommands.static.commands,
         fallbackCommands: staticFallbackCommands,
     });
+    const lintShellCommands = buildVerifyShellCommands({
+        repoRoot: sources.repoRoot,
+        commands: partitionedStaticVerifyCommands.lint.commands,
+        fallbackCommands: [],
+    });
     const behaviorShellCommands = buildVerifyShellCommands({
         repoRoot: sources.repoRoot,
         commands: behaviorVerifyCommands.commands,
@@ -1825,16 +2013,28 @@ function buildFrontendHybridDagFromTask(sources) {
     const staticVerifyEvidence = buildVerifyEvidence({
         phase: "intermediate",
         quota: strategy.intermediateQuota ?? "full",
-        commandSource: staticVerifyCommands.commandSource,
-        commands: staticVerifyCommands.commands,
+        commandSource: partitionedStaticVerifyCommands.static.commandSource,
+        commands: partitionedStaticVerifyCommands.static.commands,
         fallbackCommands: staticFallbackCommands,
+        commandTexts: staticShellCommands,
     });
+    const lintVerifyEvidence = lintShellCommands.length > 0
+        ? buildVerifyEvidence({
+            phase: "intermediate",
+            quota: strategy.intermediateQuota ?? "full",
+            commandSource: partitionedStaticVerifyCommands.lint.commandSource,
+            commands: partitionedStaticVerifyCommands.lint.commands,
+            fallbackCommands: [],
+            commandTexts: lintShellCommands,
+        })
+        : undefined;
     const behaviorVerifyEvidence = buildVerifyEvidence({
         phase: "final",
         quota: "full",
         commandSource: behaviorVerifyCommands.commandSource,
         commands: behaviorVerifyCommands.commands,
         fallbackCommands: behaviorFallbackCommands,
+        commandTexts: behaviorShellCommands,
         finalFullRequired: true,
     });
     const mockVerifyTemplate = mockMode === "required" && hasMockVerifyCommands
@@ -1897,6 +2097,7 @@ function buildFrontendHybridDagFromTask(sources) {
                 subtask_prompt: [
                     "Inspect frontend code, routing, components, styles, package scripts, and tests.",
                     "Return code and design observations, existing reuse opportunities, and verification entry points.",
+                    "Derive all file paths from this target workspace. Do not assume the project uses src/, test/, React, or the loop-agent repository layout.",
                     "Read-only: do not modify repository files.",
                     sourceContext,
                 ].join("\n\n"),
@@ -1921,6 +2122,7 @@ function buildFrontendHybridDagFromTask(sources) {
                     "Based on frontend-contract-pi, frontend-scout-pi, task sources, and the generation-time Mock capability evidence, return a minimal frontend implementation plan.",
                     "Select the Mock / API strategy inside the plan and structured contract. Carry endpoint/fixture mapping, explicit activation, production-default-off rule, verification commands, and Real Integration Gap into both outputs.",
                     "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.",
+                    "Every target file and verification target must be selected from the current target workspace and task scope. Do not reuse paths or symbols from examples, prior tasks, or loop-agent itself; if the project uses app/, packages/, spec/, __tests__, or another layout, preserve that layout.",
                     "End with exactly one fenced json object conforming to frontend-implementation-contract-v1 so small topology can materialize the contract without plan-revision.",
                     requirementCoverageInstruction,
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
@@ -2042,16 +2244,47 @@ function buildFrontendHybridDagFromTask(sources) {
                                 : ["native", "browser-intercept", "request-adapter", "not-needed"],
                         artifactName: "frontend-implementation-contract.json",
                         outputDir: "contracts",
+                        requireSourceFreshness: true,
+                        implementationWriteSet: implementPaths.writeSet,
                         openspecCandidatePaths: sources.frontendProjectCapability?.designEvidence.normativePaths ?? [],
                     },
                     cwd: ".",
                     timeoutMs: 60000,
                 },
             },
+            ...(lintShellCommands.length > 0 && lintVerifyEvidence
+                ? [
+                    {
+                        id: "frontend-lint-baseline-shell",
+                        depends_on: ["frontend-prewrite-gate-shell"],
+                        role: "verifier",
+                        executor: "shell",
+                        complexity: "LOW",
+                        writePolicy: "read-only",
+                        allowedPaths: readOnlyPaths,
+                        forbiddenPaths,
+                        outputContract: "Capture writer-preceding lint output as frontend-lint-baseline-v1 without treating existing lint diagnostics as writer failure.",
+                        subtask_prompt: "Run the frozen lint commands read-only. Preserve raw output and mark the baseline unavailable on timeout, execution failure, unparseable output, or worktree mutation.",
+                        shell: {
+                            commands: lintShellCommands,
+                            frontendLintBaseline: {
+                                schemaVersion: 1,
+                                lintCommands: lintShellCommands,
+                                lintEvidence: lintVerifyEvidence,
+                            },
+                            cwd: ".",
+                            timeoutMs: 300000,
+                        },
+                    },
+                ]
+                : []),
             {
                 id: implementId,
                 depends_on: [
                     "frontend-prewrite-gate-shell",
+                    ...(lintShellCommands.length > 0
+                        ? ["frontend-lint-baseline-shell"]
+                        : []),
                     "frontend-plan-revision-pi",
                     "frontend-final-design-review-pi",
                     "frontend-plan-pi",
@@ -2098,11 +2331,17 @@ function buildFrontendHybridDagFromTask(sources) {
                     frontendVerificationBundle: {
                         schemaVersion: 1,
                         mockCommands: mockShellCommands,
+                        lintCommands: lintShellCommands,
                         staticCommands: staticShellCommands,
                         behaviorCommands: behaviorShellCommands,
                         mockEvidence: mockVerifyEvidence,
+                        lintEvidence: lintVerifyEvidence,
                         staticEvidence: staticVerifyEvidence,
                         behaviorEvidence: behaviorVerifyEvidence,
+                        lintBaselineNodeId: lintShellCommands.length > 0
+                            ? "frontend-lint-baseline-shell"
+                            : undefined,
+                        writerNodeIds: lintShellCommands.length > 0 ? [implementId] : [],
                         mode: "initial",
                     },
                     cwd: ".",
@@ -2151,11 +2390,19 @@ function buildFrontendHybridDagFromTask(sources) {
                     frontendVerificationBundle: {
                         schemaVersion: 1,
                         mockCommands: mockShellCommands,
+                        lintCommands: lintShellCommands,
                         staticCommands: staticShellCommands,
                         behaviorCommands: behaviorShellCommands,
                         mockEvidence: mockVerifyEvidence,
+                        lintEvidence: lintVerifyEvidence,
                         staticEvidence: staticVerifyEvidence,
                         behaviorEvidence: behaviorVerifyEvidence,
+                        lintBaselineNodeId: lintShellCommands.length > 0
+                            ? "frontend-lint-baseline-shell"
+                            : undefined,
+                        writerNodeIds: lintShellCommands.length > 0
+                            ? [implementId, "frontend-repair-pi"]
+                            : [],
                         mode: "repair",
                     },
                     cwd: ".",
@@ -2177,11 +2424,11 @@ function buildFrontendHybridDagFromTask(sources) {
                 writePolicy: "read-only",
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
-                outputContract: "Canonical frontend review context containing validated contract, effective verification trace, repair assessment, and actual worktree diff.",
+                outputContract: "Canonical frontend review context containing validated contract, lint assessment when configured, effective verification trace, repair assessment, and actual worktree diff.",
                 subtask_prompt: "Capture the actual diff and bind it to the effective initial-or-post-repair verification evidence for final review.",
                 shell: {
                     commands: [],
-                    frontendReviewContext: { schemaVersion: 1 },
+                    frontendReviewContext: { schemaVersion: 1, requireBaseline: true },
                     cwd: ".",
                     timeoutMs: 120000,
                 },
@@ -2213,7 +2460,8 @@ 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.",
-                    "Read contracts/frontend-review-context.json from frontend-review-context-shell. It binds the validated implementation contract, effective initial-or-post-repair verification trace, repair assessment, and the run-owned actual diff (contracts/frontend-worktree-diff.json + artifacts/diff_patch.patch). Do not claim actual diff is missing when those artifacts exist; do not invent a diff from the implementation summary alone. Trace proves command/file/symbol binding only—not semantic correctness.",
+                    "Read contracts/frontend-review-context.json from frontend-review-context-shell. It binds the validated implementation contract, frontend lint assessment when lint is configured, effective initial-or-post-repair verification trace, repair assessment, and the run-owned actual diff (contracts/frontend-worktree-diff.json + artifacts/diff_patch.patch). Do not claim actual diff is missing when those artifacts exist; do not invent a diff from the implementation summary alone. Trace proves command/file/symbol binding only—not semantic correctness.",
+                    "Treat lint status exactly as passed | baseline-debt | failed | unavailable. baseline-debt may continue only with intact evidence and zero diagnostics on writer-changed files; report the tolerated debt count and never rewrite it as lint passed. Typecheck, build, and test still require successful final exits.",
                     "Flag .skip/.only, deleted or weakened tests, unauthorized config changes, Mock-only evidence claimed as real integration, and Browser/visual claims (always not-run in this workflow).",
                     "Use the direct contract and the effective plan/design branch: original plan plus initial pass when revision was skipped, or revised plan plus final design review when revision ran. 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/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists; in that case verify that the real request remains the default and the Real Integration Gap is preserved.",
@@ -2271,7 +2519,7 @@ function buildFrontendHybridDagFromTask(sources) {
                 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 Mock decision/strategy/files/verification/production boundary, changes, verification evidence, review result, known risks, and follow-up.",
-                    "Include a coverage matrix for each requirement id, applicable UI state, and verification target/check with status passed|failed|not-run|blocked|unavailable. Always state Browser accessibility verification: not-run and Visual regression: not-run. Use contracts/frontend-review-context.json and the effective frontend-verify-assess-shell or frontend-reverify-shell facts; do not invent Browser evidence from component tests.",
+                    "Include a coverage matrix for each requirement id, applicable UI state, and verification target/check with status passed|failed|not-run|blocked|unavailable. Report lint separately as passed|baseline-debt|failed|unavailable; baseline-debt is explicit debt, not passed. Always state Browser accessibility verification: not-run and Visual regression: not-run. Use contracts/frontend-review-context.json and the effective frontend-verify-assess-shell or frontend-reverify-shell facts; do not invent Browser evidence from component tests.",
                     `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.`,
                     `When Mock was skipped in auto mode and no real API evidence passed, state exactly Frontend status: locally-validated and Real integration: pending, summarize the Real Integration Gap, and name ${taskConfig.taskId}-real-api-integration-verify as the explicit follow-up task when backend readiness matters.`,
                     "Read-only: do not modify code, docs, artifacts, or .harness/dag-runs/.",
@@ -3100,7 +3348,7 @@ async function buildBackendTestHybridDag(sources) {
         'mkdir -p "${HARNESS_DAG_RUN_DIR}/reports"',
         'echo "pytest targets are resolved at runtime from final Markdown 自动化映射"',
     ].join("; ");
-    const execute = shellNode("execute-backend-pytest-and-html-report-shell", [traceability.id], "markdown-execute-html", "Resolve the final Markdown Automation Notes/自动化映射 to a unique, safe set of testcase/**/test_*.py targets and execute only those scripts exactly once. Validate JUnit, then render the primary self-contained Chinese HTML report from the same JUnit plus final Markdown case metadata without rerun. Keep 测试结论, quality status, failure overview, and a polished per-case result card with concise scenario, automation test name, result, duration, and redacted bounded HTTP request parameters/response results for both passed and failed cases. Do not render a technical/execution evidence section in HTML; retain auditable paths and hashes in facts.", "One scoped pytest execution over Markdown-mapped scripts producing valid JUnit with per-case captured output, self-contained HTML and reports/backend-test-facts.md; exit 0/1 with valid evidence continues.", [pytestCommand], 300000);
+    const execute = shellNode("execute-backend-pytest-and-html-report-shell", [traceability.id], "markdown-execute-html", "Resolve the final Markdown Automation Notes/自动化映射 to a unique, safe set of testcase/**/test_*.py targets and execute only those scripts exactly once. Validate JUnit, then render the primary self-contained Chinese HTML report from the same JUnit plus final Markdown case metadata without rerun. Keep 测试结论, quality status, failure overview, and a polished per-case result card with concise scenario, automation test name, result, duration, and redacted bounded HTTP request parameters/response results for both passed and failed cases. Do not render a technical/execution evidence section in HTML; retain auditable paths and hashes in facts.", "One scoped pytest execution over Markdown-mapped scripts producing valid JUnit with per-case captured output, self-contained HTML, reports/backend-test.md and reports/backend-test-facts.md; exit 0/1 with valid evidence continues.", [pytestCommand], 300000);
     if (execute.shell) {
         execute.shell.envAllowlist = collectBackendTestShellEnvAllowlist(sources);
     }
@@ -3175,51 +3423,52 @@ function buildFrontendTestHybridDag(sources) {
     const evidenceRoot = "testcase/frontend/evidence";
     const declaredAcIdsLiteral = JSON.stringify(declaredAcIds);
     const maxCasesPerBatchLiteral = String(config.maxCasesPerBatch);
+    const checklistScript = [
+        "const fs=require('fs'),path=require('path');",
+        "const root='testcase/frontend/cases';",
+        "const draft=path.join(root,'manifest.draft.json');",
+        "const final=path.join(root,'manifest.json');",
+        "const manifestPath=fs.existsSync(draft)?draft:(fs.existsSync(final)?final:null);",
+        "if(!manifestPath)throw new Error('checklist: missing manifest.draft.json or manifest.json');",
+        "const manifest=JSON.parse(fs.readFileSync(manifestPath,'utf8'));",
+        "if(!Array.isArray(manifest.cases)||manifest.cases.length===0)throw new Error('checklist: empty cases');",
+        `const declaredAc=new Set(${declaredAcIdsLiteral});`,
+        "const issues=[];",
+        "const openRe=/playwright-cli\\s+open\\s+--browser=chrome\\s+--headed\\s+https?:\\/\\/\\S+/i;",
+        "const prodRe=/(?:^|\\/\\/)(?:www\\.)?[^\\s\\/]*(?:prod|production)/i;",
+        "const caseIdRe=/^FE-[A-Za-z0-9][A-Za-z0-9-]*$/;", ,
+        "const acIdRe=/^AC(?:-[A-Z0-9]+)+$/i;",
+        "for(const c of manifest.cases){",
+        " const id=c&&c.caseId||'?';",
+        " if(typeof c.caseId!=='string'||!caseIdRe.test(c.caseId))issues.push({ruleId:'case-id-shape',caseId:id,detail:'caseId must be FE-<FEATURE>-<NNN>-<dimension>, never AC-FE-*'});",
+        " if(typeof c.caseId==='string'&&/^AC-/i.test(c.caseId))issues.push({ruleId:'case-id-is-ac',caseId:id,detail:'do not use acceptance id as caseId; put AC-FE-* only in acIds'});",
+        " const casePath=typeof c.casePath==='string'?c.casePath:null;",
+        " if(!casePath||!fs.existsSync(casePath)){issues.push({ruleId:'case-file-missing',caseId:id,detail:String(casePath)});continue;}",
+        " if(typeof c.caseId==='string'&&casePath!=='testcase/frontend/cases/'+c.caseId+'.md')issues.push({ruleId:'case-path-mismatch',caseId:id,detail:casePath+' must equal testcase/frontend/cases/'+c.caseId+'.md'});",
+        " const body=fs.readFileSync(casePath,'utf8');",
+        " if(!openRe.test(body))issues.push({ruleId:'open-prefix',caseId:id,detail:'missing playwright-cli open --browser=chrome --headed <absolute-url>; playwright-cli is strongly recommended for browser execution'});", ,
+        " const m=body.match(/playwright-cli\\s+open\\s+--browser=chrome\\s+--headed\\s+(https?:\\/\\/\\S+)/i);",
+        " if(m){const url=m[1].replace(/[)\\]},.\"']+$/,''); if(prodRe.test(url))issues.push({ruleId:'production-url',caseId:id,detail:url});}",
+        " if(!Array.isArray(c.acIds)||c.acIds.length===0)issues.push({ruleId:'ac-mapping',caseId:id,detail:'acIds required (AC-FE-* acceptance ids, not caseId)'});",
+        " else {",
+        "  for(const ac of c.acIds){",
+        "   if(typeof ac!=='string'){issues.push({ruleId:'ac-id-shape',caseId:id,detail:String(ac)+' must look like AC-FE-001'});continue;}",
+        "   if(/^FE-/i.test(ac)){issues.push({ruleId:'ac-id-is-case',caseId:id,detail:ac+' looks like caseId; acIds must be AC-*'});continue;}",
+        "   if(!acIdRe.test(ac)){issues.push({ruleId:'ac-id-shape',caseId:id,detail:ac+' must look like AC-FE-001'});continue;}",
+        "   if(declaredAc.size>0&&!declaredAc.has(ac))issues.push({ruleId:'unknown-ac',caseId:id,detail:ac+' not in task sourceBinding.requirementIds'});",
+        "  }",
+        " }",
+        "}",
+        "if(issues.length){console.error('frontend-test checklist blocked: '+JSON.stringify(issues)); process.exit(1);}",
+        "console.log('frontend-test checklist ok cases='+manifest.cases.length+' source='+path.basename(manifestPath));",
+    ].join("");
+    // Pass generated JavaScript as base64 rather than embedding it inside a
+    // shell-quoted `node -e` argument. Git Bash otherwise consumes backslashes
+    // such as \\s/\\d and interprets Markdown backticks before Node sees them.
+    const checklistScriptBase64 = Buffer.from(checklistScript, "utf8").toString("base64");
     const checklistValidation = [
-        "node -e",
-        JSON.stringify([
-            "const fs=require('fs'),path=require('path');",
-            "const root='testcase/frontend/cases';",
-            "const draft=path.join(root,'manifest.draft.json');",
-            "const final=path.join(root,'manifest.json');",
-            "const manifestPath=fs.existsSync(draft)?draft:(fs.existsSync(final)?final:null);",
-            "if(!manifestPath)throw new Error('checklist: missing manifest.draft.json or manifest.json');",
-            "const manifest=JSON.parse(fs.readFileSync(manifestPath,'utf8'));",
-            "if(!Array.isArray(manifest.cases)||manifest.cases.length===0)throw new Error('checklist: empty cases');",
-            `const declaredAc=new Set(${declaredAcIdsLiteral});`,
-            "const issues=[];",
-            "const openRe=/playwright-cli\\s+open\\s+--browser=chrome\\s+--headed\\s+https?:\\/\\/\\S+/i;",
-            "const prodRe=/(?:^|\\/\\/)(?:www\\.)?[^\\s\\/]*(?:prod|production)/i;",
-            "const codeRe=/\\b(pytest|playwright\\.test|@playwright\\/test)\\b/i;",
-            "const barePwRe=/(?:^|[\\s\"'(])(?:npx\\s+playwright\\b|playwright\\s+test\\b|from\\s+['\"]@playwright\\/|require\\(['\"]@playwright\\/|import\\s+.*@playwright\\/|(?<![\\w-])playwright(?!-cli)\\b)/i;",
-            "const caseIdRe=/^FE-[A-Za-z0-9][A-Za-z0-9-]*$/;",
-            "const acIdRe=/^AC(?:-[A-Z0-9]+)+$/i;",
-            "for(const c of manifest.cases){",
-            " const id=c&&c.caseId||'?';",
-            " if(typeof c.caseId!=='string'||!caseIdRe.test(c.caseId))issues.push({ruleId:'case-id-shape',caseId:id,detail:'caseId must be FE-<FEATURE>-<NNN>-<dimension>, never AC-FE-*'});",
-            " if(typeof c.caseId==='string'&&/^AC-/i.test(c.caseId))issues.push({ruleId:'case-id-is-ac',caseId:id,detail:'do not use acceptance id as caseId; put AC-FE-* only in acIds'});",
-            " const casePath=typeof c.casePath==='string'?c.casePath:null;",
-            " if(!casePath||!fs.existsSync(casePath)){issues.push({ruleId:'case-file-missing',caseId:id,detail:String(casePath)});continue;}",
-            " if(typeof c.caseId==='string'&&casePath!=='testcase/frontend/cases/'+c.caseId+'.md')issues.push({ruleId:'case-path-mismatch',caseId:id,detail:casePath+' must equal testcase/frontend/cases/'+c.caseId+'.md'});",
-            " const body=fs.readFileSync(casePath,'utf8');",
-            " if(!openRe.test(body))issues.push({ruleId:'open-prefix',caseId:id,detail:'missing playwright-cli open --browser=chrome --headed <absolute-url>'});",
-            " const m=body.match(/playwright-cli\\s+open\\s+--browser=chrome\\s+--headed\\s+(https?:\\/\\/\\S+)/i);",
-            " if(m){const url=m[1].replace(/[)\\]},.\"']+$/,''); if(prodRe.test(url))issues.push({ruleId:'production-url',caseId:id,detail:url});}",
-            " if(codeRe.test(body))issues.push({ruleId:'no-test-source',caseId:id,detail:'pytest/playwright test source forbidden'});",
-            " if(barePwRe.test(body))issues.push({ruleId:'playwright-cli-only',caseId:id,detail:'only playwright-cli skill commands allowed; bare Playwright CLI/API/test runner forbidden'});",
-            " if(!Array.isArray(c.acIds)||c.acIds.length===0)issues.push({ruleId:'ac-mapping',caseId:id,detail:'acIds required (AC-FE-* acceptance ids, not caseId)'});",
-            " else {",
-            "  for(const ac of c.acIds){",
-            "   if(typeof ac!=='string'){issues.push({ruleId:'ac-id-shape',caseId:id,detail:String(ac)+' must look like AC-FE-001'});continue;}",
-            "   if(/^FE-/i.test(ac)){issues.push({ruleId:'ac-id-is-case',caseId:id,detail:ac+' looks like caseId; acIds must be AC-*'});continue;}",
-            "   if(!acIdRe.test(ac)){issues.push({ruleId:'ac-id-shape',caseId:id,detail:ac+' must look like AC-FE-001'});continue;}",
-            "   if(declaredAc.size>0&&!declaredAc.has(ac))issues.push({ruleId:'unknown-ac',caseId:id,detail:ac+' not in task sourceBinding.requirementIds'});",
-            "  }",
-            " }",
-            "}",
-            "if(issues.length){console.error('frontend-test checklist blocked: '+JSON.stringify(issues)); process.exit(1);}",
-            "console.log('frontend-test checklist ok cases='+manifest.cases.length+' source='+path.basename(manifestPath));",
-        ].join("")),
+        "node -e \"eval(Buffer.from(process.argv[1],'base64').toString('utf8'))\"",
+        checklistScriptBase64,
     ].join(" ");
     const manifestValidation = [
         "node -e",
@@ -3260,6 +3509,23 @@ function buildFrontendTestHybridDag(sources) {
     // Heal malformed/missing case evidence to blocked; only unsafe evidenceDir hard-fails.
     const evidenceValidation = buildFrontendCaseEvidenceValidateShellSnippet();
     const frontendTestOutcomeGate = buildFrontendTestOutcomeGateShellSnippet();
+    const frontendCaseQualityAdvisory = [
+        "node -e",
+        JSON.stringify([
+            "const fs=require('fs'),path=require('path');",
+            "const runDir=process.env.HARNESS_DAG_RUN_DIR; if(!runDir)throw new Error('missing HARNESS_DAG_RUN_DIR');",
+            "const resultPath=path.join(runDir,'contracts','frontend-test-result.json'); if(!fs.existsSync(resultPath))throw new Error('missing '+resultPath);",
+            "const r=JSON.parse(fs.readFileSync(resultPath,'utf8')); const findings=Array.isArray(r.advisoryFindings)?r.advisoryFindings:[];",
+            "const reports='testcase/frontend/reports'; fs.mkdirSync(reports,{recursive:true});",
+            "const esc=v=>String(v??'').replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;').replaceAll('\\\"','&quot;');",
+            "const labels={cases:'用例总数',passed:'通过',failed:'失败',blocked:'阻塞'}; const totals=r.totals||{}; const missing=r.acceptanceCoverage&&Array.isArray(r.acceptanceCoverage.missing)?r.acceptanceCoverage.missing:[];",
+            "const md=['# 前端测试质量建议报告','','> Advisory：以下 finding 用于改进测试资产和证据质量，不阻塞后续流程。','','## 执行摘要','',...Object.entries(labels).map(([k,v])=>'- '+v+': '+Number(totals[k]||0)),'- 执行结果: '+String(r.outcome||'unknown'),'- 缺失 AC: '+(missing.join(', ')||'无'),'','## 建议项','',...(findings.length?findings.map(f=>'- ['+f.ruleId+']'+(f.caseId?' '+f.caseId:'')+': '+f.detail):['- 未发现建议项。']),''];",
+            "fs.writeFileSync(path.join(reports,'frontend-test-case-quality-advisory.md'),md.join('\\n'));",
+            "const rows=findings.length?findings.map(f=>'<tr><td><code>'+esc(f.ruleId)+'</code></td><td>'+esc(f.caseId||'-')+'</td><td>'+esc(f.detail)+'</td></tr>').join(''):'<tr><td colspan=3>未发现建议项。</td></tr>';",
+            "const html='<!doctype html><html lang=\\\"zh-CN\\\"><head><meta charset=\\\"utf-8\\\"><meta name=\\\"viewport\\\" content=\\\"width=device-width,initial-scale=1\\\"><title>前端测试质量建议报告</title><style>body{font:16px system-ui,Microsoft YaHei,sans-serif;background:#f5f7fb;color:#172033;margin:0;padding:32px}main{max-width:1100px;margin:auto;background:#fff;padding:32px;border-radius:16px}.badge{display:inline-block;padding:6px 10px;border-radius:999px;background:#fff3cd;color:#946200}.grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:12px}.card{padding:16px;background:#f8fafc;border-radius:10px}table{width:100%;border-collapse:collapse}th,td{text-align:left;padding:10px;border-bottom:1px solid #e5e7eb}code{color:#475467}@media(max-width:700px){.grid{grid-template-columns:1fr 1fr}}</style></head><body><main><h1>前端测试质量建议报告</h1><p><span class=\\\"badge\\\">Advisory，不阻塞后续流程</span></p><h2>执行摘要</h2><div class=\\\"grid\\\">'+Object.entries(labels).map(([k,v])=>'<div class=\\\"card\\\"><strong>'+v+'</strong><div>'+Number(totals[k]||0)+'</div></div>').join('')+'</div><p>执行结果：'+esc(r.outcome||'unknown')+'；缺失 AC：'+esc(missing.join(', ')||'无')+'</p><h2>建议项</h2><table><thead><tr><th>规则</th><th>Case ID</th><th>说明与建议</th></tr></thead><tbody>'+rows+'</tbody></table></main></body></html>';",
+            "fs.writeFileSync(path.join(reports,'frontend-test-case-quality-advisory.html'),html); console.log('frontend-test advisory report findings='+findings.length);",
+        ].join("")),
+    ].join(" ");
     const tasks = [
         {
             id: "retrieve-frontend-test-context-pi",
@@ -3413,8 +3679,8 @@ function buildFrontendTestHybridDag(sources) {
         writePolicy: "read-only",
         allowedPaths: [...ragWriteSet, ...casesWriteSet],
         forbiddenPaths: forbidden,
-        outputContract: "Mechanical checklist: open-prefix, non-prod absolute URL, acIds, playwright-cli-only, no pytest/playwright test source; emit structured ruleId issues on failure.",
-        subtask_prompt: "Scan generated cases/manifest against the shared blocking checklist. Do not use free-form LLM verdicts.",
+        outputContract: "Mechanical checklist: manifest/case paths, Case ID, non-production playwright-cli open prefix, and AC mapping; alternative executable tool commands are not inspected or blocked.",
+        subtask_prompt: "Scan generated cases/manifest for structural and safety rules only. Strongly recommend playwright-cli for browser execution, but do not inspect or reject alternative executable tool commands and do not use free-form LLM verdicts.",
         shell: { commands: [checklistValidation], cwd: ".", timeoutMs: 120000 },
     }, {
         id: "materialize-frontend-case-manifest-shell",
@@ -3548,6 +3814,20 @@ function buildFrontendTestHybridDag(sources) {
         outputContract: "Write frontend-test retrospective under testcase/frontend/reports/frontend-test-retrospect-<date>.md with coverage, pass/fail/blocked, execution evidence review, risks, findings, and A/B/C/D rating — even when outcome is failed/incomplete. Pipeline acceptance = this report exists (not case 100% pass).",
         subtask_prompt: "Write the frontend test retrospective under testcase/frontend/reports/ after result materialization (do not wait for outcome=pass). Combine AC→case→browser-evidence review with the closeout report: coverage, passed/failed/blocked (including token-budget-exhausted / executor-auth-unavailable), evidence gaps, browser anomalies, residual risks, and A/B/C/D rating. Passed cases need assertion plus screenshot or equivalent evidence when available; failed/blocked need explicit reasons. Blocked cases never count as passed. Do not replace browser evidence with model conclusions. Do not write docs/**. Pipeline success is report production, not case full green.",
     });
+    tasks.push({
+        id: "frontend-test-quality-report-html-shell",
+        depends_on: ["frontend-test-retrospect-pi"],
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "exclusive",
+        writeSet: ["testcase/frontend/reports/**"],
+        allowedPaths: ["testcase/frontend/**"],
+        forbiddenPaths: forbidden,
+        outputContract: "Write a user-readable HTML advisory report after the final Markdown retrospective; findings never block the workflow.",
+        subtask_prompt: "Generate the frontend case quality advisory Markdown and HTML report after the final test report. Record content findings only and never fail because findings exist.",
+        shell: { commands: [frontendCaseQualityAdvisory], cwd: ".", timeoutMs: 120000 },
+    });
     const globalConstraints = [
         ...sources.taskConfig.hardConstraints,
         ...STANDARD_GLOBAL_CONSTRAINTS,
@@ -4570,7 +4850,7 @@ async function buildHybridDagForTemplate(sources, template) {
     const taskContractBinding = await resolveTaskContractBindingForGenerate(sources);
     let spec;
     if (template === "frontend-implementation") {
-        spec = buildFrontendHybridDagFromTask(sources);
+        spec = await buildFrontendHybridDagFromTask(sources);
     }
     else if (template === "frontend-test-dag")
         spec = buildFrontendTestHybridDag(sources);