@longzai-intelligence-issues/ledger 0.0.2 → 0.0.4

package/src/migrate/migrate-legacy.core.ts

@@ -2,8 +2,8 @@
  * migrate-legacy 纯变换核（无 IO，可测性单一来源）
  *
  * 五方言解析（含表格）→ 字段别名 → pre-emoji 状态词规范化 → H1 编号规范 →
- * 处置段标题链对齐 → 必填元信息回填。全部变换可幂等重放，变换台账逐条记录，
- * 供命令层零丢失守卫与人工复核消费。
+ * 处置段标题链对齐 → 必填元信息回填 → 体首残留元信息块吸收与键去重收敛。
+ * 全部变换可幂等重放，变换台账逐条记录，供命令层零丢失守卫与人工复核消费。
  */
 
 import { parseHeaderDialect } from '@/normalize/normalize-header.commands';
@@ -12,9 +12,12 @@ import {
   classifyStatusLine,
   DISPOSITION_PLACEHOLDER_PATTERN,
   DISPOSITION_PLACEHOLDER_WINDOW_LINES,
-  LEGACY_STATUS_VOCABULARY,
 } from '@/parser/format.utils';
 
+import { backfillRequiredFields } from './migrate-legacy.backfill';
+import { absorbLeadingMetadata, convergeDuplicateFields } from './migrate-legacy.converge';
+import { canonicalizeH1, canonicalizeStatusValue, cleanValue } from './migrate-legacy.vocab';
+
 /**
  * 单文件迁移变换台账条目
  */
