@xulthekl/team-flow 0.49.0 → 0.51.0

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

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.49.0",
+  "version": "0.51.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.49.0",
+  "version": "0.51.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.49.0"
+    "version": "0.51.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.49.0",
+  "version": "0.51.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.49.0"
+    "version": "0.51.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.49.0",
+      "version": "0.51.0",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.51.0] - 2026-09-09
+
+### Fixed（CLI 静默失效治理：仓清单 / 白名单 / 严重度序）
+
+设计来源：`docs/architecture-api-db-design-enhancement-v0.23.md` §91-§93（2026-09-09，emp-auth 4 条 workflow-feedback：20260909-101814 / 101815 / 101816 / 104554）
+
+**R1 — severity 有序等级集中化**（`tf solutions promote` 漏晋升 critical）
+
+- **唯一真相源**：新增 `scripts/lib/severity.mjs`（`SEVERITY_ORDER` / `SEVERITY_LADDER` / `severityRank` / `meetsMinSeverity` / `nextSeverity`），取值域扩展为 `critical | high | medium | low`
+- **修复三处同时失效**：晋升判定用集合相等 `severity === 'high' || 'medium'` → `meetsMinSeverity(severity, 'medium')`；升级阶梯补 critical 封顶；`SEVERITY_ORDER` 两处重复定义删除并补 critical 键（原先 critical 排序垫底、inject top-5 优先排除）
+- **入口闸**：`tf solutions capture --severity` 新增取值校验（非法值报错并列出合法取值）
+- **防模板污染**：`parseFrontmatter` 剥离行尾注释（模板注释被逐字复制时会污染取值）
+- 规范同步：`templates/learnings.md` / `release-archivist`（SKILL + closing-procedures）/ `ce-compound`（promotion-rules + three-tier-index + write-flow）
+
+**R2 — 仓清单解析统一**（`tf execution review` 嵌套仓找不到、`tf isolate` 静默降级为空壳）
+
+- **统一入口**：`git-utils.resolveCodeRepos`（config `repo_layout.repos` 权威 → 两层探测 fallback）、`listCodeReposDeep`（支持 `service/<repo>` 等两层布局）、`parsePorcelainPaths`（porcelain 解析唯一实现）
+- **格式兼容**：`repo_layout.repos` 的 key/value 逐序尝试（相对路径 / 绝对路径 / 人类描述），命中判据为「目录存在」+ 返回 `isGitRepo` 供消费方分流
+- **禁止静默降级**：config 声明 `mode=multi-repo` 却解析不到 git 仓时 `tf isolate` 退出非 0（`--force` 可显式降级）
+- **报错可操作**：review receipt 的 SHA 不在任何已扫描仓时，报错附扫描清单与 `--repo` 指引
+- **消费者闭环**：`tf deisolate` 的 `detectCaseA` 复用两层探测（`excludeNonRepoDirs: false` 与创建方口径对齐），嵌套仓与怪名仓（`data`/`prototype`/`docs/*`）不再漏检
+- 消费方改造：`ensure-branch` / `execution-plan` / `conventions-generator`（嵌套探测）/ `glaf4-delegation`（复用解析器，修 `Object.values(repos)` 把人类描述当路径）
+
+**R3 — arch-merge 白名单机制修复**（告警与实际提交行为不一致）
+
+- **判定侧**：`detectUntouchedDirtyFiles` 改用共享 `parsePorcelainPaths`（原 `^\S+\s+` 漏匹配 ` M path`，导致本次 touch 的文件被误报为「非本次 touch 的脏文件」）
+- **提交侧**：`git commit -- <白名单>` 限定边界（裸 `git commit` 会卷走索引中已暂存的外部文件）
+- **事后断言**：回读 `git show --name-only` 与白名单比对，不一致则 WARN
+
+**质量**：P3 审查发现并修复 5 项（含 `glaf4-delegation` 设计承诺未落地）；P4 两轮评审（skill-reviewer FAIL→PASS，8 项修复；plugin-validator FAIL→FAIL→PASS，闭环 `tf deisolate` 断链与 `NON_REPO_DIRS` 口径回归）；**807/807 测试通过**。
+
+## [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 冻结边界与复利链路修复）

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.49.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.51.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.49.0**。
+当前发布版本：**v0.51.0**。
 
 ---
 
