@xulthekl/team-flow 0.53.0 → 0.55.0

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);

package/scripts/lib/state-loader.mjs

@@ -249,7 +249,10 @@ function parseYaml(content) {
   for (const line of content.split('\n')) {
     const trimmed = line.trim();
     if (!trimmed || trimmed.startsWith('#')) continue;
-    const match = trimmed.match(/^(\w[\w_]*):\s*(.*)/);
+    // v0.55.0 §8.4.3 横展（FB-4）：只额外容忍**全角冒号**（`state：executing`）。
+    // 不得收紧：`line.trim()` 已容忍缩进，保持现状（约束①：缩进在 YAML 是语义，
+    // 本层不新增缩进容忍，也不拿掉既有 trim）；字段缺失不报错（约束②）。
+    const match = trimmed.match(/^(\w[\w_]*)[:：]\s*(.*)/);
     if (match) {
       const val = match[2].trim();
       if (val === 'null' || val === '') {

package/scripts/token-extract.mjs

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+// token-extract.mjs — 逆向建库的确定性证据提取器（v0.54.0，设计 §4.1.6 降级版）
+//
+// 从既有代码目录提取设计 token 证据：8 组正则证据机 → source-tokens.json + 统计报告。
+// **零 LLM、零语义推断**——只给"频次 + 位置分布"证据，语义角色（谁是 primary）由人工策展指定。
+//
+// Usage:
+//   node scripts/token-extract.mjs <代码目录> [--out <source-tokens.json 路径>] [--budget-ms 60000]
+//   node scripts/token-extract.mjs <代码目录> --report     # 只输出统计报告
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, dirname, extname, relative } from 'node:path';
+
+// ── 配置 ──
+
+const SCAN_EXTS = new Set(['.css', '.scss', '.less', '.html', '.htm', '.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte', '.json']);
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.cache', 'vendor', '__pycache__', '.turbo', 'out', 'target']);
+const MAX_FILE_SIZE = 512 * 1024;   // 512 KiB——超过只登记不扫描
+const DEFAULT_BUDGET_MS = 60_000;
+
+// ── 证据机（8 组正则，借鉴 open-design token-evidence）──
+
+const EVIDENCE = [
+  { kind: 'color', re: /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b/g },
+  { kind: 'color', re: /rgba?\(\s*\d+\s*,\s*\d+\s*,\s*\d+[^)]*\)/g },
+  { kind: 'color', re: /hsla?\(\s*[\d.]+\s*,\s*[\d.]+%\s*,\s*[\d.]+%[^)]*\)/g },
+  { kind: 'custom-prop', re: /--[a-zA-Z][\w-]*\s*:\s*([^;{}]+)[;}]/g, captureValue: true, nameCapture: /(--[a-zA-Z][\w-]*)/ },
+  { kind: 'font', re: /font-family\s*:\s*([^;{}]+)[;}]/gi, captureValue: true },
+  { kind: 'spacing', re: /(?:padding|margin|gap|inset|top|right|bottom|left)\s*:\s*([^;{}]+)[;}]/gi, captureValue: true },
+  { kind: 'radius', re: /border(?:-[a-z]+)?-radius\s*:\s*([^;{}]+)[;}]/gi, captureValue: true },
+  { kind: 'shadow', re: /box-shadow\s*:\s*([^;{}]+)[;}]/gi, captureValue: true },
+  { kind: 'tailwind', re: /\b(?:bg|text|border|from|to|via|ring)-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|100|200|300|400|500|600|700|800|900|950)\b/g },
+];
+
+// ── Markdown 规范树证据机（v0.55.0，设计 §8.2.1）──
+//
+// 定位：**证据报告器，不做取值裁决**。P1.5 反方实证——真实规范树的 token 主形态是
+// **Markdown 表格行**（`| \`--color-primary\` | \`#3A94DD\` |`），而上方的代码用证据机
+// （`custom-prop`）要求行尾 `;` 或 `}` → 表格行**永不匹配**，只剩裸 hex 机（有值无名）；
+// 且按频次排序会选出**错的主色**（现场：`#1890ff` ×155 vs 正确值 `#3a94dd` ×62 的跨期矛盾）。
+// 故这里只**如实呈现证据与冲突**（见下方的 conflicts 段），语义角色由人裁决——
+// 与既有原则"语义角色由人定，不由 LLM 定"一致。
+const DOC_EVIDENCE = [
+  // 表格行里的 token 名 + 值：| `--color-primary` | `#3A94DD` | ...
+  { kind: 'doc-table-token', re: /\|\s*`?(--[a-zA-Z][\w-]*)`?\s*\|\s*`?([^|`]+?)`?\s*(?=\|)/g, tokenPair: true },
+  // 键值行：- `--color-primary`: #3A94DD
+  { kind: 'doc-kv-token', re: /(--[a-zA-Z][\w-]*)\s*[:：]\s*([^\n|]+)/g, tokenPair: true },
+  // 标题（结构证据：组件名 / 页面类型候选）
+  { kind: 'doc-heading', re: /^#{2,4}\s+(.+?)\s*$/g },
+];
+
+/** "看起来是值"的形态白名单——用于过滤表格里与 token 名相邻的说明文字。 */
+const VALUE_LIKE_RE = /^(#[0-9a-fA-F]{3,8}|var\(|rgba?\(|hsla?\(|cubic-bezier\(|\d+(\.\d+)?(px|rem|em|%|ms|s)?$|[a-z-]+\([^)]*\)$)/;
+
+// ── 参数 ──
+
+const argv = process.argv.slice(2);
+const REPORT_ONLY = argv.includes('--report');
+const DOCS = argv.includes('--docs');          // v0.55.0：Markdown 规范树模式（create-from-docs）
+const outIdx = argv.indexOf('--out');
+const outArg = outIdx !== -1 ? argv[outIdx + 1] : null;
+const budgetIdx = argv.indexOf('--budget-ms');
+const budgetMs = budgetIdx !== -1 ? Number(argv[budgetIdx + 1]) || DEFAULT_BUDGET_MS : DEFAULT_BUDGET_MS;
+const positional = argv.filter((a, i) => !a.startsWith('--') && !(outIdx !== -1 && i === outIdx + 1) && !(budgetIdx !== -1 && i === budgetIdx + 1));
+const rootArg = positional[0];
+
+if (!rootArg) {
+  console.error('Usage: node scripts/token-extract.mjs <目录> [--out <json 路径>] [--budget-ms 60000] [--report] [--docs]');
+  console.error('  --docs：Markdown 规范树模式（.md 纳入扫描；输出证据报告 + 冲突呈现，不做取值裁决）');
+  process.exit(1);
+}
+// v0.55.0 修正：原实现 `positional[0]` 静默丢弃其余源路径——多仓场景下用户以为处理了全部。
+if (positional.length > 1) {
+  console.error(`❌ 收到 ${positional.length} 个源路径，但本工具一次只支持一个：${positional.join(' / ')}`);
+  console.error('   （多仓请分批调用，或先合并到一个目录）');
+  process.exit(1);
+}
+const root = resolve(rootArg);
+if (!existsSync(root) || !statSync(root).isDirectory()) {
+  console.error(`目录不存在或不可读：${root}`);
+  process.exit(1);
+}
+
+// docs 模式：纳入 .md；并把 .team-flow 加入跳过（否则产物落进被扫描树内部 → 二次运行自吞）
+if (DOCS) SCAN_EXTS.add('.md');
+SKIP_DIRS.add('.team-flow');
+
+// ── 走树（迭代式，预算控制）──
+
+const started = Date.now();
+const files = [];
+const skipped = [];
+const queue = [root];
+while (queue.length > 0) {
+  if (Date.now() - started > budgetMs) {
+    skipped.push({ reason: 'budget-exceeded', remaining: queue.length });
+    break;
+  }
+  const dir = queue.shift();
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { skipped.push({ path: dir, reason: 'unreadable' }); continue; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isSymbolicLink()) { skipped.push({ path: full, reason: 'symlink' }); continue; }
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) { skipped.push({ path: full, reason: 'directory-skiplist' }); continue; }
+      queue.push(full);
+      continue;
+    }
+    if (!SCAN_EXTS.has(extname(e.name).toLowerCase())) continue;
+    let size = 0;
+    try { size = statSync(full).size; } catch { continue; }
+    if (size > MAX_FILE_SIZE) { skipped.push({ path: full, reason: 'large-file', size }); continue; }
+    files.push(full);
+  }
+}
+
+// ── 证据采集 ──
+
+const evidence = new Map();   // key: `${kind}:${normalizedValue}` → { kind, value, count, sources[], usage:Set }
+
+function record(kind, value, file, line) {
+  const v = String(value).trim().replace(/\s+/g, ' ');
+  if (!v || v.length > 120) return;
+  const key = `${kind}:${v.toLowerCase()}`;
+  let e = evidence.get(key);
+  if (!e) { e = { kind, value: v, count: 0, sources: [], usage: new Set() }; evidence.set(key, e); }
+  e.count += 1;
+  if (e.sources.length < 20) e.sources.push(`${relative(root, file)}:${line}`);
+  e.usage.add(relative(root, file));
+}
+
+let scanned = 0;
+// docs 模式追加 Markdown 证据机（结构证据 + token 对），代码证据机同时保留
+const ENGINES = DOCS ? [...EVIDENCE, ...DOC_EVIDENCE] : EVIDENCE;
+for (const file of files) {
+  if (Date.now() - started > budgetMs) { skipped.push({ reason: 'budget-exceeded-during-scan' }); break; }
+  let content;
+  try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+  scanned += 1;
+  const lines = content.split('\n');
+  // 逐行扫（拿行号）
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const ev of ENGINES) {
+      ev.re.lastIndex = 0;
+      let m;
+      while ((m = ev.re.exec(line)) !== null) {
+        if (ev.tokenPair) {
+          // v0.55.0：Markdown 的 token 对（名=值），不做语义解释。
+          // **值形态过滤**：真实规范树的表格列序不固定（实测 3 种，含交错列），
+          // 与 token 名相邻的格未必是"值"——不过滤会把说明文字（"不变"/"悬停态"/"—"）
+          // 当成 token 值，实测制造 185 条噪音冲突。故只记"看起来是值"的形态，
+          // 其余存为位置证据（kind=doc-table-ctx，不参与冲突检测）。
+          const val = m[2].trim().replace(/[;；]\s*$/, '');
+          if (VALUE_LIKE_RE.test(val)) record(ev.kind, `${m[1]}=${val}`, file, i + 1);
+          else record('doc-table-ctx', `${m[1]}~${val}`, file, i + 1);
+        } else if (ev.captureValue) {
+          const raw = m[1] !== undefined ? m[1] : m[0];
+          // 多值拆分**仅适用于空格分隔的短值**（如 `padding: 8px 16px`）。
+          // v0.55.0 修正：含括号/逗号的值（`rgba(...)` / `calc(...)` / `color-mix(...)`）
+          // 是**单个值**，拆分会产生 `rgba(0` / `0.05)` 这类碎片——实测把
+          // `--color-bg-hover: rgba(0, 0, 0, 0.05)` 记成 3 个不同值，制造假冲突。
+          const parts = /[(),]/.test(raw) ? [raw] : raw.split(/[\s,]+/);
+          for (const part of parts) {
+            const t = part.trim();
+            if (!t || t === '0' || t === 'auto' || t === 'inherit' || t === 'initial') continue;
+            if (ev.kind === 'custom-prop') {
+              const nameM = line.match(ev.nameCapture);
+              record(ev.kind, `${nameM ? nameM[1] : '--?'}=${t}`, file, i + 1);
+            } else {
+              record(ev.kind, t, file, i + 1);
+            }
+          }
+        } else {
+          record(ev.kind, m[0], file, i + 1);
+        }
+        if (m.index === ev.re.lastIndex) ev.re.lastIndex += 1;   // 防零宽死循环
+      }
+    }
+  }
+}
+
+// ── 值归一化 + 相似聚类（确定性）──
+
+function normalizeHex(v) {
+  const m = v.match(/^#([0-9a-fA-F]{3})$/);
+  if (m) return '#' + m[1].split('').map(c => c + c).join('').toLowerCase();
+  const m6 = v.match(/^#([0-9a-fA-F]{6})$/);
+  if (m6) return '#' + m6[1].toLowerCase();
+  return v.toLowerCase();
+}
+
+function hexToRgb(hex) {
+  const h = normalizeHex(hex).replace('#', '');
+  if (h.length !== 6) return null;
+  return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+
+// 距离近似（RGB 欧氏；ΔE≈2 量级约为 RGB 距离 ~12）
+function rgbDistance(a, b) {
+  return Math.sqrt((a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2);
+}
+
+function cluster(list, isSimilar) {
+  const sorted = [...list].sort((x, y) => y.count - x.count);
+  const clusters = [];
+  for (const item of sorted) {
+    const target = clusters.find(c => isSimilar(c.representative, item));
+    if (target) {
+      target.members.push(item);
+      target.count += item.count;
+      for (const s of item.sources) if (target.sources.length < 20) target.sources.push(s);
+      for (const u of item.usage) target.usage.add(u);
+    } else {
+      clusters.push({ representative: item, members: [item], count: item.count, sources: [...item.sources], usage: new Set(item.usage) });
+    }
+  }
+  return clusters;
+}
+
+const allTokens = [...evidence.values()];
+
+// 颜色：hex 归并（ΔE<2 ≈ RGB 距离 <12）
+const colorTokens = allTokens.filter(t => t.kind === 'color' && hexToRgb(t.value));
+const nonHexColors = allTokens.filter(t => t.kind === 'color' && !hexToRgb(t.value));
+const colorClusters = cluster(colorTokens, (a, b) => {
+  const ra = hexToRgb(a.value), rb = hexToRgb(b.value);
+  return ra && rb && rgbDistance(ra, rb) < 12;
+});
+
+// 尺寸类：±1px 归并
+const sizeKinds = ['spacing', 'radius'];
+const sizeClusters = {};
+for (const kind of sizeKinds) {
+  const items = allTokens.filter(t => t.kind === kind);
+  sizeClusters[kind] = cluster(items, (a, b) => {
+    const na = parseFloat(a.value), nb = parseFloat(b.value);
+    if (!Number.isFinite(na) || !Number.isFinite(nb)) return a.value === b.value;
+    const ua = a.value.replace(/[\d.\s-]/g, ''), ub = b.value.replace(/[\d.\s-]/g, '');
+    return ua === ub && Math.abs(na - nb) <= 1;
+  });
+}
+
+const passthrough = ['font', 'shadow', 'custom-prop', 'tailwind'];
+const passthroughTokens = {};
+for (const kind of passthrough) {
+  passthroughTokens[kind] = allTokens.filter(t => t.kind === kind).sort((a, b) => b.count - a.count);
+}
+
+// ── 输出 ──
+
+const sourceTokens = {
+  scan: { root, filesDiscovered: files.length, filesScanned: scanned, generatedAt: new Date().toISOString(), budgetMs },
+  tokens: {
+    color: colorClusters.map(c => ({
+      value: c.representative.value,
+      count: c.count,
+      mergedFrom: c.members.length > 1 ? c.members.map(m => m.value) : undefined,
+      sources: c.sources,
+      usage: [...c.usage].slice(0, 20),
+    })),
+    colorRaw: nonHexColors.sort((a, b) => b.count - a.count).map(t => ({ value: t.value, count: t.count, sources: t.sources })),
+    spacing: sizeClusters.spacing.map(c => ({ value: c.representative.value, count: c.count, sources: c.sources })),
+    radius: sizeClusters.radius.map(c => ({ value: c.representative.value, count: c.count, sources: c.sources })),
+    ...Object.fromEntries(passthrough.map(k => [k, passthroughTokens[k].map(t => ({ name: t.value, count: t.count, sources: t.sources.slice(0, 5) }))])),
+  },
+  skipped,
+};
+
+const colorCount = sourceTokens.tokens.color.length;
+const spacingCount = sourceTokens.tokens.spacing.length;
+const radiusCount = sourceTokens.tokens.radius.length;
+const fontCount = sourceTokens.tokens.font.length;
+
+// ── 冲突呈现（v0.55.0，docs 模式）──
+// 同一 token 名出现多个不同值 → 显式并列。这不是"工具推断哪个对"，而是把**跨期/跨源矛盾**
+// 摊开给人工裁决（现场实测：`primary` 同时有 `#3A94DD` ×62 与 `#1890ff` ×155 两套，
+// 两期各自自洽、互未发现）。
+const conflicts = [];
+if (DOCS) {
+  const byName = new Map();
+  for (const e of evidence.values()) {
+    const idx = e.value.indexOf('=');
+    if (idx <= 0) continue;
+    const name = e.value.slice(0, idx);
+    const val = e.value.slice(idx + 1);
+    if (!byName.has(name)) byName.set(name, new Map());
+    const vm = byName.get(name);
+    vm.set(val, (vm.get(val) || 0) + e.count);
+  }
+  for (const [name, vm] of byName) {
+    if (vm.size > 1) {
+      conflicts.push({
+        token: name,
+        values: [...vm.entries()].sort((a, b) => b[1] - a[1]).map(([value, count]) => ({ value, count })),
+      });
+    }
+  }
+  conflicts.sort((a, b) => b.values[0].count - a.values[0].count);
+}
+
+// 统计报告（stdout）
+const report = [];
+report.push(`=== Token 提取报告（确定性，零 LLM${DOCS ? ' · Markdown 规范树模式' : ''}）===`);
+report.push(`根目录：${root}`);
+report.push(`发现文件：${files.length} | 已扫描：${scanned}${skipped.length ? ` | 跳过：${skipped.length}` : ''}`);
+report.push('');
+report.push(`颜色：${colorCount} 个聚类（归并 ${colorTokens.length - colorCount} 个近似值）`);
+for (const c of sourceTokens.tokens.color.slice(0, 8)) {
+  report.push(`  ${c.value.padEnd(10)} ×${String(c.count).padStart(4)}${c.mergedFrom ? `  (含 ${c.mergedFrom.length - 1} 个近似写法)` : ''}`);
+}
+report.push('');
+report.push(`间距：${spacingCount} 个聚类 | 圆角：${radiusCount} 个 | 字体栈：${fontCount} 个`);
+for (const c of sourceTokens.tokens.spacing.slice(0, 5)) report.push(`  spacing ${c.value} ×${c.count}`);
+for (const c of sourceTokens.tokens.radius.slice(0, 4)) report.push(`  radius  ${c.value} ×${c.count}`);
+report.push('');
+if (DOCS) {
+  report.push('');
+  report.push(`⚠️ 冲突呈现：${conflicts.length} 个 token 名存在多值（**跨期/跨源矛盾，需人工裁决**）`);
+  for (const c of conflicts.slice(0, 6)) {
+    report.push(`  ${c.token}: ${c.values.map(v => `${v.value} ×${v.count}`).join('  |  ')}`);
+  }
+  if (conflicts.length === 0) report.push('  （无冲突）');
+}
+report.push('');
+report.push('⚠️ 以上仅为「频次 + 位置」证据——语义角色（哪个是 primary / border / font-display）**需要人工策展指定**，');
+report.push('   本工具不做自动推断（设计 §4.1.6：避免"垃圾设计系统 + 满分审计"）。');
+report.push('');
+report.push('下一步：将本报告与 source-tokens.json 呈交用户，由用户指定主色/中性色/语义色/字体后，');
+report.push('   由 design-system skill 的 create-from-code 流程补齐 A1/A2/B-slot 并落盘。');
+
+console.log(report.join('\n'));
+
+if (!REPORT_ONLY) {
+  // v0.55.0：docs 模式默认落**调用方工作目录**（workspace 根）。若沿用 `join(root, …)`，
+  // 而 root 恰是被扫描的规范树 → 产物落进被扫描树内部 → 二次运行自吞（实测 ×1 → ×3）。
+  // 同时 `.team-flow` 已加入 SKIP_DIRS 兜底。
+  const outPath = outArg
+    ? resolve(outArg)
+    : DOCS
+      ? join(process.cwd(), '.team-flow', 'token-extract', 'source-docs.json')
+      : join(root, '.team-flow', 'token-extract', 'source-tokens.json');
+  mkdirSync(dirname(outPath), { recursive: true });
+  const payload = { ...sourceTokens, mode: DOCS ? 'docs' : 'code' };
+  if (DOCS) payload.conflicts = conflicts;
+  writeFileSync(outPath, JSON.stringify(payload, null, 2), 'utf-8');
+  console.log(`\n${DOCS ? 'source-docs.json' : 'source-tokens.json'} 已写入：${outPath}`);
+}

