@xulthekl/team-flow 0.54.0 → 0.55.0

package/scripts/design-system-clone.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// design-system-clone.mjs — 设计系统移植（v0.55.0，设计 §8.2.4 形态 B / D-22）
+//
+// ── 为什么需要 ───────────────────────────────────────────────────────────────
+// 设计系统就是 `.team-flow/design-system/` 下的 markdown，技术上 `cp -r` 即可。
+// 但直接复制会留 4 个坑，本脚本把它们自动化：
+//   ① **来源与裁决记录失真**——复制后仍写着原项目的导入记录（如"从 page-gen 导入于 X"），
+//      而目标项目并未导入过 → **追加**移植条目（**保留**原裁决历史：其裁决依据仍有参考价值）
+//   ② **primer.md 的 digest 失效**——它锚定源 base.md 内容；改一个字即 STALE，
+//      而 prototype Step 0 对 `contract: v1` 系统会 **blocked** → **强制重生成 + 校验**
+//   ③ **业务专属组件残留**（如"协议富文本编辑器/内容预览画布"）→ 输出契约表清单供调用方
+//      （design-system skill）**逐条问询**
+//   ④ **授权边界**——源系统 `references/` 下可能是企业内部资产 → 输出提示（不自动判定）
+//
+// 交互部分（业务组件"要不要保留"）**不在本脚本**：脚本只做确定性动作 + 输出问询素材。
+//
+// Usage: node scripts/design-system-clone.mjs --from <源项目路径 | 源设计系统目录> --to <目标设计系统目录>
+
+import { readFileSync, writeFileSync, existsSync, statSync, cpSync, mkdirSync } from 'node:fs';
+import { resolve, dirname, join, basename } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseComponentsTable } from './lib/ds-parse.mjs';
+
+const argv = process.argv.slice(2);
+const fromIdx = argv.indexOf('--from');
+const toIdx = argv.indexOf('--to');
+const fromArg = fromIdx !== -1 ? argv[fromIdx + 1] : null;
+const toArg = toIdx !== -1 ? argv[toIdx + 1] : null;
+
+if (!fromArg || !toArg) {
+  console.error('Usage: node scripts/design-system-clone.mjs --from <源项目路径 | 源设计系统目录> --to <目标设计系统目录>');
+  process.exit(1);
+}
+
+const PLUGIN_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+const GUARD = join(PLUGIN_DIR, 'scripts', 'guard', 'design-token-guard.mjs');
+const GEN_PRIMER = join(PLUGIN_DIR, 'scripts', 'gen-primer.mjs');
+
+// ── 源定位：既接受项目根，也接受设计系统目录本身 ──
+
+const fromAbs = resolve(fromArg);
+if (!existsSync(fromAbs) || !statSync(fromAbs).isDirectory()) {
+  console.error(`源路径不存在或不是目录：${fromAbs}`);
+  process.exit(1);
+}
+const nested = join(fromAbs, '.team-flow', 'design-system');
+const srcDir = existsSync(nested) ? nested : fromAbs;
+if (!existsSync(join(srcDir, 'base.md'))) {
+  console.error(`源目录内未找到 base.md：${srcDir}`);
+  console.error('（--from 可指向项目根，或直接指向 .team-flow/design-system）');
+  process.exit(1);
+}
+
+// ── 目标：必须不存在或为空（移植是**新建**；已有设计系统请走 iterate 的 MERGE 语义）──
+
+const dstDir = resolve(toArg);
+if (existsSync(dstDir) && existsSync(join(dstDir, 'base.md'))) {
+  console.error(`目标目录已存在 base.md：${dstDir}`);
+  console.error('目标已有设计系统 → 请走 design-system 的 **iterate** 模式（MERGE 不 OVERWRITE），不要 clone。');
+  process.exit(1);
+}
+
+// ── ① 校验源系统（警告不阻断：源可能是 legacy 系统）──
+
+console.log('① 校验源系统…');
+const srcGuard = spawnSync('node', [GUARD, srcDir], { encoding: 'utf-8' });
+const srcOk = srcGuard.status === 0;
+console.log(srcOk
+  ? '   源系统硬校验通过'
+  : `   ⚠️  源系统硬校验未通过（exit ${srcGuard.status}）——移植后需一并修复`);
+if (!srcOk && srcGuard.stdout) {
+  const failed = srcGuard.stdout.split('\n').filter(l => l.trim().startsWith('❌'));
+  failed.slice(0, 5).forEach(l => console.log(`     ${l.trim()}`));
+}
+
+// ── ② 复制（排除 primer.md / pending.md / showcase/）──
+
+const EXCLUDE = new Set(['primer.md', 'pending.md', 'showcase']);
+mkdirSync(dstDir, { recursive: true });
+cpSync(srcDir, dstDir, {
+  recursive: true,
+  filter: (src) => !EXCLUDE.has(basename(src)),
+});
+console.log(`② 已复制到 ${dstDir}（排除：primer.md / pending.md / showcase/）`);
+
+// ── ③ 追加移植记录（保留原裁决历史）──
+
+const basePath = join(dstDir, 'base.md');
+let base = readFileSync(basePath, 'utf-8');
+const stamp = new Date().toISOString().slice(0, 10);
+const entry = `> **移植记录**：${stamp} 由 \`design-system-clone\` 从 \`${srcDir}\` 移植。`
+  + '原「来源与裁决记录」**保留**——其裁决依据对理解本系统的取值仍有参考价值。';
+
+if (/^##\s+来源与裁决记录\s*$/m.test(base)) {
+  base = base.replace(/^(##\s+来源与裁决记录\s*)$/m, `$1\n\n${entry}`);
+} else {
+  // 无该段 → 在文档头部（首个 ## 段之前）创建
+  const firstSection = base.search(/^##\s+/m);
+  const insertAt = firstSection === -1 ? base.length : firstSection;
+  base = `${base.slice(0, insertAt)}## 来源与裁决记录\n\n${entry}\n\n${base.slice(insertAt)}`;
+}
+writeFileSync(basePath, base, 'utf-8');
+console.log('③ 已追加移植记录（原来源与裁决记录保留）');
+
+// ── ④ 输出业务组件清单（供调用方逐条问询）──
+
+const table = parseComponentsTable(base);
+const rows = table ? table.rows : [];
+console.log(`④ 契约表共 ${rows.length} 类组件 —— **请逐条确认目标项目是否需要**（不需要的删除后重跑 guard；`);
+console.log('   注意组件数跌破档位会改变 L2 标签：<10 FAIL / 10-14 WARN / ≥15 PASS）：');
+for (const r of rows) console.log(`     - ${r.name}（${r.type}）`);
+
+// ── ⑤ 重生成 primer + 校验（digest 锚定的是新路径下的 base 内容）──
+
+console.log('⑤ 重生成 primer…');
+const gen = spawnSync('node', [GEN_PRIMER, basePath], { encoding: 'utf-8' });
+if (gen.status !== 0) {
+  console.error(`   ❌ primer 生成失败：${(gen.stderr || gen.stdout || '').trim()}`);
+  process.exit(1);
+}
+const check = spawnSync('node', [GEN_PRIMER, basePath, '--check'], { encoding: 'utf-8' });
+// v0.55.0 §8.2.4 修订：`--check` 紧跟在"刚重生成"之后运行，两者不一致 = 生成器自相矛盾
+// （而非用户输入问题）——属于内部一致性错误，**必须参与退出码**，否则脚本报成功而产物对
+// `contract: v1` 系统实为 blocked（prototype Step 0 会拒绝），问题被推迟到使用现场才暴露。
+if (check.status !== 0) {
+  console.error(`   ❌ primer 自检失败（exit ${check.status}）：刚生成的 primer 与其输入不一致。`);
+  console.error((check.stderr || check.stdout || '').trim());
+  console.error('   这是生成器缺陷（非用户输入问题），请上报；移植产物暂不可用。');
+  process.exit(1);
+}
+console.log('   primer --check：OK（digest 一致）');
+
+// ── ⑥ 跑 guard 并输出结论 ──
+
+console.log('⑥ 对移植结果跑 guard…');
+const dstGuard = spawnSync('node', [GUARD, dstDir], { encoding: 'utf-8' });
+if (dstGuard.stdout) {
+  const lines = dstGuard.stdout.split('\n');
+  const auditStart = lines.findIndex(l => l.startsWith('## 六层审计报告'));
+  if (auditStart !== -1) lines.slice(auditStart).forEach(l => console.log(`   ${l}`));
+}
+
+console.log('');
+console.log('移植完成。**仍需人工处理的事项**：');
+console.log('  a) 业务组件裁剪（见 ④ 的清单）—— 删除后重跑 guard');
+console.log('  b) 品牌适配：若目标项目主色/字体不同 → 改 base.md 的 color 段 → **重跑 gen-primer**（digest 会变）');
+console.log('  c) 授权：源系统 references/ 下若含企业内部资产，跨企业边界复用时须自行确认授权');
+console.log('  d) `contract`：移植产物继承源系统的取值；若源为 v1 而目标尚未达标，可考虑降为 legacy');
+process.exit(dstGuard.status === 0 ? 0 : 1);

package/scripts/design-system-import.mjs

@@ -1,37 +1,87 @@
 #!/usr/bin/env node
-// design-system-import.mjs — open-design DESIGN.md → team-flow base.md 转换器（v0.54.0，设计 §4.5.2）
+// design-system-import.mjs — open-design DESIGN.md / 内置 profile → team-flow base.md 转换器（v0.55.0，设计 §4.5.2 / §8.2.4）
 //
 // 解析 open-design 九节 DESIGN.md，映射到 team-flow 的 9 段 schema（A1/A2/B-slot + 组件契约表 + principles/governance）。
-// 关键约束：**A 类转换后必须补齐完整度**（palette 阶梯 / A2 派生公式 / B-slot 别名 / 组件契约表基线）——
-//           open-design 原文没有这些，转换器按 team-flow 规则生成。
+// 关键约束：**转换后必须补齐完整度**（palette 阶梯 / A2 派生公式 / B-slot 别名 / 组件契约表基线）——
+//           来源原文没有这些，转换器按 team-flow 规则生成。
 //
-// Usage: node scripts/design-system-import.mjs <DESIGN.md 路径> [--out <base.md 路径>] [--id <标识>]
+// v0.55.0 变更（设计 §8.2.4 / D-18）：
+//   - 新增 `--profile antd`：无外部源的**确定性 B 端起点**（Ant Design v5 seed token，MIT）。
+//     与 reference 导入走同一条生成路径（合成源文本 → 复用解析）。**零 LLM、零外部资产**。
+//   - 产物 `contract` 由 `v1` 改 **`legacy`**：导入的既有资产天然未经校准，按 v1 最严档判会一落盘
+//     即 blocked（死循环）。用户裁决达标后经 iterate 升 v1。
+//   - `layout` 段增「容器骨架」块与「页面范式」声明：内置 `template.html` 的骨架是营销向的
+//     `hero/cta/log`，**缺 B 端容器类** → 不给物料则 builder 每页要手写整套骨架 CSS。
+//   - 新增 `来源与裁决记录` 段（导入类条件必填，审计层 advisory，不进硬校验）。
+//
+// Usage:
+//   node scripts/design-system-import.mjs <DESIGN.md 路径> [--out <base.md 路径>] [--id <标识>]
+//   node scripts/design-system-import.mjs --profile antd [--out <base.md 路径>]
 // 输出后建议运行：node scripts/guard/design-token-guard.mjs <base.md>
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { resolve, dirname, basename, join } from 'node:path';
+import { resolve, dirname, basename, extname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+// ── 内置 profile（v0.55.0，设计 §8.2.4 形态 A）──
+//
+// "全新项目且无任何规范"时的确定性起点。规格全部来自 **Ant Design v5 seed token**（MIT）
+// 或 team-flow 自有规范——**不含任何项目补录值**（原方案的模板内容表多数条目实为某项目的
+// 补录而非通用惯例，P1.5 反方逐条实查 page-gen 全树后推翻，见设计 §8.2.4"为何取消"）。
+//
+// 实现方式：合成一份 open-design 形态的源文本，复用下方的既有解析路径（零新增解析逻辑）。
+const SYNTHETIC_SOURCES = {
+  antd: `# B-end Admin (Ant Design v5 basis)
+
+> Category: Enterprise Admin
+> 通用 B 端后台基线——规格取自 Ant Design v5 seed token（MIT）与 team-flow 自有规范，不含项目专属值。
+
+**Primary:** \`#1677FF\`
+**Surface:** \`#FFFFFF\`
+**Text:** \`#000000E0\`
+**Secondary:** \`#8C8C8C\`
+**Families:** primary=-apple-system, Segoe UI, system-ui; display=-apple-system, Segoe UI, system-ui; mono=ui-monospace
+**Scale:** 12/14/16/20/24
+**Spacing scale:** 4/8/12/16/24/32/40/48
+`,
+};
+
 const argv = process.argv.slice(2);
 const outIdx = argv.indexOf('--out');
 const outArg = outIdx !== -1 ? argv[outIdx + 1] : null;
 const idIdx = argv.indexOf('--id');
 const idArg = idIdx !== -1 ? argv[idIdx + 1] : null;
-const positional = argv.filter((a, i) => !a.startsWith('--') && !(outIdx !== -1 && i === outIdx + 1) && !(idIdx !== -1 && i === idIdx + 1));
+const profileIdx = argv.indexOf('--profile');
+const profileArg = profileIdx !== -1 ? argv[profileIdx + 1] : null;
+const positional = argv.filter((a, i) =>
+  !a.startsWith('--') && !(outIdx !== -1 && i === outIdx + 1)
+  && !(idIdx !== -1 && i === idIdx + 1) && !(profileIdx !== -1 && i === profileIdx + 1));
 const srcPath = positional[0];
 
-if (!srcPath) {
+if (profileArg && !SYNTHETIC_SOURCES[profileArg]) {
+  console.error(`未知 profile：${profileArg}（可用：${Object.keys(SYNTHETIC_SOURCES).join(', ')}）`);
+  process.exit(1);
+}
+if (!profileArg && !srcPath) {
   console.error('Usage: node scripts/design-system-import.mjs <DESIGN.md 路径> [--out <base.md 路径>] [--id <标识>]');
+  console.error('       node scripts/design-system-import.mjs --profile antd [--out <base.md 路径>]');
   process.exit(1);
 }
-const srcAbs = resolve(srcPath);
-if (!existsSync(srcAbs)) {
+const srcAbs = srcPath ? resolve(srcPath) : null;
+if (srcAbs && !existsSync(srcAbs)) {
   console.error(`DESIGN.md not found: ${srcAbs}`);
   process.exit(1);
 }
 
-const src = readFileSync(srcAbs, 'utf-8');
-const id = idArg || basename(dirname(srcAbs));
+const src = profileArg ? SYNTHETIC_SOURCES[profileArg] : readFileSync(srcAbs, 'utf-8');
+// 标识：显式 --id > profile 名 > 文件名（非约定名 `DESIGN.md` 时）> 目录名（约定名的旧行为）。
+// v0.55.0：原实现恒取目录名——内置模板库（`templates/design-systems/references/linear-app.md`）
+// 会得到无意义的 `references`，写进「来源与裁决记录」段后无法辨认来源。
+const id = idArg || (profileArg
+  ? `profile-${profileArg}`
+  : basename(srcAbs).toLowerCase() === 'design.md'
+    ? basename(dirname(srcAbs))
+    : basename(srcAbs, extname(srcAbs)));
 
 // ── 解析 open-design 九节 ──
 
@@ -141,6 +191,15 @@ const base = `# ${title}
 > ${summary}
 > 来源归因：open-design（nexu-io）MIT License，"inspired by" 逆向工程描述，非官方资产。
 
+## 来源与裁决记录
+
+> **原始来源**：${profileArg ? `内置 profile \`${profileArg}\`（Ant Design v5 seed token，MIT）` : `open-design \`${id}\`（Category: ${category}）`}
+> **导入日期**：${new Date().toISOString().slice(0, 10)}
+> **导入方式**：转换器确定性生成（\`scripts/design-system-import.mjs\`）—— **未做语义裁决**
+> **为什么不是直接采纳**：① **结构**——来源是描述性散文，team-flow 需 9 段 schema；② **Token 形式**——需补 A2 派生公式与 B-slot 别名；③ **消费入口**——需生成 primer 供 builder 使用
+> **★ 主色裁决**：无（单一来源，取自 \`accent\`）${autoExtracted ? '\n> **⚠️ B 类自动提取**：原来源未以 A 类格式声明配色，\`accent\` 等值由正则自动提取——**须人工核对**' : ''}
+> **待清理项**：组件契约表为 20 类通用基线（与来源无关），须对照项目实际增删；本段为**审计层 advisory**，不参与 guard 硬校验
+
 ## color
 
 **A1-identity（8 必选）**
@@ -171,7 +230,33 @@ const base = `# ${title}
 
 ## layout
 
-- 栅格 12 列 / 断点 sm(640) md(1024) lg(1440) / 容器 max-width 1200px
+- 栅格 12 列 / 断点：sm 640 / md 1024 / lg 1440 / 容器 max-width 1200px
+
+### 容器骨架
+
+| 容器 | 类名 | 关键 CSS 声明 |
+|------|------|--------------|
+| 顶栏 | \`app-header\` | \`position: sticky; top: 0; height: 64px; z-index: 100\` |
+| 侧栏 | \`app-sider\` | \`width: 200px; flex: 0 0 200px; overflow-y: auto\` |
+| 主区 | \`app-main\` | \`flex: 1; min-width: 0; padding: 24px\` |
+
+> 上述类**不在**内置 \`template.html\` 中——按类清单契约在页面 \`<style>\` 内定义。
+> （v0.55.0 说明：内置骨架是营销向的 \`hero/cta/log\`，**缺 B 端容器类**，故这里必须给出物料。）
+
+### 页面范式
+
+**页面范式来源**：引用内置
+
+| 页面类型 | 骨架/容器组合 | 参考 |
+|---------|-------------|------|
+| 列表页 | app-header + app-sider + app-main > ds-table + stat | layouts.md 管理后台列表页 |
+| 表单页 | app-header + app-sider + app-main > field / input / textarea | layouts.md 表单页 |
+| 仪表盘 | app-header + app-sider + app-main > stat + grid-2-1 | layouts.md 仪表盘 |
+
+> 第二列的组合**全部取自** \`layouts.md\` 的类清单契约 + 上方容器骨架块（\`ds-table\` / \`stat\` /
+> \`field\` / \`input\` / \`textarea\` / \`grid-2-1\`）——不引入表外类名（v0.55.0 修正：原表用了
+> \`filterbar\` / \`table\` / \`form\` / \`grid\`，均不在类清单契约内，builder 照抄会得到无 CSS 支撑的类）。
+> 本表仅为**内置节奏的示意**；声明 \`引用内置\` 时 L4b 免检，实际节奏以内置 \`layouts.md\` 为准。
 
 ## components
 
@@ -209,7 +294,7 @@ ${CONTRACT_ROWS.join('\n')}
 
 ## governance
 
-- contract: v1
+- contract: legacy
 - version: 0.1.0
 - 负责人: {项目角色}
 - 弃用策略: 组件弃用需在 changelog 记录 + 保留 1 个迭代周期
@@ -227,9 +312,12 @@ mkdirSync(dirname(outPath), { recursive: true });
 writeFileSync(outPath, base, 'utf-8');
 
 console.log(`base.md 已生成：${outPath}`);
-console.log(`  来源：open-design ${id}（${category}）`);
+console.log(profileArg
+  ? `  来源：内置 profile ${profileArg}（Ant Design v5 seed token，MIT + team-flow 自有规范）`
+  : `  来源：open-design ${id}（${category}）`);
 console.log(`  accent=${primary} / surface=${surface} / text=${text}`);
 console.log(`  组件契约表：20 类基线（待审阅调整）`);
+console.log('  contract: legacy（导入类默认 —— 用户裁决达标后经 iterate 升 v1）');
 // 提示中的脚本路径用**本脚本所在插件目录**解析（绝对路径，可直接复制执行）——
 // 裸 `node scripts/...` 在插件零拷贝安装下不解析（v0.54.0 P4 根因）。
 const pluginDir = dirname(dirname(fileURLToPath(import.meta.url)));

package/scripts/gen-primer.mjs

@@ -1,29 +1,39 @@
 #!/usr/bin/env node
-// gen-primer.mjs — 从 base.md 确定性生成 primer.md（v0.54.0，设计 §4.1.2）
+// gen-primer.mjs — 从设计系统确定性生成 primer.md（v0.55.0，设计 §4.1.2 / §8.2.2）
 //
-// primer 是"AI 约束入口"：组件白名单 + token 速查 + 硬规则，供 prototype-builder 消费。
-// 确定性：除"生成时间"一行外，输出完全由 base.md 内容决定（纯字符串拼接，零 LLM）。
+// primer 是"AI 约束入口"：组件白名单 + token 速查 + 硬规则 + **页面范式**，供 prototype-builder 消费。
+// 确定性：除"生成时间"一行外，输出完全由设计系统内容决定（纯字符串拼接，零 LLM）。
+//
+// v0.55.0 两项修正（P1.5 实证）：
+//   ① **digest 覆盖 base + 参与合并的端变体**。原先只对 base.md 做 sha256 →
+//      变体变更不判 STALE → prototype Step 0 gate 放行 → **原型静默用旧页面范式**。
+//      无变体时 digest 与旧实现**逐字节一致**（`[base].join('\n') === base`），既有测试不受影响。
+//   ② **「页面范式」段从设计系统派生**，含各端的页面类型表与容器骨架块（builder 的物料来源）。
+//      原先是**硬编码**字符串（primer 里唯一不读 base.md 的段），项目既有页面规范无法进入流程。
 //
 // Usage:
 //   node scripts/gen-primer.mjs <base.md path> [--out <primer path>]
-//     生成 primer（默认写 base.md 同目录 primer.md）
+//     生成 primer（默认写 base.md 同目录 primer.md）；同目录端变体自动参与
 //   node scripts/gen-primer.mjs <base.md path> --check
-//     校验同目录 primer.md 的 digest 与 base.md 是否一致
+//     校验同目录 primer.md 的 digest 与"base + 变体"是否一致
 //     exit 0 = 一致；exit 2 = 过期或缺失（供 builder gate 判定）
 //
 // 配套测试："生成物 == 源表"（tests/lib/gen-primer.test.mjs）
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import {
   parseComponentsTable,
   parseContract,
   parseA1Tokens,
   parseAntiPatterns,
+  parsePageArchetype,
+  subsectionBodyRaw,
   COMPONENT_COUNT_PASS,
   COMPONENT_COUNT_WARN,
 } from './lib/ds-parse.mjs';
+import { resolveInputs, readFileOrNull } from './lib/ds-inputs.mjs';
 
 const argv = process.argv.slice(2);
 const CHECK = argv.includes('--check');
@@ -44,10 +54,19 @@ if (!existsSync(baseAbs)) {
 }
 
 const baseContent = readFileSync(baseAbs, 'utf-8');
-const digest = createHash('sha256').update(baseContent, 'utf-8').digest('hex');
+
+// ── 变体发现与 digest（v0.55.0）──
+// 复用 guard 的输入解析（下沉在 ds-inputs.mjs，避免 import 顶层副作用的 guard 脚本）。
+const inputs = resolveInputs(baseAbs, null);
+const variantFiles = inputs.files.filter(f => resolve(f) !== baseAbs);
+const variants = variantFiles.map(f => ({ file: f, name: basename(f).replace(/-end\.md$/i, ''), text: readFileOrNull(f) || '' }));
+
+// digest 源 = base + 全部参与合并的变体（无变体时逐字节等同旧实现）
+const digest = createHash('sha256').update([baseContent, ...variants.map(v => v.text)].join('\n'), 'utf-8').digest('hex');
 const digestShort = digest.slice(0, 16);
 const primerPath = outArg ? resolve(outArg) : join(dirname(baseAbs), 'primer.md');
 const DIGEST_RE = /sha256:([0-9a-f]{16,})/;
+const sourceLabel = ['base.md', ...variants.map(v => basename(v.file))].join(' + ');
 
 // ── --check 模式：校验 primer 新鲜度（builder gate 调用）──
 
@@ -63,7 +82,7 @@ if (CHECK) {
     process.exit(2);
   }
   if (m[1] !== digestShort && !digest.startsWith(m[1])) {
-    console.error(`STALE: primer.md 已过期（记录 ${m[1]}，当前 base.md ${digestShort}）——请运行 design-system iterate 重新生成`);
+    console.error(`STALE: primer.md 已过期（记录 ${m[1]}，当前 ${sourceLabel} ${digestShort}）——请运行 design-system iterate 重新生成`);
     process.exit(2);
   }
   console.log(`OK: primer.md digest 一致（${digestShort}）`);
@@ -92,10 +111,10 @@ const countLabel = count >= COMPONENT_COUNT_PASS
 
 // 白名单行：Name(variants · sizes)
 const whitelistLines = componentRows.map(r => {
-  const variants = r.hasVariants ? r.variants.replace(/\s*\/\s*/g, '|') : '—';
+  const variants_ = r.hasVariants ? r.variants.replace(/\s*\/\s*/g, '|') : '—';
   const sizes = r.sizes && r.sizes !== '—' ? r.sizes.replace(/\s*\/\s*/g, '|') : '—';
   const typeMark = r.type === '豁免' ? '（展示类）' : r.type === '轻量' ? '（轻量）' : '';
-  return `- ${r.name}${typeMark}: variants=${variants} · sizes=${sizes}`;
+  return `- ${r.name}${typeMark}: variants=${variants_} · sizes=${sizes}`;
 });
 
 // Token 速查行
@@ -113,10 +132,42 @@ const hardRules = [
   ...antiPatterns.map((p, i) => `${i + 3}. ${p}`),
 ];
 
+/**
+ * 「页面范式」段（v0.55.0：**忠实派生物**，不再是硬编码）。
+ *
+ * 逐端摘录 `layout` 段的 `### 页面范式` 与 `### 容器骨架` 子块原文——
+ * 前者给出"页面类型 → 骨架组合"的路由，后者给出**骨架的类名与关键 CSS**（builder 的物料来源：
+ * 内置 `template.html` 里没有 `header-bar`/`sidebar-container` 这类项目容器类）。
+ */
+function pageArchetypeSection() {
+  const scopes = variants.length ? variants : [{ file: baseAbs, name: null, text: baseContent }];
+  const blocks = [];
+  for (const s of scopes) {
+    const label = s.name ? `**${s.name}**` : null;
+    const arche = parsePageArchetype(s.text);
+    const archeSub = subsectionBodyRaw(s.text, 'layout', '页面范式');
+    const skelSub = subsectionBodyRaw(s.text, 'layout', '容器骨架');
+
+    if (!arche.declared) {
+      blocks.push(`${label ? `${label}：` : ''}未声明页面范式来源 —— 在 \`layout\` 段补 \`页面范式来源：引用内置\`（绿地）或 \`项目自有\`（棕地，需附页面类型表与容器骨架块）`);
+    } else if (/^引用内置$/.test(arche.source)) {
+      blocks.push(`${label ? `${label}：` : ''}引用内置 —— \`prototype/references/layouts.md\` 的${s.name ? ` ${s.name} ` : ''}节奏表`);
+    } else if (/^同/.test(arche.source)) {
+      blocks.push(`${label ? `${label}：` : ''}${arche.source}（完整性由被指向端保证）`);
+    } else {
+      blocks.push(`${label ? `${label}：` : ''}以下为设计系统的原文摘录，**以此为准**（内置 layouts.md 仅作回退默认）\n\n${(archeSub || '').trim()}`);
+    }
+    if (skelSub) {
+      blocks.push(`#### 容器骨架${s.name ? `（${s.name}）` : ''}\n\n以下骨架类**不在**内置 \`template.html\` 中，须按类清单契约在页面 \`<style>\` 内定义：\n\n${skelSub.trim()}`);
+    }
+  }
+  return blocks.join('\n\n');
+}
+
 const primer = `# AI Primer — 原型生成约束
 
-> 本文件由 scripts/gen-primer.mjs 从 base.md 确定性生成，请勿手工编辑。
-> 生成时间：${new Date().toISOString()} | 来源：base.md @ sha256:${digestShort}
+> 本文件由 scripts/gen-primer.mjs 从设计系统确定性生成，请勿手工编辑。
+> 生成时间：${new Date().toISOString()} | 来源：${sourceLabel} @ sha256:${digestShort}
 > 契约表：${count} 类组件（${countLabel}） | contract=${contract || 'unset'}
 
 ## 可用组件白名单（只用这些）
@@ -133,11 +184,12 @@ ${hardRules.join('\n')}
 
 ## 页面范式
 
-section 骨架与页面类型节奏见 prototype skill 的 layouts.md（reference：管理后台列表页 / 表单页 / 仪表盘 / Landing / 文档索引）。
+${pageArchetypeSection()}
 `;
 
 mkdirSync(dirname(primerPath), { recursive: true });
 writeFileSync(primerPath, primer, 'utf-8');
 console.log(`primer 已生成：${primerPath}`);
 console.log(`  组件白名单：${count} 类（${countLabel}）`);
+if (variants.length) console.log(`  参与 digest 的变体：${variants.map(v => basename(v.file)).join(' / ')}`);
 console.log(`  digest：sha256:${digestShort}`);

package/scripts/guard/checks/tasks-complete.mjs

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readState } from '../../lib/state-loader.mjs';
+import { parseTaskLine } from '../../lib/md-normalize.mjs';
 import {
   isLegacyChange,
   fullWorkflowSkipViolation,
@@ -49,16 +50,20 @@ export function checkTasksComplete(changeDir) {
   }
 
   const content = fs.readFileSync(tasksPath, 'utf-8');
-  const unchecked = content.match(/^[ \t]*- \[ \]/gm);
+  // v0.55.0 §8.4.3 横展（FB-4）：识别走共享原语 `parseTaskLine`
+  // （容忍 `*` bullet / 制表符分隔等纯格式变体）。此处是**计数/存在性语义**。
+  // 注：原实现的正则无 `$` 锚且用 `[ \t]*`，本就容忍缩进——本次不放宽也不收紧缩进。
+  const taskLines = content.split('\n').map(line => parseTaskLine(line)).filter(Boolean);
+  const uncheckedCount = taskLines.filter(task => !task.checked).length;
 
-  if (unchecked && unchecked.length > 0) {
+  if (uncheckedCount > 0) {
     return {
       pass: false,
-      failures: [`tasks.md: ${unchecked.length} unchecked task(s) remaining`],
+      failures: [`tasks.md: ${uncheckedCount} unchecked task(s) remaining`],
     };
   }
 
-  const hasAny = content.match(/^[ \t]*- \[[xX]\]/gm);
+  const hasAny = taskLines.some(task => task.checked);
   if (!hasAny) {
     return { pass: false, failures: ['tasks.md: no completed tasks found'] };
   }