@tea-agent/loop-agent 0.40.0-next.1 → 0.40.0-next.11

package/dist/shared/update/npm-client.js

@@ -11,10 +11,10 @@ export function createNpmUpdateClient(options) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_NPM_QUERY_TIMEOUT_MS;
     const cwd = options.cwd;
     const env = options.env;
-    const latestVersionCheck = async () => {
+    const distTagVersionCheck = async (channel) => {
         let result;
         try {
-            result = await runner(npmCommand, ["view", PACKAGE_NAME, "dist-tags.latest", "--json"], { timeoutMs, cwd, env });
+            result = await runner(npmCommand, ["view", PACKAGE_NAME, `dist-tags.${channel}`, "--json"], { timeoutMs, cwd, env });
         }
         catch {
             return { ok: false, reason: "spawn-failure" };
@@ -27,17 +27,19 @@ export function createNpmUpdateClient(options) {
         if (result.exitCode !== 0) {
             return { ok: false, reason: "command-failed" };
         }
-        const version = parseNpmViewLatest(result.stdout);
+        const version = parseNpmViewDistTag(result.stdout, channel);
         return version
             ? { ok: true, version }
             : { ok: false, reason: "invalid-response" };
     };
+    const latestVersionCheck = () => distTagVersionCheck("latest");
     return {
         async latestVersion() {
             const result = await latestVersionCheck();
             return result.ok ? result.version : undefined;
         },
         latestVersionCheck,
+        distTagVersionCheck,
         async canAutoInstall() {
             return proveGlobalNpmInstall({
                 currentVersion: options.currentVersion,
@@ -49,10 +51,11 @@ export function createNpmUpdateClient(options) {
                 timeoutMs,
             });
         },
-        async installExact(version) {
-            if (!isStrictRelease(version))
+        async installExact(version, channel = "latest") {
+            if (!isAllowedChannelVersion(version, channel)) {
                 return { ok: false, reason: "invalid-version" };
-            const result = await runner(npmCommand, buildExactInstallArgs(version), {
+            }
+            const result = await runner(npmCommand, buildExactInstallArgs(version, channel), {
                 timeoutMs: Math.max(timeoutMs, 120000),
                 cwd,
                 env,
@@ -79,6 +82,13 @@ export function createNpmUpdateClient(options) {
     };
 }
 export function parseNpmViewLatest(stdout) {
+    return parseNpmViewDistTag(stdout, "latest");
+}
+/**
+ * `latest` stays stable-only. `next` is explicitly selected by a human and
+ * may legitimately be a SemVer prerelease, but remains an exact version.
+ */
+export function parseNpmViewDistTag(stdout, channel) {
     const trimmed = stdout.trim();
     let value = trimmed;
     try {
@@ -89,11 +99,12 @@ export function parseNpmViewLatest(stdout) {
     }
     if (typeof value !== "string")
         return undefined;
-    return isStrictRelease(value) ? value : undefined;
+    return isAllowedChannelVersion(value, channel) ? value : undefined;
 }
-export function buildExactInstallArgs(version) {
-    if (!isStrictRelease(version))
-        throw new Error(`invalid release version: ${version}`);
+export function buildExactInstallArgs(version, channel = "latest") {
+    if (!isAllowedChannelVersion(version, channel)) {
+        throw new Error(`invalid ${channel} version: ${version}`);
+    }
     return ["install", "-g", `${PACKAGE_NAME}@${version}`, "--no-fund", "--no-audit"];
 }
 export function verifyNpmListVersion(stdout, expectedVersion) {
@@ -106,7 +117,13 @@ export function verifyNpmListVersion(stdout, expectedVersion) {
     }
 }
 export function verifyPathVersion(stdout, expectedVersion) {
-    return stdout.trim() === expectedVersion;
+    // `loop-agent --version` may append a build provenance marker. The release
+    // version itself must still match exactly; accepting no other trailing form
+    // keeps PATH verification bound to the requested stable package.
+    return new RegExp(`^${escapeRegExp(expectedVersion)}(?: \\(build [^)]+\\))?$`).test(stdout.trim());
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 async function proveGlobalNpmInstall(options) {
     const root = await options.runner(options.npmCommand, ["root", "-g"], {
@@ -142,6 +159,11 @@ function isStrictRelease(version) {
     const parsed = semver.parse(version);
     return Boolean(parsed && parsed.prerelease.length === 0);
 }
+function isAllowedChannelVersion(version, channel) {
+    if (channel === "latest")
+        return isStrictRelease(version);
+    return Boolean(semver.valid(version));
+}
 async function runCommand(command, args, options) {
     return new Promise((resolve) => {
         const child = spawn(command, [...args], {

package/dist/task/config-types.js

@@ -147,6 +147,8 @@ export const backendTestConfigSchema = z
     gapDoc: z.string().min(1).optional(),
     /** gap-fill pytest execution scope: only affected items (default) or all eligible. */
     executeScope: z.enum(["affected", "all"]).optional(),
+    /** Backend-test-only workspace mutation control; omitted means Git guard. */
+    workspaceControl: z.enum(["git", "filesystem-only"]).optional(),
 })
     .strict()
     .optional();
@@ -237,5 +239,13 @@ export const taskConfigSchema = z.preprocess((raw) => {
     if ("executor" in obj || "cursorModel" in obj) {
         throw new Error(CURSOR_TASK_FIELD_REMOVED_ERROR);
     }
+    const backendTest = obj.backendTest;
+    if (backendTest &&
+        typeof backendTest === "object" &&
+        !Array.isArray(backendTest) &&
+        "workspaceControl" in backendTest &&
+        obj.taskKind !== "backend-test") {
+        throw new Error("backendTest.workspaceControl is only valid when taskKind is backend-test");
+    }
     return raw;
 }, taskConfigObjectSchema);

package/dist/task/contract/apply.js

@@ -232,8 +232,11 @@ export async function applyTaskContract(input) {
         // Re-parse through schema to ensure full TaskConfig shape for hash stability
         const fullConfig = parseTaskConfigForRuntime(mergedConfig);
         const taskConfigContent = serializeTaskConfigForDisk(fullConfig);
-        const requirementContent = projectRequirementMarkdown(input.draft);
+        const requirementContent = projectRequirementMarkdown(input.draft, input.requirementLedger);
         const constraintsContent = projectConstraintsMarkdown(input.draft);
+        const requirementLedgerContent = input.requirementLedger !== undefined
+            ? `${JSON.stringify(input.requirementLedger, null, 2)}\n`
+            : undefined;
         // Validate references manifest hash if present (do not modify)
         const paths = getTaskPaths(input.repoRoot, input.taskId);
         const manifestText = await readFile(getSourceManifestPath(paths.sourceDir), "utf-8").catch(() => null);
@@ -241,6 +244,7 @@ export async function applyTaskContract(input) {
             requirementBytes: requirementContent,
             constraintsBytes: constraintsContent,
             referenceManifestBytes: manifestText,
+            requirementLedgerBytes: requirementLedgerContent,
         });
         const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
         const canonicalHash = computeCanonicalHash({
@@ -277,6 +281,9 @@ export async function applyTaskContract(input) {
                 constraintsContent,
                 taskConfigContent,
                 contractRef: nextRef,
+                ...(requirementLedgerContent !== undefined
+                    ? { requirementLedgerContent }
+                    : {}),
             },
         });
         await appendRequestLedgerEntry({
@@ -312,6 +319,9 @@ export async function applyTaskContract(input) {
             changedFiles: [
                 "source/需求.md",
                 "source/执行约束.md",
+                ...(requirementLedgerContent !== undefined
+                    ? ["source/requirement-ledger.json"]
+                    : []),
                 "task.json",
                 "contract.json",
             ],

package/dist/task/contract/constants.js

@@ -29,3 +29,5 @@ export const TRANSACTIONS_DIRNAME = TRANSACTIONS_DIR_NAME;
 export const REQUEST_LEDGER_BASENAME = REQUEST_LEDGER_FILE_NAME;
 export const REQUIREMENT_FILE_NAME = "需求.md";
 export const CONSTRAINTS_FILE_NAME = "执行约束.md";
+/** Source fidelity ledger (20260824-frontend-source-fidelity-ledger-v1). */
+export const REQUIREMENT_LEDGER_FILE_NAME = "requirement-ledger.json";

package/dist/task/contract/hash.js

@@ -35,6 +35,9 @@ export function computeSourceHashes(input) {
     if (input.referenceManifestBytes) {
         sourceHashes.referenceManifestSha256 = sha256Utf8(input.referenceManifestBytes);
     }
+    if (input.requirementLedgerBytes) {
+        sourceHashes.requirementLedgerSha256 = sha256Utf8(input.requirementLedgerBytes);
+    }
     return sourceHashes;
 }
 export function refMatchesObserved(ref, observedCanonicalHash) {

package/dist/task/contract/observe.js

@@ -1,6 +1,6 @@
 import { access, readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { CONSTRAINTS_FILE_NAME, CONTRACT_FILE_NAME, REQUIREMENT_FILE_NAME, TRANSACTIONS_DIR_NAME, } from "./constants.js";
+import { CONSTRAINTS_FILE_NAME, CONTRACT_FILE_NAME, REQUIREMENT_FILE_NAME, REQUIREMENT_LEDGER_FILE_NAME, TRANSACTIONS_DIR_NAME, } from "./constants.js";
 import { computeCanonicalHash, computeSourceHashes, computeTaskConfigSha256, } from "./hash.js";
 import { parseTaskContractRef } from "./schema.js";
 import { getTaskPaths } from "../runtime.js";
@@ -33,11 +33,13 @@ export async function loadObservedTaskBytes(repoRoot, taskId) {
     const paths = getTaskPaths(repoRoot, taskId);
     const requirementPath = path.join(paths.sourceDir, REQUIREMENT_FILE_NAME);
     const constraintsPath = path.join(paths.sourceDir, CONSTRAINTS_FILE_NAME);
-    const [requirementBytes, constraintsBytes, taskConfigText, manifestText] = await Promise.all([
+    const requirementLedgerPath = path.join(paths.sourceDir, REQUIREMENT_LEDGER_FILE_NAME);
+    const [requirementBytes, constraintsBytes, taskConfigText, manifestText, requirementLedgerBytes] = await Promise.all([
         readTextIfExists(requirementPath),
         readTextIfExists(constraintsPath),
         readTextIfExists(paths.taskConfigPath),
         readTextIfExists(getSourceManifestPath(paths.sourceDir)),
+        readTextIfExists(requirementLedgerPath),
     ]);
     let taskConfigRaw = null;
     let taskConfigSha256 = null;
@@ -52,6 +54,7 @@ export async function loadObservedTaskBytes(repoRoot, taskId) {
         taskConfigRaw,
         taskConfigSha256,
         referenceManifestBytes: manifestText,
+        requirementLedgerBytes,
         requirementPath,
         constraintsPath,
         taskConfigPath: paths.taskConfigPath,
@@ -164,7 +167,9 @@ export async function observeTaskContractState(repoRoot, taskId) {
             message: error instanceof Error ? error.message : String(error),
         });
     }
-    const observed = await computeObservedCanonicalHashSafe(repoRoot, taskId);
+    const observed = await computeObservedCanonicalHashSafe(repoRoot, taskId, {
+        ref: ref ?? undefined,
+    });
     errors.push(...(observed.errors ?? []));
     if (!ref) {
         return {
@@ -226,7 +231,7 @@ export async function observeTaskContractState(repoRoot, taskId) {
         observationErrors: errors,
     };
 }
-async function computeObservedCanonicalHashSafe(repoRoot, taskId) {
+async function computeObservedCanonicalHashSafe(repoRoot, taskId, options) {
     const errors = [];
     try {
         const bytes = await loadObservedTaskBytes(repoRoot, taskId);
@@ -256,10 +261,26 @@ async function computeObservedCanonicalHashSafe(repoRoot, taskId) {
             }
             return { hash: null, errors };
         }
+        // Legacy compatibility (AC-FIDELITY-004): only include the ledger bytes
+        // when the stored ref actually declares requirementLedgerSha256. A ref
+        // without the ledger field keeps the existing semantics and never
+        // misreports drift for tasks that predate the ledger.
+        const refLedgerHash = options?.ref?.sourceHashes.requirementLedgerSha256 ?? null;
+        if (refLedgerHash && bytes.requirementLedgerBytes === null) {
+            errors.push({
+                code: "MISSING_REQUIREMENT_LEDGER",
+                path: "source/requirement-ledger.json",
+                message: `contract records requirementLedgerSha256 but ${REQUIREMENT_LEDGER_FILE_NAME} is missing`,
+            });
+            return { hash: null, errors };
+        }
         const sourceHashes = computeSourceHashes({
             requirementBytes: bytes.requirementBytes,
             constraintsBytes: bytes.constraintsBytes,
             referenceManifestBytes: bytes.referenceManifestBytes,
+            ...(refLedgerHash
+                ? { requirementLedgerBytes: bytes.requirementLedgerBytes }
+                : {}),
         });
         const hash = computeCanonicalHash({
             sourceHashes,

package/dist/task/contract/paths.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { getTaskPaths } from "../runtime.js";
-import { CONTRACT_JSON_BASENAME, REQUEST_LEDGER_BASENAME, TRANSACTIONS_DIRNAME, } from "./constants.js";
+import { CONTRACT_JSON_BASENAME, REQUIREMENT_LEDGER_FILE_NAME, REQUEST_LEDGER_BASENAME, TRANSACTIONS_DIRNAME, } from "./constants.js";
 export function getTaskContractPaths(repoRoot, taskId) {
     const base = getTaskPaths(repoRoot, taskId);
     return {
@@ -15,5 +15,6 @@ export function getTaskContractPaths(repoRoot, taskId) {
         transactionsDir: path.join(base.taskDir, TRANSACTIONS_DIRNAME),
         requestLedgerPath: path.join(base.taskDir, REQUEST_LEDGER_BASENAME),
         lockPath: path.join(base.taskDir, ".contract.lock"),
+        requirementLedgerPath: path.join(base.sourceDir, REQUIREMENT_LEDGER_FILE_NAME),
     };
 }

package/dist/task/contract/project.js

@@ -1,8 +1,10 @@
 import { canonicalizePathArray, canonicalizeTextProjection, } from "./canonicalize.js";
 /**
  * Project Draft → source/需求.md (deterministic template, projectionVersion=1).
+ * 当携带 ledger 时追加 `## Source ledger` 区块：明确 需求.md 是派生导航视图，
+ * 语义权威为原始 requirement/acceptance 文档与受管 requirement-ledger.json。
  */
-export function projectRequirementMarkdown(draft) {
+export function projectRequirementMarkdown(draft, ledger) {
     const lines = [
         `# 需求：${draft.title}`,
         "",
@@ -62,6 +64,18 @@ export function projectRequirementMarkdown(draft) {
             lines.push(`- [${ref.role}] ${ref.ref}`);
         }
     }
+    if (ledger) {
+        const gateStatus = ledger.stats.unresolvedCount > 0 ||
+            ledger.stats.conflictCount > 0 ||
+            ledger.stats.highRiskUncoveredCount > 0
+            ? "blocked"
+            : "pass";
+        const ledgerLine = ledger.sourcePaths.length > 0
+            ? `source/requirement-ledger.json (${ledger.sourcePaths.length} source document(s))`
+            : "source/requirement-ledger.json";
+        lines.push("", "## Source ledger", "", "> 本文件是派生导航视图，不替代原始 requirement/acceptance 文档。" +
+            " 语义权威为原始文档与 `source/requirement-ledger.json`（确定性切分账本）。", "", `- ledger: ${ledgerLine.length > 160 ? `${ledgerLine.slice(0, 160)}…` : ledgerLine}`, `- inputDigest: ${ledger.inputDigest}`, `- fragments: ${ledger.stats.fragmentCount}`, `- canonical requirements: ${ledger.stats.canonicalRequirementCount}`, `- status: ${gateStatus}`);
+    }
     lines.push("");
     return canonicalizeTextProjection(lines.join("\n"));
 }

package/dist/task/contract/schema.js

@@ -107,6 +107,8 @@ export const taskContractSourceHashesSchema = z
     requirementSha256: sha256Schema,
     constraintsSha256: sha256Schema,
     referenceManifestSha256: sha256Schema.optional(),
+    /** Source fidelity ledger hash; present only when the task binds a ledger. */
+    requirementLedgerSha256: sha256Schema.optional(),
 })
     .strict();
 export const taskContractRefSchema = z

package/dist/task/contract/transaction.js

@@ -21,6 +21,7 @@ export async function runJournaledContractCommit(input) {
     const constraintsRel = `source/${CONSTRAINTS_FILE_NAME}`;
     const taskConfigRel = "task.json";
     const contractRel = CONTRACT_FILE_NAME;
+    const requirementLedgerRel = `source/requirement-ledger.json`;
     const targetSpecs = [
         {
             kind: "requirement",
@@ -46,6 +47,17 @@ export async function runJournaledContractCommit(input) {
             content: input.targets.contractRef,
             isJson: true,
         },
+        ...(input.targets.requirementLedgerContent !== undefined
+            ? [
+                {
+                    kind: "requirement-ledger",
+                    relativePath: requirementLedgerRel,
+                    // Content is already serialized JSON text; stageText avoids double-encoding.
+                    content: input.targets.requirementLedgerContent,
+                    isJson: false,
+                },
+            ]
+            : []),
     ];
     const targetRecords = [];
     for (const spec of targetSpecs) {

package/dist/task/source-prepare/completeness.js

@@ -55,6 +55,25 @@ export function observationBlocksPrepare(state) {
     }
     return null;
 }
+/**
+ * 精确 identity 绑定的人类 resolution 判定（AC-001 / AC-005）：decidedBy==='human'、
+ * decision trim 后非空、sourceRef 与冲突 id 精确匹配三者同时成立才算有效；model/
+ * system 伪造判定、stale sourceRef（不匹配当前冲突 identity）或空/空白 decision 一律
+ * 不解锁。resolution 信息取自 draft 层（不重排流水线，listPrepareGaps 仍先于 ledger
+ * 构建执行）。
+ */
+export function hasValidHumanConflictResolution(draft, conflictId) {
+    for (const resolution of draft.sourceResolutions ?? []) {
+        if (resolution.sourceRef !== conflictId)
+            continue;
+        if (resolution.decidedBy !== "human")
+            continue;
+        if (!resolution.decision?.trim())
+            continue;
+        return true;
+    }
+    return false;
+}
 export function listPrepareGaps(input) {
     const gaps = [];
     const risks = [];
@@ -108,6 +127,12 @@ export function listPrepareGaps(input) {
     }
     if (input.acceptanceConflicts && input.acceptanceConflicts.length > 0) {
         for (const conflict of input.acceptanceConflicts) {
+            // AC-001：有效 human resolution（human + 非空 decision + sourceRef 与冲突 id
+            // 精确匹配）解除该 id 的 legacy blocking gap；无 resolution 或 resolution 不
+            // 满足三条件（AC-005：伪造判定 / stale sourceRef / 空 decision）仍发射阻断。
+            if (hasValidHumanConflictResolution(input.draft, conflict.id)) {
+                continue;
+            }
             gaps.push({
                 code: "ACCEPTANCE_ID_CONFLICT",
                 level: "blocking",
@@ -246,3 +271,166 @@ export function hasBlockingGaps(gaps) {
 export function hasBlockingRisks(risks) {
     return risks.some((risk) => risk.level === "blocking");
 }
+/**
+ * Source fidelity ledger 分级 fail-closed 阻断（AC-003 / AC-FIDELITY-003）：
+ * 高风险未映射/排除、unresolved、冲突返回稳定错误并阻断；低风险 context-only 仅当
+ * 理由完整且独立 reviewer pass 后继续；duplicate 保留全部来源（warning 可见）。
+ * 仅 taskKind 为 frontend-implementation 时全量阻断，其他 taskKind 保持 warning。
+ */
+export function appendLedgerGaps(input) {
+    const { gaps, risks } = input;
+    if (!input.ledgerSummary?.present)
+        return;
+    const blocking = input.taskKind === "frontend-implementation";
+    const level = blocking ? "blocking" : "warning";
+    const summary = input.ledgerSummary;
+    if (summary.unresolvedCount > 0) {
+        const gap = {
+            code: "SOURCE_FIDELITY_UNRESOLVED",
+            level,
+            message: `ledger 有 ${summary.unresolvedCount} 个 unresolved fragment（需人工 sourceResolutions 确认后才可继续）`,
+            details: {
+                fragmentIds: summary.exclusions
+                    .filter((e) => /^REQ-SRC-/.test(e.fragmentId) || e.fragmentId.startsWith("AC-"))
+                    .slice(0, 10)
+                    .map((e) => e.fragmentId),
+            },
+            selfHealing: blocking
+                ? {
+                    action: "reimport-prd",
+                    steps: [
+                        "检查原始 PRD 中无法映射到 canonical AC 的可执行片段（unresolved）",
+                        "补齐/修正 PRD 使每个可执行片段都能绑定 AC，或由人工在 sourceResolutions 中确认排除理由",
+                        "重新 importPrd（同 taskId）后 task advance 重建 ledger",
+                    ],
+                }
+                : undefined,
+        };
+        gaps.push(gap);
+        risks.push({
+            code: "SOURCE_FIDELITY_UNRESOLVED",
+            level: blocking ? "blocking" : "elevated",
+            message: gap.message,
+        });
+    }
+    if (summary.conflictCount > 0) {
+        const gap = {
+            code: "SOURCE_FIDELITY_CONFLICT",
+            level,
+            message: `ledger 检测到 ${summary.conflictCount} 个 AC 文本冲突（同一 ID 不同文本）`,
+            selfHealing: blocking
+                ? {
+                    action: "reimport-prd",
+                    steps: [
+                        "统一同一 AC ID 的文本后重新 importPrd（同 taskId）",
+                        "或由人工在 sourceResolutions 中声明冲突取舍（conflict → decision）",
+                    ],
+                }
+                : undefined,
+        };
+        gaps.push(gap);
+        risks.push({
+            code: "SOURCE_FIDELITY_CONFLICT",
+            level: blocking ? "blocking" : "elevated",
+            message: gap.message,
+        });
+    }
+    if (summary.failureCode === "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED") {
+        const gap = {
+            code: "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+            level,
+            message: "ledger 存在高风险 acceptance 片段未映射到 canonical requirement",
+            selfHealing: blocking
+                ? {
+                    action: "reimport-prd",
+                    steps: [
+                        "为每个未覆盖的高风险片段补齐 canonical AC（或人工 sourceResolutions 确认）",
+                        "重新 importPrd（同 taskId）后 task advance 重建 ledger",
+                    ],
+                }
+                : undefined,
+        };
+        gaps.push(gap);
+        risks.push({
+            code: "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+            level: blocking ? "blocking" : "elevated",
+            message: gap.message,
+        });
+    }
+    for (const error of input.ledgerErrors ?? []) {
+        if (error.code === "SOURCE_FIDELITY_LEDGER_MISSING") {
+            const gap = {
+                code: "SOURCE_FIDELITY_LEDGER_MISSING",
+                level,
+                message: error.message,
+            };
+            gaps.push(gap);
+        }
+        // AC-BLOCK-001：canonical requirement 缺少 fragment/sourceRef 证据、来源引用
+        // 无效、fragment 无效均为 blocking gap（frontend task），保证 prepare/apply
+        // 以稳定码 fail closed（appendLedgerGaps 是 prepare 补洞的唯一入口）。
+        if (error.code === "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED" ||
+            error.code === "SOURCE_FIDELITY_SOURCE_REF_INVALID" ||
+            error.code === "SOURCE_FIDELITY_FRAGMENT_INVALID") {
+            const gap = {
+                code: error.code,
+                level,
+                message: error.message,
+                selfHealing: blocking
+                    ? {
+                        action: "reimport-prd",
+                        steps: [
+                            "检查 PRD 中每个 canonical requirement 是否都有可审计的 fragment/sourceRef 证据",
+                            "补齐缺失的验收标准映射或修正引用后重新 importPrd（同 taskId）",
+                            "重新 importPrd（同 taskId）后 task advance 重建 ledger",
+                        ],
+                    }
+                    : undefined,
+            };
+            gaps.push(gap);
+            risks.push({
+                code: error.code,
+                level: blocking ? "blocking" : "elevated",
+                message: error.message,
+            });
+        }
+        if (error.code === "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED" &&
+            blocking) {
+            // 低风险 context-only 仅独立 reviewer pass 放行；未通过则 frontend 任务阻断。
+            const gap = {
+                code: "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED",
+                level: "blocking",
+                message: error.message,
+                selfHealing: {
+                    action: "reimport-prd",
+                    steps: [
+                        "检查 context-only 片段是否缺少完整排除理由，或由人工在 sourceResolutions 中确认",
+                        "重新 importPrd（同 taskId）后 task advance 重建 ledger 并复核 reviewer 判定",
+                    ],
+                },
+            };
+            gaps.push(gap);
+        }
+    }
+    // 低风险 context-only：记录并提示排除理由/独立 reviewer 要求（不阻断普通任务）。
+    if (summary.contextOnlyCount > 0) {
+        gaps.push({
+            code: "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED",
+            level: "warning",
+            message: `ledger 有 ${summary.contextOnlyCount} 个 context-only fragment（低风险排除；frontend 任务需完整理由且独立 reviewer pass）`,
+            details: {
+                fragmentIds: summary.exclusions
+                    .filter((e) => e.fragmentId.startsWith("REQ-SRC-"))
+                    .slice(0, 10)
+                    .map((e) => e.fragmentId),
+            },
+        });
+    }
+    if (summary.duplicateCount > 0) {
+        gaps.push({
+            code: "SOURCE_FIDELITY_DUPLICATE_PRESERVED",
+            level: "warning",
+            message: `ledger 保留 ${summary.duplicateCount} 个 duplicate fragment（duplicate 保留全部来源）`,
+        });
+    }
+}