@xulthekl/team-flow 0.48.0 → 0.49.0

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.48.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.49.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback + independent business analysis. 26 skills + 17 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.48.0",
+      "version": "0.49.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.48.0"
+    "version": "0.49.0"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.48.0"
+    "version": "0.49.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, independent business analysis, and local HTML prototyping.",
-      "version": "0.48.0",
+      "version": "0.49.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -112,8 +112,8 @@ docs/
       ├── INDEX.md     # L1 轻量索引（≤150行，每条一行摘要+标签）
       ├── requirement/ plan/ architecture/ prototype/ spec/ build/ review/ cross-phase/  # L2 分阶段目录（v0.36.0 加 architecture）
       └── <file>.md    # L3 经验文件（YAML frontmatter: phase/domain/type/severity）
-changes/<name>/        变更脚手架（S4 创建）：.team-flow.yaml（变更级状态文件）/ change-brief.md（产品级交接物，含 upstream_arch_ref）/ architecture/（变更级三件套 + sql/）
-specs/<cap>/            每变更设计/任务/契约：spec.md / design.md / tasks.md / execution-contract.md / learnings.md（v0.9 起 architecture/ 三件套已迁至 changes/<name>/architecture/）
+changes/<name>/        变更脚手架（S4 创建）：.team-flow.yaml（变更级状态文件）/ change-brief.md（产品级交接物，含 upstream_arch_ref）/ proposal.md / design.md / tasks.md / execution-contract.md / learnings.md（变更级经验台账）/ architecture/（变更级三件套 + sql/）
+specs/<cap>/            每变更规格：spec.md（v0.49.0 §83.3.5：learnings.md 归 change 根，不在此目录）
 STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 ```
 

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.49.0] - 2026-09-09
+
+### Fixed（execution plan 冻结边界与复利链路修复）
+
+设计来源：`docs/architecture-api-db-design-enhancement-v0.21.md` §83（2026-09-09，fytx-gateway-parent 4 条 workflow-feedback：093305 / 093306 / 093307 / 093308）
+
+**根因簇 A — execution plan 冻结边界错配**（3 个落点，构成闭合不可用回路）
+
+- **A1 hash 范围修正**：`normalizeCheckboxes` 归一化 tasks.md 勾选状态后再入 `artifacts_hash` / `computeTaskHash` —— 勾选是执行进度而非规划内容。修复「勾选 → plan 过期 → recordReview 抛错 → build-executor 无法勾选 → closing 死锁」（`hash.mjs`、`sdd-overlay.mjs`）
+- **A2 receipt 判据改 wave 定义指纹**：`recordReview` 写 `wave_fingerprint`（id/strategy/tasks/depends_on），`readCurrentReview` 以其为判据，`plan_hash`/`plan_revision` 降级为审计信息（存量 receipt 回退旧判据）。修复 revise / refresh-hash 后历史 receipt 全部失效且无补录路径；`describeWaves` 新增 `stale_receipt` 诊断（`execution-plan.mjs`）
+- **A3 refresh-hash 同步 recommendation_receipt**：同步 receipt 的 artifacts_hash/contract_hash 并重算 receipt.hash —— 修复 refresh-hash 在其目标场景下自失败（`execution-plan.mjs`）；`stableJson`/`hashObject` 抽到 `hash.mjs` 共享
+
+**根因簇 B — 复利链路断裂**（6 个子项）
+
+- **B1 消费通道**：build-executor Required Inputs 增加 `tf solutions inject --phase cross-phase`（标注为经验提示而非约束）
+- **B2 路径统一**：5 处文档从 `specs/<cap>/learnings.md` 更正为 change 根 `learnings.md`
+- **B3 契约分层**：`schema.yaml` 声明两条产出通道（ce-compound 手工 / promote 自动晋升）与共同消费面 INDEX.md
+- **B4 静默丢弃可见化**：promote 输出「晋升 / 确认 / 跳过」汇总 + 逐条跳过原因
+- **B5 promote 实现修复**：产出文件单 frontmatter 块（原双块，并补回 `## ` 标题前缀）；重复命中真正落盘（INDEX severity 升级 + 条目 `confirmed` 计数）
+- **B6 通道错配修正**：`compound-captured` guard 提示不再指向 `tf solutions capture`（它写全局目录、不创建 learnings.md）；release-archivist 明确 learnings.md 写入方；新增 `templates/learnings.md`
+
+**根因簇 C — 解析器不对称**
+
+- **pytest junit XML 支持**：抽出通用 `parseJunitXml`（maven-surefire 与 pytest 共用）；`parsePytest` 增加 XML 分支；`detectRunner` XML 优先嗅探；错误信息附输入形态指引（`test-record.mjs`）
+
+**协议层**
+
+- build-executor wave 完成协议增加「回写 tasks.md 勾选」；workflow-start 主动串行编排把勾选作为进下一波前置；Artifact Ownership 澄清 tasks.md 勾选状态归属
+- `glaf4-delegation.md` §8 closing 时序协议同步更新
+
+**横展修复**（P3 审查发现的既有缺陷）
+
+- **CLI 入口守卫**：5 处 `process.argv[1]?.includes(...)` 改为 `import.meta.url === pathToFileURL(process.argv[1]).href` —— 原写法使测试文件（如 `solutions-capture.test.mjs`）在 import 时触发 CLI 执行，污染真实 `docs/solutions/`（`solutions-capture/inject/index-gen/promote.mjs`、`prototype-sync.mjs`）
+- **测试隔离**：`ensure-branch.test.mjs` 的 `origin.git` 从固定 `tmpdir()` 路径改为独立随机目录 —— 原写法跨运行残留导致 push 被拒、before 钩子失败、`npm test` exit 1
+- 清理 `docs/solutions/` 中 14 个历史测试污染条目
+
+### Tests
+
+- 新增 18 个用例（A1 勾选归一化、A2 指纹判据与 stale 诊断、A3 refresh-hash 同步、pytest XML、promote 可见化与落盘）；`npm test` 742/742，`npm run test:e2e` 68/68
+
 ## [0.48.0] - 2026-08-21
 
 ### Added（多仓库场景支持，v0.48.0）

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.48.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.49.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.48.0**。
+当前发布版本：**v0.49.0**。
 
 ---
 