package/skills/design-system/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: design-system
 description: >-
-  设计系统独立创建与维护 skill。通过用户主导的交互流程（LLM 推荐+用户确认）创建
-  项目级 design-system（base 品牌共享层 + B端/C端变体），产出确定性 token 体系 +
-  预览画廊。支持独立调用或 prototype skill 内部编排调用。当用户需要创建设计系统、
-  迭代设计系统、或原型流程发现设计系统缺失时使用。
+  设计系统独立创建与维护 skill，产出落 .team-flow/design-system/（base 品牌共享层 +
+  B端/C端变体 + primer + 预览画廊）。六条创建入口：从已有项目移植（clone）、
+  从内置模板库导入、通用起点（--profile antd）、从既有规范文档导入（create-from-docs）、
+  从既有代码逆向建库（create-from-code）、交互式从零创建；已有设计系统走 iterate。
+  支持独立调用或 prototype skill 内部编排调用。当用户需要创建设计系统、迭代设计系统、
+  刷新 primer 组件白名单、或原型流程发现设计系统缺失时使用。
   不适用于：原型绘制（用 prototype）、纯架构设计（用 architecture-design）。
 ---
 
@@ -23,6 +25,34 @@ Do NOT invoke for:
 
 ## 交互创建流程（6 步）
 
