@tea-agent/loop-agent 0.42.0-next.13 → 0.42.0-next.15

package/dist/executors/dag-pi-executor.js

@@ -12,10 +12,13 @@ import { createPiReadBudgetCustomTools, } from "./pi-read-budget-policy.js";
 import { cleanupPlaywrightCliDefaultSession, createPlaywrightCliTool, PI_COMMAND_CAPABILITY_REGISTRY, resolveCaseIdFromWriteSet, resolveEvidenceDirFromWriteSet, } from "./pi-playwright-cli-tool.js";
 import { dagCommandPolicyAllows, resolveDagCommandPolicy, } from "../workflows/dag/types.js";
 import { parseLedgerJson } from "../task/source-prepare/ledger.js";
+import { splitDocumentIntoFragments, sha256Text, } from "../task/source-prepare/fragment-inventory.js";
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
 import { GitStatusUnavailableError, pathsChangedDuringRun, readGitStatusPorcelain, recoverRootNulArtifact, snapshotGitStatusPathFingerprints, snapshotGitStatusPorcelain, validateShellWriteGuard, } from "./shell-write-guard.js";
 import { captureWorkspaceWriteSnapshot, diffWorkspaceWriteSnapshots, } from "./workspace-write-snapshot.js";
 import { pathMatchesPattern } from "../shared/git-progress.js";
+import { readTypedEventStoreFromJsonl } from "../workflows/dag/frontend-typed-event-store.js";
+import { collectCanonicalStateFlowNames, frontendEvidenceExpectationSchema, resolveFrontendContractRequirements, validateFrontendRequiredDeliverables, } from "../workflows/dag/frontend-contract-facts.js";
 import { isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, INCOMPLETE_WRITE_SET_RETRY_CATEGORY, STRUCTURED_OUTPUT_RETRY_CATEGORY, WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY, WRITER_EMPTY_DIFF_RETRY_CATEGORY, } from "../workflows/dag/retry-policy.js";
 import { assessBackendTestMdPlanCompleteness, assessBackendTestMdWriterCompleteness, assessBackendTestPytestPlanCompleteness, assessBackendTestPytestWriterCompleteness, assessBackendTestShardChildCompleteness, backendTestWriterProgressRoleForTask, classifyBackendTestWriterCompletenessFailure, isBackendTestCompletenessRetryCandidate, isBackendTestMdPlanTask, isBackendTestPytestCollectionRepairOutcomeRecoveryCandidate, isBackendTestPytestPlanTask, isBackendTestShardChildTask, writeBackendTestWriterProgressArtifacts, } from "../workflows/dag/backend-test-writer-completeness.js";
 import { resolveBackendTestLayout } from "../workflows/dag/backend-test-layout.js";
