@xulthekl/team-flow 0.47.0 → 0.49.0

package/scripts/lib/execution-plan.mjs

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { computeArtifactsHash, computeContractHash } from './hash.mjs';
+import { computeArtifactsHash, computeContractHash, hashObject, stableJson } from './hash.mjs';
 import { getOverlayPaths } from './sdd-overlay.mjs';
 import { readState } from './state-loader.mjs';
 import { detectWorkspaceRoot, findSubRepo } from './git-utils.mjs';
@@ -55,11 +55,11 @@ export function writePlan(changeDir, plan) {
   mkdirSync(paths.root, { recursive: true });
   const previousPlan = readPlan(changeDir);
   if (previousPlan && (previousPlan.revision !== plan.revision || previousPlan.hash !== plan.hash)) {
-    // v0.35.0: Review receipts are RETAINED across revisions — readCurrentReview
-    // validates plan_hash/plan_revision matching, so stale receipts are
-    // automatically invalidated without losing evidence (base/head/report SHA).
-    // This prevents legitimate artifact updates (e.g., design.md 横展结论) from
-    // causing cascading receipt loss. See workflow-feedback 20260805.
+    // v0.35.0: Review receipts are RETAINED across revisions.
+    // v0.49.0 §83.3.2: 有效性判据改为 wave 定义指纹 —— receipt 只在该 wave 的定义
+    // 变化时失效，与 plan 的 revision/artifacts_hash 无关（历史 receipt 因此可跨
+    // revise/refresh-hash 继续生效）；无 wave_fingerprint 的存量 receipt 回退旧判据。
+    // See workflow-feedback 20260805 / 20260909.
     //
     // Recommendation receipt is revision-scoped and must be cleaned:
     const recommendationFile = paths.executionRecommendation;
@@ -171,6 +171,8 @@ export function recordReview(changeDir, waveId, receipt, repoPath) {
     // Persist repo path when SHA was resolved in a sub-repository, so
     // readCurrentReview can re-validate without re-scanning.
     ...(subRepoPath ? { repo: relative(changeDir, subRepoPath) } : {}),
+    // v0.49.0 §83.3.2：主判据 —— wave 定义指纹；plan_hash/plan_revision 降级为审计信息
+    wave_fingerprint: computeWaveFingerprint(wave),
     plan_hash: plan.hash,
     plan_revision: plan.revision,
     recorded_at: new Date().toISOString(),
@@ -182,16 +184,25 @@ export function recordReview(changeDir, waveId, receipt, repoPath) {
 }
 
 /**
- * Returns the current plan's receipt for one wave. Receipts from a previous
- * revision/hash are never evidence for the current plan.
+ * Returns the current plan's receipt for one wave.
+ *
+ * v0.49.0 §83.3.2：有效性判据为 **wave 定义指纹**（id/strategy/tasks/depends_on）——
+ * receipt 只在该 wave 的定义变化时失效，与 plan 的 revision/artifacts_hash 无关。
+ * 无 wave_fingerprint 的存量 receipt（v0.48.0 及以前）回退旧的 plan 全内容判据。
  */
 export function readCurrentReview(changeDir, waveId, plan = readPlan(changeDir)) {
   if (!plan) return null;
+  const wave = Array.isArray(plan.waves) ? plan.waves.find(candidate => candidate?.id === waveId) : null;
+  if (!wave) return null;
   const filePath = join(getOverlayPaths(changeDir).reviews, `${safeFileName(waveId)}.json`);
   if (!existsSync(filePath)) return null;
   try {
     const receipt = JSON.parse(readFileSync(filePath, 'utf8'));
-    if (receipt?.plan_hash !== plan.hash || receipt?.plan_revision !== plan.revision) return null;
+    if (receipt?.wave_fingerprint !== undefined) {
+      if (receipt.wave_fingerprint !== computeWaveFingerprint(wave)) return null;
+    } else if (receipt?.plan_hash !== plan.hash || receipt?.plan_revision !== plan.revision) {
+      return null;
+    }
     // When the receipt records a repo path (sub-repo scenario), use it for
     // SHA re-validation.  Otherwise fall back to the default main-repo path.
     const repoPath = receipt?.repo ? resolve(changeDir, receipt.repo) : undefined;
@@ -218,6 +229,8 @@ export function describeWaves(changeDir, plan = readPlan(changeDir)) {
     const receipt = readCurrentReview(changeDir, wave.id, plan);
     const blockers = blockedDependencies(changeDir, plan, wave);
     const retryable = receipt?.status === 'fail';
+    // v0.49.0 §83.3.2：receipt 文件存在但未被采纳时给出审计线索（来源：workflow-feedback 20260909）
+    const staleReceipt = receipt === null ? readStaleReview(changeDir, wave.id) : null;
     return {
       id: wave.id,
       strategy: wave.strategy,
@@ -226,11 +239,32 @@ export function describeWaves(changeDir, plan = readPlan(changeDir)) {
       eligible: (receipt === null || retryable) && blockers.length === 0,
       retryable,
       receipt,
+      ...(staleReceipt ? { stale_receipt: staleReceipt } : {}),
       blockers,
     };
   });
 }
 
+/**
+ * v0.49.0 §83.3.2：诊断信息 —— receipt 文件存在但因判据失配而未被采纳时返回审计线索。
+ * 不参与任何门禁判定（门禁只看 readCurrentReview）。
+ */
+function readStaleReview(changeDir, waveId) {
+  const filePath = join(getOverlayPaths(changeDir).reviews, `${safeFileName(waveId)}.json`);
+  if (!existsSync(filePath)) return null;
+  try {
+    const receipt = JSON.parse(readFileSync(filePath, 'utf8'));
+    return {
+      status: receipt?.status ?? null,
+      plan_revision: receipt?.plan_revision ?? null,
+      recorded_at: receipt?.recorded_at ?? null,
+      reason: 'the wave definition changed after this receipt was recorded',
+    };
+  } catch {
+    return null;
+  }
+}
+
 function validateReviewReportEvidence(changeDir, report) {
   requireText(report, 'receipt.report');
   if (/[\p{Cc}\p{Zl}\p{Zp}]/u.test(report)) {
@@ -271,12 +305,12 @@ function getPhysicalReviewsDirectory(changeDir) {
   let directory = changeRoot;
   for (const component of ['.superpowers', 'sdd', 'reviews']) {
     directory = join(directory, component);
-    let metadata;
-    try {
-      metadata = lstatSync(directory);
-    } catch (error) {
-      throw new Error(`Review report evidence cannot read the ${component} overlay directory: ${error.message}`);
+    // multi-repo-support v1.0 §4.2（cli-command-2 修复）：overlay 目录自动创建，修 ENOENT
+    // （首次 review 时 .superpowers/sdd/reviews/ 尚不存在，recordReview 写入前先建）
+    if (!existsSync(directory)) {
+      mkdirSync(directory, { recursive: true });
     }
+    const metadata = lstatSync(directory);
     if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
       throw new Error('Review report evidence requires physical .superpowers/sdd/reviews overlay directories');
     }
@@ -312,8 +346,11 @@ function validateReviewRange(changeDir, base, head, repoPath) {
   // This happens either through automatic fallback (subRepoPath set above)
   // or through explicit --repo pointing to a different repository.
   if (!subRepoPath && repoPath) {
-    const defaultRoot = resolveGitRoot(changeDir);
-    if (gitRoot !== defaultRoot) subRepoPath = gitRoot;
+    // multi-repo-support v1.0 §4.2（cli-command-2 修复）：--repo 场景下 change 目录可能无 git
+    //（多仓库 changes/ 未版本化），defaultRoot 比较容错返回 null，不因 change 目录无 git 报错
+    let defaultRoot = null;
+    try { defaultRoot = resolveGitRoot(changeDir); } catch {}
+    if (defaultRoot && gitRoot !== defaultRoot) subRepoPath = gitRoot;
   }
 
   const effectiveRoot = subRepoPath || gitRoot;
@@ -513,13 +550,35 @@ function hasDependencyCycle(waves) {
 }
 
 function hashPlan(plan) {
-  const { hash, ...content } = plan;
-  return `sha256:${createHash('sha256').update(stableJson(content)).digest('hex')}`;
+  // v0.49.0 §83.3.3：stableJson/hashObject 抽到 hash.mjs 共享（原为本文件与
+  // execution-recommendation.mjs 各一份副本）
+  return hashObject(plan);
+}
+
+/**
+ * v0.49.0 §83.3.2（来源：workflow-feedback 2026-09-09）：wave 定义指纹 —— review receipt 的有效性判据。
+ *
+ * receipt 证明的是"该 wave 的实现在 base..head 间完成并已审查"，其语义依赖仅为该 wave 的定义
+ * （id/strategy/tasks/depends_on）+ git 事实 + 审查报告，**不含** plan 的其余内容
+ * （rationale / artifacts_hash / contract_hash / revision / recommendation_receipt）。
+ * 绑定 plan 全内容会使任何与 wave 无关的变更（refresh-hash 刷新制品 hash、revise 升号）
+ * 误杀全部历史 receipt，且无补录路径。
+ */
+function computeWaveFingerprint(wave) {
+  return `sha256:${createHash('sha256').update(stableJson({
+    id: wave?.id,
+    strategy: wave?.strategy,
+    tasks: wave?.tasks,
+    depends_on: wave?.depends_on,
+  })).digest('hex')}`;
 }
 
 /**
  * v0.35.0: Refresh plan's artifacts_hash and contract_hash without bumping revision.
  * Returns the updated plan (already persisted via writePlan), or null if no change needed.
+ *
+ * v0.49.0 §83.3.3：同步刷新内嵌 recommendation_receipt 的两个 hash（两者语义恒等），
+ * 否则 refresh-hash 之后 validatePlan 立即 FAIL（来源：workflow-feedback 20260909）。
  */
 export function refreshPlanHash(changeDir) {
   const plan = readPlan(changeDir);
@@ -531,6 +590,11 @@ export function refreshPlanHash(changeDir) {
   }
   plan.artifacts_hash = newArtifactsHash;
   plan.contract_hash = newContractHash;
+  if (plan.recommendation_receipt) {
+    plan.recommendation_receipt.artifacts_hash = newArtifactsHash;
+    plan.recommendation_receipt.contract_hash = newContractHash;
+    plan.recommendation_receipt.hash = hashObject(plan.recommendation_receipt);
+  }
   plan.hash = hashPlan(plan);
   return writePlan(changeDir, plan);
 }
@@ -544,20 +608,6 @@ function tryHashPlan(plan) {
   }
 }
 
-function stableJson(value, seen = new WeakSet()) {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value);
-  if (seen.has(value)) throw new Error('circular plan data');
-  seen.add(value);
-  if (Array.isArray(value)) {
-    const result = `[${value.map(item => stableJson(item, seen)).join(',')}]`;
-    seen.delete(value);
-    return result;
-  }
-  const result = `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableJson(value[key], seen)}`).join(',')}}`;
-  seen.delete(value);
-  return result;
-}
-
 function writeExecutionPlanSummary(changeDir, plan) {
   const statePath = join(changeDir, '.team-flow.yaml');
   const state = readState(changeDir);

package/scripts/lib/execution-recommendation.mjs

@@ -1,10 +1,10 @@
 // Evidence-based execution-mode recommendation for DP-4.
 
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadConfig } from './config-loader.mjs';
-import { computeArtifactsHash, computeContractHash } from './hash.mjs';
+import { computeArtifactsHash, computeContractHash, hashObject, stableJson } from './hash.mjs';
 import { getOverlayPaths } from './sdd-overlay.mjs';
 import { readState } from './state-loader.mjs';
 import { EXECUTION_MODES } from './execution-plan.mjs';
@@ -205,22 +205,8 @@ function normalizeWaves(waves) {
 }
 
 function hashReceipt(receipt) {
-  const { hash, ...content } = receipt || {};
-  return `sha256:${createHash('sha256').update(stableJson(content)).digest('hex')}`;
-}
-
-function stableJson(value, seen = new WeakSet()) {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value);
-  if (seen.has(value)) throw new Error('circular recommendation data');
-  seen.add(value);
-  if (Array.isArray(value)) {
-    const result = `[${value.map(item => stableJson(item, seen)).join(',')}]`;
-    seen.delete(value);
-    return result;
-  }
-  const result = `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableJson(value[key], seen)}`).join(',')}}`;
-  seen.delete(value);
-  return result;
+  // v0.49.0 §83.3.3：stableJson/hashObject 抽到 hash.mjs 共享
+  return hashObject(receipt);
 }
 
 function atomicWrite(targetPath, content) {

package/scripts/lib/glaf4-delegation.mjs

@@ -3,8 +3,10 @@
  * glaf4-delegation — GLAF4 委托协议 CLI（v2.1 §6.6/§6.3/§6.7，P2 实施委托全链路）
  *
  * 用法：
- *   tf glaf4-delegation detect <root> [--delegation-mode <mode>] [--json]
- *       运行时探测（v2.1 §4 接口①，C1 修复接线）：三态检测 + 写 .team-flow/team-flow.config.json 的 glaf4_dev 段。
+ *   tf glaf4-delegation detect <root> [--delegation-mode <mode>] [--target-repo <模块路径>] [--json]
+ *       运行时探测（v2.1 §4 接口①，C1 修复接线 + multi-repo-support v1.0 §4.1）：
+ *       root 解析（change 目录→项目根）+ 写 .team-flow/team-flow.config.json 的 glaf4_dev 段（项目根）。
+ *       multi-repo 下按 repo_layout 清单聚合判定 is_glaf4_java；--target-repo 精确探测指定模块。
  *       contract-builder 产出 execution-contract 时（DP-4 前）显式调用此命令，recommend 才能读到 glaf4_dev。
  *   tf glaf4-delegation confirm <change-dir> --mode <mode> --write-set <json> [--json]
  *       DP-4 委托方案确认：mode 枚举标量入 state，write_set_boundary 落 .superpowers/glaf4/write-set.json，
@@ -28,7 +30,9 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 import { join, isAbsolute, relative, resolve, normalize, sep } from 'node:path';
 import { readState, writeState } from './state-loader.mjs';
 import { getOverlayPaths } from './sdd-overlay.mjs';
-import { detectGlaf4Delegation, writeGlaf4DevConfig } from './conventions-generator.mjs';
+import { detectGlaf4Delegation, detectTechStack, writeGlaf4DevConfig } from './conventions-generator.mjs';
+import { detectWorkspaceRoot, getGitRoot } from './git-utils.mjs';
+import { loadConfig } from './config-loader.mjs';
 
 // DP-4 委托模式合法枚举（对应 glaf4-dev 七模式中可委托 change 的六种）
 export const GLAF4_DELEGATION_MODES = [
@@ -72,26 +76,42 @@ export function hashWriteSet(writeSet) {
  * @param {string} [delegationMode] 覆盖 delegation_mode（auto/manual/off）
  * @returns {object} { ok, is_glaf4_java, glaf4_dev_available, glaf4_dev_version, delegation_mode, configPath }
  */
-export function detectAndWriteConfig(root, delegationMode) {
-  const detection = detectGlaf4Delegation(root, { delegationMode });
+export function detectAndWriteConfig(root, delegationMode, targetRepo) {
+  // multi-repo-support-design v1.0 §4.1（cli-command-1 修复）：root 解析——change 目录（含 changes/）→ 项目根；否则 git 根
+  const projectRoot = resolveProjectRoot(root);
+
+  // 读 repo_layout（config 已固化时）
+  const config = loadConfig(projectRoot);
+  const repoLayout = config?.repo_layout || null;
+
+  // 探测目标构造（P3 自查补全 + P4 validator W1 放宽，2026-08-21）：
+  //   --target-repo 精确 > repo_layout 清单聚合（repos 非空即聚合，不限 multi-repo——
+  //   壳仓库含 package.json 误判 monorepo 时也应聚合，否则 cli-command-1 在真实项目失效）>
+  //   root 有技术栈（探测 root，如 detect(svcA)）>
+  //   root 无技术栈（change 文档目录/容器根）→ 探测解析后项目根（单仓库项目根有 pom.xml）
+  let repos = null;
+  let probeRoot = root;
+  if (targetRepo) {
+    probeRoot = targetRepo;
+  } else if (repoLayout?.repos && Object.keys(repoLayout.repos).length > 0) {
+    repos = Object.values(repoLayout.repos);
+  } else if (!detectTechStack(root).language) {
+    probeRoot = projectRoot;
+  }
+  const detection = detectGlaf4Delegation(probeRoot, { delegationMode, repos });
 
-  // 复评 C1 嵌套工程根盲区（2026-08-18）：git root ≠ target_root（monorepo 布局）时，
-  // loadConfig(changeDir) 只查 changeDir→git root→home，不查 target_root → 委托链静默断裂。
-  // 写 git root 冗余副本保证从任意 changeDir 都能读到探测结果。gitRoot 提前解析供 mode 优先级使用。
+  // git root（冗余副本判断 + mode 优先级）
   let gitRoot = null;
   try {
-    gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
-      cwd: root, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
+    gitRoot = getGitRoot(projectRoot);
   } catch {
     // 非 git 仓库，跳过
   }
 
-  // 第四轮复评 Important（2026-08-18）：delegation_mode 优先级链补全——显式 > 目标 root 已有 > git root 已有 > auto。
-  // 上轮只查目标 root，非 Java 服务无本地 config → 默认 auto → 覆盖 git root 副本的 off（用户 off 意图被静默翻转）。
+  // delegation_mode 优先级链：显式 > 目标 root 已有 > git root 已有 > auto
   let effectiveMode = delegationMode;
   if (!effectiveMode) {
-    effectiveMode = readGlaf4DelegationMode(root)
+    effectiveMode = readGlaf4DelegationMode(projectRoot)
       || (gitRoot ? readGlaf4DelegationMode(gitRoot) : null)
       || 'auto';
   }
@@ -100,16 +120,17 @@ export function detectAndWriteConfig(root, delegationMode) {
     version: detection.glaf4_dev_version,
     delegationMode: effectiveMode,
   };
-  writeGlaf4DevConfig(root, info);
+  // config 主副本写项目根（cli-command-1 修复：不再写 change 目录）
+  // multi-repo-support v1.0：OR 聚合保留已有 enabled=true——项目级 GLAF4 能力一旦声明，
+  // 不因后续非 Java 目标探测而覆盖丢失（非 Java change detect 不应禁用项目委托）
+  const existingProjEnabled = readGitRootGlaf4Enabled(projectRoot);
+  const projEnabled = info.enabled || existingProjEnabled;
+  writeGlaf4DevConfig(projectRoot, { ...info, enabled: projEnabled, delegationMode: effectiveMode });
 
   let gitRootConfig = null;
-  if (gitRoot && gitRoot !== root) {
-    // 第三轮复评 Important①（2026-08-18）：多服务混合 monorepo 下 git root 副本 last-write-wins 污染——
-    // 非 Java 服务 detect 会把 Java 服务的 enabled=true 覆盖成 false。改为 OR 聚合：
-    // 项目级能力一旦声明（任一服务 enabled=true），不因后续非 Java 服务探测而丢失。
+  if (gitRoot && gitRoot !== projectRoot) {
     const existingEnabled = readGitRootGlaf4Enabled(gitRoot);
     const aggregatedEnabled = info.enabled || existingEnabled;
-    // 第四轮复评：git root 副本 mode 保留已有值（显式传参才覆盖）——用户 off 意图不因新探测静默翻转。
     const gitRootMode = readGlaf4DelegationMode(gitRoot);
     const gitRootEffectiveMode = delegationMode || gitRootMode || effectiveMode;
     writeGlaf4DevConfig(gitRoot, { ...info, enabled: aggregatedEnabled, delegationMode: gitRootEffectiveMode });
@@ -119,11 +140,27 @@ export function detectAndWriteConfig(root, delegationMode) {
   return {
     ok: true,
     ...detection,
-    configPath: join(root, '.team-flow', 'team-flow.config.json'),
+    configPath: join(projectRoot, '.team-flow', 'team-flow.config.json'),
     gitRootConfig,
+    projectRoot,
   };
 }
 
+/**
+ * root 解析（multi-repo-support-design v1.0 §4.1）：change 目录（含 changes/）→ 项目根；否则 git 根；兜底直接用 root
+ * @param {string} root
+ * @returns {string}
+ */
+function resolveProjectRoot(root) {
+  const ws = detectWorkspaceRoot(root);
+  if (ws) return ws;
+  try {
+    return getGitRoot(root);
+  } catch {
+    return root;
+  }
+}
+
 /**
  * 读 git root 现有 config 的 glaf4_dev.enabled（第三轮复评 Important① OR 聚合用）
  * @param {string} gitRoot
@@ -394,7 +431,7 @@ export function resetDelegation(changeDir) {
 
 export async function run(args) {
   const positionals = args.filter(a => !a.startsWith('--'));
-  const flags = new Set(args.filter(a => a.startsWith('--') && a !== '--mode' && a !== '--write-set' && a !== '--run-dir' && a !== '--target-root' && a !== '--json'));
+  const flags = new Set(args.filter(a => a.startsWith('--') && a !== '--mode' && a !== '--write-set' && a !== '--run-dir' && a !== '--target-root' && a !== '--target-repo' && a !== '--delegation-mode' && a !== '--json'));
   const opt = (name) => {
     const i = args.indexOf(`--${name}`);
     return i >= 0 ? args[i + 1] : undefined;
@@ -404,7 +441,7 @@ export async function run(args) {
   const json = flags.has('--json') || args.includes('--json');
 
   const usage = `Usage:
-  tf glaf4-delegation detect <root> [--delegation-mode <auto|manual|off>]
+  tf glaf4-delegation detect <root> [--delegation-mode <auto|manual|off>] [--target-repo <模块路径>]
   tf glaf4-delegation confirm <change-dir> --mode <mode> --write-set <json-file>
   tf glaf4-delegation verify-write-set <change-dir> --run-dir <run-dir>
   tf glaf4-delegation verify-tasks <change-dir>
@@ -424,15 +461,16 @@ export async function run(args) {
   try {
     if (subcommand === 'detect') {
       const mode = opt('delegation-mode');
+      const targetRepo = opt('target-repo');
       // 第四轮复评 Minor-1（2026-08-18）：枚举校验——非法值（如 'foo'）等同 auto 放行会让用户配置失真
       if (mode !== undefined && !['auto', 'manual', 'off'].includes(mode)) {
         console.error(`--delegation-mode 必须为 auto/manual/off 之一（实际: ${mode}）`);
         process.exit(2);
       }
-      const result = detectAndWriteConfig(changeDir, mode);
+      const result = detectAndWriteConfig(changeDir, mode, targetRepo);
       const msg = result.glaf4_dev_available
-        ? `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev v${result.glaf4_dev_version} 可用, delegation_mode=${result.delegation_mode} → config 已写 ${result.configPath}`
-        : `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev 不可用 → config 已写 ${result.configPath}`;
+        ? `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev v${result.glaf4_dev_version} 可用, delegation_mode=${result.delegation_mode} → config 已写 ${result.configPath}${result.projectRoot ? `（项目根 ${result.projectRoot}）` : ''}`
+        : `探测: is_glaf4_java=${result.is_glaf4_java}, glaf4-dev 不可用 → config 已写 ${result.configPath}${result.projectRoot ? `（项目根 ${result.projectRoot}）` : ''}`;
       print(result.ok, result, msg);
     } else if (subcommand === 'confirm') {
       const mode = opt('mode');

package/scripts/lib/hash.mjs

@@ -4,6 +4,45 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { findCanonicalSpecFiles } from './spec-paths.mjs';
 
+/**
+ * Normalize tasks.md checkbox state: `- [x]` / `- [X]` → `- [ ]`.
+ *
+ * v0.49.0 §83.3.1（来源：workflow-feedback 2026-09-09）：tasks.md 同时是规划制品
+ * （artifacts_hash 的冻结对象）与执行台账（tasks-complete guard 要求执行期回写勾选）。
+ * 勾选状态属执行进度、不属规划内容 —— 归一化后入 hash，使"执行期勾选"不再使 plan
+ * 过期（否则勾选后 recordReview 因 plan stale 抛错，形成 closing 死锁）。
+ * 任务文本、数量与结构的变更仍会改变 hash。
+ */
+export function normalizeCheckboxes(content) {
+  return content.replace(/^([ \t]*- )\[[xX]\]/gm, '$1[ ]');
+}
+
+/**
+ * 稳定序列化：对象键排序后递归序列化，保证同一内容产生同一字符串。
+ *
+ * v0.49.0 §83.3.3：从 execution-plan.mjs / execution-recommendation.mjs 抽取共享
+ * （原为两份实现），供 plan hash 与 recommendation receipt hash 共用。
+ */
+export function stableJson(value, seen = new WeakSet()) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (seen.has(value)) throw new Error('circular data');
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const result = `[${value.map(item => stableJson(item, seen)).join(',')}]`;
+    seen.delete(value);
+    return result;
+  }
+  const result = `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableJson(value[key], seen)}`).join(',')}}`;
+  seen.delete(value);
+  return result;
+}
+
+/** 通用对象 hash：剔除顶层 `hash` 字段后取 sha256。 */
+export function hashObject(value) {
+  const { hash, ...content } = value ?? {};
+  return `sha256:${crypto.createHash('sha256').update(stableJson(content)).digest('hex')}`;
+}
+
 // Compute a joint SHA256 hash of all 4 planning artifacts.
 // Input: proposal.md + specs/*/spec.md (sorted) + design.md + tasks.md
 export function computeArtifactsHash(changeDir) {
@@ -30,10 +69,10 @@ export function computeArtifactsHash(changeDir) {
     hasContent = true;
   }
 
-  // tasks.md
+  // tasks.md（v0.49.0 §83.3.1：勾选状态归一化后入 hash —— 执行进度不属规划内容）
   const tasks = path.join(changeDir, 'tasks.md');
   if (fs.existsSync(tasks)) {
-    hash.update(fs.readFileSync(tasks, 'utf-8'));
+    hash.update(normalizeCheckboxes(fs.readFileSync(tasks, 'utf-8')));
     hasContent = true;
   }
 

package/scripts/lib/prototype-sync.mjs

@@ -16,6 +16,7 @@
 
 import { readFileSync, writeFileSync, existsSync, cpSync, mkdirSync } from 'node:fs';
 import { join, basename, relative, sep, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 /**
  * 解析 CLI 参数数组为结构化对象
@@ -216,7 +217,7 @@ export function run(args = {}) {
 }
 
 // 支持直接执行：node prototype-sync.mjs <change-dir> --source <path>
-if (process.argv[1]?.includes('prototype-sync')) {
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = { _: [] };
   for (let i = 2; i < process.argv.length; i++) {
     if (process.argv[i].startsWith('--')) {

package/scripts/lib/sdd-overlay.mjs

@@ -3,7 +3,7 @@ import {
   existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync,
 } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { computeArtifactsHash } from './hash.mjs';
+import { computeArtifactsHash, normalizeCheckboxes } from './hash.mjs';
 import { readState } from './state-loader.mjs';
 
 export const HANDOFF_TYPES = new Set(['prototype', 'research', 'experiment']);
@@ -30,7 +30,8 @@ export function computeTaskHash(changeDir, taskId) {
   const escaped = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const match = tasks.match(new RegExp(`^- \\[([ xX])\\] ${escaped}\\s+.+$`, 'm'));
   if (!match) throw new Error(`Task '${taskId}' was not found in tasks.md`);
-  return `sha256:${createHash('sha256').update(match[0]).digest('hex')}`;
+  // v0.49.0 §83.3.1：勾选状态归一化 —— 勾选是执行进度，不应使 checkpoint 变 stale
+  return `sha256:${createHash('sha256').update(normalizeCheckboxes(match[0])).digest('hex')}`;
 }
 
 export function saveCheckpoint(changeDir, input) {

package/scripts/lib/solutions-capture.mjs

@@ -13,6 +13,7 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 const PHASES = ['prd', 'plan', 'architecture', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
 const MAX_INDEX_LINES = 150;
@@ -89,7 +90,7 @@ ${summary}
   return { file: `${phase}/${fileName}`, phase, domain, type, severity };
 }
 
-if (process.argv[1]?.includes('solutions-capture')) {
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = {};
   for (let i = 2; i < process.argv.length; i++) {
     if (process.argv[i].startsWith('--')) {

package/scripts/lib/solutions-index-gen.mjs

@@ -15,6 +15,7 @@
 
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 const PHASES = ['prd', 'plan', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
@@ -104,7 +105,7 @@ export function run(args = {}) {
 }
 
 // CLI 直接执行
-if (process.argv[1]?.includes('solutions-index-gen')) {
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = {};
   const dirIdx = process.argv.indexOf('--dir');
   if (dirIdx > -1 && process.argv[dirIdx + 1]) args.dir = process.argv[dirIdx + 1];

package/scripts/lib/solutions-inject.mjs

@@ -14,6 +14,7 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
 
@@ -66,7 +67,7 @@ export function run(args = {}) {
   return { entries: top5 };
 }
 
-if (process.argv[1]?.includes('solutions-inject')) {
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const args = {};
   for (let i = 2; i < process.argv.length; i += 2) {
     const key = process.argv[i]?.replace('--', '');