@@ -31,7 +34,9 @@ export type MigrationTransformation = {
     | 'h1-numbered'
     | 'disposition-renamed'
     | 'disposition-appended'
-    | 'required-backfilled';
+    | 'required-backfilled'
+    | 'header-converged'
+    | 'duplicate-field-converged';
 
   /**
    * 变换说明（原值 → 新值）
@@ -62,6 +67,11 @@ export type MigrateCoreResult = {
    * 变换台账（rewritten 时非空）
    */
   transformations: MigrationTransformation[];
+
+  /**
+   * 来源让位标记（回填缺省让位原始语义——守卫对来源键放行依据）
+   */
+  sourceReplaced: boolean;
 };
 
 /**
@@ -101,241 +111,6 @@ export type MigrateCoreOptions = {
   status?: 'red' | 'green';
 };
 
-/**
- * 状态词匹配产物
- */
-type StatusWordMatch = {
-  /**
-   * 词表档位
-   */
-  tier: 'green' | 'red' | 'deferred' | 'canceled' | 'inProgress' | 'frozen';
-
-  /**
-   * 命中词
-   */
-  word: string;
-};
-
-/**
- * 状态值规范化产物
- */
-type CanonicalStatusValue = {
-  /**
-   * 规范状态值（五态灯位 + 溯源括注）
-   */
-  value: string;
-
-  /**
-   * 词表档位
-   */
-  tier: StatusWordMatch['tier'];
-
-  /**
-   * 命中词（原词溯源）
-   */
-  word: string;
-};
-
-/**
- * 清理字段值（去首尾空白与粗体星号——覆盖三种历史形态：整体包裹 `**值**`、
- * 前导无尾随 `**值`、词中包裹 `**词**（括注）`）
- *
- * @param value - 原值
- * @returns 清理后值
- */
-export function cleanValue(value: string): string {
-  return value
-    .trim()
-    .replace(/^\*\*/, '')
-    .replace(/\*\*$/, '')
-    .replace(/\*\*(?=[（(])/, '')
-    .trim();
-}
-
-/**
- * 在状态值中匹配 pre-emoji 词表
- *
- * @param value - 清理后的状态值
- * @returns 命中档位与词；未命中为 null
- */
-function matchStatusWord(value: string): StatusWordMatch | null {
-  /**
-   * 档位遍历序（frozen 最先——冻结态优先识别并拒绝迁移）
-   */
-  const tiers: StatusWordMatch['tier'][] = [
-    'frozen',
-    'green',
-    'deferred',
-    'canceled',
-    'inProgress',
-    'red',
-  ];
-
-  for (const tier of tiers) {
-    for (const word of LEGACY_STATUS_VOCABULARY[tier]) {
-      if (value.startsWith(word)) {
-        return { tier, word };
-      }
-    }
-  }
-
-  return null;
-}
-
-/**
- * 状态值切分产物（首个括注内容与词后剩余文本）
- */
-type StatusValueSplit = {
-  /**
-   * 首个括注内容（无括注为空串）
-   */
-  paren: string;
-
-  /**
-   * 括注后的剩余文本
-   */
-  rest: string;
-};
-
-/**
- * 提取状态值中的首个括注与其余文本
- *
- * @param value - 清理后的状态值
- * @param word - 命中词
- * @returns 括注内容与词后剩余文本
- */
-function splitStatusValue(value: string, word: string): StatusValueSplit {
-  /**
-   * 词后文本
-   */
-  const afterWord = value.slice(word.length).trim();
-
-  /**
-   * 首个括注匹配
-   */
-  const parenMatch = /^[（(]([^）)]*)[）)]/.exec(afterWord);
-
-  if (parenMatch === null) {
-    return { paren: '', rest: afterWord };
-  }
-
-  return {
-    paren: (parenMatch[1] ?? '').trim(),
-    rest: afterWord.slice((parenMatch[0] ?? '').length).trim(),
-  };
-}
-
-/**
- * 规范化状态值（pre-emoji 词 → 五态灯位；原词与括注零丢失保留）
- *
- * @param value - 清理后的状态值
- * @returns 规范值与档位；不可机械迁移为 null（须人工）
- */
-export function canonicalizeStatusValue(value: string): CanonicalStatusValue | null {
-  /**
-   * 词表命中
-   */
-  const match = matchStatusWord(value);
-
-  if (match === null) {
-    return null;
-  }
-
-  /**
-   * 括注与剩余文本
-   */
-  const { paren, rest } = splitStatusValue(value, match.word);
-
-  /**
-   * 括注段收集器（顺序：括注 → 剩余 → 原词溯源）
-   */
-  const parts = [paren, rest, `原「${match.word}」`].filter((part) => part !== '');
-
-  switch (match.tier) {
-    case 'frozen':
-      return null;
-
-    case 'green':
-      return { value: `🟢 已处置（${parts.join('；')}）`, tier: match.tier, word: match.word };
-
-    case 'red':
-      return { value: `🔴 待处理（${parts.join('；')}）`, tier: match.tier, word: match.word };
-
-    case 'deferred':
-      return {
-        value: `🔴 待处理（${[paren === '' ? '延期' : paren, `原「${match.word}」`].join('；')}）`,
-        tier: match.tier,
-        word: match.word,
-      };
-
-    case 'canceled':
-      return paren === '' || paren.length < 4
-        ? null
-        : { value: `⚫ 已取消（${parts.join('；')}）`, tier: match.tier, word: match.word };
-
-    case 'inProgress':
-      return paren.length < 4
-        ? null
-        : { value: `🟡 处理中（${paren}）`, tier: match.tier, word: match.word };
-  }
-}
-
-/**
- * 严重程度/中文优先级 → P 档位映射
- *
- * @param value - 原值（高/中/低或 P1/P2/P3）
- * @returns P 档位；不可映射为 null
- */
-export function mapPriorityValue(value: string): 'P1' | 'P2' | 'P3' | null {
-  /**
-   * 严重程度中文档位与 P 档位的等价映射表（P 档位原样透传）
-   */
-  const table: Record<string, 'P1' | 'P2' | 'P3'> = {
-    高: 'P1',
-    中: 'P2',
-    低: 'P3',
-    P1: 'P1',
-    P2: 'P2',
-    P3: 'P3',
-  };
-
-  return table[cleanValue(value)] ?? null;
-}
-
-/**
- * H1 规范化产物
- */
-type CanonicalH1 = {
-  /**
-   * 规范标题行（`# NNNN - 标题核心`）
-   */
-  line: string;
-
-  /**
-   * 标题核心（剥离既有编号与分隔符变体后的标题文本）
-   */
-  titleCore: string;
-};
-
-/**
- * H1 标题规范化：`# NNNN - 标题`（剥离既有编号与分隔符变体）
- *
- * @param h1 - 原一级标题行
- * @param number - 文件名编号
- * @returns 规范标题行与标题核心
- */
-export function canonicalizeH1(h1: string, number: string): CanonicalH1 {
-  /**
-   * 标题核心（去行首 `# ` 与既有编号 + 分隔符变体）
-   */
-  const titleCore = h1
-    .replace(/^#\s+/, '')
-    .replace(new RegExp(`^${number}\\s*(?:[-·.．：:]\\s*|\\s*)`), '')
-    .trim();
-
-  return { line: `# ${number} - ${titleCore}`, titleCore };
-}
-
 /**
  * 处置段候选标题链（apex-energy-ktv 全量段名词频盘点驱动；验证族 > 治理记录族 >
  * 变更/修复族。计划性段名（治理方案/治理方向/修复方向/处置方向）不属处置记录，排除）
@@ -485,6 +260,218 @@ const HEADER_FIELD_ORDER: readonly string[] = [
   '阻塞',
 ];
 
+/**
+ * 执行单文档纯变换
+ *
+ * @param raw - 文档全文
+ * @param options - 迁移选项
+ * @returns 纯变换产物
+ */
+
+/**
+ * 超长状态拆分探测入参
+ */
+type LongStatusProbeInput = {
+  /**
+   * 显式灯位注入标记（注入通道不适用长度门）
+   */
+  injected: boolean;
+
+  /**
+   * 已规范状态标记（已规范值不适用长度门）
+   */
+  alreadyCanonical: boolean;
+
+  /**
+   * 原状态值
+   */
+  originalStatus: string;
+};
+
+/**
+ * 超长状态拆分探测产物
+ */
+type LongStatusSplit = {
+  /**
+   * 全文说明（落处置摘要字段）
+   */
+  summary: string;
+
+  /**
+   * 短规范状态（词表档位 + 原词溯源括注）
+   */
+  canonical: string;
+
+  /**
+   * 拆分档位（红/绿——处置段对齐判定依据）
+   */
+  tier: 'green' | 'red';
+};
+
+/**
+ * 超长状态拆分探测（「状态词 + 长说明」结构——词表命中拆分为短规范状态 +
+ * 处置摘要全文；未命中返回 'manual' 交人工）
+ *
+ * @param input - 探测入参
+ * @returns 拆分产物；'manual' 表示交人工；null 表示未触发（长度未超限）
+ */
+function probeLongStatusSplit(input: LongStatusProbeInput): LongStatusSplit | 'manual' | null {
+  if (input.injected || input.alreadyCanonical || input.originalStatus.length <= 80) {
+    return null;
+  }
+
+  /**
+   * 词表命中探测（值清理后取前缀——消除说明散文对 startsWith 匹配的干扰）
+   */
+  const probe = canonicalizeStatusValue(cleanValue(input.originalStatus).slice(0, 12));
+
+  if (
+    probe === null ||
+    (probe.tier !== 'green' && probe.tier !== 'red' && probe.tier !== 'deferred')
+  ) {
+    return 'manual';
+  }
+
+  /**
+   * 拆分档位
+   */
+  const tier: 'green' | 'red' = probe.tier === 'green' ? 'green' : 'red';
+
+  return {
+    summary: cleanValue(input.originalStatus.replace(/\*\*/g, '')),
+    canonical: `${CANONICAL_STATUS_LABELS[tier]}（原「${probe.word}」）`,
+    tier,
+  };
+}
+
+/**
+ * 来源与所属域回填入参
+ */
+type TailBackfillInput = {
+  /**
+   * 头部字段工作副本（原地回填）
+   */
+  fields: Array<{ key: string; value: string }>;
+
+  /**
+   * 变换台账
+   */
+  transformations: MigrationTransformation[];
+
+  /**
+   * 来源回填缺省文案
+   */
+  defaultSource?: string;
+
+  /**
+   * 所属域（scope title）
+   */
+  scopeTitle: string;
+};
+
+/**
+ * 来源与所属域回填产物
+ */
+type TailBackfillResult = {
+  /**
+   * skip 语（来源缺省未给交人工时非空）
+   */
+  skipMessage: string | null;
+};
+
+/**
+ * 执行来源与所属域回填
+ *
+ * @param input - 回填入参
+ * @returns 回填产物（skipMessage 非空即调用方应 skipped 返回）
+ */
+function backfillSourceAndDomain(input: TailBackfillInput): TailBackfillResult {
+  if (!input.fields.some((field) => field.key === '来源')) {
+    if (input.defaultSource === undefined) {
+      return { skipMessage: '缺来源且未给回填缺省——交人工' };
+    }
+
+    input.fields.push({ key: '来源', value: input.defaultSource });
+
+    input.transformations.push({ kind: 'required-backfilled', detail: '来源 ← 缺省回填' });
+  }
+
+  /**
+   * 所属域回填（scope title）
+   */
+  if (!input.fields.some((field) => field.key === '所属域')) {
+    input.fields.push({ key: '所属域', value: input.scopeTitle });
+
+    input.transformations.push({
+      kind: 'required-backfilled',
+      detail: `所属域 ← ${input.scopeTitle}`,
+    });
+  }
+
+  return { skipMessage: null };
+}
+
+/**
+ * H1 规范化入参
+ */
+type HeaderH1Input = {
+  /**
+   * 文档行数组
+   */
+  lines: string[];
+
+  /**
+   * 文件名编号
+   */
+  number: string;
+
+  /**
+   * 变换台账
+   */
+  transformations: MigrationTransformation[];
+};
+
+/**
+ * H1 规范化产物
+ */
+type HeaderH1 = {
+  /**
+   * 规范标题行
+   */
+  line: string;
+};
+
+/**
+ * 执行 H1 规范化（`# NNNN - 标题`；无一级标题返回 null 交人工）
+ *
+ * @param input - 规范化入参
+ * @returns 规范化产物；null 表示无一级标题
+ */
+function canonicalizeHeaderH1(input: HeaderH1Input): HeaderH1 | null {
+  /**
+   * 一级标题行下标
+   */
+  const h1Index = input.lines.findIndex((line) => line.startsWith('# '));
+
+  if (h1Index === -1) {
+    return null;
+  }
+
+  /**
+   * 规范 H1
+   */
+  const canonicalH1 = canonicalizeH1(input.lines[h1Index] ?? '', input.number);
+
+  if (canonicalH1.line !== (input.lines[h1Index] ?? '')) {
+    input.transformations.push({
+      kind: 'h1-numbered',
+      detail: `${input.lines[h1Index]} → ${canonicalH1.line}`,
+    });
+  }
+
+  return { line: canonicalH1.line };
+}
+
 /**
  * 执行单文档纯变换
  *
@@ -519,6 +506,7 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
       content: raw,
       message: '无可识别状态行——灯位属语义判断，交人工（--status red|green 显式定档）',
       transformations: [],
+      sourceReplaced: false,
     };
   }
 
@@ -530,14 +518,27 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
     : cleanValue(parsed.fields[statusIndex ?? 0]?.value ?? '');
 
   /**
-   * 已规范形态幂等判定（规范五态或 emoji 旧变体均不再迁移；注入通道不适用）
+   * 已规范状态标记（规范五态或 emoji 旧变体——值原样保留，仅走收敛通道：
+   * 体首残留元信息块吸收与键去重，不做状态词规范化）
+   */
+  const alreadyCanonical = !injected && classifyStatusLine(`状态: ${originalStatus}`) !== 'unknown';
+
+  /**
+   * 超长状态拆分产物（null 未触发；'manual' 词表未命中交人工）
    */
-  if (!injected && classifyStatusLine(`状态: ${originalStatus}`) !== 'unknown') {
+  const longSplit = probeLongStatusSplit({
+    injected,
+    alreadyCanonical,
+    originalStatus,
+  });
+
+  if (longSplit === 'manual') {
     return {
-      outcome: 'unchanged',
+      outcome: 'skipped',
       content: raw,
-      message: '状态行已是规范五态形态',
+      message: `状态值超长（${originalStatus.length} 字符——段落级文本混入状态行且词表未命中）——交人工拆分`,
       transformations: [],
+      sourceReplaced: false,
     };
   }
 
@@ -561,102 +562,23 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
   }
 
   /**
-   * 字段别名：日期 → 立案日期（已有立案日期则保留原字段不动）
-   */
-  const filingIndex = fields.findIndex((field) => field.key === '立案日期');
-
-  /**
-   * 旧字段名「日期」下标（方言主流的立案日期载体）
+   * 必填回填（别名/立案日期/优先级——缺省未给交人工）
    */
-  const dateIndex = fields.findIndex((field) => field.key === '日期');
+  const backfill = backfillRequiredFields({
+    fields,
+    transformations,
+    defaultPriority: options.defaultPriority,
+    defaultFilingDate: options.defaultFilingDate,
+  });
 
-  if (filingIndex === -1 && dateIndex !== -1) {
-    /**
-     * 待改名的日期字段
-     */
-    const dateField = fields[dateIndex];
-
-    if (dateField !== undefined) {
-      fields[dateIndex] = { key: '立案日期', value: dateField.value };
-
-      transformations.push({
-        kind: 'field-alias',
-        detail: `日期 → 立案日期（${dateField.value}）`,
-      });
-    }
-  }
-
-  /**
-   * 立案日期缺省回填（未给缺省则 skipped 交人工）
-   */
-  if (!fields.some((field) => field.key === '立案日期')) {
-    if (options.defaultFilingDate === undefined) {
-      return {
-        outcome: 'skipped',
-        content: raw,
-        message: '缺立案日期且未给回填缺省——交人工',
-        transformations: [],
-      };
-    }
-
-    fields.push({ key: '立案日期', value: options.defaultFilingDate });
-
-    transformations.push({
-      kind: 'required-backfilled',
-      detail: `立案日期 ← ${options.defaultFilingDate}`,
-    });
-  }
-
-  /**
-   * 优先级：既有值映射 / 严重程度映射 / 缺省回填
-   */
-  const priorityIndex = fields.findIndex((field) => field.key === '优先级');
-
-  if (priorityIndex !== -1) {
-    /**
-     * 既有优先级值
-     */
-    const existing = fields[priorityIndex]?.value ?? '';
-
-    /**
-     * 映射产物（中文档位 → P 档位）
-     */
-    const mapped = mapPriorityValue(existing);
-
-    if (mapped !== null && mapped !== existing) {
-      fields[priorityIndex] = { key: '优先级', value: mapped };
-
-      transformations.push({ kind: 'priority-mapped', detail: `优先级 ${existing} → ${mapped}` });
-    }
-  } else {
-    /**
-     * 严重程度映射或缺省回填
-     */
-    const severityField = fields.find((field) => field.key === '严重程度');
-
-    /**
-     * 回填值
-     */
-    const backfill =
-      (severityField !== undefined ? mapPriorityValue(severityField.value) : null) ??
-      options.defaultPriority ??
-      null;
-
-    if (backfill === null) {
-      return {
-        outcome: 'skipped',
-        content: raw,
-        message: '缺优先级且未给回填缺省——交人工',
-        transformations: [],
-      };
-    }
-
-    fields.push({ key: '优先级', value: backfill });
-
-    transformations.push({
-      kind: severityField !== undefined ? 'priority-mapped' : 'priority-backfilled',
-      detail: `优先级 ← ${backfill}${severityField !== undefined ? `（严重程度 ${severityField.value}）` : '（缺省回填）'}`,
-    });
+  if (backfill.skipMessage !== null) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: backfill.skipMessage,
+      transformations: [],
+      sourceReplaced: false,
+    };
   }
 
   /**
@@ -665,7 +587,7 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
   const injectedTier: 'green' | 'red' = options.status === 'green' ? 'green' : 'red';
 
   /**
-   * 状态词规范化（注入通道状态已是规范形态，跳过词表判定）
+   * 状态词规范化（注入/已规范通道跳过词表判定：注入为规范标签；已规范值原样保留）
    */
   const canonicalStatus = injected
     ? {
@@ -673,7 +595,23 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
         tier: injectedTier,
         word: '<无状态行>',
       }
