@xulthekl/team-flow 0.63.0 → 0.65.0

package/scripts/guard/checks/cross-change-consistency-light.mjs

@@ -0,0 +1,75 @@
+// scripts/guard/checks/cross-change-consistency-light.mjs — 跨 change 冲突确定性初筛（§3.3）
+// v0.64.0（A-14/S-07 重定义）：guard runner 是 10s 内确定性 Node 函数，**不能调 LLM agent**。
+// 本 runner 做机械初筛：其他在途 change（state ∈ executing/debugging/approved-for-build）
+// 的 minimal api.md 端点路径 / architecture.md 聚合行 与本 change 的最小源求交——
+// 交集非空 = 共享 surface 冲突。语义级冲突由 release-archivist 关门序列派发
+// cross-change-consistency-checker agent 兜底（分工见 §3.3）。
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import { findProjectRoot } from '../../lib/surface-scan.mjs';
+
+const IN_FLIGHT = new Set(['approved-for-build', 'executing', 'debugging']);
+
+function extractApiPaths(file) {
+  if (!existsSync(file)) return new Set();
+  const text = readFileSync(file, 'utf-8');
+  // 端点表单元格里的路径 token（/api/xxx、/v1/xxx、{id} 形态）
+  const out = new Set();
+  for (const m of text.matchAll(/(\/[A-Za-z0-9_\-{}./]+)/g)) {
+    const p = m[1];
+    if (p.length > 1 && !p.endsWith('.md')) out.add(p.replace(/\/+$/, ''));
+  }
+  return out;
+}
+
+function extractAggregateNames(file) {
+  if (!existsSync(file)) return new Set();
+  const text = readFileSync(file, 'utf-8');
+  const out = new Set();
+  for (const m of text.matchAll(/聚合[：:\s*`]+[`*]*([A-Za-z][A-Za-z0-9_\-]*)/g)) out.add(m[1]);
+  return out;
+}
+
+export function checkCrossChangeConsistencyLight(changeDir) {
+  const state = readState(changeDir);
+  const projectRoot = findProjectRoot(changeDir);
+  const changesDir = join(projectRoot, 'changes');
+  if (!existsSync(changesDir)) return { pass: true, failures: [], reason: 'no changes/ dir' };
+
+  const selfName = state.change_name || basename(changeDir);
+  const selfApi = extractApiPaths(join(changeDir, 'architecture', 'api.md'));
+  const selfAgg = extractAggregateNames(join(changeDir, 'architecture', 'architecture.md'));
+
+  const conflicts = [];
+  for (const entry of readdirSync(changesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === selfName) continue;
+    const otherDir = join(changesDir, entry.name);
+    const otherStatePath = join(otherDir, '.team-flow.yaml');
+    if (!existsSync(otherStatePath)) continue;
+    const other = readState(otherDir);
+    if (!IN_FLIGHT.has(other.state)) continue;
+
+    const otherApi = extractApiPaths(join(otherDir, 'architecture', 'api.md'));
+    const otherAgg = extractAggregateNames(join(otherDir, 'architecture', 'architecture.md'));
+
+    const apiOverlap = [...selfApi].filter(p => otherApi.has(p));
+    const aggOverlap = [...selfAgg].filter(a => otherAgg.has(a));
+    if (apiOverlap.length || aggOverlap.length) {
+      conflicts.push(
+        `${entry.name}: api=[${apiOverlap.slice(0, 5).join(', ')}] aggregates=[${aggOverlap.slice(0, 5).join(', ')}]`
+      );
+    }
+  }
+
+  if (conflicts.length) {
+    return {
+      pass: false,
+      failures: [
+        `shared surface conflicts with in-flight change(s):\n    ${conflicts.join('\n    ')} `
+        + '— resolve ownership or stagger closing; semantic-level review via cross-change-consistency-checker agent',
+      ],
+    };
+  }
+  return { pass: true, failures: [] };
+}

package/scripts/guard/checks/direct-short-path.mjs

@@ -0,0 +1,52 @@
+// scripts/guard/checks/direct-short-path.mjs — direct/lightweight 短路径 + 架构 surface 扫描
+// v0.64.0（实施计划 §4，G1 加固）：
+// - 挂 quick/lightweight 的 exploring→approved-for-build / approved-for-build→executing / closing
+// - G4 前提保障：无架构 surface（API/DB/聚合）→ 过（真琐碎零负担）
+// - 命中架构 surface → FAIL 并给升级指引（禁止静默过）；扫描失败/清单缺失一律 fail-closed
+import { readState } from '../../lib/state-loader.mjs';
+import { scanArchitectureSurface } from '../../lib/surface-scan.mjs';
+
+const UPGRADE_HINT =
+  'architecture surface (API/DB/aggregate) touched — upgrade to planned: '
+  + 'tf state upgrade <change-dir> planned (keeps code/test evidence, rolls back to approved-for-build, '
+  + 're-runs planned gates + light writeback sequence; downgrades rejected)';
+
+export function checkDirectShortPath(changeDir) {
+  const state = readState(changeDir);
+  const scan = scanArchitectureSurface(changeDir, state);
+
+  if (scan.error === 'no-baseline') {
+    return {
+      pass: false,
+      failures: [
+        'no scan baseline: base_sha missing and no origin/<default> to derive merge-base — '
+        + 'run inside a git repo with at least one commit (tf state init stamps base_sha), fail-closed',
+      ],
+    };
+  }
+  if (scan.error === 'diff-failed') {
+    return {
+      pass: false,
+      failures: [`git diff against base failed (base=${scan.base ?? 'unknown'}) — cannot verify architecture surface, fail-closed`],
+    };
+  }
+  if (scan.error === 'aggregate-list-missing') {
+    return {
+      pass: false,
+      failures: [
+        'aggregate list missing: create .team-flow/aggregate-dirs.txt (one dir prefix per line; '
+        + 'empty file = explicitly no aggregates) or run workflow-bootstrap — fail-closed, aggregate surface is blind otherwise',
+      ],
+    };
+  }
+
+  if (scan.architectureSurface.length > 0) {
+    return {
+      pass: false,
+      failures: [
+        `${UPGRADE_HINT}\n    touched: ${scan.architectureSurface.slice(0, 10).join(', ')}`,
+      ],
+    };
+  }
+  return { pass: true, failures: [] };
+}

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 = [];