@xulthekl/team-flow 0.52.0 → 0.54.0

package/scripts/design-system-import.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+// design-system-import.mjs — open-design DESIGN.md → team-flow base.md 转换器（v0.54.0，设计 §4.5.2）
+//
+// 解析 open-design 九节 DESIGN.md，映射到 team-flow 的 9 段 schema（A1/A2/B-slot + 组件契约表 + principles/governance）。
+// 关键约束：**A 类转换后必须补齐完整度**（palette 阶梯 / A2 派生公式 / B-slot 别名 / 组件契约表基线）——
+//           open-design 原文没有这些，转换器按 team-flow 规则生成。
+//
+// Usage: node scripts/design-system-import.mjs <DESIGN.md 路径> [--out <base.md 路径>] [--id <标识>]
+// 输出后建议运行：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 { fileURLToPath } from 'node:url';
+
+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 srcPath = positional[0];
+
+if (!srcPath) {
+  console.error('Usage: node scripts/design-system-import.mjs <DESIGN.md 路径> [--out <base.md 路径>] [--id <标识>]');
+  process.exit(1);
+}
+const srcAbs = resolve(srcPath);
+if (!existsSync(srcAbs)) {
+  console.error(`DESIGN.md not found: ${srcAbs}`);
+  process.exit(1);
+}
+
+const src = readFileSync(srcAbs, 'utf-8');
+const id = idArg || basename(dirname(srcAbs));
+
+// ── 解析 open-design 九节 ──
+
+function grab(pattern) {
+  const m = src.match(pattern);
+  return m ? m[1].trim() : null;
+}
+
+const title = grab(/^#\s+(.+)$/m) || `Design System Inspired by ${id}`;
+const category = grab(/> Category:\s*(.+)/) || 'Uncategorized';
+const summary = grab(/>\s*(?!Category)(.+\S)/) || '';
+
+// A 类模板格式：`**Primary:** \`#hex\``
+let primary = grab(/\*\*Primary:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+let surface = grab(/\*\*Surface:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+let text = grab(/\*\*Text:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+
+// B 类精细格式 fallback：找 brand/accent/primary 上下文附近的 hex（自动提取，需人工核对）
+let autoExtracted = false;
+if (!primary) {
+  const m = src.match(/(?:brand|accent|primary)[^\n]{0,100}?(#[0-9a-fA-F]{6})/i);
+  if (m) { primary = m[1]; autoExtracted = true; }
+}
+if (!surface) {
+  const m = src.match(/(?:background|surface|canvas)[^\n]{0,100}?(#[0-9a-fA-F]{6})/i);
+  surface = m ? m[1] : '#FFFFFF';
+  if (m) autoExtracted = true;
+}
+if (!text) {
+  const m = src.match(/(?:text|foreground)[^\n]{0,100}?(#[0-9a-fA-F]{6})/i);
+  text = m ? m[1] : '#111827';
+  if (m) autoExtracted = true;
+}
+
+const secondary = grab(/\*\*Secondary:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+const success = grab(/\*\*Success:\*\*\s*`(#[0-9a-fA-F]{3,8})`/) || '#16A34A';
+const warning = grab(/\*\*Warning:\*\*\s*`(#[0-9a-fA-F]{3,8})`/) || '#D97706';
+const danger = grab(/\*\*Danger:\*\*\s*`(#[0-9a-fA-F]{3,8})`/) || '#DC2626';
+const families = grab(/\*\*Families:\*\*\s*(.+)/) || 'primary=Inter, display=Inter, mono=ui-monospace';
+const scale = grab(/\*\*Scale:\*\*\s*(.+)/) || '12/14/16/20/24/32';
+const spacingScale = grab(/\*\*Spacing scale:\*\*\s*(.+)/) || '4/8/12/16/24/32';
+
+if (!primary) {
+  console.error(`未能从 ${srcAbs} 解析出 Primary 色。`);
+  console.error('A 类格式需 `**Primary:** \\`#hex\\``；B 类格式自动提取失败。');
+  console.error('B 类设计系统建议走人工路径：浏览参考文档 → 提取配色 → 用 create-from-code 或手工创建。');
+  process.exit(1);
+}
+if (autoExtracted) {
+  console.warn('⚠️  B 类格式：配色为自动提取（brand/surface/text 上下文匹配），**请人工核对后再采用**。');
+}
+
+// 字体族解析：primary=X, display=Y, mono=Z → 系统栈兜底（零依赖：不引 webfont，仅保留字体名首选 + 系统栈）
+function fontStack(family) {
+  const f = (family || 'Inter').trim().replace(/^['"]|['"]$/g, '');
+  const isMono = /mono|code|menlo|consolas/i.test(f);
+  if (isMono) return `'${f}', ui-monospace, SFMono-Regular, Menlo, monospace`;
+  return `'${f}', -apple-system, 'Segoe UI', system-ui, 'PingFang SC', 'Microsoft YaHei', sans-serif`;
+}
+const famMap = Object.fromEntries(families.split(',').map(p => {
+  const [k, v] = p.split('=').map(x => (x || '').trim());
+  return [k, v];
+}));
+const fontDisplay = fontStack(famMap.display || famMap.primary);
+const fontBody = fontStack(famMap.primary);
+const fontMono = fontStack(famMap.mono || 'ui-monospace');
+
+// 字号阶梯：open-design 的 "12/14/16/20/24/32" → type scale 名称映射
+const scaleNums = scale.split('/').map(s => s.trim()).filter(Boolean);
+const typeScale = scaleNums.slice(0, 7).map((v, i) => {
+  const names = ['--text-xs', '--text-sm', '--text-base', '--text-lg', '--text-xl', '--text-2xl', '--text-3xl'];
+  return `${names[i]}: ${v}px`;
+}).join('；') || '--text-xs: 12px；--text-sm: 14px；--text-base: 16px；--text-lg: 20px；--text-xl: 24px；--text-2xl: 32px';
+
+// ── 组件契约表基线（20 类，来自 design-system-architect.md 的完整基线）──
+
+const CONTRACT_ROWS = [
+  '| Button | 交互 | primary / secondary / ghost / danger | sm / md / lg | default / hover / focus-visible / active / disabled / loading | 触发动作 | 用颜色单独传状态 |',
+  '| Input | 交互 | default / error / success | sm / md / lg | default / focus / disabled / readonly / error / filled | 文本录入 | 无 label |',
+  '| Select | 交互 | default / multiple / searchable | sm / md / lg | default / focus / disabled / error / open | 选项选择 | 超 10 项不用搜索 |',
+  '| Checkbox | 交互 | default / indeterminate | sm / md | default / hover / focus / disabled / checked | 多选 | — |',
+  '| Radio | 交互 | default | sm / md | default / focus / disabled / selected | 单选 | 超 7 项改用 Select |',
+  '| Switch | 交互 | default | md | default / focus / disabled / on / off | 二元开关 | 高危操作须确认 |',
+  '| Tag | 轻量 | default / success / warning / danger / info | sm / md | default / hover / closable¹ | 状态标记 | 用作按钮 |',
+  '| Icon | 豁免 | — | sm / md / lg | — | 语义图示 | emoji |',
+  '| Avatar | 轻量 | circle / square | sm / md / lg | default / fallback / loading | 用户标识 | — |',
+  '| Tooltip | 轻量 | default | — | hidden / visible | 补充说明 | 承载关键操作 |',
+  '| Modal | 交互 | default / confirm / destructive | sm / md / lg | open / loading / error / closing | 阻断式交互 | 嵌套 Modal |',
+  '| Drawer | 交互 | left / right / bottom | sm / md / lg | open / loading / error | 侧边任务面板 | — |',
+  '| Tabs | 交互 | line / pill | — | default / active / disabled / loading | 内容分组 | 超 7 个 tab |',
+  '| Table | 交互 | default / compact / striped | — | default / loading / empty / error / selected | 结构化数据 | 无分页超长列表 |',
+  '| Form | 交互 | single / two-column | — | untouched / dirty / submitted-pending / error | 字段集合 | 单页超 20 字段 |',
+  '| Card | 交互 | default / interactive / stat | — | default / hover / selected / loading | 内容容器 | 嵌套超 2 层 |',
+  '| Pagination | 交互 | default / simple | sm / md | default / disabled / loading | 分页导航 | — |',
+  '| FilterBar | 交互 | default / collapsible | — | default / expanded / applied | 筛选条件集合 | — |',
+  '| EmptyState | 豁免 | default / filtered / error | — | — | 空态承载 | 只有"暂无数据" |',
+  '| Toast | 交互 | success / warning / error / info | — | entering / visible / exiting | 轻量反馈 | 承载需用户操作的信息 |',
+];
+
+// ── 生成 base.md ──
+
+const base = `# ${title}
+
+> a11y: WCAG 2.2 AA（对比度 4.5:1 / 大字 3:1 / 焦点可见 / 键盘可达）
+
+> 由 open-design 设计系统 \`${id}\`（Category: ${category}）转换生成（scripts/design-system-import.mjs v0.54.0）。
+> ${summary}
+> 来源归因：open-design（nexu-io）MIT License，"inspired by" 逆向工程描述，非官方资产。
+
+## color
+
+**A1-identity（8 必选）**
+- \`--bg\`: color-mix(in oklab, var(--surface), var(--fg) 3%)
+- \`--surface\`: ${surface}
+- \`--fg\`: ${text}
+- \`--muted\`: color-mix(in oklab, var(--fg), var(--surface) 45%)
+- \`--border\`: color-mix(in oklab, var(--fg), var(--surface) 88%)
+- \`--accent\`: ${primary}
+- \`--font-display\`: ${fontDisplay}
+- \`--font-body\`: ${fontBody}
+
+**语义色**：success ${success} / warning ${warning} / danger ${danger}${secondary ? ` / secondary ${secondary}` : ''}
+
+**A2-derived（color-mix 公式）**：--accent-hover / --accent-active / --focus-ring / --elev-raised（公式见 token-derivation.md）
+
+**B-slot 别名**：--fg-2 → var(--fg) / --meta → var(--muted) / --border-soft → var(--border) / --surface-warm → var(--surface)
+
+## typography
+
+- 字阶：${typeScale}
+- 行高：正文 1.5 / 标题 1.2
+- 字重：400（正文）/ 500-600（标题）
+
+## spacing
+
+- 阶梯（4 基数）：${spacingScale.split('/').map((v, i) => `${v.trim()}px`).join(' / ')}
+
+## layout
+
+- 栅格 12 列 / 断点 sm(640) md(1024) lg(1440) / 容器 max-width 1200px
+
+## components
+
+| 组件 | 类型 | variants | sizes | states | 用途 | 禁止 |
+|------|------|----------|-------|--------|------|------|
+${CONTRACT_ROWS.join('\n')}
+
+## motion
+
+- duration 150–250ms / easing ease-out（\`cubic-bezier(0.2, 0, 0, 1)\`）
+
+## voice
+
+- 语气：${category} 语境的简洁专业表达——具体文案要求由项目 PRD 补充。
+
+## brand
+
+- 品牌主色：${primary}（accent 用法：主 CTA / 链接 / 选中态）
+
+## anti-patterns
+
+1. 禁止内联样式漂移
+2. 禁止非 token 颜色
+3. ${category} 语境：不得引入与来源风格冲突的装饰效果
+
+## palette
+
+- neutral / primary / success / warning / danger 各 50–900 阶梯（primary 以 ${primary} 为 500 锚点，公式见 token-derivation.md）
+
+## principles
+
+1. 一致性优先于局部创意——同类信息用同一呈现
+2. 清晰优于装饰——信息层级先于视觉效果
+3. 可访问性默认开启——所有交互元素满足 WCAG AA
+
+## governance
+
+- contract: v1
+- version: 0.1.0
+- 负责人: {项目角色}
+- 弃用策略: 组件弃用需在 changelog 记录 + 保留 1 个迭代周期
+- changelog: 见文末"变更履历"段
+
+## 变更履历
+
+| 时间 | 变更内容 | 来源 |
+|------|---------|------|
+| ${new Date().toISOString().slice(0, 10)} | 从 open-design \`${id}\` 转换生成 | design-system-import.mjs |
+`;
+
+const outPath = outArg ? resolve(outArg) : resolve(`.team-flow/design-system/base.md`);
+mkdirSync(dirname(outPath), { recursive: true });
+writeFileSync(outPath, base, 'utf-8');
+
+console.log(`base.md 已生成：${outPath}`);
+console.log(`  来源：open-design ${id}（${category}）`);
+console.log(`  accent=${primary} / surface=${surface} / text=${text}`);
+console.log(`  组件契约表：20 类基线（待审阅调整）`);
+// 提示中的脚本路径用**本脚本所在插件目录**解析（绝对路径，可直接复制执行）——
+// 裸 `node scripts/...` 在插件零拷贝安装下不解析（v0.54.0 P4 根因）。
+const pluginDir = dirname(dirname(fileURLToPath(import.meta.url)));
+console.log('\n下一步（由 design-system skill 的 Step 5 评审 → Step 6 落盘承接）：');
+console.log(`  1) node ${join(pluginDir, 'scripts', 'gen-primer.mjs')} ${outPath}     # 生成 primer（组件白名单 + digest，缺失会阻断 prototype Step 0）`);
+console.log(`  2) node ${join(pluginDir, 'scripts', 'guard', 'design-token-guard.mjs')} ${dirname(outPath)}  # 硬校验 + 六层审计`);

package/scripts/gen-primer.mjs

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

package/scripts/guard/checks/arch-merged.mjs

@@ -0,0 +1,101 @@
+// scripts/guard/checks/arch-merged.mjs — arch-merged 门禁（v0.53.0，设计增强方案 v0.25 §110）
+//
+// 挂 `executing:closing`：本 change 的架构增量必须已回写到全局 docs/architecture/。
+//
+// **背景（§101.4 根因 II）**：team-flow 对「代码→测试」「specs→merge」「tasks→complete」
+// 都挂了门禁，唯独「架构增量→台账」没有——`executing:closing` 原挂 9 个维度、无 arch-merge；
+// 且 `VALID_STATES` 无 `closed`（`isChangeClosed` 的 `state === 'closed'` 是死分支），
+// **arch-merge 在状态机上没有任何锚点**。
+//
+// **B' 方案（§110.2）**：arch-merge 前移到状态转换**之前**执行，本维度即该转换的前置条件。
+// 时序：`tests/reviews 通过 → tf arch-merge → tf state transition closing → prototype-sync`。
+// 语义上可行——`executing→closing` 是一个**原子门禁**，所有维度一起 PASS 才放行，
+// 把「回写」纳入门禁校验范围不改变「验证通过后才归档」的语义。
+import fs from 'node:fs';
+import path from 'node:path';
+import { findProjectRoot, readArchState, isLegacyArch } from './arch-gate-exemptions.mjs';
+
+/**
+ * 读 change 的 .team-flow.yaml 顶层标量字段。
+ *
+ * ⚠ **未设置字段在 state 文件中序列化为字符串 `'null'` 而非 JS `null`**——这是项目
+ * 既定约定（`writeState` 用 `state.x ?? 'null'` 拼接）。`arch-design.mjs` /
+ * `compound-captured.mjs` 均显式归一化（`val === 'null' ? null : val`）。**本 check
+ * 初版漏了这一步**：test 夹具未设 `arch_design_decision` 时读到的 `'null'` 是真值，
+ * 于是「无架构增量」被误判为「需要回写」→ 门禁误 FAIL。
+ */
+function readChangeState(changeDir) {
+  const p = path.join(changeDir, '.team-flow.yaml');
+  if (!fs.existsSync(p)) return {};
+  const out = {};
+  for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+    const m = line.match(/^(\w+):\s*(.*)$/);
+    if (m) out[m[1]] = (m[2] === 'null' || m[2] === '') ? null : m[2].trim();
+  }
+  return out;
+}
+
+/**
+ * @param {string} changeDir - change 目录路径
+ * @returns {{ pass: boolean, failures: string[] }}
+ */
+export function checkArchMerged(changeDir) {
+  const changeName = path.basename(path.resolve(changeDir).replace(/\/$/, ''));
+  const state = readChangeState(changeDir);
+
+  // ① 无架构增量 → 豁免（arch_design_decision 缺失或 skipped）
+  const decision = state.arch_design_decision;
+  if (!decision || decision === 'skipped') return { pass: true, failures: [] };
+
+  // ② 显式跳过键（§110.2 加固 iii）——与 tasks_skipped / test_matrix_skipped 同一模式。
+  //    用于 arch-merge 确为 no-op 的场景（如 architecture.md 无演进日志段且无聚合）。
+  if (state.arch_merge_skipped === 'true') {
+    console.warn(`  [WARN] arch-merged: 显式跳过（reason: ${state.arch_merge_skip_reason || '<未填写>'}）`);
+    return { pass: true, failures: [] };
+  }
+
+  // ③ legacy 项目豁免（复用 arch-gate-exemptions 唯一真相源，防判定漂移）
+  const root = findProjectRoot(changeDir);
+  if (!root) return { pass: true, failures: [] };
+  if (isLegacyArch(readArchState(root))) {
+    console.warn('  [WARN] arch-merged: 项目架构基线未建立（arch_baseline 缺失）— legacy 豁免');
+    return { pass: true, failures: [] };
+  }
+
+  const archPath = path.join(root, 'docs', 'architecture', 'ARCHITECTURE.md');
+  if (!fs.existsSync(archPath)) {
+    return {
+      pass: false,
+      failures: [`全局 docs/architecture/ARCHITECTURE.md 不存在 — 运行 tf arch-merge ${changeDir}`],
+    };
+  }
+  const content = fs.readFileSync(archPath, 'utf-8');
+
+  // 双通道判据（**缺一则门禁可能永久 FAIL 无出路**，见 §115.1 P0-2）：
+  //
+  // 通道 ①：marker 区来源列的单元格**精确等于** `change:<name>`
+  //   —— 必须按单元格精确匹配：`content.includes('change:' + name)` 会被
+  //      `change:v1-C1-other` 这类前缀相同的邻项误命中。
+  //
+  // 通道 ②：演进日志锚 `### change:<name>`
+  //   —— **为何必须有此通道**：`upsertEvolutionLog` 在 change 的 architecture.md
+  //      **没有演进日志段**时首行即 `return globalContent` 静默早退，全局永远不会出现
+  //      该锚；而零聚合 change 的 marker 区来源列也不会出现（marker 区来自已合并聚合）。
+  //      只认单通道 → 这两类 change **永久 FAIL 且重跑 arch-merge 也不会改善**。
+  const viaRegistry = content.split('\n').some(line =>
+    line.split('|').some(cell => cell.trim() === `change:${changeName}`));
+  const escaped = changeName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const viaLog = new RegExp(`^### change:${escaped}\\s*$`, 'm').test(content);
+
+  if (viaRegistry || viaLog) return { pass: true, failures: [] };
+
+  return {
+    pass: false,
+    failures: [
+      `本 change 的架构增量未回写全局台账（marker 区来源列与演进日志锚均无 change:${changeName}）`
+      + ` — 运行 tf arch-merge ${changeDir}。`
+      + `B' 时序：arch-merge 在 executing→closing 转换**之前**执行（设计增强方案 v0.25 §110.2）。`
+      + `若本 change 确无架构增量可回写，显式置 arch_merge_skipped: true + arch_merge_skip_reason。`,
+    ],
+  };
+}

package/scripts/guard/checks/arch-snapshot.mjs

@@ -1,11 +1,24 @@
 // scripts/guard/checks/arch-snapshot.mjs — 架构快照门禁（v0.35.0，v0.14 §59.4）
-// 挂 executing:closing（先于 arch-merge）：本轮迭代产品级架构快照必须已落盘（"先快照后回写"强制化）。
+// 挂 executing:closing：本轮迭代产品级架构快照必须已落盘（"先快照后回写"强制化）。
+//
+// v0.53.0 注释修正：原写「（先于 arch-merge）」。B' 方案（设计增强方案 v0.25 §110）已把
+// arch-merge 前移到本转换**之前**执行，"先于 arch-merge"不再成立。二者现同挂本转换且
+// **无数据依赖**：本 check 只读 `docs/architecture/iterations/`，而 arch-merge 全流程不触碰
+// 该目录（已逐行核对）。"先快照后回写"仍是语义前提（快照在 ARCH 阶段产出，早于整个 closing）。
 //
 // 规则：
 // - arch_baseline == null（在途/存量）→ PASS + WARN（legacy 豁免）
 // - skip 已物化（iterations/vN/SKIPPED）→ PASS
 // - iterations/<latest>/architecture.md 存在 → PASS
 // - 否则 → FAIL
+//
+// v0.53.0 §115.1 P2-5 修复：本文件使用 `join` / `existsSync` 但**从未导入**
+// `node:path` / `node:fs` → 走到兜底分支时抛 `ReferenceError`（运行期崩溃）。
+// 此前未暴露是因为前三个早退分支（legacy / skip / 有快照）覆盖了绝大多数场景；
+// 只有「非 legacy + 无 skip + 无快照」的项目才会走到第 35 行。横展核查全部 22 个
+// guard check 文件（该目录 .mjs 文件数，随本轮新增 arch-merged.mjs 由 21 增至 22），仅此一处。
+import fs from 'node:fs';
+import path from 'node:path';
 import {
   findProjectRoot, readArchState, isLegacyArch,
   findLatestIterationSnapshot, isArchSkipMaterialized, ARCH_READINESS_FAIL_HINT,
@@ -32,8 +45,8 @@ export function checkArchSnapshot(changeDir) {
   if (snap) return { pass: true, failures: [] };
 
   // v0.36.3 §63.4 在途 change 兜底：快照缺失但 change 已有增量产物 → 以 change 产物为实际态（存量升级场景）
-  const archDir = join(changeDir, 'architecture');
-  if (existsSync(archDir) && existsSync(join(archDir, 'architecture.md'))) {
+  const archDir = path.join(changeDir, 'architecture');
+  if (fs.existsSync(archDir) && fs.existsSync(path.join(archDir, 'architecture.md'))) {
     console.warn('  [WARN] arch-snapshot: 产品级快照缺失，以 change 增量产物兜底（存量升级在途 change，快照后补为 v0）');
     return { pass: true, failures: [] };
   }