@xulthekl/team-flow 0.53.0 → 0.55.0

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

@@ -1,27 +1,60 @@
 #!/usr/bin/env node
-// design-token-guard.mjs — 设计系统完整性检查（v0.18.0）
+// design-token-guard.mjs — 设计系统完整性检查（v0.55.0）
 //
-// Validates that a design-system.md is structurally complete and that a
-// design-tokens.css provides the token coverage the prototype skill relies on
-// (A1 identity tokens, A2 derived state tokens, B-slot alias tokens).
+// 两部分（v0.54.0 新增六层审计；设计 §4.1.5）：
+//   A. 硬校验（失败 exit 1）：9 段 schema / palette 5 方向 / A1 identity / A2 color-mix / B-slot 别名
+//   B. 六层审计报告（advisory，恒 exit 0）：L0 原则治理 / L0 可访问性 / L1 Token / L1 双主题 /
+//      L2 组件契约 / L3 业务模式 / L4 页面范式 / L5 Primer
 //
-// Usage: node scripts/guard/design-token-guard.mjs <design-system.md path> [design-tokens.css path]
-//   Exit 0: PASS — all required checks satisfied
-//   Exit 1: FAIL — one or more issues found (listed in the report)
-
-import { readFileSync, existsSync } from 'node:fs';
+// v0.54.0 新增：
+//   - 组件契约表检查（§4.1.1）：组件数三档（<10 FAIL 标签 / 10-14 WARN / ≥15 PASS）
+//     + 分组 states 规则（交互 ≥3 / 轻量 ≥2 / 豁免跳过）+ variants 列非空（仅交互/轻量）
+//   - governance.contract 标记：v1 → 不达标标 FAIL 标签；legacy/无标记 → 降级 WARN
+//   - --strict：legacy 系统也按 v1 标签输出（不改变 exit code，供存量自查）
+//   - --json：结构化输出（供测试与工具消费）
+//
+// exit 语义（v1.5 设计定案）：硬校验失败 → exit 1；六层报告的 WARN/FAIL 标签一律不阻断（exit 0）
+//
+// 输入（v0.54.0 修正）：接受**设计系统目录**或单个 md——
+//   - 目录 / base.md → 若 base 自身不含全 9 段（拆分布局），自动合并端变体后再断言 9 段
+//   - 单文件（已含全 9 段，如转换器产物）→ 原样断言
+//   - --variant <name> 限定合并哪个端变体
+//
+// Usage: node scripts/guard/design-token-guard.mjs <design-system.md | dir> [design-tokens.css path] [--variant <name>] [--strict] [--json]
+//
+// ⚠ 前瞻风险（v0.54.0 记录）：本脚本按插件内路径（${CLAUDE_PLUGIN_ROOT}/scripts/…）调用。
+//   design-system skill 目前不在 runtime-skill 名单（`tests/lib/platform-runtime-distribution.test.mjs`），
+//   但它是被 prototype 在运行期调用的——若平台策略将其收进名单，调用方式需整体改造。
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, basename, sep } from 'node:path';
+import {
+  extractH2Headers,
+  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'];
-
 // The 5 palette directions checked when a palette section exists.
 const PALETTE_DIRECTIONS = ['neutral', 'primary', 'success', 'warning', 'danger'];
 
@@ -44,42 +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');
-}
-
-// Collect the lower-cased text of every level-2 ("## ") markdown header.
-function extractH2Headers(markdown) {
-  return markdown
-    .split('\n')
-    .filter(line => /^##\s+/.test(line) && !/^###/.test(line))
-    .map(line => line.replace(/^##\s+/, '').trim().toLowerCase());
-}
-
-// True when any ## header mentions the given section name.
-function hasSection(headers, section) {
-  return headers.some(header => header.includes(section));
-}
-
-// Return the body of a section (text between its ## header and the next ##
-// header or EOF), lower-cased; null when the section is absent.
-function sectionBody(markdown, section) {
-  const lines = markdown.split('\n');
-  const startIdx = lines.findIndex(
-    line => /^##\s+/.test(line) && !/^###/.test(line) &&
-      line.replace(/^##\s+/, '').trim().toLowerCase().includes(section),
-  );
-  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').toLowerCase();
-}
-
 // Escape a token name for safe use inside a RegExp (names contain "--").
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -99,28 +96,62 @@ function extractVarTarget(value) {
 
 // ── Report accumulation ──
 
-const issues = [];
-function line(text = '') { console.log(text); }
+const issues = [];      // hard-check failures (exit 1)
+const audit = [];       // six-layer advisory lines
+function line(text = '') { if (!JSON_OUT) console.log(text); }
 function pass(text) { line(`  ✅ ${text}`); }
 function fail(text) { issues.push(text); line(`  ❌ ${text}`); }
+function warnLine(text) { line(`  ⚠️  ${text}`); }
 
 // ── Argument parsing ──
 
-const mdPath = process.argv[2];
-const cssPath = process.argv[3];
+const argv = process.argv.slice(2);
+const STRICT = argv.includes('--strict');
+const JSON_OUT = argv.includes('--json');
+const variantIdx = argv.indexOf('--variant');
+const VARIANT = variantIdx !== -1 ? argv[variantIdx + 1] : null;
+const positional = argv.filter((a, i) => !a.startsWith('--') && !(variantIdx !== -1 && i === variantIdx + 1));
+
+const mdPath = positional[0];
+const cssPath = positional[1];
 
 if (!mdPath) {
-  console.error('Usage: node scripts/guard/design-token-guard.mjs <design-system.md path> [design-tokens.css path]');
+  console.error('Usage: node scripts/guard/design-token-guard.mjs <design-system.md | 设计系统目录> [design-tokens.css path] [--variant <name>] [--strict] [--json]');
   process.exit(1);
 }
 
-const markdown = readFileOrNull(mdPath);
+// ── 输入解析：已下沉至 scripts/lib/ds-inputs.mjs（v0.55.0）──
+//
+// 动机：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
+  ? mdFiles.map(f => readFileOrNull(f)).filter(t => t !== null).join('\n\n')
+  : null;
 const css = cssPath ? readFileOrNull(cssPath) : null;
 
-line('Design Token Guard v0.18.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) {
+  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}`);
+if (STRICT) line('mode: --strict (legacy 按 v1 标签输出)');
 line();
 
 // ── File availability ──
@@ -132,7 +163,7 @@ if (cssPath && css === null) {
   fail(`design-tokens.css not found: ${cssPath}`);
 }
 
-// ── 9-Section Check ──
+// ── 9-Section Check (hard) ──
 
 line('## 9-Section Check');
 if (markdown === null) {
@@ -143,14 +174,18 @@ if (markdown === null) {
     if (hasSection(headers, section)) pass(section);
     else fail(`${section} — MISSING`);
   }
-  // Optional sections: report presence only, never fail.
   for (const section of OPTIONAL_SECTIONS) {
     if (hasSection(headers, section)) line(`  ℹ️  ${section} (optional, present)`);
   }
+  // 诊断提示（common footgun）：base 品牌层不含 typography/spacing/layout/motion，
+  // 且目录内没有可合并的端变体 → 大概率是把「端变体承载的段」漏建了。
+  if (mdFiles.length === 1 && !singleFile && ['typography', 'spacing', 'layout', 'motion'].every(s => !hasSection(headers, s))) {
+    line('  💡 提示：本文件是 base 品牌层（不含 typography/spacing/layout/motion，由端变体承载），但同目录未见可合并的端变体（如 b-end.md / c-end.md）——拆分系统请补变体文件，或把该文件补齐为单文件系统。');
+  }
 }
 line();
 
-// ── Palette Check (5 directions) ──
+// ── Palette Check (hard when present) ──
 
 line('## Palette Check (5 directions)');
 if (markdown === null) {
@@ -168,7 +203,7 @@ if (markdown === null) {
 }
 line();
 
-// ── A1 Identity Tokens ──
+// ── A1 Identity Tokens (hard) ──
 
 line('## A1 Identity Tokens (8 required)');
 if (css === null) {
@@ -181,7 +216,7 @@ if (css === null) {
 }
 line();
 
-// ── A2 Derived Tokens ──
+// ── A2 Derived Tokens (hard) ──
 
 line('## A2 Derived Tokens');
 if (css === null) {
@@ -200,7 +235,7 @@ if (css === null) {
 }
 line();
 
-// ── B-Slot Aliases ──
+// ── B-Slot Aliases (hard) ──
 
 line('## B-Slot Aliases');
 if (css === null) {
@@ -213,25 +248,230 @@ if (css === null) {
       continue;
     }
     const target = extractVarTarget(value);
-    if (target === base) {
-      pass(`${token} → var(${target})`);
-    } else if (target) {
-      // Alias exists but points somewhere other than the expected base token.
-      fail(`${token} → var(${target}) (expected var(${base}))`);
+    if (target === base) pass(`${token} → var(${target})`);
+    else if (target) fail(`${token} → var(${target}) (expected var(${base}))`);
+    else pass(`${token} = ${value}`);
+  }
+}
+line();
+
+// ── 六层审计报告（advisory；v0.54.0 新增，§4.1.5；v0.55.0 三态 + L3/L4 改造）──
+//
+// 标签规则（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;
+
+// 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 = {};
+
+if (markdown === null) {
+  line('## 六层审计报告');
+  line('  ⏭️  skipped — design-system.md not found');
+} else {
+  line('## 六层审计报告');
+
+  // L0 原则与治理
+  const principlesBody = sectionBodyRaw(markdown, 'principles');
+  const principleCount = principlesBody
+    ? principlesBody.split('\n').filter(l => /^\s*(\d+[.、)]|[-*])\s+\S/.test(l)).length
+    : 0;
+  const hasGovernance = sectionBodyRaw(markdown, 'governance') !== null;
+  const l0ok = principleCount >= 3 && hasGovernance;
+  layerResults['L0-原则治理'] = l0ok;
+  line(`L0 原则与治理    ${labelOf(l0ok)} principles(${principleCount})+governance(${hasGovernance ? 'present' : 'missing'})`);
+
+  // L0 可访问性（base.md 内声明 WCAG）
+  const l0a11y = /wcag/i.test(markdown);
+  layerResults['L0-可访问性'] = l0a11y;
+  line(`L0 可访问性      ${labelOf(l0a11y)} ${l0a11y ? 'WCAG 声明存在' : '缺 WCAG 声明（可从 prototype craft 层提级）'}`);
+
+  // L1 Token（复用硬校验结果）
+  const l1ok = issues.length === 0;
+  layerResults['L1-Token'] = l1ok;
+  line(`L1 Token         ${labelOf(l1ok)} 硬校验${l1ok ? '全部通过' : `有 ${issues.length} 项失败`}`);
+
+  // L1 双主题（css 含暗色覆盖或同目录有 variants/dark.md）
+  const darkVariantExists = existsSync(join(dsDir, 'variants', 'dark.md'));
+  const cssDark = css ? /\[data-theme=["']dark["']\]|prefers-color-scheme\s*:\s*dark/i.test(css) : false;
+  const l1theme = darkVariantExists || cssDark;
+  layerResults['L1-双主题'] = l1theme;
+  line(`L1 双主题        ${l1theme ? '✅' : '⏭️ '} ${l1theme ? 'dark 变体或暗色覆盖存在' : '未启用（theme=light，可选）'}`);
+
+  // L2 组件契约（表格 + 三档 + 分组 states + variants 范围）
+  // 合并输入下按组件名去重（base 在合并顺序前 → base 行优先，端变体差异行不重复计数）
+  const rawTable = parseComponentsTable(markdown);
+  const table = rawTable && (() => {
+    const seen = new Map();
+    for (const r of rawTable.rows) if (!seen.has(r.name)) seen.set(r.name, r);
+    return { ...rawTable, rows: [...seen.values()] };
+  })();
+  if (!table) {
+    layerResults['L2-组件'] = false;
+    line(`L2 组件          ${labelOf(false)} 未检测到组件契约表（components 段无表格或类型列）`);
+  } else {
+    const count = table.rows.length;
+    const countOk = count >= COMPONENT_COUNT_PASS;
+    const countWarn = count >= COMPONENT_COUNT_WARN && count < COMPONENT_COUNT_PASS;
+    const stateViolations = table.rows.filter(r => {
+      const min = COMPONENT_TYPE_MIN_STATES[r.type];
+      return min !== null && r.statesCount < min;
+    });
+    const variantViolations = table.rows.filter(r => {
+      const min = COMPONENT_TYPE_MIN_STATES[r.type];
+      return min !== null && !r.hasVariants;
+    });
+    const l2ok = countOk && stateViolations.length === 0 && variantViolations.length === 0;
+    layerResults['L2-组件'] = l2ok;
+    if (l2ok) {
+      line(`L2 组件          ✅ ${count} 类契约表（PASS 档），states/variants 全部达标`);
     } else {
-      // Defined as a literal value rather than an alias to the base token.
-      pass(`${token} = ${value}`);
+      const parts = [];
+      if (!countOk) parts.push(countWarn ? `${count} 类（WARN 档：10-14）` : `${count} 类（低于起步线 10）`);
+      if (stateViolations.length) parts.push(`${stateViolations.length} 个组件 states 不足（${stateViolations.map(r => r.name).join('/')}）`);
+      if (variantViolations.length) parts.push(`${variantViolations.length} 个组件缺 variants（${variantViolations.map(r => r.name).join('/')}）`);
+      line(`L2 组件          ${countWarn && !stateViolations.length && !variantViolations.length ? '⚠️ ' : labelOf(false) + ' '}${parts.join('；')}`);
+      // WARN 档（10-14 类且其余达标）算通过（S2 验收口径）；否则按降级规则标注
+      layerResults['L2-组件'] = countWarn && stateViolations.length === 0 && variantViolations.length === 0;
     }
   }
+
+  // ── 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'));
+  layerResults['L5-Primer'] = primerExists;
+  line(`L5 Primer        ${labelOf(primerExists)} ${primerExists ? 'primer.md 存在' : '未生成 primer.md'}`);
+
+  line('------------------------------------------');
+  // 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} 层达标${warnCount ? `；${warnCount} 项待补写` : ''}；contract=${contract || 'unset'}`
+    + `${downgrade ? ' → 不达标降级 WARN' : ''}${contractUnknown ? '（未识别取值，按最严档）' : ''}；不输出总分）`);
 }
 line();
 
-// ── Verdict ──
+// ── Verdict（exit 语义：仅硬校验决定 exit code）──
+
+if (JSON_OUT) {
+  const report = {
+    // 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));
+}
 
 if (issues.length === 0) {
-  line('Verdict: PASS');
+  line('Verdict: PASS（硬校验通过；六层标签不阻断）');
   process.exit(0);
 }
 
-line(`Verdict: FAIL (${issues.length} issue${issues.length === 1 ? '' : 's'})`);
+line(`Verdict: FAIL (${issues.length} issue${issues.length === 1 ? '' : 's'}；硬校验失败)`);
 process.exit(1);

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。
  *