@xulthekl/team-flow 0.54.0 → 0.56.0

package/scripts/guard/design-token-guard.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// design-token-guard.mjs — 设计系统完整性检查（v0.54.0）
+// design-token-guard.mjs — 设计系统完整性检查（v0.55.0）
 //
 // 两部分（v0.54.0 新增六层审计；设计 §4.1.5）：
 //   A. 硬校验（失败 exit 1）：9 段 schema / palette 5 方向 / A1 identity / A2 color-mix / B-slot 别名
@@ -33,24 +33,28 @@ import {
   hasSection,
   sectionBody,
   sectionBodyRaw,
+  subsectionBodyRaw,
   parseComponentsTable,
   parseContract,
+  parsePageArchetype,
+  contractFormatWarning,
   COMPONENT_TYPE_MIN_STATES,
   COMPONENT_COUNT_PASS,
   COMPONENT_COUNT_WARN,
 } from '../lib/ds-parse.mjs';
+import {
+  REQUIRED_SECTIONS,
+  OPTIONAL_SECTIONS,
+  NON_SECTION_FILES,
+  KNOWN_VARIANT_RE,
+  readFileOrNull,
+  designSystemMds,
+  variantCandidates,
+  resolveInputs,
+} from '../lib/ds-inputs.mjs';
 
 // ── Check definitions ──
 
-// The 9 required ## sections in design-system.md.
-const REQUIRED_SECTIONS = [
-  'color', 'typography', 'spacing', 'layout', 'components',
-  'motion', 'voice', 'brand', 'anti-patterns',
-];
-
-// Optional ## sections — reported for visibility, never counted as failures.
-const OPTIONAL_SECTIONS = ['palette', 'aliases', 'extensions', 'principles', 'governance'];
-
 // The 5 palette directions checked when a palette section exists.
 const PALETTE_DIRECTIONS = ['neutral', 'primary', 'success', 'warning', 'danger'];
 
