@tea-agent/loop-agent 0.39.0-next.9 → 0.39.1

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

@@ -8,11 +8,14 @@ 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",
     "strip-comments",
     "canonicalize-requirement-ids",
     "canonicalize-verification-alias",
+    "drop-unresolved-verification-symbols",
     "inject-source-binding",
 ]);
 export function sha256Hex(input) {
@@ -102,6 +105,21 @@ async function deriveFrozenCommandLabelsFromRun(runDir) {
     return [...labels];
 }
 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";
+/**
+ * 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
+ * cannot redefine task identity, risk, or the implementation write boundary.
+ */
+export function buildFrontendImplementationContractSkeleton(input) {
+    return {
+        schemaVersion: 1,
+        sourceBinding: canonicalFrontendContractSourceBinding(input.sourceBinding),
+        riskLevel: input.riskLevel,
+        targets: { files: [...input.targetFiles] },
+        mockApi: { productionDefaultOff: true },
+    };
+}
 /**
  * Load the canonical frontend-implementation-contract-v1 JSON Schema from the
  * installed loop-agent package docs/templates/ path. Package-root discovery
@@ -262,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({
@@ -279,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
@@ -415,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 &&
@@ -499,9 +570,9 @@ function isPlainObject(value) {
  * ever materialized, so a patch that removes a required field still fails
  * closed at the gate.
  */
-export function applyFrontendImplementationContractPatch(target, patch) {
+export function applyFrontendContractMergePatch(target, patch) {
     if (!isPlainObject(patch)) {
-        throw new Error("frontend revision patch must be a JSON object");
+        throw new Error("frontend contract patch must be a JSON object");
     }
     const merge = (base, delta) => {
         if (delta === null)
@@ -526,6 +597,9 @@ export function applyFrontendImplementationContractPatch(target, patch) {
     };
     return merge(target, patch);
 }
+export function applyFrontendImplementationContractPatch(target, patch) {
+    return applyFrontendContractMergePatch(target, patch);
+}
 export async function assertFrontendSourceBindingFresh(input) {
     for (const source of input.binding.sources) {
         const absolute = resolveDagTaskSourcePath({
@@ -548,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)/;
@@ -722,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,
@@ -732,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)
@@ -1466,7 +1572,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 {
@@ -1608,6 +1720,243 @@ export async function writeFrontendImplementationContractArtifact(input) {
         schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
     };
 }
+const FRONTEND_PLAN_PATCH_PROTECTED_PATHS = [
+    "/schemaVersion",
+    "/sourceBinding",
+    "/riskLevel",
+    "/targets/files",
+    "/mockApi/productionDefaultOff",
+];
+function frontendPlanPatchProtectedPathViolations(patch) {
+    const record = asRecord(patch);
+    if (!record)
+        return ["/"];
+    const violations = [];
+    for (const key of ["schemaVersion", "sourceBinding", "riskLevel"]) {
+        if (Object.hasOwn(record, key))
+            violations.push(`/${key}`);
+    }
+    const targets = asRecord(record.targets);
+    if (targets && Object.hasOwn(targets, "files"))
+        violations.push("/targets/files");
+    const mockApi = asRecord(record.mockApi);
+    if (mockApi && Object.hasOwn(mockApi, "productionDefaultOff"))
+        violations.push("/mockApi/productionDefaultOff");
+    return violations;
+}
+function workspaceRootFromDagRunDir(runDir) {
+    const absolute = path.resolve(runDir);
+    const segments = absolute.split(path.sep);
+    const harnessIndex = segments.lastIndexOf(".harness");
+    if (harnessIndex < 0 ||
+        segments[harnessIndex + 1] !== "dag-runs" ||
+        harnessIndex + 3 >= segments.length) {
+        return null;
+    }
+    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;
+    for (const targetValue of targets) {
+        const target = asRecord(targetValue);
+        const file = asString(target?.file);
+        const symbol = asString(target?.symbol);
+        if (!target || !file || !symbol)
+            continue;
+        const absolute = path.resolve(workspaceRoot, file);
+        const relative = path.relative(workspaceRoot, absolute);
+        if (relative.startsWith("..") ||
+            path.isAbsolute(relative) ||
+            relative.includes("..")) {
+            continue;
+        }
+        let content;
+        try {
+            content = await readFile(absolute, "utf8");
+        }
+        catch {
+            // Missing files remain a trace-time hard failure; do not hide them by
+            // changing the optional symbol during candidate normalization.
+            continue;
+        }
+        if (verificationSymbolMatchesFile(symbol, content))
+            continue;
+        delete target.symbol;
+        changed = true;
+    }
+    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];
+}
+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.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 a path-only pointer plus the hash-bound canonical artifact for
+ * downstream review and prewrite nodes.
+ */
+export async function validateFrontendPlanPatchNodeOutput(input) {
+    const nodeId = input.nodeId ?? "frontend-plan-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,
+    });
+    const reportBase = {
+        schemaVersion: 1,
+        schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID,
+        nodeId,
+        attempt,
+        rawPath,
+        protectedPaths: [...FRONTEND_PLAN_PATCH_PROTECTED_PATHS],
+        candidateRawSha256: sha256Hex(input.text),
+    };
+    let extractedPatchPath;
+    let extractedPatchSha256;
+    const writeReport = async (value) => {
+        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.validation.json`), {
+            ...reportBase,
+            ...(extractedPatchPath
+                ? { extractedPatchPath, extractedPatchSha256 }
+                : {}),
+            ...value,
+        });
+    };
+    try {
+        if (!input.sourceBinding)
+            throw new Error("frontend plan patch validator requires DAG sourceBinding");
+        const skeleton = input.structuredContractOutput?.skeleton;
+        if (!skeleton)
+            throw new Error("frontend plan patch validator requires a deterministic runtime skeleton");
+        const patch = extractFrontendImplementationJson(input.text);
+        if (!isPlainObject(patch))
+            throw new Error("frontend plan patch must extract to one JSON object");
+        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({
+            runDir: input.runDir,
+            contract: merged,
+        });
+        const analysis = await analyzeFrontendImplementationContract({
+            runDir: input.runDir,
+            rawContractText: serializeDeterministicJson(merged),
+            sourceBinding: input.sourceBinding,
+        });
+        const normalizedArtifact = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
+        await writeReport({
+            classification: "accepted-normalized",
+            normalizedContractPath: path.posix.relative(input.runDir.replaceAll(path.sep, "/"), normalizedArtifact.path.replaceAll(path.sep, "/")),
+            normalizedContractSha256: normalizedArtifact.sha256,
+            normalizationActions: [
+                "apply-runtime-skeleton",
+                ...(droppedUnresolvedSymbols
+                    ? ["drop-unresolved-verification-symbols"]
+                    : []),
+                ...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,
+            skeleton,
+        });
+        const artifact = {
+            path: canonicalArtifact.path,
+            sha256: canonicalArtifact.sha256,
+            schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+        };
+        return {
+            ok: true,
+            contract: analysis.canonical,
+            artifact,
+            normalizedText: formatStructuredArtifactPointer(artifact),
+        };
+    }
+    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: classified.classification,
+            normalizationActions: [],
+            errors: classified.errors,
+        });
+        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;
+    }
+}
 /**
  * Node-output self-check for plan nodes that produce the implementation
  * contract. Mirrors the prewrite gate validation so schema/typo/null violations
@@ -1626,12 +1975,122 @@ 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. 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.
+ */
+export async function validateFrontendRevisionPatchNodeOutput(input) {
+    const fail = (reason) => {
+        const classified = classifyStructuredContractFailure({ reason });
+        return {
+            ok: false,
+            reason,
+            classification: classified.classification,
+            errors: classified.errors,
+        };
+    };
+    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));
+    }
+    const textWithoutCitations = input.text.replace(citationsBlock, "");
+    let patch;
+    try {
+        patch = extractFrontendImplementationJson(textWithoutCitations);
+    }
+    catch (error) {
+        return fail(`revision patch output must contain exactly one valid JSON object: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    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)");
+    }
+    const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
+    if (protectedViolations.length > 0) {
+        return fail(`frontend revision patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`);
+    }
+    const original = (await readFrontendCanonicalCandidate(input.runDir, "frontend-plan-pi")) ??
+        (await readFrontendCanonicalCandidate(input.runDir, nodeId));
+    if (!input.sourceBinding) {
+        return { ok: true, contract: patch };
+    }
+    if (!original) {
+        return fail("frontend revision patch requires the original frontend-plan-pi canonical contract");
+    }
+    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),
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return fail(reason);
+    }
+}
 export async function materializeFrontendImplementationContract(input) {
     const analysis = await analyzeFrontendImplementationContract(input);
     return writeFrontendImplementationContractArtifact({

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)_",
         "",