@xulthekl/team-flow 0.48.0 → 0.50.0

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

@@ -1,3 +1,3 @@
-# team-flow v0.48.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.50.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.50.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.48.0",
+  "version": "0.50.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.50.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.50.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.50.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.50.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.50.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,82 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.50.0] - 2026-09-09
+
+### Fixed（hotfix 路径死锁 + 轻量路径仪式成本）
+
+设计来源：`docs/architecture-api-db-design-enhancement-v0.22.md` §85-§88（2026-09-09，fytx-gateway-parent 3 条 workflow-feedback：20260909-103500-guard / 20260909-103600-cli-command / 20260909-112755-sop-flow）
+
+**根因簇 R1 — hotfix/tweak 产物归属链断裂**（closing 死锁）
+
+- **可审计豁免**：`executing:closing` 的 `tasks-complete` 维度对 hotfix/tweak 必然 FAIL（跳过 spec-writer，tasks.md 无原生产出者），与 SKILL「may skip tasks.md」冲突且无豁免路径 → 新增 `tasks_skipped` + `tasks_skip_reason`（与 `test_matrix_skipped` 同构的可审计豁免范式），存量 change 走 legacy 豁免；新增 `scripts/guard/checks/tasks-gate-exemptions.mjs` 作为判定唯一真相源（`tasks-complete.mjs`）
+- **字段贯通**：`state-loader`（BUILTIN_DEFAULTS + writeState 序列化）、`cmd-state`（SETTABLE_FIELDS）、`tf doctor` 卫生巡检（skip 无理由 + 引用文件缺失）三处同步
+- **模式门控**（P4 终检补，LT 2026-09-09 决策）：`tasks_skipped` 仅对 hotfix/tweak 合法——full/auto 置键直接 FAIL 并引导两条出路（产出 `tasks.md` / 先 `tf state set <dir> workflow hotfix|tweak`），消除「文档说不允许、代码却放行」的口径分裂；`auto` 归一化为 full（与 `cmd-state.mjs:163` 同口径，安全侧默认）
+- **横展**：tweak 路径存在同类死锁，一并修；`docs/decision-points.md` 补录 DP-A（v0.29.0 引入时遗漏）并新增「确认点合并」节
+
+**根因簇 R2 — CLI 输入约束未上浮到接口层**（两处）
+
+- **jest 需 `--json`**：解析器要求 JSON 输出但 help/SKILL 未声明 → 顶层 help + build-executor SKILL 补声明
+- **`tf execution review --report` 须在 change overlay 内**：路径约束仅存在于报错文案 → 顶层 help + 5 处 SKILL 补声明（横展 code-reviewer / execution-modes / routing-rules）
+- **清单化扫描**：`scripts/lib/*.mjs` 全部输入校验点逐条核对文档声明，其余约束或报错自解释、或已声明，不额外补文档
+
+**根因簇 R3 — 轻量规定不可执行**
+
+- **contract-builder `## Hotfix Mode` 重写**：适用判据 3 条 + 轻契约骨架 6 章节（Intent Lock / 锁定值表 / 范围栅栏 / Execution Batch / Test Matrix / Approval Gate）+ 移出清单 + 代码锚点 + 质量不变量
+- **release-archivist `## Lightweight Closure` 补回写链前置判据**：arch-merge / prototype-sync / test-merge / compound promotion 四项「何时适用」表，消除 `skip silently` 的适用性歧义（`:164`/`:196` 加回指）
+- **Hotfix/Tweak Exemption 拆块**：hotfix/tweak 块与 full 特例块分离，避免 full 流程被卷入 skip 引导
+
+**根因簇 R4 — 仪式成本未按风险分级**
+
+- **确认点合并**：hotfix 6 个确认点（DP-0 / DP-A / DP-3 / G4 / DP-4 / DP-7）合并为 3 组（变更基线 / 实施授权 / 归档）；先修正 DP-0 口径矛盾（保留 DP-0，`:170` 表述修正）；`arch_design_decision == required` 时 DP-A 不合并；门禁维度与 state 字段不变——减少的是交互轮次，不是门禁强度
+- **`tf arch precheck` 证据工具**：新增 `scripts/lib/arch-precheck.mjs`——输出确定性证据（架构关键词的变更语境命中 / 否定命中 / 仅提及 + 改动文件分类），**退出码恒 0**；architecture-design 据此走 Fast Path（`signal: none` 时只读 brief + precheck 输出，不读全量 `docs/architecture/`），**判断权仍在子代理**（证据与 brief 不符必须回退完整路径）
+
+### Tests & Tooling
+
+- 新增 `tests/lib/guard-tasks-gate.test.mjs`（12 例，含 5 例模式门控）、`tests/lib/arch-precheck.test.mjs`（7 例）
+- `tests/lib/cmd-doctor.test.mjs` 补 `checkChangeTestGates()` 覆盖（9 例，此前该函数无任何测试）
+- 新增 `npm run lint:skills`（此前 lint 脚本存在但未接入任何 npm script）；修正 `behavior-consistency` 规则误报（`route to \`references/...\`` 被当作 skill 名，error 级），6 error → 5 error（余下 5 项为既有 SKILL.md 超行数，记入待办）
+
+## [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.50.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.50.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` 都不会被当作合法规范静默通过。
@@ -809,4 +809,4 @@ Checkpoint 是任务级恢复上下文。`result-ready` handoff 在继续受影
 
 推荐流程：`exploring -> specifying -> bridging -> approved-for-build -> execution plan -> executing -> closing`
 