+### Step 0: 起点选择（v0.55.0：7 条，全部展示）
+
+若 `.team-flow/design-system/` 不存在（无设计系统），先询问起点。
+**每条都要展示，并带"适用场景"一句话**——能力存在但用户不知道 = 能力不存在；
+按**资产就绪度降序**排列（从最厚的已有资产到最薄的空白起点）：
+
+| # | 选项 | 适用场景（对用户的一句话） | 动作 |
+|---|------|---------------------------|------|
+| 1 | **移植已有设计系统** | "你们公司**另一个后台项目**已经建过设计系统 → 直接复制过来改" | `clone --from <源路径> --to <目标路径>`（**两参数均必填**，流程见 `references/creation-modes.md` §1） |
+| 2 | **从模板库选择** | "想参考某个成熟产品（Linear / Stripe / Vercel…）的视觉风格" | 展示 `${CLAUDE_PLUGIN_ROOT}/templates/design-systems/registry.json`（8 个参考）→ `node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-import.mjs <reference.md> --out .team-flow/design-system/base.md` → **续跑 Step 5 评审 → Step 6 落盘** |
+| 3 | **通用起点（Ant Design 规格）** | "全新项目、**没有任何规范**，先要一套像 Ant Design 的合规底座" | `node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-import.mjs --profile antd --out .team-flow/design-system/base.md` → 续跑 Step 5 → Step 6 |
+| 4 | **从文档规范导入** | "手里有**一套写好的 UI 规范**（Markdown / 规范树）" | `create-from-docs`（流程见 `references/creation-modes.md` §4） |
+| 5 | **从代码逆向建库** | "项目里**已有符合规范的原型代码**" | `create-from-code`（见下方「逆向建库模式」） |
+| 6 | **从零交互创建** | "什么都没有，边聊边定" | 直接进 Step 1（交互式 6 步） |
+| 7 | 已有设计系统 → **iterate** | （非新建） | 见下方「迭代模式」 |
+
+> **入口同步（两处声明 + 一处事实传达，v0.55.0 校正）**：
+> ① 本文件 Step 0 —— **无条件展示全部 7 条**（这是模式可达性的**唯一保证**）；
+> ② `workflow-bootstrap` B4.6 —— 六项 + 跳过，逐行带适用场景与委托参数；
+> ③ prototype 内部编排（`orchestration-flow.md` §①b）—— 只传达 scout 简报中的**资产事实**（如"已有符合规范的原型代码"），**不预选起点**。
+>
+> ③ 不做 mode 预选是**有意设计**：prototype 无从判断用户资产状况，预选会让其余 6 条不可见。
+> 故**新模式可达性由 ① 的无条件展示保证，不依赖各入口的正确预选**——任何入口下用户都能看到全 7 条。
+
+> B 类参考（如 linear-app）转换为**自动提取配色**，须提示用户人工核对（转换器会输出该警告）。
+
+> **风格种子（styles.json）**：`${CLAUDE_PLUGIN_ROOT}/templates/design-systems/styles.json` 提供 57 个风格型设计系统的配色/字体元数据（如"想要 X 风格"）——Step 1 需求收集时可作为 mood/品牌主色的参考依据，用户选定后以 `brand_color` 传入（不扩充 5 维封闭词汇，保持核心交互稳定）。
+
 ### Step 1: 需求收集（≤5 个预填推荐问题）
 用 AskUserQuestion 收集 5 个维度（预填 LLM 推荐值，用户原样确认或调整）：
 1. 品牌调性（封闭词汇：professional_minimal / warm_approachable / technical_dense / editorial / brutalist）
