@tea-agent/loop-agent 0.39.0-beta.7 → 0.39.0-beta.9

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 保留全部来源）`,
+        });
+    }
+}

package/dist/task/source-prepare/fragment-inventory.js

@@ -0,0 +1,477 @@
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Deterministic fragment inventory (AC-001 / AC-FIDELITY-001)
+// 对 .md/.markdown/.txt 按标题、段落、列表项、checklist、表格行确定性切分。
+// 稳定 fragment ID：显式 AC ID 原样保留（含 `#### AC-*` 标题式）；无 ID 片段生成
+// 跨文档稳定 REQ-SRC-*（基于 path+行号+文本的确定性哈希，与文档枚举顺序无关，
+// 消除 per-document counter reset 碰撞）。不按文档前 24K 字符裁剪——尾部片段仍
+// 进入 inventory（覆盖统计证明）。
+// ---------------------------------------------------------------------------
+export const FRAGMENT_ID_PREFIX = "REQ-SRC";
+/** 生成 fragment ID 的合法形态（防伪造：拒绝自由格式 ID）。 */
+export const FRAGMENT_ID_PATTERN = /^(?:AC(?:-[A-Z0-9]+)+|REQ-SRC-[A-Z0-9-]+)$/;
+const ACCEPTANCE_HEADING_RE = /(?:^|\s)(?:验收标准|acceptance criteria|acceptance|完成标准|完成定义|验收条件|验收准则|dod|definition of done|验收)(?:\s|$)/iu;
+const CONSTRAINT_HEADING_RE = /(?:^|\s)(?:约束|constraints|invariants|不变式)(?:\s|$)/iu;
+const NON_GOAL_HEADING_RE = /(?:^|\s)(?:非目标|out of scope|non-goals|non goals)(?:\s|$)/iu;
+const OBJECTIVE_HEADING_RE = /(?:^|\s)(?:目标|objective|问题与目标|业务目标|需求概述)(?:\s|$)/iu;
+/** 可执行片段启发式（AC 风格/祈使语气）：命中则不可按 context-only 降级。 */
+const EXECUTABLE_HINT_RE = /(?:必须|应当|应支持|需要|需|不得|should|must|shall|will|require|support|implement|provide|ensure|verify|当.*?时|when.*?then)/iu;
+/** 显式 AC 式 ID 前缀：AC-001 / AC-FE-001 / AC-FE-INS-001 等（允许 bullet 标记后空格
+ * 与 checklist 勾选框）。收紧解析（AC-001 / AC-HARD-001）：AC 后必须跟分隔符
+ * （-/_）+ 大写字母/数字 id 形态（含可选 FE/BE/UI/API 作用域前缀与 V4 `#### AC-*`
+ * 标题归属）；`## Acceptance Criteria` / `## Acceptance` / Ac 开头普通单词永不产生
+ * 伪造 id（ACCEPTANCE 类 id 全量消失）。捕获组 1 = AC id，捕获组 2 = 余下文本。 */
+const EXPLICIT_AC_ID_RE = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(AC(?:[-_](?:FE|BE|UI|API))?[-_][A-Z0-9]+(?:[-_][A-Z0-9]+)*)\s*[:：]?\s*(.*)$/iu;
+/** 显式 AC 标题式：`#### AC-FE-001 Save nickname` / `### AC-001：正文`。
+ * AC 后必须跟分隔符（-/_）+ id 形态；普通单词（Acceptance Criteria / Acceptance）
+ * 永不匹配，按 ACCEPTANCE_HEADING_RE 章节分类生成稳定 REQ-SRC-* 片段。
+ * 捕获组 1 = AC id，捕获组 2 = 标题余下文本。 */
+const EXPLICIT_AC_HEADING_RE = /^\s*(AC(?:[-_](?:FE|BE|UI|API))?[-_][A-Z0-9]+(?:[-_][A-Z0-9]+)*)\s*[:：]?\s*(.*)$/iu;
+/** Markdown 表格数据行（非分隔行）。 */
+const TABLE_DATA_ROW_RE = /^\s*\|.*\|\s*$/;
+const TABLE_SEPARATOR_ROW_RE = /^\s*\|[\s:|-]+\|\s*$/;
+/** 表格表头行：数据行且下一行是分隔行（`| 列 | 列 |` + `| --- | --- |`）。 */
+function isTableHeaderRow(line, nextLine) {
+    return isTableDataRow(line) && TABLE_SEPARATOR_ROW_RE.test(nextLine.trim());
+}
+/** 表格行首格显式 AC ID：`| AC-001 | 订单列表加载完成 |` → id=AC-001, rest=订单列表加载完成。 */
+function matchTableRowAcId(line) {
+    const trimmed = line.trim().replace(/^\|/, "");
+    const cells = trimmed.split("|");
+    const first = cells[0]?.trim() ?? "";
+    const idMatch = EXPLICIT_AC_HEADING_RE.exec(first);
+    if (!idMatch)
+        return null;
+    const id = (idMatch[1] ?? "").trim().toUpperCase().replace(/_/g, "-");
+    if (!id)
+        return null;
+    const rest = cells
+        .slice(1)
+        .join("|")
+        .replace(/\|\s*$/, "")
+        .trim();
+    return { id, rest: rest || id };
+}
+export function sha256Text(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function normalizeFragmentText(text) {
+    return text
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function matchExplicitAcId(line) {
+    const match = EXPLICIT_AC_ID_RE.exec(line.trim());
+    if (!match)
+        return null;
+    const rawId = match[1] ?? "";
+    const id = rawId.trim().toUpperCase().replace(/_/g, "-");
+    if (!id)
+        return null;
+    return { id, rest: (match[2] ?? "").trim() };
+}
+/** V4 显式 AC 标题式匹配：`#### AC-FE-001 Save nickname` → id=AC-FE-001, rest=Save nickname。 */
+export function matchExplicitAcHeading(headingText) {
+    const match = EXPLICIT_AC_HEADING_RE.exec(headingText.trim());
+    if (!match)
+        return null;
+    const rawId = match[1] ?? "";
+    const id = rawId.trim().toUpperCase().replace(/_/g, "-");
+    if (!id)
+        return null;
+    return { id, rest: (match[2] ?? "").trim() };
+}
+function isAtxHeading(line) {
+    const match = /^(#{1,6})\s+(.+?)\s*$/u.exec(line);
+    if (!match)
+        return null;
+    return { level: match[1].length, text: match[2].trim() };
+}
+function isListItem(line) {
+    return /^\s*(?:[-*+]|\d+[.)])\s+(?:\[(?: |x|X)\]\s+)?/.test(line);
+}
+function isTableDataRow(line) {
+    const trimmed = line.trim();
+    return TABLE_DATA_ROW_RE.test(trimmed) && !TABLE_SEPARATOR_ROW_RE.test(trimmed);
+}
+function classifySectionHeading(headingPath) {
+    const normalized = headingPath.toLowerCase();
+    if (ACCEPTANCE_HEADING_RE.test(normalized))
+        return "acceptance";
+    if (CONSTRAINT_HEADING_RE.test(normalized))
+        return "constraint";
+    if (NON_GOAL_HEADING_RE.test(normalized))
+        return "non-goal";
+    if (OBJECTIVE_HEADING_RE.test(normalized))
+        return "objective";
+    return "other";
+}
+/**
+ * 确定性生成 fragment ID：REQ-SRC-<sha256(path+行号+文本) 前 12 位大写>。
+ * 与文档枚举顺序无关（跨文档不碰撞、重排不换 ID），相同输入恒等复现。
+ */
+export function generatedFragmentId(pathValue, lineRange, text) {
+    const digest = sha256Text(`${pathValue}\u0000${lineRange.start}\u0000${lineRange.end}\u0000${text}`);
+    return `${FRAGMENT_ID_PREFIX}-${digest.slice(0, 12).toUpperCase()}`;
+}
+/**
+ * 将单个文档切分为标题段落（section），再按列表项/段落/表格行切分为原始片段。
+ * 完全确定性：相同输入总是产出相同片段序列。generated ID 使用跨文档稳定哈希，
+ * 不依赖文档内自增 counter（消除多文档 counter reset 碰撞）。
+ */
+export function splitDocumentIntoFragments(doc) {
+    const normalized = doc.content.replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    const sections = [];
+    const headingStack = [];
+    let current = null;
+    const flushSection = (endLine) => {
+        if (!current)
+            return;
+        current.endLine = Math.max(current.startLine, endLine);
+        current.lines = lines.slice(current.startLine - 1, Math.min(current.endLine, lines.length));
+        sections.push(current);
+        current = null;
+    };
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        const heading = isAtxHeading(line);
+        if (heading) {
+            flushSection(index - 1);
+            while (headingStack.length > 0 &&
+                headingStack[headingStack.length - 1].level >= heading.level) {
+                headingStack.pop();
+            }
+            headingStack.push({ level: heading.level, text: heading.text });
+            current = {
+                headingPath: headingStack.map((h) => h.text).join(" > "),
+                level: heading.level,
+                startLine: index + 1,
+                endLine: index + 1,
+                lines: [],
+            };
+            continue;
+        }
+        if (!current) {
+            current = {
+                headingPath: "",
+                level: 0,
+                startLine: index + 1,
+                endLine: index + 1,
+                lines: [],
+            };
+        }
+    }
+    flushSection(lines.length);
+    const rawFragments = [];
+    for (const section of sections) {
+        // V4 显式 AC 标题（`#### AC-*`）本身即验收段：标题行的 ID 原样保留。
+        const lastHeadingSegment = section.headingPath.split(" > ").pop() ?? section.headingPath;
+        const explicitSectionAc = matchExplicitAcHeading(lastHeadingSegment);
+        const sectionKind = classifySectionHeading(section.headingPath);
+        const effectiveKind = explicitSectionAc ? "acceptance" : sectionKind;
+        const bodyStart = section.headingPath
+            ? section.startLine + (explicitSectionAc ? 0 : 1)
+            : section.startLine;
+        const bodyEnd = section.endLine;
+        const bodyLines = lines.slice(Math.max(0, bodyStart - 1), Math.min(bodyEnd, lines.length));
+        // 当前验收章节内最近的显式 AC ID（V4 标题或 AC 条目），正文片段继承它。
+        let pendingAcId = null;
+        const emit = (fragment) => {
+            const explicit = fragment.explicitId ?? null;
+            let id = explicit;
+            if (!id) {
+                id = generatedFragmentId(doc.path, fragment.lineRange, fragment.text);
+            }
+            rawFragments.push({
+                id,
+                path: doc.path,
+                headingPath: fragment.headingPath,
+                lineRange: fragment.lineRange,
+                text: fragment.text,
+                ...(explicit
+                    ? {}
+                    : fragment.inheritAcId && pendingAcId
+                        ? { explicitAcId: pendingAcId }
+                        : {}),
+            });
+        };
+        if (explicitSectionAc) {
+            // 标题式 AC 段：标题行本身是一个 acceptance 片段（ID 原样保留）。
+            pendingAcId = explicitSectionAc.id;
+            emit({
+                headingPath: section.headingPath,
+                lineRange: { start: section.startLine, end: section.startLine },
+                text: explicitSectionAc.rest || explicitSectionAc.id,
+                explicitId: explicitSectionAc.id,
+            });
+        }
+        if (effectiveKind === "acceptance") {
+            // acceptance 章节：每个列表项/checklist/AC 标题行/表格数据行 = 一个片段。
+            let paragraphStart = null;
+            const flushParagraph = (endLine) => {
+                if (paragraphStart === null)
+                    return;
+                const text = lines
+                    .slice(paragraphStart - 1, Math.min(endLine, lines.length))
+                    .map((line) => line.trim())
+                    .filter(Boolean)
+                    .join(" ")
+                    .trim();
+                if (text) {
+                    emit({
+                        headingPath: section.headingPath,
+                        lineRange: { start: paragraphStart, end: Math.max(paragraphStart, endLine) },
+                        text,
+                        inheritAcId: true,
+                    });
+                }
+                paragraphStart = null;
+            };
+            for (let index = bodyStart; index <= bodyEnd; index += 1) {
+                const line = lines[index - 1] ?? "";
+                const trimmed = line.trim();
+                if (!trimmed) {
+                    flushParagraph(index - 1);
+                    continue;
+                }
+                if (TABLE_SEPARATOR_ROW_RE.test(trimmed)) {
+                    // 表格分隔行不进入 inventory。
+                    flushParagraph(index - 1);
+                    continue;
+                }
+                const heading = isAtxHeading(trimmed);
+                if (heading) {
+                    flushParagraph(index - 1);
+                    const explicit = matchExplicitAcHeading(heading.text);
+                    if (explicit) {
+                        pendingAcId = explicit.id;
+                        emit({
+                            headingPath: section.headingPath,
+                            lineRange: { start: index, end: index },
+                            text: explicit.rest || explicit.id,
+                            explicitId: explicit.id,
+                        });
+                    }
+                    else {
+                        pendingAcId = null;
+                    }
+                    continue;
+                }
+                if (isTableDataRow(trimmed)) {
+                    const nextLine = lines[index] ?? "";
+                    if (isTableHeaderRow(trimmed, nextLine)) {
+                        // 表头行（后随分隔行）不进入 inventory。
+                        flushParagraph(index - 1);
+                        continue;
+                    }
+                    flushParagraph(index - 1);
+                    const rowExplicit = matchTableRowAcId(trimmed);
+                    emit({
+                        headingPath: section.headingPath,
+                        lineRange: { start: index, end: index },
+                        text: rowExplicit ? rowExplicit.rest : trimmed,
+                        explicitId: rowExplicit?.id,
+                        ...(rowExplicit ? {} : { inheritAcId: true }),
+                    });
+                    continue;
+                }
+                if (isListItem(trimmed)) {
+                    flushParagraph(index - 1);
+                    const explicit = matchExplicitAcId(trimmed);
+                    // 列表项自包含：显式 AC ID 只属于该项，不改变 heading 作用域
+                    // （pendingAcId 仅由 V4 `#### AC-*` 标题设置）。
+                    const text = explicit
+                        ? explicit.rest
+                        : trimmed.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, "");
+                    if (text.trim()) {
+                        emit({
+                            headingPath: section.headingPath,
+                            lineRange: { start: index, end: index },
+                            text: text.trim(),
+                            explicitId: explicit?.id,
+                            ...(explicit ? {} : { inheritAcId: true }),
+                        });
+                    }
+                    continue;
+                }
+                if (paragraphStart === null)
+                    paragraphStart = index;
+            }
+            flushParagraph(bodyEnd);
+            continue;
+        }
+        // 非 acceptance 章节：连续非空行 = 一个段落片段（空行分隔）；表格数据行独立成片。
+        let paragraphStart = null;
+        const flushParagraph = (endLine) => {
+            if (paragraphStart === null)
+                return;
+            const text = lines
+                .slice(paragraphStart - 1, Math.min(endLine, lines.length))
+                .map((line) => line.trim())
+                .filter(Boolean)
+                .join(" ")
+                .trim();
+            if (text) {
+                emit({
+                    headingPath: section.headingPath,
+                    lineRange: { start: paragraphStart, end: Math.max(paragraphStart, endLine) },
+                    text,
+                });
+            }
+            paragraphStart = null;
+        };
+        for (let index = bodyStart; index <= bodyEnd; index += 1) {
+            const line = lines[index - 1] ?? "";
+            const trimmed = line.trim();
+            if (!trimmed) {
+                flushParagraph(index - 1);
+                continue;
+            }
+            if (isAtxHeading(trimmed)) {
+                flushParagraph(index - 1);
+                continue;
+            }
+            if (TABLE_SEPARATOR_ROW_RE.test(trimmed)) {
+                flushParagraph(index - 1);
+                continue;
+            }
+            if (isTableDataRow(trimmed)) {
+                const nextLine = lines[index] ?? "";
+                if (isTableHeaderRow(trimmed, nextLine)) {
+                    flushParagraph(index - 1);
+                    continue;
+                }
+                flushParagraph(index - 1);
+                emit({
+                    headingPath: section.headingPath,
+                    lineRange: { start: index, end: index },
+                    text: trimmed,
+                });
+                continue;
+            }
+            if (paragraphStart === null)
+                paragraphStart = index;
+        }
+        flushParagraph(bodyEnd);
+    }
+    return rawFragments;
+}
+/**
+ * 对多个原始文档确定性切分并做 disposition 分类（AC-001）。
+ * 每个非空有效片段携带稳定 fragment ID、原始路径、标题路径、行号、原文哈希、
+ * 分级风险与且仅一个 disposition。duplicate 保留全部来源。文档先按 path 排序，
+ * 使 duplicate 判定与文档枚举顺序无关（同一输入恒等复现）。
+ */
+export function buildFragmentInventory(input) {
+    const sortedDocuments = [...input.documents].sort((a, b) => a.path.localeCompare(b.path));
+    const fragments = [];
+    for (const doc of sortedDocuments) {
+        fragments.push(...splitDocumentIntoFragments(doc));
+    }
+    const canonicalById = new Map(input.canonicalRequirements.map((req) => [req.id, req.text]));
+    const canonicalTextSet = new Set(input.canonicalRequirements.map((req) => normalizeFragmentText(req.text)));
+    const seenText = new Map();
+    const records = fragments.map((fragment) => {
+        const text = normalizeFragmentText(fragment.text);
+        const sectionKind = classifySectionHeading(fragment.headingPath);
+        // 切分器已把显式 AC ID 放入 fragment.id 并从文本剥离前缀；此处从 id 恢复。
+        const explicitIdFromId = /^AC(?:-[A-Z0-9]+)+$/iu.test(fragment.id)
+            ? fragment.id
+            : null;
+        const explicit = explicitIdFromId
+            ? { id: explicitIdFromId, rest: fragment.text }
+            : matchExplicitAcId(fragment.text);
+        // V4 标题/条目下正文继承的显式 AC ID（不生成取代它的 REQ-SRC-*）。
+        const inherited = !explicit && fragment.explicitAcId
+            ? { id: fragment.explicitAcId, rest: fragment.text }
+            : null;
+        const effectiveExplicit = explicit ?? inherited;
+        const mappedIds = [];
+        if (effectiveExplicit && canonicalById.has(effectiveExplicit.id)) {
+            mappedIds.push(effectiveExplicit.id);
+        }
+        else if (effectiveExplicit && !canonicalById.has(effectiveExplicit.id)) {
+            // 显式 AC ID 但不在 canonical 集合：按文本匹配兜底，仍不中则 unresolved。
+            if (canonicalTextSet.has(text)) {
+                for (const req of input.canonicalRequirements) {
+                    if (normalizeFragmentText(req.text) === text) {
+                        mappedIds.push(req.id);
+                    }
+                }
+            }
+        }
+        else if (canonicalTextSet.has(text)) {
+            for (const req of input.canonicalRequirements) {
+                if (normalizeFragmentText(req.text) === text) {
+                    mappedIds.push(req.id);
+                }
+            }
+        }
+        let disposition;
+        let reason;
+        if (effectiveExplicit && canonicalById.has(effectiveExplicit.id) && mappedIds.length === 0) {
+            disposition = "acceptance";
+            reason = `explicit id ${effectiveExplicit.id} declared in source but canonical requirement has no fragment text match`;
+        }
+        else if (sectionKind === "acceptance" || effectiveExplicit) {
+            disposition = mappedIds.length > 0 ? "acceptance" : "unresolved";
+            if (disposition === "unresolved") {
+                reason =
+                    effectiveExplicit && !canonicalById.has(effectiveExplicit.id)
+                        ? `explicit AC id ${effectiveExplicit.id} not present in canonical requirements`
+                        : "acceptance fragment without a canonical requirement mapping";
+            }
+        }
+        else if (sectionKind === "objective") {
+            disposition = "requirement";
+        }
+        else if (sectionKind === "constraint") {
+            disposition = "constraint";
+        }
+        else if (sectionKind === "non-goal") {
+            disposition = "non-goal";
+        }
+        else {
+            // Non-goal/constraint/acceptance/objective sections are classified
+            // above. An "other" section (背景 / 概述 / 说明 …) is contextual
+            // description, not an executable requirement: even when it mentions
+            // implementation verbs ("需要", "渲染", "组件"), it must not be
+            // promoted to a high-risk unresolved executable fragment — that
+            // blocks PRDs whose 背景 prose happens to use such words (merge
+            // regression: "需要一个小组件" was flagged executable via 需要).
+            // Explicit AC ids are already handled by the branches above, so
+            // this branch is always contextual.
+            disposition = "context-only";
+            reason = "context-only fragment; excluded from canonical requirement coverage";
+        }
+        const priorId = seenText.get(text);
+        if (priorId) {
+            disposition = "duplicate";
+            reason = `duplicate of fragment ${priorId} (duplicate 保留全部来源)`;
+        }
+        else if (!priorId && text) {
+            seenText.set(text, fragment.id);
+        }
+        const risk = disposition === "context-only" || disposition === "duplicate"
+            ? "low"
+            : "high";
+        return {
+            id: fragment.id,
+            path: fragment.path,
+            headingPath: fragment.headingPath,
+            lineRange: fragment.lineRange,
+            sha256: sha256Text(fragment.text),
+            risk,
+            disposition,
+            ...(reason ? { reason } : {}),
+            canonicalRequirementIds: mappedIds,
+        };
+    });
+    return { fragments, records, documents: sortedDocuments };
+}