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

package/dist/workflows/dag/frontend-design-policy.js

@@ -28,31 +28,37 @@ function sortFindings(findings) {
  * visual UI-state dimension (it cannot cover behavioural interactions). */
 export function checkUiDesignCoverage(contract) {
     const findings = [];
-    const purposes = new Set((contract.uiComponentChoices ?? []).map((choice) => choice.purpose));
-    const hasStyling = Boolean(contract.stylingStrategy?.trim());
-    // Reuse of an existing component/pattern covers behavioural interactions
-    // without forcing one uiComponentChoices row per interaction: the model
-    // should not enumerate every click/hover on a reused Button. Only
-    // interactions with no reuse and no explicit purpose are flagged.
-    const hasReuseChoice = (contract.uiComponentChoices ?? []).some((choice) => choice.decision === "reuse-existing");
+    // Explicit per-id coverage (dogfood r-plan-quality): one choice covers an
+    // interaction/state when its purpose equals the name OR the choice lists
+    // the name in covers. The old wildcards are gone — a single reuse-existing
+    // row no longer passes every interaction, and a non-empty stylingStrategy
+    // no longer passes every state.
+    const covered = new Set();
+    for (const choice of contract.uiComponentChoices ?? []) {
+        if (choice.purpose.trim())
+            covered.add(choice.purpose);
+        for (const id of choice.covers ?? []) {
+            if (id.trim())
+                covered.add(id);
+        }
+    }
     for (const state of contract.uiStates) {
         if (!state.applicable)
             continue;
-        const covered = purposes.has(state.name) || hasStyling;
-        if (!covered) {
+        if (!covered.has(state.name)) {
             findings.push({
                 code: "ui-design-coverage-missing",
-                message: `applicable UI state "${state.name}" has no matching uiComponentChoices.purpose or stylingStrategy`,
+                message: `applicable UI state "${state.name}" is not covered by any uiComponentChoices purpose or covers entry`,
                 path: state.name,
             });
         }
     }
     for (const interaction of contract.interactions) {
-        if (purposes.has(interaction.name) || hasReuseChoice)
+        if (covered.has(interaction.name))
             continue;
         findings.push({
             code: "ui-design-coverage-missing",
-            message: `interaction "${interaction.name}" has no matching uiComponentChoices.purpose and no reuse-existing choice covering it`,
+            message: `interaction "${interaction.name}" is not covered by any uiComponentChoices purpose or covers entry`,
             path: interaction.name,
         });
     }
@@ -158,7 +164,7 @@ export function checkMockStrategy(contract, allowedMockStrategies) {
  * A component specReference must still not point into clearly non-component
  * spec areas — templates and the ai_workspace governance subtree cannot be the
  * authoritative component definition. */
-export function checkComponentChoice(contract, componentSpecCandidatePaths) {
+export function checkComponentChoice(contract, componentSpecCandidatePaths, options) {
     const findings = [];
     const candidates = new Set(componentSpecCandidatePaths.map(normalizeRelativePath));
     const isNonComponentSpecArea = (path) => {
@@ -200,6 +206,23 @@ export function checkComponentChoice(contract, componentSpecCandidatePaths) {
                 });
             }
         }
+        else if (choice.decision === "reuse-existing") {
+            if (!(choice.evidencePath && choice.evidencePath.trim().length > 0)) {
+                findings.push({
+                    code: "component-reuse-evidence-missing",
+                    message: `reuse-existing component choice #${index} is missing evidencePath naming the existing repo file that proves the reuse; a greenfield path must use decision=new`,
+                    path: choice.purpose,
+                });
+            }
+            else if (options?.hasFreshPathEvidence &&
+                !options.hasFreshPathEvidence(choice.evidencePath)) {
+                findings.push({
+                    code: "component-reuse-path-not-fresh",
+                    message: `reuse-existing component choice #${index} evidencePath "${choice.evidencePath}" has no fresh existence evidence (path not found); reuse requires an existing file — use decision=new for greenfield paths`,
+                    path: choice.evidencePath,
+                });
+            }
+        }
         else if (choice.decision === "new") {
             if (!choice.specReference || !choice.specReference.path) {
                 findings.push({
@@ -371,6 +394,64 @@ export function checkDesignApproval(designApproval) {
     }
     return [];
 }
+/**
+ * UX vocabulary collisions (item ③, dogfood dag-1788504923861-0f7b17a9):
+ * prioritize-planner-task / prioritizePlannerTask / prioritize-planner-tasks
+ * are one behavior renamed three ways. Case/separator-insensitive duplicates
+ * inside interactions or inside uiStates are blocking.
+ */
+export function checkUxNameCollisions(contract) {
+    const findings = [];
+    const normalize = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
+    const collisions = (names, kind) => {
+        const byNormalized = new Map();
+        const found = [];
+        for (const name of names) {
+            const key = normalize(name);
+            if (!key)
+                continue;
+            const existing = byNormalized.get(key);
+            if (existing !== undefined && existing !== name) {
+                found.push({
+                    code: "ux-name-collision",
+                    message: `"${name}" and "${existing}" are the same ${kind} name up to case/separator — one behavior must keep one stable name`,
+                    path: name,
+                });
+            }
+            else {
+                byNormalized.set(key, name);
+            }
+        }
+        return found;
+    };
+    findings.push(...collisions(contract.interactions.map((interaction) => interaction.name), "interaction"));
+    findings.push(...collisions(contract.uiStates.map((state) => state.name), "UI state"));
+    return findings;
+}
+/**
+ * Deliverable completeness (item ⑦): every file explicitly declared by Contract
+ * from frozen source fragments (projected into targets.requiredDeliverables)
+ * must be planned — bound by some requirement's implementationTargets or a
+ * verification target's file, or listed in targets.files. allowedPaths is a
+ * write boundary and never implies coverage.
+ */
+export function checkRequiredDeliverables(contract) {
+    const required = contract.targets.requiredDeliverables ?? [];
+    if (required.length === 0)
+        return [];
+    const planned = new Set([
+        ...contract.targets.files,
+        ...contract.requirements.flatMap((requirement) => requirement.implementationTargets),
+        ...contract.verificationTargets.map((target) => target.file),
+    ]);
+    return required
+        .filter((path) => !planned.has(path))
+        .map((path) => ({
+        code: "required-deliverable-unplanned",
+        message: `Contract declares required deliverable "${path}" but no requirement implementationTarget, verification target, or targets.files entry plans it`,
+        path,
+    }));
+}
 /** Aggregate the deterministic design-policy checks into a single
  * deterministic result. Any finding blocks; an empty finding list approves. */
 export function evaluateFrontendDesignPolicy(input) {
@@ -379,10 +460,14 @@ export function evaluateFrontendDesignPolicy(input) {
         ...checkUiDesignCoverage(input.contract),
         ...checkSourceFreshness(input.contract, input.sourceFreshness),
         ...checkMockStrategy(input.contract, input.allowedMockStrategies),
-        ...checkComponentChoice(input.contract, input.componentSpecCandidatePaths),
+        ...checkComponentChoice(input.contract, input.componentSpecCandidatePaths, input.hasFreshPathEvidence
+            ? { hasFreshPathEvidence: input.hasFreshPathEvidence }
+            : undefined),
         ...checkTargetPaths(input.contract, input.writeSetPatterns),
         ...checkDependencies(input.contract, input.allowedDependencies),
         ...checkUiStateAttribution(input.contract),
+        ...checkUxNameCollisions(input.contract),
+        ...checkRequiredDeliverables(input.contract),
     ]);
     const classification = findings.length > 0 ? "blocked" : "approved";
     const result = {

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

@@ -9,10 +9,12 @@ import { findPackageRoot } from "../../shared/package-metadata.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
 import { readTypedEventStoreFromJsonl } from "./frontend-typed-event-store.js";
+import { extractRequiredDeliverablePaths } from "./frontend-contract-facts.js";
+export { extractRequiredDeliverablePaths } from "./frontend-contract-facts.js";
 // Cycle-safe value imports: the check functions are hoisted declarations used
 // only at call time, so the contract module and the policy module can depend
 // on each other without module-init ordering issues.
-import { checkDependencies, checkTargetPaths, checkUiDesignCoverage, checkUiStateAttribution, } from "./frontend-design-policy.js";
+import { checkDependencies, checkTargetPaths, checkUiDesignCoverage, checkUiStateAttribution, checkRequiredDeliverables, checkUxNameCollisions, } from "./frontend-design-policy.js";
 import { isDagSourceBindingV2 } from "./types.js";
 import { canonicalContractRel, classifyStructuredContractFailure, formatStructuredArtifactPointer, persistRuntimeSkeleton, } from "./structured-output-repair.js";
 import { renderFrontendPlanMarkdown } from "./frontend-plan-render.js";
@@ -600,12 +602,30 @@ const uiComponentChoiceSchema = z
     decision: z.enum(["specified", "reuse-existing", "new"]),
     specReference: uiComponentSpecReferenceSchema.nullable().optional(),
     // Optional: the decision enum already carries the semantic (specified →
-    // specReference, new → task-source traceability, reuse-existing → no
-    // rationale needed).
-    // Omit for reuse-existing to keep plan output small.
+    // specReference, new → task-source traceability, reuse-existing →
+    // evidencePath). Omit for reuse-existing to keep plan output small.
     rationale: z.string().min(1).optional(),
+    // Multi-id coverage (dogfood r-plan-quality): ONE choice may cover many
+    // UI states/interactions explicitly instead of the old implicit
+    // "reuse-existing covers everything" wildcard.
+    covers: z.array(z.string().min(1)).optional(),
+    // reuse-existing evidence (dogfood dag-1788504923861-0f7b17a9: 18
+    // reuse-existing rows cited conventions in a not-yet-written
+    // src/planner.ts): a repo-relative path to the existing file that
+    // proves the reuse. Enforced by superRefine + fresh-existence checks.
+    evidencePath: safePath.optional(),
 })
-    .strict();
+    .strict()
+    .superRefine((choice, ctx) => {
+    if (choice.decision === "reuse-existing" &&
+        !(choice.evidencePath && choice.evidencePath.trim().length > 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["evidencePath"],
+            message: "decision=reuse-existing requires evidencePath naming the existing repo file that proves the reuse; use decision=new for greenfield paths",
+        });
+    }
+});
 const uiComponentChoicesSchema = z.array(uiComponentChoiceSchema);
 /**
  * Normalize unstable model emissions before the strict schema sees them:
@@ -680,6 +700,11 @@ export const frontendImplementationContractSchema = z
         files: z.array(safePath).min(1),
         routes: z.array(z.string().startsWith("/")).optional(),
         publicApiChanges: z.array(z.string().min(1)).optional(),
+        // Runtime-owned deliverable contract (dogfood r-plan-quality):
+        // explicit, source-bound file inventory committed by Contract.
+        // The design-policy completeness gate checks ONLY these —
+        // allowedPaths is a write boundary, not a coverage obligation.
+        requiredDeliverables: z.array(safePath).optional(),
     })
         .strict(),
     requirements: z.array(z
@@ -1634,7 +1659,12 @@ export function compactFrontendImplementationContract(value) {
     const targets = asRecord(record.targets);
     if (targets) {
         const compactTargets = { ...targets };
-        for (const field of ["files", "routes", "publicApiChanges"]) {
+        for (const field of [
+            "files",
+            "routes",
+            "publicApiChanges",
+            "requiredDeliverables",
+        ]) {
             if (Object.hasOwn(compactTargets, field)) {
                 compactTargets[field] = dedupeJsonArray(compactTargets[field]);
             }
@@ -2425,6 +2455,16 @@ export async function analyzeFrontendImplementationContract(input) {
             files: referencedConcretePaths,
         };
     }
+    // Both Plan precheck and policy materialization consume this exact inventory.
+    // Never trust a Plan patch or infer delivery obligations from prose.
+    const contractRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, input.contractNodeId ?? "frontend-contract-pi", "contract-typed-facts.jsonl"));
+    const requiredDeliverables = extractRequiredDeliverablePaths(contractRecords
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact));
+    delete result.data.targets.requiredDeliverables;
+    if (requiredDeliverables.length > 0) {
+        result.data.targets.requiredDeliverables = requiredDeliverables;
+    }
     const blockingGaps = [
         ...(result.data.evidenceGaps ?? []),
         ...result.data.requirements.flatMap((item) => item.evidenceGap ? [item.evidenceGap] : []),
@@ -2632,6 +2672,7 @@ const FRONTEND_PLAN_PATCH_PROTECTED_PATHS = [
     "/sourceBinding",
     "/riskLevel",
     "/targets/files",
+    "/targets/requiredDeliverables",
     "/mockApi/productionDefaultOff",
 ];
 const PLAN_LEDGER_FACT_KINDS_FOR_COMPILE = [
@@ -2680,6 +2721,8 @@ function frontendPlanPatchProtectedPathViolations(patch) {
     const targets = asRecord(record.targets);
     if (targets && Object.hasOwn(targets, "files"))
         violations.push("/targets/files");
+    if (targets && Object.hasOwn(targets, "requiredDeliverables"))
+        violations.push("/targets/requiredDeliverables");
     const mockApi = asRecord(record.mockApi);
     if (mockApi && Object.hasOwn(mockApi, "productionDefaultOff"))
         violations.push("/mockApi/productionDefaultOff");
@@ -2864,6 +2907,8 @@ export async function analyzeFrontendPlanPatchCandidate(input) {
     const policyPreFindings = [
         ...checkUiDesignCoverage(analysis.canonical),
         ...checkUiStateAttribution(analysis.canonical),
+        ...checkRequiredDeliverables(analysis.canonical),
+        ...checkUxNameCollisions(analysis.canonical),
         ...checkDependencies(analysis.canonical, await deriveAllowedDependenciesFromRun(input.runDir)),
         ...checkTargetPaths(analysis.canonical, await deriveWriteSetFromRun(input.runDir)),
     ];
@@ -3082,9 +3127,11 @@ export async function buildContractFromCommittedFacts(input) {
     }
     // b. Committed contract terminal fact (contract-finalized).
     const contractRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, contractNodeId, "contract-typed-facts.jsonl"));
-    const contractKinds = new Set(contractRecords
+    const committedContractFacts = contractRecords
         .filter((record) => record.phase === "committed")
-        .map((record) => record.fact.kind)
+        .map((record) => record.fact);
+    const contractKinds = new Set(committedContractFacts
+        .map((fact) => fact?.kind)
         .filter((kind) => typeof kind === "string"));
     if (!contractKinds.has("contract-finalized")) {
         return {
@@ -3139,6 +3186,7 @@ export async function buildContractFromCommittedFacts(input) {
             runDir: input.runDir,
             rawContractText: serializeDeterministicJson(merged),
             sourceBinding: input.sourceBinding,
+            contractNodeId,
         });
         return {
             ok: true,

package/dist/workflows/dag/frontend-plan-render.js

@@ -12,8 +12,19 @@ function bulletList(items) {
         return "";
     return items.map((item) => `- ${item}`).join("\n");
 }
+/** The runtime's deterministic fallback for an outcome the plan did not
+ * author. It is bookkeeping for the schema's non-empty constraint, not user
+ * prose — the renderer must never present it as requirement content. */
+const IMPLIED_OUTCOME_PREFIX = "implied by contract:";
 function requirementsCoverage(contract) {
-    const lines = contract.requirements.map((requirement) => `- ${requirement.id}: ${requirement.expectedOutcome}`);
+    const lines = contract.requirements.map((requirement) => {
+        const targets = requirement.implementationTargets.join(", ");
+        const verificationTargets = requirement.verificationTargetIds.join(", ");
+        const authoredOutcome = requirement.expectedOutcome.startsWith(IMPLIED_OUTCOME_PREFIX)
+            ? ""
+            : ` — ${requirement.expectedOutcome}`;
+        return `- ${requirement.id} → ${targets || "(no targets)"} [${verificationTargets || "no VT"}]${authoredOutcome}`;
+    });
     return lines.length > 0 ? lines.join("\n") : "_(no requirements)_";
 }
 function uiStateHandling(contract) {
@@ -98,7 +109,7 @@ export function renderFrontendPlanMarkdown(contract) {
         interactionNotes(contract),
         "",
         "## Mock & API Strategy",
-        contract.mockApi.strategy,
+        contract.mockApi?.strategy || "_(not specified)_",
         "",
         "## Dependency Policy",
         contract.dependencyPolicy || "_(not specified)_",

package/dist/workflows/dag/frontend-shadow-dual-write.js

@@ -226,6 +226,7 @@ export function parseTargetSurfaceFacts(text) {
 }
 export const PLAN_LEDGER_FACT_KINDS = [
     "target-surface",
+    "state-registry",
     "component-choice",
     "state-flow",
     "data-flow",

package/dist/workflows/dag/frontend-typed-event-store.js

@@ -95,6 +95,8 @@ export const CONTRACT_FACT_KINDS = [
     "open-question",
     "split-proposal",
     "openspec-selection",
+    "ui-state-declaration",
+    "required-deliverables",
     "contract-finalized",
 ];
 export const CONTRACT_TERMINAL_FACT_KINDS = ["contract-finalized"];
@@ -124,6 +126,7 @@ export const PLAN_RECORD_FACT_KINDS = [
     "plan-requirement",
     "plan-verification-target",
     "plan-evidence-gap",
+    "state-registry",
 ];
 /**
  * A+B (AC-009): typed issue category shared by review and design change

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

@@ -3344,13 +3344,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.",
@@ -3408,6 +3411,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.",

package/dist/workflows/dag/node-execution.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";
@@ -325,6 +326,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 +556,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 +584,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 +613,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 +629,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 +654,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 +679,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 +719,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 +736,7 @@ export async function buildFrontendPlanInputContext(runDir, componentSourceCitat
     return renderFrontendPlanInputContext({
         contractRecords,
         scoutRecords,
+        planRecords,
         componentSourceCitations,
     });
 }

package/docs/operations/README.md

@@ -11,5 +11,6 @@
 - [`production-readiness.md`](production-readiness.md)：交付前的生产就绪判断。
 - [`agent-worker-production-readiness.md`](agent-worker-production-readiness.md)：agent-worker Feature/Task Pool 外层编排的 Production Readiness v1 操作合同。
 - [`backend-test-jacoco-coverage.md`](backend-test-jacoco-coverage.md)：Java 被测服务挂载 JaCoCo tcpserver agent 的 Maven、`java -jar` 与 Docker 操作手册。
+- [`console-chat-dogfood-playbook.md`](console-chat-dogfood-playbook.md)：Operator Chat（含 Explore 子 Agent）真实模型 dogfood 的 CLI 驱动步骤、mutation 双 token / SSE 超时 / question 应答等已知陷阱与验证方式。
 
 验证命令仍以 [`../governance/verification-matrix.md`](../governance/verification-matrix.md) 为准。

package/docs/templates/frontend-implementation-contract.schema.json

@@ -58,6 +58,12 @@
             "type": "string",
             "minLength": 1
           }
+        },
+        "requiredDeliverables": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/path"
+          }
         }
       }
     },
@@ -433,8 +439,7 @@
         "required": [
           "purpose",
           "component",
-          "decision",
-          "rationale"
+          "decision"
         ],
         "properties": {
           "purpose": {
@@ -465,6 +470,16 @@
           "rationale": {
             "type": "string",
             "minLength": 1
+          },
+          "covers": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "evidencePath": {
+            "$ref": "#/$defs/path"
           }
         },
         "allOf": [
@@ -511,6 +526,23 @@
                 }
               }
             }
+          },
+          {
+            "if": {
+              "properties": {
+                "decision": {
+                  "const": "reuse-existing"
+                }
+              },
+              "required": [
+                "decision"
+              ]
+            },
+            "then": {
+              "required": [
+                "evidencePath"
+              ]
+            }
           }
         ]
       }