-hotfix 快速路径：`exploring -> bridging -> approved-for-build -> executing`。hotfix 可以跳过完整的 `proposal.md`、`design.md`、`tasks.md`、`specs/`，但仍然必须先生成一份新的最小 `execution-contract.md`，并完成 DP-3 批准后才能开始实现。
+hotfix 快速路径：`exploring -> bridging -> approved-for-build -> executing`。hotfix 可以跳过完整的 `proposal.md`、`design.md`、`specs/`，但仍然必须先生成一份新的最小 `execution-contract.md`，并完成 DP-3 批准后才能开始实现。`tasks.md` 不允许静默缺失（v0.22 §85）：须由 contract-builder 显式登记 `tasks_skipped=true` + `tasks_skip_reason`，或一并产出最小任务清单。

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.48.0`
+> 当前版本：`v0.50.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/agents/architecture-design.md

@@ -37,7 +37,7 @@ You are an independent architecture designer. You read the change brief, plan, e
 | `mode` | `change`（默认，workflow-start 五项检查）\| `product`（v0.36.0，S3.5 产品级架构设计） |
 | `change_brief_path` | change-brief.md 路径（scope / AC / 技术方向；change 模式必填） |
 | `plan_path` | requirement/vN/plan.md 路径（高阶技术设计段） |
-| `snapshot_path` | docs/architecture/iterations/vN/architecture.md（产品级快照；change 模式主输入，product 模式产出目标） |
+| `snapshot_path` | docs/architecture/iterations/vN/architecture.md（产品级快照；change 模式主输入，product 模式产出目标；**Fast Path 命中时不传**） |
 | `specs_dir` | changes/<name>/specs/ 路径（现有规格，如有） |
 | `global_arch_dir` | docs/architecture/ 路径（As-Is 基线） |
 

package/agents/code-reviewer.md

@@ -15,7 +15,7 @@ You are an independent Code Reviewer. You review code changes for quality, spec
 
 ## Iron Law
 
-You are a reviewer. You did NOT write the code. You read the implementation, compare it against specs/requirements, check code quality, and produce a verdict with findings. You MUST write the review report to disk at the path specified by the orchestration layer (typically `changes/<name>/code-review.md`). Do NOT modify any implementation files — only write the review report.
+You are a reviewer. You did NOT write the code. You read the implementation, compare it against specs/requirements, check code quality, and produce a verdict with findings. You MUST write the review report to disk at the path specified by the orchestration layer — it MUST resolve inside the change review overlay `<change-dir>/.superpowers/sdd/reviews/` (v0.22 §86: the CLI rejects any path outside it). Do NOT modify any implementation files — only write the review report.
 
 ## Inputs
 

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.48.0`
+- Current: `v0.50.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)
@@ -279,7 +279,7 @@ not implemented, so this documentation does not claim `/tf:*` commands.
 
 ### Fast Paths (hotfix / tweak)
 