-    : canonicalizeStatusValue(originalStatus);
+    : alreadyCanonical
+      ? {
+          value: originalStatus,
+          tier:
+            classifyStatusLine(`状态: ${originalStatus}`) === 'green' ||
+            classifyStatusLine(`状态: ${originalStatus}`) === 'legacy-green'
+              ? ('green' as const)
+              : ('red' as const),
+          word: '<已规范>',
+        }
+      : longSplit !== null
+        ? {
+            value: longSplit.canonical,
+            tier: longSplit.tier,
+            word: '<超长拆分>',
+          }
+        : canonicalizeStatusValue(originalStatus);
 
   if (canonicalStatus === null) {
     return {
@@ -681,9 +619,22 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
       content: raw,
       message: `状态值「${originalStatus}」不可机械迁移（冻结/取消无据/黄灯无因/词表未识别）——交人工`,
       transformations: [],
+      sourceReplaced: false,
     };
   }
 
+  /**
+   * 超长状态拆分产物：短规范状态承载词表档位，全文说明落处置摘要字段
+   */
+  if (longSplit !== null && !fields.some((field) => field.key === '处置摘要')) {
+    fields.push({ key: '处置摘要', value: longSplit.summary });
+
+    transformations.push({
+      kind: 'status-canonicalized',
+      detail: `状态值超长拆分：${longSplit.summary.slice(0, 24)}… → 短规范状态 + 处置摘要字段（${longSplit.summary.length} 字符全文承载）`,
+    });
+  }
+
   /**
    * 处置段对齐（绿灯族；黄灯降级案同样需要对齐后的段供回填）
    */
