@xulthekl/team-flow 0.54.0 → 0.55.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,6 +4,7 @@ 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';
 
 export const HANDOFF_TYPES = new Set(['prototype', 'research', 'experiment']);
@@ -28,10 +29,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) {

package/scripts/lib/solutions-promote.mjs

@@ -22,6 +22,7 @@ import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } fr
 import { join, basename } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { meetsMinSeverity, nextSeverity } from './severity.mjs';
+import { normalizeInline } from './md-normalize.mjs';
 
 /**
  * 剥离 YAML 行尾注释（空格 + `#` 起始）——v0.23 §91 硬化：
@@ -39,9 +40,12 @@ function parseFrontmatter(content) {
   if (!match) return null;
   const fm = {};
   for (const line of match[1].split('\n')) {
-    const idx = line.indexOf(':');
+    // v0.55.0 §8.4.3 横展（FB-4）：容忍全角冒号、`**key**` 加粗与反引号
+    // （走共享层 `normalizeInline`）。原实现只认半角 `:` + 裸键名，
+    // `severity：high` / `**severity**: high` 会整键丢失 → 该条静默不晋升。
+    const idx = line.search(/[:：]/);
     if (idx > 0) {
-      fm[line.slice(0, idx).trim()] = stripInlineComment(line.slice(idx + 1));
+      fm[normalizeInline(line.slice(0, idx))] = normalizeInline(stripInlineComment(line.slice(idx + 1)));
     }
   }
   return fm;
@@ -100,10 +104,13 @@ function markEntryConfirmed(filePath) {
   const content = readFileSync(filePath, 'utf-8');
   const block = content.match(/^---\n([\s\S]*?)\n---/);
   if (!block) return;
-  const counter = block[1].match(/^confirmed:\s*(\d+)\s*$/m);
+  // v0.55.0 §8.4.3 横展（FB-4）：容忍全角冒号与 `**confirmed**` 加粗。
+  // 放宽前这类行匹配不到 → 走追加分支 → frontmatter 出现**重复 confirmed 键**
+  // （计数错乱且静默）。命中后统一改回规范形态 `confirmed: N`。
+  const counter = block[1].match(/^\**confirmed\**\s*[:：]\s*(\d+)\s*$/m);
   const next = counter ? parseInt(counter[1], 10) + 1 : 2;
   const frontmatter = counter
-    ? block[1].replace(/^confirmed:\s*\d+\s*$/m, `confirmed: ${next}`)
+    ? block[1].replace(/^\**confirmed\**\s*[:：]\s*\d+\s*$/m, `confirmed: ${next}`)
     : `${block[1]}\nconfirmed: ${next}`;
   writeFileSync(filePath, content.replace(block[0], `---\n${frontmatter}\n---`), 'utf-8');
 }

package/scripts/lib/spec-merge.mjs

@@ -14,8 +14,40 @@
 // 5. 主基格式不做规范化：按 `### Requirement:` 为块边界解析，兼容既有主基的
 //    `## ADDED Requirements` 容器形态（不改写既有段落结构）。
 
-const REQ_RE = /^###\s*Requirement:\s*(.+?)\s*$/;
+import { stripInlineEmphasis } from './md-normalize.mjs';
+
+// v0.55.0 §8.4.3 横展（FB-4）：标题行先过 `stripInlineEmphasis` 再匹配——容忍
+// `### **Requirement**: X` 这类手写加粗；同时容忍全角冒号与冒号前空格
+// （`md-normalize.matchKeyValue` 的同一约定）。**不放宽层级**：仍是恰好 `###`。
+const REQ_RE = /^###\s*Requirement\s*[:：]\s*(.+?)\s*$/;
 const H2_RE = /^##\s+/;
+/** 形似 Requirement 标题（带分隔符）——用于「解析失败不静默」告警。 */
+const REQUIREMENT_LIKE_RE = /^#{1,6}\s*\**\s*Requirement\s*\**\s*[:：]/i;
+
+/** 归一化后匹配 requirement 标题：容忍加粗等纯格式变体（FB-4 横展）。 */
+function matchRequirement(line) {
+  return stripInlineEmphasis(line).match(REQ_RE);
+}
+
+/** 解析失败不静默（约束②）：形似 requirement 标题但未被接受的 → WARN（不报错）。 */
+function warnUnparsedRequirementHeadings(content) {
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!REQUIREMENT_LIKE_RE.test(lines[i]) || matchRequirement(lines[i])) continue;
+    console.warn(`  [WARN] spec-merge: 第 ${i + 1} 行形似 Requirement 标题但无法解析（按非标题处理）：${lines[i].trim().slice(0, 80)}`);
+  }
+}
+
+/**
+ * 名称比较键：容忍加粗/反引号/首尾空白等**纯格式**差异。
+ *
+ * 必要性：delta 侧解析器（`src/parsing/requirement-blocks.ts` 的
+ * `normalizeRequirementName`）**只做 trim**，主基侧若单边归一化，`**Foo**` 与 `Foo`
+ * 会被判为不同名 → ADDED 静默追加重复块 / MODIFIED 误报「不存在」。故比较时两侧同键。
+ */
+function nameKey(name) {
+  return stripInlineEmphasis(String(name ?? '').replace(/`/g, '')).trim();
+}
 
 /** dist 解析器惰性加载（与 cmd-sync 导入 Validator 同源）。 */
 let _parseDeltaSpec = null;
@@ -39,7 +71,7 @@ function blockBody(blockLines) {
 
 /** 切掉 `#### Previous version` 子节（及其后内容）——用于幂等比对与旧内容提取。 */
 function stripPreviousVersion(body) {
-  const idx = body.search(/^####\s+Previous version\b/m);
+  const idx = body.search(/^####\s+\**\s*Previous version\b/m);
   return idx === -1 ? body : body.slice(0, idx).replace(/\s+$/, '');
 }
 
@@ -53,8 +85,8 @@ function escapeRe(s) {
  * `v1-C3-session-governance` 的注记）。
  */
 function hasMergedNote(body, changeName) {
-  const re = new RegExp(`^####\\s+Previous version\\b.*(?<![\\w-])${escapeRe(changeName)}(?![\\w-])`, 'm');
-  return re.test(body);
+  const re = new RegExp(`^####\\s+\\**\\s*Previous version\\b.*(?<![\\w-])${escapeRe(changeName)}(?![\\w-])`, 'm');
+  return re.test(stripInlineEmphasis(body));
 }
 
 function renameNote(from, changeName) {
@@ -62,7 +94,7 @@ function renameNote(from, changeName) {
 }
 
 function isRemovedSection(section) {
-  return typeof section === 'string' && /^Removed\b/i.test(section.trim());
+  return typeof section === 'string' && /^Removed\b/i.test(stripInlineEmphasis(section).trim());
 }
 
 /**
@@ -81,14 +113,14 @@ function parseMain(content) {
       i++;
       continue;
     }
-    const m = lines[i].match(REQ_RE);
+    const m = matchRequirement(lines[i]);
     if (!m) {
       i++;
       continue;
     }
     let end = lines.length;
     for (let j = i + 1; j < lines.length; j++) {
-      if (REQ_RE.test(lines[j]) || H2_RE.test(lines[j])) {
+      if (matchRequirement(lines[j]) || H2_RE.test(lines[j])) {
         end = j;
         break;
       }
@@ -99,9 +131,10 @@ function parseMain(content) {
   return { lines, blocks };
 }
 
-/** 在正常区（非 `## Removed` 段）按名查找 requirement 块。 */
+/** 在正常区（非 `## Removed` 段）按名查找 requirement 块（名称按 `nameKey` 宽松比较）。 */
 function findBlock(parsed, name) {
-  return parsed.blocks.find(b => b.name === name && !isRemovedSection(b.section)) || null;
+  const key = nameKey(name);
+  return parsed.blocks.find(b => nameKey(b.name) === key && !isRemovedSection(b.section)) || null;
 }
 
 /**
@@ -122,7 +155,7 @@ function findAppendIndex(parsed) {
 
 /** 定位 `## Removed` 段的 [start, end)（end = 下一个二级标题或文件末尾）；无则 -1。 */
 function findRemovedSectionRange(parsed) {
-  const start = parsed.lines.findIndex(l => /^##\s+Removed\s*$/i.test(l));
+  const start = parsed.lines.findIndex(l => /^##\s+\**\s*Removed\**\s*$/i.test(stripInlineEmphasis(l)));
   if (start === -1) return { start: -1, end: -1 };
   let end = parsed.lines.length;
   for (let j = start + 1; j < parsed.lines.length; j++) {
@@ -235,7 +268,8 @@ function applyRemoved(content, plan, changeName, today, report) {
 
     if (!target) {
       // 幂等：该名已出现在 `## Removed` 段
-      const inRemoved = parsed.blocks.some(b => b.name === name && isRemovedSection(b.section));
+      const key = nameKey(name);
+      const inRemoved = parsed.blocks.some(b => nameKey(b.name) === key && isRemovedSection(b.section));
       if (inRemoved) {
         report.skipped++;
         continue;
@@ -300,6 +334,7 @@ export async function mergeMainSpec(mainContent, deltaContent, changeName, optio
   }
 
   const report = { renamed: 0, modified: 0, added: 0, removed: 0, skipped: 0, noOps: false };
+  warnUnparsedRequirementHeadings(mainContent);
   let content = mainContent;
   content = applyRenamed(content, plan, changeName, report);
   content = applyModified(content, plan, changeName, today, report);