-- **hotfix** — ≤2 files, no new modules → `exploring -> bridging -> approved-for-build -> executing`. It may skip full planning artifacts such as `proposal.md`, `design.md`, `tasks.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md` plus DP-3 approval before implementation
+- **hotfix** — ≤2 files, no new modules → `exploring -> bridging -> approved-for-build -> executing`. It may skip full planning artifacts such as `proposal.md`, `design.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md` plus DP-3 approval before implementation. `tasks.md` is not silently skipped (v0.22 §85): contract-builder records an explicit `tasks_skipped=true` + `tasks_skip_reason`, or produces a minimal task list
 - **tweak** — ≤4 files, config/docs only → skip planning + bridging, direct edit
 
 ---

package/docs/artifact-contract.md

@@ -45,6 +45,8 @@ Defines:
 - dependency-aware work breakdown
 - completion units that become named execution waves in the execution plan
 
+> **hotfix/tweak 豁免（v0.22 §85）**：该路径跳过 spec-writer，`tasks.md` 默认显式跳过（`tasks_skipped=true` + `tasks_skip_reason`）——**hotfix 由 contract-builder 写入，tweak 由主代理写入**（tweak 不经过 contract-builder）；若 change 需要任务清单，归属 contract-builder 产出。closing 的 `tasks-complete` 门禁按该键豁免。
+
 ### `execution-contract.md`
 
 Defines:

package/docs/decision-points.md

@@ -74,6 +74,16 @@
 - **预期输出**：用户确认归档并批准 delta spec 合并，或要求调整合并范围后再执行
 - **关联 skill**：`team-flow:release-archivist`
 
+## DP-A: 架构设计确认（v0.29.0 §37）
+
+- **编号**：DP-A
+- **名称**：架构设计用户确认门
+- **触发条件**：architecture-design 子代理返回判定结果 + auto-review 完成后、路由 spec-writer 前
+- **所需输入**：架构决策摘要（decision + reason + artifacts）、auto-review verdict
+- **预期输出**：用户确认接受（`dp_a_result: confirmed`）或要求调整（`adjustment_requested`——须经 SendMessage 恢复原子代理修改后重新确认）
+- **关联 skill**：`team-flow:workflow-start`（编排层把关；**非状态转换 guard 维度**）
+- **状态字段**：`dp_a_result` / `dp_a_timestamp` / `dp_a_adjustments`
+
 ## 决策点与 Skill 映射总览
 
 | 编号 | 名称 | 关联 Skill | 阶段 |
@@ -86,3 +96,16 @@
 | DP-5 | 调试升级 | `team-flow:bug-investigator` | 执行 |
 | DP-6 | 验证失败 | `team-flow:release-archivist` | 收尾 |
 | DP-7 | 归档确认 | `team-flow:release-archivist` | 收尾 |
+| DP-A | 架构设计确认 | `team-flow:workflow-start` | 架构 |
+
+## 确认点合并（v0.22 §88.3.1）
+
+以下三组可合并为**一次** AskUserQuestion——减少的是用户交互轮次，**门禁强度不变**（`dp_*` 字段仍须写入，guard 维度不豁免）：
+
+| 合并组 | 触发条件 |
+|--------|----------|
+| DP-0 + DP-A | `arch_design_decision == skipped` |
+| DP-3 + G4 + DP-4 | 契约已产出且 hash 有效 |
+| DP-7 + 代码落地 + G5 | 恒成立 |
+
+`arch_design_decision == required` 时 DP-A 必须独立（用户需单独审架构产物）。

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/docs/state-machine.md

@@ -157,6 +157,6 @@ If the contract changed, the artifacts changed.
 ## Fast-Path Notes
 
 - `hotfix` follows `exploring -> bridging -> approved-for-build -> executing`.