@@ -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.49.0`
+> 当前版本：`v0.51.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

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.49.0`
+- Current: `v0.51.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/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.49.0",
+  "version": "0.51.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.49.0: auto-sync CLI version with plugin version
+# v0.51.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.49.0"
+PLUGIN_VERSION="0.51.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.49.0.
+Current version: v0.51.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.49.0",
+  "version": "0.51.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.49.0",
+  "version": "0.51.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/ensure-branch.mjs

@@ -6,16 +6,19 @@
 //
 // Usage: node ensure-branch.mjs <change-dir> [change-name] [--force]
 //
-// 布局识别（来源：workflow-feedback 2026-08-01 #100009）：
-//   Case A 多仓库工作区 —— change-dir 形如 <root>/changes/<name>，且 <root> 下
-//     存在含 .git 的直接子目录（真正的业务代码仓库，如 bff-*/ui-*/prototype/）。
-//     工作区根本身往往只是近空壳 git 仓库（仅跟踪 .gitignore，无 remote）。旧实现
-//     把 change-dir 当代码仓库、worktree 建在 ../，结果是空工作区副本，实现子代理
-//     看不到任何参考代码。新实现为每个代码仓库在 <root>/.worktrees/<change>/<repo>
-//     建立 worktree（基于各仓库当前分支），实现子代理进入 <root>/.worktrees/<change>/
-//     即可看到与主工作区一致的目录结构和全部参考代码。
-//   Case B 单代码仓库（遗留兼容）—— 不满足 Case A 时回退到旧行为：把 change-dir
-//     当代码仓库，worktree 建在 ../<repo>-<name>。保证单仓库项目不被破坏。
+// 布局识别（来源：workflow-feedback 2026-08-01 #100009；v0.23 §92.3.4/§92.3.6 重构）：
+//   仓清单统一由 git-utils.resolveCodeRepos 解析（config 权威 → 两层探测 fallback），
+//   本文件不再自行枚举目录。
+//   Case A 多仓库工作区 —— change-dir 形如 <root>/changes/<name>，且解析出 ≥1 个代码仓库
+//     （含 <root>/<repo> 与 <root>/service/<repo> 两种布局）。工作区根本身往往只是近空壳
+//     git 仓库（仅跟踪 .gitignore，无 remote）。旧实现把 change-dir 当代码仓库、worktree
+//     建在 ../，结果是空工作区副本，实现子代理看不到任何参考代码。现为每个代码仓库在
+//     <root>/.worktrees/<change>/<repo> 建立 worktree（基于各仓库当前分支），实现子代理
+//     进入 <root>/.worktrees/<change>/ 即可看到与主工作区一致的目录结构和全部参考代码。
+//   Case B 单代码仓库（遗留兼容）—— 无 repo_layout 声明或声明为 single 时回退旧行为：
+//     把 change-dir 当代码仓库，worktree 建在 ../<repo>-<name>。保证单仓库项目不被破坏。
+//   硬失败（v0.23 §92.3.6）—— config 声明 mode=multi-repo 却解析不到任何代码仓库时退出
+//     非 0（此前会静默降级为 Case B，建出空壳 worktree 且代码落到共享分支）。--force 可显式降级。
 //
 // Security: every git invocation uses execFileSync with a LITERAL command
 // ('git') and a LITERAL argument array (no shell, no string-form command) — the
@@ -25,8 +28,9 @@
 // branch names are additionally sanitized to git-legal characters before use.
 import { execFileSync } from 'node:child_process';
 import { resolve, basename, join } from 'node:path';
-import { detectWorkspaceRoot } from './lib/git-utils.mjs';
-import { readdirSync, existsSync, appendFileSync, readFileSync } from 'node:fs';
+import { detectWorkspaceRoot, resolveCodeRepos } from './lib/git-utils.mjs';
+import { loadConfig } from './lib/config-loader.mjs';
+import { existsSync, appendFileSync, readFileSync } from 'node:fs';
 
 const rawChangeDir = process.argv[2];
 // 第三个位置参数是可选 change-name；若它其实是 '--force' 之类的开关则忽略，避免把
@@ -107,21 +111,6 @@ function checkSharedBranch(repoDir) {
   }
 }
 
