@xulthekl/team-flow 0.51.1 → 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

@@ -54,9 +54,19 @@ function parseArgv(argv) {
   return parsed;
 }
 
-/** git 执行封装（统一 encoding + 错误降级）。 */
+/**
+ * git 执行封装（统一 encoding）。
+ *
+ * v0.24 §98.3.1：**只裁首尾换行，不用 `.trim()`**。`status --porcelain` 是固定宽度
+ * 格式，首行可能是 ` M path`（X 位空格 = 未暂存修改）——`.trim()` 会吃掉行首空格，
+ * 令 parsePorcelainPaths 的 `slice(3)` 切掉路径首字符（`changes/…` → `hanges/…`），
+ * 路径损坏 → 白名单失配 → 误报「白名单之外存在未提交文件」（而 git add 用的白名单
+ * 未损坏，文件实际被提交，形成"告警与行为不一致"）。
+ * 对 `branch --show-current` / `rev-parse` 等单行输出，只裁尾换行与 trim 等效。
+ */
 function git(cwd, ...args) {
-  return execFileSync('git', args, { encoding: 'utf-8', cwd, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  return execFileSync('git', args, { encoding: 'utf-8', cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    .replace(/^[\r\n]+|[\r\n]+$/g, '');
 }
 
 function isDir(p) {
@@ -114,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 [];
@@ -147,7 +188,10 @@ function detectOutsideDirty(projectRoot, whitelist) {
         }
         return true;
       });
-  } catch {
+  } catch (e) {
+    // v0.24 §98.3.2：解析失败不得静默（旧实现静默返回 [] = 漏报）。提交主流程不受影响，
+    // 但必须让使用者知道"本次白名单外检测未生效"，改以 git status 原始输出人工核对。
+    console.warn(`[WARN] 白名单外脏文件检测失败（${e.message}）——本次不输出该告警，提交范围仍以白名单为准。`);
     return [];
   }
 }
@@ -209,7 +253,9 @@ export async function run(args = []) {
   // 脏文件检测（target 之外）→ 告警不阻断
   const outsideDirty = detectOutsideDirty(projectRoot, whitelist);
   if (outsideDirty.length > 0) {
-    console.warn(`[WARN] 白名单之外存在 ${outsideDirty.length} 个未提交文件（不提交）：`);
+    // v0.24 §98：文案中性化（与 v0.51.0 arch-merge 同类处理对齐）——「不提交」易被误读为
+    // 永久不提交（这些文件可能由其他流程提交），准确表述为「本次不提交 + 范围以白名单为准」。
+    console.warn(`[WARN] 白名单之外存在 ${outsideDirty.length} 个未提交文件（本次不提交，提交范围以白名单为准）：`);
     for (const f of outsideDirty.slice(0, 5)) console.warn(`  - ${f}`);
     if (outsideDirty.length > 5) console.warn(`  ... 等 ${outsideDirty.length} 个`);
   }
@@ -232,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) {