-- `hotfix` may skip full planning artifacts such as `proposal.md`, `design.md`, `tasks.md`, and `specs/`.
+- `hotfix` may skip full planning artifacts such as `proposal.md`, `design.md`, and `specs/`; `tasks.md` requires an explicit `tasks_skipped=true` + `tasks_skip_reason` (v0.22 §85) rather than a silent skip. The key is rejected for `full`/`auto` workflows — declare the mode first (`tf state set <dir> workflow hotfix|tweak`) or produce `tasks.md`.
 - `hotfix` still requires a fresh minimal `execution-contract.md` and explicit DP-3 approval before implementation.
 - `tweak` remains the only path that can jump directly from `exploring` to `approved-for-build`.

package/docs/usage-guide.md

@@ -1,6 +1,6 @@
 # team-flow 使用说明（研发团队版）
 
-> 版本锚点：v0.47.0（26 skills + 17 agents）· 更新日期：2026-08-21
+> 版本锚点：v0.50.0（26 skills + 17 agents）· 更新日期：2026-09-09
 > 读者：使用 team-flow 做日常研发的工程师。不需要你懂插件内部实现，只需要照着路径走。
 > 配套文档：安装细节见 [INSTALL.md](../INSTALL.md)；状态机细节见 [state-machine.md](state-machine.md)；决策点细节见 [decision-points.md](decision-points.md)；平台差异见 [platform-matrix.md](platform-matrix.md)。
 
@@ -164,7 +164,7 @@ workflow-start 在初始化时自动推断（`tf runtime infer`），你也可
 | **hotfix** | ≤2 任务、≤2 文件、不动 schema/API | 跳过需求探索和规划制品，最小契约仍需 DP-3 批准 | test-matrix-complete、执行计划回执 |
 | **tweak** | ≤4 任务的纯配置/文档类 | 直接进 approved-for-build，直接编辑 | 执行计划、逐 wave 审查回执、测试矩阵 |
 
-**注意**：hotfix/tweak 豁免测试矩阵时**必须显式 skip 并写明理由**（`tf state set test_matrix_skipped true` + `test_matrix_skip_reason`），门禁不接受无理由跳过。架构设计判断门（五项检查）**两种模式都不豁免**。
+**注意**：hotfix/tweak 豁免测试矩阵与 `tasks.md` 时**必须显式 skip 并写明理由**（`tf state set test_matrix_skipped true` + `test_matrix_skip_reason`；`tf state set tasks_skipped true` + `tasks_skip_reason`），门禁不接受无理由跳过。架构设计判断门（五项检查）**两种模式都不豁免**。
 
 ### 4.3 决策点（DP）——什么时候需要你拍板
 
@@ -427,6 +427,7 @@ tf prototype branch <prd-vN> | tf prototype deisolate <prd-vN> [--merge]
 tf solutions capture|index-gen|inject|promote
 tf arch init [--mode reconstruction|design]   # 项目架构基线打戳（存量豁免键）
 tf arch show
+tf arch precheck <change-dir> [--json]        # 架构判断门证据（signal none/weak/strong，退出码恒 0）
 tf inject <dir> [--platforms claude,cursor,...]   # 按当前状态生成 phase-guard 注入各平台
 tf config [--resolve-model <profile>]          # mechanical/standard/strong/review 四档
 tf runtime check-update | infer <dir> | guard ... | config ... | asset read <path>
@@ -482,8 +483,7 @@ tf runtime check-update | infer <dir> | guard ... | config ... | asset read <pat
 │   ├── execution-contract.md          # 执行契约（contract_hash）
 │   ├── test-matrix.md                 # 测试矩阵（12 列，test_matrix_hash）
 │   ├── learnings.md                   # 复利经验（closing 门禁要求或显式 skip）
-│   ├── code-review.md / *-review.md   # 各审查报告
-│   └── .superpowers/                  # 运行时 overlay
+│   └── .superpowers/                  # 运行时 overlay（审查报告已迁至 sdd/reviews/）
 │       ├── sdd/                       # execution-plan.json / reviews/ / checkpoints / progress.md
 │       └── test-evidence/             # tf test record 的 runner 原始输出证据
 │
@@ -514,6 +514,8 @@ tf runtime guard check <change-dir> <from> <to> --json
 | `no programmatic test evidence recorded` | 没有 `tf test record` 记录 | 跑测试 → `tf test record <dir> --from <输出文件>` |
 | `recorded-by` 校验失败 | 手工写了 test_result | 手工通道已关闭，必须走 tf test record；或显式 skip+理由 |
 | `test matrix skip reason missing` | skip 了矩阵没写理由 | `tf state set test_matrix_skip_reason "<理由>"` |
