@xulthekl/team-flow 0.53.0 → 0.54.0

package/scripts/gen-primer.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// gen-primer.mjs — 从 base.md 确定性生成 primer.md（v0.54.0，设计 §4.1.2）
+//
+// primer 是"AI 约束入口"：组件白名单 + token 速查 + 硬规则，供 prototype-builder 消费。
+// 确定性：除"生成时间"一行外，输出完全由 base.md 内容决定（纯字符串拼接，零 LLM）。
+//
+// Usage:
+//   node scripts/gen-primer.mjs <base.md path> [--out <primer path>]
+//     生成 primer（默认写 base.md 同目录 primer.md）
+//   node scripts/gen-primer.mjs <base.md path> --check
+//     校验同目录 primer.md 的 digest 与 base.md 是否一致
+//     exit 0 = 一致；exit 2 = 过期或缺失（供 builder gate 判定）
+//
+// 配套测试："生成物 == 源表"（tests/lib/gen-primer.test.mjs）
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import {
+  parseComponentsTable,
+  parseContract,
+  parseA1Tokens,
+  parseAntiPatterns,
+  COMPONENT_COUNT_PASS,
+  COMPONENT_COUNT_WARN,
+} from './lib/ds-parse.mjs';
+
+const argv = process.argv.slice(2);
+const CHECK = argv.includes('--check');
+const outIdx = argv.indexOf('--out');
+const outArg = outIdx !== -1 ? argv[outIdx + 1] : null;
+const positional = argv.filter((a, i) => !a.startsWith('--') && !(outIdx !== -1 && i === outIdx + 1));
+const basePath = positional[0];
+
+if (!basePath) {
+  console.error('Usage: node scripts/gen-primer.mjs <base.md path> [--out <primer path>] [--check]');
+  process.exit(1);
+}
+
+const baseAbs = resolve(basePath);
+if (!existsSync(baseAbs)) {
+  console.error(`base.md not found: ${baseAbs}`);
+  process.exit(1);
+}
+
+const baseContent = readFileSync(baseAbs, 'utf-8');
+const digest = createHash('sha256').update(baseContent, 'utf-8').digest('hex');
+const digestShort = digest.slice(0, 16);
+const primerPath = outArg ? resolve(outArg) : join(dirname(baseAbs), 'primer.md');
+const DIGEST_RE = /sha256:([0-9a-f]{16,})/;
+
+// ── --check 模式：校验 primer 新鲜度（builder gate 调用）──
+
+if (CHECK) {
+  if (!existsSync(primerPath)) {
+    console.error(`STALE: primer.md 不存在（${primerPath}）——请运行 design-system iterate 生成`);
+    process.exit(2);
+  }
+  const primerContent = readFileSync(primerPath, 'utf-8');
+  const m = primerContent.match(DIGEST_RE);
+  if (!m) {
+    console.error('STALE: primer.md 无 digest 头部（格式不符）——请重新生成');
+    process.exit(2);
+  }
+  if (m[1] !== digestShort && !digest.startsWith(m[1])) {
+    console.error(`STALE: primer.md 已过期（记录 ${m[1]}，当前 base.md ${digestShort}）——请运行 design-system iterate 重新生成`);
+    process.exit(2);
+  }
+  console.log(`OK: primer.md digest 一致（${digestShort}）`);
+  process.exit(0);
+}
+
+// ── 生成模式 ──
+
+const table = parseComponentsTable(baseContent);
+if (!table) {
+  console.error('base.md 的 components 段未检测到组件契约表（需 | 组件 | 类型 | variants | sizes | states | 用途 | 禁止 | 表格）。');
+  console.error('存量系统请先运行 design-system iterate 补全契约表。');
+  process.exit(1);
+}
+
+const contract = parseContract(baseContent);
+const a1 = parseA1Tokens(baseContent);
+const antiPatterns = parseAntiPatterns(baseContent);
+const componentRows = table.rows;
+const count = componentRows.length;
+const countLabel = count >= COMPONENT_COUNT_PASS
+  ? 'PASS（完整）'
+  : count >= COMPONENT_COUNT_WARN
+    ? 'WARN（可用，建议补全）'
+    : 'FAIL（低于起步线）';
+
+// 白名单行：Name(variants · sizes)
+const whitelistLines = componentRows.map(r => {
+  const variants = r.hasVariants ? r.variants.replace(/\s*\/\s*/g, '|') : '—';
+  const sizes = r.sizes && r.sizes !== '—' ? r.sizes.replace(/\s*\/\s*/g, '|') : '—';
+  const typeMark = r.type === '豁免' ? '（展示类）' : r.type === '轻量' ? '（轻量）' : '';
+  return `- ${r.name}${typeMark}: variants=${variants} · sizes=${sizes}`;
+});
+
+// Token 速查行
+const tokenKeys = ['--bg', '--surface', '--fg', '--muted', '--border', '--accent'];
+const tokenLine = tokenKeys
+  .filter(k => a1[k])
+  .map(k => `${k} ${a1[k]}`)
+  .join(' / ');
+const fontDisplay = a1['--font-display'] ? `\n- --font-display: ${a1['--font-display']}` : '';
+const fontBody = a1['--font-body'] ? `\n- --font-body: ${a1['--font-body']}` : '';
+
+const hardRules = [
+  '1. 只使用上方白名单组件与 token；若需系统外元素 → 记录为新组件需求（ds_increment），不自造',
+  '2. 数据展示须覆盖 Loading / Empty / Error / Populated / Edge 五状态（craft/state-coverage.md）',
+  ...antiPatterns.map((p, i) => `${i + 3}. ${p}`),
+];
+
+const primer = `# AI Primer — 原型生成约束
+
+> 本文件由 scripts/gen-primer.mjs 从 base.md 确定性生成，请勿手工编辑。
+> 生成时间：${new Date().toISOString()} | 来源：base.md @ sha256:${digestShort}
+> 契约表：${count} 类组件（${countLabel}） | contract=${contract || 'unset'}
+
+## 可用组件白名单（只用这些）
+
+${whitelistLines.join('\n')}
+
+## Token 速查
+
+${tokenLine || '（base.md 未内联 A1 token 值，请以 design-tokens.css 为准）'}${fontDisplay}${fontBody}
+
+## 硬规则
+
+${hardRules.join('\n')}
+
+## 页面范式
+
+section 骨架与页面类型节奏见 prototype skill 的 layouts.md（reference：管理后台列表页 / 表单页 / 仪表盘 / Landing / 文档索引）。
+`;
+
+mkdirSync(dirname(primerPath), { recursive: true });
+writeFileSync(primerPath, primer, 'utf-8');
+console.log(`primer 已生成：${primerPath}`);
+console.log(`  组件白名单：${count} 类（${countLabel}）`);
+console.log(`  digest：sha256:${digestShort}`);

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

