@xulthekl/team-flow 0.54.0 → 0.56.0

package/scripts/lib/ds-parse.mjs

@@ -1,7 +1,15 @@
-// ds-parse.mjs — 设计系统文档解析（公共模块，v0.54.0）
+// ds-parse.mjs — 设计系统文档解析（公共模块，v0.55.0）
 //
-// 供 design-token-guard.mjs / gen-primer.mjs 复用（避免多份重复解析）。
+// 供 design-token-guard.mjs / gen-primer.mjs / design-system-import.mjs 复用。
 // 纯函数，无副作用。
+//
+// v0.55.0（FB-4 修复）：全部解析点接入 md-normalize 共享层。
+// 原实现对 Markdown 强调语法脆弱且**失败静默**——`- **contract**: v1` 解析不出值，
+// 被判 unset → guard 降级 + primer 头部错报，无任何提示。根因与同类复发史见
+// md-normalize.mjs 头注。本文件另提供 *Diag 函数，把"段存在但解析不出"变成**显式告警**
+// （纯函数不打印，由调用方决定输出通道）。
+
+import { normalizeInline, stripInlineEmphasis, matchKeyValue } from './md-normalize.mjs';
 
 // 组件契约表分组规则（§4.1.1）：类型 → states 下限（null = 豁免）
 export const COMPONENT_TYPE_MIN_STATES = { '交互': 3, '轻量': 2, '豁免': null };
@@ -40,16 +48,50 @@ export function sectionBodyRaw(markdown, section) {
   return body.join('\n');
 }
 
+/**
+ * Return the raw body of an **H3 subsection** inside a section (v0.55.0 新增).
+ *
+ * 动机：`layout` 段同时承载 栅格/断点 + 容器骨架 + 页面范式 三块（设计 §8.2.2）。
+ * L4b 若要按"页面类型表行数"判定，必须**只在 `### 页面范式` 子块内计数** ——
+ * 按整段计数会把容器骨架表/断点表的行也数进去，产生**假 PASS**
+ * （实测：现场 b-end.md 的 layout 段已有 2 张表 8 行，8 ≥ 3 直接误判达标）。
+ *
+ * 切片语义：从 `### <sub>` 起，到下一个 `###` 或 `##` 或 EOF 止；
+ * `#### ` 不截断（`/^###?\s+/` 不匹配 `####`——回溯后 `\s+` 无法匹配 `#`）。
+ */
+export function subsectionBodyRaw(markdown, section, sub) {
+  const sectionRaw = sectionBodyRaw(markdown, section);
+  if (sectionRaw === null) return null;
+  const lines = sectionRaw.split('\n');
+  const startIdx = lines.findIndex(line => {
+    const m = /^###\s+(.*)$/.exec(line);
+    return m && m[1].trim().toLowerCase().includes(sub);
+  });
+  if (startIdx === -1) return null;
+  const body = [];
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (/^###?\s+/.test(lines[i]) && !/^####/.test(lines[i])) break;
+    body.push(lines[i]);
+  }
+  return body.join('\n');
+}
+
 // Lower-cased section body.
 export function sectionBody(markdown, section) {
   const raw = sectionBodyRaw(markdown, section);
   return raw === null ? null : raw.toLowerCase();
 }
 
