@tea-agent/loop-agent 0.42.0-next.9 → 0.42.1

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

@@ -1,3 +1,4 @@
+import { frontendExecutionSchema, collectFrontendExecutionGroups } from "./frontend-execution-groups.js";
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
@@ -9,10 +10,12 @@ import { findPackageRoot } from "../../shared/package-metadata.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
 import { readTypedEventStoreFromJsonl } from "./frontend-typed-event-store.js";
+import { extractRequiredDeliverablePaths } from "./frontend-contract-facts.js";
+export { extractRequiredDeliverablePaths } from "./frontend-contract-facts.js";
 // Cycle-safe value imports: the check functions are hoisted declarations used
 // only at call time, so the contract module and the policy module can depend
 // on each other without module-init ordering issues.
-import { checkDependencies, checkTargetPaths, checkUiDesignCoverage, checkUiStateAttribution, } from "./frontend-design-policy.js";
+import { checkDependencies, checkTargetPaths, checkUiDesignCoverage, checkUiStateAttribution, checkRequiredDeliverables, checkUxNameCollisions, } from "./frontend-design-policy.js";
 import { isDagSourceBindingV2 } from "./types.js";
 import { canonicalContractRel, classifyStructuredContractFailure, formatStructuredArtifactPointer, persistRuntimeSkeleton, } from "./structured-output-repair.js";
 import { renderFrontendPlanMarkdown } from "./frontend-plan-render.js";
