@tea-agent/loop-agent 0.44.0-next.10 → 0.44.0-next.12

package/dist/workflows/dag/hybrid/templates/frontend.js

@@ -0,0 +1,1529 @@
+/** DAG hybrid frontend-implementation 模板族：writer/review/design 节点装配与 mock 阻断 DAG。 */
+import path from "node:path";
+import { inspectFrontendTestCommand } from "../../frontend-test-execution-evidence.js";
+import { createHash } from "node:crypto";
+import { frontendExecutionPolicySchema } from "../../../../shared/frontend-execution-policy.js";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { assertValidDagSpec } from "../../validate.js";
+import { DEFAULT_DAG_EXECUTOR_MODELS, DEFAULT_DAG_OUTPUT_LANGUAGE, parseDagSpec } from "../../types.js";
+import { DEFAULT_FRONTEND_SPEC_ROOTS, DEFAULT_OPENSPEC_GOVERNANCE_ROOT, extractTaskSourceFrontendSpecPaths } from "../../../../shared/openspec-spec.js";
+import { readFrontendSpecRegistry, scoreFrontendSpecCandidate } from "../../../../task/frontend-project-capability.js";
+import { DEFAULT_READ_ONLY_PI_RETRY_POLICY, FRONTEND_PLAN_LADDER_RETRY_POLICY, FRONTEND_REVIEW_TERMINAL_RETRY_POLICY, FRONTEND_SCOUT_COMPLETENESS_RETRY_POLICY } from "../../retry-policy.js";
+import { DEFAULT_VERIFY_TIMEOUT_MS } from "../../../../executors/shell-verification.js";
+import { classifyFrontendRisk } from "../../frontend-risk.js";
+import { resolveFrontendSpecRootAliases } from "../../frontend-project-capability.js";
+import { buildFrontendImplementationContractSkeleton, buildFrontendVerifyCommandDirectory, classifyFrontendVerifyCommandText } from "../../frontend-implementation-contract.js";
+import { computeFrontendShapeSourceDigest, parseFrontendShapeTransitionCapsule, resolveFrontendTaskShape } from "../../frontend-shape.js";
+import { FRONTEND_NO_VERIFICATION_MARKER_TEXT } from "../../frontend-verification-trace.js";
+import { resolveWriterComplexity, writerDeliveryContract } from "../types.js";
+import { FRONTEND_BOUNDED_IMPLEMENT_SKILLS, FRONTEND_CONTRACT_SKILLS, FRONTEND_DEFAULTS, FRONTEND_DESIGN_REVIEW_SKILLS, FRONTEND_PLAN_SKILLS, FRONTEND_REVIEW_SKILLS, FRONTEND_SCOUT_SKILLS, FRONTEND_SKILLS_BY_ROLE, GENERATED_DAG_RUNTIME_CONTRACT, STANDARD_GLOBAL_CONSTRAINTS, buildDagSourceBinding, buildExplicitFrontendVerifyCommands, buildSourceContextBlock, buildVerifyEvidence, buildVerifyShellCommands, collectDeclaredDependencies, discoverFrontendFallbackVerifyCommands, extractFrontendVerifyCommandsFromMarkdown, extractObjective, extractSuccessCriteria, frontendSourceMentionsMock, hasApiDependency, mergeForbiddenPaths, partitionFrontendStaticVerifyCommands, resolveDagVerifyStrategy, resolveFrontendMockMode, resolveImplementPaths, verifyCommandKey } from "../sources.js";
+import { applyDefaultReadOnlyRetryPolicy, mapTaskComplexity, stampGeneratedArtifactBindings, } from "./shared.js";
+export function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, fixedVerificationContext, readOnlyPaths, forbiddenPaths) {
+    const configuredPolicy = sources.taskConfig.frontendMock?.policy ?? "auto";
+    const mockMode = sources.frontendMockMode ?? "not-required";
+    const capabilityStatus = sources.frontendMockCapability?.status;
+    const autoMaySkipMissingMock = configuredPolicy === "auto" &&
+        mockMode === "not-required" &&
+        (capabilityStatus === "absent" || capabilityStatus === "ambiguous");
+    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_PLAN_SKILLS,
+        firstProtocolLine: "MOCK_STRATEGY:",
+        outputContract: "Plain Markdown whose first 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 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. Do not emit blank lines, headings, or explanatory preamble before it.",
+            "Do not wrap the first line in Markdown bullets, quotes, emphasis, code fences, inline code, Chinese punctuation, or a split label/value form. Put any headings or explanation only after the exact first line.",
+            "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.",
+            autoMaySkipMissingMock
+                ? "Auto mode may skip Mock when no project Mock capability is confirmed. Select not-needed with positive evidence from contract/scout that no project Mock capability is confirmed, continue without adding Mock files or dependencies, run the fixed verification entrypoints, and record any unproved real API behavior in Real Integration Gap. Do not block solely because no project Mock capability, browser interception harness, or request adapter exists."
+                : "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.",
+            ...(autoMaySkipMissingMock
+                ? [
+                    "- In auto mode with no confirmed project Mock capability, do not block solely because Mock is unavailable or Mock-specific verification is absent; choose not-needed and make the Real Integration Gap explicit unless project specs require Mock or another safety rule is violated.",
+                ]
+                : []),
+            "- 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"),
+    };
+}
+export 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,
+        },
+    };
+}
+export 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: [],
+                commandTexts: commands,
+                commandTimeoutMs: DEFAULT_VERIFY_TIMEOUT_MS,
+                preflight: sources.verificationPreflight,
+            }),
+            cwd: ".",
+            timeoutMs: DEFAULT_VERIFY_TIMEOUT_MS,
+        },
+    };
+}
+export function buildBlockedFrontendMockDag(sources, readOnlyPaths, forbiddenPaths, globalConstraints, blockedReason) {
+    const { taskConfig } = sources;
+    const reason = blockedReason ?? "Mock contract is blocked by deterministic generation-time Mock safety constraints.";
+    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-mock-blocked-shell",
+                depends_on: [],
+                role: "verifier",
+                executor: "shell",
+                complexity: "LOW",
+                writePolicy: "read-only",
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                outputContract: "Deterministic generation-time Mock blocker. Always exits nonzero and never reaches a writer.",
+                subtask_prompt: `Fail closed: ${reason} Resolve the task contract and regenerate the DAG.`,
+                shell: {
+                    commands: [
+                        `node -e ${JSON.stringify(`console.error(${JSON.stringify(`frontend Mock contract blocked: ${reason}`)}); process.exit(1)`)}`,
+                    ],
+                    cwd: ".",
+                    timeoutMs: 60000,
+                },
+            },
+        ],
+    };
+    applyDefaultReadOnlyRetryPolicy(spec);
+    stampGeneratedArtifactBindings(spec);
+    parseDagSpec(spec);
+    assertValidDagSpec(spec);
+    return spec;
+}
+export 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") {
+        if (frontendMockStrategyMustBeNotNeeded(sources)) {
+            parts.push('Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed when Mock is intentionally skipped. Auto mode has no confirmed project Mock capability or no deterministic Mock verification command. The structured contract must set mockApi.strategy to "not-needed". Keep the real request path as the default, record any unproved backend behavior as Real Integration Gap, and do not add Mock files or dependencies within this run.');
+            parts.push('HARD CONSTRAINT (frozen at generation time): this DAG allows only mockApi.strategy "not-needed"; the prewrite gate rejects any other strategy. If project governance (openspec / ai_workspace / decision records, e.g. a DEC rule requiring native) demands Mock-backed verification, that is a generation-time contract gap, not a plan-revision defect: declare frontendMock.verifyCommands (or policy: "required") in task.json and regenerate the DAG.');
+        }
+        else {
+            parts.push("Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed when Mock is intentionally skipped, or select a safe Mock strategy if project evidence supports one.");
+        }
+    }
+    if (mode === "blocked") {
+        parts.push("Mock contract is blocked. The DAG must stop before any write node executes.");
+    }
+    return parts.join("\n");
+}
+export async 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, {
+        repoRoot: sources.repoRoot,
+    });
+    const implementId = frontendImplementationNodeId();
+    const mockContextBlock = resolveFrontendMockContextBlock(frontendSources);
+    const capabilityContextBlock = resolveFrontendCapabilityContextBlock(frontendSources);
+    // Freeze the design-policy dependency allowlist from the project manifest:
+    // already-declared deps are authorized; anything else in the model's
+    // dependency policy that looks like a package name is an unauthorized new
+    // dependency (fail-closed at the policy shell and the plan pre-check).
+    const declaredDependencies = await collectDeclaredDependencies(sources.repoRoot ?? process.cwd());
+    const frontendRisk = frontendSources.frontendRisk ??
+        classifyFrontendRisk({
+            title: taskConfig.title,
+            requirementMarkdown: sources.requirementMarkdown,
+            constraintMarkdown: sources.constraintMarkdown ?? undefined,
+            allowedPaths: taskConfig.allowedPaths,
+            complexity: taskConfig.complexity,
+        });
+    const frontendTaskShape = resolveFrontendTaskShape({
+        complexity: taskConfig.complexity,
+        allowedPaths: taskConfig.allowedPaths,
+        requirementMarkdown: sources.requirementMarkdown,
+        constraintMarkdown: sources.constraintMarkdown ?? undefined,
+        splitSignal: { splitRequired: false, runtimeSupportsSplit: true },
+        taskId: sources.taskId,
+        sourceDigest: computeFrontendShapeSourceDigest({
+            requirementMarkdown: sources.requirementMarkdown,
+            constraintMarkdown: sources.constraintMarkdown ?? "",
+        }),
+        shapeTransitionCapsule: resolveFrontendShapeCapsuleGenerationInput(sources),
+    });
+    const frontendSourceBinding = buildDagSourceBinding(sources, taskConfig.taskKind);
+    const frontendContractSkeleton = buildFrontendImplementationContractSkeleton({
+        sourceBinding: frontendSourceBinding,
+        riskLevel: frontendRisk.selectedRisk,
+        targetFiles: implementPaths.writeSet,
+    });
+    const frontendContractFieldSummary = [
+        "## Contract field summary (authoritative JSON; no plan prose)",
+        "frontend-plan-pi records typed facts; frontend-design-policy-shell applies the runtime skeleton, validates, and materializes the canonical full contract JSON supplied here. There is no separate plan prose authority. Review these fields:",
+        "- requirements[]: id, expectedOutcome, implementationTargets, verificationTargetIds, evidenceGap",
+        "- uiStates[]: name, applicable, expectedBehavior, implementationTargets, verificationTargetIds, notApplicableReason",
+        "- interactions[]: name, trigger, expectedBehavior, implementationTargets, verificationTargetIds",
+        "- targets: routes, publicApiChanges (files are runtime-owned)",
+        "- mockApi: strategy, productionDefaultOff, activation, endpoints[]",
+        "- verificationTargets[]: id (stable target identity; execution binds commandId + file, never test titles), commandId (frozen directory key), mode + commandLabel (runtime-resolved), file, requirementIds, uiStates, scope? (display-only)",
+        "- designEvidence: source, paths, conflicts; evidenceGaps[] (optional)",
+        "- optional: stylingStrategy, uiComponentChoices[], dependencyPolicy, residualRisks[], realIntegrationGap",
+        "- uiComponentChoices[]: purpose, component, decision (specified|reuse-existing|new), specReference { path, section, line } | null, rationale",
+        "Do not require or read a separate plan prose section; the contract JSON is the only plan surface.",
+    ].join("\n");
+    // Do not carry every attachment through the whole frontend pipeline. The
+    // contract node is the sole requirements/materials synthesis point; scout
+    // and plan only need the canonical request plus constraints, while design
+    // review consumes the materialized contract and only needs source provenance.
+    // This prevents attachment content from accumulating on later review calls.
+    const sourceContexts = {
+        contract: [buildSourceContextBlock(sources), capabilityContextBlock]
+            .filter(Boolean)
+            .join("\n\n"),
+        scout: [
+            buildSourceContextBlock(sources, { includeRequirementExcerpt: false, includeConstraintExcerpt: false, includeReferenceDocuments: false }),
+            capabilityContextBlock,
+        ]
+            .filter(Boolean)
+            .join("\n\n"),
+        designReview: buildSourceContextBlock(sources, {
+            includeRequirementExcerpt: false,
+            includeConstraintExcerpt: false,
+            includeReferenceDocuments: false,
+        }),
+    };
+    const hasMockVerifyCommands = (taskConfig.frontendMock?.verifyCommands.length ?? 0) > 0 ||
+        mockCapability.verifyCommands.length > 0;
+    const requirementIds = frontendSourceBinding.requirementIds;
+    const strategy = resolveDagVerifyStrategy(taskConfig);
+    const readOnlyPaths = taskConfig.allowedPaths.length > 0 ? taskConfig.allowedPaths : ["**"];
+    const behaviorPaths = deriveFrontendBehaviorPaths(taskConfig);
+    const globalConstraints = [
+        ...taskConfig.hardConstraints,
+        ...(sources.constraintMarkdown
+            ? [`See 执行约束.md in task source (${sources.taskId})`]
+            : []),
+        ...STANDARD_GLOBAL_CONSTRAINTS,
+        "Frontend design policy (frontend-design-policy-shell) and writer admission (frontend-writer-admission-shell) are the only write authorization; the writer runs only after both materialized the canonical contract and admitted a concrete writeSet.",
+        "Design review verdict is consumed only as admission data input; it never drives branch selection.",
+        "Verification failure is terminal for the run: frontend-verify-shell fails closed, routes to recovery, and never selects a same-run repair branch.",
+        "Frontend review is decided exclusively by the committed typed terminal tools (approve_review / request_review_changes); response-text JSON verdicts and first-line VERDICT markers carry no control-flow weight.",
+        "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 before final review. Behavior verification is also required when the task declares a behavior entrypoint or the implementation contract contains a behavior-mode verification target; static-only contracts must map every target to the declared static entrypoint.",
+        "Frontend closeout renders only from committed facts; a weak status (failed / not-run / baseline-debt / mock-backed / pending) can never be rewritten into a stronger one (passed / real-integrated).",
+        `Frontend risk classification: ${frontendRisk.selectedRisk} — ${frontendRisk.reason}`,
+        frontendRisk.forceFullGates
+            ? "High-risk or supervised: keep full design gates; do not weaken write boundaries."
+            : "Risk-aware topology may omit redundant design revision nodes for small tasks only.",
+    ];
+    // Guard: blocked mode — generate assessment-only DAG with no writer reachable
+    if (mockMode === "blocked") {
+        const blockedReason = mockCapability.safetyViolation
+            ? `Mock contract blocked: ${mockCapability.safetyViolation}`
+            : (taskConfig.frontendMock?.policy ?? "auto") === "required"
+                ? "Mock strategy is required, but no authorized Mock verification command was found."
+                : "Mock contract is blocked by deterministic generation-time Mock safety constraints.";
+        return buildBlockedFrontendMockDag(frontendSources, readOnlyPaths, forbiddenPaths, globalConstraints, blockedReason);
+    }
+    const fallbackVerifyCommands = await discoverFrontendFallbackVerifyCommands(sources.repoRoot);
+    // The verification bundle schema requires at least one static command. When
+    // a real project exposes no usable verification command at all, run an
+    // explicit no-op marker instead of a command that is guaranteed to fail:
+    // the trace then records not-run honestly and the advisory asks the task
+    // to declare verification commands and regenerate.
+    const staticFallbackCommands = fallbackVerifyCommands.staticCommands.length > 0
+        ? fallbackVerifyCommands.staticCommands
+        : [FRONTEND_NO_STATIC_VERIFICATION_MARKER];
+    const behaviorFallbackCommands = fallbackVerifyCommands.behaviorCommands;
+    const parsedFrontendVerifyCommands = extractFrontendVerifyCommandsFromMarkdown({
+        repoRoot: sources.repoRoot,
+        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)));
+    // Split adapter commands by lane BEFORE handing them to either lane. The
+    // same array used to be passed to both `chooseFrontendVerifyCommands` calls,
+    // so every adapter command entered static and behavior at once. The behavior
+    // lane is test-observed at writer admission, so a governance script from
+    // harness.json (`bash scripts/check-repo.sh`) demanded test-report
+    // capability it can never have and blocked admission deterministically.
+    // Adapter commands carry no declared lane, so classify them from their text;
+    // an explicit declaration still wins because it is chosen earlier.
+    //
+    // A declared task verifier owns this task's verification boundary and the
+    // adapter array is discarded for both lanes, so an unclassifiable adapter
+    // entry is harmless then and must not fail generation.
+    const hasDeclaredFrontendVerification = explicitFrontendVerifyCommands.staticCommands.length > 0 ||
+        explicitFrontendVerifyCommands.behaviorCommands.length > 0 ||
+        parsedFrontendVerifyCommands.staticCommands.length > 0 ||
+        parsedFrontendVerifyCommands.behaviorCommands.length > 0;
+    const adapterStaticCommands = [];
+    const adapterBehaviorCommands = [];
+    for (const command of adapterVerifyCommands) {
+        // Classify on the bare argv only. The frozen shell form prepends an env
+        // prefix and a `cd …` prologue, which would obscure the runner name.
+        const text = command.args.join(" ");
+        const mode = classifyFrontendVerifyCommandText(text);
+        if (mode === "static") {
+            adapterStaticCommands.push(command);
+            continue;
+        }
+        if (mode === "behavior") {
+            adapterBehaviorCommands.push(command);
+            continue;
+        }
+        // Unrecognized adapter command. When the task declares any verification
+        // of its own, it owns the verification boundary and the adapter array is
+        // discarded for both lanes, so an unclassifiable entry is harmless and
+        // must not fail generation. Only an adapter command that would actually
+        // be USED needs a lane, and defaulting it to `behavior` would make writer
+        // admission demand test-report capability it cannot provide. Fail loudly
+        // there and name the operator's fix.
+        if (hasDeclaredFrontendVerification)
+            continue;
+        throw new Error(`adapter verification command ${JSON.stringify(text)} (label ${JSON.stringify(command.label)}) has no recognizable lane; declare it explicitly with mode: "static" or mode: "behavior" in task verifyCommands, or remove it from the harness manifest`);
+    }
+    const staticVerifyCommands = chooseFrontendVerifyCommands({
+        explicitCommands: explicitFrontendVerifyCommands.staticCommands,
+        parsedCommands: parsedFrontendVerifyCommands.staticCommands,
+        adapterCommands: adapterStaticCommands,
+    });
+    const partitionedStaticVerifyCommands = partitionFrontendStaticVerifyCommands({
+        repoRoot: sources.repoRoot,
+        commands: staticVerifyCommands.commands,
+        commandSource: staticVerifyCommands.commandSource,
+    });
+    const behaviorVerifyCommands = chooseFrontendVerifyCommands({
+        explicitCommands: explicitFrontendVerifyCommands.behaviorCommands,
+        parsedCommands: parsedFrontendVerifyCommands.behaviorCommands,
+        adapterCommands: adapterBehaviorCommands,
+        // A declared task verifier owns this task's verification boundary. A
+        // static-only task must not inherit unrelated root-level test commands.
+        allowAdapter: !hasDeclaredFrontendVerification,
+    });
+    const staticShellCommands = buildVerifyShellCommands({
+        repoRoot: sources.repoRoot,
+        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,
+        fallbackCommands: hasDeclaredFrontendVerification
+            ? []
+            : behaviorFallbackCommands,
+    });
+    const effectiveBehaviorFallbackCommands = hasDeclaredFrontendVerification
+        ? []
+        : behaviorFallbackCommands;
+    const staticVerifyEvidence = buildVerifyEvidence({
+        phase: "intermediate",
+        quota: strategy.intermediateQuota ?? "full",
+        commandSource: partitionedStaticVerifyCommands.static.commandSource,
+        commands: partitionedStaticVerifyCommands.static.commands,
+        fallbackCommands: staticFallbackCommands,
+        commandTexts: staticShellCommands,
+        commandTimeoutMs: DEFAULT_VERIFY_TIMEOUT_MS,
+        preflight: sources.verificationPreflight,
+    });
+    const lintVerifyEvidence = lintShellCommands.length > 0
+        ? buildVerifyEvidence({
+            phase: "intermediate",
+            quota: strategy.intermediateQuota ?? "full",
+            commandSource: partitionedStaticVerifyCommands.lint.commandSource,
+            commands: partitionedStaticVerifyCommands.lint.commands,
+            fallbackCommands: [],
+            commandTexts: lintShellCommands,
+            commandTimeoutMs: DEFAULT_VERIFY_TIMEOUT_MS,
+            preflight: sources.verificationPreflight,
+        })
+        : undefined;
+    const behaviorVerifyEvidence = buildVerifyEvidence({
+        phase: "final",
+        quota: "full",
+        commandSource: behaviorVerifyCommands.commandSource,
+        commands: behaviorVerifyCommands.commands,
+        fallbackCommands: effectiveBehaviorFallbackCommands,
+        commandTexts: behaviorShellCommands,
+        finalFullRequired: true,
+        commandTimeoutMs: DEFAULT_VERIFY_TIMEOUT_MS,
+        preflight: sources.verificationPreflight,
+    });
+    const mockVerifyTemplate = mockMode === "required" && hasMockVerifyCommands
+        ? buildFrontendMockVerifyNode(frontendSources, implementId, readOnlyPaths, forbiddenPaths)
+        : undefined;
+    const mockShellCommands = mockVerifyTemplate?.shell?.commands ?? [];
+    const mockVerifyEvidence = mockVerifyTemplate?.shell?.verifyEvidence;
+    // Contract v2: the frozen command directory is the only command reference
+    // the plan may use. Modes are assigned here once from the generation-time
+    // lane split; downstream materialization resolves the same directory from
+    // the run spec, so plan and runtime can never disagree on a mode.
+    const frontendVerifyDirectory = buildFrontendVerifyCommandDirectory({
+        staticLabels: staticVerifyEvidence.commandLabels,
+        behaviorLabels: behaviorVerifyEvidence.commandLabels,
+        mockLabels: mockVerifyEvidence?.commandLabels ?? [],
+        staticCommandTexts: staticVerifyEvidence.commandTexts,
+        behaviorCommandTexts: behaviorVerifyEvidence.commandTexts,
+        mockCommandTexts: mockVerifyEvidence?.commandTexts ?? [],
+    });
+    // Freeze capability only after final selection; discarded adapter commands
+    // cannot block this task. Unsupported inputs remain explicit preflight
+    // failures and writer admission refuses them before any implementation.
+    behaviorVerifyEvidence.preflight = await Promise.all(behaviorShellCommands.map(async (command, index) => {
+        const label = behaviorVerifyEvidence.commandLabels[index] ?? command;
+        const prior = sources.verificationPreflight?.find(entry => entry.label === label);
+        const inspected = await inspectFrontendTestCommand({ command, cwd: sources.repoRoot ?? process.cwd(), workspaceRoot: sources.repoRoot ?? process.cwd(), allowedPaths: implementPaths.allowedPaths, forbiddenPaths });
+        const commandId = frontendVerifyDirectory.find(entry => entry.mode === "behavior" && entry.label === label)?.commandId;
+        return { label, status: prior?.status ?? "ok", testObservation: { ...inspected.observation, commandId } };
+    }));
+    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.",
+        "Reference frozen commands ONLY by commandId (record_plan_verification_target entry.commandId). The runtime resolves mode and label; never invent a mode or type.",
+        ...frontendVerifyDirectory.map((entry) => `  - ${entry.commandId} [${entry.mode}]: ${JSON.stringify(entry.label)}`),
+        `- Static command source: ${staticVerifyEvidence.commandSource}`,
+        `- Behavior command source: ${behaviorVerifyEvidence.commandSource}`,
+    ].join("\n");
+    const advisories = [];
+    if (!hasDeclaredFrontendVerification &&
+        fallbackVerifyCommands.staticCommands.length === 0 &&
+        fallbackVerifyCommands.behaviorCommands.length === 0) {
+        advisories.push("未发现可用的前端验证命令：目标项目没有可读取的 package.json scripts，也未探测到本地 TypeScript，verify 节点将没有静态/行为命令可执行。请在 task.json --verify 或执行约束.md 的验证约束中显式声明命令（例如 node --check src/app.js），然后重新生成 DAG。");
+    }
+    if (frontendSourceMentionsMock(frontendSources) &&
+        frontendMockStrategyMustBeNotNeeded(frontendSources)) {
+        advisories.push("auto 模式已将 Mock 策略收窄为 not-needed：任务源提到接口/API/Mock 需求，但仓库无确认 Mock 能力或无确定性 Mock 验证命令。若项目规范要求 Mock，请声明 frontendMock.verifyCommands 或 policy:required 后重新生成 DAG。");
+    }
+    const openspecGate = await resolveFrontendOpenspecGateConfig(sources);
+    const requiresOpenspecClassification = openspecGate.openspecPolicy === "cited" &&
+        openspecGate.openspecCandidatePaths.length > 0;
+    // Prompt 内联的候选只保留与任务相关的子集：mandatory（任务显式声明/
+    // 引用）始终保留；scan-strict 候选按路径段是否命中任务源关键词过滤。
+    // runtime 的选型/read 门禁仍消费完整 openspecCandidatePaths——这里只
+    // 减小 prompt 体积，不改变门禁语义；未提及的候选 runtime 默认 irrelevant。
+    const promptCandidatePaths = filterRelevantOpenspecCandidates({
+        candidates: openspecGate.openspecCandidateSummaries.map((candidate) => candidate.path),
+        mandatoryPaths: openspecGate.openspecMandatoryPaths,
+        sourceMarkdown: [
+            sources.requirementMarkdown,
+            sources.constraintMarkdown ?? "",
+        ].join("\n"),
+        maxCandidates: 24,
+    });
+    const candidateByPath = new Map(openspecGate.openspecCandidateSummaries.map((candidate) => [
+        candidate.path,
+        candidate,
+    ]));
+    // Preserve the filter's mandatory/relevance order. Sorting then slicing here
+    // used to be able to drop a mandatory path after it passed the Top-K filter.
+    const promptCandidates = promptCandidatePaths.flatMap((candidatePath) => {
+        const candidate = candidateByPath.get(candidatePath);
+        return candidate
+            ? [
+                {
+                    path: candidate.path,
+                    kind: candidate.kind,
+                    score: candidate.score,
+                    reasons: candidate.reasons,
+                    source: candidate.source,
+                },
+            ]
+            : [];
+    });
+    const openspecSelectionContext = JSON.stringify({
+        schemaVersion: 1,
+        schemaId: "frontend-openspec-selection-v1",
+        candidates: promptCandidates,
+        mandatoryPaths: openspecGate.openspecMandatoryPaths,
+    });
+    const scopedOpenspecContext = promptCandidates.length > 0
+        ? [
+            "## Task-relevant OpenSpec Top-K (generation frozen)",
+            `Policy: ${openspecGate.openspecPolicy}. This is the bounded prompt index; the deterministic gate retains ${openspecGate.openspecCandidatePaths.length} frozen candidates.`,
+            ...promptCandidates.map((candidate) => `- ${openspecGate.openspecMandatoryPaths.includes(candidate.path) ? "mandatory" : "candidate"}: ${candidate.path} (${candidate.kind}; ${candidate.source})`),
+            "Apply or cite only paths relevant to the concrete contract. Report applied rules with path/section/line and surface conflicts or missing specifications; unlisted candidates default to irrelevant unless the deterministic gate requires them.",
+        ].join("\n")
+        : "";
+    // Generation-frozen component/theme specification bucket (ADR 0016). Derived
+    // from the classified component/theme/rule.components buckets; the prewrite
+    // gate consumes it to enforce uiComponentChoices presence and specReference
+    // cross-checking. `src/task/**` classification logic is intentionally
+    // unchanged — these buckets already partition normativePaths.
+    const classified = sources.frontendProjectCapability?.designEvidence.classified;
+    const componentSpecCandidatePaths = [
+        ...(classified?.component ?? []),
+        ...(classified?.theme ?? []),
+        ...(classified?.rule.components ?? []),
+    ].filter((value, index, array) => array.indexOf(value) === index).sort();
+    if (openspecGate.openspecPolicy === "cited") {
+        if (openspecGate.openspecCandidatePaths.length === 0) {
+            advisories.push("openspec 策略 cited：契约声明的 requiredReadPaths 与任务源引用均为空，prewrite gate 不强制读取 openspec；如需增强规范门禁，请在 task.json.frontendOpenspec.requiredReadPaths 声明必读路径或在任务源中显式引用 openspec 文件。");
+        }
+        else {
+            advisories.push(`openspec 策略 cited：候选 ${openspecGate.openspecCandidatePaths.length} 个（declared ${openspecGate.openspecCandidateSources.declared.length} / task-source-cited ${openspecGate.openspecCandidateSources.taskSourceCited.length}），plan 必须在 typed decision ledger 的 uiComponentChoices.specReference 中声明并通过真实 read 事件佐证。`);
+        }
+    }
+    else {
+        const openspecDiscovery = sources.frontendProjectCapability?.openspecDiscovery;
+        if (openspecDiscovery) {
+            advisories.push(`openspec 策略 scan-strict：候选来源 auto-discovered，共 ${openspecDiscovery.candidateCount} 个，排除治理目录 ${openspecDiscovery.governanceRoot} 下 ${openspecDiscovery.excludedGovernanceCount} 个文件`);
+            if (openspecDiscovery.truncated) {
+                advisories.push(`openspec 候选命中安全上限 ${openspecDiscovery.maxCandidates}，已截断（非静默）；请缩小 spec 范围或提高上限`);
+            }
+        }
+    }
+    const spec = {
+        version: 3,
+        title: `Frontend implementation DAG: ${taskConfig.title}`,
+        runtimeContract: GENERATED_DAG_RUNTIME_CONTRACT,
+        objective: extractObjective(sources.requirementMarkdown, taskConfig.title),
+        successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
+        globalConstraints,
+        defaults: {
+            ...FRONTEND_DEFAULTS,
+            contextProfile: taskConfig.contextProfile,
+        },
+        skillsByRole: FRONTEND_SKILLS_BY_ROLE,
+        executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
+        verifyStrategy: resolveDagVerifyStrategy(taskConfig),
+        advisories: advisories.length > 0 ? advisories : undefined,
+        tasks: [
+            {
+                id: "frontend-contract-pi",
+                depends_on: [],
+                role: "planner",
+                executor: "pi",
+                complexity: "MED",
+                writePolicy: "read-only",
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                skills: FRONTEND_CONTRACT_SKILLS,
+                outputContract: "Incremental typed requirement facts; narrative is display-only and should be omitted. Submit through the incremental typed tools record_requirement / record_constraint / record_evidence_expectation / record_handoff_intent / record_open_question / record_split_proposal / record_ui_state / record_required_deliverables / record_openspec_selection, then complete each input scope with complete_contract_scope, then call finalize_contract; correct rejected calls until one successful terminal. record_requirement takes the canonical ledger requirement id and optional execution:{groupId,kind,summary} — the runtime owns the authoritative text, source spans, fragment bindings, and disposition. UI-visible or interactive requirements register a non-blocking frontend-test handoff intent, and any source-declared UI-state table is extracted verbatim through record_ui_state. End finalize_contract with a single contract disposition of ready | ready-with-assumptions | blocked. Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations; do not fix target files, components, or implementation methods as requirements. When OpenSpec candidates exist, classify only the ones you actually use: call record_openspec_selection once per required/relevant path; never enumerate irrelevant candidates (unmentioned defaults to irrelevant) and never emit a fenced selection JSON. After a successful typed terminal, stop without a Markdown summary. No file writes.",
+                subtask_prompt: [
+                    "OUTPUT BUDGET DISCIPLINE: provider capacity is discovered at runtime; use small records — NEVER attempt to emit the whole contract in one response; a single large JSON dump will be truncated and rejected. Incremental submission through the typed tools is the ONLY supported output mode. Start submitting with the FIRST tool call: after each read, call record_requirement for the requirements you have already confirmed, one or a few per call. Every tool-call round MUST make progress by submitting at least one record_* fact. Do not re-read the same source file that is already materialized in this session; read each file at most once.",
+                    "Consume the complete injected input scope and produce a concise frontend implementation contract as typed requirement facts from complete injected scopes.",
+                    "Confirm each requirement by the SAME id as the ledger canonical requirement it covers (sourceBinding.requirementIds, e.g. AC-001) — do NOT invent new REQ/BR prefixed ids for canonical requirements: the compiled contract must match the ledger canonical requirement ids exactly or schema validation rejects it (unknown requirement id). record_requirement takes the canonical id and optional execution:{groupId,kind,summary}; the runtime commits the authoritative text and sourceFragmentIds from the frozen ledger. Never pass text/statement/sourceFragmentIds yourself — model rewrites and JSON-stringified fragment arrays are rejected.",
+                    "Requirement semantics, source spans, dispositions, and fragment bindings are ledger/runtime-owned. If a canonical requirement is genuinely blocked, say so in the Markdown contract narrative and finalize with the matching disposition instead of trying to encode it in the requirement fact.",
+                    "Register evidence expectations for each requirement across static, behavior, Mock, and real integration as required | optional | not-applicable; required must follow from user requirements, task risk, or project governance, never from model convenience. For UI-visible or interactive requirements, register a non-blocking frontend-test handoff intent.",
+                    'Use record_evidence_expectation with {requirementId,evidence:{static,behavior,mock,"real-integration"}}; every lane is required | optional | not-applicable. Requirement text and provenance remain runtime-owned.',
+                    'Before finalize_contract ready, call record_required_deliverables once with the complete {items:[{path,requirementId,sourceFragmentId}]} inventory, or {items:[]} when no file delivery is mandatory. Interpret the original source, including lists and tables: allowedPaths/only-allowed-to-modify is permission, not an obligation; do not promote prohibited files, examples or references into deliverables. Paths must occur exactly in a frozen source fragment bound to that canonical requirement. Correct the whole inventory before finalizing if needed.',
+                    "Authoritative UI states: when the task source declares a UI-state table (state id / trigger / observable outcome), extract it VERBATIM through record_ui_state, one call per state, using the source's own state ids. The planner must bind these ids later — do not rename, merge, or invent states.",
+                    "Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations. Do not fix target files, components, styling, or implementation methods as requirements; leave those to Scout and Plan.",
+                    "If the task is too large for one bounded writer, record a task split proposal instead of silently widening scope.",
+                    "End the contract with a single disposition: ready, ready-with-assumptions (bounded assumptions that do not change product behavior), or blocked.",
+                    scopedOpenspecContext,
+                    ...(requiresOpenspecClassification ? [
+                        "Classify OpenSpec candidates incrementally while contracting — only the ones you actually use. Call record_openspec_selection once per path with disposition required (must be read and cited by the plan) or relevant (may inform planning). Never call it for irrelevant candidates and never list them: candidates you do not mention are treated as irrelevant by the runtime. Explicit task declarations / source citations are already required and must-read regardless; you never need to re-declare them.",
+                        "Mandatory paths are enforced by the runtime from the frozen task configuration — do not enumerate them, do not downgrade them.",
+                        openspecSelectionContext,
+                    ] : []),
+                    "Read-only: do not modify code, docs, artifacts, or repository files.",
+                    sourceContexts.contract,
+                ].join("\n\n"),
+            },
+            {
+                id: "frontend-scout-pi",
+                depends_on: ["frontend-contract-pi"],
+                role: "scout",
+                executor: "pi",
+                complexity: mapTaskComplexity(taskConfig.complexity),
+                writePolicy: "read-only",
+                retryPolicy: FRONTEND_SCOUT_COMPLETENESS_RETRY_POLICY,
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                skills: FRONTEND_SCOUT_SKILLS,
+                outputContract: "Markdown scout report covering target surface and design evidence (frontend stack, routes, components, styling system, existing design conventions, state/data flow, test entry points, reuse opportunities, risks). Submit through the incremental evidence tools record_target_surface / record_design_evidence. A complete target surface is mandatory before Plan; if it cannot be proven, commit blocked with unresolved paths so this Scout node retries rather than shifting discovery to Plan. No fixed TARGET_SURFACE section title is required — target surface and design evidence are reported as committed typed facts. 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.",
+                    "Report target surface and design evidence as facts (no fixed section title required): completeness, entrypoint, routeOrMount, implementationPaths, testPaths, dataSource, allowedPathConflicts, unresolvedPaths. Use repository-relative POSIX paths. A complete surface must name at least one target candidate and set unresolvedPaths to []; if any target ownership remains unknown, commit completeness=blocked with every unresolved path instead of guessing. Prefer existing files/directories when they exist. For a greenfield target explicitly pinned by the task source, future implementation/test paths are allowed, but every such path must be named by the source and runtime-enriched as sourceDeclared; do not invent paths merely because they fit allowedPaths. allowedPathConflicts must list every discovered path not covered by task allowedPaths, or [] when none exists.",
+                    "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.",
+                    sourceContexts.scout,
+                    scopedOpenspecContext,
+                ].join("\n\n"),
+            },
+            {
+                id: "frontend-plan-pi",
+                depends_on: ["frontend-contract-pi", "frontend-scout-pi"],
+                role: "planner",
+                executor: "pi",
+                // Small topology has already proven a concentrated, no-remote scope;
+                // keep its bounded plan on the LOW model tier. Standard/High retain
+                // MED for broader contract-to-surface decisions.
+                complexity: frontendTaskShape.shape === "small" ? "LOW" : "MED",
+                writePolicy: "read-only",
+                retryPolicy: FRONTEND_PLAN_LADDER_RETRY_POLICY,
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                skills: FRONTEND_PLAN_SKILLS,
+                structuredContractOutput: {
+                    schemaId: "frontend-implementation-contract-plan-patch-v1",
+                    retryOnInvalid: true,
+                    skeleton: frontendContractSkeleton,
+                },
+                outputContract: "Typed decision patch only: map frozen requirements to implementation/verification targets and select the needed component, state, data/Mock, styling, and dependency decisions. Use only the record_* tools needed to express those decisions, then call finalize_plan; correct rejected facts until one successful terminal. Contract owns requirement semantics; Scout owns repository discovery; deterministic runtime owns schema, protected fields, path containment, and command validation. No Markdown narrative or file writes.",
+                subtask_prompt: [
+                    "Plan only the delta between the frozen frontend-contract-pi facts and frontend-scout-pi target surface. Do not reinterpret the task, repeat requirements, search the repository, or choose implementation order.",
+                    "Record only: requirement-to-file/verification coverage; component/styling choices; applicable UI state and interaction behavior; data/Mock strategy; and a dependency policy or genuine evidence gap. Reuse Scout paths. If scope is missing, record a blocking gap instead of inventing a path.",
+                    "Use the typed tool schemas as the field contract. Runtime owns schemaVersion, sourceBinding, riskLevel, targets.files, mockApi.productionDefaultOff, aliases, command allowlisting, path containment, and final validation; do not restate those rules or emit a full JSON contract.",
+                    `Cover each frozen requirement ID exactly once: ${requirementIds.join(", ") || "(none)"}. Bind every verification target to a frozen commandId from the directory above plus a Scout-confirmed file. Behavior commands prove observable behavior: one target may cover multiple related requirementIds when one test behavior proves them together; do not mechanically create one target per requirement. A behavior target id is the stable machine trace token and its file must be a test file. Static commands are project-wide checks traced by file and command only.`,
+                    "UX vocabulary protocol: record_state_registry FIRST with the full global vocabulary — one stable kebab-case behavior-domain name per UI state/interaction (e.g. planner-task-edit, focus-queue-move), never one name per AC number and never a rename of an already-recorded concept. Details consume complete execution-group scopes and reuse the same global names across scopes. Constraints/exclusions must not manufacture UI. Then record_state_flow entries whose names all come from that registry; uiState names must use the contract's declared authoritative ids (declaredUiStates in the plan input) when present. Retry attempts see committedUx in this input — reuse those exact names. Components: one choice may cover many state/interaction ids via covers; reuse-existing requires evidencePath naming an existing repo file (greenfield must be decision=new).",
+                    ...(requiresOpenspecClassification ? ["When a component choice uses an OpenSpec selection, cite that selection; otherwise do not classify unrelated candidates."] : []),
+                    "Call finalize_plan; correct rejected facts until one successful terminal after the necessary typed facts. Return no Markdown narrative.",
+                    "Group members retain full source text and independent ACs. Use record_plan_group_coverage only for actually shared references; do not create components for exclusions. TOOL-ONLY PLAN: Do not read Contract/Scout stdout, task sources, or Scout-confirmed target files. Contract and Scout already own evidence discovery; use the injected upstream facts, record a genuine evidence gap when those facts are insufficient, and start committing record_* facts immediately. For decision=new, pass sourceRequirementIds to record_component_choice; runtime derives the exact PRD citation from the frozen ledger.",
+                    "Incremental output protocol: process the current complete scope, committing small records immediately. Runtime packs full input and estimated work without assuming a model capacity from its name. Use record_plan_group_coverage for shared references, record_mock_endpoint per endpoint, and finalize only when all coverage is complete. On exhaustion, durable progress survives and remaining work is reduced; never omit source conditions or repeatedly retry the same exhausted scope.",
+                    fixedVerificationContext,
+                    scopedOpenspecContext,
+                    mockContextBlock,
+                    frontendContractFieldSummary,
+                    frontendComponentConformanceInstruction,
+                ].join("\n\n"),
+            },
+            {
+                id: "frontend-design-policy-shell",
+                depends_on: ["frontend-plan-pi"],
+                role: "verifier",
+                executor: "shell",
+                complexity: "LOW",
+                writePolicy: "read-only",
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                outputContract: "Deterministic design policy: materialize the canonical frontend implementation contract from the plan patch, enforce requirement-id retention, Mock strategy/frozen-command binding, writeSet containment, source freshness, and openspec invariants, then evaluate the design policy (write policy result).",
+                subtask_prompt: "Materialize the canonical contract and fail closed unless the deterministic design policy approves. The design verdict is not available at this stage; the writer admission shell enforces it.",
+                shell: {
+                    commands: [],
+                    frontendDesignPolicy: {
+                        schemaVersion: 1,
+                        planFromNodeId: "frontend-plan-pi",
+                        requiredRequirementIds: requirementIds,
+                        allowedMockStrategies: taskConfig.frontendMock?.policy === "disabled" ||
+                            frontendMockStrategyMustBeNotNeeded(frontendSources)
+                            ? ["not-needed"]
+                            : taskConfig.frontendMock?.policy === "required"
+                                ? [
+                                    "native",
+                                    "browser-intercept",
+                                    "request-adapter",
+                                ]
+                                : [
+                                    "native",
+                                    "browser-intercept",
+                                    "request-adapter",
+                                    "not-needed",
+                                ],
+                        mockCommandLabels: mockVerifyEvidence?.commandLabels ?? [],
+                        artifactName: "frontend-implementation-contract.json",
+                        outputDir: "contracts",
+                        requireSourceFreshness: true,
+                        implementationWriteSet: implementPaths.writeSet,
+                        ...(taskConfig.requirementOwnership?.length
+                            ? { requirementOwnership: taskConfig.requirementOwnership }
+                            : {}),
+                        ...(taskConfig.capabilityBoundary
+                            ? { capabilityBoundary: taskConfig.capabilityBoundary }
+                            : {}),
+                        ...(taskConfig.interactionIds?.length
+                            ? { interactionIds: taskConfig.interactionIds }
+                            : {}),
+                        openspecPolicy: openspecGate.openspecPolicy,
+                        openspecSpecRoots: taskConfig.frontendOpenspec?.specRoots ?? [
+                            ...DEFAULT_FRONTEND_SPEC_ROOTS,
+                        ],
+                        ...(requiresOpenspecClassification
+                            ? { openspecSelectionNodeId: "frontend-contract-pi" }
+                            : {}),
+                        openspecMandatoryPaths: openspecGate.openspecMandatoryPaths,
+                        openspecCandidateSources: {
+                            declared: openspecGate.openspecCandidateSources.declared,
+                            taskSourceCited: openspecGate.openspecCandidateSources.taskSourceCited,
+                            scanStrict: openspecGate.openspecCandidateSources.scanStrict,
+                        },
+                        openspecCandidatePaths: openspecGate.openspecCandidatePaths,
+                        ...(openspecGate.openspecCandidateSnapshots
+                            ? {
+                                openspecCandidateSnapshots: openspecGate.openspecCandidateSnapshots,
+                            }
+                            : {}),
+                        componentSpecCandidatePaths,
+                        allowedDependencies: declaredDependencies,
+                    },
+                    cwd: ".",
+                    timeoutMs: 60000,
+                },
+            },
+            {
+                id: "frontend-design-review-pi",
+                depends_on: ["frontend-design-policy-shell"],
+                role: "reviewer",
+                executor: "pi",
+                complexity: "MED",
+                writePolicy: "read-only",
+                retryPolicy: DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                skills: FRONTEND_DESIGN_REVIEW_SKILLS,
+                outputContract: "Authoritative typed design terminal via approve_design / request_design_changes tools. No JSON verdict; the committed typed design fact is the only authority. No file writes.",
+                subtask_prompt: [
+                    "Submit findings individually with record_design_finding and stable IDs; terminal tools aggregate saved findings. Correct rejected calls, stop after a successful terminal. Check execution groups against every member source outcome, including permission, threshold and failure-path differences; shared verification is valid only when it proves each independent AC.",
+                    "After the typed design terminal succeeds, stop immediately; do not emit a Markdown recap.",
+                    "Audit the frontend plan before implementation. frontend-plan-pi is emitted to you as canonical full-contract JSON after the runtime applied and validated the planner's editable patch against its protected skeleton; there is no separate plan prose.",
+                    "Your authoritative terminal verdict is exactly one committed typed tool call: approve_design or request_design_changes. Call exactly one of them; after calling one, do not call the other.",
+                    "request_design_changes must carry a typed issueCategory, at least one evidenceRef, and non-empty findings.",
+                    "Your verdict is consumed as deterministic data input by frontend-writer-admission-shell. approve_design permits admission; request_design_changes blocks writer admission until a recovery plan incorporates every Critical/Important finding.",
+                    "Request design changes when the Mock strategy is 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 a declared behavior target or selected Mock strategy. Mock strategies require Mock-backed evidence; a static-only contract is allowed only when every verification target is static and maps to a declared static entrypoint; not-needed requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists, in which case the plan must preserve the real request path and record the Real Integration Gap.",
+                    "Also request design changes 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.",
+                    "Component selection conformance is a hard blocking condition: request_design_changes when the frontend spec (component/theme/rule.components bucket) already defines a component for a purpose but the plan selects another or self-invents one without a declared deviation; when uiComponentChoices is missing/empty for UI-visible work while the frozen component/theme bucket is non-empty; when a decision=specified specReference.path is missing a ledger OpenSpec reference or successful read event; or when a decision=new component lacks a traceable task-source/PRD specReference. A PRD reference for decision=new is not an OpenSpec citation and must not be rejected merely for lacking an OpenSpec read event. For uiComponentChoices, coverage is judged by the covers list: every applicable UI state and interaction must appear in some choice's purpose or covers, and the runtime already pre-checks this deterministically at plan finalize — do not re-litigate it. purpose is a human-readable description of what the choice is for and must NOT be rejected merely for not matching an interaction or uiState name; judge responsibility semantics from the covered ids' expectedBehavior plus the choice rationale.",
+                    "You must NOT make authoritative assertions about the execution result of frozen verification commands: command results are deterministically established by frontend-verify-shell. Record a verification-feasibility concern only as a non-blocking finding (severity must not be Critical, and it must never be the sole fatal basis for request_design_changes). Only semantic design defects (component selection, state flow, interaction contract, or conflicts with the specification) may be Critical; a pure command-will-fail prediction must not be classified as contract-requirement-gap.",
+                    "Read-only: do not modify repository files.",
+                    "LARGE-FILE AUDIT (avoid full reads): style/theme audit files can be large (e.g. styles.css is often hundreds of KB). Prefer grep to locate the exact rules/variables you must verify (e.g. grep the oc- class, is-* modifier, or --oc- theme variables with their line numbers), then read only the narrow line range when surrounding context is needed. Do not read a large style/test file in full — a single full read can exhaust the read budget and fail the attempt.",
+                    "Canonical contract reading: frontend-design-policy-shell prints absolute paths for Contract, Contract index, and the non-blocking Capacity diagnostic. Read the capacity diagnostic first. When it recommends full-contract, read the exact Contract path. When it recommends indexed-sections, read the Contract index and its hash-bound section files instead of opening the full contract. Never resolve a bare contracts/... path against the repository root or hunt for substitutes. Implementation target files inside the writeSet are created later by the implement node: do not read them and do not treat their absence as a design defect.",
+                    fixedVerificationContext,
+                    sourceContexts.designReview,
+                    scopedOpenspecContext,
+                    mockContextBlock,
+                ].join("\n\n"),
+            },
+            {
+                id: "frontend-writer-admission-shell",
+                depends_on: ["frontend-design-policy-shell", "frontend-design-review-pi"],
+                role: "verifier",
+                executor: "shell",
+                complexity: "LOW",
+                writePolicy: "read-only",
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                outputContract: "Deterministic writer admission: require design review verdict pass, freeze the pre-writer worktree/lint baselines, derive the concrete writeSet + admission digest, and write contracts/frontend-writer-admission-result.json (schemaId frontend-writer-admission-shell-v1).",
+                subtask_prompt: "Fail closed unless the design review approved and the deterministic admission derived a concrete, non-empty writeSet. The admission result is the only write authorization.",
+                shell: {
+                    commands: [],
+                    frontendWriterAdmission: {
+                        schemaVersion: 1,
+                        designReviewFromNodeId: "frontend-design-review-pi",
+                        frozenCommandLabels: [
+                            ...staticVerifyEvidence.commandLabels,
+                            ...behaviorVerifyEvidence.commandLabels,
+                            ...(mockVerifyEvidence?.commandLabels ?? []),
+                        ],
+                        allowedMockStrategies: taskConfig.frontendMock?.policy === "disabled" ||
+                            frontendMockStrategyMustBeNotNeeded(frontendSources)
+                            ? ["not-needed"]
+                            : taskConfig.frontendMock?.policy === "required"
+                                ? [
+                                    "native",
+                                    "browser-intercept",
+                                    "request-adapter",
+                                ]
+                                : [
+                                    "native",
+                                    "browser-intercept",
+                                    "request-adapter",
+                                    "not-needed",
+                                ],
+                        ...(lintShellCommands.length > 0 && lintVerifyEvidence
+                            ? {
+                                lintCommands: lintShellCommands,
+                                lintEvidence: lintVerifyEvidence,
+                            }
+                            : {}),
+                    },
+                    cwd: ".",
+                    timeoutMs: 60000,
+                },
+            },
+            {
+                id: implementId,
+                depends_on: ["frontend-writer-admission-shell"],
+                ...buildFrontendWriterNodeDefaults({
+                    complexity: resolveWriterComplexity(taskConfig),
+                    writeSet: implementPaths.writeSet,
+                    allowedPaths: implementPaths.allowedPaths,
+                    forbiddenPaths,
+                    writerOutcomePolicyType: "frontend-facts-v1",
+                }),
+                outputContract: "The implementation status is derived by the executor from mechanical facts (write-tool events, run delta, write guard, requirement coverage, focused-check), not from any IMPLEMENTATION_OUTCOME first line. Deliver a Markdown summary with Contract Ref (path/schema/hash), Changed Files, Requirements Implemented, UI States, Tests Changed, Verification Attempts, Deviations, and Residual Risks. Follow fixed stages: contract confirm → tests → component/state → API/Mock → focused checks → diff cleanup.",
+                subtask_prompt: [
+                    "Implement against the validated run-owned Frontend Implementation Contract materialized by frontend-design-policy-shell (path/schema/hash) and authorized by frontend-writer-admission-shell. Do not rebuild the contract from Markdown alone.",
+                    "WRITER TOOL PROTOCOL (hard): the response text is not delivery. Never paste source code, test code, or full file contents into chat. After reading the canonical contract, make the first implementation change with the structured write/edit tool (one file per call); continue writing through those tools until the writeSet is complete. If a write/edit tool is unavailable, stop and report the blocked capability instead of drafting code in the response.",
+                    "The canonical contract already contains the approved requirement, target-file, UI-state, verification, design, and Mock/API decisions. Do not re-open task sources, OpenSpec, AI workspace, plan/revision, or design-review prose, and do not repeat broad repository research. Inspect only contract target files and directly related local code needed to implement them.",
+                    "Execute in fixed stages and report each in the delivery summary: (1) Contract confirm, (2) Tests sync, (3) Component/UI state implementation, (4) API/Mock wiring per contract.mockApi, (5) Focused checks behind frozen entrypoints only, (6) Diff cleanup.",
+                    "Map every requirement id, expectedOutcome, interaction trigger/expectedBehavior, and applicable UI state from the contract to concrete files. Do not invent shell verification commands; only frozen static/behavior entrypoints will run.",
+                    "A behavior verification target's target.id is only the contract's identifier for that entry; it does not need to appear in test titles. Never add tests, rename describe/it/test titles, or restructure files just to carry generated ids — reuse affected existing test files and their names. The requirement ↔ verification-target association lives in the contract (requirementIds / verificationTargetIds), not in title strings.",
+                    "Begin implementation after the contract and its target files are confirmed. Do not spend the turn collecting optional context. If the canonical contract lacks behavior needed to edit safely, stop and state the blocking reason in the summary instead of reopening broad discovery.",
+                    "Your implementation status is derived by the executor from mechanical facts (persisted write-tool events, run delta, write guard, requirement coverage, focused-check failures), never from any IMPLEMENTATION_OUTCOME first line. Do not emit an IMPLEMENTATION_OUTCOME first line.",
+                    "The node runs a bounded micro-loop: after each write attempt the executor re-runs frozen focused checks and records a per-round diff checkpoint; the write guard stays active every round. Only repair local issues attributable to the current diff (syntax/type/import/format/unit-assert/obvious omission). Never change requirements, design, writeSet, or verification strictness inside the loop.",
+                    "Implement only the approved Mock strategy carried by the validated contract. 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.",
+                    "frontend-design-policy-shell materialized and validated the canonical contract; frontend-writer-admission-shell authorized the writeSet. 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. Do not claim Browser/visual verification.",
+                    "Edit existing files with the structured edit/write tools. NEVER rewrite Markdown (or any file with quoting/backticks/indentation-sensitive content) via bash sed/awk/echo redirection: escaping mistakes silently corrupt the file and self-repair loops burn the run.",
+                    ...(implementPaths.docIndexCompanions.length > 0
+                        ? [
+                            `Doc index sync is MANDATORY: ${implementPaths.docIndexCompanions.join(", ")} are catalog index files for this writeSet. When you add, rename, or remove any indexed file, you MUST also update ${implementPaths.docIndexCompanions.join(" and ")} in the same run (append or fix the matching index entry following the existing line style). Verification runs check-doc-index and fails the run when a new file is missing from the index.`,
+                        ]
+                        : []),
+                    writerDeliveryContract(taskConfig),
+                ]
+                    .filter((value) => Boolean(value))
+                    .join("\n\n"),
+            },
+            {
+                id: "frontend-verify-shell",
+                depends_on: [implementId],
+                role: "verifier",
+                executor: "shell",
+                complexity: "LOW",
+                writePolicy: "read-only",
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                outputContract: "Run frozen Mock/static/behavior commands and materialize the verification trace. Any failure is terminal: no same-run repair branch, failure ownership facts are materialized for recovery.",
+                subtask_prompt: "Execute the frontend verification bundle. Preserve per-command evidence; a failure fails this node (terminal) and routes to recovery.",
+                shell: {
+                    commands: [],
+                    frontendVerificationBundle: {
+                        schemaVersion: 1,
+                        mockCommands: mockShellCommands,
+                        lintCommands: lintShellCommands,
+                        staticCommands: staticShellCommands,
+                        behaviorCommands: behaviorShellCommands,
+                        mockEvidence: mockVerifyEvidence,
+                        lintEvidence: lintVerifyEvidence,
+                        staticEvidence: staticVerifyEvidence,
+                        behaviorEvidence: behaviorVerifyEvidence,
+                        lintBaselineNodeId: lintShellCommands.length > 0
+                            ? "frontend-writer-admission-shell"
+                            : undefined,
+                        writerNodeIds: lintShellCommands.length > 0 ? [implementId] : [],
+                        mode: "initial",
+                    },
+                    cwd: ".",
+                    timeoutMs: DEFAULT_VERIFY_TIMEOUT_MS,
+                },
+            },
+            {
+                id: "frontend-review-context-shell",
+                depends_on: ["frontend-verify-shell", implementId],
+                role: "verifier",
+                executor: "shell",
+                complexity: "LOW",
+                writePolicy: "read-only",
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                outputContract: "Canonical frontend review context containing a hash-bound contract reference and field index, lint assessment when configured, effective verification trace, optional verify-failure facts, and actual worktree diff.",
+                subtask_prompt: "Capture the actual diff and bind it to the effective verification evidence for final review.",
+                shell: {
+                    commands: [],
+                    frontendReviewContext: { schemaVersion: 1, requireBaseline: true },
+                    cwd: ".",
+                    timeoutMs: 120000,
+                },
+            },
+            {
+                id: "frontend-review-pi",
+                depends_on: ["frontend-review-context-shell"],
+                role: "reviewer",
+                executor: "pi",
+                complexity: "HIGH",
+                writePolicy: "read-only",
+                retryPolicy: FRONTEND_REVIEW_TERMINAL_RETRY_POLICY,
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                skills: FRONTEND_REVIEW_SKILLS,
+                outputContract: 'Authoritative typed review terminal via approve_review / request_review_changes tools. No JSON verdict is required in the response text; the typed terminal fact is the only authority. No file writes.',
+                subtask_prompt: [
+                    "Submit findings individually with record_review_finding and stable IDs; terminal tools aggregate saved findings. Correct rejected calls, stop after a successful terminal. Check execution groups against every member source outcome, including permission, threshold and failure-path differences; shared verification is valid only when it proves each independent AC.",
+                    "After the typed review terminal succeeds, stop immediately; do not emit a Markdown recap.",
+                    "Review the frontend implementation and verification evidence.",
+                    "Your authoritative terminal verdict is exactly one committed typed tool call: approve_review or request_review_changes. Call it once and do not call the other afterwards.",
+                    "approve_review means the implementation passes; it must not carry Critical or Important findings. request_review_changes must carry a typed issueCategory, at least one evidenceRef, and non-empty findings.",
+                    "Do NOT emit an equivalent JSON verdict in the response text: the committed typed terminal fact is the only authority and no branch or gate reads response-text JSON verdicts.",
+                    "Read contracts/frontend-review-context.json from frontend-review-context-shell. It binds a hash-verified canonical contract reference, a field-to-section index, frontend lint assessment when configured, the per-command verification evidence (verificationEvidence.commands: commandId/label/lane/exitCode/ok plus allPassed, and lintStatus with lintConfigured) , the effective verification trace, and the run-owned actual diff. Read contractRef.capacityDiagnosticPath first: use contractRef.path only when full-contract is recommended; otherwise read only the hash-bound contractRef.sections needed for the changed surface and verification claims. Then read diff.reviewSummaryPath. The full artifacts/diff_patch.patch is retained only as audit evidence: do NOT read it in full. For semantic review, read only the named per-file diff fragment in the summary/index (in part order when needed) and then the current source file when necessary. 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/stable-target-id binding only—not semantic correctness.",
+                    "Treat lint status exactly as passed | baseline-debt | failed | unavailable, and read lintConfigured: when it is false the task declares no lint commands, so lintStatus unavailable means it is not part of this task — report no lint finding either way. 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, judged from verificationEvidence.commands exit codes rather than from the binding trace.",
+                    "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).",
+                    "The contract referenced and hash-bound by frontend-review-context.json is the effective plan materialized by frontend-design-policy-shell. Do not re-open task sources, OpenSpec, AI workspace, design-review, writer summary, or verification node prose. Inspect only the canonical review context, its indexed contract sections, its bound diff, and diff-referenced files when semantic review requires source code.",
+                    "For uiComponentChoices, coverage is judged by the covers list and is deterministically pre-checked at plan finalize; purpose is a human-readable description and must not be rejected merely for not matching an interaction or uiState name. Responsibility is expressed by the covered ids' expectedBehavior plus the choice rationale.",
+                    "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.",
+                    "Inspect the frontend-verify-shell evidence in the review context directly, including the production/default-real-path static check, 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.",
+                ].join("\n\n"),
+            },
+            {
+                id: "frontend-closeout-shell",
+                depends_on: ["frontend-review-context-shell", "frontend-review-pi"],
+                role: "closeout",
+                executor: "shell",
+                complexity: "LOW",
+                writePolicy: "read-only",
+                allowedPaths: readOnlyPaths,
+                forbiddenPaths,
+                outputContract: "Deterministic closeout rendered from committed facts only: coverage matrix, lint status, integration facts, typed review verdict, cumulative diff, browser/visual not-run, risks, and follow-up. No model summaries are re-interpreted.",
+                subtask_prompt: "Render the closeout deterministically from frontend-review-context.json, the verification trace, and the committed typed review terminal fact.",
+                shell: {
+                    commands: [],
+                    frontendCloseout: {
+                        schemaVersion: 1,
+                        reviewFromNodeId: "frontend-review-pi",
+                    },
+                    cwd: ".",
+                    timeoutMs: 60000,
+                },
+            },
+        ],
+    };
+    // The static DAG template is the topology source of truth: the generated
+    // chain must match the template's node set and order, and the template's
+    // depends_on must be a subset of the generated one (the runtime may add
+    // dependencies, e.g. Mock-required planning depending on the contract
+    // node's Mock facts). The template's own tasks carry simplified placeholder
+    // configs; the generated node definitions (budgets, retry, skeleton,
+    // skills, prompts) and any runtime-added dependencies win.
+    const frontendTemplate = await loadFrontendDagTemplate(sources.repoRoot);
+    if (frontendTemplate) {
+        const byId = new Map(spec.tasks.map((task) => [task.id, task]));
+        const templateIds = frontendTemplate.tasks.map((task) => task.id);
+        const missing = templateIds.filter((id) => !byId.has(id));
+        if (missing.length > 0) {
+            throw new Error(`frontend DAG template topology drift: generated chain is missing template node(s): ${missing.join(", ")}`);
+        }
+        for (const templateTask of frontendTemplate.tasks) {
+            const generated = byId.get(templateTask.id);
+            const generatedDeps = new Set(generated.depends_on);
+            const templateOnly = templateTask.depends_on.filter((dep) => !generatedDeps.has(dep));
+            if (templateOnly.length > 0) {
+                throw new Error(`frontend DAG template topology drift: generated node ${templateTask.id} is missing template dependency ${templateOnly.join(", ")}`);
+            }
+        }
+        const templateSet = new Set(templateIds);
+        const ordered = templateIds.map((id) => byId.get(id));
+        const extra = spec.tasks.filter((task) => !templateSet.has(task.id));
+        spec.tasks = [...ordered, ...extra];
+    }
+    if (frontendTaskShape.shape === "split-required") {
+        spec.tasks = pruneFrontendTasksForSplitRequired(spec.tasks);
+    }
+    else {
+        const reshapeRaisedTopology = frontendTaskShape.signals.includes("shape-transition-reshape");
+        if (!reshapeRaisedTopology) {
+            spec.tasks = pruneFrontendTasksForRisk(spec.tasks, frontendRisk);
+        }
+        if (frontendTaskShape.shape === "micro") {
+            spec.tasks = pruneFrontendTasksForMicro(spec.tasks);
+        }
+    }
+    spec.advisories = [
+        ...(spec.advisories ?? []),
+        `frontend-task-shape: ${frontendTaskShape.shape} (${frontendTaskShape.reason})`,
+    ];
+    // Freeze the frontend recovery continuation quota from task.json so the
+    // runner can bound M6 auto-recovery without re-reading the task config.
+    const frontendMaxContinuations = sources.taskConfig.frontendRecovery?.maxContinuations ?? 1;
+    spec.frontendRecovery = { maxContinuations: frontendMaxContinuations };
+    // Configurable execution safety quota, independent of model context/output capacity.
+    spec.budget = { schemaVersion: 1, mode: "hard", limits: { maxProviderRequests: sources.taskConfig.frontendRecovery?.maxProviderRequests ?? 1024 } };
+    spec.frontendExecutionPolicy = frontendExecutionPolicySchema.parse(sources.taskConfig.frontendExecutionPolicy ?? {});
+    applyDefaultReadOnlyRetryPolicy(spec);
+    stampGeneratedArtifactBindings(spec);
+    parseDagSpec(spec);
+    assertValidDagSpec(spec);
+    return spec;
+}
+export async function loadFrontendDagTemplate(repoRoot) {
+    const candidates = [];
+    if (repoRoot) {
+        candidates.push(path.join(repoRoot, "docs", "templates", "frontend-implementation-dag.json"));
+    }
+    candidates.push(fileURLToPath(new URL("../../../docs/templates/frontend-implementation-dag.json", import.meta.url)));
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(await readFile(candidate, "utf8"));
+            if (!Array.isArray(parsed.tasks))
+                continue;
+            const tasks = parsed.tasks.filter((item) => typeof item === "object" &&
+                item !== null &&
+                typeof item.id === "string" &&
+                Array.isArray(item.depends_on) &&
+                typeof item.executor === "string");
+            if (tasks.length === 0)
+                continue;
+            return { tasks };
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+export function frontendMockStrategyMustBeNotNeeded(sources) {
+    const policy = sources.taskConfig.frontendMock?.policy ?? "auto";
+    const capability = sources.frontendMockCapability;
+    const capabilityStatus = capability?.status;
+    const hasDeterministicMockVerification = (capability?.verifyCommands.length ?? 0) > 0;
+    return (policy === "auto" &&
+        (sources.frontendMockMode ?? "not-required") === "not-required" &&
+        (capabilityStatus === "absent" ||
+            capabilityStatus === "ambiguous" ||
+            !hasDeterministicMockVerification));
+}
+export function frontendImplementationNodeId() {
+    return "frontend-implement-pi";
+}
+export function resolveFrontendCapabilityContextBlock(sources) {
+    const risk = sources.frontendRisk;
+    const capability = sources.frontendProjectCapability;
+    const parts = ["## Frontend risk & project capability", ""];
+    if (risk) {
+        parts.push(`Risk level: ${risk.selectedRisk}`, `Risk reason: ${risk.reason}`, `Risk signals: ${risk.signals.join(", ") || "(none)"}`, `Rejected signals: ${risk.rejectedSignals.join(", ") || "(none)"}`, `Force full gates: ${risk.forceFullGates}`);
+    }
+    else {
+        parts.push("Risk level: standard (not precomputed)");
+    }
+    if (capability) {
+        parts.push("", capability.adapterGuidance);
+        parts.push("Task-relevant OpenSpec candidates are injected separately as a bounded Top-K index. The deterministic prewrite gate retains the complete frozen candidate set; unlisted candidates are neither silently required nor evidence of a missing specification.");
+        parts.push(`A11y capability: ${capability.a11y.status}` +
+            (capability.a11y.tools.length
+                ? ` (${capability.a11y.tools.join(", ")})`
+                : ""));
+        parts.push("Browser accessibility verification: not-run (out of scope for this workflow).");
+    }
+    return parts.join("\n");
+}
+export function resolveFrontendShapeCapsuleGenerationInput(sources) {
+    const explicit = sources.frontendShapeTransitionCapsule == null
+        ? undefined
+        : parseFrontendShapeTransitionCapsule(sources.frontendShapeTransitionCapsule);
+    const autoloaded = sources.autoloadedFrontendShapeTransitionCapsule == null
+        ? undefined
+        : parseFrontendShapeTransitionCapsule(sources.autoloadedFrontendShapeTransitionCapsule);
+    if (explicit && autoloaded && explicit.capsuleDigest !== autoloaded.capsuleDigest) {
+        throw new Error("explicit frontend shape transition capsule conflicts with runtime autoload");
+    }
+    return explicit ?? autoloaded;
+}
+export function deriveFrontendBehaviorPaths(taskConfig) {
+    if (taskConfig.allowedPaths.length === 0)
+        return ["**"];
+    const explicitTestPaths = taskConfig.allowedPaths.filter((entry) => entry.includes("/test/") ||
+        entry.includes("/tests/") ||
+        entry.includes("/e2e/") ||
+        entry.includes("/spec/"));
+    if (explicitTestPaths.length > 0)
+        return explicitTestPaths;
+    return taskConfig.allowedPaths;
+}
+export const FRONTEND_NO_STATIC_VERIFICATION_MARKER = `node -e "console.log('${FRONTEND_NO_VERIFICATION_MARKER_TEXT}; static/behavior verification not-run')"`;
+export 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" };
+    }
+    if (input.allowAdapter !== false &&
+        input.adapterCommands &&
+        input.adapterCommands.length > 0) {
+        return { commands: input.adapterCommands, commandSource: "adapter" };
+    }
+    return { commandSource: "inline" };
+}
+export async function resolveFrontendOpenspecGateConfig(sources) {
+    const taskConfig = sources.taskConfig;
+    const policy = taskConfig.frontendOpenspec?.policy ?? "cited";
+    const declared = taskConfig.frontendOpenspec?.requiredReadPaths ?? [];
+    const governanceRoot = sources.frontendProjectCapability?.openspecDiscovery?.governanceRoot ??
+        DEFAULT_OPENSPEC_GOVERNANCE_ROOT;
+    const specRoots = taskConfig.frontendOpenspec?.specRoots ?? DEFAULT_FRONTEND_SPEC_ROOTS;
+    const rootAliases = sources.repoRoot
+        ? await resolveFrontendSpecRootAliases(sources.repoRoot, [...specRoots])
+        : [];
+    const remappedSourceMarkdown = rootAliases.reduce((markdown, { alias, logicalRoot }) => markdown.replace(new RegExp(`(^|[^A-Za-z0-9_.-])${alias.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`, "g"), `$1${logicalRoot}/`), [sources.requirementMarkdown, sources.constraintMarkdown ?? ""].join("\n"));
+    const taskSourceCited = extractTaskSourceFrontendSpecPaths(remappedSourceMarkdown, specRoots, governanceRoot);
+    const scanStrict = sources.frontendProjectCapability?.designEvidence.normativePaths ?? [];
+    const registry = sources.repoRoot
+        ? await readFrontendSpecRegistry(sources.repoRoot)
+        : null;
+    const registryModes = new Map();
+    for (const root of registry?.roots ?? []) {
+        if (root.scope && !root.scope.includes("frontend"))
+            continue;
+        if (!root.mode)
+            continue;
+        for (const candidate of scanStrict) {
+            if (candidate === root.path || candidate.startsWith(`${root.path}/`)) {
+                registryModes.set(candidate, root.mode);
+            }
+        }
+    }
+    const dedupeSorted = (paths) => [...new Set(paths)].sort();
+    const openspecCandidateSources = {
+        declared: dedupeSorted(declared),
+        taskSourceCited: dedupeSorted(taskSourceCited),
+        scanStrict: dedupeSorted(scanStrict),
+    };
+    // Candidate discovery is frozen independently from the eventual must-read
+    // set. The selector may mark candidates irrelevant, while explicit task
+    // declarations/source citations are never allowed to be downgraded.
+    const openspecMandatoryPaths = dedupeSorted([
+        ...declared,
+        ...taskSourceCited,
+    ]);
+    // `cited` must stay demand-driven: a normative registry makes a path
+    // discoverable, not implicitly task-mandatory. Only scan-strict may offer
+    // the global discovery set to the bounded task-relevance selector.
+    const openspecCandidatePaths = policy === "cited"
+        ? openspecMandatoryPaths
+        : dedupeSorted([
+            ...openspecCandidateSources.scanStrict,
+            ...openspecMandatoryPaths,
+        ]);
+    const result = {
+        openspecPolicy: policy,
+        openspecCandidatePaths,
+        openspecCandidateSources,
+        openspecMandatoryPaths,
+        openspecCandidateSummaries: buildFrontendSpecCandidateSummaries({
+            paths: openspecCandidatePaths,
+            mandatoryPaths: openspecMandatoryPaths,
+            registryModes,
+            sourceMarkdown: [sources.requirementMarkdown, sources.constraintMarkdown ?? ""].join("\n"),
+        }),
+    };
+    if (sources.repoRoot && openspecCandidatePaths.length > 0) {
+        result.openspecCandidateSnapshots = await Promise.all(openspecCandidatePaths.map(async (candidate) => ({
+            path: candidate,
+            sha256: createHash("sha256")
+                .update(await readFile(path.join(sources.repoRoot, candidate)))
+                .digest("hex"),
+        })));
+    }
+    return result;
+}
+export function filterRelevantOpenspecCandidates(input) {
+    const mandatory = new Set(input.mandatoryPaths);
+    const relevant = [];
+    for (const candidate of input.candidates) {
+        if (mandatory.has(candidate)) {
+            relevant.push(candidate);
+            continue;
+        }
+        if (openspecCandidateMatchesSource(candidate, input.sourceMarkdown)) {
+            relevant.push(candidate);
+        }
+    }
+    // 保持候选发现顺序（确定性）；mandatory 与相关候选都按原始顺序出现。
+    const maxCandidates = input.maxCandidates ?? 24;
+    if (relevant.length <= maxCandidates)
+        return relevant;
+    const mandatoryRelevant = relevant.filter((candidate) => mandatory.has(candidate));
+    const optionalRelevant = relevant.filter((candidate) => !mandatory.has(candidate));
+    return [
+        ...mandatoryRelevant,
+        ...optionalRelevant.slice(0, Math.max(0, maxCandidates - mandatoryRelevant.length)),
+    ];
+}
+export const frontendComponentConformanceInstruction = [
+    "## Component Selection conformance (uiComponentChoices; hard rule)",
+    "每个 UI 用途必须在契约的 uiComponentChoices[] 中声明组件选型：{ purpose, component, decision, specReference, rationale }。",
+    "覆盖关系以 covers 列表为准：每个 applicable UI state 与 interaction 必须出现在某条 choice 的 purpose 或 covers 中，且运行时已在 plan finalize 阶段确定性预检——不要重复翻案。purpose 是描述用途的自由文本，不得仅因未精确匹配 interaction.name 或 uiState.name 而判缺陷；职责语义由被覆盖 id 的 expectedBehavior 与 rationale 表达。",
+    "- decision=specified：前端规范（候选组件/主题桶 + 任务源显式引用）已定义该用途组件 → 必须使用该组件，并给精确 specReference { path, section, line }（path 必须是 openspec/ai_workspace 受支持规范路径）。",
+    "- decision=reuse-existing：仅当该组件/惯例**确实已存在于仓库当前代码**（如复用现有 ActiveRunBadge 的 oc- class 惯例）→ specReference 可为 null，rationale 必须指明复用的具体现有组件/文件与依据。",
+    "- decision=new：任务源/PRD 要求**新增**该组件（仓库当前不存在该组件文件）→ decision 必须为 new，不得标 reuse-existing；调用 record_component_choice 时传 sourceRequirementIds（关联的 frozen requirement ID）与 plan checklist 列出的 sourceFragmentId，runtime 校验其隶属关系并物化精确的任务源 PRD { path, section, line }。不要读取 PRD 或手填/猜测 specReference；rationale 说明新增纯展示组件、复用既有 CSS 命名与主题变量约定。",
+    "不得静默替换规范组件或自创组件而无偏差声明；spec 已定义该用途组件时不得改选其它组件。",
+    "prewrite gate 确定性交叉校验：仅 decision=specified 的 specReference 必须是候选 OpenSpec 路径、在 typed decision ledger 中声明且有成功 read 事件；decision=new 的 PRD 引用走任务源可追溯性审查，不得按 OpenSpec 候选拒绝。候选桶非空且契约有 UI 可见工作而 uiComponentChoices 缺失/空 → component-choices-missing。",
+].join("\n");
+export function buildFrontendWriterNodeDefaults(input) {
+    return {
+        role: "implementer",
+        executor: "pi",
+        toolProfile: "write",
+        complexity: input.complexity,
+        writePolicy: "exclusive",
+        writeSet: input.writeSet,
+        allowedPaths: input.allowedPaths,
+        forbiddenPaths: input.forbiddenPaths,
+        skills: FRONTEND_BOUNDED_IMPLEMENT_SKILLS,
+        writerOutcomePolicy: {
+            type: input.writerOutcomePolicyType ?? "implementation-outcome-v1",
+        },
+    };
+}
+export function pruneFrontendTasksForSplitRequired(tasks) {
+    const writerChain = new Set([
+        "frontend-writer-admission-shell",
+        "frontend-implement-pi",
+        "frontend-verify-shell",
+        "frontend-review-context-shell",
+        "frontend-review-pi",
+        "frontend-closeout-shell",
+    ]);
+    return tasks.filter((task) => !writerChain.has(task.id));
+}
+export function pruneFrontendTasksForRisk(tasks, risk) {
+    if (risk.forceFullGates || risk.selectedRisk !== "small") {
+        return tasks;
+    }
+    // Small topology keeps one design review and removes only the redundant
+    // design-review node; the deterministic design-policy and writer-admission
+    // shells consume the surviving plan directly.
+    const drop = new Set(["frontend-design-review-pi"]);
+    const filtered = tasks.filter((task) => !drop.has(task.id));
+    const byId = new Map(filtered.map((task) => [task.id, task]));
+    const remap = (deps) => {
+        if (!deps)
+            return [];
+        const next = [];
+        for (const dep of deps) {
+            if (dep === "frontend-design-review-pi")
+                continue;
+            if (byId.has(dep) || dep === "frontend-implement-pi")
+                next.push(dep);
+        }
+        return [...new Set(next)];
+    };
+    return filtered.map((task) => {
+        const depends_on = remap(task.depends_on);
+        if (task.id === "frontend-writer-admission-shell") {
+            // Small topology: no design review node, so the admission shell drops
+            // the design-review dependency and the verdict requirement.
+            const admission = task.shell?.frontendWriterAdmission;
+            return {
+                ...task,
+                depends_on: ["frontend-design-policy-shell"],
+                shell: admission
+                    ? {
+                        ...task.shell,
+                        commands: task.shell?.commands ?? [],
+                        frontendWriterAdmission: {
+                            ...admission,
+                            designReviewFromNodeId: undefined,
+                        },
+                    }
+                    : task.shell,
+            };
+        }
+        if (task.id === "frontend-implement-pi") {
+            for (const need of ["frontend-writer-admission-shell"]) {
+                if (byId.has(need) && !depends_on.includes(need))
+                    depends_on.push(need);
+            }
+        }
+        return { ...task, depends_on };
+    });
+}
+export function pruneFrontendTasksForMicro(tasks) {
+    // Micro topology (7 nodes): contract-import-shell → writer-admission →
+    // implement → verify → review-context → review → closeout. Drops scout/plan/
+    // design-policy/design-review and replaces the model contract node with a
+    // deterministic contract-import shell (§7.3: no model, no requirement
+    // rewrites — micro consumes a pre-validated managed Contract).
+    const drop = new Set([
+        "frontend-contract-pi",
+        "frontend-scout-pi",
+        "frontend-plan-pi",
+        "frontend-design-policy-shell",
+        "frontend-design-review-pi",
+    ]);
+    const contractPi = tasks.find((task) => task.id === "frontend-contract-pi");
+    const contractImportShell = contractPi
+        ? {
+            id: "frontend-contract-import-shell",
+            role: "verifier",
+            executor: "shell",
+            complexity: "LOW",
+            writePolicy: "read-only",
+            depends_on: [],
+            allowedPaths: contractPi.allowedPaths,
+            forbiddenPaths: contractPi.forbiddenPaths,
+            subtask_prompt: "Deterministic managed-Contract import + source/binding/schema freshness re-validation; no model, no requirement rewrite.",
+            shell: {
+                commands: [],
+                frontendContractImport: {
+                    schemaVersion: 1,
+                    artifactName: "frontend-task-contract.json",
+                    outputDir: "contracts",
+                    requireSourceFreshness: true,
+                },
+                cwd: ".",
+                timeoutMs: 60000,
+            },
+        }
+        : undefined;
+    const filtered = [
+        ...(contractImportShell ? [contractImportShell] : []),
+        ...tasks.filter((task) => !drop.has(task.id)),
+    ];
+    const byId = new Map(filtered.map((task) => [task.id, task]));
+    const remap = (deps) => {
+        if (!deps)
+            return [];
+        const next = [];
+        for (const dep of deps) {
+            if (drop.has(dep))
+                continue;
+            if (byId.has(dep))
+                next.push(dep);
+        }
+        return [...new Set(next)];
+    };
+    return filtered.map((task) => {
+        const depends_on = remap(task.depends_on);
+        if (task.id === "frontend-writer-admission-shell") {
+            const admission = task.shell?.frontendWriterAdmission;
+            return {
+                ...task,
+                depends_on: ["frontend-contract-import-shell"],
+                shell: admission
+                    ? {
+                        ...task.shell,
+                        commands: task.shell?.commands ?? [],
+                        frontendWriterAdmission: {
+                            ...admission,
+                            designReviewFromNodeId: undefined,
+                        },
+                    }
+                    : task.shell,
+            };
+        }
+        return { ...task, depends_on };
+    });
+}
+export function buildFrontendSpecCandidateSummaries(input) {
+    const mandatory = new Set(input.mandatoryPaths);
+    return input.paths
+        .map((candidate) => scoreFrontendSpecCandidate(candidate, "", {
+        registryMode: input.registryModes.get(candidate),
+        taskRelated: mandatory.has(candidate) || openspecCandidateMatchesSource(candidate, input.sourceMarkdown),
+    }))
+        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+}
+export function openspecCandidateMatchesSource(candidate, sourceMarkdown) {
+    const sourceTokens = extractOpenspecSourceTokens(sourceMarkdown);
+    if (sourceTokens.size === 0)
+        return true;
+    const candidateLower = candidate.toLowerCase().replace(/\\/g, "/");
+    const candidateSegments = candidateLower.split("/");
+    const candidateBasename = candidateSegments[candidateSegments.length - 1] ?? "";
+    for (const token of sourceTokens) {
+        if (candidateBasename.includes(token) ||
+            candidateLower.includes(`/${token}/`) ||
+            candidateLower.includes(`${token}.`)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function extractOpenspecSourceTokens(markdown) {
+    const tokens = new Set();
+    const push = (raw) => {
+        const cleaned = raw
+            .trim()
+            .replace(/[.*+?^${}()|[\]\\]/g, "")
+            .toLowerCase();
+        if (cleaned.length >= 2 && cleaned.length <= 40)
+            tokens.add(cleaned);
+    };
+    // 反引号内联代码（文件名/组件名）
+    for (const match of markdown.matchAll(/`([^`\n]+)`/g)) {
+        push(match[1] ?? "");
+    }
+    // markdown 链接文本
+    for (const match of markdown.matchAll(/\[([^\]]+)\]\([^)]+\)/g)) {
+        push(match[1] ?? "");
+    }
+    // 路径 token（openspec/ 或 xxx/xxx.md）
+    for (const match of markdown.matchAll(/(?:[A-Za-z0-9_-]+\/)+[A-Za-z0-9_.-]+/g)) {
+        const segments = (match[0] ?? "").split("/");
+        const basename = segments[segments.length - 1] ?? "";
+        push(basename.replace(/\.[a-z0-9]+$/i, ""));
+        for (const segment of segments)
+            push(segment);
+    }
+    return tokens;
+}