-// Parse a markdown table row into trimmed cells; null when not a data row.
+/**
+ * Parse a markdown table row into trimmed cells; null when not a data row.
+ *
+ * v0.55.0：接入共享归一化层（去反引号 + 剥强调）——与 arch-parse.mjs 的
+ * 同型实现统一。此前本函数不剥强调，导致 `| **交互** |` 这类单元格无法匹配类型表，
+ * **整行静默漏计**（FB-4 实测复现）。
+ */
 export function parseTableRow(line) {
   if (!/^\s*\|/.test(line)) return null;
-  const cells = line.split('|').slice(1, -1).map(c => c.trim());
+  const cells = line.split('|').slice(1, -1).map(c => normalizeInline(c.trim()));
   if (cells.length === 0) return null;
   if (cells.every(c => /^:?-{2,}:?$/.test(c))) return null;
   return cells;
@@ -90,35 +132,105 @@ export function parseComponentsTable(markdown) {
   return rows.length > 0 ? { rows } : null;
 }
 
+/** contract 取值的接受形态（v0.55.0 放宽）：`v1` / `v2` / … / `legacy`。 */
+const CONTRACT_VALUE_RE = /^(v\d+|legacy)$/i;
+
 // Parse governance section for the `contract` marker (§4.1.3).
-// Returns 'v1' | 'legacy' | null.
+// Returns 形如 'v1' | 'legacy' | 'v2' | null（**未知值不再静默归 null**）。
+//
+// v0.55.0：容忍 `**contract**:` / `` `contract`: `` / 全角冒号 / 表格形态；
+// 值域由 `v1|legacy` 放宽为任意 `v\d+`，未知值交由 guard 按最严档处理 + WARN。
 export function parseContract(markdown) {
   const body = sectionBodyRaw(markdown, 'governance');
   if (!body) return null;
-  const m = body.match(/contract\s*[:：]\s*(v1|legacy)/i);
-  return m ? m[1].toLowerCase() : null;
+  // 形态 1：key: value（含各种格式变体）
+  const kv = matchKeyValue(body, 'contract');
+  if (kv) {
+    const v = kv.match(CONTRACT_VALUE_RE);
+    if (v) return v[1].toLowerCase();
+  }
+  // 形态 2：表格 `| contract | v1 |`
+  for (const line of body.split('\n')) {
+    const cells = parseTableRow(line);
+    if (!cells || cells.length < 2) continue;
+    if (!/^contract$/i.test(cells[0])) continue;
+    const v = cells[1].match(CONTRACT_VALUE_RE);
+    if (v) return v[1].toLowerCase();
+  }
+  return null;
+}
+
+/**
+ * 诊断：governance 段**存在且提到 contract**，但解析不出取值。
+ * 返回警告文本或 null（纯函数——由调用方决定输出到 stderr/stdout）。
+ *
+ * 动机：FB-4 的核心痛点是**静默**——用户"已知自己写的是 v1 却显示 unset"，
+ * 靠对照才发现是格式问题。本函数把这种情形变成显式信号。
+ */
+export function contractFormatWarning(markdown) {
+  const body = sectionBodyRaw(markdown, 'governance');
+  if (!body) return null;                        // 段缺失 → 另一类问题，不在此报
+  if (parseContract(markdown)) return null;      // 解析成功 → 无警告
+  if (!/contract/i.test(body)) return null;      // 未提及 → 无警告
+  return '检测到 governance 段含 contract 字样但未能解析出取值，请检查格式（应为 `contract: v1`；'
+    + '容忍 `**contract**:` / 反引号 / 全角冒号）';
 }
 
 // Parse the A1 identity token block from a token/spec section (for primer 速查).
 // Looks for `--token: value` pairs anywhere in the markdown.
+// v0.55.0：接入共享层（容忍 `**--accent**:` / 反引号 等写法）。
 export function parseA1Tokens(markdown) {
   const names = ['--bg', '--surface', '--fg', '--muted', '--border', '--accent', '--font-display', '--font-body'];
   const out = {};
   for (const name of names) {
-    const re = new RegExp(`${name.replace(/-/g, '\\-')}\\s*[:：]\\s*([^;\\n]+)`, 'i');
-    const m = markdown.match(re);
-    if (m) out[name] = m[1].trim().replace(/\s+$/, '');
+    const v = matchKeyValue(markdown, name);
+    if (v) out[name] = v.trim().replace(/\s+$/, '');
   }
   return out;
 }
 
-// Extract the anti-patterns section as a list of bullet/numbered items.
+/**
+ * 解析**页面范式声明**（v0.55.0，设计 §8.2.2 / §8.2.5）。
+ *
+ * 承载点：`layout` 段内的 `### 页面范式` 子块 —— 选 `layout` 是因为它是**必填段**，
+ * 单文件模式（转换器产物）也必然含它，不依赖变体合并（原方案新增独立段在单文件模式下
+ * 永远不可见且静默）。
+ *
+ *   ### 页面范式
+ *   **页面范式来源**：引用内置 | 项目自有 | 同 <端>
+ *   | 页面类型 | 骨架/容器组合 | 参考 |
+ *
+ * **只在子块内计数表行**（表行数 = 页面类型数）：按 layout 段整段计数会把
+ * 容器骨架表 / 断点表的行也数进去——现场实测该段已有 2 表 8 行，8 ≥ 3 会**假 PASS**。
+ *
+ * @returns {{declared: boolean, source: string|null, tableRows: number, subPresent: boolean}}
+ */
+export function parsePageArchetype(markdown) {
+  const sub = subsectionBodyRaw(markdown, 'layout', '页面范式');
+  if (sub === null) return { declared: false, source: null, tableRows: 0, subPresent: false };
+  const raw = matchKeyValue(sub, '页面范式来源');
+  // 表格行数 = **数据行**（排除表头）。parseTableRow 已滤掉分隔行（`|---|`），
+  // 但表头行仍会被匹配 → 子块内**首个表格行视为表头**跳过。
+  const tableLines = sub.split('\n').map(parseTableRow).filter(Boolean);
+  const tableRows = Math.max(0, tableLines.length - (tableLines.length > 0 ? 1 : 0));
+  return {
+    declared: Boolean(raw),
+    source: raw ? raw.replace(/\s+/g, '') : null,
+    tableRows,
+    subPresent: true,
+  };
+}
+
+/**
+ * Extract the anti-patterns section as a list of bullet/numbered items.
+ * v0.55.0：容忍整行被强调包裹（`**- item**`）——先剥行内强调再匹配列表符。
+ */
 export function parseAntiPatterns(markdown) {
   const body = sectionBodyRaw(markdown, 'anti-patterns');
   if (!body) return [];
   return body
     .split('\n')
-    .map(l => l.trim())
+    .map(l => stripInlineEmphasis(l.trim()))
     .filter(l => /^([-*]|\d+[.、)])\s+\S/.test(l))
     .map(l => l.replace(/^([-*]|\d+[.、)])\s+/, ''));
 }