@@ -694,6 +645,26 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
    */
   let bodyLines = lines.slice(parsed.bodyStartIndex);
 
+  /**
+   * 体首残留元信息块吸收（历史批量清偿事故形态：方言行未被解析而落 residual、
+   * 注入回填后又在正文首部原样存留——吸收回头部字段并随后键去重收敛）
+   */
+  const absorbed = absorbLeadingMetadata(bodyLines, fields);
+
+  if (absorbed.consumedLines > 0) {
+    bodyLines = absorbed.restLines;
+
+    transformations.push({
+      kind: 'header-converged',
+      detail: `体首残留元信息块吸收 ${absorbed.consumedLines} 行（键去重收敛见产物）`,
+    });
+  }
+
+  /**
+   * 键去重与语义让位（状态/来源：注入定档/回填标记让位于吸收到的原始语义）
+   */
+  const convergence = convergeDuplicateFields(fields, transformations);
+
   /**
    * 处置段对齐产物（非绿灯族不触发）
    */
@@ -709,11 +680,12 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
    * 最终状态值（占位降级：历史绿词但验证口径为占位——诚实黄灯；注入通道定档为人工语义不降级）
    */
   const finalStatus =
-    !injected && alignment.placeholder
+    convergence.statusValue ??
+    (!injected && alignment.placeholder
       ? `🟡 处理中（历史标记已处置但验证口径为占位，清偿时待核实；原「${canonicalStatus.word}」）`
-      : canonicalStatus.value;
+      : canonicalStatus.value);
 
