@xulthekl/team-flow 0.48.0 → 0.50.0

package/scripts/lib/arch-precheck.mjs

@@ -0,0 +1,190 @@
+// scripts/lib/arch-precheck.mjs — tf arch precheck：架构判断门的确定性证据工具（v0.22 §88.3.2）
+//
+// 定位：**证据工具，不是判断者**。本命令只输出"架构信号命中情况"，
+// 判断仍归 architecture-design 子代理（v0.9 §26 的独立性不变）。
+// 退出码恒为 0 —— 不阻断流程，也不替代判断。
+//
+// 动机（workflow-feedback 20260909-112755）：hotfix 对表现层文案改动跑完整架构门
+// 消耗 41,864 tk，结论必然 skipped。让子代理在 signal=none 时只读 brief + 本命令输出
+// （不读全量 docs/architecture/）可大幅降本，同时保留独立判断与回退能力。
+//
+// 设计约束（H1 实测校准）：
+//   - 关键词须为**高置信度**短语——裸 `schema` / `api` 会误命中测试矩阵术语（"schema 覆盖声明"）
+//   - 否定表述须识别——"不动 filter.args" / "无聚合" 是**负向**证据，不能计为命中
+//   - 文件提取须去噪——`node_modules/` 引用非改动文件；同名文件按最完整路径去重
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 架构关键词表（对应 architecture-design SKILL 五项检查 + 配置契约 key）。 */
+const ARCH_KEYWORDS = [
+  // 1 聚合
+  '聚合', '聚合根', 'aggregate',
+  // 2 限界上下文
+  '限界上下文', 'bounded context',
+  // 3 读写模型
+  '读写模型', 'cqrs', '写模型', '读模型',
+  // 4 API（精确短语，避免裸 api 假阳性）
+  'api 签名', 'api 端点', 'api 变更', 'api 新增', '新增 api', 'api 契约', 'endpoint', '端点',
+  // 5 DB schema（精确短语，避免裸 schema 误命中测试矩阵术语）
+  'db schema', '数据库 schema', '表结构', 'ddl', '数据库表', '索引变更',
+  // 配置契约 key
+  'filter.args',
+];
+
+/**
+ * 否定上下文（行级）：否定词可能出现在关键词**之后**同句（如"范围外…`filter.args` …一律不动"）。
+ * 宽松匹配是刻意的——误判为 negated 只会让门走完整路径（安全），
+ * 误判为 positive 才会放行 fast path（危险）。
+ */
+const LINE_NEGATION_RE = /(不动|不涉及|不变更|不新增|不修改|不改变|不调整|不包含|严禁|不得|禁止|零变更|无变更|无新增|无修改|保持不变|unchanged|no change|without)/i;
+const NEGATION_ADJACENT_RE = /(不|无|非|未|零|no|not)\s*$/;
+
+/**
+ * 变更语境：关键词前文出现变更动词才计为**正向**信号。
+ * 仅"提到"关键词（如"按 filter.args 断言写回"）属中性，不构成架构变更信号。
+ */
+const CHANGE_VERB_RE = /(新增|修改|变更|调整|增加|删除|引入|扩展|重构|改造|迁移|升级|add|new|modify|change|update|refactor|migrate)/i;
+
+const PRESENTATION_EXTS = new Set(['.vue', '.jsx', '.tsx', '.less', '.css', '.scss', '.sass', '.html']);
+const BACKEND_EXTS = new Set(['.java', '.go', '.py', '.rb', '.rs', '.kt', '.kts', '.cs']);
+const CONFIG_EXTS = new Set(['.yaml', '.yml', '.json', '.sql', '.toml', '.ini', '.properties']);
+const SCRIPT_EXTS = new Set(['.js', '.ts', '.mjs', '.cjs', '.mts', '.cts']);
+const TEST_PATTERNS = [
+  /\.spec\.[cm]?[jt]sx?$/i,
+  /\.test\.[cm]?[jt]sx?$/i,
+  /Tests?\.java$/,
+  /_test\.go$/i,
+  /^test_.*\.py$/i,
+  /Tests?\.(kt|cs)$/,
+];
+
+const CODE_EXT_PATTERN = [...PRESENTATION_EXTS, ...BACKEND_EXTS, ...CONFIG_EXTS, ...SCRIPT_EXTS]
+  .map(e => e.slice(1))
+  .sort((a, b) => b.length - a.length)
+  .join('|');
+
+const FILE_RE = new RegExp(`(?:[\\w.-]+/)*[\\w.-]+\\.(?:${CODE_EXT_PATTERN})(?![\\w])`, 'gi');
+
+function classifyFile(file) {
+  const ext = path.extname(file).toLowerCase();
+  const base = path.basename(file);
+  if (TEST_PATTERNS.some(re => re.test(base))) return 'test';
+  if (PRESENTATION_EXTS.has(ext)) return 'presentation';
+  if (BACKEND_EXTS.has(ext)) return 'backend';
+  if (CONFIG_EXTS.has(ext)) return 'config';
+  if (SCRIPT_EXTS.has(ext)) return 'script';
+  return 'other';
+}
+
+/** 文件提取：剔除 node_modules 引用，同名文件保留最完整路径。 */
+function extractFiles(text) {
+  const byBase = new Map();
+  for (const m of text.matchAll(FILE_RE)) {
+    const f = m[0];
+    if (/(^|\/)node_modules\//.test(f)) continue;
+    const base = path.basename(f);
+    const prev = byBase.get(base);
+    if (!prev || f.length > prev.length) byBase.set(base, f);
+  }
+  return [...byBase.values()];
+}
+
+/** 关键词逐次出现的语境统计：negated（否定）/ positive（变更动词）/ neutral（仅提及）。 */
+function findKeyword(text, keyword) {
+  const kw = keyword.toLowerCase();
+  const stat = { occurrences: 0, positive: 0, negated: 0, neutral: 0 };
+  for (const line of text.split('\n')) {
+    const lowerLine = line.toLowerCase();
+    let idx = lowerLine.indexOf(kw);
+    while (idx !== -1) {
+      stat.occurrences += 1;
+      const before = line.slice(Math.max(0, idx - 30), idx);
+      if (LINE_NEGATION_RE.test(line) || NEGATION_ADJACENT_RE.test(before)) stat.negated += 1;
+      else if (CHANGE_VERB_RE.test(before)) stat.positive += 1;
+      else stat.neutral += 1;
+      idx = lowerLine.indexOf(kw, idx + kw.length);
+    }
+  }
+  return stat;
+}
+
+/**
+ * 扫描 change 的规划制品，返回架构信号证据。
+ * @returns {{ signal: 'none'|'weak'|'strong', hits: object, evidence: string[], sources: string[] }}
+ */
+export function collectArchSignals(changeDir) {
+  const sources = [];
+  for (const name of ['change-brief.md', 'execution-contract.md']) {
+    const p = path.join(changeDir, name);
+    if (fs.existsSync(p)) sources.push({ name, text: fs.readFileSync(p, 'utf-8') });
+  }
+
+  const text = sources.map(s => s.text).join('\n');
+
+  const keywords = [];
+  const negated = [];
+  const neutral = [];
+  for (const kw of ARCH_KEYWORDS) {
+    const stat = findKeyword(text, kw);
+    if (stat.occurrences === 0) continue;
+    if (stat.positive > 0) keywords.push(kw);
+    else if (stat.negated > 0) negated.push(kw);
+    else neutral.push(kw);
+  }
+
+  const files = { presentation: [], backend: [], config: [], script: [], test: [], other: [] };
+  for (const f of extractFiles(text)) files[classifyFile(f)].push(f);
+
+  const hasSql = files.config.some(f => f.toLowerCase().endsWith('.sql'));
+
+  let signal;
+  if (keywords.length > 0) signal = 'strong';
+  else if (files.backend.length > 0 || hasSql) signal = 'weak';
+  else if (files.presentation.length > 0) signal = 'none';
+  else signal = 'weak';
+
+  const evidence = [];
+  if (sources.length === 0) {
+    evidence.push('no change-brief.md / execution-contract.md found — signal defaults to weak');
+  }
+  evidence.push(keywords.length === 0
+    ? 'no architecture keyword in change context'
+    : `architecture keyword in change context: ${keywords.join(', ')}`);
+  if (negated.length > 0) evidence.push(`negated (not a signal): ${negated.join(', ')}`);
+  if (neutral.length > 0) evidence.push(`mentioned without change context (not a signal): ${neutral.join(', ')}`);
+  evidence.push(
+    `code files — presentation=${files.presentation.length}, backend=${files.backend.length}, `
+    + `config=${files.config.length}, script=${files.script.length}, test=${files.test.length}`,
+  );
+  if (signal === 'none') {
+    evidence.push('all evidence points to presentation-layer only — fast-path candidate (sub-agent must still confirm)');
+  }
+
+  return {
+    signal,
+    hits: { keywords, negatedKeywords: negated, neutralKeywords: neutral, files },
+    evidence,
+    sources: sources.map(s => s.name),
+  };
+}
+
+export async function run(positionals, values) {
+  const changeDirArg = positionals[0];
+  if (!changeDirArg) {
+    console.error('Usage: tf arch precheck <change-dir> [--json]');
+    process.exit(2);
+  }
+  const changeDir = path.resolve(changeDirArg);
+  const result = collectArchSignals(changeDir);
+
+  if (values.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`arch precheck — signal: ${result.signal}`);
+    console.log(`  sources: ${result.sources.join(', ') || '(none)'}`);
+    for (const line of result.evidence) console.log(`  - ${line}`);
+    console.log('  note: evidence only — the architecture-design sub-agent still makes the decision.');
+  }
+  // 证据工具：恒以 0 退出，不阻断流程。
+  process.exit(0);
+}

