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

package/dist/workflows/dag/frontend-review-context.js

@@ -1,17 +1,39 @@
+import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
 import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "./frontend-worktree-diff.js";
 import { frontendLintAssessmentArtifactSchema } from "./frontend-lint-baseline.js";
-import { frontendImplementationContractSchema } from "./frontend-implementation-contract.js";
+import { frontendImplementationContractSchema, } from "./frontend-implementation-contract.js";
 import { frontendRepairAssessmentSchema } from "./frontend-repair.js";
+import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { ledgerStatsLine, parseLedgerJson, } from "../../task/source-prepare/ledger.js";
 export const FRONTEND_REVIEW_CONTEXT_SCHEMA_ID = "frontend-review-context-v1";
+/**
+ * review-context 稳定失败枚举（AC-011 / AC-HARD-005）：v2 drift / manifest 失败返回
+ * 结构化、可消费的 failure code（稳定枚举 + reason 的 envelope），既有调用方无需字符串
+ * 匹配裸 Error 文本。message 保持人类可读（shell stderr 兼容），code 供机械化路由。
+ */
+export const FRONTEND_REVIEW_CONTEXT_FAILURE_CODES = [
+    "review-context-invalid-contract",
+    "review-context-verification-unbound",
+    "review-context-ledger-drift",
+    "review-context-manifest-missing",
+];
+export class FrontendReviewContextFailure extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "FrontendReviewContextFailure";
+        this.code = code;
+    }
+}
 async function readRequiredJson(runDir, relativePath) {
     try {
         return JSON.parse(await readFile(path.join(runDir, relativePath), "utf8"));
     }
-    catch {
-        throw new Error(`frontend review context missing or invalid ${relativePath}`);
+    catch (error) {
+        throw new FrontendReviewContextFailure("review-context-manifest-missing", `frontend review context missing or invalid ${relativePath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 async function readOptionalLintAssessment(runDir) {
@@ -32,8 +54,9 @@ async function readOptionalLintAssessment(runDir) {
 }
 function assertReviewEvidence(input) {
     const contract = frontendImplementationContractSchema.safeParse(input.contract);
-    if (!contract.success)
-        throw new Error("frontend review context invalid implementation contract");
+    if (!contract.success) {
+        throw new FrontendReviewContextFailure("review-context-invalid-contract", "frontend review context invalid implementation contract");
+    }
     const trace = input.verificationTrace;
     const expectedTargets = new Map(contract.data.verificationTargets.map((target) => [target.id, target]));
     const actualTargets = Array.isArray(trace?.targets) ? trace.targets : [];
@@ -69,17 +92,19 @@ function assertReviewEvidence(input) {
         actualIds.size !== expectedTargets.size ||
         !mockEvidenceBound ||
         trace.mockStrategy !== contract.data.mockApi.strategy) {
-        throw new Error("frontend review context verification trace is not bound to a passing contract");
+        throw new FrontendReviewContextFailure("review-context-verification-unbound", "frontend review context verification trace is not bound to a passing contract");
     }
     const assessment = frontendRepairAssessmentSchema.safeParse(input.repairAssessment);
-    if (!assessment.success)
-        throw new Error("frontend review context invalid repair assessment");
+    if (!assessment.success) {
+        throw new FrontendReviewContextFailure("review-context-invalid-contract", "frontend review context invalid repair assessment");
+    }
 }
 export async function runFrontendReviewContextGate(input) {
     const contract = await readRequiredJson(input.runDir, "contracts/frontend-implementation-contract.json");
     const parsedContract = frontendImplementationContractSchema.safeParse(contract);
-    if (!parsedContract.success)
-        throw new Error("frontend review context invalid implementation contract");
+    if (!parsedContract.success) {
+        throw new FrontendReviewContextFailure("review-context-invalid-contract", "frontend review context invalid implementation contract");
+    }
     const diff = await runFrontendWorktreeDiffGate({
         ...input,
         authorizedChangedPaths: parsedContract.data.targets.files,
@@ -88,6 +113,9 @@ export async function runFrontendReviewContextGate(input) {
     const repairAssessment = await readRequiredJson(input.runDir, "contracts/frontend-repair-assessment.json");
     const lintAssessment = await readOptionalLintAssessment(input.runDir);
     assertReviewEvidence({ contract, verificationTrace, repairAssessment });
+    // Source fidelity ledger 核对（AC-008 / AC-FIDELITY-008）：ledger 缺失/漂移即阻断；
+    // 同时把核对清单注入 review-context 供最终 reviewer 机械化核对。
+    const sourceFidelity = await buildReviewSourceFidelityChecklist(input, parsedContract.data);
     const payload = {
         schemaVersion: 1,
         schemaId: FRONTEND_REVIEW_CONTEXT_SCHEMA_ID,
@@ -95,6 +123,7 @@ export async function runFrontendReviewContextGate(input) {
         verificationTrace,
         repairAssessment,
         ...(lintAssessment ? { lintAssessment } : {}),
+        sourceFidelity,
         diff: {
             schemaId: diff.schemaId,
             patchPath: diff.patchPath,
@@ -107,6 +136,59 @@ export async function runFrontendReviewContextGate(input) {
     const artifactPath = await writeDagRunJsonArtifact(input.runDir, "contracts/frontend-review-context.json", payload);
     return { ok: true, artifactPath, diff };
 }
+/**
+ * 最终 review 核对清单（机械化）：ledger 缺失/漂移、canonical requirement 漏项、
+ * diff 越界、验证证据缺失均阻断 pass。清单以有界安全摘要注入提示词，不泄漏原文。
+ */
+async function buildReviewSourceFidelityChecklist(input, contract) {
+    const binding = contract.sourceBinding;
+    const checklist = [];
+    // 契约级 sourceBinding 的 v2 语义：四个 ledger 字段必须齐全（缺失即 v1 遗留绑定）。
+    const boundV2 = Boolean(binding.ledgerPath) &&
+        Boolean(binding.ledgerSha256) &&
+        Boolean(binding.inputDigest) &&
+        binding.requirementToFragments !== undefined;
+    if (!boundV2) {
+        return {
+            bound: false,
+            ledger: null,
+            checklist: [
+                "source fidelity ledger: not bound (v1 binding); 按现有语义评审",
+                "canonical contract 与实际 diff 逐项核对，验证证据齐全后 verdict 可为 pass",
+            ],
+        };
+    }
+    const absolute = resolveDagTaskSourcePath({
+        workspaceRoot: input.workspaceRoot,
+        taskId: contract.sourceBinding.taskId,
+        sourcePath: binding.ledgerPath,
+    });
+    let ledger = null;
+    try {
+        const raw = await readFile(absolute, "utf8");
+        const actualSha = createHash("sha256").update(raw).digest("hex");
+        if (actualSha !== binding.ledgerSha256) {
+            throw new Error(`ledger sha256 mismatch (bound ${binding.ledgerSha256}, observed ${actualSha})`);
+        }
+        ledger = parseLedgerJson(raw);
+    }
+    catch (error) {
+        // AC-011 / AC-HARD-005：v2 drift 返回结构化 failure code（稳定枚举 + reason），
+        // 不再裸 throw new Error；message 保持人类可读供 shell stderr。
+        throw new FrontendReviewContextFailure("review-context-ledger-drift", `frontend review context source fidelity ledger unavailable or drifted: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    checklist.push("ledger: 存在且绑定 sha256 一致（无缺失/漂移）", `ledger 覆盖统计: ${ledgerStatsLine(ledger)}`, "canonical contract requirements 必须覆盖 ledger 全部 canonical requirement IDs", "实际 diff 必须限制在契约 targets 内（越界即阻断 pass）", "验证证据必须绑定契约 verificationTargets（缺失即阻断 pass）", "仅满足派生摘要而遗漏 ledger requirement 时 verdict 不得为 pass");
+    return {
+        bound: true,
+        ledger: {
+            path: binding.ledgerPath,
+            sha256: binding.ledgerSha256,
+            inputDigest: binding.inputDigest,
+            stats: ledgerStatsLine(ledger),
+        },
+        checklist,
+    };
+}
 export function formatFrontendReviewContextStdout(result) {
     return [
         "Frontend review context: pass",

package/dist/workflows/dag/init-hybrid.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { access, readdir, readFile, realpath } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { assertValidDagSpec } from "./validate.js";
@@ -22,6 +22,9 @@ import { discoverProjectGovernancePresence } from "./project-governance-context.
 import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { materializeTaskReferenceDocs } from "../../task/source-references.js";
 import { observeTaskContract } from "../../task/contract/observe.js";
+import { extractRequirementFactsFromMarkdown } from "../../task/source-prepare/parse-intent.js";
+import { computeLedgerInputDigest, parseLedgerJson, recoverLedgerInputContract, } from "../../task/source-prepare/ledger.js";
+import { REQUIREMENT_LEDGER_FILE_NAME } from "../../task/contract/constants.js";
 import { dagHasWriterExecution } from "./task-contract-binding.js";
 import { DEFAULT_VERIFY_TIMEOUT_MS, resolveVerifyPreset, } from "../../executors/shell-verification.js";
 import { resolveExecutorModelMatrices } from "../../executors/model-routing.js";
@@ -1477,7 +1480,7 @@ export function extractTaskScopedRequirementIds(requirementMarkdown, ...fallback
         .sort((a, b) => a - b);
     return numbered.map((value) => `AC-${value}`);
 }
-function buildDagSourceBinding(sources) {
+function buildDagSourceBindingBase(sources) {
     const sourceEntries = [
         {
             kind: "requirement",
@@ -1512,6 +1515,124 @@ function buildDagSourceBinding(sources) {
         requirementIds: extractTaskScopedRequirementIds(sources.requirementMarkdown, sources.constraintMarkdown, ...(sources.referenceDocuments ?? []).map((reference) => reference.markdown)),
     };
 }
+/**
+ * Source binding v2（AC-001 / AC-FIDELITY-REPAIR-001）：仅 frontend taskKind 且存在
+ * 可解析 requirement/acceptance 引用时产出 schemaVersion=2 绑定（ledger 指针 +
+ * requirement→fragment 映射全部必填）。绑定完全来自 task advance 已持久化的
+ * source/requirement-ledger.json（intake 侧同一份受管账本的原始字节/hash/inputDigest），
+ * 绝不从 materialized reference path 重建语义等价但 path/hash 不同的 ledger；
+ * 缺失/损坏/漂移 fail closed（SOURCE_FIDELITY_LEDGER_MISSING / _STALE）。
+ */
+function buildDagSourceBinding(sources, taskKind) {
+    const base = buildDagSourceBindingBase(sources);
+    if (taskKind !== "frontend-implementation")
+        return base;
+    const ledgerBinding = loadPersistedFrontendSourceBindingLedger(sources);
+    if (!ledgerBinding)
+        return base;
+    // AC-002 / AC-HARD-002：物化 REQ-SRC-* canonical id 确定性并入 v2 requirementIds。
+    // 生成型 REQ-SRC-* id 无法从 markdown 文本导出（必须来自持久化 ledger），此处
+    // 在 required requirement ids 侧确定性注入，确保 prewrite missing-requirement-ids
+    // 不误伤（不要求文本可导出）也不漏检（物化 id 必须被契约覆盖）。
+    const materializedRequirementIds = Object.keys(ledgerBinding.requirementToFragments)
+        .filter((id) => /^REQ-SRC-/.test(id) && !base.requirementIds.includes(id))
+        .sort();
+    return {
+        schemaVersion: 2,
+        taskId: base.taskId,
+        sources: base.sources,
+        requirementIds: [
+            ...base.requirementIds,
+            ...materializedRequirementIds,
+        ],
+        ledgerPath: ledgerBinding.ledgerPath,
+        ledgerSha256: ledgerBinding.ledgerSha256,
+        inputDigest: ledgerBinding.inputDigest,
+        requirementToFragments: ledgerBinding.requirementToFragments,
+    };
+}
+/**
+ * 读取 Task Contract 已持久化的 source/requirement-ledger.json，核验字节 sha256
+ * 与 inputDigest（与当前源输入 digest 一致）后产出 v2 绑定字段。缺失/损坏/漂移
+ * 抛稳定错误（SOURCE_FIDELITY_LEDGER_MISSING / SOURCE_FIDELITY_LEDGER_STALE）。
+ * 新鲜度侧不再"重新推导"权威输入，而是从持久化 ledger 恢复 build 侧的输入合同
+ * （与 ledger build 使用完全相同的输入），避免 contract apply 重投影派生导航视图
+ * 需求.md 导致重抽取漂移误判 stale（AC-DIGEST-001/002/003）。
+ */
+function loadPersistedFrontendSourceBindingLedger(sources) {
+    const referenceDocs = (sources.referenceDocuments ?? []).filter((doc) => doc.markdown.trim().length > 0);
+    if (referenceDocs.length === 0)
+        return null;
+    // 存在性守卫（保持既有 v1 回退行为）：派生视图无可抽取 requirement/acceptance
+    // 引用时不要求持久化 ledger，直接回退 base binding。此守卫只用于"是否 ledger
+    // 任务"判定，绝不参与 digest 键计算——键输入完全来自持久化 ledger 恢复。
+    const guardFacts = extractRequirementFactsFromMarkdown(sources.requirementMarkdown);
+    if (guardFacts.acceptanceCriteria.length === 0)
+        return null;
+    const ledgerAbsolutePath = path.join(sources.taskDir, "source", REQUIREMENT_LEDGER_FILE_NAME);
+    let raw;
+    try {
+        raw = readFileSync(ledgerAbsolutePath, "utf8");
+    }
+    catch (error) {
+        throw new Error(`SOURCE_FIDELITY_LEDGER_MISSING: frontend task ${sources.taskId} has resolvable requirement/acceptance references but no persisted ${REQUIREMENT_LEDGER_FILE_NAME} at ${ledgerAbsolutePath}; run task advance (intake) to persist the ledger before dag init-hybrid (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const ledgerSha256 = createHash("sha256").update(raw).digest("hex");
+    let ledger;
+    try {
+        ledger = parseLedgerJson(raw);
+    }
+    catch (error) {
+        throw new Error(`SOURCE_FIDELITY_LEDGER_MISSING: persisted ${REQUIREMENT_LEDGER_FILE_NAME} is not a valid v1 ledger: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // canonical 侧：ledger.canonicalRequirements 按 build 顺序原样保留输入 canonical
+    // requirements（id/text 逐字节），过滤物化 REQ-SRC-*（AC-HARD-002 "物化不入键"）
+    // 即精确恢复 digest 输入集；派生导航视图 需求.md 投影不参与键计算。
+    const contract = recoverLedgerInputContract(ledger);
+    if (contract.canonicalRequirements.length === 0) {
+        // AC-HARD-003：存在 v2 ledger 但 canonical requirements 为空时 fail closed，
+        // 绝不回退 v1 base 绑定（buildDagSourceBinding 不降级）。空 canonical 的 ledger
+        // 无法提供 requirement→fragment 映射证据，任何 v1 回退都会静默放行 fail-open。
+        throw new Error(`SOURCE_FIDELITY_LEDGER_STALE: persisted ${REQUIREMENT_LEDGER_FILE_NAME} has an empty canonical requirement set; refusing to fall back to a v1 base binding; re-run task advance (intake) to rebuild the ledger`);
+    }
+    // source 侧：ledger.sourcePaths（build 时权威 sourceDocuments 的 repo-root
+    // relative POSIX 路径集合）作为权威身份集合，对当前 materialized reference 文件
+    // 做交集过滤；内容取当前字节（漂移检测）。权威路径缺失（删除/清空/重命名）→
+    // fail-closed STALE；新增的非权威 role 文件被正确排除（不入键）。
+    const currentByPath = new Map();
+    for (const doc of referenceDocs) {
+        currentByPath.set(toDagSourcePath(sources, doc.path), doc.markdown);
+    }
+    const missingAuthoritativePaths = contract.sourcePaths.filter((sourcePath) => !currentByPath.has(sourcePath));
+    if (missingAuthoritativePaths.length > 0) {
+        throw new Error(`SOURCE_FIDELITY_LEDGER_STALE: persisted ${REQUIREMENT_LEDGER_FILE_NAME} was built from authoritative source documents no longer present (${missingAuthoritativePaths.join(", ")}); re-run task advance (intake) to rebuild the ledger`);
+    }
+    // inputDigest 新鲜度：与当前源输入（canonical repo-root relative identity）一致。
+    // digest 只绑定语义权威输入（规范化源文档 + canonical requirements +
+    // schema/reconciler version）；派生导航视图 需求.md 投影不参与键计算。
+    const expectedDigest = computeLedgerInputDigest({
+        sourceDocuments: contract.sourcePaths.map((sourcePath) => ({
+            path: sourcePath,
+            content: currentByPath.get(sourcePath),
+        })),
+        canonicalRequirements: contract.canonicalRequirements,
+    });
+    if (ledger.inputDigest !== expectedDigest) {
+        throw new Error(`SOURCE_FIDELITY_LEDGER_STALE: persisted ${REQUIREMENT_LEDGER_FILE_NAME} inputDigest ${ledger.inputDigest} does not match current source input ${expectedDigest}; re-run task advance (intake) to rebuild the ledger`);
+    }
+    const requirementToFragments = {};
+    for (const requirement of ledger.canonicalRequirements) {
+        if (requirement.sourceFragmentIds.length > 0) {
+            requirementToFragments[requirement.id] = requirement.sourceFragmentIds;
+        }
+    }
+    return {
+        ledgerPath: toDagSourcePath(sources, ledgerAbsolutePath),
+        ledgerSha256,
+        inputDigest: ledger.inputDigest,
+        requirementToFragments,
+    };
+}
 function buildBackendTestAnalysisSourceBindingContract(sources) {
     const binding = buildDagSourceBinding(sources);
     const requirement = binding.sources.find((source) => source.kind === "requirement");
@@ -2416,7 +2537,7 @@ async function buildFrontendHybridDagFromTask(sources) {
             allowedPaths: taskConfig.allowedPaths,
             complexity: taskConfig.complexity,
         });
-    const frontendSourceBinding = buildDagSourceBinding(sources);
+    const frontendSourceBinding = buildDagSourceBinding(sources, taskConfig.taskKind);
     const frontendContractSkeleton = buildFrontendImplementationContractSkeleton({
         sourceBinding: frontendSourceBinding,
         riskLevel: frontendRisk.selectedRisk,
@@ -6563,7 +6684,7 @@ async function buildHybridDagForTemplate(sources, template, options = {}) {
     if (!spec.runtimeContract) {
         spec.runtimeContract = GENERATED_DAG_RUNTIME_CONTRACT;
     }
-    spec.sourceBinding = buildDagSourceBinding(sources);
+    spec.sourceBinding = buildDagSourceBinding(sources, template === "frontend-implementation" ? "frontend-implementation" : undefined);
     spec.taskContractBinding = taskContractBinding;
     assertNoGovernanceFlagOnDisallowedTemplate(spec, template);
     if (template === "standard-dag" ||

package/dist/workflows/dag/node-execution.js

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
 import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHumanEscalationArtifacts, } from "./decision-envelope.js";
 import { FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, FRONTEND_WRITER_NODE_IDS, isFrontendWriterAuthorized, readFrontendPrewriteResult, } from "./scheduler.js";
 import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
@@ -306,6 +307,35 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
         "</retry_instruction>",
     ].join("\n");
 }
+const PROMPT_RESTART_CANDIDATE_MAX_BYTES = 64 * 1024;
+function promptRestartCandidateForAttempt(input) {
+    if (input.attemptPrompt === input.baseRuntimePrompt) {
+        return input.taskPrompt;
+    }
+    const appendedPrefix = `${input.baseRuntimePrompt}\n\n`;
+    if (input.attemptPrompt.startsWith(appendedPrefix)) {
+        return [
+            input.taskPrompt,
+            input.attemptPrompt.slice(appendedPrefix.length),
+        ]
+            .filter(Boolean)
+            .join("\n\n");
+    }
+    return input.attemptPrompt;
+}
+async function persistFailedPromptRestartCandidate(input) {
+    const redacted = redactSecrets(input.prompt);
+    const preview = truncateUtf8Preview(redacted, PROMPT_RESTART_CANDIDATE_MAX_BYTES);
+    await writeDagNodeJsonArtifact(input.runDir, input.nodeId, `prompt-candidate-attempt-${input.attempt}.json`, {
+        schemaVersion: 1,
+        attempt: input.attempt,
+        failureCategory: input.failureCategory ?? "unknown",
+        prompt: preview,
+        truncated: preview !== redacted,
+        maxBytes: PROMPT_RESTART_CANDIDATE_MAX_BYTES,
+        sha256: createHash("sha256").update(redacted).digest("hex"),
+    });
+}
 export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd, options) {
     const policy = resolveContextPolicy(spec);
     const skillNames = policy.resolveSkills(spec, task);
@@ -770,6 +800,7 @@ export async function executeDagNode(input) {
         // exactly this attempt's segment (B1: earlier attempts legitimately use
         // ls/find and must not be attributed to the repair attempt).
         const attemptSessionEventsOffset = await sessionEventsByteLength(runDir, nodeId);
+        let promptRestartCandidate = task.subtask_prompt;
         let result;
         try {
             validateRepairArtifactGateBeforeShell({
@@ -833,6 +864,11 @@ export async function executeDagNode(input) {
                     previousReason: previousProtocolReason,
                 });
             }
+            promptRestartCandidate = promptRestartCandidateForAttempt({
+                taskPrompt: task.subtask_prompt,
+                baseRuntimePrompt: prompt,
+                attemptPrompt,
+            });
             result = await executeNode({
                 task,
                 cwd,
@@ -960,6 +996,15 @@ export async function executeDagNode(input) {
         const attemptWallDurationMs = durationBetween(attemptStartedAt, attemptFinishedAt);
         totalAttemptWallDurationMs += attemptWallDurationMs;
         const rawFailureCategory = result.rawFailureCategory ?? result.failureCategory;
+        if (task.executor === "pi" && !result.ok) {
+            await persistFailedPromptRestartCandidate({
+                runDir,
+                nodeId,
+                attempt: attemptNumber,
+                failureCategory: result.failureCategory,
+                prompt: promptRestartCandidate,
+            });
+        }
         const attemptRecord = {
             attempt: attemptNumber,
             startedAt: attemptStartedAt,

package/dist/workflows/dag/types.js

@@ -890,20 +890,51 @@ export const dagEvaluationBindingSchema = z
     .strict();
 /** Eval Lab Campaign Budget (W3.4); enforced by runner ledger when mode=hard. */
 export const dagBudgetSchema = campaignBudgetSchema;
-export const dagSourceBindingSchema = z.object({
+export const dagSourceBindingSourceSchema = z.object({
+    kind: z.enum(["requirement", "constraint", "reference"]),
+    path: z.string().min(1),
+    sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
+});
+/**
+ * DagSourceBinding v1：无 ledger 字段（schemaVersion=1，.strict() 拒绝 ledger
+ * 字段混入，不得以 v1+optional 冒充 v2）。非 frontend task / 无可解析引用时使用。
+ */
+export const dagSourceBindingV1Schema = z
+    .object({
     schemaVersion: z.literal(1),
     taskId: z.string().min(1),
-    sources: z
-        .array(z.object({
-        kind: z.enum(["requirement", "constraint", "reference"]),
-        path: z.string().min(1),
-        sha256: z
-            .string()
-            .regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
-    }))
-        .min(1),
+    sources: z.array(dagSourceBindingSourceSchema).min(1),
     requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
-});
+})
+    .strict();
+/**
+ * DagSourceBinding v2（20260824-frontend-source-fidelity-ledger-v1）：仅
+ * frontend-implementation 且存在可解析 requirement/acceptance 引用时产出；
+ * ledgerPath/ledgerSha256/inputDigest/requirementToFragments 全部必填且完整，
+ * 伪造或缺失任一字段被 schema/prewrite 拒绝（AC-002 / AC-FIDELITY-REPAIR-002）。
+ */
+export const dagSourceBindingV2Schema = z
+    .object({
+    schemaVersion: z.literal(2),
+    taskId: z.string().min(1),
+    sources: z.array(dagSourceBindingSourceSchema).min(1),
+    requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
+    /** 受管 requirement-ledger.json 的 DAG 可解析路径（.harness/tasks/…/source/…）。 */
+    ledgerPath: z.string().min(1),
+    ledgerSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    inputDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    requirementToFragments: z.record(z.string(), z.array(z.string())),
+})
+    .strict();
+export const dagSourceBindingSchema = z.discriminatedUnion("schemaVersion", [
+    dagSourceBindingV1Schema,
+    dagSourceBindingV2Schema,
+]);
+export function isDagSourceBindingV2(binding) {
+    return binding.schemaVersion === 2;
+}
 const dagRerunFeedbackEvidencePathSchema = z
     .string()
     .min(1)

package/docs/README.md

@@ -27,6 +27,7 @@
 | 选择快速、标准或完整验证命令 | `governance/verification-matrix.md` |
 | 理解 CLI、runtime 和初始化能力边界 | `runtime/loop-agent-harness.md` |
 | 运行 DAG、查看报告或处理失败 | `runtime/agent-dag-runner.md`、`runtime/agent-dag-recovery-playbook.md`；Operator Chat P0 closeout 见 `reports/feature/2026-08-14-operator-chat-dag-recovery-p0.md` |
+| 理解前端实现 DAG 与需求保真账本 | `runtime/frontend-implementation-workflow.md`（含 source fidelity ledger v2 绑定、顺序 reconciliation、独立 reviewer、human resolution 与 prewrite fail-closed）；init-evolution 审查见 `reports/init-evolution/2026-08-24-frontend-source-fidelity-ledger-init-evolution-review.md` |
 | 按 TDD、验证和调试纪律推进修复 | `governance/harness-methodology-tdd.md`、`governance/harness-methodology-verification.md`、`governance/harness-methodology-debugging.md` |
 | 执行真实 backend-test provider 验证 | `runtime/backend-test-live-campaign.md` |
 | 判断单任务 loop-agent Production Readiness | `operations/production-readiness.md` |

package/docs/architecture/evolution.md

@@ -33,6 +33,7 @@ loop-agent CLI
 | Worker readiness baseline | Attempt identity、immutable owner、lineage/revision、task-scoped lease、controller protocol、acceptance、reconcile | Agent Worker PR v1 Phase 1–7 / `0.32.0` |
 | Operator Surface | 裸 `agent-worker console`；Operate、`/inspect/`、Operator Chat、recovery CTA、intake bridge | ADR 0005、0011–0013 |
 | 自举与验证 | controller identity、skill snapshot、deterministic/live canary、verified tarball、`verify:tree` receipt | `runtime-boundaries.md`、verification matrix |
+| Source fidelity ledger | 原始 requirement/acceptance 文档保持语义权威，派生 `source/需求.md` 仅作导航视图；确定性 fragment inventory、受管 `requirement-ledger.json`（进入 Task Contract transaction 与 canonical hash）、source binding v2（仅 frontend taskKind，schemaVersion=2 必填字段）、prewrite fail-closed 门禁（`SOURCE_FIDELITY_*`/`source-*` 稳定错误码）、顺序 reconciliation 与独立 reviewer、human resolution 生效、有界提示词与最终 reviewer 核对清单 | `20260824-frontend-source-fidelity-ledger-v1` + `2026-08-24-frontend-source-fidelity-repair-v2`（本页面下方 init-evolution 审查）、`CHANGELOG.md [Unreleased]` |
 
 ### 当前不变量
 
@@ -106,3 +107,47 @@ Evidence & Trust Plane
 2. 证明成立后更新 current capability summary 和本页“当前架构”。
 3. 未证明部分只保留在 active design/exec-plan，不能通过修改措辞升级状态。
 4. 使用者短索引同步到 `website/docs/overview/roadmap.md`，避免复制长版本流水账。
+
+## Init Evolution Review — 2026-08-24 frontend source fidelity ledger
+
+Base/Head：见 `docs/reports/init-evolution/` 中对应 `*-init-evolution-review.md`（若已提交则含 Base/Head 字段；未提交工作区由 CI 非严格模式放行）。
+
+### Changed Surface
+
+- `src/task/source-prepare/**`：新增 `fragment-inventory.ts`、`ledger.ts`；扩展 `types.ts`、`prepare.ts`、`completeness.ts`、`parse-intent.ts`（无外部 API 变化）。
+- `src/task/contract/**`：`requirement-ledger.json` 进入受管 transaction 与 canonical hash；`TaskContractSourceHashesV1` 新增可选 `requirementLedgerSha256`（legacy ref 向后兼容）。
+- `src/workflows/dag/**`：`dagSourceBindingSchema` 拆为 v1/v2 discriminated union（v2 schemaVersion=2，四个 ledger 字段全部必填；v1 strict 拒绝 ledger 字段）；`init-hybrid` 改读已持久化 ledger（缺失/漂移 fail closed）；prewrite 门禁新增 ledger 检查与失败码。
+- `src/task/source-prepare/**`：新增 `ledger-reconciliation.ts`（顺序 reconciliation）、`ledger-review.ts`（独立 reviewer）；fragment inventory 表格行切分、跨文档稳定 REQ-SRC ID、V4 显式 AC 标题；human resolution 生效。
+- `src/worker/observe/**`：新增只读 `GET /api/tasks/:id/ledger` 与展示（安全摘要，不泄漏原文）。
+- `src/worker/console/**`：Draft/ContractPanel/InspectSplitPanel 安全摘要展示。
+- `docs/templates/frontend-implementation-contract.schema.json`：requirements 增加可选 `sourceFragmentIds`/`sourceRefs`，sourceBinding 增加可选 ledger 字段（all-or-none）。
+
+### Decision
+
+**No init impact / Surface check only**。
+
+Rationale：
+
+- 新增均为模块内部实现；不新增 CLI 命令、不改 init 入口、不改变 target-project 初始化行为。
+- `docs/templates/frontend-implementation-contract.schema.json` 已随 `docs/templates/` 目录 glob 打包（`package.json files`），无需新增 manifest 条目。
+- 运行时加载 schema 的 `loadFrontendImplementationContractJsonSchema` 仅做结构性校验（$id/required/properties/const），新增可选字段不破坏既有契约。
+- 不新增任何运行时或开发依赖（node:crypto、既有 zod/Vitest/Vite/React 19）。
+
+### Updates Made
+
+- `docs/architecture/evolution.md`：本条目。
+- `CHANGELOG.md [Unreleased]`、`CONTEXT.md`：glossary 术语。
+- `docs/templates/frontend-implementation-contract.schema.json`：可选字段同步。
+
+### Verification
+
+```bash
+npm run typecheck && npm run console:typecheck
+npx vitest run test/task-source-prepare.test.ts test/task-contract-canonicalize.test.ts test/task-contract-observe.test.ts test/dag-init-hybrid.test.ts test/frontend-implementation-contract.test.ts test/frontend-prewrite-gate.test.ts test/frontend-writer-admission.test.ts test/worker/observe/dag-inspector-node-input.test.ts test/worker/console/inspect-split-panel.test.ts
+```
+
+### Residual Risk
+
+- 长尾 24K 截断遗漏回归：以确定性分片 inventory + ledger 覆盖统计断言固定（AC-FIDELITY-001/007）。
+- 账本漂移/篡改：inputDigest 复用失效 + prewrite fail closed（AC-FIDELITY-003/006）。
+- 既有带引用 frontend task 重建路径变化：ledger 纳入 canonical hash 改变 `observeTaskContractState` 判定，legacy ref 向后兼容覆盖（AC-FIDELITY-004）。

package/docs/init-surface.manifest.json

@@ -30,6 +30,7 @@
     "docs/templates/frontend-task-requirement.md",
     "docs/templates/frontend-task-constraints.md",
     "docs/templates/frontend-design-contract.md",
+    "docs/templates/frontend-implementation-contract.schema.json",
     "docs/templates/worker-dogfood-setup.md",
     "docs/templates/worker-dogfood-evidence.md",
     "docs/templates/harness.schema.json",

package/docs/templates/README.md

@@ -37,7 +37,7 @@
 ## Frontend
 
 - `frontend-task-requirement.md`、`frontend-task-constraints.md`、`frontend-design-contract.md` — 前端任务输入与设计合同。
-- `frontend-implementation-contract.schema.json` — 前端实现合同 schema。
+- `frontend-implementation-contract.schema.json` — 前端实现合同 schema（sourceBinding v2 ledger 字段 all-or-none：任一出现则四项齐全，禁止 v1+optional 冒充 v2）。`requirements[].sourceRefs[].items` 使用合法 `$ref: #/$defs/path`（相对路径、无 `..` 逃逸、无反斜杠），模板 JSON 无非法键，运行时加载器可直接编译（AC-003）。
 - `frontend-test-dag.json` — frontend-test DAG 模板；其 deterministic checklist 会拒绝 alternative executable instructions，仅允许 allowlisted `playwright-cli` command。Pi generator/reviser 的 runtime writeSet 仅授权下列目标项目生成路径（不是本仓库文档索引目标）：
 
   ~~~text