@xulthekl/team-flow 0.31.0 → 0.32.2

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

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

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "description": "Unified workflow plugin: team-flow + compound-engineering core subset + architecture-design + prototype + workflow-orchestrator + workflow-bootstrap + e2e + session-handoff + workflow-feedback. 23 skills + 15 agents, one install.",
+  "description": "Unified workflow plugin: team-flow + compound-engineering core subset + architecture-design + prototype + workflow-orchestrator + workflow-bootstrap + e2e + session-handoff + workflow-feedback. 24 skills + 15 agents, one install.",
   "owner": {
     "name": "LT",
     "url": "https://github.com/LT"
@@ -8,8 +8,8 @@
   "plugins": [
     {
       "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. 23 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.31.0",
+      "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback. 24 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
+      "version": "0.32.2",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.31.0",
+  "version": "0.32.2",
   "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). 24 skills + 15 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.31.0",
+  "version": "0.32.2",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",
@@ -26,7 +26,7 @@
   "interface": {
     "displayName": "team-flow",
     "shortDescription": "Spec-first workflow with guarded execution.",
-    "longDescription": "A self-contained Codex workflow plugin with nine skills for intent exploration, planning artifacts, execution contracts, TDD execution, review gates, systematic debugging, closure, and delta spec sync.",
+    "longDescription": "A self-contained Codex workflow plugin with 24 skills for intent exploration, planning artifacts, execution contracts, TDD execution, review gates, systematic debugging, closure, and delta spec sync.",
     "developerName": "MageByte",
     "category": "Developer Tools",
     "composerIcon": "./assets/icon.svg",

package/.cursor-plugin/marketplace.json

@@ -5,13 +5,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.31.0"
+    "version": "0.32.2"
   },
   "plugins": [
     {
       "name": "team-flow",
       "source": ".",
-      "description": "Unified workflow plugin: team-flow + compound-engineering core subset + architecture-design + prototype. 17 collaborative skills."
+      "description": "Unified workflow plugin: team-flow + compound-engineering core subset + architecture-design + prototype. 24 skills + 15 agents."
     }
   ]
 }

package/.cursor-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "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). 23 skills + 15 agents, one install.",
-  "version": "0.31.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). 24 skills + 15 agents, one install.",
+  "version": "0.32.2",
   "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.31.0"
+    "version": "0.32.2"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, and local HTML prototyping.",
-      "version": "0.31.0",
+      "version": "0.32.2",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md · team-flow
 
-> team-flow 统一插件 = **team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 Playwright E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同（23 skills + 15 agents），支持 9 安装面（Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, Trae, ima-copilot）。
+> team-flow 统一插件 = **team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 Playwright E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同（24 skills + 15 agents），支持 9 安装面（Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, Trae, ima-copilot）。
 
 ## What This Is
 
@@ -12,7 +12,7 @@
 
 ### 身份与依赖关系
 
-- **team-flow**（本插件）：Claude Code / Cursor 等宿主的插件实体（`plugin.json` name = `team-flow`），包含 23 个 skills + 15 个 agents + hooks + templates
+- **team-flow**（本插件）：Claude Code / Cursor 等宿主的插件实体（`plugin.json` name = `team-flow`），包含 24 个 skills + 15 个 agents + hooks + templates
 - **@xulthekl/team-flow**（npm 底座包）：team-flow 的 CLI 工具层（`package.json` name = `@xulthekl/team-flow`，bin = `tf` / `team-flow`），提供状态机、校验、复利 CLI 等运行时能力
 - 关系：team-flow 插件 **包含** @xulthekl/team-flow npm 包作为底座（同一仓库、同一版本）。skills 中的 `tf ...` 调用的是已全局安装的 @xulthekl/team-flow CLI，版本由 session-start hook 自动同步
 - 历史身份（已废弃）：`spec-superflow`（npm 包名，0.11.0 后停止发布）/ `ssf`（CLI 前缀）/ `.spec-superflow.yaml`（状态文件）—— 详见设计增强方案 v0.9 §27
@@ -33,7 +33,7 @@ node --test tests/e2e.test.mjs --test-name-pattern="parseDeltaSpec"
 npm run validate
 ```
 
-## 能力概览（九套合一，23 skills）
+## 能力概览（九套合一，24 skills）
 
 ### 1. team-flow（底座，9 skills）
 spec 驱动开发过程。8 态变更机：`exploring → specifying → bridging → approved-for-build → executing → closing`（另有 `debugging` 侧路径 + `abandoned` 终态）。

package/CHANGELOG.md

@@ -6,6 +6,75 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.32.2] - 2026-08-03
+
+### Fixed（C1 死锁链修复三件套，设计见工作区级文档 team-flow-workspace/docs/plan/v0.32.2-hook-and-gate-fix.md）
+
+#### pre-tool-use-guard 路径化（P1-44，死锁环1）
+- **hooks/pre-tool-use-guard**：新增产物区豁免——Write/Edit/MultiEdit 目标在活动 change 目录内（architecture/、specs/、proposal/design/tasks、contract、test-matrix、reviews 等工作流产物）→ 全状态放行；change 目录外（实现代码）→ 维持状态门禁（仅 approved-for-build/executing/debugging）。修复 exploring/specifying/bridging 阶段产物写入被一刀切拦截、LLM 被迫 Bash 绕过（写入彻底脱管）的死锁
+- `.team-flow.yaml` 本身恒受状态门禁（state 禁写红线保留）
+- macOS symlink 归一化（/private/var ↔ /var 双侧对齐），防物理/逻辑路径前缀失配
+
+#### exploring→specifying 门禁时序（P3-10，死锁环2）
+- **scripts/guard/guard.mjs**：`exploring:specifying` 移除 `artifacts-exist` 维度（四件规划产物由 spec-writer 在 specifying 阶段生成，转换前要求属鸡生蛋死锁）；产物齐全性由 `specifying:bridging` 独家负责（该维度本就挂着，单一责任人）
+
+#### hooks 版本同步（P2-40，发版中断根治）
+- **scripts/lib/cmd-version.mjs**：hooks/session-start 纳入自动同步——头部注释行 pattern 后缀改通配（根因：旧 pattern 写死 `: conditional injection` 措辞，hook 注释演进后失配，v0.27.2~v0.32.1 四次发版中断）+ PLUGIN_VERSION 变量首次纳入同步
+- 顺带修复：major 版本号硬编码为 0 的缺陷（v1.0.0 里程碑会静默写成 0.x.y）——解构补 major + 全部 replacement 改 %MAJOR% 占位 + 全部 pattern 首段泛化（`0\.` → `\d+`，支持 1.x 匹配）
+
+### Tests
+- tests/lib/hook-pre-tool-use.test.mjs：路径化判定 9 场景矩阵（产物区放行/代码区拦截/构建态/禁写红线/无 change/非 Write 工具/相对路径）
+- tests/lib/cmd-version-hooks.test.mjs：hooks 双位置同步 + 幂等 + pattern 防腐化 3 例
+- guard.test.mjs / guard-dimensions.test.mjs：artifacts-exist 断言迁移至 specifying→bridging + exploring→specifying 新语义断言
+- 全量回归：lib 498/498 + Tier1 e2e 68/68 + check-versions ✅
+
+## [0.32.1] - 2026-08-03
+
+> 版本号说明：0.32.0 因 `.npmignore` 缺失 `/tests/` 排除项，误将 61.8M e2e 基线归档打入 tarball（72MB），发布后 30 分钟内撤回；npm 版本号一经发布不可复用，故以 **0.32.1** 重发（内容完全一致 + 打包修复）。
+
+### Added（设计增强方案 v0.13 §47-§53 测试门禁硬化——C1-domain-policy 事件修复）
+
+#### 豁免键修正（v0.13 §48）
+- **scripts/lib/state-loader.mjs**：BUILTIN_DEFAULTS 新增 `test_matrix_skip_reason` / `test_evidence_path`；`schema_version` 不进 defaults（字段缺失 = 存量信号）；writeState 条件序列化 `schema_version`
+- **scripts/lib/cmd-state.mjs**：init 分支仅在 change 创建（状态文件尚不存在）时打戳 `schema_version: 1`（rebuild/set 不追加）；SETTABLE_FIELDS 移除 `test_result`、新增 `test_matrix_skip_reason`；`test_result`/`schema_version` 手工 set 被拒并给引导
+- **scripts/guard/checks/test-gate-exemptions.mjs**：新建共享豁免判定模块（legacy/skip 语义唯一真相源，防三个测试门禁漂移）
+- **scripts/guard/checks/test-matrix-complete.mjs**：重写——legacy/skip 双豁免；删除内容型豁免（contract 无 `## Test Matrix` 段即 PASS）与"无 contract → PASS"；删除 hash null 短路；skip 必附理由
+
+#### 门禁前移（v0.13 §49）
+- **scripts/guard/checks/test-matrix-ready.mjs**：新建入口维度（矩阵存在非空 + contract 声明段 OR 显式 skip 附理由；legacy 豁免）
+- **scripts/guard/guard.mjs**：full `approved-for-build:executing` 新增 `test-matrix-ready`（hotfix/tweak 沿用 §45.3 豁免不挂）
+
+#### tests-passing 证据程序化（v0.13 §50，BUG-A 政策修正）
+- **scripts/lib/test-record.mjs**：新建 `tf test record` 命令——maven-surefire（控制台汇总行 + XML 报告目录）/jest(--json)/pytest 解析器 + auto 识别；结构化 `test_result`（recorded-by=tf-test-record）+ 证据落盘 `.superpowers/test-evidence/`；fail 结果 exit 1；无手工自述通道
+- **scripts/guard/checks/tests-passing.mjs**：重写——非存量 change 只认程序化结构化记录 + 证据文件存在性；dp_6_result 去证据化（BUG-A 通道仅存量保留）；total=0 空真拒绝；skip 必附理由
+- **scripts/team-flow.mjs**：注册 `test` 命令 + HELP
+
+#### review 硬化 + 巡检扩展（v0.13 §51-§52）
+- **scripts/lib/execution-plan.mjs**：validateReviewRange 禁止 base==head（空 diff review 非法，C1 现场 6 个 receipt 全为空 diff）；receipt 新增可选 `tests` 统计字段（非负整数校验）
+- **scripts/lib/cmd-execution.mjs**：review 新增 `--tests-total/--tests-passed/--tests-failed`（须同时提供）
+- **scripts/lib/cmd-doctor.mjs**：新增 checkChangeTestGates 巡检（skip_reason 配对 + arch_review_report/test_evidence_path 引用完整性）
+- **scripts/lib/cmd-validate.mjs**：test-matrix 双向互锁（契约段↔矩阵文件，非存量非 skip 时 ERROR）+ hash 漂移警告
+
+### Changed（SOP 硬化批次，v0.13 §52）
+- **agents/contract-builder.md**：skills 补 test-strategy 预加载（修复矩阵生成者的预加载断点）+ test-matrix.md 所有权声明
+- **skills/contract-builder/SKILL.md**：Test Matrix Generation 升 MUST（full workflow）+ skip 必附理由
+- **skills/release-archivist/SKILL.md**：Step 1 零测试条款（0 tests ≠ PASS）+ tf test record 程序化记录；Step 2b 矩阵缺失对非存量 change FAIL（删除静默 SKIP）；dp_6 去证据化说明
+- **skills/workflow-start/SKILL.md**：build-executor 返回验证补测试文件检查（SDD/full）；contract-builder 路由声明矩阵必产；入口门禁前移引导
+- **skills/workflow-start/references/routing-rules.md**：Route to glaf4-tests 归位（触发主体 = contract-builder；可选的是工具选择，矩阵生成本身强制）
+- **skills/session-handoff/SKILL.md**：Guardrail #6 报告生成纪律（LLM 重构报告必须现场核对，C1 报告 10+ 处失真教训）
+
+### Fixed（P3 审查横展修复）
+- **skills/workflow-start/SKILL.md**：路由优先级块修正 v0.30.0 引入的存量矛盾——删除"hotfix/tweak 架构设计可跳过（自动写 skipped）"例外句（与 Fast-Path 5 处"不豁免"条款及 v0.9 §26 冲突，且无对应代码行为）；skill-reviewer F-1
+- **skills/release-archivist/SKILL.md** + **skills/contract-builder/SKILL.md**：Lightweight Closure / Hotfix Mode 补非存量 change tests-passing 门禁指引（skip+reason 或 tf test record），修复轻量收尾必然撞门禁的断点；skill-reviewer W-0
+- **agents/contract-builder.md**：DON'T 列表终态标记条款反向措辞修正；skill-reviewer W-2
+- **计数同步**：12 处 manifest/文档的 skill 计数修正为 24 skills（v0.31.0 新增 test-strategy 时漏更的遗留债）；plugin-validator
+
+### Tests
+- tests/lib/schema-version.test.mjs（打戳语义 5 例）、test-record.test.mjs（解析器 9 例 + CLI 6 例）、review-hardening.test.mjs（base==head 拒绝 + 统计字段 4 例）
+- tests/e2e/deterministic/guard-dimensions.test.mjs：test-matrix-complete 重写为 v0.13 六步判定（9 例）+ test-matrix-ready 新 describe（6 例）+ tests-passing 程序化/skip/负向用例
+- tests/lib/cmd-state.test.mjs：test_result/schema_version 拒设用例 + skip_reason 可设用例；tests/lib/guard.test.mjs：closing 前置夹具适配（legacy 夹具直写 yaml 模拟旧 CLI）
+- 全量回归：lib 486/486 + Tier1 e2e 67/67
+
 ## [0.31.0] - 2026-08-01
 
 ### Added（设计增强方案 v0.12 §40-§46 测试矩阵驱动开发 + 测试复利闭环）

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.31.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.32.2 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/HANDOFF.md

@@ -23,7 +23,7 @@
 | **e2e**（端到端测试） | 整个 skill | 1 |
 | **session-handoff**（session 交接） | 整个 skill | 1 |
 | **workflow-feedback**（反馈闭环） | 整个 skill | 1 |
-| **合计** | | **23 skills + 15 agents** |
+| **合计** | | **24 skills + 15 agents** |
 
 - 零运行时外部依赖（team-flow 底座自包含）。
 - prototype 额外**零外部依赖、可离线**（自包含 HTML + 页面内 Tweaks 控件，无 CDN）。

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.31.0**。
+当前发布版本：**v0.32.2**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.31.0`
+> 当前版本：`v0.32.2`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 
@@ -34,7 +34,7 @@
 git clone <your-repo> && <cli> plugin install ./team-flow
 ```
 
-> 不同宿主 CLI 的安装子命令略有差异（如 Claude Code 为 `/plugin add`，Cursor 为 `plugin install`）。以宿主文档为准；本插件提供单一 `plugin.json`，一次安装即加载全部 23 个 skills。
+> 不同宿主 CLI 的安装子命令略有差异（如 Claude Code 为 `/plugin add`，Cursor 为 `plugin install`）。以宿主文档为准；本插件提供单一 `plugin.json`，一次安装即加载全部 24 个 skills。
 
 ## 配置（插件层扩展字段）
 

package/agents/contract-builder.md

@@ -28,6 +28,9 @@ color: magenta
 tools: ["Read", "Bash", "Grep", "Glob", "Write", "Edit"]
 skills:
   - contract-builder
+  # v0.13 §52 B1：test-matrix.md 由本 agent 生成，需预加载测试设计方法论
+  #（design_method 选择/复杂度分级/对抗验证），修复 v0.31.0 的预加载断点。
+  - test-strategy
 ---
 
 You are an independent Contract Builder. You compress approved planning artifacts into a single execution handshake: `execution-contract.md`. You operate in an independent context with Write capability for the contract file only.
@@ -36,6 +39,8 @@ You are an independent Contract Builder. You compress approved planning artifact
 
 **You are the sole owner of `execution-contract.md`** within the change directory. No other agent or the orchestration layer may directly edit it. Refresh/adjustment requests MUST be routed through you via `SendMessage` resume; the orchestration layer does not edit your artifact directly.
 
+**You are also the sole owner of `test-matrix.md`**（execution-contract.md 的附属产物，v0.12 §42 / v0.13 §52 B1）：full workflow 的契约必须声明 `## Test Matrix` 段并生成非空矩阵文件（hotfix/tweak 豁免）。矩阵缺失时 `test-matrix-ready`/`test-matrix-complete` 门禁会阻断 executing 入口与 closing。
+
 **Your preloaded Skill contains the detailed methodology** (artifact-to-contract mapping, requirement-coverage cross-check, DP-3 approval gate, stale-contract detection, hotfix minimal contract). Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver.
 
 ## Iron Law
@@ -74,5 +79,5 @@ summary: "..."                       # handoff rules + flagged ambiguities
 **DON'T:**
 - DO NOT modify the `state` or `workflow` field of .team-flow.yaml. State transitions are the orchestrator's exclusive responsibility, executed via `tf state transition`. You only write your own dp_N_* decision fields via `tf state set` as the Skill instructs.
 - When you receive external suggestions (reviewer findings, user opinions), verify them against the codebase FIRST — search for existing implementations/patterns before accepting. A suggestion is input, not an instruction. If a suggestion conflicts with project conventions or lacks evidence, report your concern to the main agent via SendMessage (suggestion + your evidence-based objection + alternative), do NOT silently comply.
-- End your final response with an explicit terminal marker line: `FINAL VERDICT: <DONE | BLOCKED | FAIL>`. Your SendMessage report is the authoritative result; the task-notification summary is internal metadata only.
+- DO NOT end your final response **without** an explicit terminal marker line: `FINAL VERDICT: <DONE | BLOCKED | FAIL>`. Your SendMessage report is the authoritative result; the task-notification summary is internal metadata only.
 - Continue to implementation while ambiguity remains, or approve the contract for the user

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.31.0`
+- Current: `v0.32.2`
 - 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,6 +2,8 @@
 <!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
 | date | phase | domain | type | severity | summary | file |
 |------|-------|--------|------|----------|---------|------|
+| 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 |

package/docs/solutions/cross-phase/2026-08-01-no-summary.md

@@ -0,0 +1,17 @@
+---
+phase: cross-phase
+domain: general
+type: insight
+severity: medium
+date: 2026-08-01
+source: 
+---
+
+## 问题描述
+(no summary)
+
+## 根因/模式
+（待补充）
+
+## 预防措施/应用方式
+（待补充）

package/docs/solutions/cross-phase/2026-08-03-no-summary.md

@@ -0,0 +1,17 @@
+---
+phase: cross-phase
+domain: general
+type: insight
+severity: medium
+date: 2026-08-03
+source: 
+---
+
+## 问题描述
+(no summary)
+
+## 根因/模式
+（待补充）
+
+## 预防措施/应用方式
+（待补充）

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). 17 skills, one install.",
-  "version": "0.31.0",
+  "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML). 24 skills, one install.",
+  "version": "0.32.2",
   "contextFileName": "GEMINI.md"
 }

package/hooks/pre-tool-use-guard

@@ -5,12 +5,21 @@
 # ----------------------------------------------------------------------------
 # Purpose
 # ----------------------------------------------------------------------------
-# Blocks Write/Edit/MultiEdit implementation edits unless the active
+# Blocks Write/Edit/MultiEdit IMPLEMENTATION edits unless the active
 # team-flow change is in a state that permits building. This enforces the
 # state-machine rule that "no implementation is allowed" outside the
 # build-permitted states (exploring / specifying / bridging must finish and be
 # approved before any code is written).
 #
+# v0.32.2 (P1-44): path-based artifact-zone exemption. The workflow itself
+# REQUIRES artifact writes during non-build states (architecture/*.md while
+# exploring, proposal/specs/design/tasks while specifying, contract/matrix
+# while bridging). The original state-only gate blocked those too, forcing
+# LLMs to bypass via Bash writes (which are not gated at all). Now writes
+# INSIDE the active change directory (artifact zone) are allowed; only writes
+# OUTSIDE it (implementation code) remain state-gated. `.team-flow.yaml`
+# itself stays state-gated even inside the change dir (state 禁写红线).
+#
 # ----------------------------------------------------------------------------
 # Guard logic
 # ----------------------------------------------------------------------------
@@ -19,6 +28,9 @@
 #        - Not found  -> ALLOW (no active team-flow change in scope).
 #   2. Read the current workflow state from the `state:` line of the yaml.
 #   3. For Write/Edit/MultiEdit only:
+#      3a. Target path inside the change directory (artifact zone) AND not
+#          `.team-flow.yaml` -> ALLOW (workflow artifacts are state-agnostic).
+#      3b. Otherwise by state:
 #        - state in {approved-for-build, executing, debugging} -> ALLOW
 #        - any other state (exploring/specifying/bridging/closing/abandoned/
 #          unknown) -> BLOCK with an explanatory reason.
@@ -101,13 +113,42 @@ state="$(grep -E '^[[:space:]]*state:[[:space:]]*' "$yaml" 2>/dev/null \
 # Could not determine state -> defensive allow (never block on parse failure).
 [ -n "$state" ] || allow
 
+# --- v0.32.2 (P1-44): artifact-zone exemption ------------------------------
+# Writes targeting the active change directory itself are workflow artifacts
+# (architecture/, specs/, proposal/design/tasks, contract, test-matrix,
+# reviews, learnings...) — required by the workflow in EVERY state, so they
+# are exempt from the build-state gate. Only writes outside the change dir
+# (implementation code) are gated. `.team-flow.yaml` remains gated (state 禁写).
+file_path="$(printf '%s' "$INPUT" \
+  | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' \
+  | head -1 \
+  | sed 's/.*:"//; s/"$//')"
+# Relative target -> absolutize against $PWD for a stable prefix comparison.
+case "$file_path" in
+  ''|/*) : ;;
+  *) file_path="$PWD/$file_path" ;;
+esac
+if [ -n "$file_path" ] && [ "${file_path##*/}" != ".team-flow.yaml" ]; then
+  case "$file_path" in
+    "$dir"/*) allow ;;   # artifact zone: inside the change directory
+  esac
+  # macOS symlink normalization: /var,/tmp are symlinks to /private/var,/private/tmp.
+  # $PWD may be physical (child-process chdir) while file_path is logical, or vice
+  # versa — strip the /private prefix on both sides before comparing.
+  norm_dir="${dir#/private}"
+  norm_fp="${file_path#/private}"
+  case "$norm_fp" in
+    "$norm_dir"/*) allow ;;
+  esac
+fi
+
 # --- decision --------------------------------------------------------------
 case "$state" in
   approved-for-build|executing|debugging)
     allow
     ;;
   *)
-    reason="team-flow guard: implementation edits (Write/Edit/MultiEdit) are blocked while the change is in state '$state'. Edits are only allowed in states: approved-for-build, executing, debugging. Advance the workflow to an approved build state first (see docs/state-machine.md or /team-flow:workflow-start). If no change is actually active, remove or fix the stray .team-flow.yaml."
+    reason="team-flow guard: implementation edits (Write/Edit/MultiEdit) OUTSIDE the change directory are blocked while the change is in state '$state'. Code edits are only allowed in states: approved-for-build, executing, debugging. Artifact writes inside the change directory are always permitted (v0.32.2). Advance the workflow to an approved build state first (see docs/state-machine.md or /team-flow:workflow-start). If no change is actually active, remove or fix the stray .team-flow.yaml."
     # Escape backslashes and double quotes for safe JSON string embedding.
     reason_esc="$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g')"
     printf '{"decision":"block","reason":"%s"}\n' "$reason_esc"

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.31.0: auto-sync CLI version with plugin version
+# v0.32.2: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.31.0"
+PLUGIN_VERSION="0.32.2"
 
 # ═══════════════════════════════════════════════════════════════
 # 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.31.0.
+Current version: v0.32.2.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.31.0",
-  "description": "Unified plugin (23 skills + 15 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback for multi-agent coding tools.",
+  "version": "0.32.2",
+  "description": "Unified plugin (24 skills + 15 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -13,6 +13,10 @@
     "build": "tsc",
     "test": "node --test tests/e2e.test.mjs tests/lib/*.test.mjs",
     "test:raw-mode": "node --test tests/lib/raw-mode-smoke.test.mjs",
+    "test:e2e": "node --test tests/e2e/deterministic/*.test.mjs",
+    "test:e2e:baseline": "node tests/e2e/scripts/make-baseline.mjs",
+    "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",
     "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",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.31.0",
+  "version": "0.32.2",
   "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). 24 skills + 15 agents, one install.",
   "author": {
     "name": "LT"

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

@@ -0,0 +1,53 @@
+// scripts/guard/checks/test-gate-exemptions.mjs — shared exemption logic for v0.13 test gates
+//
+// v0.13 §48/§49（设计增强方案 v0.13，C1-domain-policy 事件修复）：
+// test-matrix-complete / test-matrix-ready / tests-passing 三个测试门禁共享同一套
+// legacy/skip 豁免语义，抽取到本模块作为唯一真相源，防止三处判定漂移。
+//
+// 豁免键修正背景（RC-1）：v0.12 §45.3 的"存量兼容"豁免以 contract 内容为键
+//（无 '## Test Matrix' 段即放行），无法区分"真存量"与"新 change 漏生成矩阵"，
+// 导致 v0.31.0 发布当天 C1-domain-policy 零测试通过全部门禁。v0.13 将豁免键改为
+// state 初始化版本标记（schema_version），内容型豁免整体删除。
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * v0.13 §48.1：legacy = v0.32.0 之前创建的 change（状态文件无 schema_version 打戳）。
+ * 打戳只发生在 `tf state init` 创建 change 时；rebuild/doctor/set 一律不追加，
+ * 因此"字段缺失"是可靠的存量信号，不会被新 CLI 重写状态文件而污染。
+ */
+export function isLegacyChange(state) {
+  return state?.schema_version == null;
+}
+
+/** v0.13 §48.2：显式 skip 必须附理由（可审计豁免）。 */
+export function hasExplicitSkip(state) {
+  return state?.test_matrix_skipped === 'true'
+    && typeof state?.test_matrix_skip_reason === 'string'
+    && state.test_matrix_skip_reason.trim().length > 0;
+}
+
+/** skip 已置但理由缺失 → 门禁拒绝并引导补理由。 */
+export function skipMissingReason(state) {
+  return state?.test_matrix_skipped === 'true' && !hasExplicitSkip(state);
+}
+
+export const SKIP_REASON_HINT =
+  "test_matrix_skipped=true requires test_matrix_skip_reason — record it: "
+  + "tf state set <dir> test_matrix_skip_reason '<why this change needs no test matrix>'";
+
+/** contract 是否声明 '## Test Matrix' 段（不存在时 exists=false）。 */
+export function contractDeclaresTestMatrix(changeDir) {
+  const contractPath = path.join(changeDir, 'execution-contract.md');
+  if (!fs.existsSync(contractPath)) return { exists: false, declares: false };
+  const contract = fs.readFileSync(contractPath, 'utf-8');
+  return { exists: true, declares: contract.includes('## Test Matrix') };
+}
+
+/** test-matrix.md 存在性与非空性。 */
+export function readTestMatrixFile(changeDir) {
+  const matrixPath = path.join(changeDir, 'test-matrix.md');
+  if (!fs.existsSync(matrixPath)) return { exists: false, empty: true };
+  const content = fs.readFileSync(matrixPath, 'utf-8');
+  return { exists: true, empty: content.trim().length === 0 };
+}