@tea-agent/loop-agent 0.42.0-next.14 → 0.42.0-next.16

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

@@ -2559,8 +2559,8 @@ function resolveFrontendMockContextBlock(sources) {
     if (mode === "not-required") {
         parts.push("Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed when Mock is intentionally skipped, or select a safe Mock strategy if project evidence supports one.");
         if (frontendMockStrategyMustBeNotNeeded(sources)) {
-            parts.push('Auto mode has no confirmed project Mock capability or no deterministic Mock verification command. The structured contract must set mockApi.strategy to "not-needed". Do not add Mock files or dependencies; keep the real request path as default and record any unproved backend behavior as Real Integration Gap.');
-            parts.push('HARD CONSTRAINT (frozen at generation time): this DAG allows only mockApi.strategy "not-needed"; the prewrite gate rejects any other strategy. If project governance (openspec / ai_workspace / decision records, e.g. a DEC rule requiring native) demands Mock-backed verification, that is a generation-time contract gap, not a plan-revision defect: declare frontendMock.verifyCommands (or policy: "required") in task.json and regenerate the DAG. Do not emit any mockApi.strategy outside the allowlist and do not add Mock files or dependencies within this run.');
+            parts.push('Auto mode has no confirmed project Mock capability or no deterministic Mock verification command. The structured contract must set mockApi.strategy to "not-needed". Keep the real request path as the default, record any unproved backend behavior as Real Integration Gap, and do not add Mock files or dependencies within this run.');
+            parts.push('HARD CONSTRAINT (frozen at generation time): this DAG allows only mockApi.strategy "not-needed"; the prewrite gate rejects any other strategy. If project governance (openspec / ai_workspace / decision records, e.g. a DEC rule requiring native) demands Mock-backed verification, that is a generation-time contract gap, not a plan-revision defect: declare frontendMock.verifyCommands (or policy: "required") in task.json and regenerate the DAG.');
         }
     }
     if (mode === "blocked") {
@@ -3226,9 +3226,7 @@ async function buildFrontendHybridDagFromTask(sources) {
         "Reference frozen commands ONLY by commandId (record_plan_verification_target entry.commandId). The runtime resolves mode and label; never invent a mode or type.",
         ...frontendVerifyDirectory.map((entry) => `  - ${entry.commandId} [${entry.mode}]: ${JSON.stringify(entry.label)}`),
         `- Static command source: ${staticVerifyEvidence.commandSource}`,
-        ...staticVerifyEvidence.commandLabels.map((command) => `  - ${JSON.stringify(command)}`),
         `- Behavior command source: ${behaviorVerifyEvidence.commandSource}`,
-        ...behaviorVerifyEvidence.commandLabels.map((command) => `  - ${JSON.stringify(command)}`),
     ].join("\n");
     const advisories = [];
     if (!hasDeclaredFrontendVerification &&
@@ -3344,13 +3342,16 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_CONTRACT_SKILLS,
-                outputContract: "Typed requirement facts plus a concise Markdown contract. Submit through the incremental typed tools record_requirement / record_constraint / record_evidence_expectation / record_handoff_intent / record_open_question / record_split_proposal / record_openspec_selection, then call finalize_contract exactly once. Requirements use stable REQ/BR/AC identifiers with source spans and a disposition (explicit | repository-resolvable | assumption | blocking); each requirement registers evidence expectations across static/behavior/Mock/real-integration (required | optional | not-applicable), and UI-visible or interactive requirements register a non-blocking frontend-test handoff intent. End finalize_contract with a single contract disposition of ready | ready-with-assumptions | blocked. Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations; do not fix target files, components, or implementation methods as requirements. When OpenSpec candidates exist, classify only the ones you actually use: call record_openspec_selection once per required/relevant path; never enumerate irrelevant candidates (unmentioned defaults to irrelevant) and never emit a fenced selection JSON. No file writes.",
+                outputContract: "Typed requirement facts plus a concise Markdown contract. Submit through the incremental typed tools record_requirement / record_constraint / record_evidence_expectation / record_handoff_intent / record_open_question / record_split_proposal / record_ui_state / record_required_deliverables / record_openspec_selection, then call finalize_contract exactly once. record_requirement takes only the canonical ledger requirement id — the runtime owns the authoritative text, source spans, fragment bindings, and disposition. UI-visible or interactive requirements register a non-blocking frontend-test handoff intent, and any source-declared UI-state table is extracted verbatim through record_ui_state. End finalize_contract with a single contract disposition of ready | ready-with-assumptions | blocked. Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations; do not fix target files, components, or implementation methods as requirements. When OpenSpec candidates exist, classify only the ones you actually use: call record_openspec_selection once per required/relevant path; never enumerate irrelevant candidates (unmentioned defaults to irrelevant) and never emit a fenced selection JSON. No file writes.",
                 subtask_prompt: [
                     "OUTPUT BUDGET DISCIPLINE (hard requirement, extreme-environment safe): the provider output window is small — NEVER attempt to emit the whole contract in one response; a single large JSON dump will be truncated and rejected. Incremental submission through the typed tools is the ONLY supported output mode. Start submitting with the FIRST tool call: after each read, call record_requirement for the requirements you have already confirmed, one or a few per call. Every tool-call round MUST make progress by submitting at least one record_* fact. Do not re-read the same source file that is already materialized in this session; read each file at most once.",
                     "Read task source and produce a concise frontend implementation contract as typed requirement facts plus narrative Markdown.",
-                    "Assign each requirement the SAME id as the ledger canonical requirement it covers (sourceBinding.requirementIds, e.g. AC-001) — do NOT invent new REQ/BR prefixed ids for canonical requirements: the compiled contract must match the ledger canonical requirement ids exactly or schema validation rejects it (unknown requirement id). Requirements use the canonical id with a source span (task-source section or repository file:line). Label each requirement's disposition as explicit | repository-resolvable | assumption | blocking; a blocking requirement must name its owner (human-decision or external-state) and evidence refs.",
-                    "Source fidelity ledger: when the DAG sourceBinding carries a requirement→fragment mapping (requirementToFragments, e.g. REQ-SRC-* ids from the managed ledger), each record_requirement MUST declare the fragments that requirement is bound to: set sourceFragmentIds to the mapped fragment ids (the authoritative provenance evidence the design policy verifies). sourceRefs (fragment→path display refs) are optional — declare them only when you have the exact path from the materialized source; otherwise omit them rather than inventing paths. Declare exactly what the ledger binds — do not invent ids, do not omit them, and do not re-derive them from prose. A requirement that the ledger binds but the contract omits (or fabricates) fails writer admission.",
+                    "Confirm each requirement by the SAME id as the ledger canonical requirement it covers (sourceBinding.requirementIds, e.g. AC-001) — do NOT invent new REQ/BR prefixed ids for canonical requirements: the compiled contract must match the ledger canonical requirement ids exactly or schema validation rejects it (unknown requirement id). record_requirement takes ONLY the canonical id; the runtime commits the authoritative text and sourceFragmentIds from the frozen ledger. Never pass text/statement/sourceFragmentIds yourself — model rewrites and JSON-stringified fragment arrays are rejected.",
+                    "Requirement semantics, source spans, dispositions, and fragment bindings are ledger/runtime-owned. If a canonical requirement is genuinely blocked, say so in the Markdown contract narrative and finalize with the matching disposition instead of trying to encode it in the requirement fact.",
                     "Register evidence expectations for each requirement across static, behavior, Mock, and real integration as required | optional | not-applicable; required must follow from user requirements, task risk, or project governance, never from model convenience. For UI-visible or interactive requirements, register a non-blocking frontend-test handoff intent.",
+                    'Use record_evidence_expectation with {requirementId,evidence:{static,behavior,mock,"real-integration"}}; every lane is required | optional | not-applicable. Requirement text and provenance remain runtime-owned.',
+                    'Before finalize_contract ready, call record_required_deliverables once with the complete {items:[{path,requirementId,sourceFragmentId}]} inventory, or {items:[]} when no file delivery is mandatory. Interpret the original source, including lists and tables: allowedPaths/only-allowed-to-modify is permission, not an obligation; do not promote prohibited files, examples or references into deliverables. Paths must occur exactly in a frozen source fragment bound to that canonical requirement. Correct the whole inventory before finalizing if needed.',
+                    "Authoritative UI states: when the task source declares a UI-state table (state id / trigger / observable outcome), extract it VERBATIM through record_ui_state, one call per state, using the source's own state ids. The planner must bind these ids later — do not rename, merge, or invent states.",
                     "Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations. Do not fix target files, components, styling, or implementation methods as requirements; leave those to Scout and Plan.",
                     "If the task is too large for one bounded writer, record a task split proposal instead of silently widening scope.",
                     "End the contract with a single disposition: ready, ready-with-assumptions (bounded assumptions that do not change product behavior), or blocked.",
@@ -3391,7 +3392,10 @@ async function buildFrontendHybridDagFromTask(sources) {
                 depends_on: ["frontend-contract-pi", "frontend-scout-pi"],
                 role: "planner",
                 executor: "pi",
-                complexity: "MED",
+                // Small topology has already proven a concentrated, no-remote scope;
+                // keep its bounded plan on the LOW model tier. Standard/High retain
+                // MED for broader contract-to-surface decisions.
+                complexity: frontendTaskShape.shape === "small" ? "LOW" : "MED",
                 writePolicy: "read-only",
                 retryPolicy: FRONTEND_PLAN_LADDER_RETRY_POLICY,
                 allowedPaths: readOnlyPaths,
@@ -3408,6 +3412,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Record only: requirement-to-file/verification coverage; component/styling choices; applicable UI state and interaction behavior; data/Mock strategy; and a dependency policy or genuine evidence gap. Reuse Scout paths. If scope is missing, record a blocking gap instead of inventing a path.",
                     "Use the typed tool schemas as the field contract. Runtime owns schemaVersion, sourceBinding, riskLevel, targets.files, mockApi.productionDefaultOff, aliases, command allowlisting, path containment, and final validation; do not restate those rules or emit a full JSON contract.",
                     `Cover each frozen requirement ID exactly once: ${requirementIds.join(", ") || "(none)"}. Bind every verification target to a frozen commandId from the directory above plus a Scout-confirmed file. Behavior commands prove observable behavior: one target may cover multiple related requirementIds when one test behavior proves them together; do not mechanically create one target per requirement. A behavior target id is the stable machine trace token and its file must be a test file. Static commands are project-wide checks traced by file and command only.`,
+                    "UX vocabulary protocol: record_state_registry FIRST with the full global vocabulary — one stable kebab-case behavior-domain name per UI state/interaction (e.g. planner-task-edit, focus-queue-move), never one name per AC number and never a rename of an already-recorded concept. Coverage slices by requirement; UX does not. Then record_state_flow entries whose names all come from that registry; uiState names must use the contract's declared authoritative ids (declaredUiStates in the plan input) when present. Retry attempts see committedUx in this input — reuse those exact names. Components: one choice may cover many state/interaction ids via covers; reuse-existing requires evidencePath naming an existing repo file (greenfield must be decision=new).",
                     ...(requiresOpenspecClassification ? ["When a component choice uses an OpenSpec selection, cite that selection; otherwise do not classify unrelated candidates."] : []),
                     "Call finalize_plan exactly once after the necessary typed facts. Return no Markdown narrative.",
                     "TOOL-ONLY PLAN: Do not read Contract/Scout stdout, task sources, or Scout-confirmed target files. Contract and Scout already own evidence discovery; use the injected upstream facts, record a genuine evidence gap when those facts are insufficient, and start committing record_* facts immediately. For decision=new, pass sourceRequirementIds to record_component_choice; runtime derives the exact PRD citation from the frozen ledger.",
@@ -3499,18 +3504,16 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Your authoritative terminal verdict is exactly one committed typed tool call: approve_design or request_design_changes. Call exactly one of them; after calling one, do not call the other.",
                     "request_design_changes must carry a typed issueCategory, at least one evidenceRef, and non-empty findings.",
                     "Your verdict is consumed as deterministic data input by frontend-writer-admission-shell. approve_design permits admission; request_design_changes blocks writer admission until a recovery plan incorporates every Critical/Important finding.",
-                    "Request design changes when the Mock strategy is MOCK_STRATEGY: blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for a declared behavior target or selected Mock strategy. Mock strategies require Mock-backed evidence. A static-only contract is allowed only when every verification target is static and maps to a declared static entrypoint. not-needed otherwise requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists; in that case the plan must preserve the real request path and record the Real Integration Gap.",
+                    "Request design changes when the Mock strategy is blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for a declared behavior target or selected Mock strategy. Mock strategies require Mock-backed evidence; a static-only contract is allowed only when every verification target is static and maps to a declared static entrypoint; not-needed requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists, in which case the plan must preserve the real request path and record the Real Integration Gap.",
                     "Also request design changes for missing applicable UI states, unsupported dependency additions, design-system drift without reason, weak interaction coverage, broad scope, inline fake data, schema drift, or missing deterministic verification commands.",
-                    "Component selection conformance is a hard blocking condition: request_design_changes when the frontend spec (component/theme/rule.components bucket) already defines a component for a purpose but the plan selects another or self-invents one without a declared deviation; when uiComponentChoices is missing/empty for UI-visible work while the frozen component/theme bucket is non-empty; when a decision=specified specReference.path is missing a ledger OpenSpec reference or successful read event; or when a decision=new component lacks a traceable task-source/PRD specReference. A PRD reference for decision=new is not an OpenSpec citation and must not be rejected merely for lacking an OpenSpec read event.",
-                    "For uiComponentChoices, purpose is the stable coverage key and must match interaction.name or uiState.name. Responsibility is expressed by the matched expectedBehavior plus rationale; you must not reject it merely for matching an interaction or component identifier.",
-                    "You must NOT make authoritative assertions about the execution result of frozen verification commands (typecheck/test/build/lint/etc.). Predicting that a command will necessarily pass or fail, or declaring an acceptance criterion unreachable on that basis, is out of your authority: command results are deterministically established by frontend-verify-shell. Any concern about verification feasibility must be recorded only as a non-blocking verification concern in findings (severity must not be Critical, and it must never be the sole fatal basis for request_design_changes). Only semantic design defects (component selection, state flow, interaction contract, or conflicts with the specification) may be Critical. A pure command-will-fail prediction must not be classified as contract-requirement-gap.",
+                    "Component selection conformance is a hard blocking condition: request_design_changes when the frontend spec (component/theme/rule.components bucket) already defines a component for a purpose but the plan selects another or self-invents one without a declared deviation; when uiComponentChoices is missing/empty for UI-visible work while the frozen component/theme bucket is non-empty; when a decision=specified specReference.path is missing a ledger OpenSpec reference or successful read event; or when a decision=new component lacks a traceable task-source/PRD specReference. A PRD reference for decision=new is not an OpenSpec citation and must not be rejected merely for lacking an OpenSpec read event. For uiComponentChoices, purpose is the stable coverage key and must match interaction.name or uiState.name; responsibility is expressed by the matched expectedBehavior plus rationale, and you must not reject it merely for matching an interaction or component identifier.",
+                    "You must NOT make authoritative assertions about the execution result of frozen verification commands: command results are deterministically established by frontend-verify-shell. Record a verification-feasibility concern only as a non-blocking finding (severity must not be Critical, and it must never be the sole fatal basis for request_design_changes). Only semantic design defects (component selection, state flow, interaction contract, or conflicts with the specification) may be Critical; a pure command-will-fail prediction must not be classified as contract-requirement-gap.",
                     "Read-only: do not modify repository files.",
                     "LARGE-FILE AUDIT (avoid full reads): style/theme audit files can be large (e.g. styles.css is often hundreds of KB). Prefer grep to locate the exact rules/variables you must verify (e.g. grep the oc- class, is-* modifier, or --oc- theme variables with their line numbers), then read only the narrow line range when surrounding context is needed. Do not read a large style/test file in full — a single full read can exhaust the read budget and fail the attempt.",
                     "Canonical contract reading: frontend-design-policy-shell prints absolute paths for Contract, Contract index, and the non-blocking Capacity diagnostic. Read the capacity diagnostic first. When it recommends full-contract, read the exact Contract path. When it recommends indexed-sections, read the Contract index and its hash-bound section files instead of opening the full contract. Never resolve a bare contracts/... path against the repository root or hunt for substitutes. Implementation target files inside the writeSet are created later by the implement node: do not read them and do not treat their absence as a design defect.",
                     fixedVerificationContext,
                     sourceContexts.designReview,
                     scopedOpenspecContext,
-                    frontendContractFieldSummary,
                     mockContextBlock,
                 ].join("\n\n"),
             },

package/dist/workflows/dag/node-execution.js

@@ -13,7 +13,7 @@ import { buildDagNodePromptEnvelope, formatConvergenceFeedbackBlock, } from "./p
 import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
 import { materializeDeclaredArtifactFacts } from "./artifact-bindings.js";
 import { buildOutputLimitRecoverySection, loadBackendTestWriterProgressForRetry, } from "./backend-test-writer-completeness.js";
-import { computeBackoffDelayMs, isCanonicalFinalVerifyShellRetryCandidate, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, projectFrontendNodeProtocolFailureReason, resolveFrontendPlanBackupRoute, resolveFrontendPlanRetryStep, VERIFY_SHELL_RETRY_POLICY, } from "./retry-policy.js";
+import { computeBackoffDelayMs, isCanonicalFinalVerifyShellRetryCandidate, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, OUTPUT_LIMIT_RETRY_CATEGORY, projectFrontendNodeProtocolFailureReason, resolveFrontendPlanBackupRoute, resolveFrontendPlanRetryStep, VERIFY_SHELL_RETRY_POLICY, } from "./retry-policy.js";
 import { applyNodeActivity, evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
 import { buildProtocolRetryInstruction, normalizeReviewVerdictAfterRetries, parseJsonReviewVerdict, validateOutputProtocol, } from "./output-protocol.js";
 import { getStructuredContractValidator } from "./contract-output-registry.js";
@@ -21,6 +21,7 @@ import "./contract-validator-registrations.js";
 import { computeNormalizedFailureFingerprint } from "./frontend-recovery-lineage.js";
 import { parseLedgerJson } from "../../task/source-prepare/ledger.js";
 import { readTypedEventStoreFromJsonl } from "./frontend-typed-event-store.js";
+import { collectCanonicalStateFlowNames, extractRequiredDeliverablePaths, resolveFrontendContractRequirements, } from "./frontend-contract-facts.js";
 import { allowedRepairReadPaths, auditRepairAttemptToolUse, buildStructuredOutputRepairPrompt, freezeStructuredOutputRepairContext, hasNonEmptyStructuredCandidate, isFrontendStructuredRepairSchemaId, isStructuredRepairableFailureCategory, persistStructuredAttemptRaw, sessionEventsByteLength, GOVERNANCE_BLOCKED_CATEGORY, STRUCTURED_REPAIR_EXHAUSTED_CATEGORY, } from "./structured-output-repair.js";
 import { readFrontendCanonicalCandidate } from "./frontend-implementation-contract.js";
 import { writeDagNodeJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
@@ -256,6 +257,9 @@ function frontendPlanValidationRetryGuidance(reason) {
     if (/verificationTargets.*uiStates|uiStates.*verificationTargets/i.test(reason)) {
         guidance.push("For this retry, provide verificationTargets[].uiStates as an array; use [] when the target has no named UI state.");
     }
+    if (/duplicate|already recorded/i.test(reason)) {
+        guidance.push("For this retry, re-commit the corrected entry with the same id and replace=true; the ledger compiles the latest submission as the full replacement. A duplicate receipt is a correction invitation, not a prohibition, and backfilling a cited fact's reverse reference in-node does not re-derive committed facts.");
+    }
     return guidance;
 }
 function compactRetryText(text, maxChars) {
@@ -325,6 +329,8 @@ const FRONTEND_CONTRACT_RECORD_TOOL_NAMES_LOCAL = new Set([
     "record_handoff_intent",
     "record_open_question",
     "record_split_proposal",
+    "record_ui_state",
+    "record_required_deliverables",
 ]);
 async function countContractRecordSubmissions(runDir, nodeId) {
     const eventsPath = path.join(runDir, nodeId, "session-events.jsonl");
@@ -553,8 +559,9 @@ export function renderFrontendPlanInputContext(input) {
         : []);
     const contractFacts = committedFacts(input.contractRecords);
     const scoutFacts = committedFacts(input.scoutRecords);
-    const requirements = contractFacts
-        .filter((fact) => fact.kind === "requirement" && fact.origin === "contract")
+    const requirementFacts = resolveFrontendContractRequirements(contractFacts);
+    const requiredDeliverables = extractRequiredDeliverablePaths(contractFacts);
+    const requirements = requirementFacts
         .map((fact) => ({
         id: planInputText(fact.id, 80),
         text: planInputText(fact.text),
@@ -580,19 +587,28 @@ export function renderFrontendPlanInputContext(input) {
         paths: fact.paths,
         conflicts: fact.conflicts,
     }));
+    // Authoritative UI states (contract-declared): the source's UI-state table
+    // extracted by the contract node. The planner binds these ids instead of
+    // inventing list-visibility variants.
+    const declaredUiStates = contractFacts
+        .filter((fact) => fact.kind === "ui-state-declaration" && fact.origin === "contract")
+        .map((fact) => ({
+        id: planInputText(fact.id, 80),
+        trigger: planInputText(fact.trigger),
+        observableOutcome: planInputText(fact.observableOutcome),
+    }))
+        .filter((state) => state.id !== undefined);
+    // Replay registry edits and state-flow removals/additions in commit order.
+    const committedUxNames = collectCanonicalStateFlowNames(input.planRecords ?? [], true);
+    const committedUiStateNames = [...committedUxNames.uiStateNames];
+    const committedInteractionNames = [...committedUxNames.interactionNames];
     // Reviewer-rubric scaffold: the design reviewer re-runs the design-policy
     // checks on the committed facts, so publish the checklist to the producer.
     // Requirements whose contract evidence expects behavioural verification are
     // enumerated explicitly — those are the slots the reviewer finds missing
     // when the plan models interactions ad hoc (r8/r9 findings).
-    const behaviorRequiredIds = requirements
-        .filter((requirement) => {
-        const fact = contractFacts.find((candidate) => candidate.kind === "requirement" &&
-            candidate.origin === "contract" &&
-            candidate.id === requirement.id);
-        const evidence = fact?.evidence;
-        return evidence?.behavior === "required";
-    })
+    const behaviorRequiredIds = requirementFacts
+        .filter((requirement) => requirement.evidence.behavior === "required")
         .map((requirement) => requirement.id);
     const serializeAtCap = (cap) => JSON.stringify({
         requirements: requirements.map((requirement) => ({
@@ -600,6 +616,7 @@ export function renderFrontendPlanInputContext(input) {
             text: planInputText(requirement.text, cap.text),
             sourceFragmentIds: planInputStrings(requirement.sourceFragmentIds).slice(0, cap.array),
         })),
+        requiredDeliverables,
         targetSurface: targetSurface.map((surface) => ({
             completeness: planInputText(surface.completeness, 32),
             entrypoint: planInputText(surface.entrypoint, cap.text),
@@ -615,6 +632,18 @@ export function renderFrontendPlanInputContext(input) {
             paths: planInputStrings(evidence.paths).slice(0, cap.array),
             conflicts: planInputStrings(evidence.conflicts).slice(0, cap.array),
         })),
+        declaredUiStates: declaredUiStates.map((state) => ({
+            id: state.id,
+            trigger: planInputText(state.trigger, cap.text),
+            observableOutcome: planInputText(state.observableOutcome, cap.text),
+        })),
+        committedUx: committedUiStateNames.length > 0 ||
+            committedInteractionNames.length > 0
+            ? {
+                uiStateNames: committedUiStateNames,
+                interactionNames: committedInteractionNames,
+            }
+            : undefined,
     });
     let serialized = serializeAtCap(FRONTEND_PLAN_INPUT_CAP_LADDER[0]);
     for (const cap of FRONTEND_PLAN_INPUT_CAP_LADDER.slice(1)) {
@@ -628,6 +657,7 @@ export function renderFrontendPlanInputContext(input) {
         // to the minimum, and declare the degradation instead of corrupting JSON.
         let fallback = {
             degraded: "requirement-texts-truncated",
+            requiredDeliverables,
             requirements: requirements.map((requirement) => ({
                 id: requirement.id,
                 text: "(truncated)",
@@ -652,20 +682,20 @@ export function renderFrontendPlanInputContext(input) {
         serialized = bounded;
     }
     const checklistLines = [
-        "1. Every interaction you record needs a uiComponentChoices entry whose purpose equals the interaction name, or one decision=reuse-existing choice covering behavioural interactions.",
-        "2. Every applicable UI state needs a purpose-matching component choice or a stylingStrategy.",
-        "3. Every requirement marked (behavior) below needs modelled interactions plus at least one verification target that references it.",
-        "4. targets.files must name the concrete deliverable files; never leave the scope broader than the frozen requirements state.",
+        "1. Record the GLOBAL UX vocabulary with record_state_registry BEFORE any record_state_flow: one stable behavior-domain name per state/interaction (e.g. planner-task-edit), never one name per AC number, and never a rename of an already-recorded concept. Coverage slices by AC; UX does not.",
+        "2. Every recorded interaction/uiState name must be in that registry, and uiState names must use the contract's declared authoritative ids (declaredUiStates below) when present.",
+        "3. Every interaction and every applicable UI state must be covered by a uiComponentChoices entry: its purpose equals the name, or the choice lists the name in covers (one choice may cover many ids). A reuse-existing decision without evidencePath is rejected; stylingStrategy alone covers nothing.",
+        "4. Every requirement marked (behavior) below needs modelled interactions plus at least one verification target that references it.",
         "5. Verification targets may only reference UI states and requirements you actually recorded (the record_* tools reject unknown references).",
         `Requirements requiring behavioural coverage: ${behaviorRequiredIds.length > 0 ? behaviorRequiredIds.join(", ") : "(none)"}`,
-        "6. A decision=new component must declare sourceRequirementIds and pass sourceFragmentId for the frozen PRD fragment whose section matches the component's purpose — the runtime validates that binding and derives specReference (path/section/line); the reviewer checks purpose↔citation consistency.",
+        "6. A decision=new component must declare sourceRequirementIds and pass sourceFragmentId for the frozen PRD fragment whose section matches the component's purpose — the runtime validates that binding and derives specReference (path/section/line); the reviewer checks purpose↔citation consistency. A decision=reuse-existing component must pass evidencePath pointing at the existing repo file that proves the reuse.",
         ...[...input.componentSourceCitations ?? []]
             .filter(([id]) => behaviorRequiredIds.includes(id))
             .flatMap(([id, citations]) => citations.map((citation) => `   ${id} + ${citation.fragmentId} → ${citation.section}${citation.line ? ` (line ${citation.line})` : ""}`)),
     ];
     return [
         "<frontend_plan_input>",
-        "Committed Contract/Scout facts, compiled by the runner. Treat them as the complete planning evidence.",
+        "Committed Contract/Scout facts, compiled by the runner. Treat them as the complete planning evidence. declaredUiStates are the authoritative UI states from the task source; committedUx (retry attempts) is the UX vocabulary already recorded — reuse those names, never re-invent them.",
         serialized,
         "Do not read upstream artifacts, task sources, or repository files. If this input cannot support a decision, record a genuine evidence gap.",
         "</frontend_plan_input>",
@@ -692,6 +722,16 @@ export async function buildFrontendPlanInputContext(runDir, componentSourceCitat
         // forbids reading anything.
         throw new Error(`frontend-plan-input-unavailable: cannot read committed typed facts (${error instanceof Error ? error.message : String(error)})`);
     }
+    // Retry-attempt continuity (UX slice visibility): the plan node's own
+    // committed facts are absent on the first attempt and present on retries;
+    // a missing file is normal there, not a broken pipeline.
+    let planRecords = [];
+    try {
+        planRecords = await readTypedEventStoreFromJsonl(path.join(runDir, "frontend-plan-pi", "plan-typed-facts.jsonl"));
+    }
+    catch {
+        planRecords = [];
+    }
     const committedCount = [...contractRecords, ...scoutRecords].filter((record) => record.phase === "committed").length;
     if (committedCount === 0) {
         throw new Error(`frontend-plan-input-unavailable: no committed Contract/Scout facts in ${contractFactsPath} / ${scoutFactsPath}`);
@@ -699,6 +739,7 @@ export async function buildFrontendPlanInputContext(runDir, componentSourceCitat
     return renderFrontendPlanInputContext({
         contractRecords,
         scoutRecords,
+        planRecords,
         componentSourceCitations,
     });
 }
@@ -736,6 +777,87 @@ export function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFail
             "</retry_instruction>",
         ].join("\n");
     }
+    // Repair-category guidance must outrank the retry ladder position: the
+    // ladder advances monotonically on transport failures (e.g. length →
+    // compact-terminal-first), and its "keep the committed ledger intact"
+    // instruction directly contradicts the repair action for invalid-output /
+    // truncated ledger facts (re-commit corrected record_* facts). When both
+    // apply, the model receives the repair instruction, not the rung script.
+    if (previousFailureCategory === "invalid-output" &&
+        task.structuredContractOutput &&
+        previousProtocolReason) {
+        // The frontend plan node's compile authority is the committed typed
+        // ledger, not a fenced JSON text artifact: its retry guidance must
+        // direct the model to re-commit corrected record_* facts and
+        // finalize_plan. The legacy full-contract JSON guidance below applies
+        // only to nodes whose authority is still a text contract artifact.
+        if (task.structuredContractOutput.schemaId ===
+            "frontend-implementation-contract-plan-patch-v1") {
+            const splitGuidance = /write-set-too-large|split the task/.test(previousProtocolReason ?? "")
+                ? [
+                    "",
+                    "The writeSet is too large for one implement node. Preserve the complete requirement and file coverage. This needs a Contract-level task split, not a Plan formatting repair. Report the write-set-too-large finding and the affected paths for the controller to resume Contract/split orchestration. Plan cannot change protected targets.files or call Contract-only tools; do not invent a split tool or discard required files.",
+                ]
+                : [];
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "Previous plan ledger facts failed canonical contract validation:",
+                previousProtocolReason,
+                "Fix the reported violations by re-committing corrected record_* facts and calling finalize_plan exactly once. The committed typed ledger is the only compile authority.",
+                "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
+                ...frontendPlanValidationRetryGuidance(previousProtocolReason),
+                ...splitGuidance,
+                "</retry_instruction>",
+            ].join("\n");
+        }
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt produced an invalid frontend implementation contract:",
+            previousProtocolReason,
+            ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
+            "Fix every reported field violation: do not emit null for optional fields, do not misspell field names, and match the required types exactly.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory === "invalid-output" &&
+        task.id === "frontend-scout-pi") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "The previous Scout attempt did not commit a complete, runtime-evidenced target surface.",
+            "Search the repository only as needed to establish the real entrypoint, implementation ownership, and applicable test path. Commit record_target_surface with completeness=complete and unresolvedPaths=[] only after at least one named target has fresh runtime evidence, unless the task source explicitly declares a greenfield target: in that case every future path must be source-declared by the runtime-enriched fact. If ownership truly cannot be established, record completeness=blocked with each unresolved path; do not make Plan discover it.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory === "structured-output-truncated" &&
+        task.structuredContractOutput) {
+        if (task.structuredContractOutput.schemaId ===
+            "frontend-implementation-contract-plan-patch-v1") {
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "Previous attempt was truncated by the provider (stopReason=length) before the plan facts were fully committed.",
+                "Re-commit the missing record_* facts and call finalize_plan exactly once; the committed typed ledger is the only compile authority. Do NOT re-read contract/scout outputs or source files — use the facts already in context. Commit record_* facts one tool call per message, then finalize_plan immediately.",
+                "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
+                "</retry_instruction>",
+            ].join("\n");
+        }
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt was truncated by the provider (stopReason=length) before the JSON contract was completed.",
+            ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
+            "The JSON artifact must be complete; omit evidence excerpts and duplicated upstream context.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (frontendPlanRetryStep === "compact-terminal-first") {
         return [
             basePrompt,
@@ -807,83 +929,25 @@ export function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFail
             "</retry_instruction>",
         ].join("\n");
     }
-    if (previousFailureCategory === "invalid-output" &&
-        task.structuredContractOutput &&
-        previousProtocolReason) {
-        // The frontend plan node's compile authority is the committed typed
-        // ledger, not a fenced JSON text artifact: its retry guidance must
-        // direct the model to re-commit corrected record_* facts and
-        // finalize_plan. The legacy full-contract JSON guidance below applies
-        // only to nodes whose authority is still a text contract artifact.
-        if (task.structuredContractOutput.schemaId ===
-            "frontend-implementation-contract-plan-patch-v1") {
-            const splitGuidance = /write-set-too-large|split the task/.test(previousProtocolReason ?? "")
-                ? [
-                    "",
-                    "The writeSet is too large for one implement node. Do NOT delete implementation files to squeeze under the limit — that drops required work. Split the task via record_split_proposal (or narrow targets.files to a genuine subset) so each implement node stays bounded; the full file set must remain covered across the split.",
-                ]
-                : [];
-            return [
-                basePrompt,
-                "",
-                "<retry_instruction>",
-                "Previous plan ledger facts failed canonical contract validation:",
-                previousProtocolReason,
-                "Fix the reported violations by re-committing corrected record_* facts and calling finalize_plan exactly once. The committed typed ledger is the only compile authority.",
-                "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
-                ...frontendPlanValidationRetryGuidance(previousProtocolReason),
-                ...splitGuidance,
-                "</retry_instruction>",
-            ].join("\n");
-        }
-        return [
-            basePrompt,
-            "",
-            "<retry_instruction>",
-            "Previous attempt produced an invalid frontend implementation contract:",
-            previousProtocolReason,
-            ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
-            "Fix every reported field violation: do not emit null for optional fields, do not misspell field names, and match the required types exactly.",
-            "</retry_instruction>",
-        ].join("\n");
-    }
-    if (previousFailureCategory === "invalid-output" &&
-        task.id === "frontend-scout-pi") {
-        return [
-            basePrompt,
-            "",
-            "<retry_instruction>",
-            "The previous Scout attempt did not commit a complete, runtime-evidenced target surface.",
-            "Search the repository only as needed to establish the real entrypoint, implementation ownership, and applicable test path. Commit record_target_surface with completeness=complete and unresolvedPaths=[] only after at least one named target has fresh runtime evidence, unless the task source explicitly declares a greenfield target: in that case every future path must be source-declared by the runtime-enriched fact. If ownership truly cannot be established, record completeness=blocked with each unresolved path; do not make Plan discover it.",
-            "</retry_instruction>",
-        ].join("\n");
-    }
-    if (previousFailureCategory === "structured-output-truncated" &&
-        task.structuredContractOutput) {
-        if (task.structuredContractOutput.schemaId ===
-            "frontend-implementation-contract-plan-patch-v1") {
-            return [
-                basePrompt,
-                "",
-                "<retry_instruction>",
-                "Previous attempt was truncated by the provider (stopReason=length) before the plan facts were fully committed.",
-                "Re-commit the missing record_* facts and call finalize_plan exactly once; the committed typed ledger is the only compile authority. Do NOT re-read contract/scout outputs or source files — use the facts already in context. Commit record_* facts one tool call per message, then finalize_plan immediately.",
-                "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
-                "</retry_instruction>",
-            ].join("\n");
-        }
+    // Generic output-limit fallback. Every branch above this one carries a
+    // more precise instruction for the same capacity signal (contract repair
+    // reasons, ladder rungs — compact-terminal-first is the reason-mandated
+    // rung for length-before-terminal —, protocol/review/read-burst repair),
+    // so output-limit must not shadow them.
+    if (previousFailureCategory === OUTPUT_LIMIT_RETRY_CATEGORY) {
         return [
             basePrompt,
             "",
             "<retry_instruction>",
-            "Previous attempt was truncated by the provider (stopReason=length) before the JSON contract was completed.",
-            ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
-            "The JSON artifact must be complete; omit evidence excerpts and duplicated upstream context.",
+            "The previous turn ended with stopReason=length before the required output was complete. This is output-capacity truncation, not empty output.",
+            "Continue incrementally from already committed typed facts and current in-scope workspace files. Do not repeat completed discovery, decisions, facts, or writes.",
+            "Generate the smallest unfinished unit next, validate its required format immediately, repair any format error in this node, and only then continue to the next unfinished unit or terminal tool.",
+            "Keep prose minimal and finish the required terminal/output protocol as soon as the remaining work is valid.",
             "</retry_instruction>",
         ].join("\n");
     }
     if (previousFailureCategory === "writer-empty-diff") {
-        const maxAttempts = task.retryPolicy?.maxAttempts ?? 3;
+        const maxAttempts = task.retryPolicy?.maxAttempts ?? 5;
         // When a completeness progress exists for this writer, fold the concrete
         // target paths into the empty-diff retry so the model does not guess and
         // does not need to read a forbidden `.harness/**` evidence file.
@@ -911,7 +975,7 @@ export function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFail
         ].join("\n");
     }
     if (previousFailureCategory === "incomplete-write-set") {
-        const maxAttempts = task.retryPolicy?.maxAttempts ?? 3;
+        const maxAttempts = task.retryPolicy?.maxAttempts ?? 5;
         const bindingOnly = task.id?.startsWith("generate-backend-md-case-") === true &&
             (recoveryTargetPaths?.length ?? 0) === 1 &&
             Object.values(recoveryDiagnostics ?? {}).flat().some((detail) => /(?:unclassified Test Points|duplicate Test Point bindings)/i.test(detail));
@@ -1727,6 +1791,32 @@ export async function executeDagNode(input) {
                 durationMs: 0,
             };
         }
+        // stopReason=length on top of a bare empty-output verdict is a provider
+        // capacity signal, not a true empty response: reroute it through the
+        // dedicated output-limit retry path while keeping the raw category for
+        // diagnostics. Bare empty-output and transport aliases (network,
+        // nonzero-exit, unknown) are rerouted — categories that already carry a
+        // precise repair instruction (output-too-large, invalid-output,
+        // protocol-invalid, structured-output-truncated via the validators below,
+        // writer categories) keep their classification so their exact retry
+        // guidance still reaches the model.
+        if (task.executor === "pi" &&
+            !result.ok &&
+            result.stopReason === "length" &&
+            (result.failureCategory === undefined ||
+                ["empty-output", "network", "nonzero-exit", "unknown"].includes(result.failureCategory))) {
+            result = {
+                ...result,
+                rawFailureCategory: result.rawFailureCategory ?? result.failureCategory,
+                failureCategory: OUTPUT_LIMIT_RETRY_CATEGORY,
+                stderr: [
+                    result.stderr,
+                    "output-limit: stopReason=length; preserve completed work and retry only the unfinished output",
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+            };
+        }
         if (task.id === "generate-backend-md-plan-pi" &&
             !result.ok &&
             (result.failureCategory === "output-too-large" ||
@@ -1860,7 +1950,7 @@ export async function executeDagNode(input) {
             !result.ok &&
             retryPolicy !== undefined) {
             const submissions = await countContractRecordSubmissions(runDir, nodeId);
-            if (submissions === 0) {
+            if (submissions === 0 && result.stopReason !== "length") {
                 result = {
                     ...result,
                     failureCategory: "empty-output",

package/dist/workflows/dag/rerun-feedback.js

@@ -408,6 +408,7 @@ export async function deriveDagRerunFeedback(input) {
             return (node?.status === "ERROR" &&
                 [
                     "empty-output",
+                    "output-limit",
                     "invalid-output",
                     "writer-thinking-exhausted",
                     "writer-budget-exhausted",