@@ -42,29 +72,63 @@ Do NOT invoke for:
 ### Step 4: 预览生成
 生成 `preview.html`（自包含 HTML 画廊：色板+排版+间距+组件+明暗切换）。用 `references/preview-template.html` 模板填充 token 值。
 
+### Step 4.5: Design Showcase（可选，v0.54.0）
+询问用户是否产出**基准原型**（判断设计系统实际效果）：派 `prototype-builder`（`mode: showcase`）用内置车企 brief（`references/showcase-board-{b,c}-end.md`，按 target）产出 1-3 页 Board 到 scratch。产出前明示预估耗时；可跳过。详见 `references/creation-flow.md` Step 4.5。
+
 ### Step 5: 用户评审 + 确认
-呈现：token 摘要表 + 预览路径 + 默认值透明报告。AskUserQuestion：确认 / 调整 / 重新来。
+呈现：token 摘要表 + 预览路径 + **showcase 路径（如产出）** + 默认值透明报告。AskUserQuestion：确认 / 调整 / 重新来。
 
 ### Step 6: 落盘 + guard 校验
-写入 `.team-flow/design-system/`，运行 `scripts/guard/design-token-guard.mjs` 校验。
+写入 `.team-flow/design-system/`（base + 变体 + **primer**（`${CLAUDE_PLUGIN_ROOT}/scripts/gen-primer.mjs`）+ preview + **showcase 从 scratch 复制**），运行 `node ${CLAUDE_PLUGIN_ROOT}/scripts/guard/design-token-guard.mjs <设计系统目录>`（v0.54.0：硬校验 + 六层审计；传目录会自动合并 base + 端变体再断言 9 段——base 品牌层本身不含 typography/spacing/layout/motion）。**target=both 时按端各跑一次**（`--variant b-end` / `--variant c-end`）——合并断言掩盖单端残缺。
 
 ## 存储位置
 ```
 .team-flow/design-system/
-├── base.md          # 品牌共享层
-├── b-end.md         # B 端变体（可选）
+├── base.md          # 品牌共享层（含组件契约表/principles/governance）
+├── b-end.md         # B 端变体（可选，components 段只写端特有差异）
 ├── c-end.md         # C 端变体（可选）
-└── preview.html     # token 预览画廊
+├── primer.md        # AI 约束入口（scripts/gen-primer.mjs 生成，含 digest）
+├── preview.html     # token 预览画廊
+├── showcase/        # 展示板（v0.54.0，可选：b-end.html / c-end-*.html）
+├── variants/        # 主题变体（如 dark.md）
+└── pending.md       # 增量待办（v0.54.0，单写者 = 本 skill）
 ```
 
