@xulthekl/team-flow 0.52.0 → 0.53.0

package/scripts/lib/arch-parse.mjs

@@ -4,15 +4,81 @@
 // 背景（红队评估实证）：旧实现正则硬编码（`## 2. To-Be`、`/api/` 前缀、反引号表名）
 // 在 LLM 文档标题漂移/格式变化时静默失败（match 失配返回空串、流程继续、返回 merged:true）。
 // 本模块用通用表格解析（按 `|` split + 去反引号）与格式容错匹配，抽取失配由调用方 abort。
+//
+// v0.53.0 形态健壮化（设计增强方案 v0.25 §105 / §106 / §115）：
+// - **共享常量**（§105.3）：路径字符集与方法词表原在「提取侧(本文件)」与「校验侧
+//   (arch-merge.conflictCheck)」各自硬编码 → 改一处即口径分裂（提取到、校验认不出 →
+//   冲突逃逸）。本文件为唯一来源，`arch-merge` 的手写解析器一律改调 `parseTableRow`。
+// - **extractEndpoints 六种形态**（§105.2）：合并式单元格 / 强调包裹 / 逗号枚举 /
+//   括号后缀 / 章节 kind 归属 / 无方法即跳过。并新增 `extractEndpointsDetailed`
+//   承载产出量对账（§104.2.1）。
+// - **extractAggregates 表头定位**（§106.2）：原实现用第二列的**值**是否命中
+//   `新增|修改|New|Update` 判断表布局；C1 实际写的是 `**extend**`（DDD 术语 + 加粗）
+//   → 两重失配 → 列语义整体错位 → 全局台账被写入 `上下文=extend`、
+//   `根实体=SysFrontSystem（不变）`。**这是污染而非缺失**。改判据为表头定位。
+
+/**
+ * HTTP 方法词表——**三个方法正则的唯一事实源**。
+ *
+ * 单一来源是刻意的：本文件早期版本把词表在 3 个正则里各写了一遍字面量
+ * （`HTTP_METHOD_RE` / `MULTI_METHOD_RE` / `MERGED_CELL_RE`），而 `arch-merge` 的
+ * 校验侧又自建第 4 份——这正是根因 III「同一跨文件契约在多处独立实现 → 判据漂移」
+ * （§101.5）。新增方法（如 HEAD / OPTIONS）时凡漏改一处即产生口径分裂。
+ */
+export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+const METHODS_ALT = HTTP_METHODS.join('|');
 