@@ -73,12 +77,6 @@ const B_SLOT_ALIASES = [
 
 // ── Helpers ──
 
-// Read a file as UTF-8, or return null when it does not exist.
-function readFileOrNull(filePath) {
-  if (!filePath || !existsSync(filePath)) return null;
-  return readFileSync(filePath, 'utf-8');
-}
-
 // Escape a token name for safe use inside a RegExp (names contain "--").
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -122,84 +120,13 @@ if (!mdPath) {
   process.exit(1);
 }
 
-// ── 输入解析：单文件系统 或 base + 端变体拆分系统 ──
+// ── 输入解析：已下沉至 scripts/lib/ds-inputs.mjs（v0.55.0）──
 //
-// 权威排布是「base 品牌共享层 + 端变体」（variant-schema.md）：base 不含
-// typography/spacing/layout/motion（这些随端变化）。故 9 段断言必须在**合并后**文本上做——
-// 只校验 base.md 会把合规系统判为 FAIL 并阻断落盘（v0.54.0 P4 实证：4 项 MISSING / exit 1）。
-//
-// 规则（确定性，可解释）：
-//   ① 传入目录 → 以目录内 base.md 为主体；② 传入 base.md → 以它为主体；③ 传入变体文件 → base.md 主体 + 该文件。
-//   ④ 主体自身已含全部 9 段（单文件系统 / 转换器产物）→ 单文件模式，不合并（避免卷入同目录无关 md）。
-//   ⑤ 主体不含全 9 段 → 合并**约定命名的端变体**（`*-end.md` + `variants/` 子目录内的 md）；
-//      `--variant <name>` 可显式纳入非约定命名的变体文件（逃生通道）。
-//      含必选段但未被纳入的其它 md → 告警列出（不静默补齐：一个 notes.md 不该把残缺系统伪装成 PASS）。
-// 合并按「base 在前」顺序，组件表按组件名去重（base 优先），端特有差异行不会重复计数。
-const NON_SECTION_FILES = new Set(['primer.md', 'pending.md', 'readme.md', 'index.md']);
-
-// 端变体命名约定：`*-end.md`（b-end / c-end / mobile-end …）+ `variants/` 子目录内全部 md（如 dark.md）。
-// 收紧为约定集而非「同目录任意 md」——否则一个含 `## spacing` 的 notes.md 就能补齐缺失段，
-// 把残缺系统伪装成 PASS（v0.54.0 P4 复验观察 B 实证）。非约定名可用 `--variant <name>` 显式纳入。
-const KNOWN_VARIANT_RE = /-end\.md$/i;
-
-/** 设计系统目录内的全部候选 md（dir 与 variants/ 两层，排除 base 与非段落文件）。 */
-function designSystemMds(dir) {
-  const out = [];
-  for (const d of [dir, join(dir, 'variants')]) {
-    if (!existsSync(d)) continue;
-    for (const entry of readdirSync(d, { withFileTypes: true })) {
-      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-      if (entry.name === 'base.md' || NON_SECTION_FILES.has(entry.name.toLowerCase())) continue;
-      out.push(join(d, entry.name));
-    }
-  }
-  return out.sort();
-}
-
-function variantCandidates(dir) {
-  return designSystemMds(dir).filter(f => KNOWN_VARIANT_RE.test(basename(f)) || f.includes(`${sep}variants${sep}`));
-}
-
-function resolveInputs(input, variantName) {
-  const isDir = existsSync(input) && statSync(input).isDirectory();
-  const dir = isDir ? input : dirname(input);
-  const parts = [];
-
-  if (isDir) {
-    parts.push(join(dir, 'base.md'));
-  } else if (basename(input) === 'base.md') {
-    parts.push(input);
-  } else {
-    parts.push(join(dir, 'base.md'));  // 传入变体文件时仍以 base 为主体（base 优先）
-    parts.push(input);
-  }
-
-  const present = parts.filter(f => existsSync(f) && readFileOrNull(f) !== null);
-  const subject = present[0] ? readFileOrNull(present[0]) : null;
-  const subjectComplete = subject !== null
-    && REQUIRED_SECTIONS.every(s => hasSection(extractH2Headers(subject), s));
-
-  let merged = [...present];
-  let ignored = [];
-  if (!subjectComplete) {
-    // --variant <name> 为显式指定：在**全部**候选 md 中按名匹配（含非约定命名），作为逃生通道
-    const variants = variantName
-      ? designSystemMds(dir).filter(f => basename(f).includes(variantName))
-      : variantCandidates(dir);
-    for (const v of variants) if (!merged.includes(v)) merged.push(v);
-    // 观察 B 兜底：未被纳入合并、但含必选段的非约定 md —— 显式告警（不静默补齐，也不静默忽略）
-    if (!variantName) {
-      const mergedSet = new Set(merged);
-      ignored = designSystemMds(dir).filter(f => {
-        if (mergedSet.has(f)) return false;
-        const text = readFileOrNull(f) || '';
-        const headers = extractH2Headers(text);
-        return REQUIRED_SECTIONS.some(s => hasSection(headers, s));
-      });
-    }
-  }
-  return { dir, files: merged, singleFile: subjectComplete, ignored };
-}
+// 动机：gen-primer.mjs 的 digest 必须覆盖参与合并的**全部**文件（否则变体变更不判 STALE
+// → prototype Step 0 gate 放行 → 原型静默用旧页面范式），它需要与 guard 同一套变体发现逻辑。
+// 但 guard 是**顶层副作用模块**（顶层 argv 解析 / process.exit / 打印整份报告），
+// 不能被子脚本 import（import 即先打印报告再退出）→ 纯逻辑下沉，两处 import。
+// 输入规则 ①–⑤、单文件模式与 ignored 告警语义，见 ds-inputs.mjs 头注。
 
 const { dir: dsDir, files: mdFiles, singleFile, ignored: ignoredMds } = resolveInputs(mdPath, VARIANT);
 const markdown = mdFiles.length
@@ -207,14 +134,20 @@ const markdown = mdFiles.length
   : null;
 const css = cssPath ? readFileOrNull(cssPath) : null;
 
-line('Design Token Guard v0.54.0');
+line('Design Token Guard v0.55.0');
 line('==========================');
 line(`design-system.md: ${mdPath}`);
 line(`design-tokens.css: ${cssPath || 'not provided'}`);
 if (mdFiles.length > 1) line(`合并输入（base + 端变体）：${mdFiles.map(f => basename(f)).join(' + ')}`);
 if (ignoredMds.length) {
-  line(`  ⚠️  未纳入合并（非约定命名的端变体命名：\`*-end.md\` 或 \`variants/\`）：${ignoredMds.map(f => basename(f)).join(' / ')}`);
-  line('      若其中某个确是本系统的端变体 → 改名为 <端>-end.md 或移入 variants/，或用 `--variant <name>` 显式纳入');
+  if (singleFile) {
+    // v0.55.0：单文件模式原先整块跳过 → 同目录变体静默不参与判据（P1.5 一轮 C1）
+    line(`  ⚠️  主体已含全 9 段（单文件模式），同目录变体**未参与判据**：${ignoredMds.map(f => basename(f)).join(' / ')}`);
+    line('      若该变体属于本系统 → 改走拆分布局（base.md 只留品牌层 + 端变体），或用 `--variant <name>` 显式纳入');
+  } else {
+    line(`  ⚠️  未纳入合并（非约定命名的端变体命名：\`*-end.md\` 或 \`variants/\`）：${ignoredMds.map(f => basename(f)).join(' / ')}`);
+    line('      若其中某个确是本系统的端变体 → 改名为 <端>-end.md 或移入 variants/，或用 `--variant <name>` 显式纳入');
+  }
 }
 else if (singleFile) line('输入模式: 单文件（主体已含全部 9 段）');
 if (VARIANT) line(`variant 过滤: ${VARIANT}`);
@@ -322,15 +255,33 @@ if (css === null) {
 }
 line();
 
-// ── 六层审计报告（advisory；v0.54.0 新增，§4.1.5）──
+// ── 六层审计报告（advisory；v0.54.0 新增，§4.1.5；v0.55.0 三态 + L3/L4 改造）──
 //
-// 标签规则：contract=v1（或无标记且非 strict？见下）→ 不达标标 FAIL；
-//           contract=legacy/无标记 → 降级 WARN；--strict → legacy 也按 v1 标签。
+// 标签规则（v0.55.0 三态）：
+//   `true` → ✅ ／ `false` → ❌（v1）或 ⚠️（legacy 降级）／ **`'warn'` → 恒 ⚠️，绕过降级逻辑**。
+//   `'warn'` 专用于"新增可选内容缺失"：不得让既有合规系统回归 FAIL（D-15）。
+//   原实现只有二值 + 按 contract 降级 → 现场 `contract: v1` 系统缺页面范式声明会打 ❌，
+//   与 D-15 直接冲突；且只改明细行不改汇总行会**同一次运行出现相反标签**（P1.5 二轮实证）。
 // 报告中所有标签均不阻断（不影响 exit code）。
 
 const contract = markdown ? parseContract(markdown) : null;
-const downgrade = !STRICT && contract !== 'v1';   // legacy 或无标记 → 降级
+
+// contract 值域（v0.55.0）：已知 v1 / legacy；**未知值（如 v2）按最严档（等同 v1）** + WARN——
+// 不再静默归入降级。未知意味着"更新的规范"，从严比从宽安全。
+const CONTRACT_KNOWN = ['v1', 'legacy'];
+const contractUnknown = contract !== null && !CONTRACT_KNOWN.includes(contract);
+if (contractUnknown) {
+  warnLine(`检测到未识别的 contract 取值 \`${contract}\`，按最严档（等同 v1）判定`);
+}
+// 格式诊断（v0.55.0）：段存在 + 提到 contract + 解析不出 → 显式告警（原为静默 unset）
+const contractFormatIssue = markdown ? contractFormatWarning(markdown) : null;
+if (contractFormatIssue) warnLine(contractFormatIssue);
+
+const downgrade = !STRICT && !contractUnknown && contract !== 'v1';
+
 const labelOf = (ok) => ok ? '✅' : (downgrade ? '⚠️' : '❌');
+/** 三态渲染：`'warn'` 绕过 labelOf 恒输出 ⚠️。 */
+const badge = (v) => (v === 'warn' ? '⚠️' : (v === true ? '✅' : labelOf(false)));
 
 const layerResults = {};
 
@@ -405,19 +356,79 @@ if (markdown === null) {
     }
   }
 