+## pending.md（设计系统待办，v0.54.0）
+
+原型阶段用户"暂不处理"的增量暂存（`ds_increment` 的落点）。
+- **单写者 = design-system skill**——本 skill 的 iterate 流程负责增删；主代理与 release-archivist **只读**
+- 条目格式：`{描述} | 来源: <change-id 或 s2-prototype> | 时间: <ISO>`
+- **清理规则**：用户确认 → iterate 落盘时移除该条；用户拒绝 → 直接删除（重复发现就重复问）；用户自行解决 → 下次 iterate 按同义条目清理
+- iterate 时检查 pending.md：有待办则提示用户"是否一并处理"
+
 ## 迭代模式（iterate）
 已有 design-system → 读取 → 合并增量 → 变更履历 → 预览 → 确认 → 写入。
+增量来源：① 原型阶段确认的 `ds_increment`（⑥ 路由）② **pending.md 累积待办** ③ change closing 二级确认项 ④ **页面规范增量**（v0.55.0：用户提供项目页面规范，或更新既有 `页面范式来源` 声明与页面类型表；用户不提供时**默认补写** `页面范式来源：引用内置`）。
+落盘后重新生成 primer（`${CLAUDE_PLUGIN_ROOT}/scripts/gen-primer.mjs`）+ 跑 guard；涉及 token/契约变更时**可选**重新生成 showcase（用户可跳过）。
+
+## 逆向建库模式（create-from-code）
+
+**场景**：企业已有符合规范的原型代码 → 基于它建立设计系统。**确定性提取 + 人工策展**（不做自动语义推断——避免"垃圾设计系统 + 满分审计"）。入口（**单目录**）与完整 5 步流程见 `references/creation-modes.md` §6。
+
+> **三种新模式（v0.55.0）**——移植（clone）/ 文档导入（create-from-docs）/ 通用起点（`--profile antd`）的完整命令与流程，同样见 `references/creation-modes.md`。Step 0 表格已列出全部 7 条起点及各自适用场景。
 
 ## 迁移兼容
 检测旧 `prototype/design-system.md` → 提示迁移到 `.team-flow/design-system/base.md`（一次性）。