-/** 解析一行 markdown 表格为单元格数组（去反引号/去 code 包裹/trim）。非表格行返回 null。 */
+export const HTTP_METHOD_RE = new RegExp(`^(${METHODS_ALT})$`, 'i');
+/**
+ * 多方法单元格：官方根模板 `templates/api.md` 授权 `POST / PUT / DELETE` 写法
+ * （§115.3 D-3）。若只认单方法，未来该类行会被静默丢弃。
+ */
+export const MULTI_METHOD_RE = new RegExp(`^(${METHODS_ALT})(\\s*/\\s*(?:${METHODS_ALT}))+$`, 'i');
+/** 路径单元格（含逗号枚举，如 `/check/{add,update}/{a,b}/unique`）。 */
+export const PATH_CELL_RE = /^\/[\w\-/{},.]+$/;
+/** 合并式单元格：方法与路径同格（捕获组 1=方法，2=路径）。 */
+export const MERGED_CELL_RE = new RegExp(`^(${METHODS_ALT})\\s+(\\S+)`, 'i');
+/** 路径合法字符前缀——用于合并式捕获后的**截断 + 复验**，防全角括号/尾部描述混入路径。 */
+const PATH_PREFIX_RE = /^\/[\w\-/{},.]*/;
+
+/**
+ * 端点章节的**表级**判定：首列表头**精确等于**其中之一。
+ *
+ * ⚠ **禁止 `includes` / `startsWith`**（§115.3 A-1，全量死锁风险）：
+ * `API 端点` 是引用/对齐表的固定表头，来自**两个官方模板**——
+ * `templates/api.md`（`| API 端点 | 支撑的数据实体 | 一致性 |`）与
+ * `skills/architecture-design/templates/api.md`（`| API 端点 | 对应数据实体 | 对齐状态 |`）。
+ * **每一份按模板产出的 api.md 都带此表**，且模板行本身是无斜杠简写（candidates>0 / endpoints=0）。
+ * 若用 contains 匹配，该表被判为端点章节 → 触发 FAIL 判据 → 配合 arch-merged 阻断语义
+ * → **全量 change 死锁**（严重度高于零聚合 abort：后者只影响纯 DB change）。
+ */
+export const ENDPOINT_HEADERS = new Set(['端点', 'Endpoint', 'API', '接口']);
+
+/** 强调标记剥离：`**x**` / `__x__` / `*x*` / `_x_` → `x`（首尾成对才剥离；长的优先）。 */
+function stripEmphasis(s) {
+  let out = s;
+  for (const [open, close] of [['**', '**'], ['__', '__'], ['*', '*'], ['_', '_']]) {
+    if (out.length > open.length + close.length && out.startsWith(open) && out.endsWith(close)) {
+      out = out.slice(open.length, -close.length).trim();
+    }
+  }
+  return out;
+}
+
+/**
+ * 解析一行 markdown 表格为单元格数组（去反引号 + 剥离强调标记 + trim）。非表格行返回 null。
+ *
+ * v0.53.0 §105.2.2：新增强调标记剥离。原实现只去反引号，`**\`/path\`**` 清理后残留 `**`
+ * → 首字符非 `/` → 整行漏提取。实测 C1 的 `update/status`、`reset/secret` 两条**新增**
+ * 端点因此丢失——即**最重要的增量端点最容易被漏掉**。
+ */
 export function parseTableRow(line) {
   const trimmed = line.trim();
   if (!trimmed.startsWith('|') || !trimmed.endsWith('|')) return null;
   return trimmed
     .slice(1, -1)
     .split('|')
-    .map(cell => cell.trim().replace(/`/g, '').trim());
+    .map(cell => stripEmphasis(cell.trim().replace(/`/g, '').trim()).trim());
 }
 
 /**
@@ -43,46 +109,259 @@ export function parseTableAfter(content, headingRe) {
 }
 
 /**
- * 从 api.md 提取端点（Command/Read/Query 三段表格）。
- * 容错：匹配路径单元格（`/xxx/{id}`）与方法单元格（GET/POST/PUT/DELETE/PATCH），
- * 不依赖 `/api/` 前缀硬编码（企业系统可能是 /v1/、/gateway/oms/ 等）。
+ * 章节标题分类。**未识别的标题返回 `'unknown'` 而非 `null`——即显式重置**
+ * （§105.2.6）：原实现只在匹配 Command/Read/Query 时更新 currentKind 且**从不重置**，
+ * 「前端路由契约」类标题不匹配任何模式 → 沿用更早章节（如 `### 1.3 现有 Query API`）
+ * 留下的 `Query` → C2/C3 的前端路由误报被标注为 Query 分流（**误报不仅内容错、分类也错**）。
+ * 非标题行返回 null（不动状态）。
  */
