@xulthekl/team-flow 0.63.0 → 0.64.0

package/scripts/lib/cmd-execution.mjs

@@ -1,4 +1,6 @@
 import { parseArgs } from 'node:util';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { createPlan, describeWaves, EXECUTION_MODES, readPlan, recordReview, refreshPlanHash, validatePlan, writePlan } from './execution-plan.mjs';
 import {
   createRecommendationReceipt,
@@ -6,6 +8,7 @@ import {
   writeRecommendationReceipt,
 } from './execution-recommendation.mjs';
 import { readState, writeState } from './state-loader.mjs';
+import { parseTaskLine } from './md-normalize.mjs';
 
 const SUBCOMMANDS = ['recommend', 'plan', 'show', 'revise', 'review', 'refresh-hash'];
 
@@ -17,6 +20,8 @@ export async function run(args) {
       reason: { type: 'string' },
       wave: { type: 'string', multiple: true },
       confirm: { type: 'boolean', default: false },
+      // v0.64.0（实施计划 D7）：planned 前门的 tasks.md 派生通道——跳过 recommend/receipt 仪式
+      derive: { type: 'boolean', default: false },
       'acknowledge-recommendation': { type: 'boolean', default: false },
       base: { type: 'string' },
       head: { type: 'string' },
@@ -58,10 +63,47 @@ export async function run(args) {
   }
 }
 
+// v0.64.0（D7 派生）：tasks.md checkbox → 单 wave（serial），仅 planned --derive 通道使用
+function deriveWavesFromTasks(changeDir) {
+  const tasksPath = join(changeDir, 'tasks.md');
+  if (!existsSync(tasksPath)) throw new Error('--derive requires tasks.md (planned front door: proposal.md + tasks.md)');
+  const tasks = readFileSync(tasksPath, 'utf-8')
+    .split('\n')
+    .map(line => parseTaskLine(line)?.text)
+    .map(t => (typeof t === 'string' ? t.trim() : ''))
+    .filter(Boolean);
+  if (tasks.length === 0) throw new Error('tasks.md has no checkboxes to derive a plan from');
+  return [{ id: 'w1', strategy: 'serial', tasks, depends_on: [] }];
+}
+
 function createAndPrintPlan(changeDir, values, revise) {
-  requireMode(values.mode);
   requireOption(values.reason, '--reason');
   requireSafeReason(values.reason);
+  // planned 派生通道（v0.64.0 D7）：无 recommendation/receipt/selection——validatePlan 对
+  // workflow_variant=planned 豁免三件要求；state.execution_* 由 writeExecutionSummary 同步。
+  if (values.derive) {
+    if (revise) throw new Error('--derive creates the initial plan; use "tf execution revise" for revisions');
+    const st = readState(changeDir);
+    if (st.workflow_variant !== 'planned') {
+      throw new Error('--derive is only valid for the planned front door (workflow_variant=planned)');
+    }
+    if (!values.confirm) throw new Error('--derive requires --confirm');
+    const mode = values.mode || 'inline';
+    requireMode(mode);
+    const waves = values.wave?.length ? parseWaves(values.wave) : deriveWavesFromTasks(changeDir);
+    const plan = createPlan(changeDir, {
+      mode,
+      source: 'tasks-derived',
+      rationale: values.reason,
+      waves,
+    });
+    const saved = writePlan(changeDir, plan);
+    writeExecutionSummary(changeDir, saved);
+    print(values.json, { ok: true, plan: saved },
+      `Execution plan revision ${saved.revision} recorded (${saved.mode}, derived from tasks.md).`);
+    return;
+  }
+  requireMode(values.mode);
   const waves = parseWaves(values.wave);
   const existing = readPlan(changeDir);
   if (revise) {
@@ -236,6 +278,7 @@ function printHelp() {
   console.log(`Usage:
   tf execution recommend <dir> [--wave <id>:<strategy>:<task,...>[:<depends-on,...>]] [--json]
   tf execution plan <dir> --mode <mode> --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
+  tf execution plan <dir> --derive --confirm --reason <text> [--mode <mode>]   # planned only: derive single wave from tasks.md
   tf execution show <dir> [--json]
   tf execution revise <dir> --mode sdd --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
   tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail [--repo <path>] [--tests-total N --tests-passed N --tests-failed N]

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/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,9 @@ 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-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 +90,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/clean-code/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clean-code
-description: 代码结构质量判据 skill——可机械判定项阈值与计数口径、审查必答项、增量归因边界与共享层判定。
+description: 代码结构质量判据 skill——可机械判定项阈值与计数口径、审查必答项、增量归因边界与共享层判定。限 team-flow 实施/审查流程内（code-reviewer、clean-code 门禁）调用，普通编码会话不触发（v0.64.0 §3.8 收紧）。
 user-invocable: false
 ---
 

package/skills/jarvis/SKILL.md

@@ -16,6 +16,8 @@ description: This skill should be used when the user asks to "启动 Jarvis", "
 
 **核心边界**：Jarvis 只做决策与编排——**不写产线代码、不改 team-flow 状态文件（`.team-flow.yaml`）、不发明任务方向**。（「不改状态文件」专指 team-flow 的门禁真相源；Jarvis 自己的 `state/*.log|md` 当然要写。）
 
+**前门回显（v0.64.0）**：接管/恢复任何 team-flow change 时，简报须读取并回显 `workflow_variant`（direct/planned/legacy/null）——direct/planned **轻路径无 DP-0~7 决策点可代答**（代答权限表对该两档恒 N/A）；升档决策（`tf state upgrade`）属「挂起交 LT」类，不在代答权限内。
+
 > **与 firstmate 的分工**：Jarvis 是 **team-flow 专用**的决策代理，深度集成状态机 / 决策点 / 门禁；通用跨项目的「大副」角色由 firstmate 承担。两者不重叠——Jarvis 不做通用编码、调查或审计工作。
 
 > **命令形态以官方为准**：本文命令随 Orca 版本演进，**运行前先读一次** `orca skills get orchestration`，不要凭记忆推断子命令或参数——v0.60.0 实测暴露的 skill 缺陷之一即命令形态错误。