@xulthekl/team-flow 0.62.0 → 0.64.0

package/scripts/guard/guard.mjs

@@ -16,10 +16,23 @@ import { checkExecutionReviewsPassed } from './checks/execution-reviews-passed.m
 import { checkCompoundCaptured } from './checks/compound-captured.mjs';
 import { checkTestMatrixComplete } from './checks/test-matrix-complete.mjs';
 import { checkTestMatrixReady } from './checks/test-matrix-ready.mjs';
+import { checkGatesProbed } from './checks/gates-probed.mjs';
 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 = {
@@ -39,7 +52,12 @@ const TRANSITION_CHECKS = {
   // 任何能写 dp_3_result 的主体（含夜间替身的 HOLD 落盘）都能让 change 呈现"已批准"假象，
   // 从而在无真实批准的前提下跨过 DP-3 硬门。本维度要求取值以 "approved" 开头
   // （判据实现见 checks/dp3-approved.mjs）。
-  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed', 'dp3-approved'],
+  // v0.63.0（workflow-feedback 20260923-013114 S2）：**gates-probed 新增**——契约的 G 类闸门
+  // 必须在 bridging 期跑过 dry-run（预期 FAIL = RED 基线）并留档，把 design.md R-7 长期存在的
+  // 「闸门已实测可跑」文字自证物化为机械证据。检查五件：evidence 存在 / 首行 RED 基线 /
+  // CONTRACT_HASH 值新鲜 / 契约 Gate Registry 的 id 逐 id 覆盖 / **段缺失即 FAIL（fail-closed）**。
+  // hotfix 走 WORKFLOW_TRANSITION_CHECKS 自有覆盖（下方），tweak 由 skip 回退阀放行。
+  'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed', 'dp3-approved', 'gates-probed'],
   // v0.13 §49：test-matrix-ready 门禁前移——full 模式进入 executing 前强制测试准备度
   //（矩阵存在非空 OR 显式 skip 附理由；legacy 豁免）。hotfix/tweak 沿用 §45.3 豁免，不挂。
   'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready', 'test-matrix-ready'],
@@ -51,7 +69,15 @@ const TRANSITION_CHECKS = {
   // 且 arch-merge 在状态机上无任何锚点（VALID_STATES 无 closed、closing→closed 不存在）。
   // B' 把 arch-merge 前移到本转换**之前**，本维度即其前置条件。
   // hotfix/tweak 沿用既有豁免口径（WORKFLOW_TRANSITION_CHECKS 各自列维度，天然不挂）。
-  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete', 'arch-snapshot', 'delegation-status', 'arch-merged'],
+  // v0.63.0（feedback 20260923-013114 S3）：**contract-fresh 新增**——S3「DP-3 后规划制品冻结」
+  // 的反查锚。原状 closing 无 contract-fresh，反查实际依赖 execution-plan-ready（validatePlan
+  // 比对 plan 内嵌的 artifacts_hash/contract_hash），而该比对可被 `tf execution refresh-hash`
+  // 一键刷平（refreshPlanHash 直接改写 plan JSON、revision 不升）→ 把 gate-affecting 变更
+  // 伪记为陈述性勘误后，closing 全维 PASS、wave receipt 亦不失效（wave_fingerprint 不含
+  // artifacts_hash）→ **伪绿静默通过**。本维度直接比对 state.artifacts_hash 与制品实算值，
+  // refresh-hash 无法清屏（它只改 plan JSON，不碰 state）——故为 refresh-hash 之外的独立锚。
+  // hotfix/tweak 不挂：二者跳过 spec-writer、无 planning 四件，冻结机制本身 N/A（设计 §3.9）。
+  'executing:closing':              ['contract-fresh', 'tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete', 'arch-snapshot', 'delegation-status', 'arch-merged'],
 
   // Debugging side-path
   'executing:debugging':            [],
@@ -99,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: [{
@@ -115,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];
 }
 
@@ -124,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);
   }
 
@@ -139,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(', ');
@@ -162,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));
@@ -184,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),
@@ -191,19 +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}`);

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 会**回显成功却零写入**
@@ -45,6 +52,12 @@ const SETTABLE_FIELDS = [
   'tasks_skipped', 'tasks_skip_reason',
   // Arch merge gate (v0.53.0 §110.2：arch-merged guard 维度的显式跳过键，须附理由)
   'arch_merge_skipped', 'arch_merge_skip_reason',
+  // Bridging gates dry-run gate (v0.63.0；feedback 20260923-013114 S2)
+  // 三键必须与 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) {
@@ -62,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);
   }
 
@@ -76,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);
@@ -108,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;
@@ -166,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,
       });
@@ -278,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 }));
@@ -286,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');