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

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

@@ -0,0 +1,130 @@
+import { z } from "zod";
+/** Shared projections of committed frontend facts. Callers filter commit phase. */
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Join requirement-owned identity with separately committed evidence by id.
+ * Later evidence declarations replace only the lanes they explicitly name. */
+export function resolveFrontendContractRequirements(facts) {
+    const contractFacts = facts.map(object).filter((fact) => fact?.origin === "contract");
+    const evidenceById = new Map();
+    for (const fact of contractFacts) {
+        if (fact.kind !== "evidence-expectation" ||
+            typeof fact.requirementId !== "string")
+            continue;
+        evidenceById.set(fact.requirementId, {
+            ...evidenceById.get(fact.requirementId),
+            ...object(fact.evidence),
+        });
+    }
+    return contractFacts.flatMap((fact) => fact.kind === "requirement" && typeof fact.id === "string"
+        ? [{
+                ...fact,
+                id: fact.id,
+                evidence: { ...object(fact.evidence), ...evidenceById.get(fact.id) },
+            }]
+        : []);
+}
+function names(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string" && item.trim().length > 0)
+        : [];
+}
+const evidenceStatus = z.enum(["required", "optional", "not-applicable"]);
+export const frontendEvidenceExpectationSchema = z.object({
+    requirementId: z.string().min(1),
+    evidence: z.object({
+        static: evidenceStatus.optional(),
+        behavior: evidenceStatus.optional(),
+        mock: evidenceStatus.optional(),
+        "real-integration": evidenceStatus.optional(),
+    }).strict().refine((evidence) => Object.keys(evidence).length > 0, "declare at least one evidence lane"),
+}).strict();
+const concretePath = z.string().min(1).refine((value) => value === value.trim() &&
+    !/^[A-Za-z]:/.test(value) &&
+    !/[\\*?\[\]{}\0]/.test(value) &&
+    value.split("/").every((part) => part !== "" && part !== "." && part !== ".."), "must be a concrete relative POSIX file path without traversal");
+export const frontendRequiredDeliverablesSchema = z.object({
+    items: z.array(z.object({
+        path: concretePath,
+        requirementId: z.string().min(1),
+        sourceFragmentId: z.string().min(1),
+    }).strict()),
+}).strict();
+/** Validate structure and provenance; the Contract model owns the distinction
+ * between delivery obligations, permissions, prohibitions and references. */
+export function validateFrontendRequiredDeliverables(value, requirements) {
+    const declaration = frontendRequiredDeliverablesSchema.parse(value);
+    for (const item of declaration.items) {
+        const requirement = requirements.get(item.requirementId);
+        if (!requirement?.sourceFragmentIds.includes(item.sourceFragmentId)) {
+            throw new Error(`required deliverable ${item.path} has an unknown requirement/fragment binding`);
+        }
+        const text = requirement.sourceFragments?.get(item.sourceFragmentId);
+        const escaped = item.path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        // A sentence-ending period is punctuation; a dot followed by filename
+        // characters is still part of the token (app.ts must not match app.ts.map).
+        const exactPath = new RegExp(`(^|[^\\p{L}\\p{N}_./-])${escaped}(?=$|[^\\p{L}\\p{N}_./-]|\\.(?=$|[^\\p{L}\\p{N}_./-]))`, "u");
+        if (!text || !exactPath.test(text)) {
+            throw new Error(`required deliverable ${item.path} is not an exact path in frozen source fragment ${item.sourceFragmentId}`);
+        }
+    }
+    return declaration;
+}
+/** Read the latest explicit inventory. Never infer obligations from prose. */
+export function extractRequiredDeliverablePaths(facts) {
+    const declaration = facts.map(object).filter((fact) => fact?.origin === "contract" && fact.kind === "required-deliverables").at(-1);
+    if (!declaration)
+        return [];
+    const { items } = frontendRequiredDeliverablesSchema.parse({ items: declaration.items });
+    return [...new Set(items.map((item) => item.path))].sort();
+}
+/** Apply state-flow replacement/removal semantics exactly as the plan compiler does. */
+export function collectCanonicalStateFlowNames(committedFacts, includeRegistry = false) {
+    const uiStateNames = new Set();
+    const interactionNames = new Set();
+    for (const value of committedFacts) {
+        const record = object(value);
+        if (!record || (record.phase !== undefined && record.phase !== "committed"))
+            continue;
+        const fact = object(record.fact) ?? record;
+        if (fact.origin !== "plan")
+            continue;
+        if (includeRegistry && fact.kind === "state-registry") {
+            uiStateNames.clear();
+            interactionNames.clear();
+            for (const name of names(fact.uiStateNames))
+                uiStateNames.add(name);
+            for (const name of names(fact.interactionNames))
+                interactionNames.add(name);
+        }
+        if (fact.kind !== "state-flow")
+            continue;
+        for (const name of names(fact.removeUiStateNames)) {
+            uiStateNames.delete(name);
+        }
+        for (const name of names(fact.removeInteractionNames)) {
+            interactionNames.delete(name);
+        }
+        for (const state of Array.isArray(fact.uiStates) ? fact.uiStates : []) {
+            if (!state || typeof state !== "object" || Array.isArray(state))
+                continue;
+            const name = state.name;
+            if (typeof name === "string" && name.trim())
+                uiStateNames.add(name);
+        }
+        for (const interaction of Array.isArray(fact.interactions)
+            ? fact.interactions
+            : []) {
+            if (!interaction || typeof interaction !== "object" || Array.isArray(interaction)) {
+                continue;
+            }
+            const name = interaction.name;
+            if (typeof name === "string" && name.trim())
+                interactionNames.add(name);
+        }
+    }
+    return { uiStateNames, interactionNames };
+}

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.",