+迁移属**导入类创建** → 须补 `来源与裁决记录` 段、`contract` 默认 `legacy`。
+
+## 异常处理（v0.55.0）
+
+- **源系统不可读 / `base.md` 缺失**（clone）：脚本 exit 1，提示 `--from` 的两种语义（项目根自动定位 `.team-flow/design-system`，或直接给设计系统目录）
+- **目标已有设计系统**（clone）：exit 1 并引导走 **iterate**（MERGE 不 OVERWRITE）——不覆盖
+- **primer 缺失或过期**：`gen-primer --check` **exit 2** → prototype Step 0 对 `contract: v1` 系统 **blocked**、对 `legacy` 系统 WARN 放行 → 提示用户重跑生成或 iterate
+- **guard 硬校验失败**：exit 1 阻断落盘 → 按输出逐项修复（9 段 / palette / A1 / A2 公式 / B-slot）
+- **用户中途放弃**：草案阶段产物在 scratch（`/tmp/ds-draft-<slug>/`），放弃确认时**整体丢弃**，不写任何正式路径（两阶段落盘 `confirmed:false → confirmed:true` 保证）
+- **配置漂移**：`check-project-config.mjs` 输出 ⚠️ 但 **exit 0**（提示不阻断）
 
 ## 执行引擎
 内部子代理 `references/agents/design-system-architect.md`（唯一写者，两阶段落盘：confirmed:false 草案 → 人工确认 → confirmed:true 写入）。
+**写者范围（v0.55.0）**：含 `base.md` 与**端变体的 `layout` 段**（页面范式声明 + 容器骨架块）。
 
 ## 配置
 ```json
@@ -73,3 +137,8 @@ Do NOT invoke for:
   "prototype.designSystemBase": ".team-flow/design-system/base.md"
 }
 ```
+
+> **配置漂移检查（v0.55.0）**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/check-project-config.mjs [项目根]` ——
+> 检查配置指向的路径是否存在、`version` 是否与插件一致。现场实测三类漂移（version 落后 /
+> 指向不存在的文件 / 零消费者键）**全部静默**，只会在用到时失效。检查面按"实际被消费"分级，
+> 零消费者键只提示不报错。