@@ -251,6 +254,8 @@ export const FRONTEND_CONTRACT_RECORD_TOOL_NAMES = [
     "record_handoff_intent",
     "record_open_question",
     "record_split_proposal",
+    "record_ui_state",
+    "record_required_deliverables",
 ];
 export const FRONTEND_CONTRACT_TERMINAL_TOOL_NAMES = [
     "finalize_contract",
@@ -264,6 +269,7 @@ export const FRONTEND_SCOUT_EVIDENCE_TOOL_NAMES = [
 export const FRONTEND_PLAN_RECORD_TOOL_NAMES = [
     "record_route_selection",
     "record_component_choice",
+    "record_state_registry",
     "record_state_flow",
     "record_data_flow",
     "record_mock_api",
@@ -907,8 +913,81 @@ async function resolveFrontendPlanNewComponentSourceReferences(input) {
     }
 }
 /**
- * A+B: `frontend-plan-pi` now records its decision ledger through seven
- * incremental `record_*` tools (origin=plan) and closes with exactly one
+ * Frozen canonical requirements keyed by id, resolved from the source-fidelity
+ * ledger before the contract node starts. record_requirement commits these
+ * runtime-owned values so the model can never rewrite authoritative requirement
+ * text or stringify the fragment bindings.
+ */
+async function resolveFrontendCanonicalRequirements(input) {
+    const binding = input.sourceBinding;
+    if (!binding || binding.schemaVersion !== 2 || !binding.ledgerPath) {
+        return new Map();
+    }
+    const absolutePath = path.resolve(input.cwd, binding.ledgerPath);
+    const workspaceRoot = path.resolve(input.cwd);
+    if (absolutePath !== workspaceRoot &&
+        !absolutePath.startsWith(`${workspaceRoot}${path.sep}`)) {
+        throw new Error("canonical requirement ledger escapes workspace");
+    }
+    try {
+        const raw = await readFile(absolutePath, "utf8");
+        if (sha256Text(raw) !== binding.ledgerSha256) {
+            throw new Error("source ledger is stale");
+        }
+        const ledger = parseLedgerJson(raw);
+        const sourceFragments = new Map();
+        const boundFragments = new Map(ledger.fragments.map((fragment) => [fragment.id, fragment]));
+        for (const sourcePath of new Set(ledger.fragments.map((fragment) => fragment.path))) {
+            const sourceAbsolute = path.resolve(workspaceRoot, sourcePath);
+            if (!sourceAbsolute.startsWith(`${workspaceRoot}${path.sep}`)) {
+                throw new Error("source fragment escapes workspace");
+            }
+            const content = await readFile(sourceAbsolute, "utf8");
+            for (const fragment of splitDocumentIntoFragments({ path: sourcePath, content })) {
+                const frozen = boundFragments.get(fragment.id);
+                if (frozen && frozen.sha256 === sha256Text(fragment.text)) {
+                    sourceFragments.set(fragment.id, fragment.text);
+                }
+            }
+        }
+        return new Map(ledger.canonicalRequirements.map((requirement) => [
+            requirement.id,
+            {
+                text: requirement.text,
+                sourceFragmentIds: [...(requirement.sourceFragmentIds ?? [])],
+                sourceFragments,
+            },
+        ]));
+    }
+    catch (error) {
+        throw new Error(`canonical requirement sources unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Authoritative UI state ids declared by the contract node
+ * (ui-state-declaration facts). Empty when the source declares no UI-state
+ * table, in which case the plan's state vocabulary is registry-only.
+ */
+async function resolveFrontendDeclaredUiStateIds(input) {
+    try {
+        const records = await readTypedEventStoreFromJsonl(path.join(input.runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"));
+        return records.flatMap((record) => {
+            const fact = record.fact;
+            return record.phase === "committed" &&
+                fact.kind === "ui-state-declaration" &&
+                typeof fact.id === "string"
+                ? [fact.id]
+                : [];
+        });
+    }
+    catch {
+        // No contract facts (or no declared states): registry-only vocabulary.
+        return [];
+    }
+}
+/**
+ * A+B: `frontend-plan-pi` records its decision ledger through incremental
+ * `record_*` tools (origin=plan) and closes with exactly one
  * `finalize_plan` terminal. A later attempt may explicitly adopt a quarantined
  * fact via `adopt_staged_fact`. Flush writes `plan-typed-facts.jsonl` for the
  * node validator / compile authority.
@@ -1042,6 +1121,12 @@ export async function createFrontendPlanLedgerTools(input) {
             line: Type.Optional(Type.Number({})),
         }, { additionalProperties: false })),
         rationale: Type.String({}),
+        covers: Type.Optional(Type.Array(Type.String({}), {
+            description: "UI state and/or interaction names this single component choice covers (one choice may cover many ids).",
+        })),
+        evidencePath: Type.Optional(Type.String({
+            description: "REQUIRED for decision=reuse-existing: repo-relative path whose existing file is the reuse evidence. Greenfield paths must use decision=new.",
+        })),
     }, { additionalProperties: false });
     const stringList = (value) => Array.isArray(value)
         ? value.filter((item) => typeof item === "string")
@@ -1120,7 +1205,7 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordComponentChoiceTool = defineTool({
         name: "record_component_choice",
         label: "record_component_choice",
-        description: "Record ONE component choice (origin=plan component-choice fact). Declare every UI purpose's component selection. For decision=new, pass sourceRequirementIds containing the frozen requirement ID(s) that mandate the component and sourceFragmentId selecting one frozen citation listed in the plan checklist; the runtime validates the relation and derives the exact PRD specReference. Do not read the PRD or invent a path/line. decision=reuse-existing is only for components that already exist in the repo (e.g. reusing ActiveRunBadge's styling convention). Omit rationale for reuse-existing; it is optional. Call up to 5 component choices per assistant message (batching reduces API round trips and rate-limit risk); never more than 5 per message. Optionally include stylingStrategy (set it once, on the first call). Example: {\"choice\": {\"purpose\": \"<interaction or UI state name>\", \"component\": \"<component name>\", \"decision\": \"new\"}, \"sourceRequirementIds\": [\"<AC-XXX mandating this component>\"], \"sourceFragmentId\": \"<REQ-SRC-...>\"}",
+        description: "Record ONE component choice (origin=plan component-choice fact). One choice may cover MULTIPLE UI states/interactions via covers: [\"<state-or-interaction name>\", ...]; do not emit one row per interaction. For decision=new, pass sourceRequirementIds containing the frozen requirement ID(s) that mandate the component and sourceFragmentId selecting one frozen citation listed in the plan checklist; the runtime validates the relation and derives the exact PRD specReference. Do not read the PRD or invent a path/line. decision=reuse-existing is only for components that already exist in the repo and REQUIRES evidencePath: a repo-relative path to the existing file that proves the reuse — the runtime verifies the file exists (fresh evidence); a path with no existing file is greenfield and must use decision=new instead. Call up to 5 component choices per assistant message; never more than 5 per message. Optionally include stylingStrategy (set it once, on the first call). Example: {\"choice\": {\"purpose\": \"<interaction or UI state name>\", \"component\": \"<component name>\", \"decision\": \"new\", \"covers\": [\"<other interaction names this component also serves>\"]}, \"sourceRequirementIds\": [\"<AC-XXX mandating this component>\"], \"sourceFragmentId\": \"<REQ-SRC-...>\"} or {\"choice\": {\"purpose\": \"FocusQueuePanel\", \"component\": \"FocusQueuePanel\", \"decision\": \"reuse-existing\", \"evidencePath\": \"src/journal.ts\"}}",
         promptSnippet: "Record 1-5 component choices (up to 5 per message).",
         parameters: Type.Object({
             choice: uiComponentChoiceSchema,
@@ -1171,6 +1256,46 @@ export async function createFrontendPlanLedgerTools(input) {
                     ...(citation.line !== undefined ? { line: citation.line } : {}),
                 };
             }
+            if (choice.decision === "reuse-existing") {
+                // reuse-existing must cite a file that actually exists NOW (fresh
+                // existence evidence, same semantics as Scout pathEvidence.fresh).
+                // A path with no file on disk is greenfield: decision=new is the
+                // only honest choice (dogfood run dag-1788504923861-0f7b17a9
+                // claimed 18 reuse-existing conventions in a not-yet-written
+                // src/planner.ts and every gate let it through).
+                const evidencePath = typeof choice.evidencePath === "string"
+                    ? choice.evidencePath.trim()
+                    : "";
+                if (!evidencePath) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "component-choice",
+                        error: "decision=reuse-existing requires evidencePath naming the existing repo file that proves the reuse; if the file does not exist yet, use decision=new",
+                    });
+                }
+                if (input.workspaceRoot) {
+                    const absolute = path.resolve(input.workspaceRoot, evidencePath);
+                    const workspaceRoot = path.resolve(input.workspaceRoot);
+                    const contained = absolute === workspaceRoot ||
+                        absolute.startsWith(`${workspaceRoot}${path.sep}`);
+                    let exists = false;
+                    if (contained) {
+                        try {
+                            exists = (await stat(absolute)).isFile();
+                        }
+                        catch {
+                            exists = false;
+                        }
+                    }
+                    if (!exists) {
+                        return planToolReceipt({
+                            ok: false,
+                            kind: "component-choice",
+                            error: `decision=reuse-existing evidencePath "${evidencePath}" has no fresh existence evidence (file not found in the workspace); reuse requires an existing file — use decision=new for greenfield paths`,
+                        });
+                    }
+                }
+            }
             const components = typeof choice.component === "string" ? [choice.component] : [];
             const result = await adoptPlanFact("component-choice", `${attemptId}:record_component_choice:${randomUUID()}`, {
                 kind: "component-choice",
@@ -1194,10 +1319,86 @@ export async function createFrontendPlanLedgerTools(input) {
             return planToolReceipt(echo);
         },
     });
+    // Global UX vocabulary: one compact registry committed BEFORE any state
+    // flow details. Coverage may slice by AC; UX must not — the registry is
+    // the anti-duplication anchor that keeps every later slice on the same
+    // named concepts instead of re-inventing them per AC chunk.
+    const recordStateRegistryTool = defineTool({
+        name: "record_state_registry",
+        label: "record_state_registry",
+        description: "Commit the GLOBAL UX vocabulary (origin=plan state-registry fact) BEFORE any record_state_flow call: uiStateNames (use the contract's declared authoritative state ids when provided) and interactionNames (stable behavior-domain kebab-case names, e.g. planner-task-edit / focus-queue-move — one name per behavior domain, never one per AC). Empty arrays explicitly mean the request has no UI state or interaction vocabulary. Re-record the full vocabulary to correct it; the latest commit wins, but it may not remove names still referenced by committed state-flow facts. Example: {\"uiStateNames\": [\"planner-empty\"], \"interactionNames\": [\"planner-task-create\", \"focus-queue-move\"]}",
+        promptSnippet: "Record the global UI-state/interaction vocabulary once, before any state flow.",
+        parameters: Type.Object({
+            uiStateNames: stringArray,
+            interactionNames: stringArray,
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const uiStateNames = [...new Set(stringList(params?.uiStateNames).map((name) => name.trim()))];
+            const interactionNames = [
+                ...new Set(stringList(params?.interactionNames).map((name) => name.trim())),
+            ];
+            if (uiStateNames.some((name) => name.length === 0) || interactionNames.some((name) => name.length === 0)) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-registry",
+                    error: "record_state_registry names must be non-empty strings",
+                });
+            }
+            const invalidInteractionNames = interactionNames.filter((name) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name));
+            if (invalidInteractionNames.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-registry",
+                    error: `record_state_registry interactionNames must be stable kebab-case behavior-domain names: ${invalidInteractionNames.join(", ")}`,
+                });
+            }
+            if (input.declaredUiStateIds &&
+                input.declaredUiStateIds.length > 0) {
+                const declared = new Set(input.declaredUiStateIds);
+                const undeclared = uiStateNames.filter((name) => !declared.has(name));
+                if (undeclared.length > 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-registry",
+                        error: `record_state_registry uiStateNames are not declared by the contract's authoritative UI-state table: ${undeclared.join(", ")}; use the declared ids (${input.declaredUiStateIds.join(", ")})`,
+                    });
+                }
+                const missing = input.declaredUiStateIds.filter((name) => !uiStateNames.includes(name));
+                if (missing.length > 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-registry",
+                        error: `record_state_registry must include every state from the contract's authoritative UI-state table; missing: ${missing.join(", ")}`,
+                    });
+                }
+            }
+            // A correction is deterministic only when the new last-wins registry
+            // still contains every live name already committed by state-flow facts.
+            // This permits adding a missed concept, while preventing a registry edit
+            // from retroactively orphaning earlier slices.
+            const liveNames = collectCanonicalStateFlowNames(readCommittedEvents(store, attemptId));
+            const orphanedUiStates = [...liveNames.uiStateNames].filter((name) => !uiStateNames.includes(name));
+            const orphanedInteractions = [...liveNames.interactionNames].filter((name) => !interactionNames.includes(name));
+            if (orphanedUiStates.length > 0 || orphanedInteractions.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-registry",
+                    error: `record_state_registry cannot remove names still referenced by committed state-flow facts (uiStates: ${orphanedUiStates.join(", ") || "none"}; interactions: ${orphanedInteractions.join(", ") || "none"}); first correct/remove those state-flow entries, then re-record the full registry`,
+                });
+            }
+            const result = await adoptPlanFact("state-registry", `${attemptId}:record_state_registry:${randomUUID()}`, {
+                kind: "state-registry",
+                origin: "plan",
+                uiStateNames,
+                interactionNames,
+            });
+            return planToolReceipt(result);
+        },
+    });
     const recordStateFlowTool = defineTool({
         name: "record_state_flow",
         label: "record_state_flow",
-        description: "Record UI states and interactions as an origin=plan state-flow fact. To correct stale named entries from an earlier UX batch, include removeUiStateNames and/or removeInteractionNames. Example: {\"uiStates\": [{\"name\": \"<state>\", \"applicable\": true, \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}], \"interactions\": [{\"name\": \"<interaction>\", \"trigger\": \"<user event>\", \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}]}",
+        description: "Record UI states and interactions as an origin=plan state-flow fact. REQUIRES a committed record_state_registry vocabulary first, and every name here must be in that registry; uiState names must also be contract-declared authoritative ids when the contract declares them. To correct stale named entries from an earlier UX batch, include removeUiStateNames and/or removeInteractionNames. Example: {\"uiStates\": [{\"name\": \"<state>\", \"applicable\": true, \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}], \"interactions\": [{\"name\": \"<interaction>\", \"trigger\": \"<user event>\", \"expectedBehavior\": \"<behavior>\", \"implementationTargets\": [\"<file>\"], \"verificationTargetIds\": [\"<VT-XXX>\"]}]}",
         promptSnippet: "Record the plan state-flow fact.",
         parameters: Type.Object({
             uiStates: Type.Array(uiStateSchema),
@@ -1301,9 +1502,63 @@ export async function createFrontendPlanLedgerTools(input) {
                 }
                 interactions.push({ ...interaction, name: resolvedName });
             }
+            // UX vocabulary gate: every recorded state/interaction name must be
+            // declared in the committed global registry first. This keeps UX out
+            // of AC-number slicing — the model commits one compact vocabulary
+            // (record_state_registry), then fills behavior-domain details, and a
+            // later slice cannot silently rename an earlier concept (dogfood
+            // dag-1788504923861-0f7b17a9: 5 renames of "prioritize" + 7 of
+            // "focus queue" across AC chunks).
             const states = uiStates
                 .map((state) => (typeof state?.name === "string" ? state.name : ""))
                 .filter(Boolean);
+            const committedRegistry = readCommittedEvents(store, attemptId)
+                .map((event) => event.fact)
+                .filter((fact) => isRecordObject(fact) && fact.kind === "state-registry")
+                .at(-1);
+            if (!committedRegistry) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-flow",
+                    error: "record_state_flow requires a committed UX registry first: call record_state_registry with the full uiStateNames/interactionNames vocabulary, then record state flows against it",
+                });
+            }
+            const registryUiStateNames = new Set(stringList(committedRegistry.uiStateNames));
+            const registryInteractionNames = new Set(stringList(committedRegistry.interactionNames));
+            const unknownStates = states.filter((name) => !registryUiStateNames.has(name));
+            if (unknownStates.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-flow",
+                    error: `record_state_flow uiState names not in the committed registry: ${unknownStates.join(", ")}; re-record record_state_registry with the complete vocabulary first (registered: ${[...registryUiStateNames].join(", ") || "(none)"})`,
+                });
+            }
+            const unknownInteractions = interactions
+                .map((interaction) => typeof interaction?.name === "string" ? interaction.name : "")
+                .filter((name) => name && !registryInteractionNames.has(name));
+            if (unknownInteractions.length > 0) {
+                return planToolReceipt({
+                    ok: false,
+                    kind: "state-flow",
+                    error: `record_state_flow interaction names not in the committed registry: ${unknownInteractions.join(", ")}; re-record record_state_registry with the complete vocabulary first (registered: ${[...registryInteractionNames].join(", ") || "(none)"})`,
+                });
+            }
+            // Authoritative UI states: when the contract node declared the
+            // source's UI-state table, planner states must bind those ids — no
+            // invented variants (planner-empty/create-invalid/no-results/
+            // editing/focus-full/storage-unavailable, not "planner-list").
+            if (input.declaredUiStateIds &&
+                input.declaredUiStateIds.length > 0) {
+                const declared = new Set(input.declaredUiStateIds);
+                const undeclaredStates = states.filter((name) => !declared.has(name));
+                if (undeclaredStates.length > 0) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: `record_state_flow uiState names are not declared by the contract's authoritative UI-state table: ${undeclaredStates.join(", ")}; use the declared ids (${input.declaredUiStateIds.join(", ")}), or record a design deviation if the source table is genuinely incomplete`,
+                    });
+                }
+            }
             const result = await adoptPlanFact("state-flow", `${attemptId}:record_state_flow:${randomUUID()}`, {
                 kind: "state-flow",
                 origin: "plan",
@@ -1672,6 +1927,29 @@ export async function createFrontendPlanLedgerTools(input) {
                         ? { realIntegrationGap: params.realIntegrationGap }
                         : {}),
                 };
+                const latestRegistry = [...committed]
+                    .reverse()
+                    .map((record) => record.fact)
+                    .find((fact) => isRecordObject(fact) && fact.kind === "state-registry");
+                if (latestRegistry) {
+                    const registryUiStates = new Set(stringList(latestRegistry.uiStateNames));
+                    const registryInteractions = new Set(stringList(latestRegistry.interactionNames));
+                    const live = collectCanonicalStateFlowNames(committed);
+                    const missingUiStates = [...registryUiStates].filter((name) => !live.uiStateNames.has(name));
+                    const missingInteractions = [...registryInteractions].filter((name) => !live.interactionNames.has(name));
+                    const undeclaredUiStates = [...live.uiStateNames].filter((name) => !registryUiStates.has(name));
+                    const undeclaredInteractions = [...live.interactionNames].filter((name) => !registryInteractions.has(name));
+                    if (missingUiStates.length > 0 ||
+                        missingInteractions.length > 0 ||
+                        undeclaredUiStates.length > 0 ||
+                        undeclaredInteractions.length > 0) {
+                        return planToolReceipt({
+                            ok: false,
+                            kind: "finalize_plan",
+                            error: `finalize_plan UX registry mismatch: every registered name must have one live state-flow entry and every live entry must be registered (missing uiStates: ${missingUiStates.join(", ") || "none"}; missing interactions: ${missingInteractions.join(", ") || "none"}; undeclared uiStates: ${undeclaredUiStates.join(", ") || "none"}; undeclared interactions: ${undeclaredInteractions.join(", ") || "none"})`,
+                        });
+                    }
+                }
                 // Front-load the node's compile + policy gates into the finalize
                 // receipt (same pipeline the design-policy shell and the node
                 // self-check run: merge the patch onto the runtime skeleton,
@@ -1698,9 +1976,10 @@ export async function createFrontendPlanLedgerTools(input) {
                     catch (error) {
                         if (error instanceof PlanPolicyPrecheckFailure) {
                             // Template the fix: every uncovered interaction / state
-                            // maps to a ready-to-submit record_component_choice
-                            // call. One reuse-existing choice covers all
-                            // behavioural interactions.
+                            // maps to a record_component_choice skeleton. Reuse is
+                            // never implied: the operator/model must fill an existing
+                            // evidencePath or switch the choice to decision=new with
+                            // the required frozen source citation.
                             const suggestions = error.findings
                                 .filter((finding) => finding.code === "ui-design-coverage-missing" &&
                                 finding.path)
@@ -1711,6 +1990,7 @@ export async function createFrontendPlanLedgerTools(input) {
                                         purpose: finding.path,
                                         component: "<name the existing or new component>",
                                         decision: "reuse-existing",
+                                        evidencePath: "<existing repo file that proves this reuse>",
                                     },
                                 },
                             }));