@@ -25,6 +28,7 @@ export const frontendNormalizationActionSchema = z.enum([
     "drop-unresolved-verification-symbols",
     "inject-source-binding",
     "compact-canonical-contract",
+    "resolve-verification-command-ids",
 ]);
 export function sha256Hex(input) {
     return createHash("sha256").update(input, "utf8").digest("hex");
@@ -95,20 +99,200 @@ export async function writeCompactDeterministicJsonArtifact(runDir, relativePath
     return { path: targetPath, sha256: sha256Hex(json) };
 }
 /**
- * Extract frozen command labels from the DAG run spec (run.json).
- * The run spec is written before any node executes, so it is always available
- * when the prewrite gate materializes the contract.
+ * Verification mode v2 (AC-V2-001..004).
+ *
+ * The mode is owned by the runtime, never by the model: plan tools submit a
+ * `commandId` referencing the generation-time frozen command directory, and
+ * materialization resolves `mode` + `commandLabel` from that directory. This
+ * makes contradictory combinations such as `type: component` bound to
+ * `npm run build` unrepresentable instead of failing late at the writer
+ * focused-check.
+ */
+export const frontendVerificationModeSchema = z.enum(["static", "behavior"]);
+/**
+ * Optional display-only test scope. It never participates in control flow:
+ * trace checks, writeSet derivation and behavior-required evaluation read
+ * only the runtime-derived `mode`.
+ */
+export const frontendVerificationScopeSchema = z.enum([
+    "unit",
+    "component",
+    "integration",
+]);
+function laneToVerificationMode(lane) {
+    return lane === "static" || lane === "lint" ? "static" : "behavior";
+}
+const VERIFY_RUNNER_RE = /\b(vitest|jest|mocha|ava|tap|playwright|cypress|testcafe|nightwatch|webdriverio|pytest|go test)\b/i;
+const VERIFY_E2E_RE = /(^|[\s:"'=/-])e2e([\s"'/-]|$)/i;
+const VERIFY_STATIC_SCRIPT_WORDS = new Set([
+    "typecheck",
+    "check",
+    "lint",
+    "eslint",
+    "tsc",
+    "build",
+]);
+// A script segment carrying test semantics wins over static words:
+// `test:build` builds nothing observable by itself — it runs tests, and
+// `check:unit` is a unit-test entrypoint, not a project-wide check.
+const VERIFY_BEHAVIOR_SCRIPT_WORDS = new Set([
+    "test",
+    "tests",
+    "unit",
+    "spec",
+    "specs",
+    "e2e",
+    "integration",
+    "coverage",
+]);
+function extractRunScriptName(command) {
+    // Skip package-manager flags between the binary and the script, e.g.
+    // `npm --prefix website run build` executes the `build` script.
+    const tokens = command.match(/(?:npm|pnpm|yarn|bun)(?:\.cmd|\.ps1)?\s+(.+)/i)?.[1];
+    if (!tokens)
+        return undefined;
+    const parts = tokens.split(/\s+/).filter(Boolean);
+    let index = 0;
+    while (index < parts.length) {
+        const part = parts[index].replace(/["']/g, "");
+        if (part === "--prefix" ||
+            part === "--cwd" ||
+            part === "-C" ||
+            part === "--workspace") {
+            index += 2;
+            continue;
+        }
+        if (part.startsWith("-")) {
+            index += 1;
+            continue;
+        }
+        if (/^(run|exec)$/i.test(part)) {
+            index += 1;
+            continue;
+        }
+        return part;
+    }
+    return undefined;
+}
+/**
+ * Whether a command carries known verification semantics. Markdown intake
+ * uses this before lane classification so prose cannot authorize an arbitrary
+ * package script such as `npm run deploy`. Explicit task verifyCommands remain
+ * operator-authorized and intentionally do not use this admission check.
+ */
+export function isRecognizedFrontendVerifyCommandText(command) {
+    if (VERIFY_RUNNER_RE.test(command) || VERIFY_E2E_RE.test(command))
+        return true;
+    const scriptName = extractRunScriptName(command);
+    if (scriptName) {
+        const segments = scriptName.toLowerCase().split(/[:/_-]+/);
+        return segments.some((segment) => VERIFY_BEHAVIOR_SCRIPT_WORDS.has(segment) ||
+            VERIFY_STATIC_SCRIPT_WORDS.has(segment));
+    }
+    const head = command.trim().split(/\s+/, 1)[0] ?? "";
+    const binary = head.split(/[\\/]/).pop() ?? "";
+    return (/^(tsc|eslint|stylelint|lint|typecheck|check|build)$/i.test(binary) ||
+        /\b(tsc|eslint|typecheck|check-types)\b/i.test(command) ||
+        /\bscripts[\\/]+ci(?:-tests)?\.sh\b/i.test(command));
+}
+/**
+ * Classify a raw verification command text into the runtime-owned mode.
+ * Shared single implementation used by DAG generation (lane split) and
+ * documented here so generation and validation can never disagree.
+ *
+ * Order matters: test runners and e2e harnesses always prove behavior, even
+ * when their arguments mention build/check/lint paths (e.g.
+ * `npx vitest run test/build.test.ts`). For npm scripts, a segment with
+ * test semantics (`test:build`, `check:unit`) wins over static words; pure
+ * static scripts (`npm run check`, `check:types`) and leading binaries
+ * (`tsc`, `eslint`) stay static. Package-manager flags (`npm --prefix
+ * website run build`) are skipped when locating the script.
+ */
+export function classifyFrontendVerifyCommandText(command) {
+    if (VERIFY_RUNNER_RE.test(command) || VERIFY_E2E_RE.test(command)) {
+        return "behavior";
+    }
+    const scriptName = extractRunScriptName(command);
+    if (scriptName) {
+        const segments = scriptName.toLowerCase().split(/[:/_-]+/);
+        if (segments.some((segment) => VERIFY_BEHAVIOR_SCRIPT_WORDS.has(segment))) {
+            return "behavior";
+        }
+        return segments.some((segment) => VERIFY_STATIC_SCRIPT_WORDS.has(segment))
+            ? "static"
+            : "behavior";
+    }
+    const head = command.trim().split(/\s+/, 1)[0] ?? "";
+    const binary = head.split(/[\\/]/).pop() ?? "";
+    if (/^(tsc|eslint|stylelint|lint|typecheck|check|build)$/i.test(binary) ||
+        /\b(tsc|eslint|typecheck|check-types)\b/i.test(command) ||
+        /\bscripts[\\/]+ci(?:-tests)?\.sh\b/i.test(command)) {
+        return "static";
+    }
+    return "behavior";
+}
+export function slugFrontendVerifyCommandId(label, taken) {
+    const slug = label
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48) || "verify";
+    let candidate = `verify-${slug}`;
+    let counter = 2;
+    while (taken.has(candidate)) {
+        candidate = `verify-${slug}-${counter++}`;
+    }
+    taken.add(candidate);
+    return candidate;
+}
+/**
+ * Build the generation-time frozen command directory. Lanes come from the
+ * DAG generation split (init-hybrid classifies each verify command once);
+ * labels stay human-readable while `commandId` is the stable machine key
+ * the plan references. Mock/lint lanes keep their provenance in `lane` but
+ * map to the behavior/static mode the trace gate enforces. Command texts
+ * (parallel to labels; usually from the bundle evidence) bind each id to
+ * the exact frozen command so same-label entries across lanes cannot drift
+ * into the same identity silently.
+ */
+export function buildFrontendVerifyCommandDirectory(lanes) {
+    const taken = new Set();
+    const entries = [];
+    const push = (labels, lane, texts) => {
+        labels.forEach((label, index) => {
+            const trimmed = label.trim();
+            if (!trimmed)
+                return;
+            entries.push({
+                commandId: slugFrontendVerifyCommandId(trimmed, taken),
+                label: trimmed,
+                mode: laneToVerificationMode(lane),
+                lane,
+                command: texts?.[index]?.trim() ?? "",
+            });
+        });
+    };
+    push(lanes.staticLabels, "static", lanes.staticCommandTexts);
+    push(lanes.lintLabels ?? [], "lint", lanes.lintCommandTexts);
+    push(lanes.behaviorLabels, "behavior", lanes.behaviorCommandTexts);
+    push(lanes.mockLabels ?? [], "mock", lanes.mockCommandTexts);
+    return entries;
+}
+/**
+ * Derive the frozen command directory from the DAG run spec (run.json),
+ * reading the per-lane evidence of the `frontend-verify-shell` bundle. The
+ * run spec is written before any node executes, so it is always available
+ * when the prewrite gate materializes the contract. When absent (e.g. test
+ * fixtures), there is no directory to validate against and callers skip
+ * directory validation downstream — mirroring the legacy label-set behavior.
  */
-async function deriveFrozenCommandLabelsFromRun(runDir) {
+export async function deriveFrontendVerifyCommandDirectoryFromRun(runDir) {
     const specPath = path.join(runDir, "run.json");
     let raw;
     try {
         raw = await readFile(specPath, "utf8");
     }
     catch {
-        // run.json is guaranteed to exist in production (DAG runner writes it
-        // before any node executes). When absent (e.g. test fixtures), there is
-        // no frozen set to validate against and the check is skipped downstream.
         return [];
     }
     let spec;
@@ -116,21 +300,90 @@ async function deriveFrozenCommandLabelsFromRun(runDir) {
         spec = JSON.parse(raw);
     }
     catch (error) {
-        throw new Error(`cannot derive frozen command labels: run.json is not valid JSON at ${specPath}: ${error.message}`);
-    }
-    const labels = new Set();
+        throw new Error(`cannot derive frontend verify command directory: run.json is not valid JSON at ${specPath}: ${error.message}`);
+    }
+    const lanes = {
+        staticLabels: [],
+        behaviorLabels: [],
+        mockLabels: [],
+        lintLabels: [],
+        staticCommandTexts: [],
+        behaviorCommandTexts: [],
+        mockCommandTexts: [],
+        lintCommandTexts: [],
+    };
     for (const task of spec.tasks ?? []) {
-        const cmdLabels = task.shell?.verifyEvidence?.commandLabels;
-        if (cmdLabels) {
-            for (const label of cmdLabels)
-                labels.add(label);
+        const bundle = task.shell?.frontendVerificationBundle;
+        if (!bundle)
+            continue;
+        const lanePairs = [
+            ["static", bundle.staticEvidence],
+            ["behavior", bundle.behaviorEvidence],
+            ["mock", bundle.mockEvidence],
+            ["lint", bundle.lintEvidence],
+        ];
+        for (const [lane, evidence] of lanePairs) {
+            const labels = evidence?.commandLabels ?? [];
+            const texts = evidence?.commandTexts ?? [];
+            // run.json is untrusted input: labels and texts must zip 1:1.
+            // A lane that violates the alignment fails closed instead of
+            // binding ids to the wrong commands.
+            if (texts.length > 0 && texts.length !== labels.length) {
+                throw new Error(`cannot derive frontend verify command directory: ${lane} evidence commandTexts length (${texts.length}) does not match commandLabels length (${labels.length}) in ${specPath}`);
+            }
+            lanes[`${lane}Labels`].push(...labels);
+            lanes[`${lane}CommandTexts`].push(...texts);
         }
     }
-    return [...labels];
+    if (lanes.staticLabels.length === 0 &&
+        lanes.behaviorLabels.length === 0 &&
+        lanes.mockLabels.length === 0 &&
+        lanes.lintLabels.length === 0) {
+        return [];
+    }
+    return buildFrontendVerifyCommandDirectory(lanes);
+}
+/**
+ * A behavior verification target must bind a test file: the trace gate
+ * proves behavior targets by finding the target id in a real
+ * describe/it/test title inside `file`. Enforced at the plan boundary and
+ * at materialization (path shape only — the writer may create the file).
+ *
+ * Only code files count (the gate reads titles from source): fixtures and
+ * data files such as `test/fixtures/data.json` are rejected even under a
+ * test directory, as are helper/support/setup files (`cypress/fixtures/*`,
+ * `tests/support/*`, `setup.*`) that never carry describe/it/test titles.
+ * Cypress (`*.cy.*`, `cypress/`) and e2e (`e2e/`) entries are accepted —
+ * the repo supports those harnesses.
+ */
+export function isFrontendTestFilePath(filePath) {
+    const normalized = filePath.replace(/\\/g, "/");
+    const base = normalized.split("/").pop() ?? "";
+    if (!/\.(c|m)?[jt]sx?$/.test(base))
+        return false;
+    const segments = normalized.toLowerCase().split("/");
+    // `helpers` is deliberately NOT excluded: source helper directories
+    // (e.g. `src/helpers/format.test.ts`) legitimately contain unit tests.
+    if (segments.some((segment) => segment === "fixtures" || segment === "support")) {
+        return false;
+    }
+    if (/^setup\.[^/]+$/.test(base))
+        return false;
+    if (/\.cy\.[^/]+$/.test(base))
+        return true;
+    if (/(^|\/)__tests__\//.test(normalized))
+        return true;
+    if (/(^|\/)(tests?|e2e|cypress)\//.test(normalized))
+        return true;
+    if (/\.test\.[^/]+$/.test(normalized))
+        return true;
+    if (/\.spec\.[^/]+$/.test(normalized))
+        return true;
+    return false;
 }
 /**
  * Extract the design-policy allowedDependencies set from the DAG run spec
- * (run.json), mirroring `deriveFrozenCommandLabelsFromRun`. Used by the plan
+ * (run.json), mirroring `deriveFrontendVerifyCommandDirectoryFromRun`. Used by the plan
  * node's front-loaded policy pre-check so dependency declarations can be
  * corrected through the retry ladder before the policy shell (the authority)
  * re-runs the same check on committed facts.
@@ -350,12 +603,30 @@ const uiComponentChoiceSchema = z
     decision: z.enum(["specified", "reuse-existing", "new"]),
     specReference: uiComponentSpecReferenceSchema.nullable().optional(),
     // Optional: the decision enum already carries the semantic (specified →
-    // specReference, new → task-source traceability, reuse-existing → no
-    // rationale needed).
-    // Omit for reuse-existing to keep plan output small.
+    // specReference, new → task-source traceability, reuse-existing →
+    // evidencePath). Omit for reuse-existing to keep plan output small.
     rationale: z.string().min(1).optional(),
+    // Multi-id coverage (dogfood r-plan-quality): ONE choice may cover many
+    // UI states/interactions explicitly instead of the old implicit
+    // "reuse-existing covers everything" wildcard.
+    covers: z.array(z.string().min(1)).optional(),
+    // reuse-existing evidence (dogfood dag-1788504923861-0f7b17a9: 18
+    // reuse-existing rows cited conventions in a not-yet-written
+    // src/planner.ts): a repo-relative path to the existing file that
+    // proves the reuse. Enforced by superRefine + fresh-existence checks.
+    evidencePath: safePath.optional(),
 })
-    .strict();
+    .strict()
+    .superRefine((choice, ctx) => {
+    if (choice.decision === "reuse-existing" &&
+        !(choice.evidencePath && choice.evidencePath.trim().length > 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["evidencePath"],
+            message: "decision=reuse-existing requires evidencePath naming the existing repo file that proves the reuse; use decision=new for greenfield paths",
+        });
+    }
+});
 const uiComponentChoicesSchema = z.array(uiComponentChoiceSchema);
 /**
  * Normalize unstable model emissions before the strict schema sees them:
@@ -430,12 +701,18 @@ export const frontendImplementationContractSchema = z
         files: z.array(safePath).min(1),
         routes: z.array(z.string().startsWith("/")).optional(),
         publicApiChanges: z.array(z.string().min(1)).optional(),
+        // Runtime-owned deliverable contract (dogfood r-plan-quality):
+        // explicit, source-bound file inventory committed by Contract.
+        // The design-policy completeness gate checks ONLY these —
+        // allowedPaths is a write boundary, not a coverage obligation.
+        requiredDeliverables: z.array(safePath).optional(),
     })
         .strict(),
     requirements: z.array(z
         .object({
         id,
         expectedOutcome: z.string().min(1),
+        execution: frontendExecutionSchema.optional(),
         implementationTargets: z.array(safePath),
         verificationTargetIds: z.array(z.string().min(1)),
         evidenceGap: gap.optional(),
@@ -507,12 +784,18 @@ export const frontendImplementationContractSchema = z
     verificationTargets: z.array(z
         .object({
         id: z.string().min(1),
-        type: z.enum(["static", "unit", "component", "integration", "mock"]),
+        // Runtime-owned verification mode, resolved from commandId
+        // against the frozen command directory at materialization.
+        mode: frontendVerificationModeSchema,
+        // Stable machine key into the frozen command directory.
+        commandId: z.string().min(1),
         commandLabel: z.string().min(1),
         file: safePath,
         symbol: z.preprocess((value) => (value === "" || value === null ? undefined : value), z.string().min(1).optional()),
         requirementIds: z.array(id),
         uiStates: z.array(z.string().min(1)),
+        // Display-only test scope; never read by control flow.
+        scope: frontendVerificationScopeSchema.optional(),
     })
         .strict()).min(1),
     evidenceGaps: z.array(gap).optional(),
@@ -525,6 +808,12 @@ export const frontendImplementationContractSchema = z
 })
     .strict()
     .superRefine((value, ctx) => {
+    try {
+        collectFrontendExecutionGroups(value.requirements);
+    }
+    catch (error) {
+        ctx.addIssue({ code: "custom", path: ["requirements"], message: String(error) });
+    }
     const stableIdentities = [
         {
             path: "requirements",
@@ -587,6 +876,27 @@ export const frontendImplementationContractSchema = z
                 });
             }
         }
+        // Behavior evidence must be anchored to be machine-traceable: a
+        // behavior target that names no requirement and no UI state produces
+        // coverage the trace gate and review cannot verify. Contracts that
+        // declare no UI state and no interaction (pure-logic) are exempt from
+        // the UI-state half — the schema allows `uiStates: []` there.
+        if (target.mode === "behavior" && target.requirementIds.length === 0) {
+            ctx.addIssue({
+                code: "custom",
+                message: `behavior verification target ${target.id} must reference at least one requirement`,
+                path: ["verificationTargets"],
+            });
+        }
+        if (target.mode === "behavior" &&
+            target.uiStates.length === 0 &&
+            (value.uiStates.length > 0 || value.interactions.length > 0)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `behavior verification target ${target.id} must reference at least one declared UI state`,
+                path: ["verificationTargets"],
+            });
+        }
     }
     for (const requirement of value.requirements) {
         if (!known.has(requirement.id))
@@ -1357,7 +1667,12 @@ export function compactFrontendImplementationContract(value) {
     const targets = asRecord(record.targets);
     if (targets) {
         const compactTargets = { ...targets };
-        for (const field of ["files", "routes", "publicApiChanges"]) {
+        for (const field of [
+            "files",
+            "routes",
+            "publicApiChanges",
+            "requiredDeliverables",
+        ]) {
             if (Object.hasOwn(compactTargets, field)) {
                 compactTargets[field] = dedupeJsonArray(compactTargets[field]);
             }
@@ -1666,13 +1981,32 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
     for (const [index, item] of rawVerification.entries()) {
         const vt = asRecord(item) ?? {};
         const id = asString(vt.id) || `VT-${String(index + 1).padStart(3, "0")}`;
-        const typeRaw = asString(vt.type) || asString(vt.phase) || "unit";
-        const type = ["static", "unit", "component", "integration", "mock"].includes(typeRaw)
-            ? typeRaw
-            : typeRaw.includes("type")
+        // Legacy compatibility input may still carry a model-written `type`
+        // and a bare `commandLabel`. Map them onto the v2 shape: the five
+        // legacy types collapse to the runtime mode (only `static` stays
+        // static), the commandId is slugged from the label, and a legacy
+        // unit/component/integration type is preserved as display-only scope.
+        // Production plan facts already carry commandId and are resolved
+        // against the frozen directory during materialization instead.
+        const legacyType = asString(vt.type) || asString(vt.phase);
+        const mode = asString(vt.mode) === "static" ||
+            asString(vt.mode) === "behavior"
+            ? asString(vt.mode)
+            : legacyType === "static"
                 ? "static"
-                : "unit";
+                : "behavior";
         const commandLabel = asString(vt.commandLabel) || asString(vt.command);
+        const commandId = asString(vt.commandId) ||
+            slugFrontendVerifyCommandId(commandLabel || id, new Set());
+        const scope = asString(vt.scope) === "unit" ||
+            asString(vt.scope) === "component" ||
+            asString(vt.scope) === "integration"
+            ? asString(vt.scope)
+            : legacyType === "unit" ||
+                legacyType === "component" ||
+                legacyType === "integration"
+                ? legacyType
+                : undefined;
         const file = asString(vt.file) ||
             (Array.isArray(vt.symbols) ? targetFiles.find((p) => p.includes("__tests__")) : "") ||
             targetFiles.find((p) => p.includes("__tests__")) ||
@@ -1681,10 +2015,12 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
         const uiStateNames = asStringArray(vt.uiStates);
         verificationTargets.push({
             id,
-            type,
+            mode,
+            commandId,
             commandLabel,
             file,
             symbol: asString(vt.symbol) || undefined,
+            ...(scope ? { scope } : {}),
             requirementIds: requirementIds.length > 0
                 ? requirementIds
                 : [...canonicalBinding.requirementIds],
@@ -1735,6 +2071,7 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
                 ? { sourceFragmentIds: req.sourceFragmentIds }
                 : {}),
             ...(Array.isArray(req.sourceRefs) ? { sourceRefs: req.sourceRefs } : {}),
+            ...(req.execution !== undefined ? { execution: req.execution } : {}),
         };
         // Do not mark free-form realIntegrationGap as blocking; defer to FE-TEST/FINAL-VERIFY.
         if (gapText) {
@@ -2008,19 +2345,42 @@ export async function analyzeFrontendImplementationContract(input) {
     catch (error) {
         fail("blocked", error instanceof Error ? error.message : String(error), candidateJsonSha256);
     }
-    // Validate verificationTarget commandLabels against frozen command set.
-    // The frozen set is derived from DAG verification shell task verifyEvidence.
-    const frozenLabels = await deriveFrozenCommandLabelsFromRun(input.runDir);
-    if (frozenLabels.length > 0) {
-        const frozen = new Set(frozenLabels);
-        const parsedVt = asRecord(parsed)?.verificationTargets;
+    // Resolve verificationTarget commandIds against the frozen command
+    // directory (per-lane evidence of the frontend-verify-shell bundle in
+    // run.json). The directory is the only authority for mode and label: a
+    // plan that references an unknown commandId, or binds a behavior command
+    // to a non-test file, is rejected here with plan-attributable codes
+    // instead of failing late at the writer focused-check.
+    const verifyDirectory = await deriveFrontendVerifyCommandDirectoryFromRun(input.runDir);
+    if (verifyDirectory.length > 0) {
+        const byCommandId = new Map(verifyDirectory.map((entry) => [entry.commandId, entry]));
+        const available = verifyDirectory
+            .map((entry) => `${entry.commandId} (${entry.mode}: ${entry.label})`)
+            .join(", ");
+        const parsedRecord = asRecord(parsed);
+        const parsedVt = parsedRecord?.verificationTargets;
         if (Array.isArray(parsedVt)) {
             for (const vt of parsedVt) {
-                const label = asString(asRecord(vt)?.commandLabel);
-                if (label && !frozen.has(label)) {
-                    fail("blocked", `invalid-output: verificationTarget commandLabel "${label}" is not in the frozen command set [${[...frozen].join(", ")}]`, candidateJsonSha256);
+                const record = asRecord(vt);
+                if (!record)
+                    continue;
+                const vtId = asString(record.id) || "(missing id)";
+                const commandId = asString(record.commandId);
+                if (!commandId) {
+                    fail("retryable-invalid", `invalid-output: verification target "${vtId}" must reference a frozen command: set commandId to one of [${available}]`, candidateJsonSha256);
+                }
+                const entry = byCommandId.get(commandId);
+                if (!entry) {
+                    fail("retryable-invalid", `invalid-output: verification-target-unknown-command: verification target "${vtId}" references unknown commandId "${commandId}"; available frozen commands: [${available}]`, candidateJsonSha256);
+                }
+                record.mode = entry.mode;
+                record.commandLabel = entry.label;
+                const file = asString(record.file);
+                if (entry.mode === "behavior" && file && !isFrontendTestFilePath(file)) {
+                    fail("retryable-invalid", `invalid-output: verification-target-phase-mismatch: verification target "${vtId}" binds behavior command "${entry.label}" (${entry.commandId}) to non-test file "${file}"; behavior targets must bind a test file (__tests__/, tests?/, e2e/, cypress/, *.test.*, *.spec.*, *.cy.*) so the trace gate can match the target id in a real describe/it/test title`, candidateJsonSha256);
                 }
             }
+            pushAction("resolve-verification-command-ids");
         }
     }
     const parsedTargets = asRecord(parsed)?.targets;
@@ -2104,6 +2464,16 @@ export async function analyzeFrontendImplementationContract(input) {
             files: referencedConcretePaths,
         };
     }
+    // Both Plan precheck and policy materialization consume this exact inventory.
+    // Never trust a Plan patch or infer delivery obligations from prose.
+    const contractRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, input.contractNodeId ?? "frontend-contract-pi", "contract-typed-facts.jsonl"));
+    const requiredDeliverables = extractRequiredDeliverablePaths(contractRecords
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact));
+    delete result.data.targets.requiredDeliverables;
+    if (requiredDeliverables.length > 0) {
+        result.data.targets.requiredDeliverables = requiredDeliverables;
+    }
     const blockingGaps = [
         ...(result.data.evidenceGaps ?? []),
         ...result.data.requirements.flatMap((item) => item.evidenceGap ? [item.evidenceGap] : []),
@@ -2139,6 +2509,10 @@ function splitFrontendContractReviewGroup(canonical, fields) {
         if (!Object.hasOwn(canonical, field))
             continue;
         const fieldValue = canonical[field];
+        // JSON omits undefined object properties; the index must describe the
+        // persisted contract, not phantom keys retained by normalization.
+        if (fieldValue === undefined)
+            continue;
         if (!Array.isArray(fieldValue)) {
             const candidate = { ...data, [field]: fieldValue };
             if (Object.keys(data).length > 0 &&
@@ -2311,6 +2685,7 @@ const FRONTEND_PLAN_PATCH_PROTECTED_PATHS = [
     "/sourceBinding",
     "/riskLevel",
     "/targets/files",
+    "/targets/requiredDeliverables",
     "/mockApi/productionDefaultOff",
 ];
 const PLAN_LEDGER_FACT_KINDS_FOR_COMPILE = [
@@ -2359,6 +2734,8 @@ function frontendPlanPatchProtectedPathViolations(patch) {
     const targets = asRecord(record.targets);
     if (targets && Object.hasOwn(targets, "files"))
         violations.push("/targets/files");
+    if (targets && Object.hasOwn(targets, "requiredDeliverables"))
+        violations.push("/targets/requiredDeliverables");
     const mockApi = asRecord(record.mockApi);
     if (mockApi && Object.hasOwn(mockApi, "productionDefaultOff"))
         violations.push("/mockApi/productionDefaultOff");
@@ -2395,7 +2772,7 @@ async function dropUnresolvedVerificationSymbols(input) {
         // it. This is the root fix for the recurring fabricated-symbol error
         // class: the field was allowed for static, the prompt did not forbid
         // it, and models habitually fill it; the compiler removes it instead.
-        if (target.type === "static") {
+        if (target.mode === "static") {
             if (symbol) {
                 delete target.symbol;
                 if (!actions.includes("strip-static-verification-symbols"))
@@ -2543,6 +2920,8 @@ export async function analyzeFrontendPlanPatchCandidate(input) {
     const policyPreFindings = [
         ...checkUiDesignCoverage(analysis.canonical),
         ...checkUiStateAttribution(analysis.canonical),
+        ...checkRequiredDeliverables(analysis.canonical),
+        ...checkUxNameCollisions(analysis.canonical),
         ...checkDependencies(analysis.canonical, await deriveAllowedDependenciesFromRun(input.runDir)),
         ...checkTargetPaths(analysis.canonical, await deriveWriteSetFromRun(input.runDir)),
     ];
@@ -2761,9 +3140,11 @@ export async function buildContractFromCommittedFacts(input) {
     }
     // b. Committed contract terminal fact (contract-finalized).
     const contractRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, contractNodeId, "contract-typed-facts.jsonl"));
-    const contractKinds = new Set(contractRecords
+    const committedContractFacts = contractRecords
         .filter((record) => record.phase === "committed")
-        .map((record) => record.fact.kind)
+        .map((record) => record.fact);
+    const contractKinds = new Set(committedContractFacts
+        .map((fact) => fact?.kind)
         .filter((kind) => typeof kind === "string"));
     if (!contractKinds.has("contract-finalized")) {
         return {
@@ -2818,6 +3199,7 @@ export async function buildContractFromCommittedFacts(input) {
             runDir: input.runDir,
             rawContractText: serializeDeterministicJson(merged),
             sourceBinding: input.sourceBinding,
+            contractNodeId,
         });
         return {
             ok: true,