package/scripts/lib/cmd-arch.mjs

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
+import * as archPrecheck from './arch-precheck.mjs';
 
 const ARCH_STATE_FILE = '.team-flow/arch-state.json';
 
@@ -16,6 +17,7 @@ export async function run(args) {
       'project-root': { type: 'string' },
       mode: { type: 'string', default: 'reconstruction' },
       'baseline-ref': { type: 'string', default: 'prd/vN/' },
+      json: { type: 'boolean', default: false },
     },
     allowPositionals: true,
   });
@@ -23,7 +25,9 @@ export async function run(args) {
   const sub = positionals[0];
   if (sub === 'init') return init(values);
   if (sub === 'show') return show(values);
-  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show');
+  // v0.22 §88.3.2：架构门判据的确定性证据工具（证据 only，退出码恒 0）
+  if (sub === 'precheck') return archPrecheck.run(positionals.slice(1), values);
+  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show | tf arch precheck <change-dir> [--json]');
   process.exit(2);
 }
 

package/scripts/lib/cmd-doctor.mjs

@@ -5,6 +5,8 @@ import { loadConfig } from './config-loader.mjs';
 import { PLATFORM_RUNTIME_INVENTORY } from './platform-runtime-inventory.mjs';
 // 非法 state 巡检所需的共享常量与读取器(来源:workflow-feedback 2026-08-01,#100004)。
 import { readState, VALID_STATES } from './state-loader.mjs';
