@xulthekl/team-flow 0.63.0 → 0.64.0

package/scripts/guard/checks/direct-test-result.mjs

@@ -0,0 +1,30 @@
+// scripts/guard/checks/direct-test-result.mjs — direct/lightweight 验证证据（§4.5 注记③）
+// v0.64.0：guard 只读 tf test record 程序化证据，绝不在 guard 进程内现场跑测试
+// （cmd-state spawnSync 10s 总超时会杀掉 guard，A-19）。证据机制与 tests-passing 同源。
+import fs from 'node:fs';
+import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { parseStructuredTestResult } from './tests-passing.mjs';
+
+const RECORD_HINT = 'run your verification command, then record it: tf test record <change-dir> --from <runner-output>';
+
+export function checkDirectTestResult(changeDir) {
+  const state = readState(changeDir);
+  const parsed = parseStructuredTestResult(state.test_result);
+  if (!parsed || parsed.verdict !== 'pass') {
+    return { pass: false, failures: [`no passing programmatic test evidence recorded — ${RECORD_HINT}`] };
+  }
+  if (parsed.total == null || parsed.total <= 0) {
+    return { pass: false, failures: [`recorded evidence has total=0 (empty-run rejected) — ${RECORD_HINT}`] };
+  }
+  if (!state.test_evidence_path) {
+    return { pass: false, failures: [`test_evidence_path missing — ${RECORD_HINT}`] };
+  }
+  const evidenceAbs = path.isAbsolute(state.test_evidence_path)
+    ? state.test_evidence_path
+    : path.join(changeDir, state.test_evidence_path);
+  if (!fs.existsSync(evidenceAbs)) {
+    return { pass: false, failures: [`evidence file not found: ${state.test_evidence_path} — ${RECORD_HINT}`] };
+  }
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/execution-plan-ready.mjs

@@ -7,7 +7,7 @@ import { readState } from '../../lib/state-loader.mjs';
  * A non-empty DP-4 field is not sufficient: it must name the current plan
  * revision, whose hashes, workflow, mode, and state summary remain current.
  */
-export function checkExecutionPlanReady(changeDir) {
+export function checkExecutionPlanReady(changeDir, ctx = {}) {
   const plan = readPlan(changeDir);
   if (!plan) {
     return {
@@ -21,6 +21,12 @@ export function checkExecutionPlanReady(changeDir) {
     return { pass: false, failures: validation.failures };
   }
 
+  // v0.64.0（§4.5 注记⑤，R2 兼容性修复）：planned 无 DP-4——豁免 DP-4 revision 精确引用，
+  // 判据 = plan 存在 + validatePlan 通过（内嵌 hash 与制品一致）。
+  if (ctx.variant === 'planned') {
+    return { pass: true, failures: [], reason: 'planned variant: DP-4 reference waived; plan file + hash validation suffice' };
+  }
+
   const state = readState(changeDir);
   const expectedRevision = `plan revision ${plan.revision}`;
   const decision = typeof state.dp_4_result === 'string' ? state.dp_4_result : '';

package/scripts/guard/checks/execution-reviews-passed-light.mjs

@@ -0,0 +1,28 @@
+// scripts/guard/checks/execution-reviews-passed-light.mjs — planned 一次最终审查（§4.5）
+// v0.64.0（A-05①）：planned 无波次无逐波 receipt——判据 = 关门前存在非空（≥5 非空行）
+// 最终审查记录 final-review.md；内容最低契约（B-01）防空文件桩。
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MIN_LINES = 5;
+
+export function checkExecutionReviewsPassedLight(changeDir) {
+  const p = join(changeDir, 'final-review.md');
+  if (!existsSync(p)) {
+    return {
+      pass: false,
+      failures: [
+        'final-review.md missing — planned path requires ONE final review before closing '
+        + '(record verdict, scope, and findings; ≥5 lines)',
+      ],
+    };
+  }
+  const lines = readFileSync(p, 'utf-8').split('\n').filter(l => l.trim()).length;
+  if (lines < MIN_LINES) {
+    return {
+      pass: false,
+      failures: [`final-review.md too thin (${lines} non-empty lines, need ≥${MIN_LINES}) — record verdict + scope + findings`],
+    };
+  }
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/lightweight-completion-evidence.mjs

@@ -0,0 +1,27 @@
+// scripts/guard/checks/lightweight-completion-evidence.mjs — lightweight 档完成证据（§4.5）
+// v0.64.0：类 direct-test-result——证据文件须存在且非空（独立于 test_result 解析，
+// 兜住「test_result 被清但文件还在」与「文件被删但记录还在」两种漂移）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+
+export function checkLightweightCompletionEvidence(changeDir) {
+  const state = readState(changeDir);
+  if (!state.test_evidence_path) {
+    return {
+      pass: false,
+      failures: ['completion evidence missing: test_evidence_path is null — record verification via tf test record before closing'],
+    };
+  }
+  const abs = path.isAbsolute(state.test_evidence_path)
+    ? state.test_evidence_path
+    : path.join(changeDir, state.test_evidence_path);
+  if (!fs.existsSync(abs)) {
+    return { pass: false, failures: [`completion evidence file not found: ${state.test_evidence_path}`] };
+  }
+  const content = fs.readFileSync(abs, 'utf-8').trim();
+  if (!content) {
+    return { pass: false, failures: [`completion evidence file is empty: ${state.test_evidence_path}`] };
+  }
+  return { pass: true, failures: [] };
+}

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

@@ -34,11 +34,35 @@ function hasDeltaSpecs(changeDir) {
  * Passes when either spec_merged is recorded, or there are no delta specs to merge.
  * Blocks `executing → closing` when delta specs exist but spec-merger hasn't run.
  */
-export function checkSpecsMerged(changeDir) {
+export function checkSpecsMerged(changeDir, ctx = {}) {
   const state = readState(changeDir);
   if (state.spec_merged === true || state.spec_merged === 'true') {
     return { pass: true, failures: [] };
   }
+  // v0.64.0（§4.5 注记⑦，B-02）：planned 轻语义——无 specs/ 目录即过；
+  // 有 specs/ 但无 delta 头 = 手写完整形态 specs 永不合并 → FAIL（补 delta 头或移除）。
+  if (ctx.variant === 'planned') {
+    const specsDir = join(changeDir, 'specs');
+    if (!existsSync(specsDir)) {
+      return { pass: true, failures: [], reason: 'planned: no specs/ dir — merge N/A' };
+    }
+    if (!hasDeltaSpecs(changeDir)) {
+      return {
+        pass: false,
+        failures: [
+          'specs/ exists but no ## ADDED/MODIFIED/REMOVED/RENAMED Requirements delta headers — '
+          + 'full-form specs would never merge; add delta headers (then spec-merger) or remove specs/',
+        ],
+      };
+    }
+    // 有 delta 头但未合并 → 落到下方统一失败
+    return {
+      pass: false,
+      failures: [
+        'Delta specs exist in specs/ but spec-merger has not run (spec_merged not recorded). Run spec-merger to merge ADDED/MODIFIED/REMOVED/RENAMED requirements before closing.',
+      ],
+    };
+  }
   if (!hasDeltaSpecs(changeDir)) {
     return { pass: true, failures: [] };
   }

package/scripts/guard/checks/test-matrix-complete.mjs

@@ -19,7 +19,7 @@ import {
 /**
  * Returns { pass, failures[], reason? }.
  */
-export function checkTestMatrixComplete(changeDir) {
+export function checkTestMatrixComplete(changeDir, ctx = {}) {
   const state = readState(changeDir);
 
   // Step 1 — legacy：v0.32.0 之前初始化的 change（无 schema_version 打戳）保留旧行为。
@@ -40,6 +40,32 @@ export function checkTestMatrixComplete(changeDir) {
     return { pass: true, failures: [], reason: `explicitly skipped: ${state.test_matrix_skip_reason}` };
   }
 
+  // v0.64.0（§4.5 注记②，D4 无契约轻量判据）：direct/planned/quick/lightweight
+  // 无契约 → 跳过 Step 3 契约声明检查；矩阵存在非空 +（若已记录）hash 一致即可。
+  const isLight = ctx.variant === 'direct' || ctx.variant === 'planned'
+    || ctx.workflow === 'quick' || ctx.workflow === 'lightweight';
+  if (isLight) {
+    const matrix = readTestMatrixFile(changeDir);
+    if (!matrix.exists || matrix.empty) {
+      return {
+        pass: false,
+        failures: [
+          !matrix.exists
+            ? 'test-matrix.md missing — light path requires the matrix file itself (no contract)'
+            : 'test-matrix.md is empty — must contain at least a Summary section and Cases table',
+          'or skip explicitly: tf state set <dir> test_matrix_skipped true + test_matrix_skip_reason "<reason>"',
+        ],
+      };
+    }
+    if (state.test_matrix_hash) {
+      const computedLight = computeTestMatrixHash(changeDir);
+      if (computedLight !== state.test_matrix_hash) {
+        return { pass: false, failures: ['test-matrix.md changed since recorded hash — run tf state rebuild'] };
+      }
+    }
+    return { pass: true, failures: [] };
+  }
+
   // Step 3 — 非存量 change 的契约必须声明矩阵（v0.13：内容型豁免删除）。
   const contract = contractDeclaresTestMatrix(changeDir);
   if (!contract.exists) {

package/scripts/guard/checks/test-matrix-ready.mjs

@@ -17,7 +17,7 @@ import {
 /**
  * Returns { pass, failures[], reason? }.
  */
-export function checkTestMatrixReady(changeDir) {
+export function checkTestMatrixReady(changeDir, ctx = {}) {
   const state = readState(changeDir);
 
   // Exemption 1：legacy change（v0.32.0 之前初始化，无 schema_version 打戳）。
@@ -25,6 +25,33 @@ export function checkTestMatrixReady(changeDir) {
     return { pass: true, failures: [], reason: 'legacy change — initialized before v0.32.0' };
   }
 
+  // v0.64.0（§4.5 注记②，D4 无契约轻量判据）：direct/planned/quick/lightweight
+  // 无 execution-contract——判据降为「test-matrix.md 存在非空 OR 显式 skip 附理由」，
+  // 不要求契约声明段。skip 仍须附理由（拒 state set 自清为常规通过路径）。
+  const isLight = ctx.variant === 'direct' || ctx.variant === 'planned'
+    || ctx.workflow === 'quick' || ctx.workflow === 'lightweight';
+  if (isLight) {
+    if (state.test_matrix_skipped === 'true') {
+      if (skipMissingReason(state)) {
+        return { pass: false, failures: [SKIP_REASON_HINT] };
+      }
+      return { pass: true, failures: [], reason: `explicitly skipped: ${state.test_matrix_skip_reason}` };
+    }
+    const matrix = readTestMatrixFile(changeDir);
+    if (matrix.exists && !matrix.empty) {
+      return { pass: true, failures: [] };
+    }
+    return {
+      pass: false,
+      failures: [
+        matrix.exists
+          ? 'test-matrix.md is empty — add a Summary + Cases table (light path has no contract section)'
+          : 'test-matrix.md missing — create it (light path: matrix file alone is sufficient, no contract needed)',
+        'or skip explicitly: tf state set <dir> test_matrix_skipped true + test_matrix_skip_reason "<reason>"',
+      ],
+    };
+  }
+
   // Exemption 2：显式 skip（必须附理由）。
   if (state.test_matrix_skipped === 'true') {
     // v2.1 §6.3 skip 禁令：glaf4-delegation 模式禁止 skip（唯一例外 TEST_BOOTSTRAP）

package/scripts/guard/checks/test-merged-light.mjs

@@ -0,0 +1,36 @@
+// scripts/guard/checks/test-merged-light.mjs — 测试台账轻回写（§4，横展发现的同型全局态）
+// v0.64.0：无测试触碰 → 过；有 → docs/test-ledger/** 须含归因 change:<name>
+//（写入走 tf test-merge --light，同 sink 同 rewriteIndex 单写入口）。
+import { readState } from '../../lib/state-loader.mjs';
+import { scanArchitectureSurface } from '../../lib/surface-scan.mjs';
+import { filesContainDir } from './_fs-utils.mjs';
+import { join } from 'node:path';
+
+export function checkTestMergedLight(changeDir) {
+  const state = readState(changeDir);
+  const changeName = state.change_name || changeDir.split('/').filter(Boolean).pop();
+  const scan = scanArchitectureSurface(changeDir, state);
+
+  if (scan.error === 'no-baseline' || scan.error === 'diff-failed') {
+    return { pass: false, failures: [`surface scan failed (${scan.error}) — cannot determine touched tests, fail-closed`] };
+  }
+  if (scan.error === 'aggregate-list-missing') {
+    // 测试判定不依赖聚合清单——降级为仅用文件清单分类（清单缺失不阻塞本维度）
+    // 但 scanArchitectureSurface 在清单缺失时不返回 files……此时保守 FAIL：
+    return { pass: false, failures: ['aggregate list missing (.team-flow/aggregate-dirs.txt) — shared scan precondition unmet, fail-closed'] };
+  }
+
+  if (scan.testFiles.length === 0) {
+    return { pass: true, failures: [], reason: 'no test files touched — test ledger writeback N/A' };
+  }
+
+  const ledger = join(scan.projectRoot, 'docs', 'test-ledger');
+  const anchor = `change:${changeName}`;
+  if (filesContainDir(ledger, anchor) || filesContainDir(ledger, changeName)) {
+    return { pass: true, failures: [] };
+  }
+  return {
+    pass: false,
+    failures: [`tests touched but docs/test-ledger/** has no '${anchor}' entry — run: tf test-merge --light <change-dir>`],
+  };
+}

package/scripts/guard/guard.mjs

@@ -21,6 +21,18 @@ import { checkArchReadiness } from './checks/arch-readiness.mjs';
 import { checkArchSnapshot } from './checks/arch-snapshot.mjs';
 import { checkArchMerged } from './checks/arch-merged.mjs';
 import { checkDelegationStatus } from './checks/delegation-status.mjs';
+// v0.64.0 P1（spec-superflow 2.0 实施计划 §4.5）：direct/planned/lightweight 短路径与轻量全局态闸门
+import { checkDirectShortPath } from './checks/direct-short-path.mjs';
+import { checkDirectTestResult } from './checks/direct-test-result.mjs';
+import { checkLightweightCompletionEvidence } from './checks/lightweight-completion-evidence.mjs';
+import { checkArtifactsPlanned } from './checks/artifacts-planned.mjs';
+import { checkArchDesignLight } from './checks/arch-design-light.mjs';
+import { checkArchSnapshotLight } from './checks/arch-snapshot-light.mjs';
+import { checkArchMergedLight } from './checks/arch-merged-light.mjs';
+import { checkCompoundWritebackLight } from './checks/compound-writeback-light.mjs';
+import { checkTestMergedLight } from './checks/test-merged-light.mjs';
+import { checkCrossChangeConsistencyLight } from './checks/cross-change-consistency-light.mjs';
+import { checkExecutionReviewsPassedLight } from './checks/execution-reviews-passed-light.mjs';
 
 // Transition matrix: <from>:<to> → required check dimensions
 const TRANSITION_CHECKS = {
@@ -113,12 +125,52 @@ const WORKFLOW_TRANSITION_CHECKS = {
 
 const TRANSITION_WORKFLOW_REQUIREMENTS = {
   'exploring:bridging': ['hotfix'],
-  'exploring:approved-for-build': ['tweak'],
+  // v0.64.0（§4.5 注记①）：quick/lightweight 短路径 + planned（full 变体）共用该捷径；
+  // checkWorkflowAllowed 经 variant 参数放行 planned。
+  'exploring:approved-for-build': ['tweak', 'quick', 'lightweight'],
 };
 
-function checkWorkflowAllowed(key, workflow) {
+// v0.64.0（§4.5①）：direct / lightweight 短路径维度表。
+// 必须显式列出关键跳——未列出的 key 会回落 full 基表（contract-fresh 等对轻路径恒 FAIL）。
+const QUICK_TRANSITION_CHECKS = {
+  quick: {
+    'exploring:approved-for-build': ['direct-short-path'],
+    'approved-for-build:executing': ['direct-short-path', 'test-matrix-ready'],
+    'executing:closing': ['direct-short-path', 'direct-test-result', 'test-matrix-complete'],
+    'executing:debugging': [],
+    'debugging:executing': ['direct-test-result'],
+  },
+  lightweight: {
+    'exploring:approved-for-build': ['direct-short-path'],
+    'approved-for-build:executing': ['direct-short-path', 'test-matrix-ready'],
+    'executing:closing': ['direct-short-path', 'direct-test-result', 'lightweight-completion-evidence', 'test-matrix-complete'],
+    'executing:debugging': [],
+    'debugging:executing': ['direct-test-result'],
+  },
+};
+
+// v0.64.0（§4.5②）：planned（workflow=full + variant=planned）维度表。
+// 无契约/无 DP-3/无逐波审查；回写四灯 + 最终审查 + 测试矩阵在 closing 一次性收口。
+const PLANNED_TRANSITION_CHECKS = {
+  // 注：不挂 schema-valid——该 checker 强制 canonical specs/<capability>/spec.md，
+  // 与 planned「specs 按需」冲突（P1 实测修正，同步方案 §4.5）；反空壳由 artifacts-planned
+  // （proposal≥10 行 + checkbox）+ 最终审查内容契约承担。
+  'exploring:approved-for-build': ['artifacts-planned'],
+  'approved-for-build:executing': ['execution-plan-ready', 'test-matrix-ready'],
+  'executing:closing': [
+    'execution-plan-ready', 'execution-reviews-passed-light', 'test-matrix-complete',
+    'tests-passing', 'arch-merged-light', 'compound-writeback-light', 'test-merged-light',
+    'cross-change-consistency-light', 'delegation-status', 'specs-merged', 'tasks-complete',
+  ],
+  'executing:debugging': [],
+  'debugging:executing': ['execution-plan-ready', 'tests-passing'],
+};
+
+function checkWorkflowAllowed(key, workflow, variant) {
   const allowed = TRANSITION_WORKFLOW_REQUIREMENTS[key];
   if (!allowed || allowed.includes(workflow)) return { pass: true, checks: [] };
+  // planned（full 变体）走同一捷径，但其维度由 PLANNED 表管辖（§4.5）
+  if (variant === 'planned' && key === 'exploring:approved-for-build') return { pass: true, checks: [] };
   return {
     pass: false,
     checks: [{
@@ -129,7 +181,19 @@ function checkWorkflowAllowed(key, workflow) {
   };
 }
 
-function resolveDimensions(key, workflow) {
+function resolveDimensions(key, workflow, opts = {}) {
+  const { variant, plannedArch } = opts;
+  if (workflow === 'full' && variant === 'planned') {
+    let dims = PLANNED_TRANSITION_CHECKS[key] ?? TRANSITION_CHECKS[key];
+    // G3：planned_arch=true 时在规划段追加轻架构两维（§4.5 条件行）
+    if (plannedArch && (key === 'exploring:approved-for-build' || key === 'approved-for-build:executing')) {
+      dims = [...dims, 'arch-design-light', 'arch-snapshot-light'];
+    }
+    return dims;
+  }
+  if (workflow === 'quick' || workflow === 'lightweight') {
+    return QUICK_TRANSITION_CHECKS[workflow]?.[key] ?? TRANSITION_CHECKS[key];
+  }
   return WORKFLOW_TRANSITION_CHECKS[workflow]?.[key] ?? TRANSITION_CHECKS[key];
 }
 
@@ -138,13 +202,16 @@ async function main() {
     options: {
       json: { type: 'boolean', default: false },
       workflow: { type: 'string', default: 'full' },
+      // v0.64.0 P1：cmd-state 透传的前门变体（§4.5 注记①）
+      'workflow-variant': { type: 'string', default: '' },
+      'planned-arch': { type: 'string', default: '' },
     },
     allowPositionals: true,
   });
 
   const subcommand = positionals[0];
   if (subcommand !== 'check') {
-    console.error('Usage: guard.mjs check <change-dir> <from-state> <to-state> [--json] [--workflow <mode>]');
+    console.error('Usage: guard.mjs check <change-dir> <from-state> <to-state> [--json] [--workflow <mode>] [--workflow-variant <direct|planned|legacy>] [--planned-arch true]');
     process.exit(2);
   }
 
@@ -153,20 +220,27 @@ async function main() {
   const toState = positionals[3];
   const useJson = values.json;
   const workflow = values.workflow;
+  const workflowVariant = values['workflow-variant'] || null;
+  const plannedArch = values['planned-arch'] === 'true';
 
-  const VALID_WORKFLOWS = ['full', 'hotfix', 'tweak'];
+  // F1 校正（§3.3）：加 quick/lightweight——direct/planned 是 variant 不是 workflow 值
+  const VALID_WORKFLOWS = ['full', 'hotfix', 'tweak', 'quick', 'lightweight'];
   if (!VALID_WORKFLOWS.includes(workflow)) {
     console.error(`Invalid workflow: ${workflow}. Must be one of: ${VALID_WORKFLOWS.join(', ')}`);
     process.exit(2);
   }
+  if (workflowVariant && !['direct', 'planned', 'legacy'].includes(workflowVariant)) {
+    console.error(`Invalid workflow variant: ${workflowVariant}. Must be one of: direct, planned, legacy`);
+    process.exit(2);
+  }
 
   if (!changeDir || !fromState || !toState) {
-    console.error('Usage: guard.mjs check <change-dir> <from-state> <to-state> [--json]');
+    console.error('Usage: guard.mjs check <change-dir> <from-state> <to-state> [--json] [--workflow <mode>] [--workflow-variant <direct|planned|legacy>] [--planned-arch true]');
     process.exit(2);
   }
 
   const key = `${fromState}:${toState}`;
-  const dimensions = resolveDimensions(key, workflow);
+  const dimensions = resolveDimensions(key, workflow, { variant: workflowVariant, plannedArch });
 
   if (!dimensions) {
     const valid = Object.keys(TRANSITION_CHECKS).join(', ');
@@ -176,7 +250,7 @@ async function main() {
     process.exit(1);
   }
 
-  const workflowCheck = checkWorkflowAllowed(key, workflow);
+  const workflowCheck = checkWorkflowAllowed(key, workflow, workflowVariant);
   if (!workflowCheck.pass) {
     if (useJson) {
       console.log(JSON.stringify({ pass: false, checks: workflowCheck.checks }, null, 2));
@@ -198,6 +272,10 @@ async function main() {
     process.exit(0);
   }
 
+  // 变体上下文：需要 variant/plannedArch 的 runner（test-matrix-*、execution-plan-ready、
+  // specs-merged、direct-short-path 的轻量分支）从闭包 CTX 读取，保持 runner(dir) 签名兼容。
+  const CTX = { workflow, variant: workflowVariant, plannedArch };
+
   const CHECK_RUNNERS = {
     'artifacts-exist': (dir) => checkArtifactsExist(dir),
     'schema-valid': async (dir) => (await import('./checks/schema-valid.mjs')).checkSchemaValid(dir),
@@ -205,20 +283,32 @@ async function main() {
     'contract-current': (dir) => checkContractCurrent(dir),
     'tasks-complete': (dir) => checkTasksComplete(dir),
     'tests-passing': (dir) => checkTestsPassing(dir),
-    'specs-merged': (dir) => checkSpecsMerged(dir),
+    'specs-merged': (dir) => checkSpecsMerged(dir, CTX),
     'dp-gate-passed': (dir) => checkDpGate(dir, fromState, toState),
     'dp3-approved': (dir) => checkDp3Approved(dir),
-    'execution-plan-ready': (dir) => checkExecutionPlanReady(dir),
+    'execution-plan-ready': (dir) => checkExecutionPlanReady(dir, CTX),
     'execution-reviews-passed': (dir) => checkExecutionReviewsPassed(dir),
     'arch-design': (dir) => checkArchDesign(dir),
     'compound-captured': (dir) => checkCompoundCaptured(dir),
-    'test-matrix-complete': (dir) => checkTestMatrixComplete(dir),
-    'test-matrix-ready': (dir) => checkTestMatrixReady(dir),
+    'test-matrix-complete': (dir) => checkTestMatrixComplete(dir, CTX),
+    'test-matrix-ready': (dir) => checkTestMatrixReady(dir, CTX),
     'gates-probed': (dir) => checkGatesProbed(dir),
     'arch-readiness': (dir) => checkArchReadiness(dir),
     'arch-snapshot': (dir) => checkArchSnapshot(dir),
     'arch-merged': (dir) => checkArchMerged(dir),
     'delegation-status': (dir) => checkDelegationStatus(dir),
+    // v0.64.0 P1（§3.3 清单，11 个新 runner）
+    'direct-short-path': (dir) => checkDirectShortPath(dir, CTX),
+    'direct-test-result': (dir) => checkDirectTestResult(dir),
+    'lightweight-completion-evidence': (dir) => checkLightweightCompletionEvidence(dir),
+    'artifacts-planned': (dir) => checkArtifactsPlanned(dir),
+    'arch-design-light': (dir) => checkArchDesignLight(dir),
+    'arch-snapshot-light': (dir) => checkArchSnapshotLight(dir),
+    'arch-merged-light': (dir) => checkArchMergedLight(dir),
+    'compound-writeback-light': (dir) => checkCompoundWritebackLight(dir),
+    'test-merged-light': (dir) => checkTestMergedLight(dir),
+    'cross-change-consistency-light': (dir) => checkCrossChangeConsistencyLight(dir),
+    'execution-reviews-passed-light': (dir) => checkExecutionReviewsPassedLight(dir),
   };
 
   const checks = [];

package/scripts/infer-workflow.mjs

@@ -57,11 +57,14 @@ function inferMode(changeDir) {
   const state = readState(changeDir);
 
   // Explicit override: honor any non-auto, non-null workflow value
+  // v0.64.0（§3.2 F1）：VALID_WORKFLOWS 扩为五值，quick/lightweight 亦为合法显式档位。
   if (state.workflow && state.workflow !== 'auto') {
-    const valid = ['hotfix', 'tweak', 'full'];
+    const valid = ['hotfix', 'tweak', 'full', 'quick', 'lightweight'];
     if (valid.includes(state.workflow)) {
       return {
         mode: state.workflow,
+        // 双通道（§3.2）：显式 workflow 已定时不再建议前门（显式 > 推断）
+        suggested_path: null,
         explicit: true,
         reason: `workflow explicitly set to '${state.workflow}' in .team-flow.yaml; skipping auto-detection`,
       };
@@ -85,6 +88,20 @@ function inferMode(changeDir) {
     '新增 capability', 'new capability',
   ]);
 
+  // v0.64.0（§3.2 双通道）：前门建议信号。
+  // hasSchemaChange 已含 api/schema/接口 关键词（F-06 去重：不新建同词判定）；
+  // arch/aggregate/cross_module/uncertainty 为净新增信号（现状 infer 无）。
+  const hasArchAggregate = hasKeyword(combined, [
+    '聚合', 'aggregate', 'architecture', '架构', '限界上下文', 'bounded context', 'cqrs',
+  ]);
+  const hasCrossModule = hasKeyword(combined, [
+    'cross-module', '跨模块', '跨服务', 'multi-repo', '多仓',
+  ]);
+  // 架构 surface 信号 → 建议 planned（轻架构）；不再直接推 full（D1）
+  const archPathSignal = hasSchemaChange || hasArchAggregate;
+  // 跨模块 / 高不确定性 → full（D1：full 只留重场景）
+  const fullSignal = hasCrossModule || (taskCount > 4 && fileCount > 6);
+
   const allExts = files.map(f => {
     const parts = f.split('.');
     return parts[parts.length - 1].toLowerCase();
@@ -96,6 +113,7 @@ function inferMode(changeDir) {
   if (taskCount === 0 && fileCount === 0) {
     return {
       mode: 'full',
+      suggested_path: null,
       explicit: false,
       reason: 'no planning artifacts detected → full (safe default)',
     };
@@ -105,8 +123,9 @@ function inferMode(changeDir) {
   if (taskCount <= 2 && fileCount <= 2 && !hasSchemaChange && !hasNewModule) {
     return {
       mode: 'hotfix',
+      suggested_path: 'direct',
       explicit: false,
-      reason: `≤2 tasks, ≤2 files, no schema/API/new-module keywords → hotfix`,
+      reason: `≤2 tasks, ≤2 files, no schema/API/new-module keywords → hotfix (trivial → suggest path direct; hotfix retained when reusing an existing contract)`,
     };
   }
 
@@ -114,16 +133,28 @@ function inferMode(changeDir) {
   if (taskCount <= 4 && configDocOnly && !hasSchemaChange && !hasNewModule) {
     return {
       mode: 'tweak',
+      suggested_path: 'direct',
+      explicit: false,
+      reason: `≤4 tasks, only config/doc files, no schema/API/new-module keywords → tweak (trivial → suggest path direct)`,
+    };
+  }
+
+  // Arch/API/DB/聚合信号 → 建议 planned（轻架构）而非 full（§3.2 D1 修正）
+  if (archPathSignal && !fullSignal) {
+    return {
+      mode: 'full',
+      suggested_path: 'planned',
       explicit: false,
-      reason: `≤4 tasks, only config/doc files, no schema/API/new-module keywords → tweak`,
+      reason: `${taskCount} tasks, ${fileCount} files${hasSchemaChange ? ', schema/API change detected' : ''}${hasArchAggregate ? ', arch/aggregate keywords detected' : ''} → suggest path planned (light architecture); front door: workflow start --path planned (new change) or tf state upgrade <dir> planned (existing change)`,
     };
   }
 
   // Default
   return {
     mode: 'full',
+    suggested_path: null,
     explicit: false,
-    reason: `${taskCount} tasks, ${fileCount} files${codeFileCount > 0 ? ` (${codeFileCount} code files)` : ''}${hasSchemaChange ? ', schema/API change detected' : ''}${hasNewModule ? ', new module detected' : ''} → full`,
+    reason: `${taskCount} tasks, ${fileCount} files${codeFileCount > 0 ? ` (${codeFileCount} code files)` : ''}${hasSchemaChange ? ', schema/API change detected' : ''}${hasNewModule ? ', new module detected' : ''}${hasCrossModule ? ', cross-module detected' : ''} → full`,
   };
 }
 

package/scripts/lib/arch-merge.mjs

@@ -584,16 +584,29 @@ function updateIndex(globalArchDir, changeName) {
 
 /* ============ Step 1: 预检 ============ */
 
-function preCheck(changeDir, archDir, projectRoot) {
+function preCheck(changeDir, archDir, projectRoot, light = false) {
   const conflicts = [];
   if (!existsSync(archDir)) {
     return { pass: false, conflicts: ['architecture/ directory not found in change'] };
   }
-  for (const f of ['architecture.md', 'database.md', 'api.md']) {
+  // v0.64.0（§4 D8，--light）：light 模式持久源只要求 architecture.md（聚合注册行 +
+  // 演进日志段 = marker 区投影唯一输入）；api.md/database.md 触及时才要求（调用方按
+  // touched surface 判定，此处仅对已存在文件做非空校验——缺失即该 sink 无增量，
+  // 生成式重建会安全保留旧表而非抹除）。full 模式维持三件套硬要求。
+  const required = light ? ['architecture.md'] : ['architecture.md', 'database.md', 'api.md'];
+  for (const f of required) {
     const fp = join(archDir, f);
     if (!existsSync(fp)) conflicts.push(`architecture/${f} missing`);
     else if (readFileSync(fp, 'utf-8').trim().length === 0) conflicts.push(`architecture/${f} empty`);
   }
+  if (light) {
+    for (const f of ['database.md', 'api.md']) {
+      const fp = join(archDir, f);
+      if (existsSync(fp) && readFileSync(fp, 'utf-8').trim().length === 0) {
+        conflicts.push(`architecture/${f} empty (present but blank — delete it or fill the delta)`);
+      }
+    }
+  }
   return { pass: conflicts.length === 0, conflicts };
 }
 
@@ -705,6 +718,7 @@ export function run(args = {}) {
     for (let i = 0; i < args.length; i++) {
       if (args[i] === '--project-root' && args[i + 1] && !args[i + 1].startsWith('--')) parsed.projectRoot = args[++i];
       else if (args[i] === '--dry-run') parsed.dryRun = true;
+      else if (args[i] === '--light') parsed.light = true;
       else if (!args[i].startsWith('--')) parsed._.push(args[i]);
     }
     args = parsed;
@@ -712,8 +726,9 @@ export function run(args = {}) {
 
   const changeDir = args._?.[0] || args.changeDir;
   const dryRun = args.dryRun || false;
+  const light = args.light || false; // v0.64.0 §4 D8：planned 轻回写入口
   if (!changeDir) {
-    console.error('Usage: tf arch-merge <change-dir> [--project-root <path>] [--dry-run]');
+    console.error('Usage: tf arch-merge <change-dir> [--project-root <path>] [--dry-run] [--light]');
     process.exit(1);
   }
 
@@ -733,6 +748,7 @@ export function run(args = {}) {
   console.log(`  Source: ${archDir}`);
   console.log(`  Target: ${globalArchDir}`);
   if (dryRun) console.log(`  Mode: DRY-RUN`);
+  if (light) console.log(`  Mode: LIGHT（minimal persistent source: architecture.md + present deltas；同 sink 同生成器）`);
 
   // 写锁（硬门禁 3）
   const lockPath = acquireLock(projectRoot);
@@ -740,7 +756,7 @@ export function run(args = {}) {
     if (!existsSync(globalArchDir)) makeDir(globalArchDir);
 
     // Step 1: 预检
-    const preCheckResult = preCheck(changeDir, archDir, projectRoot);
+    const preCheckResult = preCheck(changeDir, archDir, projectRoot, light);
     if (!preCheckResult.pass) {
       console.error('  Pre-check FAILED:');
       for (const c of preCheckResult.conflicts) console.error(`    - ${c}`);