@xulthekl/team-flow 0.54.0 → 0.56.0

package/scripts/lib/solutions-promote.mjs

@@ -22,6 +22,11 @@ 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';
+import { slugify } from './slug.mjs';
+
+/** 文件名 slug 截断长度（与 solutions-capture 一致） */
+const SLUG_MAX_LENGTH = 40;
 
 /**
  * 剥离 YAML 行尾注释（空格 + `#` 起始）——v0.23 §91 硬化：
@@ -39,9 +44,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 +108,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');
 }
@@ -181,7 +192,7 @@ export function run(args = {}) {
       mkdirSync(phaseDir, { recursive: true });
     }
 
-    const slug = learning.title.toLowerCase().replace(/[^a-z0-9一-鿿]+/g, '-').slice(0, 40);
+    const slug = slugify(learning.title, { maxLength: SLUG_MAX_LENGTH });
     const fileName = `${date}-${slug}.md`;
     const filePath = join(phaseDir, fileName);
 

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/lib/test-merge.mjs

@@ -27,6 +27,7 @@
 import { readFileSync, writeFileSync, existsSync, cpSync, mkdirSync, readdirSync } from 'node:fs';
 import { join, basename, relative, resolve } from 'node:path';
 import { execSync } from 'node:child_process';
+import { slugify } from './slug.mjs';
 
 /**
  * 解析 CLI 参数数组为结构化对象
@@ -197,7 +198,9 @@ export function mergeBaselines(ledgerDir, changeName, moduleSections, candidateL
   const today = new Date().toISOString().slice(0, 10);
 
   for (const [moduleName, sectionContent] of Object.entries(moduleSections)) {
-    const safeName = moduleName.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    // 统一走 slug.mjs（保留 CJK）——原 `[^a-z0-9-]` 逐字符替换会把中文标题退化成纯短横线，
+    // 实证 emp-auth `baselines/--------------------.md`（2026-09-12）
+    const safeName = slugify(moduleName);
     const baselinePath = join(baselinesDir, `${safeName}.md`);
     const moduleCandidates = candidateLedger.filter(c =>
       c.candidate.toLowerCase().includes(moduleName.toLowerCase())

package/scripts/token-extract.mjs

@@ -32,10 +32,31 @@ const EVIDENCE = [
   { 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');
@@ -44,7 +65,14 @@ const positional = argv.filter((a, i) => !a.startsWith('--') && !(outIdx !== -1
 const rootArg = positional[0];
 
 if (!rootArg) {
-  console.error('Usage: node scripts/token-extract.mjs <代码目录> [--out <json 路径>] [--budget-ms 60000] [--report]');
+  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);
@@ -53,6 +81,10 @@ if (!existsSync(root) || !statSync(root).isDirectory()) {
   process.exit(1);
 }
 
+// docs 模式：纳入 .md；并把 .team-flow 加入跳过（否则产物落进被扫描树内部 → 二次运行自吞）
+if (DOCS) SCAN_EXTS.add('.md');
+SKIP_DIRS.add('.team-flow');
+
 // ── 走树（迭代式，预算控制）──
 
 const started = Date.now();
@@ -99,6 +131,8 @@ function record(kind, value, file, line) {
 }
 
 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;
@@ -108,14 +142,27 @@ for (const file of files) {
   // 逐行扫（拿行号）
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    for (const ev of EVIDENCE) {
+    for (const ev of ENGINES) {
       ev.re.lastIndex = 0;
       let m;
       while ((m = ev.re.exec(line)) !== null) {
-        if (ev.captureValue) {
+        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）拆开逐项
-          for (const part of raw.split(/[\s,]+/)) {
+          // 多值拆分**仅适用于空格分隔的短值**（如 `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') {
@@ -226,9 +273,36 @@ 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）===');
+report.push(`=== Token 提取报告（确定性，零 LLM${DOCS ? ' · Markdown 规范树模式' : ''}）===`);
 report.push(`根目录：${root}`);
 report.push(`发现文件：${files.length} | 已扫描：${scanned}${skipped.length ? ` | 跳过：${skipped.length}` : ''}`);
 report.push('');
@@ -241,6 +315,15 @@ report.push(`间距：${spacingCount} 个聚类 | 圆角：${radiusCount} 个 |
 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('');
@@ -250,8 +333,17 @@ report.push('   由 design-system skill 的 create-from-code 流程补齐 A1/A2/
 console.log(report.join('\n'));
 
 if (!REPORT_ONLY) {
-  const outPath = outArg ? resolve(outArg) : join(root, '.team-flow', 'token-extract', 'source-tokens.json');
+  // 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 });
-  writeFileSync(outPath, JSON.stringify(sourceTokens, null, 2), 'utf-8');
-  console.log(`\nsource-tokens.json 已写入：${outPath}`);
+  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/ce-compound/references/three-tier-index.md

@@ -5,8 +5,9 @@
 ```
 docs/solutions/
 ├── INDEX.md                  # L1：轻量索引（≤150行，每条一行摘要+标签）
-├── requirement/              # 按阶段分目录
+├── prd/                      # 按阶段分目录（枚举权威：scripts/lib/solutions-phases.mjs）
 ├── plan/
+├── architecture/
 ├── prototype/
 ├── spec/
 ├── build/
@@ -14,6 +15,9 @@ docs/solutions/
 └── cross-phase/              # 跨阶段通用经验
 ```
 
+> 注意：目录树中**只有上述 phase 目录**由 `tf solutions` CLI 通道维护；`workflow-issues/`、
+> `build-errors/` 等 category 目录由 `/ce-compound` 通道写入，两套词表互不兼容。
+
 ## INDEX.md 格式
 
 ```markdown
@@ -29,7 +33,7 @@ docs/solutions/
 
 ```yaml
 ---
-phase: prd          # 阶段标签：prd | plan | prototype | spec | build | review | cross-phase
+phase: prd          # 阶段标签：prd | plan | architecture | prototype | spec | build | review | cross-phase
 domain: auth        # 领域标签（与 PRD/change 的领域对应）
 type: pitfall       # pitfall | pattern | decision | insight
 severity: high      # critical | high | medium | low（序定义于 scripts/lib/severity.mjs）

package/skills/design-system/SKILL.md

@@ -2,8 +2,9 @@
 name: design-system
 description: >-
   设计系统独立创建与维护 skill，产出落 .team-flow/design-system/（base 品牌共享层 +
-  B端/C端变体 + primer + 预览画廊）。三条创建入口：交互式（LLM 推荐+用户确认）、
-  从内置模板库导入（registry.json 8 个参考）、从既有代码逆向建库（create-from-code）。
+  B端/C端变体 + primer + 预览画廊）。六条创建入口：从已有项目移植（clone）、
+  从内置模板库导入、通用起点（--profile antd）、从既有规范文档导入（create-from-docs）、
+  从既有代码逆向建库（create-from-code）、交互式从零创建；已有设计系统走 iterate。
   支持独立调用或 prototype skill 内部编排调用。当用户需要创建设计系统、迭代设计系统、
   刷新 primer 组件白名单、或原型流程发现设计系统缺失时使用。
   不适用于：原型绘制（用 prototype）、纯架构设计（用 architecture-design）。
@@ -24,14 +25,29 @@ Do NOT invoke for:
 
 ## 交互创建流程（6 步）
 
-### Step 0: 起点选择（v0.54.0）
-
-若 `.team-flow/design-system/` 不存在（无设计系统），先询问起点：
-
-- **从模板库选择**：展示 `${CLAUDE_PLUGIN_ROOT}/templates/design-systems/registry.json`（8 个参考：linear-app / stripe / vercel / supabase / sentry / posthog / notion / claude）→ 用户选定后运行 `node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-import.mjs <reference.md> --out .team-flow/design-system/base.md` 转换 → **续跑 Step 5 评审 → Step 6 落盘**（落盘动作含 primer 生成 + guard 校验；primer 缺失会让 prototype Step 0 对 `contract: v1` 系统 blocked）
-- **逆向建库**：走 **create-from-code** 模式（见下方「逆向建库模式」）——从既有代码提取
-- **从零创建**：直接进 Step 1（交互式 6 步）
-- **已有设计系统** → 走 iterate 模式
+### 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）转换为**自动提取配色**，须提示用户人工核对（转换器会输出该警告）。
 
@@ -88,29 +104,31 @@ Do NOT invoke for:
 
 ## 迭代模式（iterate）
 已有 design-system → 读取 → 合并增量 → 变更履历 → 预览 → 确认 → 写入。
-增量来源：① 原型阶段确认的 `ds_increment`（⑥ 路由）② **pending.md 累积待办** ③ change closing 二级确认项。
+增量来源：① 原型阶段确认的 `ds_increment`（⑥ 路由）② **pending.md 累积待办** ③ change closing 二级确认项 ④ **页面规范增量**（v0.55.0：用户提供项目页面规范，或更新既有 `页面范式来源` 声明与页面类型表；用户不提供时**默认补写** `页面范式来源：引用内置`）。
 落盘后重新生成 primer（`${CLAUDE_PLUGIN_ROOT}/scripts/gen-primer.mjs`）+ 跑 guard；涉及 token/契约变更时**可选**重新生成 showcase（用户可跳过）。
 
-## 逆向建库模式（create-from-code，v0.54.0）
-
-**场景**：企业已有符合规范的原型代码 → 基于它建立设计系统。**确定性提取 + 人工策展**（不做自动语义推断——避免"垃圾设计系统 + 满分审计"）。
-
-**入口**：`/team-flow:design-system create-from-code --source <代码目录>`（多仓库可传多值或指向 repo_layout 清单）
+## 逆向建库模式（create-from-code）
 
-**流程（5 步）**：
-1. **提取**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/token-extract.mjs <目录>` → `.team-flow/token-extract/source-tokens.json` + 统计报告（频次 + 位置证据，零 LLM）
-2. **呈现报告**：向用户展示提取统计（"47 个文件、23 个颜色、8 个间距值，高频 Top10 …"）
-3. **候选稿**：从高频值生成候选 token 表（标注"候选"）
-4. **人工策展**（多轮 AskUserQuestion）：用户指定 primary / 中性色 / 语义色 / 字体栈（每项有频次+位置证据可参考）→ skill 按确定性规则补齐 A1/A2/B-slot + palette 阶梯
-5. **落盘**：base.md + 变体 + primer + preview（+ 可选 showcase）→ guard 六层审计
+**场景**：企业已有符合规范的原型代码 → 基于它建立设计系统。**确定性提取 + 人工策展**（不做自动语义推断——避免"垃圾设计系统 + 满分审计"）。入口（**单目录**）与完整 5 步流程见 `references/creation-modes.md` §6。
 
-**关键约束**：绝不静默发明（候选值标注 `sources[]` 证据）；**语义角色由人定，不由 LLM 定**；目标已有 base.md 时走 iterate 合并（需用户确认）。
+> **三种新模式（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
@@ -119,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 落后 /
+> 指向不存在的文件 / 零消费者键）**全部静默**，只会在用到时失效。检查面按"实际被消费"分级，
+> 零消费者键只提示不报错。

package/skills/design-system/references/agents/design-system-architect.md

@@ -1,11 +1,11 @@
-You are a Design System Architect. You are dispatched by the `design-system` skill to **create or iterate** the project-level `.team-flow/design-system/base.md` — the single source of truth for design tokens, components, and anti-patterns (compounded back via prototype-sync). The orchestrating design-system skill **never writes `base.md` itself — you are the sole writer**. You run in two phases: first produce a **draft** (`confirmed: false`) for orchestrator review + human confirmation; then, re-dispatched with `confirmed: true`, **you yourself write the official path**. The orchestrator only reviews, confirms, and re-dispatches — it does not Write/Edit `base.md`.
+You are a Design System Architect. You are dispatched by the `design-system` skill to **create or iterate** the project-level `.team-flow/design-system/base.md` — the single source of truth for design tokens, components, and anti-patterns (compounded back via prototype-sync). The orchestrating design-system skill **never writes `base.md` itself — you are the sole writer**（v0.55.0 起写者范围另含**端变体的 `layout` 段**）。 You run in two phases: first produce a **draft** (`confirmed: false`) for orchestrator review + human confirmation; then, re-dispatched with `confirmed: true`, **you yourself write the official path**. The orchestrator only reviews, confirms, and re-dispatches — it does not Write/Edit `base.md`.
 
 ### 文件结构：base + variant
 
 architect 写入的文件采用 **base + variant** 结构：
 - **`.team-flow/design-system/base.md`**：基础设计系统（全量 token + 组件规范 + anti-patterns），是所有 variant 的公共底座。
 - **`.team-flow/design-system/variants/<name>.md`**（可选）：品牌/主题变体文件，只覆写差异 token（如暗色主题、子品牌色板），继承 base 未覆写部分。
-- architect 在 `confirmed: true` 阶段写入 base.md；如需 variant，同时写入对应 variant 文件。
+- architect 在 `confirmed: true` 阶段写入 base.md；如需 variant，同时写入对应 variant 文件。**v0.55.0 起另含端变体（`b-end.md` / `c-end.md`）的 `layout` 段**（页面范式声明 + 容器骨架块，见下方「端变体 `layout` 段写者」）。
 
 The plugin stays **generic**: do NOT hardcode any specific company/product brand. Derive tokens deterministically from the project's stated tone/brand input; when none is given, fall back to a neutral default and record the assumption.
 
@@ -15,7 +15,7 @@ The dispatch prompt provides:
 - `mode: create | iterate`.
 - `confirmed: false | true`（v0.15.0 两阶段落盘）：
   - `false`（默认，草案阶段）：只产草案（写 scratch 草稿路径或返回 response），**不写正式 `.team-flow/design-system/base.md`**。
-  - `true`（人工已确认）：把已确认的草案**写入正式 `.team-flow/design-system/base.md`**（你是唯一写者）。
+  - `true`（人工已确认）：把已确认的草案**写入正式 `.team-flow/design-system/base.md`**（你是唯一写者）；若本次产出 / 更新端变体的 `layout` 段（页面范式声明 + 容器骨架块），同批写入。
 - `design_system_path`: 正式目标路径（`confirmed: true` 时写入此处，默认 `.team-flow/design-system/base.md`）。
 - `draft`（`confirmed: true` 时传入）：上一阶段已确认的草案内容/路径。
 - `create` inputs (as available): project tone/brand hints, PRD path (to read product domain & voice), existing scaffold `.team-flow/design-system/base.md`.
@@ -37,7 +37,8 @@ Every `.team-flow/design-system/base.md` follows this schema (9 sections + a 5-d
 | `brand` | logo / 品牌主色 |
 | `anti-patterns` | 禁止内联样式漂移 / 禁止非 token 颜色 |
 | `principles`（v0.54.0） | **设计原则 ≥3 条**（随 mood 预填，用户可调整） |
-| `governance`（v0.54.0） | `contract: v1`（新建固定 v1；存量升级时由 iterate 置 v1）+ version + 负责人 + 弃用策略 + changelog |
+| `governance`（v0.54.0） | `contract: v1`（**新建默认 v1；来源 ∈ {`create-from-docs` / `create-from-code` / 转换器产物 / 旧文件迁移} 时写 `legacy`**，v0.55.0 设计 §8.2.1 D-18；存量升级时由 iterate 置 v1）+ version + 负责人 + 弃用策略 + changelog |
+| `来源与裁决记录`（v0.55.0） | **导入类创建条件必填**（同上四类来源）：原始来源 / 导入方式 / 「为什么不是直接采纳」/ 主色裁决 / 待清理项——审计层 advisory，不进 `REQUIRED_SECTIONS` |
 | `palette`（5 方向确定性调色板） | neutral / primary / success / warning / danger，各含 50–900 阶梯 |
 | `aliases`（B-slot 别名层，v0.18.0） | `--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`——组件引用 B-slot 永远可解析 |
 | `extensions`（C-extension 待提升清单，v0.18.0） | 品牌专有 token 名单制；提升路径：C→B（≥2 品牌需要）→A2（有全局默认值） |
@@ -99,12 +100,13 @@ When the project has no `.team-flow/design-system/base.md`:
    - **C-extension 清单**（v0.18.0）：如有品牌专有 token，列入 `extensions` 段（名单制），标注提升路径。
    - **组件契约表（v0.54.0）**：按上方 20 类基线产出**至少 10 类**（`| 组件 | 类型 | variants | sizes | states | 用途 | 禁止 |`），全部 token-bound；类型列必须填写（交互/轻量/豁免）。
    - **principles 段（v0.54.0）**：≥3 条，随 mood 预填（如 professional_minimal → "一致性优先于局部创意 / 清晰优于装饰 / 可访问性默认开启"）。
-   - **governance 段（v0.54.0）**：`contract: v1`（新建固定 v1）+ version + 负责人 + 弃用策略 + changelog。
+   - **governance 段（v0.54.0；v0.55.0 改）**：`contract: v1`（**新建默认 v1**；**来源 ∈ {`create-from-docs`, `create-from-code`, 转换器产物, 旧文件迁移}（导入类）时写 `legacy`**——导入的既有资产未经校准，恒打 `v1` 会一落盘即 blocked）+ version + 负责人 + 弃用策略 + changelog。
+   - **`来源与裁决记录` 段（v0.55.0）**：来源属上列导入类时**条件必填**（原始来源 / 导入方式 / 「为什么不是直接采纳」/ 主色裁决 / 待清理项）；绿地创建可选，**不进 `REQUIRED_SECTIONS`**。
    - **a11y 声明行（v0.54.0）**：文档头部 `> a11y: WCAG 2.2 AA（对比度 4.5:1 / 大字 3:1 / 焦点可见 / 键盘可达）`。
    - Fill color / typography / spacing / layout / motion / voice / brand / anti-patterns consistently with the palette.
    - `anti-patterns` MUST include "禁止内联样式漂移" and "禁止非 token 颜色".
 3. **`confirmed: false`**：Deliver the draft（写 scratch 草稿路径或返回 response），**不写正式路径**。Orchestrator 评审 + 人工确认后，**带 `confirmed: true` 重新派发你**，由你写入正式 `.team-flow/design-system/base.md`（主代理不写）。
-4. **`confirmed: true`**：把传入的已确认草案 `Write` 到正式 `.team-flow/design-system/base.md`，然后执行 **预览生成步骤**，返回 `status: done` + deliverable = 正式路径。
+4. **`confirmed: true`**：把传入的已确认草案 `Write` 到正式 `.team-flow/design-system/base.md`；若本次产出端变体（`b-end.md` / `c-end.md`），同批写入其 **`layout` 段**（页面范式声明 + 容器骨架块，见下方「端变体 `layout` 段写者」），然后执行 **预览生成步骤**，返回 `status: done` + deliverable = 正式路径。
 
 #### 预览生成步骤（confirmed: true 后自动执行）
 
@@ -116,16 +118,27 @@ When the project has no `.team-flow/design-system/base.md`:
 
 ### Mode: iterate（增量更新）
 
-When prototype-sync (or a change) introduces new components / tokens / anti-patterns:
+When prototype-sync (or a change) introduces new components / tokens / anti-patterns / **page-pattern specs（页面规范增量，v0.55.0）**:
 
 1. Read the existing `.team-flow/design-system/base.md`.
 2. **Merge** (not overwrite) the incoming increments: new components into the `components` 契约表（必须指定类型列）, new tokens into the relevant section + palette, new anti-patterns into `anti-patterns`.
    - **contract 升级（v0.54.0）**：若原系统为 `legacy`/无标记，且本次补全了契约表（≥10 类）→ 将 `contract` 置为 `v1`（并记 changelog：来源"本 change 增量回流"）。
    - 变体文件的 components 段只写**端特有差异**并引用契约表（不重复定义组件清单）。
-3. Keep token consistency — a new component must reference existing tokens; if it needs a new token, add the token to the palette/section too (no orphan tokens).
-4. Append a **变更履历** entry: 时间 / 变更内容 / 来源 change-id.
-5. **`confirmed: false`**：Deliver the merged draft（草稿路径或 response）for orchestrator review + human confirmation，**不写正式路径**。
-6. **`confirmed: true`**：把已确认的合并草案 `Write` 到正式 `.team-flow/design-system/base.md`（你是唯一写者），然后执行**预览生成步骤**（同上）。
+3. **页面规范增量（v0.55.0 第四类增量）**：用户提供项目页面规范，或要更新既有 `页面范式来源` 声明 / 页面类型表时 → 写对应端变体的 `layout` 段（`### 容器骨架` 块 + `### 页面范式` 子块）。**用户不提供规范时默认补写 `页面范式来源：引用内置` 一行**，使 guard L3 的 ⚠️ 收敛为 ✅（绿地默认；已知属导入类棕地时改按 `项目自有` + 容器骨架块写——见 `variant-schema.md` 三态语义）。
+4. Keep token consistency — a new component must reference existing tokens; if it needs a new token, add the token to the palette/section too (no orphan tokens).
+5. Append a **变更履历** entry: 时间 / 变更内容 / 来源 change-id.
+6. **`confirmed: false`**：Deliver the merged draft（草稿路径或 response）for orchestrator review + human confirmation，**不写正式路径**。
+7. **`confirmed: true`**：把已确认的合并草案 `Write` 到正式 `.team-flow/design-system/base.md`（你是唯一写者）；若本次含页面规范增量，同批 `Write`/`Edit` 对应端变体的 `layout` 段，然后执行**预览生成步骤**（同上）。
+
+#### 端变体 `layout` 段写者（v0.55.0 扩面，设计 §8.2.2）
+
+**写者范围由「只写 `base.md`」扩为「`base.md` + 端变体的 `layout` 段」**——页面范式属端变体，而 architect 此前只写 base，导致该声明**无写者**、guard 的 ⚠️ 无从收敛。
+
+- **可写**：端变体（`b-end.md` / `c-end.md`）的 `layout` 段：
+  - `### 容器骨架` 块——表格 `| 容器 | 类名 | 关键 CSS 声明 |`（builder 的物料来源）
+  - `### 页面范式` 子块——`**页面范式来源**：…` 声明 + 页面类型表
+- **边界**：本次扩面**只涉及 `layout` 段**，其余段落维持既有分工，不借机扩张写面；`variants/<name>.md`（暗色等主题变体）不属本扩面。
+- **取值**（三态语义见 `variant-schema.md`）：`项目自有`（棕地导入，须附容器骨架块 + 页面类型表 ≥3 行）/ `同 <端>`（指向另一端）/ `引用内置`（绿地默认，只写声明）。
 
 ## Output Format
 
@@ -150,7 +163,7 @@ When prototype-sync (or a change) introduces new components / tokens / anti-patt
 ## Tool Guidance
 
 - Use `Read` for the existing base.md / PRD / scaffold; `Glob` to scan existing `components/` and `variants/`.
-- **`Write` 权限按 `confirmed` 阶段使用**：`confirmed: false` → 只写 scratch 草稿路径（或仅返回 response），**绝不写正式 `.team-flow/design-system/base.md`**；`confirmed: true` → 写正式路径 + 生成 preview.html（你是唯一写者，主代理不写）。
+- **`Write` 权限按 `confirmed` 阶段使用**：`confirmed: false` → 只写 scratch 草稿路径（或仅返回 response），**绝不写正式 `.team-flow/design-system/base.md`**；`confirmed: true` → 写正式路径（含端变体 `layout` 段）+ 生成 preview.html（你是唯一写者，主代理不写）。
 - Keep everything token-based and offline-friendly (产物必须零外部依赖).
 
 ## Red Lines