@xulthekl/team-flow 0.54.0 → 0.55.0

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

@@ -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/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

package/skills/design-system/references/creation-flow.md

@@ -108,12 +108,29 @@
   - `components` 组件契约表（≥10 类起步，含类型列）
   - `principles`（≥3 条）+ `governance`（`contract: v1`）
   - 头部 a11y 声明行（WCAG 2.2 AA）
+- **端变体 `layout` 段默认写 `页面范式来源：引用内置`（v0.55.0，设计 §8.2.2）**——生成端变体（`b-end.md` / `c-end.md`）时就要写，**不写则从零创建的产物两端一出生就落 ⚠️**（guard L3 声明层缺失，只能等 iterate 补）。绿地默认只写这一行；容器骨架块**可省**——内置 `template.html` 的类全是通用/营销向（`hero` / `topnav` / `pagefoot`），**C 端够用**；但 **target 为 B 端（`b_end` / `both`）时建议一并给**（内置骨架**无** `app-header` / `app-sider` / `app-main` 这类容器类，不给则 builder 每页手写整套后台骨架 CSS，单次派发无法复现）。取值三态见 `variant-schema.md`，缘由详见 `creation-modes.md` §5。
 - 用 `preview-template.html` 填 token 值 → 自包含 `preview.html`（色板/排版/间距/组件/明暗切换）。
 
 ## Step 4.5: Design Showcase 草案（v0.54.0 新增，设计 §4.1.7）
 
 > **可选环节**：Step 5 呈现前询问用户是否需要（**产出前明示预估耗时**，S5 实测校准后回填）；不需要则跳过。
 
+**0) 询问前先做原型探测（v0.55.0，设计 §8.2.3 / FB-2a）**：
+
+- **探测面**：`prototype/` ∨ config `prototype.entry` 所在目录 ∨ `prototype.versionWorktree`（worktree 内原型）∨ repo_layout 各仓的 `prototype/`——**须覆盖 worktree 与多仓**，否则探测不到 → 提示不出现 → 用户被引导重画已有原型（正是本节要修的形态）。
+- **判据**：探测到 **≥1 个 HTML 页面文件**即提示（**不设行数阈值**——机制不替用户判断"够不够成熟"，由用户在知情下决定）。
+- **呈现**（`AskUserQuestion`）：
+
+  > 「检测到项目已有原型产物（`prototype/`：N 个页面 / M 行）。showcase 的目的是在设计系统落盘前预览效果，已有真实原型时可能重复。」
+
+  | 选项 | 后续动作 |
+  |------|---------|
+  | **跳过 showcase**（推荐） | Step 5 呈现时**改引用真实原型路径**（不产 showcase 草案） |
+  | 仍然产出 | 走下方原流程（brief 场景可调） |
+  | 调整场景 | 用户给出场景描述后产出 |
+
+  > **为什么**：showcase 的定位是"设计系统落盘**前**预览效果"；已有真实原型时它是**重复劳动**——不提示就是让用户白画一遍。
+
 1. architect 产出 **primer 草案**（scratch 路径 `/tmp/ds-draft-<slug>/primer-draft.md`，digest 记录**草案 base** 的哈希）
 2. 主代理派 `prototype-builder`（`mode: showcase`，单次派发）：
    - 输入：showcase-board brief（按 target：`b_end` → b-end brief；`c_end` → c-end brief；`both` → 两个）+ 设计系统草案 + primer 草案

package/skills/design-system/references/creation-modes.md

