@xulthekl/team-flow 0.52.0 → 0.53.0

package/scripts/lib/arch-merge.mjs

@@ -22,8 +22,8 @@ import { join, basename, dirname, relative, resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 import {
-  parseTableAfter, extractEndpoints, extractAggregates,
-  extractTablesFromSql, extractTablesFromDatabaseMd, readFrontmatter,
+  parseTableRow, extractEndpoints, extractEndpointsDetailed, extractAggregates,
+  extractTablesFromSql, readFrontmatter, PATH_CELL_RE,
 } from './arch-parse.mjs';
 import { detectWorkspaceRoot, getGitRoot, parsePorcelainPaths } from './git-utils.mjs';
 
@@ -65,7 +65,7 @@ function releaseLock(lockPath) {
  * 全局文档维护 marker 区（当前态：BC/聚合注册表）+ 演进日志段。
  * marker 区重建 = 所有已合并 change 增量的投影（按聚合 id upsert，非原地编辑）。
  */
-function mergeArchitecture(changeDir, archDir, globalArchDir, changeName) {
+function mergeArchitecture(changeDir, archDir, globalArchDir, changeName, projectRoot) {
   const srcPath = join(archDir, 'architecture.md');
   const dstPath = join(globalArchDir, 'ARCHITECTURE.md');
   if (!existsSync(srcPath)) return { merged: false, reason: 'no-source' };
@@ -75,13 +75,26 @@ function mergeArchitecture(changeDir, archDir, globalArchDir, changeName) {
 
   // 结构化提取聚合清单（唯一事实源，聚合注册表）
   const aggregates = extractAggregates(srcContent);
-  // 关键门禁：声明 required 但解析到 0 聚合 → abort（禁止静默）
-  if (fm.arch_design_decision === 'required' && aggregates.length === 0) {
-    abort('architecture.md 聚合注册表解析为空（arch_design_decision=required）——检查模板 §2 是否输出聚合行');
+
+  // v0.53.0 §107 R7：零聚合增量合法化。
+  // 「arch_design_decision=required 但零聚合」是**完全合法且常见**的形态（纯 API 增量 /
+  // 纯读写模型增量 / 瞬态凭证值对象设计）——C2/C3 连续两个 change 复现，且在识别读写模型
+  // （CQRS）增量时必然触发。原实现一律 abort，且无合法绕过路径（塞聚合=伪造/冲突，
+  // 改决策=伪造判定），归档永久缺一块。
+  //
+  // **但零聚合有两种成因，必须可区分**：① 声明为无（合法）② 解析失配（缺陷）。
+  // 故只放宽前者——须显式声明 `aggregate_action: none`（或 `aggregate_id: null`），
+  // 未声明仍 abort，以保留对解析失配的守卫（否则 §106 那类列错位缺陷会被一并静默）。
+  const declaredNone = fm.aggregate_action === 'none' || fm.aggregate_id === 'null';
+  if (fm.arch_design_decision === 'required' && aggregates.length === 0 && !declaredNone) {
+    abort('architecture.md 聚合注册表解析为空且未声明零增量（arch_design_decision=required）——'
+      + '检查模板 §2 是否输出聚合行；若本 change 确无聚合增量，请显式声明 aggregate_action: none');
   }
 
   const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf-8') : '';
-  const currentStateSection = buildCurrentStateSection(aggregates, changeName);
+  // v0.53.0 §108 R8：marker 区 = **已合并 change 的聚合全集投影**（非仅当前 change）
+  const allAggregates = collectAllAggregates(projectRoot, changeName, aggregates);
+  const currentStateSection = buildCurrentStateSection(allAggregates);
 
   // marker 区替换（代码独占写）：存在则替换，缺失则插入
   let updated;
@@ -104,15 +117,59 @@ function mergeArchitecture(changeDir, archDir, globalArchDir, changeName) {
   updated = upsertEvolutionLog(updated, srcContent, changeName);
 
   writeFile(dstPath, updated, 'utf-8');
-  return { merged: true, file: 'ARCHITECTURE.md', aggregates: aggregates.map(a => a.id) };
+  return {
+    merged: true,
+    file: 'ARCHITECTURE.md',
+    aggregates: aggregates.map(a => a.id),
+    projected: allAggregates.length,
+    ...(aggregates.length === 0 ? { reason: 'no-aggregate-delta' } : {}),
+  };
+}
+
+/**
+ * v0.53.0 §108 R8：收集「已合并 change 的聚合全集」用于 marker 区投影。
+ *
+ * **原实现只用当前 change 的聚合重建 marker 区** → 多 change 场景下互相抹除：
+ * ```
+ * C1 merge → marker 区 = {C1 聚合}
+ * C2 merge → marker 区 = {C2 聚合}     ← C1 的行被抹掉
+ * ```
+ * emp-auth 现状之所以未暴露该风险，是因为 C2/C3 被零聚合 abort 挡在门外——
+ * **一旦 R7 修好门禁，抹除会立即发生**（`20260910-000823` 的「根因 4」已论证：
+ * abort 在此客观上起了保护作用）。
+ *
+ * 纳入判据与 R2 一致：**当前 change 无条件纳入**；其余仅 `closed|closing`
+ * （防在途半成品污染，沿用 v0.36.3 判据）。同一 id 被多个 change 声明时
+ * **以当前 change 优先**（本次合并是权威——而"其他 change 声明同一聚合"已由
+ * `conflictCheck` 在更早阶段阻断，此处仅为确定性兜底）。
+ */
+function collectAllAggregates(projectRoot, changeName, currentAggregates) {
+  const collected = new Map(); // id → { ...aggregate, source }
+  const changesDir = join(projectRoot, 'changes');
+  if (existsSync(changesDir)) {
+    for (const name of readdirSync(changesDir)) {
+      if (name === changeName) continue;
+      const changeRoot = join(changesDir, name);
+      if (!isChangeClosed(changeRoot)) continue;
+      const p = join(changeRoot, 'architecture', 'architecture.md');
+      if (!existsSync(p)) continue;
+      for (const a of extractAggregates(readFileSync(p, 'utf-8'))) {
+        if (!collected.has(a.id)) collected.set(a.id, { ...a, source: `change:${name}` });
+      }
+    }
+  }
+  // 当前 change 覆盖同 id 项（本次合并权威）
+  for (const a of currentAggregates) collected.set(a.id, { ...a, source: `change:${changeName}` });
+  return [...collected.values()];
 }
 
-/** 构建当前态 marker 区内容（BC 表 + 聚合注册表，厚锚点一句话级；聚合注册表带来源列）。 */
-function buildCurrentStateSection(aggregates, changeName) {
+/** 构建当前态 marker 区内容（BC 表 + 聚合注册表，厚锚点一句话级；来源列标注真实来源 change）。 */
+function buildCurrentStateSection(aggregates) {
   const bcMap = new Map();
   for (const a of aggregates) {
-    if (!bcMap.has(a.context)) bcMap.set(a.context, []);
-    bcMap.get(a.context).push(a);
+    const bc = a.context || '（未标注）';
+    if (!bcMap.has(bc)) bcMap.set(bc, []);
+    bcMap.get(bc).push(a);
   }
   const lines = ['## 当前态', ''];
   lines.push('### 限界上下文');
@@ -121,31 +178,66 @@ function buildCurrentStateSection(aggregates, changeName) {
     lines.push(`| ${bc} | ${aggs.length} |`);
   }
   lines.push('', '### 聚合注册表');
-  // v0.36.3 §62.1 首轮特例：全局聚合全部来自已合并 change（=已落地态）；状态列标注
   lines.push('| 聚合ID | 上下文 | 根实体 | 来源 | 状态 | 关键不变量 |', '|--------|--------|--------|------|------|-----------|');
   for (const a of aggregates) {
-    lines.push(`| ${a.id} | ${a.context} | ${a.root} | change:${changeName} | 已落地 | ${a.invariants || '—'} |`);
+    lines.push(`| ${a.id} | ${a.context || '—'} | ${a.root || '—'} | ${a.source || '—'} | 已落地 | ${a.invariants || '—'} |`);
   }
   return lines.join('\n');
 }
 
-/** 演进日志 upsert：按 changeName 锚定位既有块，存在则替换、否则追加。 */
+/**
+ * 演进日志 upsert：按 changeName 锚定位既有块，存在则替换、否则追加。
+ *
+ * v0.53.0 §109.4 R11 修复（幂等性）：原替换正则前瞻 `(?=^### change:|^## |^\n$|$)` 中，
+ * `$` 在 `/m` 标志下匹配的是**行尾**而非字符串末尾 —— 惰性量词 `[\s\S]*?` 在锚行行尾
+ * 处即刻满足前瞻 → 匹配范围退化为零宽 → **只替换掉锚行本身，旧表体一行不删**。
+ * 后果：arch-merge 每重复执行一次就追加一份演进日志（实测 3 次运行表体 1→2→3 份），
+ * 全局 ARCHITECTURE.md 无限膨胀。该缺陷在 B' 方案（arch-merge 前移至门禁前，重试成为
+ * 常态）下会被放大，故必须先修。
+ *
+ * 修复要点：
+ * 1. 前瞻末尾 `$` → `$(?![\s\S])`：`/m` 下中间行尾因后面仍有字符而不成立，只有字符串
+ *    末尾才命中（等价"真·文件末尾"）。
+ * 2. 移除 `^\n$`：`/m` 下几乎不匹配，且一旦匹配会造成块被提前截断（截断 = 替换不完整
+ *    = 残留累积，与本缺陷同型）。
+ * 3. **新增 `^<!-- arch:` 边界（关键）**：marker 区（当前态）紧跟在 `### change:` 块之后，
+ *    而 `<!-- arch:current-state:begin -->` 不匹配 `^## `。若边界漏掉它，替换会一路吞到
+ *    文件末尾，**把 marker 区一并删除** → marker 不成对 → 下次 `mergeArchitecture` 直接
+ *    abort。原实现之所以未暴露该风险，恰恰是因为零宽 bug 让它"什么都没删"。
+ * 4. 块范围 = 锚行 → 下一个块起点，块起点 ∈ {`^### change:`、`^## ` / `^# `、`^<!-- arch:`、
+ *    文件末尾}。边界之外的内容（含 change 级模板残留表）由本 change 块独占，随替换清理。
+ * 5. 删除死变量 `anchorRe`（`/^#{3,4}\s*.*change[:\s].*$/mi`，从未被引用）。
+ */
 function upsertEvolutionLog(globalContent, srcContent, changeName) {
   // 从 change 源提取演进日志条目（标题 + 正文）
   const logStart = srcContent.search(/^#{2,3}\s*\d*\.?\s*(演进日志|Evolution Log)/m);
   if (logStart < 0) return globalContent;
   const logSection = srcContent.slice(logStart).trim();
-  const anchorRe = /^#{3,4}\s*.*change[:\s].*$/mi;
   const anchor = `### change:${changeName}`;
   const logBlock = `${anchor}\n${logSection.replace(/^#{2,3}\s*\d*\.?\s*(演进日志|Evolution Log)/m, '').trim()}`;
 
-  // 已存在 → 替换；否则追加到演进日志段末尾
+  // 已存在 → 替换整块；否则追加到演进日志段末尾
   const logHeadingRe = /^#{2,3}\s*\d*\.?\s*(演进日志|Evolution Log)/m;
-  if (new RegExp(`^### change:${escapeRegExp(changeName)}\\s*$`, 'm').test(globalContent)) {
-    return globalContent.replace(
-      new RegExp(`^### change:${escapeRegExp(changeName)}[\\s\\S]*?(?=^### change:|^## |^\\n$|$)`, 'm'),
-      logBlock
+  const anchorRe = new RegExp(`^### change:${escapeRegExp(changeName)}\\s*$`, 'm');
+  if (anchorRe.test(globalContent)) {
+    // 块起点：下一个 change 块 / 下一个一二级标题 / arch marker / 文件末尾
+    const blockRe = new RegExp(
+      `^### change:${escapeRegExp(changeName)}\\s*$[\\s\\S]*?`
+      + `(?=^### change:|^#{1,2}\\s|^<!-- arch:|$(?![\\s\\S]))`,
+      'm'
     );
+    const matched = globalContent.match(blockRe);
+    if (matched) {
+      // 被替换段内若含疑似人工内容（非标题/非表格行/非空行/非注释）→ 告警不静默
+      const suspicious = matched[0].split('\n').slice(1)
+        .filter(l => l.trim() && !l.trim().startsWith('|') && !/^#{1,6}\s/.test(l.trim()));
+      if (suspicious.length > 0) {
+        console.warn(`  [WARN] 演进日志块 change:${changeName} 内含 ${suspicious.length} 行非表格内容，将被替换：${suspicious[0].slice(0, 60)}`);
+      }
+    }
+    // 替换值恒为 `${logBlock}\n`：blockRe 的惰性匹配天然包含块尾换行，故重建结果
+    // 与首次写入（第三分支 `+ logBlock + '\n'`）逐字节一致 → 逐字节幂等。
+    return globalContent.replace(blockRe, `${logBlock}\n`);
   }
   if (logHeadingRe.test(globalContent)) {
     return globalContent.replace(logHeadingRe, `$&\n${logBlock}`);
@@ -232,13 +324,24 @@ function isChangeClosed(changeRoot) {
   if (!existsSync(stateFile)) return false;
   const m = readFileSync(stateFile, 'utf-8').match(/^state:\s*(.*)$/m);
   const state = m ? m[1].trim() : '';
+  // 注：`closed` 在 `VALID_STATES`（state-loader.mjs）中**不存在**，`closing→closed`
+  // 转换也不在状态机上——此处的 `closed` 分支**仅为前向兼容**（若未来新增终态则自动
+  // 生效），当前活跃路径只有 `closing`。**勿将其当作可依赖的活跃分支。**
   return state === 'closed' || state === 'closing';
 }
 
 /**
- * Step 6: API-INDEX.md 生成式（api-scan 核心）。
- * 扫描项目根下所有已关闭 change 的 architecture/api.md + domains/，归一化端点重建。
- * 保护：①重建结果为空 → 拒绝覆盖（防历史手工端点被抹）；②只扫已关闭 change（v0.36.3，在途半成品端点不得入全局）。
+ * Step 6: API-INDEX.md 生成式（api-scan 核心）+ 产出量对账（v0.53.0 §103/§104）。
+ *
+ * 扫描项目根下所有（已关闭 **或本次正在合并** 的）change 的 architecture/api.md，重建端点。
+ *
+ * 保护与对账：
+ * ① **当前 change 无条件纳入**（§103 R2）——原实现对自身也施加 `isChangeClosed` 判据，
+ *    而执行时刻自身状态仍为 `executing`/`approved-for-build` → 自我排除 → 扫描集空 →
+ *    命中空结果保护 → **报成功但零产出**。此修复使行为与执行时序**彻底解耦**。
+ * ② 重建结果为空 → 拒绝覆盖（防历史手工端点被抹；保护本身正确，**但必须可见**，见 §104 R4）。
+ * ③ 产出量对账（§104.2.2）——生成器原只判「源文件在不在」，从不判「吃进去多少 / 原文多少」，
+ *    形态失配因此长期隐性。
  */
 function generateApiIndex(projectRoot, globalArchDir, changeName) {
   const changesDir = join(projectRoot, 'changes');
@@ -246,29 +349,85 @@ function generateApiIndex(projectRoot, globalArchDir, changeName) {
   const header = '# API Index（generated by arch-merge, do not edit）\n\n';
 
   const endpoints = [];
+  const details = [];
   if (existsSync(changesDir)) {
     for (const changeDirName of readdirSync(changesDir)) {
       const changeRoot = join(changesDir, changeDirName);
-      if (!isChangeClosed(changeRoot)) continue; // v0.36.3：只扫已关闭 change
+      if (changeDirName !== changeName && !isChangeClosed(changeRoot)) continue; // §103 R2
       const apiPath = join(changeRoot, 'architecture', 'api.md');
       if (!existsSync(apiPath)) continue;
-      const ep = extractEndpoints(readFileSync(apiPath, 'utf-8'));
-      for (const e of ep) endpoints.push({ ...e, source: changeDirName });
+      const det = extractEndpointsDetailed(readFileSync(apiPath, 'utf-8'));
+      details.push({ change: changeDirName, ...det });
+      for (const e of det.endpoints) endpoints.push({ ...e, source: changeDirName });
+    }
+  }
+
+  // ---- 产出量对账（§104.2.2 / §115.3）----
+  const warnings = [];
+  const failures = [];
+  for (const d of details) {
+    const epSections = d.sections.filter(s => s.isEndpointSection);
+    const epTotal = epSections.reduce((n, s) => n + s.endpoints, 0);
+    const candTotal = epSections.reduce((n, s) => n + s.candidates, 0);
+
+    // FAIL 前提（§115.3 A-2）：仅「端点章节」参与判定，且要求 every(全零) && some(有候选)。
+    // 这样纯 DB 变更 / 纯重构 change（api.md 存在但无端点）不会误杀——它们没有端点章节候选。
+    //
+    // v0.53.0 §115.8（P4 复核发现，**严重**）：**失败必须归属到 owner**。
+    // 本函数扫描「当前 change + 全部已关闭 change」。若把扫描集中**任一** change 的解析
+    // 失败都算作本次失败，则**一个历史脏数据会死锁所有后续 change 的 closing**——
+    // 实测：无关的已关闭 change 畸形 → `tf arch-merge <当前 change>` 退出码 1，
+    // 而当前 change 自己的回写已落地、`arch-merged` 门禁也 PASS；且 `arch_merge_skipped`
+    // 只豁免 guard 维度、**不清除命令级 failure** → 逃生通道完全不通。
+    //
+    // 判据：只有**本 change** 的解析失配才是本次 merge 的 failure（意味着本 change 的
+    // 端点未能入索引，回写不完整）；其他 change 的问题降级为 WARN，由各自 owner 修复。
+    if (epSections.length > 0 && epTotal === 0 && candTotal > 0) {
+      const msg = `${d.change}：端点章节表有 ${candTotal} 行候选但 0 条提取——api.md 表格形态失配`;
+      if (d.change === changeName) failures.push(msg);
+      else warnings.push(`[历史 change 解析异常] ${msg}（不影响本次回写，请单独修复该 change 的 api.md）`);
+    }
+    // ratio：仅端点章节内（§104.2.2 ⑤）——实测修复前 C1/C2/C3 为 0.163/0.083/0.077
+    // 三个文件全部触发，故该规则**必须与 §105 同批上线**才有判别力。
+    if (candTotal > 0 && epTotal / candTotal < 0.5) {
+      warnings.push(`${d.change}：端点章节覆盖率偏低 ${epTotal}/${candTotal}`);
     }
+    // 分层展示（§104.2.2 ②）：真信号层（端点章节内）逐条；噪音层折叠为计数。
+    // 实测端点章节内 unmatched 恒为 0 → **平时静默、出问题才响**。
+    for (const u of d.unmatched.filter(x => x.isEndpointSection)) {
+      warnings.push(`${d.change}：端点章节内未识别（${u.kind}）第 ${u.line} 行: ${u.text}`);
+    }
+    const noiseCount = d.unmatched.length - d.unmatched.filter(x => x.isEndpointSection).length;
+    if (noiseCount > 0) {
+      warnings.push(`${d.change}：引用/映射/约定章节未识别 ${noiseCount} 行（噪音层，已折叠）`);
+    }
+  }
+
+  // 解析失配 → fail-closed 不写盘（与聚合链 abort 标准对齐）
+  if (failures.length > 0) {
+    return { generated: false, reason: 'endpoint-parse-mismatch', failures, warnings, file: 'API-INDEX.md', endpoints: endpoints.length };
   }
 
-  // 空结果拒绝覆盖（数据丢失保护）
+  // 空结果拒绝覆盖（数据丢失保护，**保留**）+ 可见化（§104 R4：不得静默）
   if (endpoints.length === 0 && existsSync(dstPath)) {
-    return { generated: false, reason: 'empty-scan-skip-overwrite', file: 'API-INDEX.md', endpoints: 0 };
+    return {
+      generated: false,
+      reason: 'empty-scan-skip-overwrite',
+      warnings: [...warnings, '扫描结果为空，已保留既有 API-INDEX.md 未被覆盖（防历史手工端点被抹）；若确应清空请手工处理'],
+      file: 'API-INDEX.md',
+      endpoints: 0,
+    };
   }
 
   const lines = [header, '> 扫描 changes/**/api.md + domains/* 归一化端点重建（v0.14 §62.4）。\n'];
   lines.push('| 方法 | 路径 | 分流 | 来源 |', '|------|------|------|------|');
   for (const e of endpoints) {
-    lines.push(`| ${e.method || '—'} | ${e.path} | ${e.kind} | ${e.source} |`);
+    // method 恒非空（§105.2.4「无方法即跳过」保证），故不再写 `—` 占位——
+    // 否则往返解析（updateIndex 会重新 extractEndpoints）时该行会被判为无方法而丢失。
+    lines.push(`| ${e.method} | ${e.path} | ${e.kind} | ${e.source} |`);
   }
   writeFile(dstPath, lines.join('\n'), 'utf-8');
-  return { generated: true, file: 'API-INDEX.md', endpoints: endpoints.length };
+  return { generated: true, file: 'API-INDEX.md', endpoints: endpoints.length, warnings, failures: [] };
 }
 
 /* ============ 冲突预检 ============ */
@@ -280,27 +439,63 @@ function generateApiIndex(projectRoot, globalArchDir, changeName) {
  */
 function conflictCheck(changeDir, archDir, globalArchDir, changeName) {
   const conflicts = [];
+  const warnings = [];
   const apiPath = join(archDir, 'api.md');
   const archPath = join(archDir, 'architecture.md');
 
   if (existsSync(apiPath)) {
-    const newEndpoints = extractEndpoints(readFileSync(apiPath, 'utf-8'));
+    // v0.53.0 §115.5：**排除 As-Is 段端点**。
+    //
+    // As-Is 段（`## 1. As-Is 基线（冻结复制）` / `### 1.x 现有 …`）是**冻结复制的基线记录**，
+    // 不是本 change 的端点所有权声明。原实现比较两个 change 的**全部**端点 → 多个 change
+    // 各自复制同一批 As-Is 端点即被误判为所有权冲突。
+    //
+    // emp-auth 实测：C2 与 C3 的 As-Is 段共享 5 条 `/auth/*` 端点（C2 明确标注「F5 归 C3」
+    // 即这些归 C3 实现）→ C2 的 arch-merge 被阻断，其演进日志与 marker 来源列永不写入
+    // → 连带 `arch-merged` 门禁对该 change 无出路。
+    //
+    // **该缺陷是 R5 修复暴露出来的**：修复前合并式单元格提取不到这些端点，冲突检查
+    // 是"假通过"（同时真冲突也检不出）；修复后端点提取完整，误判才显现。
+    const newEndpoints = extractEndpointsDetailed(readFileSync(apiPath, 'utf-8'))
+      .endpoints.filter(e => !e.isAsIs);
     const indexPath = join(globalArchDir, 'API-INDEX.md');
     if (existsSync(indexPath)) {
       // 全局端点带来源（API-INDEX 生成格式列3=来源）；排除本 change 自身的（幂等重复不冲突）
+      //
+      // v0.53.0 §105.3 R12：**改用 `parseTableRow` + 共享常量**。
+      // 原实现是**手写的第二套表格解析器**——`slice(1,-1).split('|')` 自建拆分 + 自建
+      // 反引号剥离 + 硬编码路径字符集。它与生成侧的 `parseTableRow` **清洗规则不同**：
+      // 若生成侧未来输出 `**GET**`，`parseTableRow`（已支持强调剥离）认得出、此处认不出
+      // → 校验静默漏检。**仅把字符集换成共享常量不够，必须统一拆分与清洗入口**——
+      // 否则只统一了字符集，口径分裂仍在。
       const existingByKey = new Map();
       for (const line of readFileSync(indexPath, 'utf-8').split('\n')) {
-        if (!line.trim().startsWith('|')) continue;
-        const cells = line.trim().slice(1, -1).split('|').map(c => c.trim().replace(/`/g, ''));
-        if (cells.length < 4) continue;
+        const cells = parseTableRow(line);
+        if (!cells || cells.length < 4) continue;
         const method = cells[0], path = cells[1], source = cells[3];
-        if (!/^\/[\w\-/{}.]+$/.test(path)) continue;
+        if (!PATH_CELL_RE.test(path)) continue;
         existingByKey.set(`${method}:${path}`, source);
       }
+      // v0.53.0 §115.5：**端点重复声明由阻断降级为告警**。
+      //
+      // 原实现把"两个 change 涉及同一端点"当作所有权冲突硬阻断。但实测（emp-auth）：
+      // C2 与 C3 的 §2.1 To-Be 段都列了 `/auth/logout`、`/auth/token/flush`、
+      // `/auth/token/disable`（C2 明确标注「F5 归 C3」——即它知道这些归 C3，只是
+      // 在自己的 To-Be 表里记录了变更影响）。**两个 change 涉及同一端点是协作常态**
+      // （登录链路的 change 必然碰到会话治理的 change 要改的端点）。
+      //
+      // 硬阻断的后果与本方案的**核心目标直接冲突**：C2 因此无法完成 arch-merge →
+      // 演进日志与 marker 来源列永不写入 → 连带 `arch-merged` 门禁对该 change 无出路
+      // →「架构变更必须合并到台账」这一原则被破坏。
+      //
+      // **判据修正**：端点归属无法由解析判定（无法区分"重复实现"与"协作共享"），
+      // 故降级为 WARN 提示，交由 `cross-change-consistency-checker` agent 做语义判断。
+      // **聚合冲突保持阻断**——聚合所有权是明确的（一个聚合一个 owner，由 §2.1 聚合变更
+      // 表显式声明），不存在"协作共享聚合"的合法形态。
       for (const e of newEndpoints) {
         const key = `${e.method}:${e.path}`;
         if (existingByKey.has(key) && existingByKey.get(key) !== changeName) {
-          conflicts.push(`端点 ${e.method} ${e.path} 已被 change ${existingByKey.get(key)} 占用 → 阻断`);
+          warnings.push(`端点 ${e.method} ${e.path} 亦被 change ${existingByKey.get(key)} 声明（协作共享，非阻断）`);
         }
       }
     }
@@ -321,7 +516,7 @@ function conflictCheck(changeDir, archDir, globalArchDir, changeName) {
     }
   }
 
-  return { conflicts };
+  return { conflicts, warnings };
 }
 
 /* ============ INDEX 确定性统计 ============ */
@@ -444,7 +639,17 @@ function gitCommit(projectRoot, globalArchDir, touchedFiles, changeName, dryRun)
       unexpected,
     };
   } catch (e) {
-    return { committed: false, error: e.message };
+    const msg = (e.stderr && e.stderr.toString()) || (e.stdout && e.stdout.toString()) || e.message || '';
+    // v0.53.0 §104.2.4（B' 方案的硬前提）：无变更重跑是**幂等重试的常态**。
+    // B' 让 arch-merge 前移到门禁之前，「guard FAIL → 修复 → 重试」成为常态路径，
+    // arch-merge 会被反复执行；第二次 merge 内容无变化 → `git commit` 报 nothing to commit
+    // → 原实现落入 catch 返回 `{committed:false, error}`。一旦 §104 引入 failure 升级，
+    // 这会被计为 failure → 退出码非 0 → **重试永远无法通过门禁**（路径自我阻断）。
+    // 故必须归为 **no-op**，不得计为 failure。判据与 `cmd-publish` 同源。
+    if (msg.includes('nothing to commit') || msg.includes('nothing added to commit')) {
+      return { committed: false, noop: true, message: commitMsg };
+    }
+    return { committed: false, error: msg };
   }
 }
 
@@ -457,8 +662,19 @@ function detectUntouchedDirtyFiles(projectRoot, globalArchDir, touchedFiles) {
     // v0.23 §93.3.1：改用共享解析器。原 `^\S+\s+` 无法剥离 ` M path`（行首空格 = 未暂存修改，
     // 最常见形态）→ 路径残留状态码 → 本次 touch 的文件被误报为「非本次 touch 的脏文件」。
     // 路径口径统一为「相对 projectRoot 的绝对路径」后再与白名单比对，不依赖 process.cwd()。
-    const touched = new Set(touchedFiles.map(p => resolve(projectRoot, p)));
-    return parsePorcelainPaths(status).filter(p => p && !touched.has(resolve(projectRoot, p)));
+    //
+    // v0.53.0 §109.3 R10：比对判据改为**双向往返匹配**（与 `cmd-publish.detectOutsideDirty`
+    // 同源）。原实现是**精确匹配** `touched.has(resolve(p))`，而 git 对**全新未跟踪目录**
+    // 输出的是**目录级**路径 `?? docs/architecture/`（白名单是文件级）→ 永不命中 →
+    // **全新项目首次 arch-merge 必然误报**。该坑 `cmd-publish` 已踩过并修复（其注释明确
+    // 记录了「未跟踪内容显示目录级」场景），只是**未横展到 arch-merge**。
+    const norm = s => s.replace(/\/+$/, '');
+    const touchedDirs = touchedFiles.map(p => norm(resolve(projectRoot, p)));
+    return parsePorcelainPaths(status).filter(p => {
+      if (!p) return false;
+      const abs = norm(resolve(projectRoot, p));
+      return !touchedDirs.some(t => abs === t || abs.startsWith(t + '/') || t.startsWith(abs + '/'));
+    });
   } catch (e) {
     // v0.24 §98.3.2：解析失败不得静默（旧实现静默返回 [] = 漏报）。commit 侧仍有
     // `git commit -- <白名单>` 与提交后回读比对两道防线，故此处仅告警不阻断。
@@ -514,7 +730,16 @@ export function run(args = {}) {
     if (!preCheckResult.pass) {
       console.error('  Pre-check FAILED:');
       for (const c of preCheckResult.conflicts) console.error(`    - ${c}`);
-      return { merged: false, reason: 'pre-check-failed', conflicts: preCheckResult.conflicts };
+      // 返回形态统一（v0.53.0 §104.2.3）：**所有路径都必须带 warnings/failures 双数组**。
+      // 早退路径原先只返 {merged, reason, conflicts}，调用方写 `result.failures.length`
+      // 会抛 TypeError——同一契约面两种形状是漂移源。
+      return {
+        merged: false,
+        reason: 'pre-check-failed',
+        conflicts: preCheckResult.conflicts,
+        warnings: [],
+        failures: preCheckResult.conflicts,
+      };
     }
 
     // Step 1b: 冲突预检
@@ -522,11 +747,17 @@ export function run(args = {}) {
     if (conflictResult.conflicts.length > 0) {
       console.error('  Conflict check FAILED:');
       for (const c of conflictResult.conflicts) console.error(`    - ${c}`);
-      return { merged: false, reason: 'conflict', conflicts: conflictResult.conflicts };
+      return {
+        merged: false,
+        reason: 'conflict',
+        conflicts: conflictResult.conflicts,
+        warnings: conflictResult.warnings || [],
+        failures: conflictResult.conflicts,
+      };
     }
 
     // Step 2: ARCHITECTURE.md（当前态 upsert）
-    const archResult = mergeArchitecture(changeDir, archDir, globalArchDir, changeName);
+    const archResult = mergeArchitecture(changeDir, archDir, globalArchDir, changeName, projectRoot);
 
     // Step 4: schema-baseline.sql（幂等追加）——先同步 DDL，供 PHYSICAL-MODEL/DATABASE 生成消费
     const schemaResult = syncSchemaBaseline(changeDir, archDir, globalArchDir, changeName);
@@ -563,10 +794,45 @@ export function run(args = {}) {
     }
     const commitResult = gitCommit(projectRoot, globalArchDir, touchedFiles, changeName, dryRun);
 
-    console.log('\narch-merge complete.');
+    // ---- v0.53.0 §104.2.3 失败升级：子步骤结果不再被吞成 merged:true ----
+    // 原实现无视全部子步骤结果，一律 `return { merged: true }` + `arch-merge complete.`
+    // → `empty-scan-skip-overwrite` 等降级被静默，调用方（release-archivist）在 closing
+    // 归档报告里看到的是"全绿"。而**聚合链是有 abort() 的**——两条链标准不对称。
+    const warnings = [
+      ...(conflictResult.warnings || []),
+      ...(apiResult.warnings || []),
+      ...(archResult.reason === 'no-aggregate-delta'
+        ? [`${changeName}：本 change 无聚合增量（aggregate_action: none），marker 区按已合并 change 全集投影，未新增聚合行`]
+        : []),
+      ...(schemaResult.synced === false && schemaResult.reason && schemaResult.reason !== 'no-ddl-dir'
+        ? [`${changeName}：schema-baseline 未同步（${schemaResult.reason}）`]
+        : []),
+      ...(commitResult.noop ? [`${changeName}：无内容变更，未产生新提交（幂等重跑，非失败）`] : []),
+      // commit 失败归 **warning 而非 failure**：arch-merge 的核心职责是**回写制品**（已成功），
+      // commit 是协作便利层。非 git 环境（如单测 fixture）不应阻断 merge——但必须可见。
+      ...(commitResult.error ? [`${changeName}：git commit 失败（制品已写盘）——${commitResult.error}`] : []),
+      ...(dirty.length > 0 ? [`${changeName}：docs/architecture/ 有 ${dirty.length} 个非本次 touch 的改动，未纳入本次提交`] : []),
+    ];
+    const failures = [
+      // 只收「设计层面判定为解析/生成失败」的项。schema 未同步（无 DDL 目录/无 .sql 文件）
+      // 属**正常降级**（change 可能本就无 DB 变更），归 warning。
+      ...(archResult.merged === false && archResult.reason !== 'no-source'
+        ? [`architecture.md 未合并（${archResult.reason}）`] : []),
+      ...(apiResult.failures || []),
+    ];
+
+    for (const w of warnings) console.warn(`  [WARN] ${w}`);
+    for (const f of failures) console.error(`  [FAIL] ${f}`);
+
+    const merged = failures.length === 0;
+    console.log(merged
+      ? (warnings.length ? `\narch-merge complete (with ${warnings.length} warning(s)).` : '\narch-merge complete.')
+      : `\narch-merge FAILED: ${failures.length} failure(s).`);
     return {
-      merged: true,
+      merged,
       changeName,
+      warnings,
+      failures,
       steps: {
         architecture: archResult, physicalModel: pmResult, database: dbResult,
         schema: schemaResult, archive: archiveResult, apiIndex: apiResult,
@@ -578,6 +844,96 @@ export function run(args = {}) {
   }
 }
 
+/* ============ 生成器导出（供 tf arch scaffold 复用，§102.2.1 / §115.1 P2-4） ============ */
+
+/**
+ * 全局台账初始化脚手架：产出**目标格式**的空基线（而非复制 change 级模板）。
+ *
+ * 背景（§101.3 根因 I）：`workflow-bootstrap` B2 Step 0 原从
+ * `skills/architecture-design/templates/` 复制 **change 级模板** 到全局台账路径
+ * （`api.md → API-INDEX.md` 等 5 处），与 arch-merge 的生成式产物语义互斥。
+ * 其中 `DATABASE/PHYSICAL-MODEL/INDEX` 因无条件重建而被覆盖，`ARCHITECTURE/API-INDEX`
+ * 则永久卡在模板态——且 `API-INDEX.md` 模板自带的 4 条 `/api/xxx` 占位行使扫描非空，
+ * **连"空结果拒绝覆盖"保护都不触发**，`updateIndex` 还把这 4 行统计成 `端点数量: 4`。
+ *
+ * 本函数复用 arch-merge 的**同一批生成器**，构造上消除格式漂移：脚手架产出什么格式，
+ * 生成器就维护什么格式。
+ *
+ * @returns {{created: string[], skipped: string[]}}
+ */
+export function scaffoldGlobalLedger(projectRoot) {
+  const globalArchDir = join(projectRoot, 'docs', 'architecture');
+  const created = [];
+  const skipped = [];
+  const schemaPath = join(globalArchDir, 'schema-baseline.sql');
+
+  if (!existsSync(globalArchDir)) mkdirSync(globalArchDir, { recursive: true });
+
+  const writeIfAbsent = (name, produce) => {
+    const p = join(globalArchDir, name);
+    if (existsSync(p)) { skipped.push(name); return; }
+    fsWriteFileSync(p, produce(), 'utf-8');
+    created.push(name);
+  };
+
+  // 空 marker 区骨架（与 buildCurrentStateSection 同源）。
+  // 带 H1 与内容归属说明（v0.53.0 §115.6，P4 反馈 m2 / 问题8）：同批其他制品均有 H1，
+  // 且需澄清「As-Is 叙述写哪」——arch-merge 只重写 marker 区**之间**，区外内容保留。
+  writeIfAbsent('ARCHITECTURE.md', () => [
+    '# Architecture',
+    '',
+    '> **As-Is 架构叙述写在本文件 marker 区之外**（分层 / 模块边界 / 技术选型等）。',
+    // ⚠ 此处**不得原样写出 marker 字符串**——那会让文件里出现两对 begin/end，
+    // 触发 mergeArchitecture 的 marker 成对校验 → 首次 arch-merge 直接 abort。
+    // （本行曾是 `${MARKER_BEGIN}` 插值，被 R1 的"scaffold 产物可被接管"测试抓住。）
+    '> 两个 `arch:current-state` HTML 注释标记**之间**为全局当前态（聚合注册表），',
+    '> 由 `tf arch-merge` 独占维护（generated — 请勿手工编辑该区）。',
+    '',
+    MARKER_BEGIN,
+    buildCurrentStateSection([]),
+    MARKER_END,
+    '',
+  ].join('\n'));
+  // 生成器产物（无 schema 时输出"暂无"）
+  writeIfAbsent('PHYSICAL-MODEL.md', () => {
+    const header = '# Physical Model（generated by arch-merge, do not edit）\n\n';
+    return header + '> schema-baseline.sql 不存在，暂无物理模型。\n';
+  });
+  writeIfAbsent('DATABASE.md', () => {
+    const header = '# Database（generated by arch-merge, do not edit）\n\n';
+    return header + '> schema-baseline.sql 不存在，暂无库表说明。\n';
+  });
+  writeIfAbsent('API-INDEX.md', () => [
+    '# API Index（generated by arch-merge, do not edit）',
+    '',
+    '> 扫描 changes/**/api.md 归一化端点重建（v0.14 §62.4）。',
+    '',
+    '| 方法 | 路径 | 分流 | 来源 |',
+    '|------|------|------|------|',
+    '',
+  ].join('\n'));
+  writeIfAbsent('INDEX.md', () => [
+    '# Architecture Index',
+    '',
+    '> 本文件始终加载，各产物按需 Read。',
+    '',
+    '## 统计（确定性源）',
+    '- 限界上下文: 0',
+    '- 表数量: 0',
+    '- 端点数量: 0',
+    '',
+  ].join('\n'));
+
+  if (!existsSync(schemaPath)) {
+    fsWriteFileSync(schemaPath, '-- Schema Baseline\n-- Auto-maintained by arch-merge (generated, do not edit)\n\n', 'utf-8');
+    created.push('schema-baseline.sql');
+  } else {
+    skipped.push('schema-baseline.sql');
+  }
+
+  return { created, skipped };
+}
+
 // 支持直接执行（仅当被 node 直接运行，非被 import——node --test 加载时 process.argv[1] 可能含文件名片段）
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = process.argv.slice(2);
@@ -587,5 +943,9 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     else if (args[i] === '--dry-run') parsed.dryRun = true;
     else if (!args[i].startsWith('--')) parsed._.push(args[i]);
   }
-  run(parsed);
+  const result = run(parsed);
+  // v0.53.0 §104.2.3：有 failure → 非零退出码。
+  // 原实现一律 exit 0 并以 `arch-merge complete.` 结束，降级（如空扫描保护命中）对
+  // 调用方完全不可见。
+  if (result && Array.isArray(result.failures) && result.failures.length > 0) process.exitCode = 1;
 }