-  // L3 业务模式（页面范式的归属声明：设计系统侧只做**引用**，节奏表在 prototype skill 的 layouts.md）
-  // 检测面 = 合并后设计系统文本 + 同目录 primer.md（gen-primer 写入 `## 页面范式` 段）——
-  // v0.54.0 P4 修正：只读传入的单个 md 会让任何按规范创建的系统恒为 ❌（假红灯）。
-  const primerText = readFileOrNull(join(dsDir, 'primer.md')) || '';
-  const l3ok = /layouts|页面范式|页面节奏|page pattern/i.test(markdown + '\n' + primerText);
-  layerResults['L3-业务模式'] = l3ok;
-  line(`L3 业务模式      ${labelOf(l3ok)} ${l3ok ? '页面范式引用存在（设计系统侧只引用，节奏表在 prototype layouts.md）' : '未见页面范式引用（缺 primer.md 或引用句）'}`);
-
-  // L4 页面范式（layout 段 + 断点）
-  const layoutBody = sectionBodyRaw(markdown, 'layout');
-  const l4ok = layoutBody !== null && /断点|breakpoint|sm|md|lg|栅格|grid/i.test(layoutBody);
-  layerResults['L4-页面范式'] = l4ok;
-  line(`L4 页面范式      ${labelOf(l4ok)} ${l4ok ? 'layout 段含栅格/断点' : 'layout 段缺栅格或断点声明'}`);
+  // ── L3 业务模式 / L4 页面范式（v0.55.0 改造，设计 §8.2.5）──
+  //
+  // 检测面 = **设计系统源文本，按端分别求值**。两个理由均为 P1.5 实证：
+  //   ① **不再读 primer.md**：原判据 `/layouts|页面范式|页面节奏/` 对 markdown + primer 匹配，
+  //      而 primer 里 gen-primer 硬编码的 `## 页面范式` 段**必然命中** → L3 恒通过，
+  //      等价于重复断言 L5，且**用派生物测源 = 自证**。
+  //   ② **不用合并文本**：`sectionBodyRaw` 用 `findIndex` **只取首个** `## layout`，
+  //      合并顺序恒为 base → b-end → c-end → **c-end 的声明永不解析**。
+  //      `both` 是默认 target；既有纪律见 `creation-flow.md`（"合并断言掩盖单端残缺"）。
+  const endFiles = mdFiles.filter(f =>
+    KNOWN_VARIANT_RE.test(basename(f)) || f.includes(`${sep}variants${sep}`));
+  const scopes = endFiles.length >= 2
+    ? endFiles.map(f => ({ name: basename(f).replace(/-end\.md$/i, ''), text: readFileOrNull(f) || '' }))
+    : [{ name: null, text: markdown }];
+  const arche = scopes.map(s => ({ ...s, ...parsePageArchetype(s.text) }));
+
+  // L3 = 来源声明层（值域三值；未声明 → 'warn'，**不走 FAIL** —— 新增可选内容不得让存量系统回归，D-15）
+  const l3vals = arche.map(a => {
+    if (!a.declared) return 'warn';
+    const s = a.source || '';
+    return (/^引用内置$/.test(s) || /^项目自有/.test(s) || /^同/.test(s)) ? true : 'warn';
+  });
+
+  // L4a = 布局基础（栅格/断点）。v0.55.0 **收紧 + 三形态**：
+  // 原裸子串 `/断点|breakpoint|sm|md|lg|栅格|grid/` 被 `.md` 路径文本保证命中
+  // （`layouts.md` ⊃ `md`，`b-end.md` 同理）→ 空检测。
+  // 现要求"名 + 值"配对，接受三种真实写法：
+  //   ① 键形态：`栅格：12 列` / `断点：sm 640`
+  //   ② 值形态：`sm 640` / `md 1024px`
+  //   ③ **表格形态**：`| sm | 640px |` —— 现场 b-end.md 用 4 列表格声明断点，
+  //      只认前两种会把它判成"缺断点"（P1.5 三轮预警的假阴性，实施期实测确认）
+  const L4A_KEY_RE = /(栅格|断点)\s*[:：]/i;
+  // 值形态：`sm 640` / `sm（640）` / `` `sm` `≥ 768px` ``（后接数字，容 24 字符间隔）
+  const L4A_VALUE_RE = /\b(xs|sm|md|lg|xl)\b[^\n]{0,24}?\d{3,4}/i;
+  // 表格形态：`| \`sm\` | \`≥ 768px\` |` —— 现场 b-end.md 的实际写法（反引号包裹 + ≥ 符号）
+  const L4A_TABLE_RE = /\|\s*`?\s*(xs|sm|md|lg|xl)\s*`?\s*\|[^|\n]*\d{3,4}/i;
+  const l4avals = arche.map(a => {
+    const body = sectionBodyRaw(a.text, 'layout');
+    if (body === null) return false;   // 缺 layout 段是真问题（必填段）→ 走降级规则
+    return L4A_KEY_RE.test(body) || L4A_VALUE_RE.test(body) || L4A_TABLE_RE.test(body);
+  });
+
+  // L4b = 页面范式内容层：引用内置 / 同 <端> → 免检；项目自有 → **子块内**页面类型表行数 ≥3
+  const l4bvals = arche.map(a => {
+    if (!a.declared) return 'warn';
+    const s = a.source || '';
+    if (/^引用内置$/.test(s) || /^同/.test(s)) return true;
+    if (/^项目自有/.test(s)) return a.tableRows >= 3 ? true : 'warn';
+    return 'warn';
+  });
+
+  const agg = (vals) => vals.every(v => v === true) ? true
+    : (vals.some(v => v === 'warn') ? 'warn' : false);
+  const perEnd = (vals) => arche.map((a, i) => `${a.name} ${vals[i] === true ? '✅' : '⚠️'}`).join(' / ');
+
+  const l3 = agg(l3vals);
+  const l4a = agg(l4avals);
+  const l4b = agg(l4bvals);
+  const l4 = (l4a === true && l4b === true) ? true : ((l4a === 'warn' || l4b === 'warn') ? 'warn' : false);
+
+  layerResults['L3-业务模式'] = l3;
+  layerResults['L4-页面范式'] = l4;
+  if (arche.length > 1) {
+    line(`L3 业务模式      ${badge(l3)} ${perEnd(l3vals)}（按端求值）`);
+    line(`L4 页面范式      ${badge(l4)} 布局 ${perEnd(l4avals)} ｜ 范式 ${perEnd(l4bvals)}`);
+  } else {
+    const a0 = arche[0];
+    line(`L3 业务模式      ${badge(l3)} ${l3 === true
+      ? `页面范式来源已声明（${a0.source}）`
+      : '未声明页面范式来源 —— 可在 layout 段补 `页面范式来源：引用内置`，或经 iterate 补写（不阻断）'}`);
+    const rowInfo = /^项目自有/.test(a0.source || '') ? `（页面类型 ${a0.tableRows} 行）` : '';
+    line(`L4 页面范式      ${badge(l4)} 布局基础 ${badge(l4a)} ｜ 页面范式内容 ${badge(l4b)}${rowInfo}`);
+  }
 
   // L5 Primer（同目录 primer.md 存在）
   const primerExists = existsSync(join(dsDir, 'primer.md'));