@@ -0,0 +1,171 @@
+# 创建模式详解（v0.55.0）
+
+> 本文是 `SKILL.md` Step 0 的**展开说明**。Step 0 按「资产就绪度降序」列出 7 条起点，
+> 其中 6 条的完整流程在此（**iterate** 见 `creation-flow.md`；**从零创建**即 Step 1 起的交互 6 步）：
+> §1 移植 clone · §2 模板库 · §3 通用起点 `--profile antd` · §4 文档导入 create-from-docs ·
+> §5 B 端容器骨架为何必须给（贯穿 §1/§3） · §6 代码逆向 create-from-code。
+
+---
+
+## 1. 移植模式（clone）
+
+**场景**：**同类后台项目之间复用设计系统**——"以后其他项目是相同的后台"。
+
+**入口**：`/team-flow:design-system clone --from <源项目路径 | 源设计系统目录> --to <目标设计系统目录>`
+
+设计系统就是 `.team-flow/design-system/` 下的 markdown，技术上 `cp -r` 即可——但**直接复制会留 4 个坑**，
+`clone` 把它们自动化：
+
+| # | 坑 | 处置 |
+|---|-----|------|
+| 1 | **`来源与裁决记录` 失真**（复制后仍写着原项目的导入记录，而目标并未导入过） | **追加**移植记录，**保留**原裁决历史——其裁决依据对理解本系统取值仍有参考价值 |
+| 2 | **`primer.md` digest 失效**（锚定源 base 内容；改一字即 STALE，而 prototype Step 0 对 `contract: v1` 系统 **blocked**） | 强制重生成 + `--check` 校验 |
+| 3 | **业务专属组件残留**（如"协议富文本编辑器 / 内容预览画布"） | 输出契约表全量清单 → **逐条问询** |
+| 4 | **授权边界**（源 `references/` 下可能是企业内部资产） | 提示（不自动判定） |
+
+**脚本自动完成（确定性）**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-clone.mjs --from <源> --to <目标>`
+1. 校验源系统（跑 guard；不合规**只警告不阻断**——源可能是 legacy）
+2. 复制（**排除** `primer.md` / `pending.md` / `showcase/`）
+3. 追加移植记录
+4. 输出契约表清单（供第 5 步问询）
+5. 重生成 primer + `--check`
+6. 对结果跑 guard 并输出六层审计
+
+**需 LLM 承接（脚本不做的交互部分）**：
+- **业务组件逐条问询**：读第 4 步清单 → `AskUserQuestion` 逐条确认 → 删除不再需要的
+  → **提示用户**：组件数跌破档位会改变 L2 标签（<10 FAIL / 10-14 WARN / ≥15 PASS）
+- **品牌适配**：主色/字体不同 → 改 `base.md` 的 `color` 段 → **必须重跑 `gen-primer`**
+- **`contract` 取值**：移植产物继承源系统；若源为 `v1` 而目标尚未达标，可考虑降为 `legacy`
+- **页面范式来源复核（v0.55.0）**：`### 页面范式` 是**原样带过来**的，但目标项目的页面现实可能不同——
+  **判据 = 目标项目是否已有成文的页面规范或既有原型页面类型**：
+  源 `引用内置` 而目标是**棕地** → **改为 `项目自有`** + 补容器骨架块 + 页面类型表（否则目标既有的
+  页面规范进不了 builder，本次移植等于只搬了一半）；源 `项目自有` 而目标是**绿地**（无既有页面规范）
+  → 可改 `引用内置`（否则 builder 会按源项目的页面类型硬套，与目标实际页面不符）。改后**必须重跑 `gen-primer`**。
+
+**与 iterate 的分界**：clone 是**新建**（目标无设计系统）；目标**已有**设计系统 → 走 iterate（MERGE 不 OVERWRITE）。
+
+---
+
+## 2. 模板库导入
+
+**场景**：想参考某个成熟产品的视觉风格（Linear / Stripe / Vercel / Supabase / Sentry / PostHog / Notion / Claude）。
+
+**流程**：展示 `${CLAUDE_PLUGIN_ROOT}/templates/design-systems/registry.json` → 用户选定 →
+`node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-import.mjs <reference.md> --out .team-flow/design-system/base.md`
+→ **续跑 Step 5 评审 → Step 6 落盘**（落盘含 primer 生成 + guard 校验）。
+
+> **B 类参考**（如 linear-app）为**自动提取配色**，转换器会输出警告 → **须提示用户人工核对**。
+>
+> **风格种子**（`styles.json`，57 个）：Step 1 需求收集时作为 mood / 品牌主色的参考依据。
+
+---
+
+## 3. 通用起点（`--profile antd`）
+
+**场景**：全新项目、**没有任何规范**，先要一套合规的 token 底座。
+
+**入口**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/design-system-import.mjs --profile antd --out .team-flow/design-system/base.md`
+→ 续跑 Step 5 → Step 6。
+
+**产出规格**（全部来自 Ant Design v5 seed token（MIT）或 team-flow 自有规范）：
+
+| 规格 | 值 |
+|------|-----|
+| 控件高 | 32px（`controlHeight`） |
+| 圆角阶梯 | 2 / 4 / 6 / 8（`borderRadius`，v5 默认 6） |
+| 字号阶梯 | 12 / 14 / 16 / 20 / 24（`fontSize`） |
+| 间距 | 8 档 4→48px（**team-flow 自定**，参考 AntD size 阶梯） |
+| 组件契约表 | 20 类通用基线（team-flow 自有） |
+
+**零 LLM、零外部资产、零授权链风险**。
+
+> **定位**：它是**薄起点**——不含**业务**组件（20 类为通用基线，不针对任何业务）、
+> 不含**项目自有**页面范式（`### 页面范式` 声明 `引用内置`，页面类型表只是内置节奏的示意）。
+>
+> **但它含一份通用 B 端容器骨架块**（`app-header` / `app-sider` / `app-main`）。这不是矛盾：
+> 内置 `template.html` 的 15 个类全是**营销向**的（`hero` / `topnav` / `pagefoot` / `cta`），
+> **没有任何 B 端容器类**——不给物料，builder 就得每页手写整套后台骨架 CSS，
+> 单次派发无法复现（详见 §5「B 端容器骨架为何必须给」）。
+>
+> 要复用**厚资产**（如某项目已建好的 30+ 类契约 + 页面规范）请用**移植模式**。
+
+---
+
+## 4. 文档导入模式（create-from-docs）
+
+**场景**：手里有**既有的 Markdown 规范树**（非代码、非模板库形态）——如企业的三层规范
+（基础元素层 / 页面模板层 / 模式规范层）。
+
+**流程（5 步）**：
+
+1. **提取**：`node ${CLAUDE_PLUGIN_ROOT}/scripts/token-extract.mjs <规范树目录> --docs`
+   → `.team-flow/token-extract/source-docs.json` + 报告（**零 LLM**）
+2. **呈现报告（含冲突项）**：报告器只呈现**证据与冲突**，**不做取值裁决**——
+   同一 token 名多值时显式并列（如 `--color-primary`：`#1890ff`×20 / `#3A94DD`×3），
+   标注"跨期/跨源矛盾，需人工裁决"
+3. **人工裁决**（多轮 `AskUserQuestion`）：**语义角色由人定，不由 LLM 定**
+4. **落盘**：base + 变体（含 `layout` 段的「容器骨架」块 + `页面范式来源：项目自有`）
+   + **`来源与裁决记录` 段（强制）**
+5. guard 校验
+
+**为什么报告器不做裁决**：真实规范树的 token 主形态是 **Markdown 表格行**，且列序不固定
+（实测 3 种，含交错列）；按频次排序会选出**错的主色**（现场实测：错值 `#1890ff` ×157
+vs 正确值 `#3A94DD` ×62——两期各自自洽、互未发现）。工具的职责是**把矛盾摊开**，不是选一个。
+
+**授权约束**：导入的既有资产**只留在项目内**，**不打包**进插件分发包。
+
+---
+
+## 5. B 端容器骨架为何必须给（v0.55.0）
+
+**事实**：内置 `template.html` 的全部 15 个类是
+`brand / btn / btn-primary / btn-secondary / container / eyebrow / hero / hero-center /
+hero-cta / lead / meta / pagefoot / row-between / section / topnav`——
+**清一色营销向**，没有 `app-header` / `app-sider` / `app-main` 这类后台容器类。
+
+**后果（不写骨架块时）**：builder 每页都要**从零手写**整套后台骨架 CSS（顶栏 sticky + 侧栏固定宽 +
+主区弹性），而它是**单次派发**的子代理——没有跨页记忆、无法从既有页面"抄"，同一项目不同页面
+会漂移出不同的骨架实现。
+
+**所以**：`--profile antd`（通用起点）与导入类模式**都附一份骨架块**（类名 + 关键 CSS 声明）。
+这不是"厚资产"，是**最小可复现物料**——与"薄起点"定位不冲突。
+
+**契约不变**：骨架类**不在** `layouts.md` 的类清单表内，按该表**同一条硬规则**处理——
+**先在页面 `<style>` 里定义，再使用**；绝不允许凭空发明没有 CSS 支撑的全局类。
+物料来源是 primer 的「容器骨架」块（`gen-primer` 逐端摘录原文）。
+
+> **三态下的骨架块**（与 `variant-schema.md` 的 `layout` 段三态表一致）：
+> `引用内置` → **可省**（C 端/营销页内置骨架够用），但 **B 端建议给**；
+> `项目自有` → **必须给**（这是棕地项目页面规范能进 builder 的唯一通道）；
+> `同 <端>` → 由被指向端保证，本端免写。
+
+---
+
+## 6. 逆向建库模式（create-from-code）
+
+**场景**：企业已有**符合规范的原型代码** → 基于它建立设计系统。
+
+**定位**：**确定性提取 + 人工策展**。不做自动语义推断——那会产出"垃圾设计系统 + 满分审计"
+（guard 只校验**结构**合规，不校验**语义**正确）。
+
+**入口**：`/team-flow:design-system create-from-code <代码目录>`
+
+> ⚠️ **单目录**：`token-extract.mjs` 的位置参数只接受一个源路径，传多个会**显式报错 exit 1**
+> （v0.55.0 修正：原实现静默丢弃其余路径，多仓场景下用户以为处理了全部）。
+> 多仓请**分批调用**，或先合并到一个目录。
+
+**流程（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 六层审计
+
+**关键约束**：绝不静默发明（候选值标注 `sources[]` 证据）；**语义角色由人定，不由 LLM 定**；
+目标已有 base.md 时走 iterate 合并（需用户确认）。
+
+> **空目录边界（§4 文档导入同此）**：0 个可扫描文件时脚本只输出"发现文件：0"——
+> 须**提示用户核对目录**，不要拿空报告进第 3 步（会把"没扫到"误当成"候选为空"继续策展）。