@tea-agent/loop-agent 0.40.0-next.2 → 0.40.0-next.3

package/dist/worker/observe/static/views/dag.d.ts

@@ -0,0 +1,13 @@
+export interface DagNodeRemark {
+	failed: boolean;
+	text: string;
+	isErrorSummary: boolean;
+}
+
+export function resolveNodeRemark(node: {
+	status?: string | null;
+	errorPreview?: string | null;
+	label?: string | null;
+	nodeId: string;
+	rank?: string | number | null;
+} | null | undefined): DagNodeRemark;

package/dist/worker/observe/static/views/dag.js

@@ -70,6 +70,7 @@ import {
 	dashboardVisibleFeatures,
 	findDagForRun,
 } from "../dag-model.js";
+import { describeDagNodePurpose } from "../dag-node-purpose.js";
 import { layoutDag } from "../dag-layout.js";
 import {
 	showView,
@@ -136,7 +137,7 @@ export function extractFirstErrorSummary(errorPreview) {
 	return effective ?? "";
 }
 
-/** Resolve 备注 cell content for a DAG node (failed → summary; else label). */
+/** Resolve 备注 cell content for a DAG node (failed → summary; else purpose). */
 export function resolveNodeRemark(node) {
 	const failed = isNodeFailed(node?.status);
 	if (failed) {
@@ -147,10 +148,10 @@ export function resolveNodeRemark(node) {
 			isErrorSummary: Boolean(summary),
 		};
 	}
-	const label = typeof node?.label === "string" ? node.label.trim() : "";
+	const purpose = describeDagNodePurpose(node?.nodeId, node);
 	return {
 		failed: false,
-		text: label || "—",
+		text: purpose || "—",
 		isErrorSummary: false,
 	};
 }

package/dist/worker/observe/static/views/task.js

@@ -34,6 +34,7 @@ import {
 	repoBaseName,
 	parseMarkdownBlocks,
 	markdownLinkHref,
+	formatLedgerSummary,
 } from "../format.js";
 import { parseRoute, navigate, buildHashPath } from "../router.js";
 import {
@@ -94,6 +95,7 @@ export async function renderTaskDetail(featureId, taskId) {
 	const linksEl = document.getElementById("task-links");
 	const evidenceEl = document.getElementById("task-evidence");
 	const runsEl = document.getElementById("task-runs");
+	const ledgerEl = document.getElementById("task-ledger");
 	if (!metaEl || !linksEl || !evidenceEl || !runsEl) return false;
 	if (titleEl) titleEl.textContent = displayLabel;
 	mountViewState(metaEl, "loading", "加载 Task…");
@@ -252,9 +254,62 @@ export async function renderTaskDetail(featureId, taskId) {
 	const active = ["running", "pending", "blocked", "stale"].includes(
 		(task.status ?? "").toLowerCase(),
 	);
+	if (ledgerEl) {
+		void renderTaskLedger(ledgerEl, taskId);
+	}
 	return active;
 }
 
+/**
+ * Task 详情页 ledger 安全摘要（AC-009）：从只读 GET /api/tasks/:id/ledger 拉取，
+ * 计数/状态/failure code + 有界排除理由；无 ledger 显示空态，失败安全降级。
+ */
+async function renderTaskLedger(ledgerEl, taskId) {
+	clearNode(ledgerEl);
+	ledgerEl.appendChild(el("h3", "section-heading", "Source fidelity ledger"));
+	mountViewState(ledgerEl, "loading", "加载 ledger…");
+	let body = null;
+	try {
+		body = await fetchJson(`/api/tasks/${encodeURIComponent(taskId)}/ledger`);
+	} catch {
+		body = null;
+	}
+	if (!body) {
+		mountViewState(ledgerEl, "error", "ledger 只读接口失败（安全降级）。");
+		return;
+	}
+	if (body.present !== true) {
+		mountViewState(
+			ledgerEl,
+			body.error ? "error" : "empty",
+			body.error
+				? `ledger 不可用（${body.error}）。`
+				: "无 source fidelity ledger（任务无引用或 ledger 缺失，不伪造计数）。",
+		);
+		return;
+	}
+	const pre = el(
+		"pre",
+		"cmd",
+		formatLedgerSummary({
+			present: true,
+			fragmentCount: body.fragmentCount,
+			canonicalRequirementCount: body.canonicalRequirementCount,
+			contextOnlyCount: body.contextOnlyCount,
+			duplicateCount: body.duplicateCount,
+			unresolvedCount: body.unresolvedCount,
+			conflictCount: body.conflictCount,
+			gateStatus: body.gateStatus,
+			failureCode: body.failureCode,
+			exclusions: body.exclusions ?? [],
+		}),
+	);
+	pre.dataset.testid = "task-ledger-summary";
+	clearNode(ledgerEl);
+	ledgerEl.appendChild(el("h3", "section-heading", "Source fidelity ledger"));
+	ledgerEl.appendChild(pre);
+}
+
 export async function loadOlderTaskRuns(featureId, taskId, before, runsEl) {
 	if (runsEl === undefined) {
 		runsEl = before;

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

@@ -8,6 +8,7 @@ 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 { isDagSourceBindingV2 } from "./types.js";
 import { canonicalContractRel, classifyStructuredContractFailure, formatStructuredArtifactPointer, openspecCitationsRel, parseOpenspecCitationsBlock, persistRuntimeSkeleton, } from "./structured-output-repair.js";
 export const frontendNormalizationActionSchema = z.enum([
     "remove-trailing-commas",
@@ -279,8 +280,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({
@@ -296,6 +322,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
@@ -432,6 +462,30 @@ export const frontendImplementationContractSchema = z
                     message: `unknown verification target ${targetId}`,
                     path: ["requirements"],
                 });
+        // Source fidelity ledger binding (AC-005/AC-006): 绑定携带
+        // requirementToFragments（ledger v2）时，每个 requirement 必须携带
+        // 有效 sourceFragmentIds/sourceRefs，否则 fail closed（防引用伪造/缺失）。
+        const boundFragments = value.sourceBinding.requirementToFragments?.[requirement.id];
+        if (value.sourceBinding.ledgerPath &&
+            (!requirement.sourceFragmentIds ||
+                requirement.sourceFragmentIds.length === 0 ||
+                !requirement.sourceRefs ||
+                requirement.sourceRefs.length === 0)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `requirement ${requirement.id} must carry sourceFragmentIds/sourceRefs 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 &&
@@ -568,6 +622,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)/;
@@ -742,7 +819,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,
@@ -752,6 +829,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)

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

@@ -47,6 +47,27 @@ function componentSelection(contract) {
     })
         .join("\n");
 }
+/**
+ * 有界 source fidelity ledger 指针（AC-007 / AC-FIDELITY-007）：长原文不重新
+ * 全量内联到节点提示词；只注入紧凑 canonical contract 与 bound ledger 指针
+ * （路径/哈希/inputDigest），ledger coverage 证明长尾未丢失。
+ */
+function sourceFidelityLedger(contract) {
+    const binding = contract.sourceBinding;
+    if (!binding.ledgerPath)
+        return "_(not bound — v1 source binding)_";
+    const lines = [
+        `- ledger: ${binding.ledgerPath}`,
+        `- ledgerSha256: ${binding.ledgerSha256 ?? "(missing)"}`,
+        `- inputDigest: ${binding.inputDigest ?? "(missing)"}`,
+        "- 语义权威：原始 requirement/acceptance 文档与 requirement-ledger.json；本计划只消费派生摘要与 bound ledger 指针，长原文不内联。",
+    ];
+    const boundCount = Object.keys(binding.requirementToFragments ?? {}).length;
+    if (boundCount > 0) {
+        lines.push(`- requirement→fragment bindings: ${boundCount}`);
+    }
+    return lines.join("\n");
+}
 export function renderFrontendPlanMarkdown(contract) {
     return [
         "# Frontend Implementation Plan",
@@ -54,6 +75,9 @@ export function renderFrontendPlanMarkdown(contract) {
         "## Requirement Coverage",
         requirementsCoverage(contract),
         "",
+        "## Source Fidelity Ledger",
+        sourceFidelityLedger(contract),
+        "",
         "## Implementation Steps",
         bulletList(contract.implementationSteps) || "_(not specified)_",
         "",

package/dist/workflows/dag/frontend-prewrite-gate.js

@@ -2,9 +2,12 @@ import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
+import { isDagSourceBindingV2 } from "./types.js";
 import { isOpenspecSpecFilePath } from "../../shared/openspec-spec.js";
 import { writeTextArtifactFile } from "../../infrastructure/harness/artifact-store.js";
 import { countExcludedGovernanceSpecFiles, resolveOpenspecGovernanceRoot, } from "../../task/frontend-project-capability.js";
+import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { parseLedgerJson, validateRequirementLedger, } from "../../task/source-prepare/ledger.js";
 import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, serializeDeterministicJson, FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, FrontendContractFailure, frontendNormalizationActionSchema, } from "./frontend-implementation-contract.js";
 import { renderFrontendPlanMarkdown } from "./frontend-plan-render.js";
 import { captureFrontendWorktreeBaseline } from "./frontend-worktree-diff.js";
@@ -42,6 +45,14 @@ export const frontendPrewriteFailureCodeSchema = z.enum([
     "component-choices-missing",
     "contract-too-large",
     "revision-patch-unmergeable",
+    // Source fidelity ledger 类目（SOURCE_FIDELITY_*/source-* 稳定错误码）。
+    "source-fidelity-ledger-missing",
+    "source-fidelity-ledger-stale",
+    "source-fidelity-unresolved",
+    "source-fidelity-conflict",
+    "source-fidelity-high-risk-uncovered",
+    "source-fidelity-requirement-not-covered",
+    "source-fidelity-source-ref-invalid",
 ]);
 export const frontendPrewriteResultV1Schema = z
     .object({
@@ -442,6 +453,162 @@ async function finalizePrewrite(input, pending) {
         openspecPolicy: pending.openspecPolicy,
     };
 }
+/**
+ * Source fidelity ledger 门禁检查（AC-FIDELITY-002/003/006）：绑定携带 ledger 指针时，
+ * 依次核验 ledger 存在、绑定 hash 一致、inputDigest 新鲜、无 unresolved/conflict/
+ * 高风险未覆盖、canonical requirement 全覆盖、来源引用有效且非伪造。任一失败 fail closed。
+ */
+export async function checkFrontendSourceFidelityLedger(input) {
+    const { binding } = input;
+    // v1 绑定不携带 ledger 指针：非 frontend task / 无可解析引用 → 无 v2 校验路径。
+    if (!isDagSourceBindingV2(binding)) {
+        return { ok: true, failureCode: null, failureReason: null, ledger: null };
+    }
+    const absolute = resolveDagTaskSourcePath({
+        workspaceRoot: input.workspaceRoot,
+        taskId: binding.taskId,
+        sourcePath: binding.ledgerPath,
+    });
+    let raw;
+    try {
+        raw = await readFile(absolute, "utf8");
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-missing",
+            failureReason: `frontend source fidelity ledger missing: ${binding.ledgerPath} (${error instanceof Error ? error.message : String(error)})`,
+            ledger: null,
+        };
+    }
+    const actualSha = createHash("sha256").update(raw).digest("hex");
+    if (actualSha !== binding.ledgerSha256) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-stale",
+            failureReason: `frontend source fidelity ledger stale or tampered: ${binding.ledgerPath} (bound ${binding.ledgerSha256}, observed ${actualSha})`,
+            ledger: null,
+        };
+    }
+    let ledger;
+    try {
+        ledger = parseLedgerJson(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-stale",
+            failureReason: `frontend source fidelity ledger is not a valid v1 ledger: ${error instanceof Error ? error.message : String(error)}`,
+            ledger: null,
+        };
+    }
+    if (ledger.inputDigest !== binding.inputDigest) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-stale",
+            failureReason: `frontend source fidelity ledger inputDigest mismatch: bound ${binding.inputDigest}, ledger ${ledger.inputDigest}`,
+            ledger,
+        };
+    }
+    const validation = validateRequirementLedger(ledger);
+    const firstError = (code) => validation.find((error) => error.code === code)?.message ?? null;
+    if (ledger.stats.unresolvedCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_UNRESOLVED")) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-unresolved",
+            failureReason: firstError("SOURCE_FIDELITY_UNRESOLVED") ??
+                `frontend source fidelity ledger has ${ledger.stats.unresolvedCount} unresolved fragment(s)`,
+            ledger,
+        };
+    }
+    if (ledger.stats.conflictCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_CONFLICT")) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-conflict",
+            failureReason: firstError("SOURCE_FIDELITY_CONFLICT") ??
+                `frontend source fidelity ledger has ${ledger.stats.conflictCount} conflict(s)`,
+            ledger,
+        };
+    }
+    if (ledger.stats.highRiskUncoveredCount > 0 ||
+        validation.some((e) => e.code === "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED")) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-high-risk-uncovered",
+            failureReason: firstError("SOURCE_FIDELITY_HIGH_RISK_UNCOVERED") ??
+                `frontend source fidelity ledger has ${ledger.stats.highRiskUncoveredCount} high-risk uncovered fragment(s)`,
+            ledger,
+        };
+    }
+    // AC-BLOCK-001：canonical requirement 缺少 fragment/sourceRef 证据（ledger 侧
+    // REQUIREMENT_NOT_COVERED）与来源引用/片段无效（SOURCE_REF_INVALID /
+    // FRAGMENT_INVALID）均为阻断性失败，结构化失败结果不得产生可继续执行的成功。
+    const notCoveredError = validation.find((e) => e.code === "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED");
+    if (notCoveredError) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-requirement-not-covered",
+            failureReason: notCoveredError.message,
+            ledger,
+        };
+    }
+    const refInvalidError = validation.find((e) => e.code === "SOURCE_FIDELITY_SOURCE_REF_INVALID" ||
+        e.code === "SOURCE_FIDELITY_FRAGMENT_INVALID");
+    if (refInvalidError) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-source-ref-invalid",
+            failureReason: refInvalidError.message,
+            ledger,
+        };
+    }
+    const ledgerIds = new Set(ledger.canonicalRequirements.map((requirement) => requirement.id));
+    const contractIds = new Set(input.contractRequirements.map((r) => r.id));
+    const uncoveredRequirements = [...ledgerIds].filter((id) => !contractIds.has(id));
+    if (uncoveredRequirements.length > 0) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-requirement-not-covered",
+            failureReason: `frontend contract requirements do not cover ledger canonical requirement ids: ${uncoveredRequirements.join(", ")}`,
+            ledger,
+        };
+    }
+    const fragmentById = new Map(ledger.fragments.map((fragment) => [fragment.id, fragment]));
+    for (const requirement of input.contractRequirements) {
+        if (!ledgerIds.has(requirement.id))
+            continue;
+        const declared = requirement.sourceFragmentIds ?? [];
+        if (declared.length === 0) {
+            return {
+                ok: false,
+                failureCode: "source-fidelity-source-ref-invalid",
+                failureReason: `frontend contract requirement ${requirement.id} lacks sourceFragmentIds for the bound ledger`,
+                ledger,
+            };
+        }
+        const boundFragments = new Set(ledger.canonicalRequirements.find((r) => r.id === requirement.id)
+            ?.sourceFragmentIds ?? []);
+        for (const fragmentId of declared) {
+            if (!fragmentById.has(fragmentId)) {
+                return {
+                    ok: false,
+                    failureCode: "source-fidelity-source-ref-invalid",
+                    failureReason: `frontend contract requirement ${requirement.id} references unknown fragment ${fragmentId}`,
+                    ledger,
+                };
+            }
+            if (!boundFragments.has(fragmentId)) {
+                return {
+                    ok: false,
+                    failureCode: "source-fidelity-source-ref-invalid",
+                    failureReason: `frontend contract requirement ${requirement.id} declares fabricated fragment reference ${fragmentId} (not bound in ledger)`,
+                    ledger,
+                };
+            }
+        }
+    }
+    return { ok: true, failureCode: null, failureReason: null, ledger };
+}
 export async function runFrontendPrewriteGate(input) {
     const workspaceRoot = input.workspaceRoot ?? input.repoRoot;
     // selectNode throws for a scheduling defect (no FINISHED plan/review). That
@@ -589,6 +756,33 @@ export async function runFrontendPrewriteGate(input) {
         }
         throw error;
     }
+    // Source fidelity ledger gate (20260824-frontend-source-fidelity-ledger-v1):
+    // 在 verdict/missing-requirement-ids/source-binding-not-fresh 之后插入 ledger
+    // 检查。缺失即 fail closed 且 writer 不获授权；所有检查通过才继续物化契约。
+    if (input.sourceBinding) {
+        const ledgerCheck = await checkFrontendSourceFidelityLedger({
+            workspaceRoot: workspaceRoot ?? "",
+            binding: input.sourceBinding,
+            contractRequirements: analysis.canonical.requirements.map((requirement) => ({
+                id: requirement.id,
+                sourceFragmentIds: requirement.sourceFragmentIds,
+                sourceRefs: requirement.sourceRefs,
+            })),
+        });
+        if (!ledgerCheck.ok && ledgerCheck.failureCode) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                candidateJsonSha256: analysis.candidateJsonSha256,
+                normalizationActions: [],
+                mockStrategy: analysis.canonical.mockApi.strategy,
+                classification: "blocked",
+                failureReason: ledgerCheck.failureReason ??
+                    "frontend source fidelity ledger gate failed",
+                failureCode: ledgerCheck.failureCode,
+            });
+        }
+    }
     // Size guard: a canonical contract above 64KB is a retryable-invalid defect
     // (compress the contract) rather than a writer authorization failure.
     const contractSizeBytes = Buffer.byteLength(serializeDeterministicJson(analysis.canonical), "utf8");
@@ -947,6 +1141,9 @@ export function formatFrontendPrewriteGateStdout(result) {
     }
     lines.push(`Prewrite result: ${result.prewriteResult.path}`);
     lines.push(`Openspec policy: ${result.openspecPolicy}`);
+    if (result.failureCode?.startsWith("source-fidelity-")) {
+        lines.push(`Source fidelity ledger: blocked (${result.failureCode})`);
+    }
     if (result.failureReason)
         lines.push(`Failure reason: ${result.failureReason}`);
     if (result.openspecReadPaths.length > 0) {