@@ -761,7 +761,7 @@ tf execution review changes/my-change --wave foundation --base <sha> --head <sha
 report 本身必须为普通、非空、非符号链接文件。
 
 每一个 wave 均须有当前 `pass` review receipt，才可启动依赖 wave 或进入 closing；
-修订计划会废止旧 receipt。#47 所提出的恢复、切换与手动保存 slash command 尚未实现，
+receipt 绑定该 wave 的定义（v0.49.0 起）：wave 定义未变时，修订计划或刷新 hash 不会废止它。#47 所提出的恢复、切换与手动保存 slash command 尚未实现，
 不能假定有 `/tf:*` 命令。
 
 Delta spec 的规范路径是 `specs/<capability>/spec.md`。扁平的 `specs/<capability>.md` 和根级 `specs/spec.md` 都不会被当作合法规范静默通过。

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.48.0`
+> 当前版本：`v0.49.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 
@@ -66,7 +66,7 @@ prototype/         全局原型（UI 契约真相源）
 docs/
   ├── architecture/  全局架构三层（v0.36.0）：ARCHITECTURE.md / PHYSICAL-MODEL.md / DATABASE.md / API-INDEX.md / INDEX.md / domains/<bc>.md / iterations/vN/（产品级快照）/ baseline.md
   └── solutions/     复利经验库（三层索引：INDEX.md → 分阶段目录 → 经验文件）
-specs/<cap>/        每变更设计/任务/契约 + learnings.md
+specs/<cap>/        每变更规格：spec.md（learnings.md 归 change 根目录）
 STRATEGY.md CONCEPTS.md 策略 / 领域词汇
 ```
 
@@ -155,7 +155,7 @@ tf execution review changes/my-change --wave foundation --base <sha> --head <sha
 report 本身必须为普通、非空、非符号链接文件。
 
 每一个 wave 均须有当前 `pass` review receipt，才可启动依赖 wave 或进入 closing；
-修订计划会废止旧 receipt。#47 所提出的恢复、切换与手动保存 slash command 尚未实现，
+receipt 绑定该 wave 的定义（v0.49.0 起）：wave 定义未变时，修订计划或刷新 hash 不会废止它。#47 所提出的恢复、切换与手动保存 slash command 尚未实现，
 不能假定有 `/tf:*` 命令。
 
 ## OpenAI Codex CLI 安装与升级

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.48.0`
+- Current: `v0.49.0`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

package/docs/solutions/INDEX.md

@@ -2,17 +2,3 @@
 <!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
 | date | phase | domain | type | severity | summary | file |
 |------|-------|--------|------|----------|---------|------|
-| 2026-08-21 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-21-no-summary.md |
-| 2026-08-19 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-19-no-summary.md |
-| 2026-08-18 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-18-no-summary.md |
-| 2026-08-17 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-17-no-summary.md |
-| 2026-08-07 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-07-no-summary.md |
-| 2026-08-06 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-06-no-summary.md |
-| 2026-08-05 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-05-no-summary.md |
-| 2026-08-04 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-04-no-summary.md |
-| 2026-08-03 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-03-no-summary.md |
-| 2026-08-01 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-08-01-no-summary.md |
-| 2026-07-31 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-31-no-summary.md |
-| 2026-07-30 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-30-no-summary.md |
-| 2026-07-29 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-29-no-summary.md |
-| 2026-07-28 | cross-phase | general | insight | medium | (no summary) | cross-phase/2026-07-28-no-summary.md |

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML) + business-analysis (independent requirement/scenario artifact). 26 skills, one install.",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.48.0: auto-sync CLI version with plugin version
+# v0.49.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.48.0"
+PLUGIN_VERSION="0.49.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.48.0.
+Current version: v0.49.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Unified plugin (26 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/guard/checks/compound-captured.mjs

@@ -61,10 +61,13 @@ export function checkCompoundCaptured(changeDir) {
   }
 
   // 3. 未捕获且未豁免 → fail
+  // v0.49.0 §83.3.5：修正通道错配——原提示指向 `tf solutions capture`，但该命令写的是
+  // 全局 docs/solutions/，不会创建 learnings.md（用户照做后 guard 仍 FAIL）。
   failures.push(
-    'Compound capture missing: no learnings.md found in change directory. ' +
-    'Run `tf solutions capture --phase review --domain <d> --type insight --severity medium --summary "..."` ' +
-    'to document session learnings, or `tf state set compound_skipped true` to explicitly skip.'
+    "Compound capture missing: no learnings.md found in change directory. "
+    + "Write this change's session learnings to <change-dir>/learnings.md (format: templates/learnings.md) during closing, "
+    + 'or `tf state set compound_skipped true` to explicitly skip. '
+    + 'Note: `tf solutions capture` writes to global docs/solutions/, not to learnings.md.'
   );
   return { pass: false, failures };
 }

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/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('--')) {