package/scripts/lib/execution-recommendation.mjs

@@ -8,6 +8,7 @@ import { computeArtifactsHash, computeContractHash, hashObject, stableJson } fro
 import { getOverlayPaths } from './sdd-overlay.mjs';
 import { readState } from './state-loader.mjs';
 import { EXECUTION_MODES } from './execution-plan.mjs';
+import { parseTaskLine } from './md-normalize.mjs';
 
 // v2.1 §6.6（二轮评审 HIGH）：recommend 链补全
 // - GLAF4 change 的 recommend 恒为"推荐 inline + available_modes 含 glaf4-delegation"
@@ -151,10 +152,18 @@ export function validateRecommendationReceipt(changeDir, receipt, waves = [], ex
   return failures;
 }
 
+/**
+ * tasks.md 中已记录的 task 数（DP-4 推荐的事实输入之一）。
+ *
+ * v0.55.0 §8.4.3 横展（FB-4）：识别走共享原语 `parseTaskLine`——原正则要求
+ * `- [x] `（`]` 后必须跟空格）且不容缩进，`*` bullet / 缩进行 / `- [x]正文` 全部漏计。
+ * **计数语义**（约束③：会改变 inline / batch-inline / sdd 的推荐结果）。
+ */
 function countDocumentedTasks(changeDir) {
   const tasksPath = join(changeDir, 'tasks.md');
   if (!existsSync(tasksPath)) return null;
-  return (readFileSync(tasksPath, 'utf8').match(/^- \[[ xX]\] /gm) || []).length;
+  return readFileSync(tasksPath, 'utf8').split('\n')
+    .map(line => parseTaskLine(line)).filter(Boolean).length;
 }
 
 function result(availableModes, mode, reasons, facts) {

package/scripts/lib/glaf4-delegation.mjs

@@ -33,6 +33,7 @@ import { getOverlayPaths } from './sdd-overlay.mjs';
 import { detectGlaf4Delegation, detectTechStack, writeGlaf4DevConfig } from './conventions-generator.mjs';
 import { detectWorkspaceRoot, getGitRoot, resolveCodeRepos } from './git-utils.mjs';
 import { loadConfig } from './config-loader.mjs';
+import { parseTaskLine, stripInlineEmphasis } from './md-normalize.mjs';
 
 // DP-4 委托模式合法枚举（对应 glaf4-dev 七模式中可委托 change 的六种）
 export const GLAF4_DELEGATION_MODES = [
@@ -372,8 +373,18 @@ export function recordPartialWrites(changeDir, runDir) {
   return { ok: true, partialWrites, count: partialWrites.length };
 }
 
+/**
+ * `· targets:` 注解判定（`·` 是结构标记，不放宽；容忍 `**targets**` 加粗与全角冒号）。
+ */
+function hasTargetsAnnotation(text) {
+  return /·\s*targets\s*[:：]/.test(stripInlineEmphasis(text));
+}
+
 /**
  * task 完成度对账（审计输出）：tasks.md targets 注解统计
+ *
+ * v0.55.0 §8.4.3 横展（FB-4）：识别走共享原语 `parseTaskLine`——容忍 `*` bullet、
+ * 制表符分隔与缩进（原本 `^- \[` 不容缩进）。**计数语义**（约束③：派生数字会变）。
  * @param {string} changeDir change 目录
  * @returns {object} { ok, totalTasks, doneTasks, annotatedTasks, missingAnnotation }
  */
@@ -383,10 +394,10 @@ export function verifyTasks(changeDir) {
     return { ok: false, totalTasks: 0, doneTasks: 0, annotatedTasks: 0, missingAnnotation: 0 };
   }
   const content = readFileSync(tasksPath, 'utf-8');
-  const taskLines = content.split('\n').filter(l => /^- \[[ xX]\] /.test(l));
+  const taskLines = content.split('\n').map(line => parseTaskLine(line)).filter(Boolean);
   const totalTasks = taskLines.length;
-  const doneTasks = taskLines.filter(l => /^- \[[xX]\] /.test(l)).length;
-  const annotatedTasks = taskLines.filter(l => /·\s*targets:\s*/.test(l)).length;
+  const doneTasks = taskLines.filter(task => task.checked).length;
+  const annotatedTasks = taskLines.filter(task => hasTargetsAnnotation(task.text)).length;
 
   return {
     ok: doneTasks === totalTasks && totalTasks > 0,

package/scripts/lib/hash.mjs

@@ -3,6 +3,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { findCanonicalSpecFiles } from './spec-paths.mjs';
+import { parseTaskLine } from './md-normalize.mjs';
 
 /**
  * Normalize tasks.md checkbox state: `- [x]` / `- [X]` → `- [ ]`.
@@ -12,9 +13,20 @@ import { findCanonicalSpecFiles } from './spec-paths.mjs';
  * 勾选状态属执行进度、不属规划内容 —— 归一化后入 hash，使"执行期勾选"不再使 plan
  * 过期（否则勾选后 recordReview 因 plan stale 抛错，形成 closing 死锁）。
  * 任务文本、数量与结构的变更仍会改变 hash。
+ *
+ * v0.55.0 §8.4.3 横展（FB-4）：识别改用共享原语 `parseTaskLine`（容忍 `*` bullet /
+ * 缩进 / 制表符等纯格式变体），但**语义保持"替换式"**——只把复选框标记改回 `[ ]`，
+ * 行的其余字符（缩进、bullet 符号、分隔空白、正文、行尾 `\r`）**逐字节保留**，
+ * 因此该函数**不是**计数函数、不重建行。
  */
 export function normalizeCheckboxes(content) {
-  return content.replace(/^([ \t]*- )\[[xX]\]/gm, '$1[ ]');
+  return content.split('\n').map((line) => {
+    const task = parseTaskLine(line);
+    if (!task || !task.checked) return line;
+    const at = line.indexOf('[');
+    if (at === -1) return line;
+    return `${line.slice(0, at + 1)} ${line.slice(at + 2)}`;
+  }).join('\n');
 }
 
 /**
@@ -130,9 +142,13 @@ export function isContractFresh(changeDir, stateLoader) {
   return storedHash === currentHash;
 }
 
+// v0.55.0 §8.4.3 横展（FB-4）：容忍全角冒号（`artifacts_hash：sha256:…`）。
+// 这是 `isContractFresh` 的判据——解析不出即判 stale，静默且后果重（closing 死锁）。
+// 仅放宽冒号形态（与 `md-normalize.matchKeyValue` 的全角冒号约定一致），
+// 不引入缩进等结构语义容忍（约束①）。
 function extractYamlField(content, field) {
   for (const line of content.split('\n')) {
-    const match = line.match(new RegExp(`^${field}:\\s*(.*)`));
+    const match = line.match(new RegExp(`^${field}[:：]\\s*(.*)`));
     if (match) {
       const val = match[1].trim();
       return val === 'null' || val === '' ? null : val;

package/scripts/lib/md-normalize.mjs

@@ -0,0 +1,108 @@
+// md-normalize.mjs — 手写 Markdown 的解析容错共享层（v0.55.0）
+//
+// ── 为什么存在（根因，workflow-feedback 2026-09-11 FB-4）──────────────────────
+// 解析层默认"用户会按规范格式书写"，对最常见的 Markdown 强调语法（`**x**`、
+// 反引号、表格）脆弱，且**失败静默**。实测：`- **contract**: v1` 与 `` `contract`: v1 ``
+// 都解析不出值，被判 unset → guard 降级、primer 头部错报，全程无任何提示。
+//
+// 该缺陷是**复发型**，不是孤立疏漏——同型 bug 已修过两次，且两次都未横展：
+//   - arch-parse.mjs:58-66（v0.53.0 §105.2.2）：表格单元格缺 stripEmphasis
+//     → 新增端点 `update/status` / `reset/secret` 整行漏提取
+//   - test-merge.mjs:79-89（feedback 2026-08-05）：正则未容忍 `\*{0,2}`
+//     → 手写加粗致 Total cases 计数归零
+//
+// 本模块是**全仓库唯一的 Markdown 归一化约定**（单一真相源）。新解析点一律复用，
+// 不再各写各的正则——避免第三次复发。
+//
+// ── 三条安全约束（设计 §8.4.3，D-16「全修」决策的配套）───────────────────────
+//   ① 宽容 ≠ 放宽语义：只容忍**纯格式变体**（`**`/反引号/全角冒号/冒号前空格），
+//      **不改变结构语义**。例：YAML 缩进是语义，不得在此层容忍。
+//   ② 宽容 + 校验配对，但缺字段一律 WARN（不报错）——避免打断被测试断言的既有契约。
+//   ③ 派生数字变更须先出对照表（计数型解析点的宽容会改变判定，见 parseTaskLine 注）。
+
+/**
+ * 强调标记剥离：`**x**` / `__x__` / `*x*` / `_x_` → `x`（**首尾成对**才剥离；长的优先）。
+ *
+ * 实现自 arch-parse.mjs（v0.53.0 §105.2.2），此处提为共享层。
+ * 适用于**整段/整格**的首尾包裹场景（如 `**\`/path\`**`）。
+ */
+export 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;
+}
+
+/**
+ * 行内强调剥离（**全局**，非首尾）：`- **contract**: v1` → `- contract: v1`。
+ *
+ * 与 {@link stripEmphasis} 的分工：后者只处理"整段被一对标记包裹"，本函数处理
+ * "一行内嵌着一对标记"——这是 key/value 行的常见写法，也是 FB-4 的实际触发形态。
+ *
+ * **只剥离双符号对（`**` / `__`）**，单符号（`*` / `_`）刻意不动：
+ * `*` 可能是列表符、`_` 可能是 snake_case 标识符——剥离它们是"改语义"而非"容格式"，
+ * 违反安全约束 ①。
+ */
+export function stripInlineEmphasis(text) {
+  if (typeof text !== 'string') return '';
+  return text.replace(/\*\*(.+?)\*\*/g, '$1').replace(/__(.+?)__/g, '$1');
+}
+
+/**
+ * 行内归一化：去反引号 + 剥强调 + trim。用于单元格与 key/value 两侧。
+ */
+export function normalizeInline(s) {
+  if (typeof s !== 'string') return '';
+  return stripEmphasis(stripInlineEmphasis(s.replace(/`/g, '')).trim()).trim();
+}
+
+/**
+ * 宽容匹配 `key: value`，返回首个捕获值或 null。
+ *
+ * 容忍的写法（FB-4 的 5 种格式变体）：
+ *   a. `**key**: value`   —— 加粗（**本函数的主要动机**）
+ *   b. `key：value`       —— 全角冒号
+ *   c. `` `key`: value `` —— 反引号
+ *   d. `key : value`      —— 冒号前空格
+ *   （e. 表格形态 `| key | value |` 不在此处理——用 ds-parse 的表格路径）
+ *
+ * @param {string} text 待搜索文本（整段或整行均可）
+ * @param {string} key  键名（可含 `-`，如 `--bg`）
+ */
+export function matchKeyValue(text, key) {
+  if (typeof text !== 'string' || !key) return null;
+  const normalized = stripInlineEmphasis(text).replace(/`/g, '');
+  const escaped = key.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+  const m = normalized.match(new RegExp(`${escaped}\\s*[:：]\\s*([^;\\n|]+)`, 'i'));
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * 任务行解析**原语**（复选框）：`- [ ] x` / `* [x] x` / 缩进子项 → `{ indent, checked, text }`；
+ * 非任务行返回 null。
+ *
+ * **本函数不做语义判定** —— 全仓库 5 处复选框解析语义并不同（原方案误判为"同语义"）：
+ *   - `hash.mjs` 的 `normalizeCheckboxes` 是**替换式归一化**（保证勾选不改变 artifacts_hash）
+ *   - `tasks-complete.mjs` / `glaf4-delegation.mjs` / `execution-recommendation.mjs` /
+ *     `infer-workflow.mjs` 是**计数/存在性判定**
+ * 故只共享"识别"，语义由调用方决定。
+ *
+ * **安全约束 ③ 提醒**：把本函数接入计数型解析点会**改变派生数字** →
+ * `infer-workflow.mjs` 的 `taskCount` 直接决定 hotfix(≤2) / tweak(≤4) / full 档位。
+ * 接入前须先出**新旧计数对照表**（构造的格式变体集，见 tests/lib/checkbox-consistency.test.mjs）。
+ *
+ * **CRLF 容错（`\r?$`，v0.55.0 接入期实测补充）**：接入前，各处用逐行正则计数时
+ * `\r` 被当作普通字符（`[ \t]*- \[ \]` 无 `$` 锚）→ CRLF 的 tasks.md 正常计数；
+ * 若本函数不容忍行尾 `\r`，接入后这些行会**全部解析失败** → 计数归零/guard 静默放行
+ * （比现状更差）。故此处容忍行尾 `\r`（纯格式变体），返回的 `text` 不含 `\r`。
+ * 调用方若需**逐字节保留原行**（如 hash 归一化），请自行持有原行、不要用本返回值重建。
+ */
+export function parseTaskLine(line) {
+  if (typeof line !== 'string') return null;
+  const m = /^([ \t]*)([-*])\s+\[([ xX])\]\s?(.*)\r?$/.exec(line);
+  if (!m) return null;
+  return { indent: m[1].length, checked: m[3].toLowerCase() === 'x', text: m[4] };
+}

package/scripts/lib/prototype-sync.mjs

@@ -19,6 +19,19 @@ import { readFileSync, writeFileSync, existsSync, cpSync, mkdirSync } from 'node
 import { join, basename, relative, sep, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+/**
+ * UX 增量标题（v0.55.0 §8.4.3 横展 FB-4）：在 `## UX 增量` 基础上容忍 `**加粗**`
+ * 与行尾空白。**不锚行首是既有行为**——`### UX 增量` / `#### **UX 增量**` 修复前
+ * 也能命中且正文提取正确，故此处不收紧（收紧会让既有契约文本失同步）。
+ */
+const UX_HEADING_RE = /##[ \t]+\**[ \t]*(?:UX 增量|Prototype Changes|UX Delta)\**[ \t]*\r?\n([\s\S]*?)(?=\n## |\n---|\n$)/;
+
+/**
+ * 形似 UX 增量标题但上面未命中（实测为 H1 `# UX 增量`，正则要求两个 `#` 起）——
+ * 用于给出不静默的 WARN，避免"整段 UX 增量丢失且只说 nothing to sync"。
+ */
+const UX_HEADING_LIKE_RE = /^#{1,6}[ \t]*\**[ \t]*(?:UX 增量|Prototype Changes|UX Delta)/m;
+
 /**
  * 解析 CLI 参数数组为结构化对象
  * @param {string[]} argv - 原始参数数组，如 ['changes/my-change/', '--source', 'delta.md']
@@ -110,10 +123,15 @@ export function run(args = {}) {
     if (existsSync(contractPath)) {
       const contract = readFileSync(contractPath, 'utf-8');
       // 提取 UX 相关章节（## UX 增量 或 ## Prototype Changes）
-      const uxMatch = contract.match(/## (?:UX 增量|Prototype Changes|UX Delta)\n([\s\S]*?)(?=\n## |\n---|\n$)/);
+      // v0.55.0 §8.4.3 横展（FB-4）：修复前 `## **UX 增量**`（加粗）静默降级成
+      // "No UX delta found, nothing to sync"，整段 UX 增量丢失且无任何提示。
+      const uxMatch = contract.match(UX_HEADING_RE);
       if (uxMatch) {
         uxDeltaContent = uxMatch[1].trim();
         uxDeltaSource = contractPath;
+      } else if (UX_HEADING_LIKE_RE.test(contract)) {
+        // 含关键词但正则未命中（如 H1 `# UX 增量`）→ 显式提示，不再静默
+        console.warn('  [WARN] prototype-sync: execution-contract.md 含 UX 增量字样但标题形态不匹配（期望 `## UX 增量`），本次未同步');
       }
     }
   }

package/scripts/lib/sdd-overlay.mjs

@@ -4,7 +4,9 @@ import {
 } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { computeArtifactsHash, normalizeCheckboxes } from './hash.mjs';
+import { parseTaskLine } from './md-normalize.mjs';
 import { readState } from './state-loader.mjs';
+import { safeName } from './slug.mjs';
 
 export const HANDOFF_TYPES = new Set(['prototype', 'research', 'experiment']);
 export const HANDOFF_DECISIONS = new Set(['accept', 'reject', 'defer']);
@@ -28,10 +30,21 @@ export function getOverlayPaths(changeDir) {
 export function computeTaskHash(changeDir, taskId) {
   const tasks = readFileSync(join(changeDir, 'tasks.md'), 'utf8');
   const escaped = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const match = tasks.match(new RegExp(`^- \\[([ xX])\\] ${escaped}\\s+.+$`, 'm'));
-  if (!match) throw new Error(`Task '${taskId}' was not found in tasks.md`);
+  // 任务正文须以 id 开头且后面还有内容（与原 `^...\\s+.+$` 同判据）
+  const idRe = new RegExp(`^${escaped}\\s+[\\s\\S]`);
+  // v0.55.0 §8.4.3 横展（FB-4）：行定位走共享原语 `parseTaskLine`（容忍 `*` bullet /
+  // 制表符分隔 / 缩进等纯格式变体）。**本函数保持"找不到即抛错"的硬失败语义**——
+  // 定位失败会让 checkpoint 无法落盘，静默放行比抛错危险。
+  // hash 仍取**原始行**（仅去行尾 `\\r`，与旧 `match[0]` 一致）→ 既有 checkpoint 不失效。
+  const matched = tasks.split('\n')
+    .map(line => line.replace(/\r$/, ''))
+    .find((line) => {
+      const task = parseTaskLine(line);
+      return task ? idRe.test(task.text) : false;
+    });
+  if (matched === undefined) throw new Error(`Task '${taskId}' was not found in tasks.md`);
   // v0.49.0 §83.3.1：勾选状态归一化 —— 勾选是执行进度，不应使 checkpoint 变 stale
-  return `sha256:${createHash('sha256').update(normalizeCheckboxes(match[0])).digest('hex')}`;
+  return `sha256:${createHash('sha256').update(normalizeCheckboxes(matched)).digest('hex')}`;
 }
 
 export function saveCheckpoint(changeDir, input) {
@@ -258,6 +271,4 @@ function requireText(value, field) {
   if (typeof value !== 'string' || !value.trim()) throw new Error(`${field} is required`);
 }
 
-function safeName(value) {
-  return String(value).replace(/[^A-Za-z0-9._-]/g, '_');
-}
+// safeName 已收敛到 slug.mjs（保留 CJK；`. _ -` 语义不变，如 taskId `1.1` 原样保留）

package/scripts/lib/slug.mjs

@@ -0,0 +1,68 @@
+/**
+ * slug — 文件名 / 路径段安全化的唯一真相源（2026-09-12，emp-auth 复利膨胀调查）
+ *
+ * 背景：同一插件内曾存在 3 套文件名安全化规则，其中两套**未保留 CJK 且逐字符替换**，
+ * 导致中文标题退化为纯短横线序列。实证（emp-auth v1 迭代）：
+ *   - `docs/test-ledger/baselines/--------------------.md`（原名「执行结果（三仓实测，命令 + 实际输出）」）
+ *   - 同目录 17 个文件名受影响，其中多份已无法从文件名辨识内容
+ *   - 叠加第二个因素：baselines 的 moduleName 取自 test-matrix 三级标题原文（每轮由 LLM
+ *     自由命名，如 `DemoHome 当前应用（demo-ui，medium）` vs `DemoHome（demo-ui，medium，revision 3）`）
+ *     ⇒ 文件名每轮变化 ⇒ `existsSync` 不命中 ⇒ **新建而非增量合并**（demohome 三次 merge
+ *     产出 3 个文件，git 记录全为 A）
+ *
+ * 约定：
+ * - 字符集统一为 **ASCII 字母数字 + CJK 统一表意文字（U+4E00–U+9FFF）**；其余字符折叠为分隔符
+ * - 一律使用 `+` 量词折叠连续非法字符——**禁止逐字符替换**（一个中文 = 一个分隔符是退化根因）
+ * - 两类用途语义不同，**不要互串**：
+ *   · slugify()  标题 → 文件名（小写、`.`/`_`/`-` 均折叠为分隔符、可截断）
+ *   · safeName() ID → 路径段（保留大小写与 `.` `_` `-`，不截断）——ID 自身以这些字符作分隔，
+ *     例如 taskId `1.1` MUST 保持为 `1.1`（折叠成 `1_1` 会失配既有 checkpoint 文件）
+ *
+ * @module slug
+ */
+
+/**
+ * CJK 统一表意文字区间字符类（U+4E00–U+9FFF）。
+ *
+ * 用 `\u` 转义写法而非字面「一-鿿」：字面写法拼进字符类时，**前一个字符若为 `-`
+ * 会被解析成范围**——`[^..._-一-鿿]` 里的 `_-一` 是 U+005F–U+4E00 范围，
+ * 结果 U+4E00 以上的汉字（如「任务」U+4EFB）仍被替换。转义写法无此风险。
+ */
+export const CJK_CLASS = '\\u4e00-\\u9fff';
+
+/** 转义正则元字符（separator 由调用方传入，可能是 `-` / `_` 等） */
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * 标题 → 文件名 slug。
+ *
+ * 保留 ASCII 小写字母数字与 CJK；其余连续字符折叠为一个 separator；去掉首尾 separator。
+ *
+ * @param {string} value 原始文本（通常是条目标题 / 模块名）
+ * @param {{separator?: string, maxLength?: number}} [options]
+ *   separator 默认 `-`；maxLength > 0 时才截断（默认不截断，由调用方按场景显式传入）
+ * @returns {string}
+ */
+export function slugify(value, { separator = '-', maxLength = 0 } = {}) {
+  const esc = escapeRe(separator);
+  let s = String(value ?? '').toLowerCase();
+  s = s.replace(new RegExp(`[^a-z0-9${CJK_CLASS}]+`, 'g'), separator);
+  s = s.replace(new RegExp(`^(?:${esc})+|(?:${esc})+$`, 'g'), '');
+  return maxLength > 0 ? s.slice(0, maxLength) : s;
+}
+
+/**
+ * ID → 路径段安全名。
+ *
+ * 保留 ASCII 字母数字（含大小写）与 `.` `_` `-`，以及 CJK；其余连续字符折叠为一个 `_`。
+ * 不截断、不改大小写——ID 的既有语义（如 `1.1`、`W4-1`）MUST 原样保留。
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function safeName(value) {
+  // `-` MUST 置于字符类末尾（否则与相邻字符构成范围）
+  return String(value ?? '').replace(new RegExp(`[^A-Za-z0-9._${CJK_CLASS}-]+`, 'g'), '_');
+}

package/scripts/lib/solutions-capture.mjs

@@ -16,17 +16,11 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } fr
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { SEVERITY_VALUES, isSeverity } from './severity.mjs';
+import { SOLUTION_PHASES } from './solutions-phases.mjs';
+import { slugify } from './slug.mjs';
 
-const PHASES = ['prd', 'plan', 'architecture', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
 const MAX_INDEX_LINES = 150;
-
-function slugify(text) {
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9一-鿿]+/g, '-')
-    .replace(/^-|-$/g, '')
-    .slice(0, 40);
-}
+const SLUG_MAX_LENGTH = 40;
 
 export function run(args = {}) {
   const phase = args.phase || 'cross-phase';
@@ -42,8 +36,8 @@ export function run(args = {}) {
 
   // 注：process.exit 后补 return——真实 CLI 下 exit 即终止；测试环境 mock exit 时
   // 不得继续执行（否则校验失败仍会写入文件，v0.23 §91.3.4 横展）。
-  if (!PHASES.includes(phase)) {
-    console.error(`Invalid phase: ${phase}. Valid: ${PHASES.join(', ')}`);
+  if (!SOLUTION_PHASES.includes(phase)) {
+    console.error(`Invalid phase: ${phase}. Valid: ${SOLUTION_PHASES.join(', ')}`);
     process.exit(1);
     return;
   }
@@ -61,7 +55,7 @@ export function run(args = {}) {
 
   // 生成文件名
   const date = new Date().toISOString().slice(0, 10);
-  const slug = slugify(summary);
+  const slug = slugify(summary, { maxLength: SLUG_MAX_LENGTH });
   const fileName = `${date}-${slug}.md`;
   const filePath = join(phaseDir, fileName);
 

package/scripts/lib/solutions-index-gen.mjs

@@ -17,8 +17,8 @@ import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from '
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { severityRank } from './severity.mjs';
+import { SOLUTION_PHASES } from './solutions-phases.mjs';
 
-const PHASES = ['prd', 'plan', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
 const MAX_INDEX_LINES = 150;
 
 function parseFrontmatter(content) {
@@ -54,7 +54,7 @@ export function run(args = {}) {
 
   const entries = [];
 
-  for (const phase of PHASES) {
+  for (const phase of SOLUTION_PHASES) {
     const phaseDir = join(dir, phase);
     if (!existsSync(phaseDir) || !statSync(phaseDir).isDirectory()) continue;
 

package/scripts/lib/solutions-phases.mjs

@@ -0,0 +1,32 @@
+/**
+ * solutions-phases — 复利条目 phase 目录的唯一真相源（2026-09-12）
+ *
+ * 背景：PHASES 枚举曾在 3 处各自定义且互相矛盾——
+ *   - `solutions-capture.mjs`   8 项（含 `architecture`，v0.36.3 加入）
+ *   - `solutions-index-gen.mjs` 7 项（**缺 `architecture`**）
+ *   - 文档树（three-tier-index.md / AGENTS.md）写 `requirement`，而 frontmatter 示例写 `prd`
+ *
+ * 后果（实证，emp-auth）：`tf solutions capture --phase architecture` 写入的条目在
+ * `tf solutions index-gen` 重建后会**从 INDEX.md 消失**——文件仍在磁盘，但对所有
+ * 注入 / 检索通道不可见。任何新增 phase 只改本文件。
+ *
+ * 注意：`docs/solutions/` 下另有 ce-compound 通道写入的 **category 目录**
+ * （`workflow-issues/` 等，见 skills/ce-compound/references/yaml-schema.md），
+ * 那套词表与本 phase 词表**互不兼容**，本模块不覆盖。
+ *
+ * @module solutions-phases
+ */
+
+/** 合法 phase 取值（同时是 docs/solutions/ 下的子目录名） */
+export const SOLUTION_PHASES = Object.freeze([
+  'prd', 'plan', 'architecture', 'prototype', 'spec', 'build', 'review', 'cross-phase',
+]);
+
+/**
+ * 是否为合法 phase 取值。
+ * @param {string} phase
+ * @returns {boolean}
+ */
+export function isSolutionPhase(phase) {
+  return SOLUTION_PHASES.includes(phase);
+}