@tea-agent/loop-agent 0.41.0 → 0.41.1-beta.0

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

@@ -8,8 +8,16 @@ import { writeTextArtifactFile } from "../../infrastructure/harness/artifact-sto
 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";
+// 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 { isDagSourceBindingV2 } from "./types.js";
-import { canonicalContractRel, classifyStructuredContractFailure, formatStructuredArtifactPointer, openspecCitationsRel, parseOpenspecCitationsBlock, persistRuntimeSkeleton, } from "./structured-output-repair.js";
+import { canonicalContractRel, classifyStructuredContractFailure, formatStructuredArtifactPointer, persistRuntimeSkeleton, } from "./structured-output-repair.js";
+import { renderFrontendPlanMarkdown } from "./frontend-plan-render.js";
+import { isConfigurationVerificationFile, verificationSymbolMatchesContent, } from "./frontend-verification-trace.js";
+import { FRONTEND_READ_BUDGETS } from "./frontend-read-budgets.js";
 export const frontendNormalizationActionSchema = z.enum([
     "remove-trailing-commas",
     "strip-comments",
@@ -17,6 +25,7 @@ export const frontendNormalizationActionSchema = z.enum([
     "canonicalize-verification-alias",
     "drop-unresolved-verification-symbols",
     "inject-source-binding",
+    "compact-canonical-contract",
 ]);
 export function sha256Hex(input) {
     return createHash("sha256").update(input, "utf8").digest("hex");
@@ -40,6 +49,15 @@ function sortKeysDeep(value) {
 export function serializeDeterministicJson(value) {
     return JSON.stringify(sortKeysDeep(value), null, 2);
 }
+/**
+ * Deterministic compact JSON for the canonical contract artifact. The pretty
+ * serializer remains the default for human-facing audit artifacts, while the
+ * writer contract uses this representation to reduce artifact size and
+ * downstream read pressure without changing contract semantics.
+ */
+export function serializeCompactDeterministicJson(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
 export function deterministicSha256(value) {
     return sha256Hex(serializeDeterministicJson(value));
 }
@@ -70,6 +88,13 @@ export async function writeDeterministicJsonArtifact(runDir, relativePath, value
     await writeTextArtifactFile(targetPath, json);
     return { path: targetPath, sha256: sha256Hex(json) };
 }
+/** Write a canonical contract artifact with compact deterministic JSON. */
+export async function writeCompactDeterministicJsonArtifact(runDir, relativePath, value) {
+    const json = `${serializeCompactDeterministicJson(value)}\n`;
+    const targetPath = path.join(runDir, relativePath);
+    await writeTextArtifactFile(targetPath, json);
+    return { path: targetPath, sha256: sha256Hex(json) };
+}
 /**
  * Extract frozen command labels from the DAG run spec (run.json).
  * The run spec is written before any node executes, so it is always available
@@ -104,8 +129,93 @@ async function deriveFrozenCommandLabelsFromRun(runDir) {
     }
     return [...labels];
 }
+/**
+ * Extract the design-policy allowedDependencies set from the DAG run spec
+ * (run.json), mirroring `deriveFrozenCommandLabelsFromRun`. Used by the plan
+ * node's front-loaded policy pre-check so dependency declarations can be
+ * corrected through the retry ladder before the policy shell (the authority)
+ * re-runs the same check on committed facts.
+ */
+async function deriveAllowedDependenciesFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const deps = new Set();
+    for (const task of spec.tasks ?? []) {
+        const allowed = task.shell?.frontendDesignPolicy?.allowedDependencies;
+        if (allowed) {
+            for (const dep of allowed)
+                deps.add(dep);
+        }
+    }
+    return [...deps];
+}
+/** Read the frozen implementation writeSet patterns from run.json so the plan
+ * validator can front-load checkTargetPaths (write-set-too-large) before the
+ * design-policy shell terminates the run. */
+async function deriveWriteSetFromRun(runDir) {
+    const specPath = path.join(runDir, "run.json");
+    let raw;
+    try {
+        raw = await readFile(specPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const writeSet = new Set();
+    for (const task of spec.tasks ?? []) {
+        const patterns = task.shell?.frontendDesignPolicy?.implementationWriteSet;
+        if (patterns) {
+            for (const pattern of patterns)
+                writeSet.add(pattern);
+        }
+    }
+    return [...writeSet];
+}
 export const FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID = "frontend-implementation-contract-v1";
 export const FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID = "frontend-implementation-contract-plan-patch-v1";
+export const FRONTEND_CONTRACT_REVIEW_INDEX_SCHEMA_ID = "frontend-contract-review-index-v1";
+export const FRONTEND_CONTRACT_SECTION_SCHEMA_ID = "frontend-contract-section-v1";
+export const FRONTEND_CONTRACT_CAPACITY_SCHEMA_ID = "frontend-contract-capacity-v1";
+const FRONTEND_CONTRACT_REVIEW_GROUPS = [
+    {
+        id: "core",
+        fields: ["schemaVersion", "sourceBinding", "riskLevel", "targets", "requirements"],
+    },
+    {
+        id: "ux",
+        fields: ["uiStates", "interactions", "uiComponentChoices", "stylingStrategy"],
+    },
+    {
+        id: "data-design",
+        fields: ["mockApi", "designEvidence", "dependencyPolicy", "realIntegrationGap"],
+    },
+    {
+        id: "verification",
+        fields: ["verificationTargets", "evidenceGaps", "implementationSteps", "residualRisks"],
+    },
+];
+const FRONTEND_CONTRACT_CAPACITY_WARNING_RATIO = 0.6;
+const FRONTEND_CONTRACT_SECTION_DATA_TARGET_BYTES = 40 * 1024;
 /**
  * Build the deterministic, run-owned portion of the frontend contract. The
  * planner is allowed to fill semantic fields with an RFC 7386 merge patch but
@@ -171,7 +281,6 @@ export function loadFrontendImplementationContractJsonSchema(startDir = path.dir
         "mockApi",
         "designEvidence",
         "verificationTargets",
-        "evidenceGaps",
     ];
     const actualRequired = Array.isArray(schema.required) ? schema.required : [];
     const missing = expectedRequired.filter((key) => !actualRequired.includes(key));
@@ -220,13 +329,13 @@ const gap = z
  *   `specReference` is required (path/section/line hit).
  * - `reuse-existing`: reuse an existing repo component/convention not named by
  *   the spec → `specReference` may be null, rationale explains the basis.
- * - `new`: neither spec nor existing code fits → `specReference` must be null,
- *   rationale must declare the deviation (design-review approves it).
+ * - `new`: the task source mandates a component absent from the repository →
+ *   `specReference` is required and points at that task-source declaration;
+ *   rationale explains the bounded addition.
  *
- * `specReference` is nullable + optional because `stripNullValuesDeep` strips
- * null object values before validation, so a `new` choice's `specReference:
- * null` becomes an absent field; the superRefine below treats absent and null
- * identically.
+ * `specReference` is nullable + optional at the wire boundary because
+ * `stripNullValuesDeep` removes model-emitted nulls before validation. The
+ * decision-specific requirements are enforced by the superRefine below.
  */
 const uiComponentSpecReferenceSchema = z
     .object({
@@ -241,7 +350,11 @@ const uiComponentChoiceSchema = z
     component: z.string().min(1),
     decision: z.enum(["specified", "reuse-existing", "new"]),
     specReference: uiComponentSpecReferenceSchema.nullable().optional(),
-    rationale: z.string().min(1),
+    // 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.
+    rationale: z.string().min(1).optional(),
 })
     .strict();
 const uiComponentChoicesSchema = z.array(uiComponentChoiceSchema);
@@ -270,7 +383,12 @@ function stripNullValuesDeep(value) {
     return value;
 }
 export const frontendImplementationContractSchema = z
-    .preprocess(stripNullValuesDeep, z
+    .preprocess((value) => {
+    const record = asRecord(value);
+    if (!record)
+        return stripNullValuesDeep(value);
+    return stripNullValuesDeep(record);
+}, z
     .object({
     schemaVersion: z.literal(1),
     sourceBinding: z
@@ -398,7 +516,7 @@ export const frontendImplementationContractSchema = z
         uiStates: z.array(z.string().min(1)),
     })
         .strict()).min(1),
-    evidenceGaps: z.array(gap),
+    evidenceGaps: z.array(gap).optional(),
     implementationSteps: z.array(z.string().min(1)).optional(),
     stylingStrategy: z.string().min(1).optional(),
     uiComponentChoices: uiComponentChoicesSchema.optional(),
@@ -408,6 +526,37 @@ export const frontendImplementationContractSchema = z
 })
     .strict()
     .superRefine((value, ctx) => {
+    const stableIdentities = [
+        {
+            path: "requirements",
+            label: "requirement id",
+            values: value.requirements.map((item) => item.id),
+        },
+        {
+            path: "uiStates",
+            label: "UI state name",
+            values: value.uiStates.map((item) => item.name),
+        },
+        {
+            path: "interactions",
+            label: "interaction name",
+            values: value.interactions.map((item) => item.name),
+        },
+        {
+            path: "uiComponentChoices",
+            label: "component choice purpose",
+            values: (value.uiComponentChoices ?? []).map((item) => item.purpose),
+        },
+    ];
+    for (const identity of stableIdentities) {
+        if (new Set(identity.values).size !== identity.values.length) {
+            ctx.addIssue({
+                code: "custom",
+                message: `duplicate ${identity.label}`,
+                path: [identity.path],
+            });
+        }
+    }
     const verificationIds = value.verificationTargets.map((target) => target.id);
     if (new Set(verificationIds).size !== verificationIds.length)
         ctx.addIssue({
@@ -462,18 +611,32 @@ export const frontendImplementationContractSchema = z
                     message: `unknown verification target ${targetId}`,
                     path: ["requirements"],
                 });
+        // Interactions bind to VTs too: an interaction whose behavior
+        // verification points at an unmaterialized VT is untraceable —
+        // r20 review finding (dangling *-BEHAVIOR references sailed
+        // through plan/design/implement to the final review).
+        for (const interaction of value.interactions)
+            for (const targetId of interaction.verificationTargetIds)
+                if (!verificationIds.includes(targetId))
+                    ctx.addIssue({
+                        code: "custom",
+                        message: `interaction "${interaction.name}" references unknown verification target ${targetId}`,
+                        path: ["interactions"],
+                    });
         // Source fidelity ledger binding (AC-005/AC-006): 绑定携带
         // requirementToFragments（ledger v2）时，每个 requirement 必须携带
-        // 有效 sourceFragmentIds/sourceRefs，否则 fail closed（防引用伪造/缺失）。
+        // 非空 sourceFragmentIds，否则 fail closed（防引用伪造/缺失）。
+        // sourceRefs（fragment→path 的派生展示）不设硬门槛：模型从 binding
+        // 只能拿到 fragment id 拿不到权威 path，强制只会诱导编造；防伪造的
+        // 真实性校验由 fidelity gate 按 sourceFragmentIds 执行（存在性 +
+        // 与 ledger boundFragments 一致）。
         const boundFragments = value.sourceBinding.requirementToFragments?.[requirement.id];
         if (value.sourceBinding.ledgerPath &&
             (!requirement.sourceFragmentIds ||
-                requirement.sourceFragmentIds.length === 0 ||
-                !requirement.sourceRefs ||
-                requirement.sourceRefs.length === 0)) {
+                requirement.sourceFragmentIds.length === 0)) {
             ctx.addIssue({
                 code: "custom",
-                message: `requirement ${requirement.id} must carry sourceFragmentIds/sourceRefs when a source fidelity ledger is bound`,
+                message: `requirement ${requirement.id} must carry sourceFragmentIds when a source fidelity ledger is bound`,
                 path: ["requirements", requirement.id, "sourceFragmentIds"],
             });
         }
@@ -491,12 +654,23 @@ export const frontendImplementationContractSchema = z
         if (state.applicable &&
             (!state.expectedBehavior ||
                 !state.implementationTargets?.length ||
-                !state.verificationTargetIds?.length))
+                !state.verificationTargetIds?.length)) {
+            // Name the state and the exact missing fields: the fixer is a
+            // model iterating on finalize receipts — it cannot fix a
+            // defect it cannot locate (r18: 39 blind finalize retries).
+            const missing = [];
+            if (!state.expectedBehavior)
+                missing.push("expectedBehavior");
+            if (!state.implementationTargets?.length)
+                missing.push("implementationTargets");
+            if (!state.verificationTargetIds?.length)
+                missing.push("verificationTargetIds");
             ctx.addIssue({
                 code: "custom",
-                message: "applicable UI state requires behavior, implementation, and verification",
+                message: `applicable UI state "${state.name}" is missing: ${missing.join(", ")} — record_state_flow it again with those fields filled`,
                 path: ["uiStates"],
             });
+        }
         if (!state.applicable && !state.notApplicableReason)
             ctx.addIssue({
                 code: "custom",
@@ -515,10 +689,10 @@ export const frontendImplementationContractSchema = z
             }
         }
         else if (choice.decision === "new") {
-            if (choice.specReference) {
+            if (!choice.specReference || !choice.specReference.path) {
                 ctx.addIssue({
                     code: "custom",
-                    message: "new component choice must not carry a specReference",
+                    message: "new component choice requires a task-source specReference.path",
                     path: ["uiComponentChoices", index, "specReference"],
                 });
             }
@@ -1045,11 +1219,40 @@ function deriveFrontendVerificationCoverage(value, canonicalBinding) {
                 ])];
             const evidenceGap = asRecord(requirement.evidenceGap);
             const hasProof = provenRequirementIds.has(requirementId);
+            // A committed evidenceGap with a blank description means "no gap":
+            // small-output models emit the slot defensively with description
+            // "" and the strict gap schema (description min 1 char) would
+            // fail the whole compile. Strip the incoming slot first and only
+            // re-add it when usable — the requirement either has proof (no
+            // gap needed) or receives the derived blocking gap below.
+            const evidenceGapDescription = asString(evidenceGap?.description).trim();
+            const hasUsableEvidenceGap = evidenceGap !== undefined && evidenceGapDescription !== "";
+            // Source fidelity bindings are deterministic ledger data, not
+            // model-authored content: when the plan requirement carries no
+            // binding (r6 — the contract input block degraded, the model
+            // correctly refused to invent ids), inject the ledger binding
+            // for the requirement id. The strict schema fails a ledger-bound
+            // contract on any requirement without sourceFragmentIds.
+            const declaredSourceFragmentIds = Array.isArray(requirement.sourceFragmentIds)
+                ? requirement.sourceFragmentIds
+                : undefined;
+            const ledgerBoundFragmentIds = Array.isArray(canonicalBinding.requirementToFragments?.[requirementId])
+                ? canonicalBinding.requirementToFragments[requirementId]
+                : undefined;
+            const sourceFragmentIds = declaredSourceFragmentIds && declaredSourceFragmentIds.length > 0
+                ? declaredSourceFragmentIds
+                : ledgerBoundFragmentIds;
+            const { evidenceGap: _incomingGap, sourceFragmentIds: _incomingFragmentIds, ...requirementWithoutGap } = requirement;
+            void _incomingGap;
+            void _incomingFragmentIds;
             return {
-                ...requirement,
+                ...requirementWithoutGap,
+                ...(sourceFragmentIds ? { sourceFragmentIds } : {}),
                 ...(verificationTargetIds.length > 0 ? { verificationTargetIds } : {}),
                 ...(hasProof
-                    ? (evidenceGap ? { evidenceGap: { ...evidenceGap, blocking: false } } : {})
+                    ? (hasUsableEvidenceGap
+                        ? { evidenceGap: { ...evidenceGap, blocking: false } }
+                        : {})
                     : {
                         evidenceGap: {
                             requirementId,
@@ -1061,10 +1264,16 @@ function deriveFrontendVerificationCoverage(value, canonicalBinding) {
         })
         : record.requirements;
     const modelEvidenceGaps = Array.isArray(record.evidenceGaps)
-        ? record.evidenceGaps.map((item) => {
+        ? record.evidenceGaps
+            .map((item) => {
             const gap = asRecord(item);
             if (!gap)
                 return item;
+            // Blank-description gaps are meaningless statements that would
+            // fail the strict gap schema; drop them like the embedded
+            // per-requirement empty slots.
+            if (asString(gap.description).trim() === "")
+                return undefined;
             const requirementId = canonicalizeRequirementId(asString(gap.requirementId));
             // Model gaps are advisory. Blocking status is reconstructed below
             // from the source binding and executable verification targets.
@@ -1077,6 +1286,7 @@ function deriveFrontendVerificationCoverage(value, canonicalBinding) {
                 blocking: false,
             };
         })
+            .filter((item) => item !== undefined)
         : [];
     const derivedBlockingGaps = canonicalBinding.requirementIds
         .filter((requirementId) => !provenRequirementIds.has(requirementId))
@@ -1091,6 +1301,114 @@ function deriveFrontendVerificationCoverage(value, canonicalBinding) {
         evidenceGaps: [...modelEvidenceGaps, ...derivedBlockingGaps],
     };
 }
+function dedupeJsonArray(value) {
+    if (!Array.isArray(value))
+        return value;
+    const seen = new Set();
+    return value.filter((item) => {
+        const key = serializeCompactDeterministicJson(item);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function compactRecordArrayField(value, fields) {
+    if (!Array.isArray(value))
+        return value;
+    return dedupeJsonArray(value.map((item) => {
+        const record = asRecord(item);
+        if (!record)
+            return item;
+        const compact = { ...record };
+        for (const field of fields) {
+            if (Object.hasOwn(compact, field)) {
+                compact[field] = dedupeJsonArray(compact[field]);
+            }
+        }
+        return compact;
+    }));
+}
+/**
+ * Compact the canonical contract without weakening its schema or coverage
+ * semantics. This is deliberately a closed list of transformations:
+ * byte-identical records and repeated set members are deduplicated, and
+ * mutually exclusive UI-state fields are normalized. Conflicting stable
+ * identities remain visible so strict schema validation can reject them.
+ */
+export function compactFrontendImplementationContract(value) {
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const compact = { ...record };
+    const sourceBinding = asRecord(record.sourceBinding);
+    if (sourceBinding) {
+        const compactBinding = { ...sourceBinding };
+        for (const field of ["referencePaths", "requirementIds"]) {
+            if (Object.hasOwn(compactBinding, field)) {
+                compactBinding[field] = dedupeJsonArray(compactBinding[field]);
+            }
+        }
+        const fragments = asRecord(sourceBinding.requirementToFragments);
+        if (fragments) {
+            compactBinding.requirementToFragments = Object.fromEntries(Object.entries(fragments).map(([id, ids]) => [id, dedupeJsonArray(ids)]));
+        }
+        compact.sourceBinding = compactBinding;
+    }
+    const targets = asRecord(record.targets);
+    if (targets) {
+        const compactTargets = { ...targets };
+        for (const field of ["files", "routes", "publicApiChanges"]) {
+            if (Object.hasOwn(compactTargets, field)) {
+                compactTargets[field] = dedupeJsonArray(compactTargets[field]);
+            }
+        }
+        compact.targets = compactTargets;
+    }
+    compact.requirements = compactRecordArrayField(record.requirements, [
+        "implementationTargets",
+        "verificationTargetIds",
+        "sourceFragmentIds",
+        "sourceRefs",
+    ]);
+    compact.uiStates = compactRecordArrayField(record.uiStates, ["implementationTargets", "verificationTargetIds"]);
+    if (Array.isArray(compact.uiStates)) {
+        compact.uiStates = dedupeJsonArray(compact.uiStates.map((item) => {
+            const state = asRecord(item);
+            if (!state)
+                return item;
+            const normalized = { ...state };
+            if (normalized.applicable === true)
+                delete normalized.notApplicableReason;
+            if (normalized.applicable === false)
+                delete normalized.expectedBehavior;
+            return normalized;
+        }));
+    }
+    compact.interactions = compactRecordArrayField(record.interactions, ["implementationTargets", "verificationTargetIds"]);
+    compact.verificationTargets = compactRecordArrayField(record.verificationTargets, ["requirementIds", "uiStates"]);
+    const mockApi = asRecord(record.mockApi);
+    if (mockApi) {
+        compact.mockApi = {
+            ...mockApi,
+            endpoints: dedupeJsonArray(mockApi.endpoints),
+        };
+    }
+    const designEvidence = asRecord(record.designEvidence);
+    if (designEvidence) {
+        compact.designEvidence = {
+            ...designEvidence,
+            paths: dedupeJsonArray(designEvidence.paths),
+            conflicts: dedupeJsonArray(designEvidence.conflicts),
+        };
+    }
+    for (const field of ["evidenceGaps", "implementationSteps", "residualRisks"]) {
+        if (Object.hasOwn(compact, field))
+            compact[field] = dedupeJsonArray(compact[field]);
+    }
+    compact.uiComponentChoices = dedupeJsonArray(record.uiComponentChoices);
+    return compact;
+}
 function assertFrontendContractPathsSafe(value) {
     const record = asRecord(value);
     if (!record)
@@ -1166,6 +1484,40 @@ function looksLikeStrictFrontendContract(value) {
         asRecord(record.mockApi) !== null &&
         asRecord(record.designEvidence) !== null);
 }
+/**
+ * Single shared completion layer for required-with-fallback contract fields.
+ *
+ * Structural invariant: the coerce normalizer has strict-shape and free-form
+ * branches that reshape differently, but every required key that carries a
+ * deterministic fallback (currently `designEvidence`) must be completed in
+ * exactly ONE place — here — so the branches can never drift again (the
+ * designEvidence Required and invented-uiStates failures both came from
+ * branch-local rules diverging). This layer never invents values that later
+ * refinements reject: it only fills documented fallbacks for keys already
+ * present-but-partial, and is idempotent for already-complete inputs.
+ */
+export function completeCanonicalRequiredFields(value) {
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const designEvidence = asRecord(record.designEvidence);
+    if (!designEvidence)
+        return value;
+    const source = asString(designEvidence.source);
+    const paths = Array.isArray(designEvidence.paths);
+    const conflicts = Array.isArray(designEvidence.conflicts);
+    if (source && paths && conflicts)
+        return value;
+    return {
+        ...record,
+        designEvidence: {
+            ...designEvidence,
+            ...(source ? {} : { source: "repository-fallback+task-source" }),
+            ...(paths ? {} : { paths: [] }),
+            ...(conflicts ? {} : { conflicts: [] }),
+        },
+    };
+}
 /**
  * Coerce common free-form plan JSON into frontend-implementation-contract-v1.
  * Near-schema payloads are left untouched so unknown-key fail-closed still holds.
@@ -1270,6 +1622,9 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
                 ...strictRecord,
                 requirements,
                 ...(strictMockApi ? { mockApi: { ...strictMockApi, endpoints: mockEndpoints } } : {}),
+                // Required-with-fallback keys (designEvidence etc.) are completed
+                // by the single shared `completeCanonicalRequiredFields` layer in
+                // the analyze pipeline — never per-branch.
             };
         }
     }
@@ -1318,9 +1673,7 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
             : typeRaw.includes("type")
                 ? "static"
                 : "unit";
-        const commandLabel = asString(vt.commandLabel) ||
-            asString(vt.command) ||
-            (type === "static" ? "npm run typecheck" : "npm run test:unit:fe");
+        const commandLabel = asString(vt.commandLabel) || asString(vt.command);
         const file = asString(vt.file) ||
             (Array.isArray(vt.symbols) ? targetFiles.find((p) => p.includes("__tests__")) : "") ||
             targetFiles.find((p) => p.includes("__tests__")) ||
@@ -1336,7 +1689,11 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
             requirementIds: requirementIds.length > 0
                 ? requirementIds
                 : [...canonicalBinding.requirementIds],
-            uiStates: uiStateNames.length > 0 ? uiStateNames : ["success", "error"],
+            // Never invent UI state references: "success" is not a canonical
+            // state name, so a defaulted ["success","error"] was always rejected
+            // by the schema's unknown-uiState refinement — a verification
+            // target that declares no UI binding stays unbound ([]).
+            uiStates: uiStateNames,
         });
     }
     if (verificationTargets.length === 0) {
@@ -1371,6 +1728,14 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
             verificationTargetIds: verificationTargetIds.length > 0
                 ? verificationTargetIds
                 : defaultVerificationIds,
+            // Source fidelity provenance 透传：兼容分支重建 requirement 时必须
+            // 保留已声明的 sourceFragmentIds/sourceRefs（strict 分支通过
+            // `...requirement` 保留，两边必须一致），否则 ledger-bound 契约在
+            // designEvidence 缺失等情况下走兼容分支时丢失防伪造证据。
+            ...(Array.isArray(req.sourceFragmentIds)
+                ? { sourceFragmentIds: req.sourceFragmentIds }
+                : {}),
+            ...(Array.isArray(req.sourceRefs) ? { sourceRefs: req.sourceRefs } : {}),
         };
         // Do not mark free-form realIntegrationGap as blocking; defer to FE-TEST/FINAL-VERIFY.
         if (gapText) {
@@ -1664,12 +2029,25 @@ export async function analyzeFrontendImplementationContract(input) {
     if (parsedTargetFiles.some((file) => file.startsWith("/") || file.includes("\\")))
         fail("blocked", "invalid-output: frontend contract target paths must be relative POSIX paths", candidateJsonSha256);
     const parsedStates = asRecord(parsed)?.uiStates;
-    if (Array.isArray(parsedStates) && parsedStates.some((item) => {
-        const state = asRecord(item);
-        return state?.applicable === true &&
-            (!asString(state.expectedBehavior) || asStringArray(state.implementationTargets).length === 0 || asStringArray(state.verificationTargetIds).length === 0);
-    }))
-        fail("retryable-invalid", "invalid-output: applicable UI state requires behavior, implementation, and verification", candidateJsonSha256);
+    if (Array.isArray(parsedStates)) {
+        const incompleteStates = [];
+        for (const item of parsedStates) {
+            const state = asRecord(item);
+            if (!state || state.applicable !== true)
+                continue;
+            const missing = [];
+            if (!asString(state.expectedBehavior))
+                missing.push("expectedBehavior");
+            if (asStringArray(state.implementationTargets).length === 0)
+                missing.push("implementationTargets");
+            if (asStringArray(state.verificationTargetIds).length === 0)
+                missing.push("verificationTargetIds");
+            if (missing.length > 0)
+                incompleteStates.push(`"${asString(state.name)}": missing ${missing.join(", ")}`);
+        }
+        if (incompleteStates.length > 0)
+            fail("retryable-invalid", `invalid-output: applicable UI states incomplete — re-record each with record_state_flow filling the named fields: ${incompleteStates.join("; ")}`, candidateJsonSha256);
+    }
     const parsedMockApi = asRecord(parsed)?.mockApi;
     if (asRecord(parsedMockApi) &&
         typeof asRecord(parsedMockApi)?.strategy === "string" &&
@@ -1686,15 +2064,49 @@ export async function analyzeFrontendImplementationContract(input) {
     // There is exactly one post-security candidate. A fallback candidate would
     // allow malformed raw fields to bypass the boundary checks above.
     const normalizedContract = coerceFrontendImplementationContractInput(parsed, canonicalBinding);
+    const completedContract = completeCanonicalRequiredFields(normalizedContract);
     const candidate = deriveFrontendVerificationCoverage({
-        ...(asRecord(normalizedContract) ?? parsed),
+        ...(asRecord(completedContract) ?? parsed),
         sourceBinding: canonicalBinding,
     }, canonicalBinding);
-    const result = frontendImplementationContractSchema.safeParse(candidate);
+    const compactedCandidate = compactFrontendImplementationContract(candidate);
+    if (serializeCompactDeterministicJson(compactedCandidate) !==
+        serializeCompactDeterministicJson(candidate))
+        pushAction("compact-canonical-contract");
+    const result = frontendImplementationContractSchema.safeParse(compactedCandidate);
     if (!result.success)
         fail("retryable-invalid", `invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`, candidateJsonSha256);
+    // targets.files is runtime-owned (the skeleton derives it from the task
+    // writeSet, a glob the model must not edit). Narrow it AFTER the full
+    // schema validation — never before, so model-authored unsafe/absolute
+    // declarations are still rejected — to every CONCRETE path the validated
+    // contract references (requirement implementationTargets,
+    // verification-target files, Mock endpoint fixture/consumer paths). The
+    // prewrite containment semantics keep covering everything the contract
+    // references because every narrowed entry already matched the declared
+    // patterns during validation. Satisfies frozen requirements like "deliver
+    // exactly these files" without asking the model to edit a protected
+    // field (r10/r11 design-review findings).
+    const referencedConcretePaths = [
+        ...new Set([
+            ...result.data.requirements.flatMap((requirement) => requirement.implementationTargets),
+            // Mock endpoint paths stay in the set: the zod refine validated
+            // them against the declared targets.files patterns, so the
+            // narrowing must keep covering them. Verification-target files
+            // deliberately do NOT join: they are test artifacts, not
+            // deliverables, and pulling them in would change which gate
+            // fires for an out-of-writeSet VT (AC-3a semantics).
+            ...(result.data.mockApi?.endpoints ?? []).flatMap((endpoint) => [endpoint.fixture, endpoint.consumer].filter((value) => typeof value === "string" && value.length > 0)),
+        ].filter((value) => value.length > 0)),
+    ].sort();
+    if (referencedConcretePaths.length > 0) {
+        result.data.targets = {
+            ...result.data.targets,
+            files: referencedConcretePaths,
+        };
+    }
     const blockingGaps = [
-        ...result.data.evidenceGaps,
+        ...(result.data.evidenceGaps ?? []),
         ...result.data.requirements.flatMap((item) => item.evidenceGap ? [item.evidenceGap] : []),
     ].filter((item) => item.blocking);
     if (blockingGaps.length > 0)
@@ -1703,7 +2115,7 @@ export async function analyzeFrontendImplementationContract(input) {
             .join(", ")}`, candidateJsonSha256);
     for (const requirementId of canonicalBinding.requirementIds)
         if (!result.data.requirements.some((item) => item.id === requirementId) &&
-            !result.data.evidenceGaps.some((item) => item.requirementId === requirementId))
+            !(result.data.evidenceGaps ?? []).some((item) => item.requirementId === requirementId))
             fail("blocked", `frontend contract does not cover ${requirementId}`, candidateJsonSha256);
     return {
         canonical: result.data,
@@ -1712,12 +2124,211 @@ export async function analyzeFrontendImplementationContract(input) {
         normalizationActions,
     };
 }
+function frontendCapacityEntry(consumer, maxFiles, maxBytes, contractBytes, sectionCount) {
+    const utilizationRatio = contractBytes / maxBytes;
+    const indexedFiles = sectionCount + 2;
+    const byteLevel = utilizationRatio >= 1
+        ? "over-budget"
+        : utilizationRatio >= FRONTEND_CONTRACT_CAPACITY_WARNING_RATIO
+            ? "warning"
+            : "ok";
+    return {
+        consumer,
+        maxFiles,
+        maxBytes,
+        contractBytes,
+        indexedFiles,
+        headroomBytes: Math.max(0, maxBytes - contractBytes),
+        utilizationRatio: Number(utilizationRatio.toFixed(4)),
+        level: byteLevel !== "ok" && indexedFiles > maxFiles
+            ? "over-budget"
+            : byteLevel,
+        recommendedReadMode: byteLevel === "ok"
+            ? "full-contract"
+            : "indexed-sections",
+    };
+}
+function splitFrontendContractReviewGroup(canonical, fields) {
+    const parts = [];
+    let data = {};
+    let slices = [];
+    const dataBytes = (candidate) => Buffer.byteLength(serializeCompactDeterministicJson(candidate), "utf8");
+    const flush = () => {
+        if (Object.keys(data).length === 0)
+            return;
+        parts.push({ data, slices });
+        data = {};
+        slices = [];
+    };
+    for (const field of fields) {
+        if (!Object.hasOwn(canonical, field))
+            continue;
+        const fieldValue = canonical[field];
+        if (!Array.isArray(fieldValue)) {
+            const candidate = { ...data, [field]: fieldValue };
+            if (Object.keys(data).length > 0 &&
+                dataBytes(candidate) > FRONTEND_CONTRACT_SECTION_DATA_TARGET_BYTES) {
+                flush();
+            }
+            data[field] = fieldValue;
+            slices.push({ field });
+            continue;
+        }
+        if (fieldValue.length === 0) {
+            const candidate = { ...data, [field]: [] };
+            if (Object.keys(data).length > 0 &&
+                dataBytes(candidate) > FRONTEND_CONTRACT_SECTION_DATA_TARGET_BYTES) {
+                flush();
+            }
+            data[field] = [];
+            slices.push({ field, start: 0, end: 0, total: 0 });
+            continue;
+        }
+        let start = 0;
+        while (start < fieldValue.length) {
+            let end = start;
+            let accepted = [];
+            while (end < fieldValue.length) {
+                const next = [...accepted, fieldValue[end]];
+                const candidate = { ...data, [field]: next };
+                if (accepted.length > 0 &&
+                    dataBytes(candidate) > FRONTEND_CONTRACT_SECTION_DATA_TARGET_BYTES) {
+                    break;
+                }
+                if (accepted.length === 0 &&
+                    Object.keys(data).length > 0 &&
+                    dataBytes(candidate) > FRONTEND_CONTRACT_SECTION_DATA_TARGET_BYTES) {
+                    flush();
+                    continue;
+                }
+                accepted = next;
+                end += 1;
+            }
+            data[field] = accepted;
+            slices.push({ field, start, end, total: fieldValue.length });
+            start = end;
+            if (start < fieldValue.length)
+                flush();
+        }
+    }
+    flush();
+    return parts;
+}
+/**
+ * Materialize a hash-bound field index and bounded contract sections.
+ * These artifacts are an alternate read surface only: the canonical contract
+ * remains authoritative and capacity diagnostics never affect admission.
+ */
+export async function writeFrontendContractReviewArtifacts(input) {
+    const contractRelativePath = path.posix.join(input.outputDir, input.artifactName);
+    const baseName = input.artifactName.endsWith(".json")
+        ? input.artifactName.slice(0, -".json".length)
+        : input.artifactName;
+    const sectionDir = path.posix.join(input.outputDir, `${baseName}.sections`);
+    const indexRelativePath = path.posix.join(input.outputDir, `${baseName}.index.json`);
+    const capacityRelativePath = path.posix.join(input.outputDir, `${baseName}.capacity.json`);
+    const compactContract = `${serializeCompactDeterministicJson(input.canonical)}\n`;
+    const canonicalArtifact = input.canonicalArtifact ?? {
+        path: path.join(input.runDir, contractRelativePath),
+        sha256: sha256Hex(compactContract),
+        bytes: Buffer.byteLength(compactContract, "utf8"),
+    };
+    const sections = [];
+    for (const [index, group] of FRONTEND_CONTRACT_REVIEW_GROUPS.entries()) {
+        const parts = splitFrontendContractReviewGroup(input.canonical, group.fields);
+        for (const [partIndex, part] of parts.entries()) {
+            const relativePath = path.posix.join(sectionDir, `${String(index + 1).padStart(2, "0")}-${group.id}-part-${String(partIndex + 1).padStart(2, "0")}.json`);
+            const sectionPayload = {
+                schemaVersion: 1,
+                schemaId: FRONTEND_CONTRACT_SECTION_SCHEMA_ID,
+                contractSchemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+                contractSha256: canonicalArtifact.sha256,
+                group: group.id,
+                part: partIndex + 1,
+                partCount: parts.length,
+                fields: Object.keys(part.data),
+                slices: part.slices,
+                data: part.data,
+            };
+            const written = await writeCompactDeterministicJsonArtifact(input.runDir, relativePath, sectionPayload);
+            sections.push({
+                id: group.id,
+                fields: Object.keys(part.data),
+                part: partIndex + 1,
+                partCount: parts.length,
+                slices: part.slices,
+                path: relativePath,
+                sha256: written.sha256,
+                bytes: Buffer.byteLength(`${serializeCompactDeterministicJson(sectionPayload)}\n`, "utf8"),
+            });
+        }
+    }
+    const indexPayload = {
+        schemaVersion: 1,
+        schemaId: FRONTEND_CONTRACT_REVIEW_INDEX_SCHEMA_ID,
+        contract: {
+            path: contractRelativePath,
+            schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+            sha256: canonicalArtifact.sha256,
+            bytes: canonicalArtifact.bytes,
+        },
+        sections,
+    };
+    const writtenIndex = await writeCompactDeterministicJsonArtifact(input.runDir, indexRelativePath, indexPayload);
+    const consumers = [
+        frontendCapacityEntry("design-review", FRONTEND_READ_BUDGETS.designReview.maxFiles, FRONTEND_READ_BUDGETS.designReview.maxBytes, canonicalArtifact.bytes, sections.length),
+        frontendCapacityEntry("final-review", FRONTEND_READ_BUDGETS.finalReview.maxFiles, FRONTEND_READ_BUDGETS.finalReview.maxBytes, canonicalArtifact.bytes, sections.length),
+    ];
+    const capacityPayload = {
+        schemaVersion: 1,
+        schemaId: FRONTEND_CONTRACT_CAPACITY_SCHEMA_ID,
+        nonBlocking: true,
+        warningThresholdRatio: FRONTEND_CONTRACT_CAPACITY_WARNING_RATIO,
+        contract: indexPayload.contract,
+        index: {
+            path: indexRelativePath,
+            sha256: writtenIndex.sha256,
+            sectionCount: sections.length,
+            sectionBytes: sections.reduce((total, section) => total + section.bytes, 0),
+            maxSectionBytes: Math.max(...sections.map((section) => section.bytes)),
+            oversizedSectionCount: sections.filter((section) => section.bytes >= 48 * 1024).length,
+        },
+        consumers,
+        overallLevel: consumers.some((entry) => entry.level === "over-budget")
+            ? "over-budget"
+            : consumers.some((entry) => entry.level === "warning")
+                ? "warning"
+                : "ok",
+    };
+    const writtenCapacity = await writeCompactDeterministicJsonArtifact(input.runDir, capacityRelativePath, capacityPayload);
+    return {
+        index: {
+            path: writtenIndex.path,
+            relativePath: indexRelativePath,
+            artifactSha256: writtenIndex.sha256,
+            ...indexPayload,
+        },
+        capacity: {
+            path: writtenCapacity.path,
+            relativePath: capacityRelativePath,
+            artifactSha256: writtenCapacity.sha256,
+            ...capacityPayload,
+        },
+    };
+}
 export async function writeFrontendImplementationContractArtifact(input) {
-    const written = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(input.outputDir, input.artifactName), input.canonical);
+    const written = await writeCompactDeterministicJsonArtifact(input.runDir, path.posix.join(input.outputDir, input.artifactName), input.canonical);
+    const bytes = Buffer.byteLength(`${serializeCompactDeterministicJson(input.canonical)}\n`, "utf8");
+    const reviewArtifacts = await writeFrontendContractReviewArtifacts({
+        ...input,
+        canonicalArtifact: { ...written, bytes },
+    });
     return {
         path: written.path,
         sha256: written.sha256,
         schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+        reviewIndexPath: reviewArtifacts.index.path,
+        capacityDiagnosticPath: reviewArtifacts.capacity.path,
     };
 }
 const FRONTEND_PLAN_PATCH_PROTECTED_PATHS = [
@@ -1727,6 +2338,40 @@ const FRONTEND_PLAN_PATCH_PROTECTED_PATHS = [
     "/targets/files",
     "/mockApi/productionDefaultOff",
 ];
+const PLAN_LEDGER_FACT_KINDS_FOR_COMPILE = [
+    "target-surface",
+    "component-choice",
+    "state-flow",
+    "data-flow",
+    "mock-api",
+    "design-deviation",
+    "dependency",
+    "plan-requirement",
+    "plan-verification-target",
+    "plan-evidence-gap",
+];
+/**
+ * Restore the editable RFC 7386 plan patch from a committed plan ledger.
+ * This is the single compile authority for the frontend implementation
+ * contract: the tool payload (`patch` on any committed plan fact) wins over
+ * any narrative JSON in the plan node text.
+ */
+export function restorePlanPatchFromCommittedFacts(records) {
+    const planFacts = records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter((fact) => fact.origin === "plan" &&
+        typeof fact.kind === "string" &&
+        PLAN_LEDGER_FACT_KINDS_FOR_COMPILE.includes(fact.kind));
+    if (planFacts.length === 0)
+        return undefined;
+    for (const fact of planFacts) {
+        const patch = fact.patch;
+        if (isPlainObject(patch))
+            return patch;
+    }
+    return undefined;
+}
 function frontendPlanPatchProtectedPathViolations(patch) {
     const record = asRecord(patch);
     if (!record)
@@ -1756,34 +2401,34 @@ function workspaceRootFromDagRunDir(runDir) {
     const joined = segments.slice(0, harnessIndex).join(path.sep);
     return joined || path.parse(absolute).root;
 }
-function verificationSymbolMatchesFile(symbol, content) {
-    if (symbol.trim().toLowerCase() === "all describe blocks")
-        return content.includes("describe(");
-    const symbols = symbol.includes(" / ")
-        ? symbol
-            .split(/[（(]/, 1)[0]
-            .split("/")
-            .map((item) => item.trim())
-            .filter(Boolean)
-        : [symbol];
-    return symbols.every((item) => {
-        const describeTitle = item.match(/^describe\((?:['"])(.+?)(?:['"])/i)?.[1];
-        return [item, describeTitle, describeTitle ? "describe(" : undefined]
-            .filter((candidate) => Boolean(candidate))
-            .some((candidate) => content.includes(candidate));
-    });
-}
 async function dropUnresolvedVerificationSymbols(input) {
     const workspaceRoot = workspaceRootFromDagRunDir(input.runDir);
     const targets = asRecord(input.contract)?.verificationTargets;
     if (!workspaceRoot || !Array.isArray(targets))
-        return false;
-    let changed = false;
+        return [];
+    const actions = [];
     for (const targetValue of targets) {
         const target = asRecord(targetValue);
         const file = asString(target?.file);
         const symbol = asString(target?.symbol);
-        if (!target || !file || !symbol)
+        if (!target || !file)
+            continue;
+        // Static targets (project-wide commands such as typecheck/build) verify
+        // by command exit code, never by a per-file symbol. Strip any symbol
+        // the planner attached — including fabricated placeholders like "null"
+        // — so the plan shape check and the verify trace gate never evaluate
+        // it. This is the root fix for the recurring fabricated-symbol error
+        // class: the field was allowed for static, the prompt did not forbid
+        // it, and models habitually fill it; the compiler removes it instead.
+        if (target.type === "static") {
+            if (symbol) {
+                delete target.symbol;
+                if (!actions.includes("strip-static-verification-symbols"))
+                    actions.push("strip-static-verification-symbols");
+            }
+            continue;
+        }
+        if (!symbol)
             continue;
         const absolute = path.resolve(workspaceRoot, file);
         const relative = path.relative(workspaceRoot, absolute);
@@ -1792,6 +2437,11 @@ async function dropUnresolvedVerificationSymbols(input) {
             relative.includes("..")) {
             continue;
         }
+        // Configuration files (tsconfig.json, vite.config.*, ...) do not expose
+        // source symbols; legacy symbol normalization leaves them alone. Runtime
+        // trace binding handles static targets through file + command only.
+        if (isConfigurationVerificationFile(file))
+            continue;
         let content;
         try {
             content = await readFile(absolute, "utf8");
@@ -1801,23 +2451,13 @@ async function dropUnresolvedVerificationSymbols(input) {
             // changing the optional symbol during candidate normalization.
             continue;
         }
-        if (verificationSymbolMatchesFile(symbol, content))
+        if (verificationSymbolMatchesContent(symbol, content))
             continue;
         delete target.symbol;
-        changed = true;
+        if (!actions.includes("drop-unresolved-verification-symbols"))
+            actions.push("drop-unresolved-verification-symbols");
     }
-    return changed;
-}
-function extractSingleOpenspecCitationsBlock(text) {
-    // Line-anchored so a directly closed empty fence (no candidate rows) still
-    // counts as the one required block instead of "found 0" retry loops.
-    const blocks = [
-        ...text.matchAll(/^```openspec-citations[ \t]*\r?\n([\s\S]*?)^```[ \t]*$/gim),
-    ].map((match) => match[0]);
-    if (blocks.length !== 1) {
-        throw new Error(`frontend plan patch output must include exactly one fenced openspec-citations block (found ${blocks.length})`);
-    }
-    return blocks[0];
+    return actions;
 }
 async function writeFrontendPlanCandidateRaw(input) {
     const relativePath = path.posix.join("contracts", "candidates", input.nodeId, `attempt-${input.attempt}.raw.md`);
@@ -1831,6 +2471,118 @@ async function writeFrontendPlanCandidateRaw(input) {
  * prose. A successful result returns a path-only pointer plus the hash-bound canonical artifact for
  * downstream review and prewrite nodes.
  */
+/**
+ * Placeholder tokens that are never valid verification symbols ("null" is the
+ * classic model artifact: it serializes a JS null into the symbol string).
+ */
+const VERIFICATION_SYMBOL_PLACEHOLDERS = new Set([
+    "null",
+    "undefined",
+    "none",
+    "n/a",
+    "na",
+    "tbd",
+    "todo",
+    "...",
+    "?",
+    "-",
+]);
+/** An over-long symbol can never resolve to a real declaration. */
+const VERIFICATION_SYMBOL_MAX_CHARS = 60;
+/**
+ * Deterministic shape check for a verification target symbol. Catches obvious
+ * model fabrication (placeholder tokens, prose fragments) when reading a
+ * legacy contract. New plan tool calls do not expose this field; runtime trace
+ * binding uses the stable verification-target id instead.
+ *
+ * Deliberately conservative: bare test titles without punctuation ("renders
+ * loading") and `describe(...)` / `it(...)` forms stay valid — a real symbol
+ * may be a function name, a dotted path, or a describe/it title.
+ */
+export function isSuspiciousVerificationSymbol(symbol) {
+    const trimmed = symbol.trim();
+    if (!trimmed)
+        return false;
+    if (VERIFICATION_SYMBOL_PLACEHOLDERS.has(trimmed.toLowerCase()))
+        return true;
+    if (trimmed.length > VERIFICATION_SYMBOL_MAX_CHARS)
+        return true;
+    // Deliberately conservative: bare test titles with punctuation (e.g.
+    // "adds +1 button") are valid describe/it-style symbols and must pass;
+    // the length + placeholder rules above already catch obvious fabrication
+    // ("null", over-long prose fragments). Everything else is left to the
+    // deterministic drop/trace resolvability check.
+    return false;
+}
+function assertVerificationSymbolShapes(contract) {
+    for (const target of contract.verificationTargets) {
+        if (!target.symbol)
+            continue;
+        if (isSuspiciousVerificationSymbol(target.symbol)) {
+            throw new Error(`frontend plan verification target "${target.id}" declares a fabricated legacy symbol "${target.symbol}" for ${target.file}; remove the symbol (deterministic trace binding uses the stable target id)`);
+        }
+    }
+}
+/**
+ * Thrown by analyzeFrontendPlanPatchCandidate when the design-policy
+ * pre-checks report findings. Carries the structured findings so callers
+ * (finalize_plan receipt) can synthesize fix suggestions instead of making
+ * the model re-derive them from prose.
+ */
+export class PlanPolicyPrecheckFailure extends Error {
+    findings;
+    constructor(message, findings) {
+        super(message);
+        this.name = "PlanPolicyPrecheckFailure";
+        this.findings = findings;
+    }
+}
+/**
+ * Shared tail of the plan patch validation: analyze the merged contract and
+ * front-load the plan-attributable design-policy checks. Throws the same
+ * errors the node self-check throws (FrontendContractFailure for schema
+ * failures, Error for policy findings) so every caller — the node validator
+ * and the finalize_plan receipt — surfaces identical diagnostics.
+ */
+export async function analyzeFrontendPlanPatchCandidate(input) {
+    const analysis = await analyzeFrontendImplementationContract(input);
+    // A committed VT with a fabricated symbol is an immutable ledger fact —
+    // the record boundary rejects duplicate ids, so the model cannot overwrite
+    // it and throwing here deadlocks the receipt loop (r19: VT-AC006-BEHAVIOR).
+    // Drop suspicious symbols deterministically instead: the VT stays valid and
+    // the deterministic trace gate verifies file+command (and resolvability)
+    // after verification. Mirrors the shell materialization's drop semantics.
+    for (const target of analysis.canonical.verificationTargets) {
+        if (target.symbol && isSuspiciousVerificationSymbol(target.symbol)) {
+            target.symbol = undefined;
+        }
+    }
+    // Front-load the verification-symbol shape check so fabricated symbols
+    // are fixed by the plan retry ladder in-node instead of failing the
+    // verify trace gate at the end of the run.
+    assertVerificationSymbolShapes(analysis.canonical);
+    // Front-load the plan-attributable design-policy checks so the §5.1
+    // retry ladder can fix these facts in-node with diagnostics instead of
+    // the run terminating at the policy shell. The policy shell remains the
+    // final authority and re-runs the identical checks on committed facts.
+    const policyPreFindings = [
+        ...checkUiDesignCoverage(analysis.canonical),
+        ...checkUiStateAttribution(analysis.canonical),
+        ...checkDependencies(analysis.canonical, await deriveAllowedDependenciesFromRun(input.runDir)),
+        ...checkTargetPaths(analysis.canonical, await deriveWriteSetFromRun(input.runDir)),
+    ];
+    if (policyPreFindings.length > 0) {
+        const message = `frontend plan policy pre-check failed (fix these plan facts, then re-commit and finalize): ${policyPreFindings
+            .map((finding) => `${finding.code}: ${finding.message}`)
+            .join("; ")}`;
+        throw new PlanPolicyPrecheckFailure(message, policyPreFindings.map((finding) => ({
+            code: finding.code,
+            message: finding.message,
+            ...(finding.path ? { path: finding.path } : {}),
+        })));
+    }
+    return analysis;
+}
 export async function validateFrontendPlanPatchNodeOutput(input) {
     const nodeId = input.nodeId ?? "frontend-plan-pi";
     const attempt = input.attempt ?? 1;
@@ -1867,22 +2619,22 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
         const skeleton = input.structuredContractOutput?.skeleton;
         if (!skeleton)
             throw new Error("frontend plan patch validator requires a deterministic runtime skeleton");
-        const patch = extractFrontendImplementationJson(input.text);
+        const committed = await readTypedEventStoreFromJsonl(path.join(input.runDir, nodeId, "plan-typed-facts.jsonl"));
+        const patch = restorePlanPatchFromCommittedFacts(committed);
         if (!isPlainObject(patch))
-            throw new Error("frontend plan patch must extract to one JSON object");
+            throw new Error("frontend plan ledger missing: no committed origin=plan facts (record_* + finalize_plan); narrative JSON is not the compile authority");
         extractedPatchPath = path.posix.join(candidateDir, `attempt-${attempt}.extracted.json`);
         const extractedArtifact = await writeDeterministicJsonArtifact(input.runDir, extractedPatchPath, patch);
         extractedPatchSha256 = extractedArtifact.sha256;
-        const citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
         const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
         if (protectedViolations.length > 0)
             throw new Error(`frontend plan patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`);
         const merged = applyFrontendContractMergePatch(skeleton, patch);
-        const droppedUnresolvedSymbols = await dropUnresolvedVerificationSymbols({
+        const symbolNormalizationActions = await dropUnresolvedVerificationSymbols({
             runDir: input.runDir,
             contract: merged,
         });
-        const analysis = await analyzeFrontendImplementationContract({
+        const analysis = await analyzeFrontendPlanPatchCandidate({
             runDir: input.runDir,
             rawContractText: serializeDeterministicJson(merged),
             sourceBinding: input.sourceBinding,
@@ -1894,20 +2646,13 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
             normalizedContractSha256: normalizedArtifact.sha256,
             normalizationActions: [
                 "apply-runtime-skeleton",
-                ...(droppedUnresolvedSymbols
-                    ? ["drop-unresolved-verification-symbols"]
-                    : []),
+                ...symbolNormalizationActions,
                 ...analysis.normalizationActions,
             ],
             errors: [],
         });
         const canonicalRel = canonicalContractRel(nodeId);
         const canonicalArtifact = await writeDeterministicJsonArtifact(input.runDir, canonicalRel, analysis.canonical);
-        const parsedCitations = parseOpenspecCitationsBlock(citationsBlock);
-        await writeDeterministicJsonArtifact(input.runDir, openspecCitationsRel(nodeId), {
-            citations: parsedCitations.citations,
-            block: citationsBlock,
-        });
         await persistRuntimeSkeleton({
             runDir: input.runDir,
             nodeId,
@@ -1918,11 +2663,17 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
             sha256: canonicalArtifact.sha256,
             schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
         };
+        // Human-readable plan summary appended after the artifact pointer. The
+        // pointer remains the machine authority (path/schema/sha256); the
+        // rendered summary is a deterministic view of the canonical contract so
+        // Console/reviewers can read the plan without opening the JSON. It never
+        // participates in downstream validation.
+        const planSummary = renderFrontendPlanMarkdown(analysis.canonical);
         return {
             ok: true,
             contract: analysis.canonical,
             artifact,
-            normalizedText: formatStructuredArtifactPointer(artifact),
+            normalizedText: `${formatStructuredArtifactPointer(artifact)}\n\n${planSummary}`,
         };
     }
     catch (error) {
@@ -1989,106 +2740,125 @@ export async function validateFrontendContractNodeOutput(input) {
     }
 }
 /**
- * Node-output self-check for the plan revision node. Format-level checks still
- * require one openspec-citations fence and one JSON object. When the original
- * canonical contract and sourceBinding are present, this node is the merge
- * authority: it applies the RFC 7386 patch, validates the full contract, and
- * writes the revision node's own hash-bound canonical artifact.
+ * Deterministically assemble the canonical frontend implementation contract
+ * from committed typed facts, never from plan/contract node text.
+ *
+ * Inputs (all read-only, all fail-closed):
+ * - `<planNodeId>/plan-typed-facts.jsonl` (phase=committed) restores the
+ *   editable RFC 7386 patch;
+ * - `<contractNodeId>/contract-typed-facts.jsonl` (phase=committed) must carry
+ *   a `contract-finalized` terminal fact;
+ * - `<contractNodeId>/frontend-task-contract-vNext.json` must exist and parse.
+ *
+ * The patch is applied onto the runtime skeleton and re-validated through the
+ * same `analyzeFrontendImplementationContract` pipeline used by the legacy
+ * text path, so the downstream artifact semantics are unchanged. The function
+ * is pure: it never writes candidate/audit artifacts and always produces the
+ * same canonical serialization for the same committed facts. It never falls
+ * back to parsing Plan/Contract node text.
  */
-export async function validateFrontendRevisionPatchNodeOutput(input) {
-    const fail = (reason) => {
-        const classified = classifyStructuredContractFailure({ reason });
+export async function buildContractFromCommittedFacts(input) {
+    const contractNodeId = input.contractNodeId ?? "frontend-contract-pi";
+    // Skeleton guard: the runtime skeleton must carry the protected identity
+    // fields so the merged contract can be validated against the full schema.
+    const skeletonRecord = asRecord(input.skeleton);
+    const skeletonTargets = asRecord(skeletonRecord?.targets);
+    const skeletonRiskLevel = asString(skeletonRecord?.riskLevel);
+    if (!skeletonRecord ||
+        !["small", "standard", "high-risk"].includes(skeletonRiskLevel) ||
+        !Array.isArray(skeletonTargets?.files) ||
+        skeletonTargets.files.length === 0) {
         return {
             ok: false,
-            reason,
-            classification: classified.classification,
-            errors: classified.errors,
+            reason: "frontend contract skeleton missing required runtime fields (riskLevel/targets.files)",
+            failureCode: "missing-skeleton",
         };
-    };
-    const nodeId = input.nodeId ?? "frontend-plan-revision-pi";
-    const attempt = input.attempt ?? 1;
-    await writeFrontendPlanCandidateRaw({
-        runDir: input.runDir,
-        nodeId,
-        attempt,
-        text: input.text,
-    });
-    let citationsBlock;
-    try {
-        citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
     }
-    catch (error) {
-        return fail(error instanceof Error ? error.message : String(error));
+    // a. Committed plan ledger restores the editable patch.
+    const planRecords = await readTypedEventStoreFromJsonl(path.join(input.runDir, input.planNodeId, "plan-typed-facts.jsonl"));
+    const patch = restorePlanPatchFromCommittedFacts(planRecords);
+    if (!isPlainObject(patch)) {
+        return {
+            ok: false,
+            reason: "frontend plan ledger missing: no committed origin=plan facts (record_* + finalize_plan); narrative JSON is not the compile authority",
+            failureCode: "missing-plan-ledger",
+        };
+    }
+    // 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
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact.kind)
+        .filter((kind) => typeof kind === "string"));
+    if (!contractKinds.has("contract-finalized")) {
+        return {
+            ok: false,
+            reason: "frontend contract facts missing: no committed contract-finalized terminal fact",
+            failureCode: "missing-contract-finalize",
+        };
     }
-    const textWithoutCitations = input.text.replace(citationsBlock, "");
-    let patch;
+    // c. frontend-task-contract-vNext.json must exist and parse (input integrity).
+    let rawVNext;
     try {
-        patch = extractFrontendImplementationJson(textWithoutCitations);
+        rawVNext = await readFile(path.join(input.runDir, contractNodeId, "frontend-task-contract-vNext.json"), "utf8");
     }
-    catch (error) {
-        return fail(`revision patch output must contain exactly one valid JSON object: ${error instanceof Error ? error.message : String(error)}`);
+    catch {
+        return {
+            ok: false,
+            reason: `frontend task contract vNext missing at ${contractNodeId}/frontend-task-contract-vNext.json`,
+            failureCode: "contract-vnext-missing",
+        };
     }
-    if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
-        return fail("revision patch output must extract to exactly one JSON object (RFC 7386 merge-patch delta)");
+    try {
+        JSON.parse(rawVNext);
     }
-    const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
-    if (protectedViolations.length > 0) {
-        return fail(`frontend revision patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`);
+    catch (error) {
+        return {
+            ok: false,
+            reason: `frontend task contract vNext is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "contract-vnext-invalid",
+        };
     }
-    const original = (await readFrontendCanonicalCandidate(input.runDir, "frontend-plan-pi")) ??
-        (await readFrontendCanonicalCandidate(input.runDir, nodeId));
-    if (!input.sourceBinding) {
-        return { ok: true, contract: patch };
+    // d. Merge the editable patch onto the protected skeleton and validate.
+    let merged;
+    try {
+        merged = applyFrontendContractMergePatch(input.skeleton, patch);
     }
-    if (!original) {
-        return fail("frontend revision patch requires the original frontend-plan-pi canonical contract");
+    catch (error) {
+        return {
+            ok: false,
+            reason: `frontend contract patch could not be applied to the runtime skeleton: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "schema-drift",
+        };
     }
+    // The design-policy shell is the authoritative materializer of the
+    // canonical contract; keep legacy symbol normalization identical to the
+    // plan validator even though trace binding now uses stable target ids.
+    await dropUnresolvedVerificationSymbols({
+        runDir: input.runDir,
+        contract: merged,
+    });
     try {
-        const merged = applyFrontendContractMergePatch(original, patch);
-        const droppedUnresolvedSymbols = await dropUnresolvedVerificationSymbols({
-            runDir: input.runDir,
-            contract: merged,
-        });
         const analysis = await analyzeFrontendImplementationContract({
             runDir: input.runDir,
             rawContractText: serializeDeterministicJson(merged),
             sourceBinding: input.sourceBinding,
         });
-        const candidateDir = path.posix.join("contracts", "candidates", nodeId);
-        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.extracted.json`), patch);
-        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
-        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.validation.json`), {
-            classification: "accepted-normalized",
-            normalizationActions: [
-                "apply-original-canonical",
-                ...(droppedUnresolvedSymbols
-                    ? ["drop-unresolved-verification-symbols"]
-                    : []),
-                ...analysis.normalizationActions,
-            ],
-            errors: [],
-        });
-        const canonicalArtifact = await writeDeterministicJsonArtifact(input.runDir, canonicalContractRel(nodeId), analysis.canonical);
-        const parsedCitations = parseOpenspecCitationsBlock(citationsBlock);
-        await writeDeterministicJsonArtifact(input.runDir, openspecCitationsRel(nodeId), {
-            citations: parsedCitations.citations,
-            block: citationsBlock,
-        });
-        const artifact = {
-            path: canonicalArtifact.path,
-            sha256: canonicalArtifact.sha256,
-            schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
-        };
         return {
             ok: true,
-            contract: analysis.canonical,
-            artifact,
-            normalizedText: formatStructuredArtifactPointer(artifact),
+            canonical: analysis.canonical,
+            normalizationActions: analysis.normalizationActions,
+            candidateJsonSha256: analysis.candidateJsonSha256,
         };
     }
     catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        return fail(reason);
+        const failureKind = error instanceof FrontendContractFailure ? error.kind : undefined;
+        return {
+            ok: false,
+            reason: `frontend contract schema drift: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "schema-drift",
+            ...(failureKind ? { failureKind } : {}),
+        };
     }
 }
 export async function materializeFrontendImplementationContract(input) {