+| `tasks skip reason missing` | skip 了 tasks.md 没写理由 | `tf state set tasks_skip_reason "<理由>"` |
+| `tasks_skipped is only valid for hotfix/tweak` | full/auto 路径置了 skip 键 | 产出 tasks.md，或 `tf state set <dir> workflow <hotfix\|tweak>` 先声明模式 |
 | `dp_3_result` / `dp_4_result` 缺失 | DP 决策未记录 | 回到对应决策点完成确认 |
 | `plan revision <N>` 不匹配 | DP-4 记录没引用当前计划版本 | 重新 `tf execution plan`（或 revise） |
 | `base == head` review 被拒 | 空 diff 审查 | 用真实的 wave 起止 commit |
@@ -530,6 +532,7 @@ tf runtime guard check <change-dir> <from> <to> --json
 
 每条门禁都有合法逃生舱，但**必须显式+留痕**：
 - 测试矩阵：`test_matrix_skipped=true` + `test_matrix_skip_reason`
+- tasks.md：`tasks_skipped=true` + `tasks_skip_reason`（**仅 hotfix/tweak**；full/auto 置键会被 `tasks-complete` 直接 FAIL——先 `tf state set <dir> workflow <hotfix|tweak>` 声明模式，或产出 tasks.md）
 - 复利：`tf state set compound_skipped true`
 - 架构 skip：物化 `iterations/vN/SKIPPED` 标记 + 理由
 - 隔离失败：`--force`（会警告）

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.50.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.50.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.50.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.50.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.50.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",
@@ -18,6 +18,7 @@
     "test:e2e:plugin-sync": "node tests/e2e/scripts/plugin-sync.mjs",
     "test:e2e:llm": "TF_E2E_LLM=1 node --test --test-concurrency=1 tests/e2e/workflow/*.test.mjs",
     "validate": "node scripts/validate-artifacts",
+    "lint:skills": "node scripts/lint/lint-skills.mjs",
     "version": "node scripts/team-flow.mjs version $npm_new_version && node scripts/check-version-consistency.mjs && git add -A",
     "check-versions": "node scripts/check-version-consistency.mjs",
     "setup-hooks": "node scripts/install-git-hooks.mjs"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.48.0",
+  "version": "0.50.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/guard/checks/tasks-complete.mjs

@@ -1,15 +1,51 @@
 // scripts/guard/checks/tasks-complete.mjs — verify all tasks in tasks.md are checked off
+//
+// v0.22 §85（workflow-feedback 20260909-103500-guard）：新增 legacy 与显式 skip 两条豁免。
+// 修复前 hotfix/tweak（跳过 spec-writer，无 tasks.md）在 executing:closing 必然 FAIL，
+// 与 workflow-start SKILL 的 "may skip tasks.md" 表述冲突，导致 closing 死锁。
 import fs from 'node:fs';
 import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import {
+  isLegacyChange,
+  fullWorkflowSkipViolation,
+  tasksSkipMissingReason,
+  TASKS_SKIP_REASON_HINT,
+  TASKS_SKIP_FULL_FORBIDDEN_HINT,
+} from './tasks-gate-exemptions.mjs';
 
 /**
  * Check that tasks.md has no unchecked items and at least one completed item.
- * Returns { pass, failures[] }.
+ * Returns { pass, failures[], reason? }.
  */
 export function checkTasksComplete(changeDir) {
+  const state = readState(changeDir);
+
+  if (isLegacyChange(state)) {
+    return { pass: true, failures: [], reason: 'legacy change — initialized before v0.32.0' };
+  }
+
+  if (state.tasks_skipped === 'true') {
+    // v0.22 §85.4（LT 2026-09-09）：full/auto 不允许跳过——tasks.md 是 spec-writer 核心产物。
+    // 与 contract-builder SKILL「full 不得设置 tasks_skipped」及 usage-guide 的口径一致。
+    if (fullWorkflowSkipViolation(state)) {
+      return { pass: false, failures: [TASKS_SKIP_FULL_FORBIDDEN_HINT] };
+    }
+    if (tasksSkipMissingReason(state)) {
+      return { pass: false, failures: [TASKS_SKIP_REASON_HINT] };
+    }
+    return { pass: true, failures: [], reason: `explicitly skipped: ${state.tasks_skip_reason}` };
+  }
+
   const tasksPath = path.join(changeDir, 'tasks.md');
   if (!fs.existsSync(tasksPath)) {
-    return { pass: false, failures: ['tasks.md: missing'] };
+    return {
+      pass: false,
+      failures: [
+        'tasks.md: missing — produce it, or skip explicitly '
+        + '(tf state set <dir> tasks_skipped true && tf state set <dir> tasks_skip_reason "<why>")',
+      ],
+    };
   }
 
   const content = fs.readFileSync(tasksPath, 'utf-8');
@@ -28,4 +64,4 @@ export function checkTasksComplete(changeDir) {
   }
 
   return { pass: true, failures: [] };
-}
+}