@@ -1,15 +1,44 @@
 #!/usr/bin/env node
-// design-token-guard.mjs — 设计系统完整性检查（v0.18.0）
+// design-token-guard.mjs — 设计系统完整性检查（v0.54.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,
+  parseComponentsTable,
+  parseContract,
+  COMPONENT_TYPE_MIN_STATES,
+  COMPONENT_COUNT_PASS,
+  COMPONENT_COUNT_WARN,
+} from '../lib/ds-parse.mjs';
 
 // ── Check definitions ──
 
@@ -20,7 +49,7 @@ const REQUIRED_SECTIONS = [
 ];
 
 // Optional ## sections — reported for visibility, never counted as failures.
-const OPTIONAL_SECTIONS = ['palette', 'aliases', 'extensions'];
+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'];
@@ -50,36 +79,6 @@ function readFileOrNull(filePath) {
   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 +98,127 @@ 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);
+// ── 输入解析：单文件系统 或 base + 端变体拆分系统 ──
+//
+// 权威排布是「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 };
+}
+
+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.54.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>` 显式纳入');
+}
+else if (singleFile) line('输入模式: 单文件（主体已含全部 9 段）');
+if (VARIANT) line(`variant 过滤: ${VARIANT}`);
+if (STRICT) line('mode: --strict (legacy 按 v1 标签输出)');
 line();
 
 // ── File availability ──
@@ -132,7 +230,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 +241,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 +270,7 @@ if (markdown === null) {
 }
 line();
 
-// ── A1 Identity Tokens ──
+// ── A1 Identity Tokens (hard) ──
 
 line('## A1 Identity Tokens (8 required)');
 if (css === null) {
@@ -181,7 +283,7 @@ if (css === null) {
 }
 line();
 
-// ── A2 Derived Tokens ──
+// ── A2 Derived Tokens (hard) ──
 
 line('## A2 Derived Tokens');
 if (css === null) {
@@ -200,7 +302,7 @@ if (css === null) {
 }
 line();
 
-// ── B-Slot Aliases ──
+// ── B-Slot Aliases (hard) ──
 
 line('## B-Slot Aliases');
 if (css === null) {
@@ -213,25 +315,144 @@ 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）──
+//
+// 标签规则：contract=v1（或无标记且非 strict？见下）→ 不达标标 FAIL；
+//           contract=legacy/无标记 → 降级 WARN；--strict → legacy 也按 v1 标签。
+// 报告中所有标签均不阻断（不影响 exit code）。
+
+const contract = markdown ? parseContract(markdown) : null;
+const downgrade = !STRICT && contract !== 'v1';   // legacy 或无标记 → 降级
+const labelOf = (ok) => ok ? '✅' : (downgrade ? '⚠️' : '❌');
+
+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 业务模式（页面范式的归属声明：设计系统侧只做**引用**，节奏表在 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 段缺栅格或断点声明'}`);
+
+  // 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('------------------------------------------');
+  const passed = Object.values(layerResults).filter(Boolean).length;
+  const total = Object.keys(layerResults).length;
+  const mark = (k, v) => {
+    if (k === 'L1-双主题' && !v) 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();
 
-// ── Verdict ──
+// ── Verdict（exit 语义：仅硬校验决定 exit code）──
+
+if (JSON_OUT) {
+  const report = {
+    schemaVersion: '0.20.0',
+    hardChecks: { passed: issues.length === 0, issues },
+    layers: layerResults,
+    contract: contract || null,
+    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);