@xulthekl/team-flow 0.63.0 → 0.65.0

package/scripts/lib/cmd-state.mjs

@@ -17,6 +17,13 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // schema_version 不可设置（仅 init 打戳，防止伪造豁免身份，v0.13 §48.1）。
 const SETTABLE_FIELDS = [
   'workflow', 'batches_completed', 'spec_merged',
+  // v0.64.0 P0（实施计划 §3.3）：前门双维度。三环齐全（本列表 + state-loader
+  // BUILTIN_DEFAULTS + writeState 序列化分支），缺一即「回显成功却零写入」。
+  // workflow_variant 走通用通道仅 exploring 态可写（下方 set 分支强制）；
+  // 升档豁免 = tf state upgrade 专用子命令（不经本通道），写入打
+  // variant_source=upgrade + variant_direction=up，guard 据此 fail-closed。
+  'workflow_variant', 'variant_source', 'variant_direction',
+  'planned_arch', 'model_profile',
   'dp_0_decisions', 'dp_0_confirmed', 'dp_0_timestamp', 'dp_0_result',
   // v0.59.0（P4 实测）：dp_{1,2,3,5,6,7}_decisions / _confirmed 共 12 个字段已移除——
   // 它们虽在旧白名单内，但 writeState 无对应序列化分支，tf state set 会**回显成功却零写入**
@@ -49,6 +56,8 @@ const SETTABLE_FIELDS = [
   // 三键必须与 state-loader BUILTIN_DEFAULTS + writeState 序列化分支同步注册，
   // 缺任一环即「回显成功却零写入」（v0.59.0 同型教训，见本文件 :20-24 注释）。
   'gates_probed_skipped', 'gates_probed_skip_reason', 'gates_probed_na',
+  // v0.64.0（§4 arch-design-light）：轻架构说明显式跳过键（须附理由）
+  'arch_design_light_skipped', 'arch_design_light_skip_reason',
 ];
 
 export async function run(args) {
@@ -66,7 +75,7 @@ export async function run(args) {
 
   if (!changeDir) {
     console.error('Usage: tf state <subcommand> <change-dir> [arg]');
-    console.error('Subcommands: init, check, transition, get, rebuild, set');
+    console.error('Subcommands: init, check, transition, get, rebuild, set, upgrade');
     process.exit(2);
   }
 
@@ -80,7 +89,7 @@ export async function run(args) {
   // Unknown subcommand: report a usage error (exit 2) BEFORE the BUG-B
   // state-file existence check, so a bad subcommand is not masked by the
   // "No state file" error (which would return exit 1 instead of exit 2).
-  const KNOWN_SUBS = ['init', 'check', 'transition', 'get', 'rebuild', 'set'];
+  const KNOWN_SUBS = ['init', 'check', 'transition', 'get', 'rebuild', 'set', 'upgrade'];
   if (!KNOWN_SUBS.includes(sub)) {
     console.error(`Unknown subcommand: ${sub}. Valid: ${KNOWN_SUBS.join(', ')}`);
     process.exit(2);
@@ -112,6 +121,12 @@ export async function run(args) {
       const state = readState(changeDir);
       if (!stateFileExisted) {
         state.schema_version = 1;
+        // v0.64.0 P0（§4 扫描基线）：init 打戳 base_sha（架构 surface 扫描的 git 基线）。
+        // 非 git 环境 / 尚无提交 → 保持 null，扫描时按 §4 退化参照（origin → FAIL）。
+        try {
+          const rev = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: changeDir, encoding: 'utf-8', timeout: 3_000 });
+          if (rev.status === 0 && rev.stdout?.trim()) state.base_sha = rev.stdout.trim();
+        } catch { /* 保持 null */ }
       }
       state.artifacts_hash = hash;
       state.contract_hash = ch;
@@ -170,7 +185,16 @@ export async function run(args) {
       const rawWorkflow = state.workflow || 'full';
       // Normalize: guard only accepts full/hotfix/tweak, not "auto"
       const workflow = rawWorkflow === 'auto' ? 'full' : rawWorkflow;
-      const guardResult = spawnSync('node', [guardScript, 'check', changeDir, fromState, toState, '--json', '--workflow', workflow], {
+      // v0.64.0 P1（§3.3/§4.5 注记①）：透传前门变体——guard 据此选 quick/planned 维度表。
+      // 这是 workflow_variant 到达 resolveDimensions 的唯一管道（workflow-start 是 skill，不是调用方）。
+      const guardArgs = [guardScript, 'check', changeDir, fromState, toState, '--json', '--workflow', workflow];
+      if (state.workflow_variant != null && state.workflow_variant !== 'null') {
+        guardArgs.push('--workflow-variant', String(state.workflow_variant));
+      }
+      if (state.planned_arch === true || state.planned_arch === 'true') {
+        guardArgs.push('--planned-arch', 'true');
+      }
+      const guardResult = spawnSync('node', guardArgs, {
         cwd: join(__dirname, '..', '..'),
         timeout: 10_000,
       });
@@ -282,6 +306,28 @@ export async function run(args) {
         }
         process.exit(1);
       }
+      // v0.64.0 P0 写限（§3.3/§5.3）：workflow_variant 通用通道仅 exploring 态可写，
+      // 防关门段自降档清屏；升档唯一豁免 = tf state upgrade 专用子命令（不走本通道）。
+      if (field === 'workflow_variant') {
+        const cur = readState(changeDir);
+        if (cur.state !== 'exploring') {
+          console.error(
+            `⛔ 'workflow_variant' 仅可在 exploring 态通过本通道写入（当前: ${cur.state}）。\n` +
+            `   升档唯一机械入口: tf state upgrade <change-dir> <planned|full>（原子改写 variant_source=upgrade + 回退 approved-for-build + 重算 hash；降档拒绝）`
+          );
+          process.exit(1);
+        }
+        if (value !== 'null' && !['direct', 'planned', 'legacy'].includes(value)) {
+          console.error(`⛔ Invalid workflow_variant: '${value}'. Must be one of: direct, planned, legacy, null`);
+          process.exit(1);
+        }
+      }
+      if (field === 'model_profile') {
+        if (!['mechanical', 'standard', 'strong', 'review'].includes(value)) {
+          console.error(`⛔ Invalid model_profile: '${value}'. Must be one of: mechanical, standard, strong, review`);
+          process.exit(1);
+        }
+      }
       updateField(changeDir, field, value);
       if (values.json) {
         console.log(JSON.stringify({ ok: true, field, value }));
@@ -290,8 +336,52 @@ export async function run(args) {
       }
       break;
     }
+    case 'upgrade': {
+      // v0.64.0（实施计划 §5.3 D9，升档唯一机械入口）：
+      // tf state upgrade <change-dir> <planned|full>
+      // 校验方向向上 → 原子写 variant_source=upgrade + variant_direction=up →
+      // state 回退 approved-for-build（重跑目标档闸门）→ 重算 artifacts_hash（B-10）。
+      // 保留：磁盘代码/产物、test_result + test_evidence_path、test_matrix_hash。
+      const toVariant = arg;
+      if (!['planned', 'full'].includes(toVariant)) {
+        console.error('Usage: tf state upgrade <change-dir> <planned|full> (downgrades are forbidden)');
+        process.exit(2);
+      }
+      const ORDER = { direct: 0, planned: 1 };
+      const cur = readState(changeDir);
+      const from = cur.workflow_variant;
+      // 档位序：direct(0) < planned(1) < full/legacy(2)。upgrade full = 置 legacy + workflow full
+      //（variant 枚举无 'full'，full 档由 workflow=full + legacy 全量仪式表达，方案 §5.3）。
+      const fromOrder = from === 'legacy' || from == null ? 2 : (ORDER[from] ?? 0);
+      const targetOrder = toVariant === 'full' ? 2 : ORDER[toVariant];
+      if (fromOrder >= targetOrder) {
+        console.error(`⛔ Upgrade ${from ?? 'null'} -> ${toVariant} is not upward (downgrades are forbidden)`);
+        process.exit(1);
+      }
+      cur.workflow_variant = toVariant === 'full' ? 'legacy' : toVariant;
+      cur.variant_source = 'upgrade';
+      cur.variant_direction = 'up';
+      if (toVariant === 'full') cur.workflow = 'full';
+      // 已过规划段则回退 approved-for-build 重跑目标档闸门；exploring 态无需回退
+      const ROLLBACK_STATES = ['specifying', 'bridging', 'executing', 'debugging', 'closing'];
+      if (ROLLBACK_STATES.includes(cur.state)) {
+        const prev = cur.state;
+        cur.state = 'approved-for-build';
+        cur.last_transition_from = prev;
+        cur.last_transition_to = 'approved-for-build';
+        cur.last_transition = new Date().toISOString();
+      }
+      cur.artifacts_hash = computeArtifactsHash(changeDir); // B-10 重算，防 doctor/check 恒报不一致
+      writeState(changeDir, cur);
+      if (values.json) {
+        console.log(JSON.stringify({ ok: true, from: from ?? 'null', to: cur.workflow_variant, state: cur.state, variant_source: 'upgrade' }));
+      } else {
+        console.log(`✅ Upgraded workflow_variant: ${from ?? 'null'} -> ${cur.workflow_variant} (source=upgrade, state=${cur.state}, artifacts_hash recomputed)`);
+      }
+      break;
+    }
     default:
-      console.error(`Unknown subcommand: ${sub}. Valid: init, check, transition, get, rebuild, set`);
+      console.error(`Unknown subcommand: ${sub}. Valid: init, check, transition, get, rebuild, set, upgrade`);
       process.exit(2);
   }
 }

package/scripts/lib/config-loader.mjs

@@ -47,6 +47,26 @@ const DEFAULTS = {
     // 各 skill 上下文加载时按 phase 过滤注入
     // 示例: { database: ".team-flow/conventions/db-design.md", ... }
   },
+  arch: {
+    // C4 代码注解扫描配置（ddd-purity-and-arch-merge-design v1.4 §5.4-4b）。
+    // C4 是本机制**唯一**「A 级 · 真独立」锚：锚点 = 代码本体，不经 arch-merge 写路径。
+    scan: {
+      // 持久化注解名（默认 MyBatis-Plus）。非该框架的项目改此值。
+      annotation: 'TableName',
+      // 自定义正则源（优先于 annotation）。约定 capture group(1) 为表名。
+      pattern: null,
+      // 扫描的目标文件扩展名。
+      extensions: ['.java'],
+      // 多仓场景：扫描根（相对项目根）；为空则扫项目根。
+      // emp-auth 恰把两仓放在同一工作树，故单根可跑；两仓分属不同 git 仓库时须配置。
+      repos: [],
+      // 排除目录（按 basename 匹配，任意层级生效）。
+      // ★ 必配：emp-auth 根下有 4 个 .worktrees/ 副本，不排除会把同一批注解重复计入。
+      // ★ 真相源说明（P3 MIN-4）：**强制底线以 `arch-scan-code.mjs` 的 `DEFAULT_EXCLUDE_DIRS`
+      //   为准**（并集语义恒生效，配置只能追加）——此处仅是文档性默认值，漂移不影响强制性。
+      exclude: ['.worktrees', '.git', 'node_modules', 'target', 'build', 'dist'],
+    },
+  },
   glaf4_dev: {
     // glaf4-dev 运行时探测结果（v2.1 §4 接口①）
     // contract-builder 产出 execution-contract 时实时探测写入；delegation_mode 由用户/编排开关

package/scripts/lib/execution-plan.mjs

@@ -107,7 +107,9 @@ export function validatePlan(changeDir, plan) {
   if (state.revision != null && plan?.revision !== state.revision) {
     failures.push('execution plan revision does not match state');
   }
-  if (plan?.workflow !== 'tweak') {
+  // v0.64.0（§4.5 注记⑤配套）：planned（workflow=full+variant=planned）无 recommendation/
+  // selection 仪式——plan 由 tasks.md 派生，不走 execution-recommendation 流程；豁免三件要求。
+  if (plan?.workflow !== 'tweak' && state.workflow_variant !== 'planned') {
     if (plan?.recommendation === undefined) failures.push('execution plan recommendation is required for full/hotfix');
     if (plan?.recommendation_receipt === undefined) failures.push('execution plan recommendation receipt is required for full/hotfix');
     if (plan?.selection === undefined) failures.push('execution plan selection is required for full/hotfix');

package/scripts/lib/state-loader.mjs

@@ -15,6 +15,21 @@ export const VALID_STATES = [
 const BUILTIN_DEFAULTS = {
   state: 'exploring',
   workflow: 'auto',
+  // spec-superflow 2.0 双维度（v0.64.0 P0；实施计划 §3.1）：
+  // workflow 仍是内部档位 full|hotfix|tweak|quick|lightweight（+auto 归一化前）；
+  // workflow_variant 是用户前门意图 null|direct|planned|legacy——两者不可混用。
+  // 旧 yaml 缺字段 → null，路由语义 = legacy 分支（见 workflow-start SKILL）。
+  workflow_variant: null,
+  // 升档标记（§5.3）：variant_source ∈ null|start|upgrade；direction ∈ null|up|down。
+  // guard fail-closed 校验数据源——非 exploring 改 variant 必须 source=upgrade 且 direction=up。
+  variant_source: null,
+  variant_direction: null,
+  // planned 是否走轻架构表（arch-design-light + arch-snapshot-light，G3）
+  planned_arch: false,
+  // 角色级模型分配档（config-loader MODEL_PROFILES），仅解析不改流程（§3.5）
+  model_profile: 'standard',
+  // 架构 surface 扫描基线（§4）：tf state init 打戳 git HEAD；缺失时扫描退化参照
+  base_sha: null,
   revision: null,
   artifacts_hash: null,
   contract_hash: null,
@@ -90,6 +105,10 @@ const BUILTIN_DEFAULTS = {
   gates_probed_skipped: null,
   gates_probed_skip_reason: null,
   gates_probed_na: null,
+  // v0.64.0（§4 arch-design-light）：轻架构说明的显式跳过键（skip-with-reason 模式，
+  // 与 arch_merge_skipped / test_matrix_skipped 同型：跳过必须附理由留痕）
+  arch_design_light_skipped: null,
+  arch_design_light_skip_reason: null,
   // 注意：schema_version 故意不在 BUILTIN_DEFAULTS 中（v0.13 §48.1）——
   // 它只由 `tf state init` 在 change 创建时打戳，字段缺失本身就是"存量 change"信号。
 };
@@ -135,6 +154,26 @@ export function writeState(changeDir, state) {
   lines.push('# === Core state ===');
   lines.push(`state: ${state.state || 'exploring'}`);
   lines.push(`workflow: ${state.workflow || 'auto'}`);
+  // v0.64.0 P0：前门双维度字段。条件序列化（同 schema_version 模式）——
+  // 存量 change 无这些字段时不追加，避免全量 churn；readState 缺失回退 BUILTIN_DEFAULTS。
+  if (state.workflow_variant != null) {
+    lines.push(`workflow_variant: ${state.workflow_variant}`);
+  }
+  if (state.variant_source != null) {
+    lines.push(`variant_source: ${state.variant_source}`);
+  }
+  if (state.variant_direction != null) {
+    lines.push(`variant_direction: ${state.variant_direction}`);
+  }
+  if (state.planned_arch === true || state.planned_arch === 'true') {
+    lines.push(`planned_arch: true`);
+  }
+  if (state.model_profile != null && state.model_profile !== 'standard') {
+    lines.push(`model_profile: ${state.model_profile}`);
+  }
+  if (state.base_sha != null) {
+    lines.push(`base_sha: ${state.base_sha}`);
+  }
   lines.push(`revision: ${state.revision ?? 'null'}`);
   // v0.13 §48.1：schema_version 仅由 tf state init 在 change 创建时打戳；
   // 缺失 = 存量 change（测试门禁豁免键）。rebuild/set 不追加，故条件序列化。
@@ -225,6 +264,10 @@ export function writeState(changeDir, state) {
   lines.push(`gates_probed_skipped: ${state.gates_probed_skipped ?? 'null'}`);
   lines.push(`gates_probed_skip_reason: ${state.gates_probed_skip_reason ?? 'null'}`);
   lines.push(`gates_probed_na: ${state.gates_probed_na ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Light architecture design gate (v0.64.0) ===');
+  lines.push(`arch_design_light_skipped: ${state.arch_design_light_skipped ?? 'null'}`);
+  lines.push(`arch_design_light_skip_reason: ${state.arch_design_light_skip_reason ?? 'null'}`);
 
   fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
 }

package/scripts/lib/surface-scan.mjs

@@ -0,0 +1,156 @@
+// scripts/lib/surface-scan.mjs — 架构 surface 扫描共享层（v0.64.0，实施计划 §4）
+//
+// 唯一真相源：direct-short-path / arch-merged-light / test-merged-light /
+// cross-change-consistency-light 都从这里取「本次变更碰了哪些文件、是否命中架构 surface」。
+// 判据统一为「架构 surface = API / DB / 聚合」（R2 A-17 统一，禁止各 check 自造变体）。
+//
+// 三源合并（B-05/B-06）：已提交 diff + 工作区修改 + untracked；基线 = state.base_sha，
+// 缺失退化 origin/<default> merge-base，再无 → no-baseline（fail-closed，禁 merge-base HEAD HEAD 空过）。
+// 聚合清单（B-04）：.team-flow/aggregate-dirs.txt 机器清单（每行一个目录前缀，# 注释，
+// 空文件 = 显式确认无聚合）；与 docs/architecture/baseline.md 皆缺失 → missing（fail-closed）。
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const GIT_TIMEOUT_MS = 2_000; // §4 扫描预算 ≤2s（cmd-state spawnSync 10s 总超时）
+
+// API/DB surface 路径模式（§4 路径模式表）——聚合只认清单目录，不做词义解析
+const SURFACE_PATH_RE = /(^|\/)(api|apis|routes|controllers?)(\/|$)|mapper|migrations?(\/|$)|(^|\/)schema[._/-]|\.(sql)$/i;
+// 测试文件（test-merged-light 用）
+const TEST_PATH_RE = /(^|\/)(tests?|__tests__|spec)(\/|$)|\.(test|spec)\.[jt]sx?$|Test\.java$/i;
+
+function git(args, cwd) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf-8',
+    timeout: GIT_TIMEOUT_MS,
+    maxBuffer: 8 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/** 由 changes/<name> 推项目根：优先含 changes/ 或 docs/ 的祖先 */
+export function findProjectRoot(changeDir) {
+  const a = dirname(dirname(changeDir));
+  if (existsSync(join(a, 'changes')) || existsSync(join(a, 'docs'))) return a;
+  const b = dirname(changeDir);
+  if (existsSync(join(b, 'changes')) || existsSync(join(b, 'docs'))) return b;
+  return a;
+}
+
+/**
+ * 解析聚合清单。返回 { missing, dirs[] }。
+ * missing=true 表示两处皆无 → 调用方 fail-closed。
+ */
+export function readAggregateList(projectRoot) {
+  const txt = join(projectRoot, '.team-flow', 'aggregate-dirs.txt');
+  const baseline = join(projectRoot, 'docs', 'architecture', 'baseline.md');
+  const txtExists = existsSync(txt);
+  const baselineExists = existsSync(baseline);
+  if (!txtExists && !baselineExists) return { missing: true, dirs: [] };
+  if (!txtExists) return { missing: false, dirs: [] }; // 有 baseline 但无机器清单：清单维度放行，聚合匹配按空表（见设计 §4）
+  const dirs = readFileSync(txt, 'utf-8')
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('#'));
+  return { missing: false, dirs };
+}
+
+function readScanIgnore(projectRoot) {
+  const p = join(projectRoot, '.team-flow', 'scan-ignore');
+  if (!existsSync(p)) return [];
+  return readFileSync(p, 'utf-8')
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('#'));
+}
+
+/**
+ * 三源合并的变更文件清单。
+ * 返回 { error: null|'no-baseline'|'diff-failed', files: string[], base }
+ */
+export function gitChangedFiles(changeDir, state) {
+  const files = new Set();
+  let base = state?.base_sha || null;
+
+  // 退化：base_sha 缺失 → origin/<default> merge-base（B-05：参照对象写死）
+  if (!base) {
+    try {
+      const ref = git(['symbolic-ref', 'refs/remotes/origin/HEAD'], changeDir).trim();
+      const remoteBranch = ref.replace('refs/remotes/', '');
+      base = git(['merge-base', 'HEAD', remoteBranch], changeDir).trim();
+    } catch {
+      return { error: 'no-baseline', files: [], base: null };
+    }
+  }
+
+  // 源①：已提交 diff（base...HEAD）
+  try {
+    for (const f of git(['diff', '--name-only', `${base}...HEAD`], changeDir).split('\n')) {
+      if (f.trim()) files.add(f.trim());
+    }
+  } catch {
+    return { error: 'diff-failed', files: [], base };
+  }
+
+  // 源②：工作区已修改
+  try {
+    for (const f of git(['diff', '--name-only', 'HEAD'], changeDir).split('\n')) {
+      if (f.trim()) files.add(f.trim());
+    }
+  } catch { /* 无 HEAD 时忽略 */ }
+
+  // 源③：untracked（porcelain -uall；B-06：新建未 add 的文件只有此源可见）
+  try {
+    for (const line of git(['status', '--porcelain', '-uall'], changeDir).split('\n')) {
+      if (!line) continue;
+      let p = line.slice(3);
+      const arrow = p.indexOf(' -> ');
+      if (arrow !== -1) p = p.slice(arrow + 4); // rename 取新名
+      p = p.trim().replace(/^"|"$/g, '');
+      if (p) files.add(p);
+    }
+  } catch { /* 忽略 */ }
+
+  // 排除清单（B-06：防无关 WIP 误报）
+  const ignore = readScanIgnore(findProjectRoot(changeDir));
+  const out = [...files].filter(f => !ignore.some(prefix => f.startsWith(prefix)));
+  return { error: null, files: out, base };
+}
+
+/**
+ * 文件 → 架构 surface 分类。
+ * 返回 { architectureSurface, apiFiles, dbFiles, aggregateFiles, testFiles }
+ */
+export function classifyFiles(files, aggregateDirs) {
+  const apiFiles = [];
+  const dbFiles = [];
+  const aggregateFiles = [];
+  const testFiles = [];
+  for (const f of files) {
+    if (TEST_PATH_RE.test(f)) testFiles.push(f);
+    if (SURFACE_PATH_RE.test(f)) {
+      apiFiles.push(f);
+      if (/migrations?(\/|$)|schema[._/-]|\.(sql)$/i.test(f)) dbFiles.push(f);
+    }
+    if (aggregateDirs.some(d => {
+      const norm = d.replace(/\/+$/, '');
+      return f === norm || f.startsWith(`${norm}/`);
+    })) {
+      aggregateFiles.push(f);
+    }
+  }
+  const architectureSurface = [...new Set([...apiFiles, ...aggregateFiles])];
+  return { architectureSurface, apiFiles, dbFiles, aggregateFiles, testFiles };
+}
+
+/** 便捷组合：扫描 + 清单 + 分类（各 light runner 统一入口） */
+export function scanArchitectureSurface(changeDir, state) {
+  const changed = gitChangedFiles(changeDir, state);
+  if (changed.error) return { error: changed.error, projectRoot: findProjectRoot(changeDir) };
+  const projectRoot = findProjectRoot(changeDir);
+  const agg = readAggregateList(projectRoot);
+  if (agg.missing) return { error: 'aggregate-list-missing', projectRoot };
+  const cls = classifyFiles(changed.files, agg.dirs);
+  return { error: null, projectRoot, files: changed.files, ...cls };
+}

package/scripts/lib/test-merge.mjs

@@ -40,6 +40,8 @@ function parseArgv(argv) {
       parsed.projectRoot = argv[++i];
     } else if (argv[i] === '--dry-run') {
       parsed.dryRun = true;
+    } else if (argv[i] === '--light') {
+      parsed.light = true;
     } else if (!argv[i].startsWith('--')) {
       parsed._.push(argv[i]);
     }
@@ -584,11 +586,13 @@ export async function run(args) {
 async function main(argv, projectRoot) {
   const changeDir = argv._[0];
   const dryRun = argv.dryRun || false;
+  const light = argv.light || false; // v0.64.0 §4：planned 轻回写入口（同 rewriteIndex 单写）
 
   if (!changeDir) {
-    console.error('Usage: tf test-merge <change-dir> [--project-root <path>] [--dry-run]');
+    console.error('Usage: tf test-merge <change-dir> [--project-root <path>] [--dry-run] [--light]');
     process.exit(2);
   }
+  if (light) console.log('  Mode: LIGHT（增量条目 + change:<name> 归因锚写入 changelog）');
 
   const absChangeDir = resolve(changeDir);
   const changeName = extractChangeName(absChangeDir);
@@ -643,7 +647,11 @@ async function main(argv, projectRoot) {
   console.log(`${mark} Step 3: resolveDeferred — ${deferredResult.resolved} items resolved`);
 
   // Step 4: appendChangelog
-  const changelogPath = appendChangelog(ledgerDir, changeName, matrixContent, dryRun);
+  // v0.64.0 §4：light 模式在 changelog 首行写入归因锚 `change:<name>`——
+  // arch-merged-light 同型的 guard 归因判据（test-merged-light）依赖该锚，
+  // full 模式文件名即含 changeName，锚为显式加固不改变既有内容。
+  const changelogContent = light ? `<!-- change:${changeName} -->\n${matrixContent}` : matrixContent;
+  const changelogPath = appendChangelog(ledgerDir, changeName, changelogContent, dryRun);
   console.log(`${mark} Step 4: appendChangelog — ${relative(projectRoot, changelogPath)}`);
 
   // Step 5: rewriteIndex

package/scripts/team-flow.mjs

@@ -71,9 +71,12 @@ Commands:
   arch scaffold         Scaffold global docs/architecture/ ledger in generator format (v0.53.0 §102)
   arch precheck <change-dir> [--json]
                         Emit deterministic architecture-gate evidence (v0.22 §88; evidence only, exit 0)
-  arch-merge <change-dir> [--project-root <path>] [--dry-run]
+  arch scan-code [--root <path>|--project-root <path>] [--repos <a,b>] [--annotation <name>] [--exclude <a,b>] [--json]
+                        Scan code for persistence annotations (C4 anchor; v1.4 §5.4-4b;
+                        read-only, zero-dep, evidence only, exit 0; status=na N/A, status=partial partial coverage — neither is PASS)
+  arch-merge <change-dir> [--project-root <path>] [--dry-run] [--light]
                         Merge architecture delta into global docs/architecture/
-  test-merge <change-dir> [--project-root <path>] [--dry-run]
+  test-merge <change-dir> [--project-root <path>] [--dry-run] [--light]
                         Merge test matrix results into global docs/test-ledger/
   test-matrix-export <input.json> <output.md> [--change-id <id>]
                         Convert glaf4 test-matrix.json to team-flow test-matrix.md
@@ -90,7 +93,7 @@ Commands:
                         pytest: terminal summary or junit XML (--junitxml)
   config [options]      Display or modify configuration
   config --resolve-model <profile>  Resolve a configured model profile without switching models
-  state <sub> <dir>     Manage .team-flow.yaml state (init|check|transition|get|rebuild)
+  state <sub> <dir>     Manage .team-flow.yaml state (init|check|transition|get|rebuild|set|upgrade)
   inject <dir>          Generate phase-guard artifacts; use --platforms <name|all> when platform is ambiguous
   audit <dir>           Generate decision-point-audit.md from .team-flow.yaml
   checkpoint save <change-dir> --task <id> --next <text>

package/skills/architecture-design/SKILL.md

@@ -22,7 +22,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 实体(唯一标识)+值对象(无标识)+聚合根(唯一入口)+事务边界(聚合内一事务)。聚合仅存于业务服务；数据服务/技术服务无聚合。
 
 ### F5 · 限界上下文(Context Map)
-语义边界=L3 应用服务；同术语异义须显式映射(Shared Kernel / Anti-Corruption Layer / Open Host Service)。
+语义边界=L3 应用服务；同术语异义须显式映射——**经典 8 模式**（Shared Kernel / Customer-Supplier / Conformist / Anti-Corruption Layer / Open Host Service / Separate Ways / Partnership / Published Language），选型走决策流（`references/context-map-8.md`，含 Mermaid；CML NO-GO）。
 
 ### F6 · CQRS 写读模型
 事务型对象→写模型(聚合，Command/Read 操作)；分析型对象→读模型(查询模型，Query 派生，无事务)。Command/Read→写模型；Query 经阻断测试分流。
@@ -37,7 +37,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 - ch01-4a-domains — 4A 四域定义与分叉依赖
 - ch02-change-cascade — 变更级联与跨域一致性门禁
 - ch03-architecture-outputs — 架构产出三层 + 治理三支柱
-- ch04-entity-to-aggregate — 业务实体→聚合→限界上下文
+- ch04-entity-to-aggregate — 业务实体→聚合→子域→限界上下文
 - ch05-cqrs — 写/读模型、指令分流、三维判定
 - ch06-integration — 与 team-flow / compound-engineering 的集成
 
@@ -54,6 +54,11 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 - Command / Read / Query → ch05
 - 阻断测试 / 三维判定 → ch05
 - 增量设计 / As-Is 冻结 / 复利回写 / 全局锚点 → ch06
+- 子域 / 问题空间·解空间 / 统一语言索引 → ch04, 产品级模板 §0/§1.1（O2/O3）
+- Context Map 8 模式 / 决策流 / Mermaid → references/context-map-8.md（O7）
+- 事件 schema 版本策略 / 领域事件表 → 产品级模板 §3.2 门禁段 + 变更级模板 §2.5（O4）
+- Saga 补偿矩阵 / Projection 重建 / ADR 模板 → references/ddd-evented-playbook.md, references/adr-templates.md（O5/O6）
+- DDD 深度 advisory / ddd_depth（lightweight≠skipped）→ 「DDD 深度 advisory」段 + 结构化输出契约（O1）
 
 ## Workflow Integration: 判断+执行一体化（v0.9 §26）
 
@@ -67,10 +72,19 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 
 - `change-brief.md`（scope / AC / 技术方向）
 - `requirement/vN/plan.md` 高阶技术设计段（模块边界/技术选型/数据流/关键聚合划分）
-- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的唯一事实源；**Fast Path 下不读**（见 `### Fast Path`）
+- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**设计期主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的设计输入（★ O8：**落地态权威 = 全局 ARCHITECTURE.md**（registry 渲染），快照 = grounding + seed 源 + 体检基准，不称唯一事实源）；**Fast Path 下不读**（见 `### Fast Path`）
 - 全局 `docs/architecture/`（As-Is 实际态基线，已落地部分）
 - 现有 `specs/`（若有）
 
+### DDD 深度 advisory（O1 · 在五项检查**之前**执行）
+
+按**领域复杂度**输出 DDD 深度旗标（advisory，**绝不替代 `decision`**）：
+
+- **三判据**（禁「4 选 2」硬阈值，防 LLM 套用偏差放大）：① 是否有丰富行为/不变量 ② 是否存在模型冲突（同词异义/多义） ③ 是否存在值得深建模的 Core Domain。
+- 输出 `ddd_depth: full | lightweight`。吸收「3 Questions + 反模式红牌」（微服务过早 / CQRS / 事件溯源 / DDD / Repository 可能过度工程）。
+- **★ 头号红牌：`lightweight ≠ skipped`**——lightweight 分支**仍须走完五项检查，且第 4/5 项（API / DB schema）不得短路**；只是战术建模从简（可省略部分 DDD 战术制品），判定与 API/DB 设计照做。
+- **诚实边界**：LLM 是否把 lightweight 误当"可跳过"**无法机械观测**——由契约正交 lint 与步骤表静态检查收敛路径，行为层保留人审（§10 风险如实登记）。
+
 ### 五项检查（架构变更判定）
 
 依次检查以下五项，**全部为否** → `decision: skipped`；**任一为是** → `decision: required`：
@@ -111,25 +125,23 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 **流程**（不硬阻断，显式确认 + 登记 deviation）：
 1. **呈现变更摘要**：涉及的产品级决策 + 影响范围（引用快照章节）
 2. **用户确认**（阻塞问题工具）：接受 → 执行变更；拒绝 → 保持产品级定义，change 内走增量
-3. **登记 deviation**：确认后写入 `orchestrator.yaml` 的 `replan_log`（`seq/trigger: arch-deviation/before/after/approved_by`）+ 在 `iterations/vN/architecture.md` 演进日志追加修订记录（迭代收尾 S3.5 确认晋升）
+3. **登记 deviation**：确认后写入 `orchestrator.yaml` 的 `replan_log`（`seq/trigger: arch-deviation/before/after/approved_by`——**可机读唯一落点**）；**Rationale/Consequences 按 `references/adr-templates.md` 选型**（五模板；仅「难逆转 ∧ 无上下文会困惑 ∧ 真实权衡」三条件全满足才写完整 ADR，否则 replan_log 一行即可，防泛滥；**不另起 `docs/adr/`**，防双轨漂移）+ 在 `iterations/vN/architecture.md` 演进日志追加修订记录（迭代收尾 S3.5 确认晋升）
 4. **`new` 聚合 flag**：在 `iterations/vN/architecture.md` 聚合注册表标注 `[pending-promotion]`，待下一迭代产品级晋升
 
 ### 执行流程
 
 ```
 1. 读取输入（brief + plan + specs + 全局 ARCHITECTURE.md）——**Fast Path 裁剪为「brief + precheck 输出」**
-2. 执行五项检查
-3. 全部为否：
-   → decision: skipped
-   → reason: 简述不涉及架构变更的理由
-   → 返回结构化输出
+1.5 DDD 深度 advisory（领域复杂度三判据 → ddd_depth: full | lightweight；advisory，不影响 decision）
+2. 执行五项检查（ddd_depth: lightweight 分支**同样执行全部五项**，第 4/5 项不得短路）
+3. 全部为否 → decision: skipped + reason（不涉及架构变更）→ 返回结构化输出（含 ddd_depth）
 4. 任一为是：
    → decision: required
    → reason: 简述涉及的架构变更项
-   → 执行完整 4A+DDD 增量设计（F1-F8）
+   → 执行 4A+DDD 增量设计（F1-F8；ddd_depth: lightweight 时战术制品从简，API/DB 产出不减）
    → 产出 architecture/architecture.md + database.md + api.md
    → artifacts: 产出路径列表
-   → 返回结构化输出
+   → 返回结构化输出（含 ddd_depth）
 ```
 
 ### 结构化输出契约
@@ -137,6 +149,8 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 返回给 workflow-start 的结果**必须**包含以下字段：
 
 ```yaml
+ddd_depth: full | lightweight    # O1 advisory：与 decision **正交**——任意组合合法；
+                                 # 禁止从 lightweight 推导/默认出 skipped（契约正交 lint 锁定）
 decision: required | skipped
 reason: "..."                    # skipped 时：不涉及架构变更的理由
                                  # required 时：涉及的变更项摘要
@@ -146,6 +160,10 @@ artifacts:                       # required 时必填，skipped 时为空
   - architecture/api.md
 ```
 
+> **schema 正交（O1 判据①，规则文本 lint）**：`ddd_depth ∈ {full, lightweight}` 与 `decision ∈ {required, skipped}`
+> 同时存在、取值域独立、**任意组合合法**（lightweight+required / lightweight+skipped / full+required / full+skipped 全允许）——
+> schema 层**不得**出现 `lightweight → skipped` 的推导或默认值。该 lint 校验的是**我们写下的规则文本自洽**，不校验 LLM 实际判定（诚实边界见 advisory 段）。
+
 **职责边界**：architecture-design 负责**判断+产出**（五项检查判断是否涉及架构变更，涉及则产出架构设计文档），workflow-start 负责**reasonableness check + 状态写入**（确认判断合理性后写入 yaml）。
 
 ### 产出目录

package/skills/architecture-design/chapters/ch04-entity-to-aggregate.md

@@ -1,4 +1,4 @@
-# ch04 · 业务实体→聚合→限界上下文
+# ch04 · 业务实体→聚合→子域→限界上下文
 
 ## 业务实体（识别起点）
 - 定义：BA 流程中的**表证单书**（订单/合同/工单/客户档案/库存记录），是业务概念而非数据库表。
@@ -15,12 +15,23 @@
 - 事务边界：聚合内所有操作须在一个事务完成（如创建订单同时建头/行项目/算总价）。
 - **硬规则**：聚合仅存在于业务服务；数据服务（跨聚合查询分析）、技术服务（消息队列）**无聚合**。
 
-## 限界上下文 / Context Map（核心框架 F5）
-- 限界上下文=语义边界，对应 L3 应用服务；相关聚合组成上下文。
-- 同术语异义须显式映射（映射类型）：
-  - **Shared Kernel（共享内核）**：两上下文共享部分模型。
-  - **Anti-Corruption Layer（防腐层）**：下游翻译上游模型，防止概念泄漏。
-  - **Open Host Service（开放主机）**：上游暴露标准协议供多下游消费。
+## 子域（问题空间 · 投资分级）
+- **子域(Subdomain)**：业务问题空间的分区（Vernon《IDDD》），先于解空间存在；子域 → 限界上下文是**多对多映射**（一个 BC 常服务多个子域），不是 1:1。
+- **三分类**：**Core**（核心竞争力，深建模）/ **Supporting**（保障性，最小定制）/ **Generic**（通用能力，买或复用）——**分类驱动 BC 投资**。
+- **纪律**：子域描述只写**业务问题**，不列 service / 包名 / 类名（问题空间 ≠ 解空间；按实现载体划子域/BC 是已知失效模式，须人审）。
+
+## 限界上下文 / Context Map（核心框架 F5 · 经典 8 模式，O7）
+- 限界上下文=语义边界，对应 L3 应用服务；相关聚合组成上下文（**解空间，≠ 子域**）。
+- 同术语异义须显式映射——**8 模式全集**（与产品级模板 §1.2 同步，教 = 用）：
+  - **Separate Ways**：不集成（先问要不要集成再选型）。
+  - **Partnership**：对等团队共同演进、双向承诺。
+  - **Customer-Supplier**：供需协商契约。
+  - **Conformist**：下游全盘接受上游模型。
+  - **Open Host Service**：上游开放标准协议供多下游消费。
+  - **Anti-Corruption Layer**：下游翻译上游模型，防止概念泄漏。
+  - **Shared Kernel**：两上下文共享部分模型，变更须协商。
+  - **Published Language**：标准化语义词汇（与 OHS 天然配对）。
+- **决策流与 Mermaid 生成**：见 `references/context-map-8.md`（选型顺序 Separate Ways → Partnership → Customer-Supplier → Conformist → OHS+PL → ACL → Shared Kernel；CML DSL 导出 = NO-GO）。
 
 ## 应用提示
 - 每变更设计先画"涉及实体的活动对象矩阵"；再定聚合根与事务边界；最后落到全局 Context Map。