package/scripts/guard/checks/tasks-gate-exemptions.mjs

@@ -0,0 +1,49 @@
+// scripts/guard/checks/tasks-gate-exemptions.mjs — v0.22 §85 tasks-complete 门禁豁免
+//
+// 背景（workflow-feedback 20260909-103500-guard）：
+// hotfix/tweak 跳过 spec-writer（workflow-start SKILL.md:172/173），tasks.md 的任务文本
+// 无原生产出者；而 guard 的 executing:closing 仍考核 tasks-complete（guard.mjs:75/82）。
+// 修复前该矛盾导致 closing 死锁，只能由编排层补录 tasks.md 绕过。
+//
+// 本模块与 test-gate-exemptions.mjs 同构：显式跳过优于静默豁免（v0.13 §48 原则），
+// 跳过必须附理由才放行；存量 change（无 schema_version）沿用 legacy 豁免。
+import { isLegacyChange } from './test-gate-exemptions.mjs';
+
+export { isLegacyChange };
+
+/** v0.22 §85：显式跳过 tasks.md 且理由非空（可审计豁免）。 */
+export function hasExplicitTasksSkip(state) {
+  return state?.tasks_skipped === 'true'
+    && typeof state?.tasks_skip_reason === 'string'
+    && state.tasks_skip_reason.trim().length > 0;
+}
+
+/** skip 已置但理由缺失 → 门禁拒绝并引导补理由。 */
+export function tasksSkipMissingReason(state) {
+  return state?.tasks_skipped === 'true' && !hasExplicitTasksSkip(state);
+}
+
+/**
+ * v0.22 §85.4（LT 2026-09-09 决策）：`tasks_skipped` 仅对 hotfix/tweak 合法。
+ * full 的 tasks.md 是 spec-writer 核心产物，必然产出——缺失即流程异常，应 FAIL 暴露而非豁免掩盖。
+ * `auto`/缺失归一化为 full（与 cmd-state.mjs:163 的 auto→full 归一化同口径，安全侧默认）。
+ * 无存量风险：tasks_skipped 是 v0.50.0 新字段。
+ */
+export function isFullWorkflow(state) {
+  const workflow = state?.workflow;
+  return workflow == null || workflow === '' || workflow === 'auto' || workflow === 'full';
+}
+
+/** full/auto 置了 skip → 拒绝，并给出两条可操作出路（不是死锁）。 */
+export function fullWorkflowSkipViolation(state) {
+  return state?.tasks_skipped === 'true' && isFullWorkflow(state);
+}
+
+export const TASKS_SKIP_REASON_HINT =
+  'tasks_skipped=true requires tasks_skip_reason — record it: '
+  + "tf state set <dir> tasks_skip_reason '<why this change needs no tasks.md>'";
+
+export const TASKS_SKIP_FULL_FORBIDDEN_HINT =
+  'tasks_skipped is only valid for hotfix/tweak — full workflow must produce tasks.md. '
+  + 'Either produce tasks.md, or, if this change is truly a hotfix/tweak, '
+  + 'declare the mode first: tf state set <dir> workflow <hotfix|tweak>';