@@ -425,14 +436,19 @@ if (markdown === null) {
   line(`L5 Primer        ${labelOf(primerExists)} ${primerExists ? 'primer.md 存在' : '未生成 primer.md'}`);
 
   line('------------------------------------------');
-  const passed = Object.values(layerResults).filter(Boolean).length;
-  const total = Object.keys(layerResults).length;
+  // v0.55.0：计数用**严格比较** `=== true`——原 `filter(Boolean)` 会把 `'warn'`（truthy）也算达标。
+  const vals = Object.values(layerResults);
+  const passed = vals.filter(v => v === true).length;
+  const warnCount = vals.filter(v => v === 'warn').length;
+  const total = vals.length;
   const mark = (k, v) => {
     if (k === 'L1-双主题' && !v) return '⏭️';
+    if (v === 'warn') return '⚠️';                 // 三态：与明细行同源（否则同一次运行出现相反标签）
     return v ? '✅' : (downgrade ? '⚠️' : '❌');
   };
   line(`合规层：${Object.entries(layerResults).map(([k, v]) => `${k} ${mark(k, v)}`).join(' | ')}`);
-  line(`（${passed}/${total} 层达标；contract=${contract || 'unset'}${downgrade ? ' → 不达标降级 WARN' : ''}；不输出总分）`);
+  line(`（${passed}/${total} 层达标${warnCount ? `；${warnCount} 项待补写` : ''}；contract=${contract || 'unset'}`
+    + `${downgrade ? ' → 不达标降级 WARN' : ''}${contractUnknown ? '（未识别取值，按最严档）' : ''}；不输出总分）`);
 }
 line();
 