+// v0.22 §85：tasks_skipped 豁免判定复用 guard 侧唯一真相源，避免同一规则两处实现漂移。
+import { hasExplicitTasksSkip } from '../guard/checks/tasks-gate-exemptions.mjs';
 
 const RUNTIME_SKILLS = new Set([
   'workflow-start', 'need-explorer', 'spec-writer', 'contract-builder',
@@ -258,8 +260,8 @@ function checkChangeStates(root) {
   return { pass: true, message: `${checked} change(s) have legal state values` };
 }
 
-// v0.13 §52 B4 测试门禁卫生巡检（C1-domain-policy 事件修复）：
-// 1. test_matrix_skipped=true 必须附 test_matrix_skip_reason（可审计豁免）；
+// v0.13 §52 B4 测试门禁卫生巡检（C1-domain-policy 事件修复）；v0.22 §85 扩展 tasks_skipped：
+// 1. test_matrix_skipped / tasks_skipped = true 必须附对应 reason（可审计豁免）；
 // 2. 状态引用的产物文件必须存在（arch_review_report / test_evidence_path）——
 //    C1 现场曾出现 arch_review_report 指向不存在的 auto-review.md。
 // DP 时间戳顺序检查评估后未纳入：closing 后的 DP-7 时间戳晚于 last_transition 属合法，
@@ -283,6 +285,11 @@ function checkChangeTestGates(root) {
       && !(typeof state.test_matrix_skip_reason === 'string' && state.test_matrix_skip_reason.trim())) {
       issues.push(`${d}: test_matrix_skipped=true without test_matrix_skip_reason`);
     }
+    // v0.22 §85：tasks_skipped 沿用同一可审计豁免范式（跳过必须附理由），
+    // 判定复用 tasks-gate-exemptions 的共享谓词（与 guard 同一真相源）。
+    if (state.tasks_skipped === 'true' && !hasExplicitTasksSkip(state)) {
+      issues.push(`${d}: tasks_skipped=true without tasks_skip_reason`);
+    }
     for (const field of ['arch_review_report', 'test_evidence_path']) {
       const ref = state[field];
       if (typeof ref === 'string' && ref.trim() && !existsSync(join(changeDir, ref))) {

package/scripts/lib/cmd-runtime.mjs

@@ -15,6 +15,7 @@ const ASSETS = new Set([
   'skills/build-executor/task-reviewer-prompt.md',
   'templates/design.md',
   'templates/execution-contract.md',
+  'templates/learnings.md',
   'templates/proposal.md',
   'templates/spec.md',
   'templates/tasks.md',

package/scripts/lib/cmd-state.mjs

@@ -38,6 +38,8 @@ const SETTABLE_FIELDS = [
   'compound_skipped',
   // Test matrix gate (v0.12 §45.4 + v0.13 §48.2)
   'test_matrix_skipped', 'test_matrix_skip_reason',
+  // Tasks gate (v0.22 §85：hotfix/tweak 显式跳过 tasks.md，须附理由)
+  'tasks_skipped', 'tasks_skip_reason',
 ];
 
 export async function run(args) {

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)) {
@@ -516,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);
@@ -534,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);
 }
@@ -547,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/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('--', '');