-  if (!injected) {
+  if (!injected && !alreadyCanonical) {
     if (alignment.placeholder) {
       transformations.push({
         kind: 'status-downgraded-placeholder',
@@ -737,51 +709,42 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
   }
 
   /**
-   * 来源回填
+   * 来源与所属域回填（缺省未给交人工）
    */
-  if (!fields.some((field) => field.key === '来源')) {
-    if (options.defaultSource === undefined) {
-      return {
-        outcome: 'skipped',
-        content: raw,
-        message: '缺来源且未给回填缺省——交人工',
-        transformations: [],
-      };
-    }
-
-    fields.push({ key: '来源', value: options.defaultSource });
-
-    transformations.push({ kind: 'required-backfilled', detail: '来源 ← 缺省回填' });
-  }
+  const tailBackfill = backfillSourceAndDomain({
+    fields,
+    transformations,
+    defaultSource: options.defaultSource,
+    scopeTitle: options.scopeTitle,
+  });
 
-  /**
-   * 所属域回填（scope title）
-   */
-  if (!fields.some((field) => field.key === '所属域')) {
-    fields.push({ key: '所属域', value: options.scopeTitle });
-
-    transformations.push({ kind: 'required-backfilled', detail: `所属域 ← ${options.scopeTitle}` });
-  }
-
-  /**
-   * H1 规范化
-   */
-  const h1Index = lines.findIndex((line) => line.startsWith('# '));
-
-  if (h1Index === -1) {
-    return { outcome: 'skipped', content: raw, message: '无一级标题——交人工', transformations: [] };
+  if (tailBackfill.skipMessage !== null) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: tailBackfill.skipMessage,
+      transformations: [],
+      sourceReplaced: false,
+    };
   }
 
   /**
-   * 规范 H1
+   * H1 规范化（无一级标题交人工；编号规范见变换台账）
    */
-  const canonicalH1 = canonicalizeH1(lines[h1Index] ?? '', options.number);
+  const h1 = canonicalizeHeaderH1({
+    lines,
+    number: options.number,
+    transformations,
+  });
 
-  if (canonicalH1.line !== (lines[h1Index] ?? '')) {
-    transformations.push({
-      kind: 'h1-numbered',
-      detail: `${lines[h1Index]} → ${canonicalH1.line}`,
-    });
+  if (h1 === null) {
+    return {
+      outcome: 'skipped',
+      content: raw,
+      message: '无一级标题——交人工',
+      transformations: [],
+      sourceReplaced: false,
+    };
   }
 
   /**
@@ -792,21 +755,42 @@ export function migrateLegacyCore(raw: string, options: MigrateCoreOptions): Mig
     ...fields.filter((field) => !HEADER_FIELD_ORDER.includes(field.key)),
   ];
 
+  /**
+   * 正文前导空行剥离（分隔空行由组装层统一供给——保证已规范产物逐字幂等）
+   */
+  let bodyStart = 0;
+
+  while (bodyStart < bodyLines.length && (bodyLines[bodyStart] ?? '').trim() === '') {
+    bodyStart += 1;
+  }
+
   /**
    * 产物全文
    */
   const content = [
-    canonicalH1.line,
+    h1.line,
     '',
     ...orderedFields.map((field) => `**${field.key}**: ${field.value}`),
     ...(parsed.residuals.length > 0 ? ['', ...parsed.residuals] : []),
     '',
-    ...bodyLines,
+    ...bodyLines.slice(bodyStart),
   ].join('\n');
 
   if (content === raw) {
-    return { outcome: 'unchanged', content: raw, message: '已是规范形态', transformations: [] };
+    return {
+      outcome: 'unchanged',
+      content: raw,
+      message: '已是规范形态',
+      transformations: [],
+      sourceReplaced: false,
+    };
   }
 
-  return { outcome: 'rewritten', content, message: '存量头部已清偿为规范形态', transformations };
+  return {
+    outcome: 'rewritten',
+    content,
+    message: '存量头部已清偿为规范形态',
+    transformations,
+    sourceReplaced: convergence.sourceReplaced,
+  };
 }