@@ -1796,6 +2076,7 @@ export async function createFrontendPlanLedgerTools(input) {
         customTools: [
             recordRouteSelectionTool,
             recordComponentChoiceTool,
+            recordStateRegistryTool,
             recordStateFlowTool,
             recordDataFlowTool,
             recordMockApiTool,
@@ -1845,6 +2126,10 @@ function contractFactSourceSpan(fact) {
     if (Array.isArray(fact.sourceRefs) && fact.sourceRefs.length > 0) {
         return fact.sourceRefs;
     }
+    if (Array.isArray(fact.sourceFragmentIds) &&
+        fact.sourceFragmentIds.some((value) => typeof value === "string" && value.trim().length > 0)) {
+        return fact.sourceFragmentIds;
+    }
     if (typeof fact.source === "string" && fact.source.trim().length > 0) {
         return fact.source;
     }
@@ -1894,6 +2179,7 @@ export function buildFrontendTaskContractVNext(records) {
         requirements,
         constraints: byKind("constraint"),
         evidenceExpectations: byKind("evidence-expectation"),
+        deliverableDeclarations: byKind("required-deliverables").at(-1)?.items ?? [],
         handoffIntents: byKind("handoff-intent"),
         openQuestions: byKind("open-question"),
         splitProposals: byKind("split-proposal"),
@@ -1901,7 +2187,7 @@ export function buildFrontendTaskContractVNext(records) {
     };
 }
 /**
- * A+B: `frontend-contract-pi` incremental contract tools. Six `record_*` tools
+ * A+B: `frontend-contract-pi` incremental contract tools. The `record_*` tools
  * commit origin=contract facts and `finalize_contract` commits the terminal
  * disposition (ready | ready-with-assumptions | blocked + blockingOwner).
  */
@@ -1953,9 +2239,7 @@ export async function createFrontendContractTools(input) {
         }
     }
     const recordKinds = {
-        record_requirement: "requirement",
         record_constraint: "constraint",
-        record_evidence_expectation: "evidence-expectation",
         record_handoff_intent: "handoff-intent",
         record_open_question: "open-question",
         record_split_proposal: "split-proposal",
@@ -1975,6 +2259,141 @@ export async function createFrontendContractTools(input) {
             return receipt(result);
         },
     }));