-export function extractEndpoints(apiMd) {
+function classifyHeading(line) {
+  if (!/^#{2,3}\s/.test(line)) return null;
+  if (/(Command|命令)/i.test(line)) return 'Command';
+  if (/(Read|读取)/i.test(line)) return 'Read';
+  if (/(Query|查询)/i.test(line)) return 'Query';
+  return 'unknown';
+}
+
+/**
+ * 端点提取 + 产出量对账（§104.2.1）。
+ *
+ * 返回 `{ endpoints, candidates, unmatched, sections }`；`extractEndpoints` 为兼容包装。
+ *
+ * 形态支持（§105.2 六种）：
+ * 1. 合并式单元格 `GET /path`（含尾部描述/全角括号 → **截断 + PATH_CELL_RE 复验**）
+ * 2. 强调包裹 `**\`/path\`**`（由 `parseTableRow` 统一剥离）
+ * 3. 逗号枚举 `/x/{a,b}`（`PATH_CELL_RE` 含逗号）
+ * 4. 括号后缀 `/x（svc）`（截断）
+ * 5. 章节 kind 归属（含未识别标题的显式重置）
+ * 6. 无方法即跳过 + 按 `method+path` 去重
+ */
+export function extractEndpointsDetailed(apiMd) {
   const endpoints = [];
+  const unmatched = [];
+  const sections = new Map();
+  const seen = new Set();
   const lines = apiMd.split('\n');
+
   let currentKind = 'unknown';
-  for (const line of lines) {
-    if (/^#{2,3}\s*.*(Command|命令)/i.test(line)) currentKind = 'Command';
-    else if (/^#{2,3}\s*.*(Read|读取)/i.test(line)) currentKind = 'Read';
-    else if (/^#{2,3}\s*.*(Query|查询)/i.test(line)) currentKind = 'Query';
-    if (!line.trim().startsWith('|')) continue;
+  let headingText = '(top)';
+  let currentIsAsIs = false;
+  let inTable = false;
+  let tableHeader = null;
+  let sectionIsEndpoint = false;
+  let sectionCandidates = 0;
+  let sectionEndpoints = 0;
+
+  const flushSection = () => {
+    const key = `${headingText}::${sectionIsEndpoint ? 'EP' : 'ref'}`;
+    const prev = sections.get(key) || { heading: headingText, isEndpointSection: sectionIsEndpoint, candidates: 0, endpoints: 0 };
+    prev.candidates += sectionCandidates;
+    prev.endpoints += sectionEndpoints;
+    sections.set(key, prev);
+    sectionCandidates = 0;
+    sectionEndpoints = 0;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // ---- 标题：切换 kind 与章节，并**显式重置**章节级统计 ----
+    const headingClass = classifyHeading(line);
+    if (headingClass !== null) {
+      if (inTable) flushSection();
+      currentKind = headingClass;
+      headingText = line.trim().slice(0, 60);
+      // As-Is 段（`## 1. As-Is 基线（冻结复制）` / `### 1.x 现有 …`）：这些表是
+      // **冻结复制的基线记录**，不代表本 change 的端点所有权。`conflictCheck` 必须
+      // 排除它们，否则多个 change 各自复制同一批 As-Is 端点会被误判为所有权冲突
+      // （emp-auth 实测：C2/C3 的 As-Is 段共享 5 条 `/auth/*` 端点 → C2 被阻断）。
+      currentIsAsIs = /as-?is|现有/i.test(line);
+      sectionIsEndpoint = headingClass !== 'unknown';
+      inTable = false;
+      tableHeader = null;
+      continue;
+    }
+
+    const isTableLine = line.trim().startsWith('|');
+    if (!isTableLine) {
+      if (inTable) { flushSection(); inTable = false; tableHeader = null; }
+      continue;
+    }
+
+    // ---- 表格首行 = 表头；表头行不参与提取，但参与「端点章节」的表级判定 ----
+    if (!inTable) {
+      inTable = true;
+      tableHeader = parseTableRow(line);
+      // 表级端点章节判定：首列表头**精确等于**（禁 includes/startsWith，§115.3 A-1）
+      if (tableHeader && ENDPOINT_HEADERS.has((tableHeader[0] || '').trim())) sectionIsEndpoint = true;
+      continue;
+    }
+    if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) continue; // 分隔行
+
     const cells = parseTableRow(line);
     if (!cells || cells.length === 0) continue;
-    const pathCell = cells.find(c => /^\/[\w\-/{}.]+$/.test(c));
-    if (!pathCell) continue;
-    const methodCell = cells.find(c => /^(GET|POST|PUT|DELETE|PATCH)$/i.test(c));
-    // kind：章节标题优先；若无章节标题（如 API-INDEX 生成格式），从表格分流列取
+
+    // ---- candidates 判定（§104.2.1）----
+    const mergedCell = cells.map(c => c.match(MERGED_CELL_RE)).find(Boolean);
+    const hasMethodWord = cells.some(c => HTTP_METHOD_RE.test(c) || MULTI_METHOD_RE.test(c)) || !!mergedCell;
+    const hasPathWord = cells.some(c => PATH_CELL_RE.test(c));
+    if (!hasMethodWord && !hasPathWord) continue;
+    sectionCandidates++;
+
+    // ---- 取 path / method（合并式优先，统一走「截断 + PATH_CELL_RE 复验」收口）----
+    // MERGED_CELL_RE 捕获组：1=方法，2=路径（`GET /auth/token/flush` → ['GET', '/auth/token/flush']）
+    let path = '';
+    let method = '';
+    if (mergedCell) {
+      const truncated = (mergedCell[2].match(PATH_PREFIX_RE) || [''])[0];
+      if (PATH_CELL_RE.test(truncated)) { path = truncated; method = mergedCell[1].toUpperCase(); }
+    }
+    if (!path) {
+      const pathCell = cells.find(c => PATH_CELL_RE.test(c));
+      if (pathCell) path = pathCell;
+    }
+    if (!path) {
+      if (hasMethodWord) {
+        unmatched.push({ line: i + 1, text: line.trim().slice(0, 120), section: headingText, isEndpointSection: sectionIsEndpoint, kind: 'method-no-path' });
+      }
+      continue;
+    }
+    if (!method) {
+      const methodCell = cells.find(c => HTTP_METHOD_RE.test(c) || MULTI_METHOD_RE.test(c));
+      if (methodCell) method = methodCell.split('/')[0].trim().toUpperCase();
+    }
+    // 无方法即跳过（§105.2.4）——消除前端路由误报与「半成品端点」两类噪音
+    if (!method) {
+      unmatched.push({ line: i + 1, text: line.trim().slice(0, 120), section: headingText, isEndpointSection: sectionIsEndpoint, kind: 'path-no-method' });
+      continue;
+    }
+
+    const key = `${method} ${path}`;
+    if (seen.has(key)) continue; // 去重（§105.2.6）
+    seen.add(key);
+
     const kindCell = cells.find(c => /^(Command|Read|Query)$/i.test(c));
     const kind = currentKind !== 'unknown' ? currentKind : (kindCell || 'unknown');
-    endpoints.push({ path: pathCell, method: methodCell ? methodCell.toUpperCase() : '', kind });
+    endpoints.push({
+      path, method, kind,
+      section: headingText,
+      isEndpointSection: sectionIsEndpoint,
+      isAsIs: currentIsAsIs,
+    });
+    sectionEndpoints++;
   }
-  return endpoints;
+  if (inTable) flushSection();
+
+  return {
+    endpoints,
+    candidates: [...sections.values()].reduce((n, s) => n + s.candidates, 0),
+    unmatched,
+    sections: [...sections.values()],
+  };
+}
+
+/** 兼容包装：沿用原签名（返回数组），三个既有消费方零改动。 */
+export function extractEndpoints(apiMd) {
+  return extractEndpointsDetailed(apiMd).endpoints;
+}
+
+/**
+ * 聚合表表头关键词 → 字段名。**精确匹配**（normalize 后），长的语义优先靠 Map 顺序保证。
+ * 见 §106.2：由表头决定列语义，不再由「第二列的值」决定。
+ */
+const AGG_HEADER_MAP = [
+  [['聚合id', 'aggregateid', 'aggregate', '聚合名称', '聚合'], 'id'],
+  [['聚合根', '根实体', 'root', '聚合根实体'], 'root'],
+  [['所属bc', '所属限界上下文', '所属上下文', '上下文', 'context', 'bc'], 'context'],
+  [['不变量', '关键不变量', 'invariant', 'invariants'], 'invariants'],
+  [['来源', 'source'], 'source'],
+];
+
+/** 表头归一：去空白/下划线/反引号/强调标记，转小写（中文不受影响）。 */
+function normalizeHeader(h) {
+  return (h || '').trim().replace(/[\s_*`]/g, '').toLowerCase();
+}
+
+/** 表头 → 列索引映射。未识别的字段不写入（调用方按 undefined 处理）。 */
+function mapAggregateColumns(header) {
+  const col = {};
+  header.forEach((h, i) => {
+    const n = normalizeHeader(h);
+    for (const [keys, field] of AGG_HEADER_MAP) {
+      if (col[field] !== undefined) continue;
+      if (keys.includes(n)) { col[field] = i; break; }
+    }
+  });
+  return col;
+}
+
+/**
+ * 定位聚合表（三处容错，见 §106.1 的 R2 修正）。
+ *
+ * v0.53.0 修正：R2 原为 `/^#{3,4}\s*\d*\.?\s*(聚合变更|…)/`，其中 `\d*\.?` **无法消费
+ * 子编号 `2.1` 中的 `.1`** → 实测对真实标题 `### 2.1 聚合变更` 返回 false →
+ * **R2 从未被任何实际标题命中**，所有 change 级聚合表一直靠 R3（To-Be）兜底命中。
+ * 而 R3 取的是「To-Be」标题下的**第一个表格**，若该标题下首个表不是聚合表即取错表。
+ * 修正为 `\d+(?:\.\d+)*\.?` 支持任意层级子编号。
+ */
+function locateAggregateTable(archMd) {
+  let rows = parseTableAfter(archMd, /^#{2,3}\s*\d*\.?\s*(聚合注册表|Aggregate Registry)/i);
+  if (rows.length) return rows;
+  rows = parseTableAfter(archMd, /^#{2,4}\s*(?:\d+(?:\.\d+)*\.?\s*)?(聚合变更|Aggregate Changes)/i);
+  if (rows.length) return rows;
+  return parseTableAfter(archMd, /^#{2,3}\s*\d*\.?\s*To-Be/i);
 }
 
 /**
  * 从 architecture.md 提取聚合清单。聚合 id 格式 `context:Aggregate`。
- * 兼容两种模板：
- * - 产品级「聚合注册表」：`| 聚合ID | 上下文 | 根实体 | ... |`（列1=上下文，列2=根，列5=不变量）
- * - change 级「To-Be 增量设计 §2.1 聚合变更」：`| 聚合名称 | 操作 | 聚合根 | ... | 所属 BC |`（列1=操作，列5=所属 BC）
+ *
+ * v0.53.0 §106.2：判据由「值判布局」改为「表头定位」。
+ *
+ * 原实现用**第二列的值**是否命中 `新增|修改|New|Update` 推断表布局，再据此决定后续列语义。
+ * C1 的 §2.1 写的是 `` `**extend**` ``（DDD 标准术语 + **加粗**）——**两重失配**
+ * （① 首字符 `*` 使 `^` 锚失败；② `extend` 不在词表）→ `isChange=false` → 按产品级布局
+ * 解读 → 全局台账被写入：
+ * ```
+ * | permission:FrontSystem | **extend** | SysFrontSystem（不变） | change:v1-C1 | 已落地 | emp-auth（不变） |
+ *                          ↑ 上下文取了「操作」列        ↑ 根实体取了聚合根列      ↑ 不变量取了「所属 BC」列
+ * ```
+ * **这是污染而非缺失**——错误数据进入台账比缺数据更难察觉。
+ *
+ * 表头定位后**布局判据自然消失**：change 级的 `所属 BC` 与产品级的 `上下文` 各自映射到
+ * `context`，无需推断表属于哪一类。
  */
 export function extractAggregates(archMd) {
-  let rows = parseTableAfter(archMd, /^#{2,3}\s*\d*\.?\s*(聚合注册表|Aggregate Registry)/i);
-  if (rows.length === 0) {
-    rows = parseTableAfter(archMd, /^#{3,4}\s*\d*\.?\s*(聚合变更|Aggregate Changes)/i);
+  const rows = locateAggregateTable(archMd);
+  if (rows.length === 0) return [];
+  const header = rows[0] || [];
+  const dataRows = rows.slice(1);
+  const col = mapAggregateColumns(header);
+
+  // 兜底：表头映射基本失败（< 2 个字段）→ 退回位置逻辑，但**必须告警**（不再静默猜列）
+  if (Object.keys(col).length < 2) {
+    console.warn(`  [WARN] extractAggregates 表头未识别（${header.join(' | ')}）——回退位置逻辑，可能列错位`);
+    return legacyPositionalAggregates(dataRows);
   }
-  if (rows.length === 0) {
-    rows = parseTableAfter(archMd, /^#{2,3}\s*\d*\.?\s*To-Be/i);
+
+  const aggregates = [];
+  for (const row of dataRows) {
+    const pick = f => (col[f] !== undefined ? (row[col[f]] || '').trim() : '');
+    const id = pick('id');
+    if (!id || !/^[\w]+:[\w]+$/.test(id)) continue;
+    const src = pick('source');
+    aggregates.push({
+      id,
+      context: pick('context'),
+      root: pick('root'),
+      invariants: pick('invariants'),
+      source: /^change:/.test(src) ? src : '',
+    });
   }
+  return aggregates;
+}
+
+/** 位置兜底（表头未识别时）：保持 v0.52.0 及以前的行为，仅作降级路径。 */
+function legacyPositionalAggregates(rows) {
   const aggregates = [];
   for (const row of rows) {
     const id = row[0]?.trim();
@@ -90,7 +369,6 @@ export function extractAggregates(archMd) {
     if (!/^[\w]+:[\w]+$/.test(id)) continue;
     const col1 = row[1]?.trim() || '';
     const isChange = /^(新增|修改|New|Update)/i.test(col1);
-    // source：产品级全局格式（buildCurrentStateSection 生成）列3=来源 changeName；change 级无来源列 → ''
     const source = /^change:/.test(row[3]?.trim() || '') ? row[3].trim() : '';
     aggregates.push({
       id,

package/scripts/lib/cmd-arch.mjs

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import * as archPrecheck from './arch-precheck.mjs';
+import { scaffoldGlobalLedger } from './arch-merge.mjs';
 
 const ARCH_STATE_FILE = '.team-flow/arch-state.json';
 
@@ -25,12 +26,39 @@ export async function run(args) {
   const sub = positionals[0];
   if (sub === 'init') return init(values);
   if (sub === 'show') return show(values);
+  // v0.53.0 §102.2.1 R1：全局台账脚手架（B2 Step 0 的替代，产出目标格式而非复制模板）
+  if (sub === 'scaffold') return scaffold(values);
   // v0.22 §88.3.2：架构门判据的确定性证据工具（证据 only，退出码恒 0）
   if (sub === 'precheck') return archPrecheck.run(positionals.slice(1), values);
-  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show | tf arch precheck <change-dir> [--json]');
+  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show | tf arch scaffold | tf arch precheck <change-dir> [--json]');
   process.exit(2);
 }
 
+/**
+ * v0.53.0 §102.2.1 R1：全局台账脚手架。
+ *
+ * **背景（§101.3 根因 I）**：`workflow-bootstrap` B2 Step 0 原从
+ * `skills/architecture-design/templates/` 复制 **change 级模板** 到**全局台账路径**
+ * （`architecture.md→ARCHITECTURE.md`、`api.md→API-INDEX.md` 等 5 处）。两类写入方
+ * 语义互斥且互不知情——其中 DATABASE / PHYSICAL-MODEL / INDEX 因「无条件重建」被覆盖，
+ * 而 ARCHITECTURE / API-INDEX 永久卡在模板态。更隐蔽的是：`API-INDEX.md` 模板自带的
+ * 4 条 `/api/xxx` 占位行使扫描结果非空，**连"空结果拒绝覆盖"保护都不触发**，
+ * `updateIndex` 还把这 4 行统计成 `端点数量: 4` 写进 INDEX.md。
+ *
+ * **本命令产出目标格式的空基线**（与生成器同源），而非复制模板：
+ * 脚手架产出什么格式，生成器就维护什么格式——构造上消除格式漂移。
+ *
+ * **幂等**：已存在的文件不覆盖（只补缺失）。
+ */
+function scaffold(values) {
+  const root = findRoot(values['project-root']);
+  const result = scaffoldGlobalLedger(root);
+  console.log(`全局台账脚手架：${path.join(root, 'docs', 'architecture')}`);
+  console.log(`  新建 ${result.created.length} 个：${result.created.join(', ') || '（无）'}`);
+  console.log(`  已存在跳过 ${result.skipped.length} 个：${result.skipped.join(', ') || '（无）'}`);
+  return result;
+}
+
 function findRoot(rootOpt) {
   if (rootOpt) return path.resolve(rootOpt);
   let dir = process.cwd();

package/scripts/lib/cmd-publish.mjs

@@ -124,15 +124,46 @@ function collectWhitelist(projectRoot, targets, changeDir) {
   return paths;
 }
 
+/**
+ * 白名单条目 → 仓库相对路径（**唯一实现**，v0.53.0 §115.10）。
+ *
+ * P4 复核 Minor #6：`collectWhitelist` 允许 `isAbsolute(changeDir)` 原样入列，而原先
+ * 散落在 **3 处**的 `p.replace(projectRoot + '/', '')` 对**工程外**绝对路径是**无操作**
+ * （前缀不匹配）——"相对路径"仍是绝对路径。后果：
+ *   ① `git add <abs>` / `git commit -- <abs>` → git 报 `pathspec ... is outside repository`，
+ *      再被 commit 的 catch 改写成 `git commit failed: <原消息>`（**归因错误**：真因是白名单
+ *      条目越界，不是 commit 失败）；
+ *   ② `detectOutsideDirty` 的比对集中混入绝对路径，而 `git status --porcelain` 输出恒为
+ *      仓库相对路径 → 该条目对所有文件都不匹配，覆盖比对静默失效。
+ * 三处收敛为单一实现（同属本轮根因 Ⅲ「同一契约多处各自实现」）。
+ *
+ * @returns {string|null} 相对路径；条目不在 projectRoot 之下时返回 null（越界）
+ */
+function toRelPath(p, projectRoot) {
+  const prefix = projectRoot.replace(/\/+$/, '') + '/';
+  return p.startsWith(prefix) ? p.slice(prefix.length) : null;
+}
+
+/** 严格版：越界即抛。用于会**写盘**的路径——越界属调用方/配置错误，不得静默降级为误导性报错。 */
+function toRelPathStrict(p, projectRoot) {
+  const rel = toRelPath(p, projectRoot);
+  if (rel === null) {
+    throw new Error(`白名单条目不在工程根之下，无法构造 git pathspec：${p}（projectRoot=${projectRoot}）`);
+  }
+  return rel;
+}
+
 /**
  * 检测白名单之外的未提交/未跟踪文件（团队协作安全底线，仿 arch-merge detectUntouchedDirtyFiles）。
  * 返回值：外部脏文件列表（含 staged + unstaged + untracked）。
  */
 function detectOutsideDirty(projectRoot, whitelist) {
-  const relWhitelist = new Set(whitelist.map(p => {
-    const rel = p.replace(projectRoot + '/', '');
-    return rel.replace(/\/+$/, '');
-  }));
+  // 越界条目（toRelPath 返回 null）对仓库相对路径的比对无贡献，直接剔除；
+  // 写盘侧的越界由 toRelPathStrict 提前拦下，不会走到这里。
+  const relWhitelist = new Set(whitelist
+    .map(p => toRelPath(p, projectRoot))
+    .filter(r => r !== null)
+    .map(r => r.replace(/\/+$/, '')));
   try {
     const status = git(projectRoot, 'status', '--porcelain');
     if (!status) return [];
@@ -247,13 +278,29 @@ export async function run(args = []) {
   try {
     // 白名单 git add（只 add 目标目录）
     for (const p of whitelist) {
-      const rel = p.replace(projectRoot + '/', '');
+      const rel = toRelPathStrict(p, projectRoot);
       execFileSync('git', ['add', rel], { cwd: projectRoot, stdio: 'pipe' });
     }
     // commit（nothing to commit 可接受）
+    const relPaths = whitelist.map(p => toRelPathStrict(p, projectRoot));
     try {
-      execFileSync('git', ['commit', '-m', commitMsg], { cwd: projectRoot, stdio: 'pipe' });
+      // v0.53.0 §109.2 R9：commit 必须带 pathspec。
+      // 裸 `git commit` 提交索引中**全部已暂存内容**——索引里若有他人/前序工具留下的
+      // staged 文件会被一并卷走。arch-merge 已在 v0.23 §93.3.2 修复同类问题，
+      // 而 cmd-publish 只复用了白名单的 **add** 侧、**未复用 commit 侧**（本文件头部
+      // 注释自称「复用 arch-merge 协作安全模式」，实际只复用了半套）。
+      execFileSync('git', ['commit', '-m', commitMsg, '--', ...relPaths], { cwd: projectRoot, stdio: 'pipe' });
       console.log(`✅ committed: ${commitMsg}`);
+
+      // 第二道防线（仿 arch-merge v0.23 §93.3.3）：回读实际提交清单与白名单比对。
+      // 不阻断（提交已完成），但白名单外文件必须可见。
+      const committed = execFileSync('git', ['show', '--name-only', '--format=', 'HEAD'],
+        { cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\n').filter(Boolean);
+      const wl = relPaths.map(r => r.replace(/\/+$/, ''));
+      const unexpected = committed.filter(p => !wl.some(w => p === w || p.startsWith(w + '/')));
+      if (unexpected.length > 0) {
+        console.warn(`[WARN] 本次 commit 含白名单外的文件（${unexpected.length} 个）：${unexpected.slice(0, 5).join(', ')}${unexpected.length > 5 ? ' …' : ''}`);
+      }
     } catch (e) {
       // git 空提交消息在 stdout（execFileSync 失败时 stderr 常为空 Buffer，需先排除空值）
       const msg = (e.stderr && e.stderr.toString()) || (e.stdout && e.stdout.toString()) || '';

package/scripts/lib/cmd-state.mjs

@@ -40,6 +40,8 @@ const SETTABLE_FIELDS = [
   'test_matrix_skipped', 'test_matrix_skip_reason',
   // Tasks gate (v0.22 §85：hotfix/tweak 显式跳过 tasks.md，须附理由)
   'tasks_skipped', 'tasks_skip_reason',
+  // Arch merge gate (v0.53.0 §110.2：arch-merged guard 维度的显式跳过键，须附理由)
+  'arch_merge_skipped', 'arch_merge_skip_reason',
 ];
 
 export async function run(args) {

package/scripts/lib/prototype-sync.mjs

@@ -11,7 +11,8 @@
  * 3. 若涉及设计系统迭代（新组件/token/anti-pattern），合并进 prototype/design-system.md
  * 4. 输出合并报告
  *
- * 回写顺序：arch-merge → prototype-sync（同一 change closing 内，顺序提交）
+ * 回写顺序：arch-merge → state transition closing → prototype-sync → test-merge → compound promotion
+ * （同一 change closing 内顺序执行；状态转换位次由 v0.53.0 §110 B' 时序前移确定）
  */
 
 import { readFileSync, writeFileSync, existsSync, cpSync, mkdirSync } from 'node:fs';

package/scripts/lib/state-loader.mjs

@@ -77,6 +77,12 @@ const BUILTIN_DEFAULTS = {
   // Tasks gate (v0.22 §85：hotfix/tweak 跳过 spec-writer 时显式跳过 tasks.md)
   tasks_skipped: null,
   tasks_skip_reason: null,
+  // Arch merge gate (v0.53.0 §110.2 加固 iii：arch-merged guard 维度的显式跳过键)
+  // 与 tasks_skipped / test_matrix_skipped 同一模式。用于 arch-merge 确为 no-op 的场景
+  // （如 change 的 architecture.md 无演进日志段且无聚合增量 → 全局台账不会出现
+  // `change:<name>`，若不给跳过键则 guard 永久 FAIL 无出路）。
+  arch_merge_skipped: null,
+  arch_merge_skip_reason: null,
   // 注意：schema_version 故意不在 BUILTIN_DEFAULTS 中（v0.13 §48.1）——
   // 它只由 `tf state init` 在 change 创建时打戳，字段缺失本身就是"存量 change"信号。
 };
@@ -203,6 +209,10 @@ export function writeState(changeDir, state) {
   lines.push('# === Tasks gate (v0.22 §85) ===');
   lines.push(`tasks_skipped: ${state.tasks_skipped ?? 'null'}`);
   lines.push(`tasks_skip_reason: ${state.tasks_skip_reason ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Arch merge gate (v0.53.0 §110.2) ===');
+  lines.push(`arch_merge_skipped: ${state.arch_merge_skipped ?? 'null'}`);
+  lines.push(`arch_merge_skip_reason: ${state.arch_merge_skip_reason ?? 'null'}`);
 
   fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
 }

package/scripts/lib/test-merge.mjs

@@ -13,7 +13,7 @@
  * 5. rewriteIndex — 统计模块数/case 数/deferred 数，重写 INDEX.md
  * 6. gitCommit — 单次原子提交
  *
- * 回写顺序：arch-merge → prototype-sync → test-merge → compound promotion
+ * 回写顺序：arch-merge → state transition closing → prototype-sync → test-merge → compound promotion
  *
  * v0.38.0（feedback 2026-08-05 修复 + E2E 层级）：
  * - resolveDeferred 只删 Deferred Items 段内被覆盖行（原全文件 regex 误删 Current Cases）

package/scripts/team-flow.mjs

@@ -67,6 +67,7 @@ Commands:
   arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>]
                         Stamp project-level arch_baseline into .team-flow/arch-state.json (v0.35.0 §59.4)
   arch show             Show current project architecture baseline state
+  arch scaffold         Scaffold global docs/architecture/ ledger in generator format (v0.53.0 §102)
   arch precheck <change-dir> [--json]
                         Emit deterministic architecture-gate evidence (v0.22 §88; evidence only, exit 0)
   arch-merge <change-dir> [--project-root <path>] [--dry-run]
@@ -198,7 +199,19 @@ async function main() {
   }
 
   const mod = await COMMANDS[command]();
-  await mod.run(commandArgs);
+  const result = await mod.run(commandArgs);
+  // v0.53.0 §104.2.3：命令以结构化失败结果结束 → 传播非零退出码。
+  //
+  // 背景：`arch-merge` 的 `[FAIL]` 汇总与 `arch-merge FAILED: N failure(s).` 消息
+  // 原本只在 `import.meta.url === process.argv[1]` 的**直调块**里设 `process.exitCode`，
+  // 而经 `tf` 调用走的是本 dispatcher（不消费返回值）→ **`tf arch-merge` 实测恒 exit 0**，
+  // 与 SKILL.md 承诺的"可能以非零退出码结束"不符，`tf arch-merge <dir> && tf state
+  // transition closing` 这类链式写法拿不到失败信号。
+  //
+  // 放在 dispatcher 而非 `run()` 内：`run()` 被 import 时不应设全局 exitCode
+  // （既有测试守护 "does not set process.exitCode when imported"）。
+  // 守卫 `Array.isArray(result.failures)`：仅对返回该结构的命令生效，其余命令不受影响。
+  if (result && Array.isArray(result.failures) && result.failures.length > 0) process.exitCode = 1;
 }
 
 main().catch(err => {

package/skills/architecture-design/templates/api.md

@@ -30,23 +30,29 @@ api_contract_manager: swagger
 
 ## 2. To-Be 增量设计
 
+> ⚠ **占位符必须替换**：示例行的路径写作 `<endpoint>` 形式而非 `/api/xxx` 这类**看起来像真实路径**的字符串。
+> 原因（v0.53.0 §115.6）：`/api/xxx` 是**合法的路径形状**，arch-merge 的端点提取器会**正常提取**它，
+> 且新加的"候选>0 且提取=0 → 失败"与"覆盖率<0.5 → 告警"两条对账判据**都不会触发**
+> （占位行被当作真实端点）。后果是占位符被计入全局 `API-INDEX.md` 与 `INDEX.md` 的「端点数量」
+> ——与 v0.25 §101.3 记录的症状同源。`<endpoint>` 不以 `/` 开头，提取器天然拒绝。
+
 ### 2.1 Command API（改状态）
 
 | 端点 | 方法 | 聚合 | 事务边界 | 说明 |
 |------|------|------|---------|------|
-| /api/xxx | POST | XxxAggregate | t_xxx 事务 | 简要说明 |
+| `<endpoint>` | POST | XxxAggregate | t_xxx 事务 | 简要说明 |
 
 ### 2.2 Read API（有逻辑不改状态）
 
 | 端点 | 方法 | 聚合 | 数据来源 | 说明 |
 |------|------|------|---------|------|
-| /api/xxx/{id}/detail | GET | XxxAggregate | t_xxx + JOIN | 简要说明 |
+| `<endpoint>/{id}` | GET | XxxAggregate | t_xxx + JOIN | 简要说明 |
 
 ### 2.3 Query API（纯查询）
 
 | 端点 | 方法 | 查询模型 | 阻断测试 | 说明 |
 |------|------|---------|---------|------|
-| /api/dashboard/xxx-stats | GET | XxxStatsView | 阻断=继续 → 数据服务 | 简要说明 |
+| `<endpoint>` | GET | XxxStatsView | 阻断=继续 → 数据服务 | 简要说明 |
 
 > **阻断测试说明**：将服务阻断 1h，下游不能继续 → 业务服务；能继续 → 数据服务
 
@@ -56,7 +62,7 @@ api_contract_manager: swagger
 
 | API 端点 | 对应数据实体 | 对齐状态 | 不一致说明 |
 |---------|------------|---------|-----------|
-| /api/xxx | t_xxx | ✅ 对齐 | — |
+| `<endpoint>` | t_xxx | ✅ 对齐 | — |
 
 ### 3.1 术语命名统一性