-// 枚举 root 下含 .git 的直接子目录（= 代码仓库），按目录名排序保证确定性。
-// .git 可能是目录（普通仓库）或文件（worktree/submodule 链接），existsSync 均覆盖。
-function listCodeRepos(root) {
-  let entries;
-  try {
-    entries = readdirSync(root, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((e) => e.isDirectory() && existsSync(join(root, e.name, '.git')))
-    .map((e) => e.name)
-    .sort();
-}
-
 // 确保 <root>/.gitignore 含忽略 .worktrees/ 的行，已有则不重复追加。
 function ensureWorktreeGitignore(root) {
   const gitignorePath = join(root, '.gitignore');
@@ -300,14 +289,51 @@ function runSingleRepo() {
   process.exit(1);
 }
 
-// 主流程：布局识别后分发（来源：workflow-feedback 2026-08-01 #100009）。
+// 主流程：布局识别后分发（来源：workflow-feedback 2026-08-01 #100009；
+// v0.23 §92.3.4/§92.3.6：仓清单统一走 resolveCodeRepos，config 声明与实况矛盾时硬失败）。
 const workspaceRoot = detectWorkspaceRoot(changeDir);
-const codeRepos = workspaceRoot ? listCodeRepos(workspaceRoot) : [];
+const config = workspaceRoot ? loadConfig(workspaceRoot) : null;
+const { repos: codeRepos, unresolved, source } = workspaceRoot
+  ? resolveCodeRepos(workspaceRoot, config)
+  : { repos: [], unresolved: [], source: 'probe' };
+
+// v0.23 §92.3.2：repo_layout.repos 条目可能是 monorepo 风格的 Java 模块（无 .git），
+// 无法建 worktree —— 隔离只对 git 仓生效，非 git 条目跳过并告警（不静默）。
+const gitRepos = codeRepos.filter(r => r.isGitRepo);
+const nonGitRepos = codeRepos.filter(r => !r.isGitRepo);
 
-if (workspaceRoot && codeRepos.length > 0) {
+if (workspaceRoot && gitRepos.length > 0) {
   // Case A：多仓库工作区。
-  runMultiRepo(workspaceRoot, codeRepos);
+  if (unresolved.length > 0) {
+    console.error(`ensure-branch: ${unresolved.length} 条 repo_layout.repos 声明无法解析为路径（已忽略）：`
+      + unresolved.map(u => `\n    - ${u.key}`).join(''));
+  }
+  if (nonGitRepos.length > 0) {
+    console.error(`ensure-branch: ${nonGitRepos.length} 个声明项非 git 仓库（无法建 worktree，已跳过隔离）：${nonGitRepos.map(r => r.relPath).join(', ')}`);
+  }
+  console.error(`ensure-branch: repo list resolved from ${source}（${gitRepos.length} 个）: ${gitRepos.map(r => r.relPath).join(', ')}`);
+  runMultiRepo(workspaceRoot, gitRepos.map(r => r.relPath));
+} else if (config?.repo_layout?.mode === 'multi-repo') {
+  // v0.23 §92.3.6：config 声明 multi-repo 却解析不到任何代码仓库 → 硬失败，禁止静默降级。
+  // 历史缺陷：此时会走 Case B，把 change-dir 当代码仓库、建出归属根仓的空壳 worktree，
+  // 实现子代理回到主工作区直接改共享分支（emp-auth feedback 2026-09-09）。
+  console.error('ensure-branch: config 声明 repo_layout.mode=multi-repo，但未解析出任何代码仓库 —— 拒绝按单仓库就地实施。');
+  console.error(`  workspace root : ${workspaceRoot}`);
+  console.error(`  config         : ${join(workspaceRoot, '.team-flow', 'team-flow.config.json')}`);
+  if (unresolved.length > 0) {
+    console.error(`  无法解析的声明（${unresolved.length} 条）：${unresolved.map(u => u.key).join(', ')}`);
+    console.error('  提示：key 应为相对工作区根的仓库路径（如 service/infra-emp-auth），或 value 为仓库绝对路径。');
+  } else {
+    console.error('  提示：repo_layout.repos 为空，或路径未指向含 .git 的目录；可运行 tf repo-layout detect 重建。');
+  }
+  console.error('  如确认要在共享分支就地实施，请显式传 --force。');
+  if (!force) process.exit(1);
+  console.error('ensure-branch: WARNING — --force given; falling back to single-repo behavior.');
+  runSingleRepo();
 } else {
-  // Case B：不满足 Case A → 回退单代码仓库行为，保证单仓库项目不被破坏。
+  // Case B：真单仓库（无 config，或 config.mode=single）→ 保持既有行为。
+  if (!config?.repo_layout?.mode) {
+    console.error('ensure-branch: 未检测到 repo_layout 配置，按单仓库处理；多仓库项目请先运行 tf repo-layout detect <root>。');
+  }
   runSingleRepo();
 }

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: [] };
-}
+}