@tea-agent/loop-agent 0.39.0-beta.1 → 0.39.0-beta.10

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

@@ -8,6 +8,15 @@ 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, persistRuntimeSkeleton, } from "./structured-output-repair.js";
+import { renderFrontendPlanMarkdown } from "./frontend-plan-render.js";
+import { isConfigurationVerificationFile, verificationSymbolMatchesContent, } from "./frontend-verification-trace.js";
 export const frontendNormalizationActionSchema = z.enum([
     "remove-trailing-commas",
     "strip-comments",
@@ -102,6 +111,68 @@ 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";
 /**
@@ -169,7 +240,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));
@@ -218,13 +288,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({
@@ -239,7 +309,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);
@@ -268,7 +342,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
@@ -278,8 +357,33 @@ export const frontendImplementationContractSchema = z
         requirementSha256: z.string().regex(/^[a-f0-9]{64}$/),
         referencePaths: z.array(safePath),
         requirementIds: z.array(id),
+        // Source binding v2 (frontend): bound ledger pointer + fragment map.
+        ledgerPath: safePath.optional(),
+        ledgerSha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+        inputDigest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+        requirementToFragments: z
+            .record(z.string(), z.array(z.string()))
+            .optional(),
     })
-        .strict(),
+        .strict()
+        .superRefine((value, ctx) => {
+        // v2 all-or-none：任一 ledger 字段出现则四项必须齐全，防止 v1+optional 冒充 v2。
+        const anyLedgerField = value.ledgerPath !== undefined ||
+            value.ledgerSha256 !== undefined ||
+            value.inputDigest !== undefined ||
+            value.requirementToFragments !== undefined;
+        const allLedgerFields = value.ledgerPath !== undefined &&
+            value.ledgerSha256 !== undefined &&
+            value.inputDigest !== undefined &&
+            value.requirementToFragments !== undefined;
+        if (anyLedgerField && !allLedgerFields) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["sourceBinding"],
+                message: "source binding v2 ledger fields (ledgerPath/ledgerSha256/inputDigest/requirementToFragments) must be provided together; partial or optional v1+ledger bindings are rejected",
+            });
+        }
+    }),
     riskLevel: z.enum(["small", "standard", "high-risk"]),
     targets: z
         .object({
@@ -295,6 +399,10 @@ export const frontendImplementationContractSchema = z
         implementationTargets: z.array(safePath),
         verificationTargetIds: z.array(z.string().min(1)),
         evidenceGap: gap.optional(),
+        // Source fidelity ledger binding (AC-005/AC-006): 每个 requirement
+        // 携带来源 fragment 证据，prewrite 门禁校验其真实性与覆盖。
+        sourceFragmentIds: z.array(z.string().min(1)).optional(),
+        sourceRefs: z.array(safePath).optional(),
     })
         .strict()).min(1),
     uiStates: z.array(z
@@ -367,7 +475,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(),
@@ -431,6 +539,32 @@ export const frontendImplementationContractSchema = z
                     message: `unknown verification target ${targetId}`,
                     path: ["requirements"],
                 });
+        // Source fidelity ledger binding (AC-005/AC-006): 绑定携带
+        // requirementToFragments（ledger v2）时，每个 requirement 必须携带
+        // 非空 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)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `requirement ${requirement.id} must carry sourceFragmentIds when a source fidelity ledger is bound`,
+                path: ["requirements", requirement.id, "sourceFragmentIds"],
+            });
+        }
+        else if (boundFragments !== undefined &&
+            (!requirement.sourceFragmentIds ||
+                requirement.sourceFragmentIds.length === 0)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `requirement ${requirement.id} is bound to ledger fragments ${boundFragments.join(", ")} but declares none`,
+                path: ["requirements", requirement.id, "sourceFragmentIds"],
+            });
+        }
     }
     for (const state of value.uiStates) {
         if (state.applicable &&
@@ -460,10 +594,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"],
                 });
             }
@@ -567,6 +701,29 @@ export async function assertFrontendSourceBindingFresh(input) {
             throw new Error(`frontend source binding is stale: ${source.path}`);
         }
     }
+    // Source binding v2 ledger 新鲜度（AC-FIDELITY-REPAIR-001/002）：v2 绑定携带的
+    // ledger 文件必须存在且 sha256 与绑定一致，否则 fail closed；v1 绑定无此路径。
+    if (isDagSourceBindingV2(input.binding)) {
+        const absolute = resolveDagTaskSourcePath({
+            workspaceRoot: input.workspaceRoot,
+            taskId: input.binding.taskId,
+            sourcePath: input.binding.ledgerPath,
+        });
+        let content;
+        try {
+            content = await readFile(absolute);
+            const info = await stat(absolute);
+            if (!info.isFile())
+                throw new Error("not a regular file");
+        }
+        catch (error) {
+            throw new Error(`frontend source fidelity ledger unavailable: ${input.binding.ledgerPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const actual = createHash("sha256").update(content).digest("hex");
+        if (actual !== input.binding.ledgerSha256) {
+            throw new Error(`frontend source fidelity ledger is stale or tampered: ${input.binding.ledgerPath} (bound ${input.binding.ledgerSha256}, observed ${actual})`);
+        }
+    }
 }
 const SECRET_KEY = /(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|credential|authorization)/i;
 const SECRET_VALUE = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:sk|ghp|github_pat|xox[baprs]|AKIA)[-_A-Za-z0-9]{12,}\b)/;
@@ -741,7 +898,7 @@ export function canonicalFrontendContractSourceBinding(binding) {
     const requirement = binding.sources.find((source) => source.kind === "requirement");
     if (!requirement)
         throw new Error("frontend implementation contract gate requires a requirement source in DAG sourceBinding");
-    return {
+    const sourceBinding = {
         taskId: binding.taskId,
         requirementPath: requirement.path,
         requirementSha256: requirement.sha256,
@@ -751,6 +908,15 @@ export function canonicalFrontendContractSourceBinding(binding) {
             .sort(),
         requirementIds: binding.requirementIds.map(canonicalizeRequirementId),
     };
+    // Source binding v2（schemaVersion=2 强制字段）：透传 ledger 指针与
+    // requirement→fragment 映射。v1 绑定不得以 optional 字段冒充 v2。
+    if (isDagSourceBindingV2(binding)) {
+        sourceBinding.ledgerPath = binding.ledgerPath;
+        sourceBinding.ledgerSha256 = binding.ledgerSha256;
+        sourceBinding.inputDigest = binding.inputDigest;
+        sourceBinding.requirementToFragments = binding.requirementToFragments;
+    }
+    return sourceBinding;
 }
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -1079,6 +1245,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.
@@ -1183,6 +1383,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.
             };
         }
     }
@@ -1231,9 +1434,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__")) ||
@@ -1249,7 +1450,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) {
@@ -1284,6 +1489,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) {
@@ -1485,7 +1698,13 @@ export async function analyzeFrontendImplementationContract(input) {
         rawOutput = input.rawContractText;
     }
     else if (input.fromNodeId !== undefined) {
-        const record = JSON.parse(await readFile(path.join(input.runDir, `${input.fromNodeId}.json`), "utf8"));
+        let record;
+        try {
+            record = JSON.parse(await readFile(path.join(input.runDir, `${input.fromNodeId}.json`), "utf8"));
+        }
+        catch (error) {
+            throw new Error(`cannot parse node record ${input.fromNodeId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
         rawOutput = record.assistantText ?? record.stdout ?? "";
     }
     else {
@@ -1593,15 +1812,16 @@ 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);
     if (!result.success)
         fail("retryable-invalid", `invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`, candidateJsonSha256);
     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)
@@ -1610,7 +1830,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,
@@ -1634,6 +1854,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)
@@ -1663,34 +1917,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);
@@ -1699,6 +1953,10 @@ async function dropUnresolvedVerificationSymbols(input) {
             relative.includes("..")) {
             continue;
         }
+        // Configuration files (tsconfig.json, vite.config.*, ...) do not expose
+        // source symbols; the trace gate skips them, so the drop must too.
+        if (isConfigurationVerificationFile(file))
+            continue;
         let content;
         try {
             content = await readFile(absolute, "utf8");
@@ -1708,60 +1966,78 @@ 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) {
-    const blocks = text.match(/```openspec-citations[ \t]*\r?\n[\s\S]*?\r?\n```/g) ?? [];
-    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];
-}
-/**
- * Frontend plan/revision output has two JSON-bearing regions: the primary
- * payload and line-oriented OpenSpec citations. Keep their parsing domains
- * separate so a citation row can never become a competing contract candidate.
- * A bare JSON payload is retained only for historical node-output compatibility.
- */
-export function extractFrontendPlanPayload(text) {
-    const citationsBlock = extractSingleOpenspecCitationsBlock(text);
-    return {
-        payload: extractFrontendPlanPrimaryPayload(text.replace(citationsBlock, "")),
-        citationsBlock,
-    };
-}
-function extractFrontendPlanPrimaryPayload(text) {
-    const fences = [...text.matchAll(/```json[ \t]*\r?\n([\s\S]*?)\r?\n```/gi)];
-    if (fences.length > 1) {
-        throw new Error(`frontend plan output must contain exactly one primary fenced json payload (found ${fences.length})`);
-    }
-    if (fences.length === 1) {
-        try {
-            return JSON.parse(fences[0][1]);
-        }
-        catch (error) {
-            throw new Error(`frontend plan primary json fence is invalid: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    return extractFrontendImplementationJson(text);
+    return actions;
 }
 async function writeFrontendPlanCandidateRaw(input) {
     const relativePath = path.posix.join("contracts", "candidates", input.nodeId, `attempt-${input.attempt}.raw.md`);
-    await writeTextArtifactFile(path.join(input.runDir, relativePath), input.text);
+    await writeTextArtifactFile(path.join(input.runDir, relativePath), input.text.endsWith("\n") ? input.text : `${input.text}\n`);
     return relativePath;
 }
 /**
  * Compile the planner's editable RFC 7386 patch against the deterministic
  * runtime skeleton. Every attempt is preserved under contracts/candidates so
  * format/schema failures can be inspected and replayed without trusting model
- * prose. A successful result returns canonical full-contract text for all
+ * 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) at plan time so the
+ * plan retry ladder can fix the facts in-node instead of the verify trace gate
+ * failing at the very end of the run.
+ *
+ * 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.
+ */
+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 symbol "${target.symbol}" for ${target.file}; fix it to a real symbol present in that file or leave the symbol empty (the deterministic trace gate verifies symbol resolvability after verification)`);
+        }
+    }
+}
 export async function validateFrontendPlanPatchNodeOutput(input) {
     const nodeId = input.nodeId ?? "frontend-plan-pi";
     const attempt = input.attempt ?? 1;
@@ -1798,20 +2074,18 @@ 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 = extractFrontendPlanPrimaryPayload(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 citationsArtifactPath = path.posix.join(candidateDir, `attempt-${attempt}.openspec-citations.md`);
-        await writeTextArtifactFile(path.join(input.runDir, citationsArtifactPath), `${citationsBlock}\n`);
         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,
         });
@@ -1820,6 +2094,24 @@ export async function validateFrontendPlanPatchNodeOutput(input) {
             rawContractText: serializeDeterministicJson(merged),
             sourceBinding: input.sourceBinding,
         });
+        // 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)
+            throw new Error(`frontend plan policy pre-check failed (fix these plan facts, then re-commit and finalize): ${policyPreFindings
+                .map((finding) => `${finding.code}: ${finding.message}`)
+                .join("; ")}`);
         const normalizedArtifact = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
         await writeReport({
             classification: "accepted-normalized",
@@ -1827,47 +2119,66 @@ 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);
+        await persistRuntimeSkeleton({
+            runDir: input.runDir,
+            nodeId,
+            skeleton,
+        });
+        const artifact = {
+            path: canonicalArtifact.path,
+            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,
-            structuredArtifact: {
-                path: normalizedArtifact.path,
-                sha256: normalizedArtifact.sha256,
-                schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
-            },
-            frontendPlanOutput: {
-                schemaVersion: 1,
-                payloadKind: "canonical-contract",
-                citationsArtifactPath: path.join(input.runDir, citationsArtifactPath),
-                citationsArtifactSha256: sha256Hex(`${citationsBlock}\n`),
-                rawCandidatePath: path.join(input.runDir, rawPath),
-                rawCandidateSha256: sha256Hex(input.text),
-            },
-            normalizedText: [
-                "Frontend implementation contract compiled from the runtime skeleton.",
-                "",
-                "```json",
-                serializeDeterministicJson(analysis.canonical),
-                "```",
-                citationsBlock,
-            ].join("\n"),
+            artifact,
+            normalizedText: `${formatStructuredArtifactPointer(artifact)}\n\n${planSummary}`,
         };
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
+        const classified = classifyStructuredContractFailure({
+            reason,
+            kind: error instanceof FrontendContractFailure ? error.kind : undefined,
+        });
         await writeReport({
-            classification: "retryable-invalid",
+            classification: classified.classification,
             normalizationActions: [],
-            errors: [{ path: "$", code: "invalid-output", message: reason }],
+            errors: classified.errors,
         });
-        return { ok: false, reason };
+        return {
+            ok: false,
+            reason,
+            classification: classified.classification,
+            errors: classified.errors,
+        };
+    }
+}
+export async function readFrontendCanonicalCandidate(runDir, nodeId) {
+    const candidatePath = path.join(runDir, canonicalContractRel(nodeId));
+    try {
+        const raw = await readFile(candidatePath, "utf8");
+        const parsed = frontendImplementationContractSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        return undefined;
     }
 }
 /**
@@ -1888,79 +2199,140 @@ export async function validateFrontendContractNodeOutput(input) {
         return { ok: true, contract: analysis.canonical };
     }
     catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const classified = classifyStructuredContractFailure({
+            reason,
+            kind: error instanceof FrontendContractFailure ? error.kind : undefined,
+        });
         return {
             ok: false,
-            reason: error instanceof Error ? error.message : String(error),
+            reason,
+            classification: classified.classification,
+            errors: classified.errors,
         };
     }
 }
 /**
- * Node-output self-check for the plan revision node, which emits an RFC 7386
- * merge-patch delta against the original contract instead of a full contract.
- * Deliberately loose and format-level: the output must contain exactly one
- * ```openspec-citations fenced block and must extract (after the citations
- * blocks are stripped) to exactly one JSON object. The delta carries no
- * schemaVersion/targets, so no full-contract schema/semantic checks run here;
- * content parsing, patch application, and merged-contract validation stay with
- * the prewrite gate, which remains the only authority.
+ * 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 nodeId = input.nodeId ?? "frontend-plan-revision-pi";
-    const attempt = input.attempt ?? 1;
-    const candidateDir = path.posix.join("contracts", "candidates", nodeId);
-    const rawPath = await writeFrontendPlanCandidateRaw({
-        runDir: input.runDir,
-        nodeId,
-        attempt,
-        text: input.text,
-    });
-    let citationsBlock;
-    let patch;
+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: "frontend contract skeleton missing required runtime fields (riskLevel/targets.files)",
+            failureCode: "missing-skeleton",
+        };
+    }
+    // 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",
+        };
+    }
+    // c. frontend-task-contract-vNext.json must exist and parse (input integrity).
+    let rawVNext;
     try {
-        const parsed = extractFrontendPlanPayload(input.text);
-        citationsBlock = parsed.citationsBlock;
-        patch = parsed.payload;
+        rawVNext = await readFile(path.join(input.runDir, contractNodeId, "frontend-task-contract-vNext.json"), "utf8");
+    }
+    catch {
+        return {
+            ok: false,
+            reason: `frontend task contract vNext missing at ${contractNodeId}/frontend-task-contract-vNext.json`,
+            failureCode: "contract-vnext-missing",
+        };
+    }
+    try {
+        JSON.parse(rawVNext);
     }
     catch (error) {
         return {
             ok: false,
-            reason: error instanceof Error ? error.message : String(error),
+            reason: `frontend task contract vNext is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "contract-vnext-invalid",
         };
     }
-    if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+    // d. Merge the editable patch onto the protected skeleton and validate.
+    let merged;
+    try {
+        merged = applyFrontendContractMergePatch(input.skeleton, patch);
+    }
+    catch (error) {
         return {
             ok: false,
-            reason: "revision patch output must extract to exactly one JSON object (RFC 7386 merge-patch delta)",
+            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 it on the same unresolved-symbol drop as the
+    // plan validator so the verify trace gate never sees fabricated symbols.
+    await dropUnresolvedVerificationSymbols({
+        runDir: input.runDir,
+        contract: merged,
+    });
+    try {
+        const analysis = await analyzeFrontendImplementationContract({
+            runDir: input.runDir,
+            rawContractText: serializeDeterministicJson(merged),
+            sourceBinding: input.sourceBinding,
+        });
+        return {
+            ok: true,
+            canonical: analysis.canonical,
+            normalizationActions: analysis.normalizationActions,
+            candidateJsonSha256: analysis.candidateJsonSha256,
         };
     }
-    const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
-    if (protectedViolations.length > 0) {
+    catch (error) {
+        const failureKind = error instanceof FrontendContractFailure ? error.kind : undefined;
         return {
             ok: false,
-            reason: `frontend revision patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`,
+            reason: `frontend contract schema drift: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "schema-drift",
+            ...(failureKind ? { failureKind } : {}),
         };
     }
-    const payloadPath = path.posix.join(candidateDir, `attempt-${attempt}.patch.json`);
-    const payloadArtifact = await writeDeterministicJsonArtifact(input.runDir, payloadPath, patch);
-    const citationsArtifactPath = path.posix.join(candidateDir, `attempt-${attempt}.openspec-citations.md`);
-    await writeTextArtifactFile(path.join(input.runDir, citationsArtifactPath), `${citationsBlock}\n`);
-    return {
-        ok: true,
-        contract: patch,
-        structuredArtifact: {
-            path: payloadArtifact.path,
-            sha256: payloadArtifact.sha256,
-            schemaId: "frontend-implementation-contract-revision-patch-v1",
-        },
-        frontendPlanOutput: {
-            schemaVersion: 1,
-            payloadKind: "merge-patch",
-            citationsArtifactPath: path.join(input.runDir, citationsArtifactPath),
-            citationsArtifactSha256: sha256Hex(`${citationsBlock}\n`),
-            rawCandidatePath: path.join(input.runDir, rawPath),
-            rawCandidateSha256: sha256Hex(input.text),
-        },
-    };
 }
 export async function materializeFrontendImplementationContract(input) {
     const analysis = await analyzeFrontendImplementationContract(input);