@@ -440,10 +456,13 @@ line();
 
 if (JSON_OUT) {
   const report = {
-    schemaVersion: '0.20.0',
+    // v0.55.0：`layers` 值域由 boolean 升为 `true | false | 'warn'` → schemaVersion 升版。
+    // 按端求值时（both）各层值为聚合结果，逐端明细见 stdout。
+    schemaVersion: '0.21.0',
     hardChecks: { passed: issues.length === 0, issues },
     layers: layerResults,
     contract: contract || null,
+    contractUnknown,
     strict: STRICT,
   };
   console.log(JSON.stringify(report, null, 2));

package/scripts/infer-workflow.mjs

@@ -3,6 +3,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { readState } from './lib/state-loader.mjs';
+import { parseTaskLine } from './lib/md-normalize.mjs';
 
 const CODE_EXTS = [
   'mjs', 'js', 'ts', 'jsx', 'tsx', 'cjs',
@@ -30,8 +31,16 @@ function readText(dir, name) {
   return existsSync(p) ? readFileSync(p, 'utf-8') : '';
 }
 
+/**
+ * tasks.md 任务行计数——**直接决定 hotfix(≤2) / tweak(≤4) / full 档位**。
+ *
+ * v0.55.0 §8.4.3 横展（FB-4，约束③ 高风险点）：识别改用共享原语 `parseTaskLine`。
+ * 原 `/^- \[([ x])\]/gm` 的三个差异面：**只认小写 `x`**（`[X]` 漏计）、**不容缩进**、
+ * **不认 `*` bullet**。三者都会让 taskCount 变小 → 档位被低估（full 误判为 hotfix/tweak）。
+ * 差异对照见 tests/lib/checkbox-consistency.test.mjs。
+ */
 function countTasks(tasks) {
-  return (tasks.match(/^- \[([ x])\]/gm) || []).length;
+  return tasks.split('\n').map(line => parseTaskLine(line)).filter(Boolean).length;
 }
 
 function collectFiles(text) {

package/scripts/lib/arch-merge.mjs

@@ -207,25 +207,39 @@ function buildCurrentStateSection(aggregates) {
  * 4. 块范围 = 锚行 → 下一个块起点，块起点 ∈ {`^### change:`、`^## ` / `^# `、`^<!-- arch:`、
  *    文件末尾}。边界之外的内容（含 change 级模板残留表）由本 change 块独占，随替换清理。
  * 5. 删除死变量 `anchorRe`（`/^#{3,4}\s*.*change[:\s].*$/mi`，从未被引用）。
+ *
+ * v0.55.0 §8.4.3 横展（FB-4）：锚行与日志标题容忍加粗/全角冒号等**纯格式变体**
+ * （`### **change:foo**`、`## **演进日志**`）。放宽前这类锚行**识别不到** →
+ * 走"追加到标题后"分支 → 同一 change 的块被**重复追加**（与 R11 缺陷同型的膨胀形态，
+ * 只是触发条件是格式变体）。提示：`change:` 关键词与 `###` 层级、change 名本身不放宽。
+ * 检测到同 change 锚块 >1（历史重复）时 WARN，只替换首个，不静默。
  */
+const EVOLUTION_LOG_HEADING_RE = /^#{2,3}\s*\d*\.?\s*\**\s*(演进日志|Evolution Log)\**/m;
+
 function upsertEvolutionLog(globalContent, srcContent, changeName) {
   // 从 change 源提取演进日志条目（标题 + 正文）
-  const logStart = srcContent.search(/^#{2,3}\s*\d*\.?\s*(演进日志|Evolution Log)/m);
+  const logStart = srcContent.search(EVOLUTION_LOG_HEADING_RE);
   if (logStart < 0) return globalContent;
   const logSection = srcContent.slice(logStart).trim();
   const anchor = `### change:${changeName}`;
-  const logBlock = `${anchor}\n${logSection.replace(/^#{2,3}\s*\d*\.?\s*(演进日志|Evolution Log)/m, '').trim()}`;
+  const logBlock = `${anchor}\n${logSection.replace(EVOLUTION_LOG_HEADING_RE, '').trim()}`;
 
   // 已存在 → 替换整块；否则追加到演进日志段末尾
-  const logHeadingRe = /^#{2,3}\s*\d*\.?\s*(演进日志|Evolution Log)/m;
-  const anchorRe = new RegExp(`^### change:${escapeRegExp(changeName)}\\s*$`, 'm');
+  const logHeadingRe = EVOLUTION_LOG_HEADING_RE;
+  // 锚行：`### change:<name>` 的宽容形态（容忍 `**` 包裹、全角冒号、冒号后空格）
+  const anchorSrc = `^###\\s*\\**\\s*change\\s*[:：]\\s*\\**\\s*${escapeRegExp(changeName)}\\s*\\**\\s*$`;
+  const anchorRe = new RegExp(anchorSrc, 'm');
   if (anchorRe.test(globalContent)) {
     // 块起点：下一个 change 块 / 下一个一二级标题 / arch marker / 文件末尾
     const blockRe = new RegExp(
-      `^### change:${escapeRegExp(changeName)}\\s*$[\\s\\S]*?`
-      + `(?=^### change:|^#{1,2}\\s|^<!-- arch:|$(?![\\s\\S]))`,
+      `${anchorSrc}[\\s\\S]*?`
+      + `(?=^###\\s*\\**\\s*change\\s*[:：]|^#{1,2}\\s|^<!-- arch:|$(?![\\s\\S]))`,
       'm'
     );
+    const duplicates = (globalContent.match(new RegExp(anchorSrc, 'gm')) || []).length;
+    if (duplicates > 1) {
+      console.warn(`  [WARN] 演进日志存在 ${duplicates} 个 change:${changeName} 锚块（历史重复追加），本次只替换第一个，请人工清理其余块`);
+    }
     const matched = globalContent.match(blockRe);
     if (matched) {
       // 被替换段内若含疑似人工内容（非标题/非表格行/非空行/非注释）→ 告警不静默

package/scripts/lib/arch-parse.mjs

@@ -17,6 +17,11 @@
 //   → 两重失配 → 列语义整体错位 → 全局台账被写入 `上下文=extend`、
 //   `根实体=SysFrontSystem（不变）`。**这是污染而非缺失**。改判据为表头定位。
 
+// v0.55.0 §8.4.3 横展（FB-4）：强调剥离改为引用共享层 `md-normalize.mjs`
+// （单一真相源）——本文件 v0.53.0 的实现已提升为全仓库约定，此处删除本地副本，
+// 避免「两份实现各自漂移」的复发形态。
+import { stripEmphasis } from './md-normalize.mjs';
+
 /**
  * HTTP 方法词表——**三个方法正则的唯一事实源**。
  *
@@ -54,17 +59,6 @@ const PATH_PREFIX_RE = /^\/[\w\-/{},.]*/;
  */
 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。
  *

package/scripts/lib/ds-inputs.mjs

@@ -0,0 +1,125 @@
+// ds-inputs.mjs — 设计系统输入解析共享层（v0.55.0）
+//
+// ── 为什么存在（设计 §8.2.2 g）────────────────────────────────────────────────
+// `resolveInputs` 原在 design-token-guard.mjs 内，gen-primer.mjs 需要同一套"从 base 路径
+// 发现端变体"的逻辑（primer 的 digest 必须覆盖参与合并的全部文件，否则变体变更不判 STALE
+// → prototype Step 0 gate 放行 → 原型静默用旧页面范式）。
+//
+// 但 guard **不能直接 import**：它是顶层副作用模块（顶层解析 argv、顶层 process.exit、
+// 顶层打印整份报告）——import 它会让 gen-primer 先打印 guard 报告然后提前退出。
+// 故把纯逻辑下沉到本模块，guard 与 gen-primer 双双 import。
+//
+// ── 输入规则（原 guard 注释，语义不变）──────────────────────────────────────
+//   ① 传入目录 → 以目录内 base.md 为主体；② 传入 base.md → 以它为主体；
+//   ③ 传入变体文件 → base.md 主体 + 该文件。
+//   ④ 主体自身已含全部 9 段（单文件系统 / 转换器产物）→ 单文件模式，不合并
+//      （避免卷入同目录无关 md）。
+//   ⑤ 主体不含全 9 段 → 合并**约定命名的端变体**（`*-end.md` + `variants/` 子目录）；
+//      `--variant <name>` 可显式纳入非约定命名的变体（逃生通道）。
+//      含必选段但未被纳入的其它 md → 告警列出（不静默补齐：一个 notes.md 不该把
+//      残缺系统伪装成 PASS，也不该被静默忽略）。
+//
+// v0.55.0 新增：**单文件模式也执行 ignored 计算**（原实现在 `!subjectComplete` 分支内，
+// 单文件模式整块被跳过 → 同目录变体静默不参与判据）。
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, basename, sep } from 'node:path';
+import { extractH2Headers, hasSection } from './ds-parse.mjs';
+
+/** 9 个必选 ## 段（design-system.md schema，设计 §4.1.1）。 */
+export const REQUIRED_SECTIONS = [
+  'color', 'typography', 'spacing', 'layout', 'components',
+  'motion', 'voice', 'brand', 'anti-patterns',
+];
+
+/** 可选 ## 段——仅作可见性报告，永不计入失败。 */
+export const OPTIONAL_SECTIONS = [
+  'palette', 'aliases', 'extensions', 'principles', 'governance',
+  '来源与裁决记录',   // v0.55.0：导入类创建条件必填（审计层 advisory，设计 §8.2.1）
+];
+
+/** 非段落文件：不参与合并，也不算"未纳入"告警。 */
+export const NON_SECTION_FILES = new Set(['primer.md', 'pending.md', 'readme.md', 'index.md']);
+
+/**
+ * 端变体命名约定：`*-end.md`（b-end / c-end / mobile-end …）+ `variants/` 子目录内全部 md
+ * （如 dark.md）。收紧为约定集而非「同目录任意 md」——否则一个含 `## spacing` 的 notes.md
+ * 就能补齐缺失段，把残缺系统伪装成 PASS。非约定名可用 `--variant <name>` 显式纳入。
+ */
+export const KNOWN_VARIANT_RE = /-end\.md$/i;
+
+/** Read a file as UTF-8, or return null when it does not exist. */
+export function readFileOrNull(filePath) {
+  if (!filePath || !existsSync(filePath)) return null;
+  return readFileSync(filePath, 'utf-8');
+}
+
+/** 设计系统目录内的全部候选 md（dir 与 variants/ 两层，排除 base 与非段落文件）。 */
+export function designSystemMds(dir) {
+  const out = [];
+  for (const d of [dir, join(dir, 'variants')]) {
+    if (!existsSync(d)) continue;
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      if (entry.name === 'base.md' || NON_SECTION_FILES.has(entry.name.toLowerCase())) continue;
+      out.push(join(d, entry.name));
+    }
+  }
+  return out.sort();
+}
+
+/** 约定命名的端变体候选。 */
+export function variantCandidates(dir) {
+  return designSystemMds(dir).filter(f => KNOWN_VARIANT_RE.test(basename(f)) || f.includes(`${sep}variants${sep}`));
+}
+
+/**
+ * 解析设计系统输入，返回 `{ dir, files, singleFile, ignored }`。
+ *
+ * @param {string} input        目录 / base.md / 变体文件路径
+ * @param {string|null} variantName  `--variant <name>` 显式指定的变体名（逃生通道）
+ */
+export function resolveInputs(input, variantName) {
+  const isDir = existsSync(input) && statSync(input).isDirectory();
+  const dir = isDir ? input : dirname(input);
+  const parts = [];
+
+  if (isDir) {
+    parts.push(join(dir, 'base.md'));
+  } else if (basename(input) === 'base.md') {
+    parts.push(input);
+  } else {
+    parts.push(join(dir, 'base.md'));  // 传入变体文件时仍以 base 为主体（base 优先）
+    parts.push(input);
+  }
+
+  const present = parts.filter(f => existsSync(f) && readFileOrNull(f) !== null);
+  const subject = present[0] ? readFileOrNull(present[0]) : null;
+  const subjectComplete = subject !== null
+    && REQUIRED_SECTIONS.every(s => hasSection(extractH2Headers(subject), s));
+
+  let merged = [...present];
+  let ignored = [];
+  if (!subjectComplete) {
+    // --variant <name> 为显式指定：在**全部**候选 md 中按名匹配（含非约定命名），作为逃生通道
+    const variants = variantName
+      ? designSystemMds(dir).filter(f => basename(f).includes(variantName))
+      : variantCandidates(dir);
+    for (const v of variants) if (!merged.includes(v)) merged.push(v);
+  }
+
+  // v0.55.0：ignored 计算**移出** `!subjectComplete` 分支——单文件模式下同目录变体
+  // 同样不参与判据，同样必须告警（原实现整块跳过 → 静默）。
+  {
+    const mergedSet = new Set(merged);
+    const scope = variantName ? [] : designSystemMds(dir);
+    for (const f of scope) {
+      if (mergedSet.has(f)) continue;
+      const text = readFileOrNull(f) || '';
+      const headers = extractH2Headers(text);
+      if (REQUIRED_SECTIONS.some(s => hasSection(headers, s))) ignored.push(f);
+    }
+  }
+
+  return { dir, files: merged, singleFile: subjectComplete, ignored };
+}