+    // record_requirement is runtime-owned by design: the requirement TEXT and
+    // sourceFragmentIds come from the frozen source-fidelity ledger, never from
+    // model-authored prose. The model only names the canonical id it confirms.
+    // This closes the free-shape hole (additionalProperties:true accepted
+    // `statement` rewrites and JSON-stringified `sourceFragmentIds` arrays,
+    // which then reached the planner as empty text + dead fragment bindings).
+    const recordRequirementTool = defineTool({
+        name: "record_requirement",
+        label: "record_requirement",
+        description: 'Confirm one canonical ledger requirement (origin=contract requirement fact). Pass ONLY the canonical id listed in the <frontend_contract_input> inventory, e.g. {"id": "AC-001"} — the runtime commits the authoritative text and sourceFragmentIds from the frozen ledger. Never pass text/statement/sourceFragmentIds yourself: free-form rewrites and JSON-stringified fragment arrays are rejected. IMPORTANT: batch up to 5 record_* calls per message, starting from the FIRST message.',
+        promptSnippet: "Confirm 1-5 canonical requirements by id (up to 5 per message).",
+        parameters: Type.Object({ id: Type.String({ description: "Canonical ledger requirement id (e.g. AC-001)" }) }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const id = typeof params?.id === "string" ? params.id.trim() : "";
+            if (!id) {
+                return receipt({
+                    ok: false,
+                    kind: "requirement",
+                    error: "record_requirement requires the canonical requirement id",
+                });
+            }
+            const canonical = input.canonicalRequirements?.get(id);
+            if (!canonical) {
+                const known = [...(input.canonicalRequirements?.keys() ?? [])];
+                return receipt({
+                    ok: false,
+                    kind: "requirement",
+                    error: `record_requirement id "${id}" is not a canonical ledger requirement; canonical ids are: ${known.join(", ") || "(none)"}`,
+                });
+            }
+            const result = await adoptContractFact("requirement", {
+                kind: "requirement",
+                origin: "contract",
+                disposition: "explicit",
+                id,
+                text: canonical.text,
+                sourceFragmentIds: canonical.sourceFragmentIds,
+            });
+            return receipt(result);
+        },
+    });
+    // Authoritative UI state declarations: the contract node extracts the
+    // PRD/reference UI-state table into structured facts so the planner binds
+    // uiStates to declared ids instead of inventing names (dogfood
+    // dag-1788504923861-0f7b17a9: 10 invented list-visibility variants, 0 of
+    // the 7 PRD states).
+    const recordUiStateTool = defineTool({
+        name: "record_ui_state",
+        label: "record_ui_state",
+        description: 'Declare ONE authoritative UI state extracted from the task source\'s UI-state table (origin=contract ui-state-declaration fact). Call once per declared state, exactly as the source names it: {"id": "<state id from the source table>", "trigger": "<when this state applies>", "observableOutcome": "<what the user can observe>"}. The planner must bind these ids later; do not rename or invent states.',
+        promptSnippet: "Declare 1-5 authoritative UI states (up to 5 per message).",
+        parameters: Type.Object({
+            id: Type.String({ description: "UI state id exactly as the source table declares it" }),
+            trigger: Type.String({ description: "When this state applies" }),
+            observableOutcome: Type.String({ description: "Observable result for the user" }),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            const id = typeof params?.id === "string" ? params.id.trim() : "";
+            const trigger = typeof params?.trigger === "string" ? params.trigger.trim() : "";
+            const observableOutcome = typeof params?.observableOutcome === "string"
+                ? params.observableOutcome.trim()
+                : "";
+            if (!id || !trigger || !observableOutcome) {
+                return receipt({
+                    ok: false,
+                    kind: "ui-state-declaration",
+                    error: "record_ui_state requires non-empty id, trigger, and observableOutcome",
+                });
+            }
+            const result = await adoptContractFact("ui-state-declaration", {
+                kind: "ui-state-declaration",
+                origin: "contract",
+                id,
+                trigger,
+                observableOutcome,
+            });
+            return receipt(result);
+        },
+    });
+    const evidenceStatus = Type.Enum({
+        required: "required", optional: "optional", "not-applicable": "not-applicable",
+    });
+    const recordEvidenceExpectationTool = defineTool({
+        name: "record_evidence_expectation",
+        label: "record_evidence_expectation",
+        description: 'Record evidence requirements as {requirementId:"<canonical id>",evidence:{static:"required|optional|not-applicable",behavior:"required|optional|not-applicable",mock:"required|optional|not-applicable","real-integration":"required|optional|not-applicable"}}. Declare at least one lane; later calls replace only the lanes they name.',
+        parameters: Type.Object({
+            requirementId: Type.String(),
+            evidence: Type.Object({
+                static: Type.Optional(evidenceStatus),
+                behavior: Type.Optional(evidenceStatus),
+                mock: Type.Optional(evidenceStatus),
+                "real-integration": Type.Optional(evidenceStatus),
+            }, { additionalProperties: false }),
+        }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const fact = frontendEvidenceExpectationSchema.parse(params);
+                if (!input.canonicalRequirements?.has(fact.requirementId)) {
+                    throw new Error(`unknown canonical requirement ${fact.requirementId}`);
+                }
+                return receipt(await adoptContractFact("evidence-expectation", {
+                    kind: "evidence-expectation", origin: "contract", ...fact,
+                }));
+            }
+            catch (error) {
+                return receipt({
+                    ok: false, kind: "evidence-expectation",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        },
+    });
+    const recordRequiredDeliverablesTool = defineTool({
+        name: "record_required_deliverables",
+        label: "record_required_deliverables",
+        description: 'Declare the complete source-required file deliverables as {items:[{path,requirementId,sourceFragmentId}]}. Interpret obligations from the original source, including lists/tables: permissions (allowedPaths/only allowed to modify), prohibitions, examples and read-only references are NOT delivery obligations. Each path must appear exactly in its frozen requirement-bound source fragment. Submit {items:[]} explicitly if no files are mandatory. A correction replaces the whole inventory. Required before finalize_contract ready.',
+        parameters: Type.Object({ items: Type.Array(Type.Object({
+                path: Type.String(), requirementId: Type.String(), sourceFragmentId: Type.String(),
+            }, { additionalProperties: false })) }, { additionalProperties: false }),
+        async execute(_toolCallId, params) {
+            try {
+                const declaration = validateFrontendRequiredDeliverables(params, input.canonicalRequirements ?? new Map());
+                return receipt(await adoptContractFact("required-deliverables", {
+                    kind: "required-deliverables", origin: "contract", ...declaration,
+                }));
+            }
+            catch (error) {
+                return receipt({
+                    ok: false, kind: "required-deliverables",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        },
+    });
     // OpenSpec selection committed as individual typed facts (one path per
     // call) so a large candidate set never exceeds a single model output
     // budget: each tool call carries exactly one {path, disposition,
@@ -2045,6 +2464,13 @@ export async function createFrontendContractTools(input) {
                     error: "blocked disposition requires blockingOwner (blocked-human | blocked-external)",
                 });
             }
+            if (disposition !== "blocked" && input.canonicalRequirements?.size &&
+                !readCommittedEvents(store, attemptId).some((record) => record.fact.kind === "required-deliverables")) {
+                return receipt({
+                    ok: false, kind: "finalize_contract",
+                    error: "call record_required_deliverables with the complete source-bound inventory (or items:[] when none) before finalizing",
+                });
+            }
             const blockedOwner = mapContractBlockedOwner({
                 disposition: disposition ?? "",
                 blockingOwner,
@@ -2068,6 +2494,10 @@ export async function createFrontendContractTools(input) {
     return {
         customTools: [
             ...recordTools,
+            recordRequirementTool,
+            recordEvidenceExpectationTool,
+            recordUiStateTool,
+            recordRequiredDeliverablesTool,
             recordOpenspecSelectionTool,
             finalizeContractTool,
         ],
@@ -2682,6 +3112,15 @@ const FRONTEND_PLAN_SEGMENTS = [
             "If a requirement genuinely cannot have a verification target, record a non-empty record_plan_evidence_gap. Do not call finalize_plan; it is not available in this phase.",
         ].join(" "),
     },
+    {
+        id: "ux-registry",
+        toolNames: new Set(["record_state_registry", "adopt_staged_fact"]),
+        instruction: [
+            "PLAN PHASE — global UX vocabulary.",
+            "Review ALL frozen requirements together and call record_state_registry exactly once with the complete UI-state and interaction vocabulary. UI states use declaredUiStates ids when present. Interaction names are stable kebab-case behavior domains; merge requirements that describe the same behavior instead of renaming it per AC slice. Empty arrays explicitly declare that no UX vocabulary applies. Do not record component choices or state-flow details in this phase.",
+            "Do not call finalize_plan; it is not available in this phase.",
+        ].join(" "),
+    },
     {
         id: "ux-local",
         toolNames: new Set([
@@ -2690,8 +3129,8 @@ const FRONTEND_PLAN_SEGMENTS = [
             "adopt_staged_fact",
         ]),
         instruction: [
-            "PLAN PHASE — requirement-local UX decisions.",
-            "Requirements and verification targets are already committed in the ledger (do NOT re-record them; duplicates are rejected). For ONLY this requirement slice, record component choices and UI state flow. Keep these facts for this slice together. Cross-cutting data flow belongs to the global Mock/data phase. Do not record routes, Mock/API policy, dependencies, or design deviations here.",
+            "PLAN PHASE — global UX decisions.",
+            "Requirements and verification targets are already committed in the ledger (do NOT re-record them; duplicates are rejected). Review the complete requirement set and the committed global UX registry together, then record each component choice, UI state and interaction exactly once. Multiple requirements that describe one behavior share one registry name and one state-flow entry; never repeat or rename it per AC. Cross-cutting data flow belongs to the global Mock/data phase. Do not record routes, Mock/API policy, dependencies, or design deviations here.",
             "Do not call finalize_plan; it is not available in this phase.",
         ].join(" "),
     },
@@ -2749,40 +3188,6 @@ function planFactStringList(value) {
 function planFactScopeIntersects(fact, requirementIds) {
     return planFactStringList(fact.scopeRequirementIds).some((id) => requirementIds.has(id));
 }
-/** Apply state-flow replacement/removal semantics exactly as the plan compiler does. */
-function collectCanonicalStateFlowNames(committedFacts) {
-    const uiStateNames = new Set();
-    const interactionNames = new Set();
-    for (const value of committedFacts) {
-        const fact = committedFactFromPlanRecord(value);
-        if (!fact || fact.origin !== "plan" || fact.kind !== "state-flow")
-            continue;
-        for (const name of planFactStringList(fact.removeUiStateNames)) {
-            uiStateNames.delete(name);
-        }
-        for (const name of planFactStringList(fact.removeInteractionNames)) {
-            interactionNames.delete(name);
-        }
-        for (const state of Array.isArray(fact.uiStates) ? fact.uiStates : []) {
-            if (!state || typeof state !== "object" || Array.isArray(state))
-                continue;
-            const name = state.name;
-            if (typeof name === "string" && name.trim())
-                uiStateNames.add(name);
-        }
-        for (const interaction of Array.isArray(fact.interactions)
-            ? fact.interactions
-            : []) {
-            if (!interaction || typeof interaction !== "object" || Array.isArray(interaction)) {
-                continue;
-            }
-            const name = interaction.name;
-            if (typeof name === "string" && name.trim())
-                interactionNames.add(name);
-        }
-    }
-    return { uiStateNames, interactionNames };
-}
 /** Compute the authoritative coverage queue from the committed plan ledger. */
 export function collectFrontendPlanMissingFacts(input) {
     const requirements = new Map();
@@ -2864,6 +3269,17 @@ export function collectFrontendPlanPhaseMissingFacts(input) {
     const facts = input.committedFacts
         .map(committedFactFromPlanRecord)
         .filter((fact) => Boolean(fact && fact.origin === "plan"));
+    if (input.phase === "ux-registry") {
+        return facts.some((fact) => fact.kind === "state-registry")
+            ? []
+            : [
+                {
+                    kind: "state-registry",
+                    requirementIds: [...input.requirementIds],
+                    reason: "global UX vocabulary phase has no committed state-registry fact",
+                },
+            ];
+    }
     if (input.phase === "ux-local") {
         const needsUx = input.requirementIds.some((id) => input.behaviorRequiredRequirementIds?.includes(id));
         if (!needsUx)
@@ -2958,10 +3374,9 @@ export function batchFrontendPlanRequirements(input) {
     return batches;
 }
 const FRONTEND_PLAN_COVERAGE_MAX_RECORD_CALLS = 10;
-const FRONTEND_PLAN_UX_LOCAL_MAX_RECORD_CALLS = 6;
-// A large requirement set creates both coverage and UX-local shards. Keep a
-// safety bound, but do not let the old 32-session ceiling skip finalize for a
-// legitimate large plan.
+// A large requirement set creates coverage shards; UX remains one global
+// decision session so behavior names and component/state facts are not
+// reinvented per AC batch. Keep a safety bound for adaptive coverage retries.
 const FRONTEND_PLAN_BATCH_MAX_SESSIONS = 128;
 const FRONTEND_PLAN_SMALL_MAX_REQUIREMENTS = 8;
 const FRONTEND_PLAN_SMALL_MAX_ESTIMATED_CALLS = 24;
@@ -3147,8 +3562,33 @@ export function compactFrontendPlanPromptForRequirementSlice(basePrompt, require
                 }];
         })
         : [];
+    const compactDeclaredUiStates = Array.isArray(payload.declaredUiStates)
+        ? payload.declaredUiStates.flatMap((value) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                return [];
+            const state = value;
+            const id = compactPromptString(state.id, 80);
+            if (!id)
+                return [];
+            return [{
+                    id,
+                    ...(compactPromptString(state.trigger, 180)
+                        ? { trigger: compactPromptString(state.trigger, 180) }
+                        : {}),
+                    ...(compactPromptString(state.observableOutcome, 240)
+                        ? { observableOutcome: compactPromptString(state.observableOutcome, 240) }
+                        : {}),
+                }];
+        })
+        : [];
+    const committedUx = payload.committedUx &&
+        typeof payload.committedUx === "object" &&
+        !Array.isArray(payload.committedUx)
+        ? payload.committedUx
+        : undefined;
     const compactPayload = {
         requirements: compactRequirements,
+        requiredDeliverables: Array.isArray(payload.requiredDeliverables) ? payload.requiredDeliverables : [],
         ...(compactTargetSurface.length > 0
             ? { targetSurface: compactTargetSurface }
             : {}),
@@ -3158,6 +3598,17 @@ export function compactFrontendPlanPromptForRequirementSlice(basePrompt, require
         ...(compactDesignEvidence.length > 0
             ? { designEvidence: compactDesignEvidence }
             : {}),
+        ...(compactDeclaredUiStates.length > 0
+            ? { declaredUiStates: compactDeclaredUiStates }
+            : {}),
+        ...(committedUx
+            ? {
+                committedUx: {
+                    uiStateNames: compactPromptStringArray(committedUx.uiStateNames, 40, 100),
+                    interactionNames: compactPromptStringArray(committedUx.interactionNames, 60, 120),
+                },
+            }
+            : {}),
     };
     const compactBlock = [
         "<frontend_plan_input>",
@@ -3254,6 +3705,8 @@ function compactFrontendPlanLedgerContext(input) {
                             purpose: compactPromptString(item.purpose, 120),
                             component: compactPromptString(item.component, 120),
                             decision: compactPromptString(item.decision, 40),
+                            covers: compactPromptStringArray(item.covers, 40, 120),
+                            evidencePath: compactPromptString(item.evidencePath, 180),
                         }];
                 }).slice(0, 24)
                 : [];
@@ -3261,6 +3714,14 @@ function compactFrontendPlanLedgerContext(input) {
                 compactFacts.push({ kind: fact.kind, uiComponentChoices: choices });
             continue;
         }
+        if (fact.kind === "state-registry") {
+            compactFacts.push({
+                kind: fact.kind,
+                uiStateNames: compactPromptStringArray(fact.uiStateNames, 40, 100),
+                interactionNames: compactPromptStringArray(fact.interactionNames, 60, 120),
+            });
+            continue;
+        }
         if (fact.kind === "state-flow") {
             compactFacts.push({
                 kind: fact.kind,
@@ -3323,6 +3784,7 @@ function compactFrontendPlanLedgerContext(input) {
 export async function runFrontendPlanSegmentedSessions(input) {
     const queue = [];
     const coverageSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "coverage");
+    const uxRegistrySegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "ux-registry");
     const uxSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "ux-local");
     const globalMockDataSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "global-mock-data");
     const finalizeSegment = FRONTEND_PLAN_SEGMENTS.find((segment) => segment.id === "finalize");
@@ -3342,7 +3804,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
                 ? ["plan-requirement", "plan-verification-target", "state-flow", "data-flow", "mock-api"]
                 : segment.id === "global-dependency-deviation"
                     ? ["dependency", "design-deviation"]
-                    : ["plan-requirement", "plan-verification-target", "component-choice", "state-flow", "data-flow", "mock-api", "design-deviation", "dependency", "target-surface"];
+                    : ["plan-requirement", "plan-verification-target", "state-registry", "component-choice", "state-flow", "data-flow", "mock-api", "design-deviation", "dependency", "target-surface"];
         const ledger = input.committedFacts
             ? compactFrontendPlanLedgerContext({
                 committedFacts: input.committedFacts(),
@@ -3378,14 +3840,20 @@ export async function runFrontendPlanSegmentedSessions(input) {
             ? compactFrontendPlanLedgerContext({
                 committedFacts: input.committedFacts(),
                 requirementIds: slice,
-                kinds: ["plan-requirement", "plan-verification-target", "component-choice", "state-flow"],
+                kinds: [
+                    "plan-requirement",
+                    "plan-verification-target",
+                    "state-registry",
+                    "component-choice",
+                    "state-flow",
+                ],
                 scopedKinds: ["component-choice", "state-flow"],
             })
             : "";
         return [
             compactFrontendPlanPromptForRequirementSlice(input.basePrompt, slice),
             uxSegment.instruction,
-            `UX LOCAL BATCH: process ONLY these requirements: ${slice.join(", ")}.`,
+            `GLOBAL UX SCOPE: process the complete requirement set together: ${slice.join(", ")}. Do not split or rename one behavior by requirement id.`,
             ledger,
             ...(missing.length > 0
                 ? [
@@ -3395,6 +3863,37 @@ export async function runFrontendPlanSegmentedSessions(input) {
                 : []),
         ].filter(Boolean).join("\n\n");
     };
+    const buildUxRegistryPrompt = (missing = []) => {
+        const ledger = input.committedFacts
+            ? compactFrontendPlanLedgerContext({
+                committedFacts: input.committedFacts(),
+                requirementIds: allRequirementIds,
+                kinds: [
+                    "plan-requirement",
+                    "plan-verification-target",
+                    "state-registry",
+                ],
+            })
+            : "";
+        const compact = allRequirementIds.length > 0
+            ? compactFrontendPlanPromptForRequirementSlice(input.basePrompt, allRequirementIds, {
+                includeVerificationTargets: false,
+                includeDesignEvidence: false,
+                includeChecklist: false,
+            })
+            : input.basePrompt;
+        return [
+            compact,
+            uxRegistrySegment.instruction,
+            ledger,
+            ...(missing.length > 0
+                ? [
+                    "MISSING-FACT QUEUE: commit the global UX registry, then re-check this phase:",
+                    ...missing.map((item) => `- ${item.reason}`),
+                ]
+                : []),
+        ].filter(Boolean).join("\n\n");
+    };
     const buildCompactLocalPrompt = (missing = []) => {
         const ledger = input.committedFacts
             ? compactFrontendPlanLedgerContext({
@@ -3403,6 +3902,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
                 kinds: [
                     "plan-requirement",
                     "plan-verification-target",
+                    "state-registry",
                     "component-choice",
                     "state-flow",
                 ],
@@ -3411,7 +3911,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
         return [
             compactFrontendPlanPromptForRequirementSlice(input.basePrompt, allRequirementIds),
             "PLAN PHASE — compact local planning for a small frontend request.",
-            "For every listed requirement, record plan-requirement and verification-target facts, then record the component-choice and state-flow facts needed by the observable UX. Do not read the repository or task source; use only the committed input above. Do not call finalize_plan in this session.",
+            "Review all listed requirements together and record_state_registry first with one global UX vocabulary. Then record every plan-requirement and verification-target fact, followed by the component-choice and state-flow facts needed by the observable UX. Do not read the repository or task source; use only the committed input above. Do not call finalize_plan in this session.",
             "TOOL-FIRST: your first assistant actions must be record_* tool calls, at most 2-3 facts per message. Do not draft the whole analysis before recording; if a fact is uncertain, record it with an evidence gap instead of reasoning longer.",
             ledger,
             ...(missing.length > 0
@@ -3462,6 +3962,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
             "record_plan_requirement",
             "record_plan_verification_target",
             "record_plan_evidence_gap",
+            "record_state_registry",
             "record_component_choice",
             "record_state_flow",
             "adopt_staged_fact",
@@ -3504,28 +4005,29 @@ export async function runFrontendPlanSegmentedSessions(input) {
         // Compact mode already queued both sessions above.
     }
     else {
-        const uxCosts = new Map((input.requirementIds ?? []).map((id) => [
-            id,
-            Math.max(2, Math.min(3, input.requirementCosts?.get(id) ?? 2)),
-        ]));
-        const uxSlices = requirementIdsProvided
-            ? batchFrontendPlanRequirements({
-                requirementIds: input.requirementIds,
-                maxEstimatedRecordCalls: FRONTEND_PLAN_UX_LOCAL_MAX_RECORD_CALLS,
-                maxRequirements: 3,
-                requirementCosts: uxCosts,
-            })
-            : [[]];
-        uxSlices.forEach((slice, batchIndex) => queue.push({
-            id: `ux-local-${batchIndex + 1}`,
-            toolNames: uxSegment.toolNames,
-            ...(slice.length > 0 ? { requirementSlice: slice } : {}),
-            prompt: slice.length > 0
-                ? buildUxPrompt(slice)
+        if (requirementIdsProvided) {
+            queue.push({
+                id: uxRegistrySegment.id,
+                toolNames: uxRegistrySegment.toolNames,
+                prompt: buildUxRegistryPrompt(),
+            });
+        }
+        const uxSlice = requirementIdsProvided ? [...allRequirementIds] : [];
+        queue.push({
+            id: "ux-local-1",
+            // Compatibility path for an unreadable requirement inventory: there is
+            // no safe all-requirements registry phase, so the unscoped UX session
+            // must establish its registry before recording state flow.
+            toolNames: requirementIdsProvided
+                ? uxSegment.toolNames
+                : new Set([...(uxSegment.toolNames ?? []), "record_state_registry"]),
+            ...(uxSlice.length > 0 ? { requirementSlice: uxSlice } : {}),
+            prompt: uxSlice.length > 0
+                ? buildUxPrompt(uxSlice)
                 : buildPhasePrompt(uxSegment),
-        }));
+        });
         for (const segment of FRONTEND_PLAN_SEGMENTS) {
-            if (["coverage", "ux-local", "finalize"].includes(segment.id))
+            if (["coverage", "ux-registry", "ux-local", "finalize"].includes(segment.id))
                 continue;
             queue.push({
                 id: segment.id,
@@ -3567,6 +4069,9 @@ export async function runFrontendPlanSegmentedSessions(input) {
         else if (session.id === "compact-local") {
             prompt = buildCompactLocalPrompt(session.missingFacts);
         }
+        else if (session.id === "ux-registry") {
+            prompt = buildUxRegistryPrompt(session.missingFacts);
+        }
         else if (session.id.startsWith("ux-local-")) {
             // Build this at execution time: coverage facts are committed by the
             // preceding sessions and must be visible to the UX-local model.
@@ -3626,6 +4131,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
             })
             : [];
         const isCompactLocalSession = session.id === "compact-local";
+        const isUxRegistrySession = session.id === "ux-registry";
         const isUxLocalSession = session.id.startsWith("ux-local-");
         const missingPhase = isCompactLocalSession && input.committedFacts
             ? [
@@ -3633,6 +4139,11 @@ export async function runFrontendPlanSegmentedSessions(input) {
                     requirementIds: allRequirementIds,
                     committedFacts: input.committedFacts(),
                 }),
+                ...collectFrontendPlanPhaseMissingFacts({
+                    phase: "ux-registry",
+                    requirementIds: allRequirementIds,
+                    committedFacts: input.committedFacts(),
+                }),
                 ...collectFrontendPlanPhaseMissingFacts({
                     phase: "ux-local",
                     requirementIds: allRequirementIds,
@@ -3640,20 +4151,26 @@ export async function runFrontendPlanSegmentedSessions(input) {
                     behaviorRequiredRequirementIds: input.behaviorRequiredRequirementIds,
                 }),
             ]
-            : isUxLocalSession && session.requirementSlice && input.committedFacts
+            : isUxRegistrySession && input.committedFacts
                 ? collectFrontendPlanPhaseMissingFacts({
-                    phase: "ux-local",
-                    requirementIds: session.requirementSlice,
+                    phase: "ux-registry",
+                    requirementIds: allRequirementIds,
                     committedFacts: input.committedFacts(),
-                    behaviorRequiredRequirementIds: input.behaviorRequiredRequirementIds,
                 })
-                : session.id === "global-mock-data" && allRequirementIds.length > 0 && input.committedFacts
+                : isUxLocalSession && session.requirementSlice && input.committedFacts
                     ? collectFrontendPlanPhaseMissingFacts({
-                        phase: "global-mock-data",
-                        requirementIds: allRequirementIds,
+                        phase: "ux-local",
+                        requirementIds: session.requirementSlice,
                         committedFacts: input.committedFacts(),
+                        behaviorRequiredRequirementIds: input.behaviorRequiredRequirementIds,
                     })
-                    : [];
+                    : session.id === "global-mock-data" && allRequirementIds.length > 0 && input.committedFacts
+                        ? collectFrontendPlanPhaseMissingFacts({
+                            phase: "global-mock-data",
+                            requirementIds: allRequirementIds,
+                            committedFacts: input.committedFacts(),
+                        })
+                        : [];
         const missingPhaseFacts = [...missingCoverage, ...missingPhase];
         // Frozen verification commands must operate on files the planner has
         // committed verification targets for; otherwise the admission writeSet
@@ -3681,11 +4198,13 @@ export async function runFrontendPlanSegmentedSessions(input) {
             ? buildCoveragePrompt(session.coverageSlice ?? [], missing)
             : isCompactLocalSession
                 ? buildCompactLocalPrompt(missing)
-                : session.id === "finalize" && useCompactSmallPlan
-                    ? buildCompactFinalizePrompt(missing)
-                    : isUxLocalSession
-                        ? buildUxPrompt(session.requirementSlice ?? [], missing)
-                        : buildPhasePrompt(globalMockDataSegment, missing);
+                : isUxRegistrySession
+                    ? buildUxRegistryPrompt(missing)
+                    : session.id === "finalize" && useCompactSmallPlan
+                        ? buildCompactFinalizePrompt(missing)
+                        : isUxLocalSession
+                            ? buildUxPrompt(session.requirementSlice ?? [], missing)
+                            : buildPhasePrompt(globalMockDataSegment, missing);
         if (result.ok) {
             if (missingPhaseFacts.length === 0) {
                 index += 1;
@@ -3800,7 +4319,7 @@ export async function runFrontendPlanSegmentedSessions(input) {
             });
             continue;
         }
-        if ((session.coverageOnly || isUxLocalSession || session.id === "global-mock-data") &&
+        if ((session.coverageOnly || isUxRegistrySession || isUxLocalSession || session.id === "global-mock-data") &&
             missingPhaseFacts.length > 0 &&
             !result.stderr.trim() &&
             !result.timedOut &&
@@ -4083,6 +4602,10 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                 store,
                 runDir: meta.runDir,
                 nodeId: input.task.id,
+                canonicalRequirements: await resolveFrontendCanonicalRequirements({
+                    cwd: input.cwd,
+                    sourceBinding: meta.spec.sourceBinding,
+                }),
             });
             writerToolPolicy = {
                 requireSdk: true,
@@ -4145,6 +4668,10 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     cwd: input.cwd,
                     sourceBinding: meta.spec.sourceBinding,
                 }),
+                declaredUiStateIds: await resolveFrontendDeclaredUiStateIds({
+                    runDir: meta.runDir,
+                }),
+                workspaceRoot: input.cwd,
             });
             writerToolPolicy = {
                 requireSdk: true,
@@ -4306,12 +4833,8 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
                     ?.kind === "requirement")
                     .map((record) => record.fact?.id)
                     .filter((id) => typeof id === "string");
-                for (const record of contractFacts) {
-                    const fact = record.fact;
-                    if (fact?.kind !== "requirement" || typeof fact.id !== "string")
-                        continue;
-                    const evidence = fact.evidence;
-                    if (evidence?.behavior === "required")
+                for (const fact of resolveFrontendContractRequirements(contractFacts.map((record) => record.fact))) {
+                    if (fact.evidence.behavior === "required")
                         behaviorRequiredRequirementIds.push(fact.id);
                     planRequirementCosts.set(fact.id, estimateFrontendPlanRequirementRecordCalls(fact));
                 }