@xulthekl/team-flow 0.32.1 → 0.33.0

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

@@ -1,3 +1,3 @@
-# team-flow v0.32.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.33.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. 24 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.32.1",
+      "version": "0.33.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.32.1",
+  "version": "0.33.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.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.32.1",
+  "version": "0.33.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.32.1"
+    "version": "0.33.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). 24 skills + 15 agents, one install.",
-  "version": "0.32.1",
+  "version": "0.33.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.32.1"
+    "version": "0.33.0"
   },
   "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.32.1",
+      "version": "0.33.0",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -6,6 +6,49 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.33.0] - 2026-08-03
+
+### Fixed（skills 注入恢复——frontmatter YAML 非法导致预加载静默失效，设计见工作区级文档 team-flow-workspace/docs/architecture-api-db-design-enhancement-v0.13.md §54）
+
+#### 根因（P2-41）
+- 全部 15 个 agent .md 的 frontmatter 是非法 YAML：`description` 块标量内顶格书写 `<example>`，缩进断裂 → Claude Code 解析静默降级：`skills:` 预加载被丢弃、`tools:` 限制失效、description 回退泛化标签，且无任何警告。插件诞生至今 SKILL.md 方法论从未被注入子代理（v0.32.1 的 contract-builder test-strategy 预加载修复同样未生效）
+- **agents/*.md（15 个）**：description 单句化 + 删除 `<example>` 块（LT 决策，学 glaf4 合法写法）；`skills:`/`tools:` 声明保持
+- **skills/e2e/SKILL.md**、**skills/test-strategy/SKILL.md**：description 含裸 `: `（非法 YAML）→ 加引号/改写修复；test-strategy 顺带修正预加载主体表述（build-executor / contract-builder）
+
+#### 行为变更
+- `skills:` 预加载开始真实生效：dispatch 时 SKILL.md 全文注入子代理上下文
+- `tools:` 限制开始真实生效：子代理工具集从全量（117 个，含全部 MCP）收紧为 frontmatter 声明集
+
+### Added
+- **tests/lib/frontmatter-lint.test.mjs**（P3-12）：frontmatter 合法性长效门禁——js-yaml 严格解析全部 agents/skills/commands frontmatter + name/description 必填断言 + agent name 与文件名一致 + skills: 引用必须解析到真实 skills/<name>/SKILL.md；进 npm test（58 例），杜绝同类缺陷复发
+- devDependency：js-yaml
+
+### Tests
+- 全量回归：556/556（lib 498 + lint 58）+ Tier1 e2e + check-versions ✅
+- 变异验证：门禁对旧式病态 frontmatter 样本可捕获
+
+## [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** 重发（内容完全一致 + 打包修复）。

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.32.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.33.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.32.1**。
+当前发布版本：**v0.33.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.32.1`
+> 当前版本：`v0.33.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

package/agents/architecture-design.md

@@ -1,39 +1,6 @@
 ---
 name: architecture-design
-description: >-
-  架构设计门控 agent——基于 4A+DDD 执行五项检查，判断是否需要架构增量设计，
-  若需要则产出三件套（architecture.md + database.md + api.md）+ SQL 制品。
-  在 workflow-start 编排中作为子代理调用，承担判断+执行一体化职责。
-  Examples:
-
-<example>
-Context: workflow-start 在 exploring 完成后，需要判断本 change 是否涉及架构变更。
-user: "exploring 完成了，帮我做架构设计判断"
-assistant: "我来启动 architecture-design agent，执行五项检查判定是否需要架构增量设计。"
-<commentary>
-architecture-design 是 exploring→specifying 之间的门控 agent。五项检查全部为否则 skipped，
-任一为是则 required 并产出三件套。workflow-start 负责后续的 auto-review + reasonableness check。
-</commentary>
-</example>
-
-<example>
-Context: hotfix 模式下仍需要经过架构设计判断门（hotfix 可能正是架构缺陷导致）。
-user: "这是一个 hotfix，需要过架构设计门控吗？"
-assistant: "需要。architecture-design 判断门对 hotfix/tweak 不豁免——启动 agent 执行五项检查。"
-<commentary>
-v0.9 §26 明确要求 hotfix/tweak 同样过 architecture-design 子代理判断门。
-</commentary>
-</example>
-
-<example>
-Context: 五项检查判定为 skipped，但 change-brief 中包含"新增 API"字样。
-user: "brief 里说新增 API，但 agent 说 skipped，这不合理吧？"
-assistant: "workflow-start 的 reasonableness check 检测到不一致——skipped + brief 含架构变更关键词 → BLOCK。需要重新执行架构设计。"
-<commentary>
-reasonableness check 是 workflow-start 的职责，不是 architecture-design agent 的。
-agent 只负责判断+产出，workflow-start 负责确认合理性。
-</commentary>
-</example>
+description: 架构设计门控 agent——基于 4A+DDD 执行五项检查判断是否需要架构增量设计，需要则产出三件套（architecture.md + database.md + api.md）+ SQL 制品。在 workflow-start 编排中作为子代理调用，承担判断+执行一体化职责。
 
 model: inherit
 color: blue

package/agents/architecture-reviewer.md

@@ -1,47 +1,6 @@
 ---
 name: architecture-reviewer
-description: >-
-  架构设计自动审查 agent——独立上下文、只读审查，对照 PRD/plan/change-brief + 全局基线 +
-  conventions 审查架构产出质量（6 维度 A1-A6）。填补 architecture-design 阶段
-  "设计完无审查"的缺口。循环修正 ≤3 轮 + 收敛检测。
-  Examples:
-
-<example>
-Context: architecture-design agent 刚产出三件套，workflow-start 需要自动审查质量。
-user: "架构设计完成了，帮我审查一下产出质量"
-assistant: "我来启动 architecture-reviewer agent，独立审查架构产出的 6 维度质量。"
-<commentary>
-architecture-reviewer 在独立上下文中运行，未参与架构设计产出，规避锚定效应。
-审查报告写在 response 中，由编排层落盘到 changes/<name>/architecture/auto-review.md。
-</commentary>
-</example>
-
-<example>
-Context: 架构产出经过修正后需要重新审查（第 2 轮）。
-user: "架构设计修正完了，重新跑一下审查"
-assistant: "我启动 architecture-reviewer agent 进行第 2 轮审查，对比修正前后不一致项是否收敛。"
-<commentary>
-FAIL 后修正→重新审查，最多 3 轮。连续两轮不一致项集合无缩小则转人工，避免死循环。
-</commentary>
-</example>
-
-<example>
-Context: 用户想确认架构产出是否覆盖了 change-brief 中的所有需求。
-user: "brief 里定义了 5 个功能点，架构设计是不是都覆盖了？"
-assistant: "让 architecture-reviewer agent 做 A4 需求覆盖的结构化检查。"
-<commentary>
-A4 需求覆盖是最关键的维度——遗漏意味着需求在架构层面丢失，下游 spec/code 无法弥补。
-</commentary>
-</example>
-
-<example>
-Context: 想检查架构产出是否遵循项目级 conventions。
-user: "帮我看看架构设计是否符合项目的 DB 命名规范和 API 规范"
-assistant: "我启动 architecture-reviewer agent 做 A6 conventions 合规检查。"
-<commentary>
-A6 读取 .team-flow/conventions/ 下的规范文件，逐项比对架构产出是否遵循。
-</commentary>
-</example>
+description: 架构设计自动审查 agent——独立上下文、只读审查，对照 PRD/plan/change-brief + 全局基线 + conventions 审查架构产出质量（6 维度 A1-A6），填补 architecture-design 阶段"设计完无审查"的缺口。循环修正 ≤3 轮 + 收敛检测。
 
 model: inherit
 color: yellow

package/agents/bug-investigator.md

@@ -1,42 +1,6 @@
 ---
 name: bug-investigator
-description: Use this agent when the user encounters a bug, test failure, unexpected behavior, build failure, or performance issue and wants autonomous root-cause investigation. The agent explores the codebase, forms hypotheses, tests them, and produces a structured root-cause analysis report. Examples:
-
-<example>
-Context: A test is failing and the user wants to understand why before attempting a fix.
-user: "This test has been failing since yesterday, can you investigate why?"
-assistant: "I'll launch the bug-investigator agent to systematically trace the root cause of the test failure."
-<commentary>
-The user wants root-cause analysis, not a quick patch. The bug-investigator agent follows a scientific method: read errors → reproduce → trace data flow → form hypothesis → test → report. It writes investigation notes but does not fix the code.
-</commentary>
-</example>
-
-<example>
-Context: Unexpected behavior in production that doesn't reproduce easily.
-user: "用户在生产环境报了一个诡异的 bug，偶发性的，帮我排查一下"
-assistant: "我来启动 bug-investigator agent，系统性地排查这个偶发问题的根因。"
-<commentary>
-Intermittent bugs require structured investigation — gathering evidence, checking component boundaries, tracing data flow. The agent excels at methodical root-cause analysis for hard-to-reproduce issues.
-</commentary>
-</example>
-
-<example>
-Context: Multiple fix attempts have failed and the user suspects a deeper issue.
-user: "I've tried fixing this three times and it keeps breaking in different ways — something is fundamentally wrong"
-assistant: "This sounds like an architectural issue. Let me dispatch the bug-investigator agent to do a deep root-cause investigation."
-<commentary>
-Multiple failed fixes indicate the symptom is being addressed, not the cause. The agent's DP-5 escalation logic specifically handles this: 3+ failures = question the architecture.
-</commentary>
-</example>
-
-<example>
-Context: A build failure with unclear error messages.
-user: "The build broke and the error message doesn't make sense, can you figure out what's going on?"
-assistant: "I'll use the bug-investigator agent to trace the build failure to its root cause."
-<commentary>
-Unclear errors require careful reading of stack traces, checking recent changes, and tracing dependency chains. The agent systematically narrows down the cause.
-</commentary>
-</example>
+description: Use this agent when the user encounters a bug, test failure, unexpected behavior, build failure, or performance issue and wants autonomous root-cause investigation. The agent explores the codebase, forms hypotheses, tests them, and produces a structured root-cause analysis report without implementing fixes.
 
 model: inherit
 color: yellow

package/agents/build-executor.md

@@ -1,27 +1,6 @@
 ---
 name: build-executor
-description: >-
-  构建执行 agent——在 execution-contract.md 经 DP-3 批准之后、release-archivist 之前,
-  以契约为权威驱动 TDD 批次实施(SDD/Inline/Batch Inline)。可写型,负责实施代码产出。
-  Examples:
-
-<example>
-Context: 契约已批准,用户希望按纪律逐批实施。
-user: "契约批了,开始按 TDD 实施"
-assistant: "I'll launch the build-executor agent to govern the batch-by-batch TDD build."
-<commentary>
-build-executor 是 executing 阶段的实施 agent,守 TDD Iron Law 与契约优先,产出实施代码。
-</commentary>
-</example>
-
-<example>
-Context: 实施中出现契约外新行为,需要回退而非硬做。
-user: "做着做着发现要加一个契约里没有的能力"
-assistant: "I'll have build-executor rewind to specifying/bridging instead of silently expanding scope."
-<commentary>
-Law 4 Rewind on Contract Break:新行为/接口实质变化/设计假设失效 → 回退规划,不私自扩 scope。
-</commentary>
-</example>
+description: 构建执行 agent——在 execution-contract.md 经 DP-3 批准之后、release-archivist 之前，以契约为权威驱动 TDD 批次实施（SDD/Inline/Batch Inline）。可写型，负责实施代码产出。
 
 model: inherit
 color: green

package/agents/change-split-auditor.md

@@ -1,47 +1,6 @@
 ---
 name: change-split-auditor
-description: >-
-  plan.md 拆分质量审计。在 ce-plan 产出 plan.md 后、change 脚手架前，
-  独立审计拆分质量：PRD 需求覆盖矩阵、DAG 无环、粒度均衡、字段完整性、所有权粒度合规（v0.9 根因判据硬门禁：切碎检测/无设计单元/跨单元臃肿）。
-  输出 PASS/FAIL verdict。只读审查。
-  Examples:
-
-<example>
-Context: ce-plan 刚产出 plan.md，orchestrator 需要在创建 change 目录前验证拆分质量。
-user: "plan.md 写好了，帮我检查一下拆分是否合理"
-assistant: "我来启动 change-split-auditor agent，独立审计 plan.md 的拆分质量。"
-<commentary>
-拆分质量审计是 orchestrator S4 阶段的前置门禁。审计失败时编排层携 findings
-回退 ce-plan 加深，避免有缺陷的拆分进入执行。
-</commentary>
-</example>
-
-<example>
-Context: 用户担心 plan 遗漏了 PRD 中的某些需求。
-user: "PRD 里有 12 个功能点，plan 的 change 是不是都覆盖了？"
-assistant: "让 change-split-auditor agent 构建 PRD→change 覆盖矩阵，检查有无遗漏或重叠。"
-<commentary>
-需求覆盖矩阵是 5 维度审计中最关键的一环——遗漏意味着需求丢失，重叠意味着重复工作。
-</commentary>
-</example>
-
-<example>
-Context: plan 中有多组依赖关系，用户想确认不存在循环依赖。
-user: "change-3 依赖 change-1，change-1 又依赖 change-3，这不是死循环了吗？"
-assistant: "我启动 change-split-auditor agent 做 DAG 无环验证和依赖完整性检查。"
-<commentary>
-循环依赖会导致所有涉及的 change 永远无法启动。DAG 验证是机械化的拓扑排序检查。
-</commentary>
-</example>
-
-<example>
-Context: plan 修订后需要重新审计。
-user: "plan 改过了，重新跑一下拆分审计"
-assistant: "我启动 change-split-auditor agent 对修订后的 plan.md 重新做 5 维度审计。"
-<commentary>
-FAIL 后 ce-plan 加深→重新审计，直到 PASS 才进入 change 脚手架。
-</commentary>
-</example>
+description: plan.md 拆分质量审计。在 ce-plan 产出 plan.md 后、change 脚手架前，独立审计拆分质量——PRD 需求覆盖矩阵、DAG 无环、粒度均衡、字段完整性、所有权粒度合规（v0.9 根因判据硬门禁：切碎检测/无设计单元/跨单元臃肿）。输出 PASS/FAIL verdict。只读审查。
 
 model: inherit
 color: cyan

package/agents/code-reviewer.md

@@ -1,47 +1,6 @@
 ---
 name: code-reviewer
-description: >-
-  代码审查 agent——审查代码质量、规格合规性、架构合理性、实现完整性。在 build-executor
-  执行后、release-archivist 归档前，独立审查实现质量。只读审查，不修改任何文件。
-  Examples:
-
-<example>
-Context: build-executor 刚完成一个 wave 的实现，orchestrator 需要审查代码质量。
-user: "wave-1 实现完了，帮我 review 一下代码"
-assistant: "我来启动 code-reviewer agent，独立审查 wave-1 的代码质量。"
-<commentary>
-代码审查是 build-executor 完成后、release-archivist 归档前的关键门禁。本 agent 在独立上下文中运行，
-未参与实现，规避锚定效应。审查报告写在 response 中，由编排层落盘。
-</commentary>
-</example>
-
-<example>
-Context: 用户担心实现偏离了规格说明。
-user: "帮我看看实现有没有偏离 design.md 和 specs/"
-assistant: "让 code-reviewer agent 做规格合规性检查，逐项核对实现与 spec 的一致性。"
-<commentary>
-规格合规性是审查的核心维度——实现必须忠实反映 design.md 的决策和 specs/ 的要求。
-偏离必须有明确理由（如技术约束），否则是 Critical finding。
-</commentary>
-</example>
-
-<example>
-Context: 实现经过修正后需要重新审查（第 2 轮）。
-user: "按上一轮 review 意见改了，重新跑一下审查"
-assistant: "我启动 code-reviewer agent 进行第 2 轮审查，对比修正前后问题是否收敛。"
-<commentary>
-FAIL→修正→重新审查，最多 3 轮。连续两轮问题集合无缩小则转人工，避免死循环。
-</commentary>
-</example>
-
-<example>
-Context: 复杂架构变更需要专项审查。
-user: "这次改了 3 个聚合的边界，帮我重点看看架构是否合理"
-assistant: "我启动 code-reviewer agent，重点审查架构决策、模块边界、依赖方向。"
-<commentary>
-架构审查关注分离关注点、依赖方向、接口设计、可扩展性。复杂变更需要专项深度审查。
-</commentary>
-</example>
+description: 代码审查 agent——审查代码质量、规格合规性、架构合理性、实现完整性。在 build-executor 执行后、release-archivist 归档前，独立审查实现质量。只读审查，不修改任何文件。
 
 model: inherit
 color: blue

package/agents/contract-builder.md

@@ -1,27 +1,6 @@
 ---
 name: contract-builder
-description: >-
-  执行契约 agent——在 spec-writer 产出规划制品并通过 DP-2 之后、build-executor 之前,
-  将规划制品压缩为单一执行握手 execution-contract.md。可写型,负责执行契约文件。
-  Examples:
-
-<example>
-Context: 四件规划制品已稳定且 DP-2 已记录,准备进入实施。
-user: "规划都确认了,帮我生成执行契约,准备开干"
-assistant: "I'll launch the contract-builder agent to convert the artifacts into execution-contract.md."
-<commentary>
-contract-builder 是 bridging 阶段的核心 agent,产出 execution-contract.md 并守 DP-3 批准门。
-</commentary>
-</example>
-
-<example>
-Context: 既有契约因 scope 变更而过期,需要刷新。
-user: "specs 改了,执行契约好像对不上了"
-assistant: "I'll have contract-builder detect staleness and refresh the contract."
-<commentary>
-契约过期检测:scope/requirements/constraints/batches 变化即刷新,不静默放行陈旧契约。
-</commentary>
-</example>
+description: 执行契约 agent——在 spec-writer 产出规划制品并通过 DP-2 之后、build-executor 之前，将规划制品压缩为单一执行握手 execution-contract.md。可写型，负责执行契约文件。
 
 model: inherit
 color: magenta

package/agents/cross-change-consistency-checker.md

@@ -1,48 +1,7 @@
 ---
 name: cross-change-consistency-checker
-description: >-
-  跨 change 冲突检测。在多 change 并行执行期或 change closing 时，
-  检测共享聚合/实体被多个 change 修改、API 签名变更影响、
-  与全局架构锚点漂移、与原型 testid 契约漂移。只读审查。
-  Examples:
-
-<example>
-Context: 两个 change 正在并行开发，orchestrator 在 S5 监控阶段触发一致性检测。
-user: "change-1 和 change-2 都在跑，帮我看看有没有冲突"
-assistant: "我来启动 cross-change-consistency-checker agent，检测跨 change 的 4 维度冲突。"
-<commentary>
-多 change 并行执行时，共享聚合/API/架构锚点可能被不同 change 独立修改导致冲突。
-S5 全局监控阶段（change≥2 时必选）定期触发此检测。
-</commentary>
-</example>
-
-<example>
-Context: 一个 change 即将 closing，需要检查它的修改是否与其他 change 矛盾。
-user: "change-3 要合并了，先检查一下跟其他 change 有没有冲突"
-assistant: "我启动 cross-change-consistency-checker agent 做 closing 前的跨 change 冲突检测。"
-<commentary>
-Change closing 是冲突检测的关键时机——合并后再发现冲突代价更高。
-</commentary>
-</example>
-
-<example>
-Context: 用户怀疑某个 change 的实现偏离了全局架构文档。
-user: "change-2 改的数据模型跟 DATABASE.md 里定义的对不上"
-assistant: "让 cross-change-consistency-checker agent 检测 change-2 与全局架构锚点的漂移。"
-<commentary>
-架构锚点漂移检测（Dim 3）比对 change 实际修改与 ARCHITECTURE.md/DATABASE.md
-的声明，发现未回写的结构性变更。
-</commentary>
-</example>
-
-<example>
-Context: 原型中定义了 data-testid 契约，需要检查各 change 是否遵守。
-user: "原型里定义了 testid，看看各个 change 有没有按契约来"
-assistant: "我启动 cross-change-consistency-checker agent 做 testid 契约漂移检测。"
-<commentary>
-Dim 4 检测原型 testid 契约是否被 change 实现正确引用，保障 E2E 测试基础。
-</commentary>
-</example>
+description: 跨 change 冲突检测。在多 change 并行执行期或 change closing 时，检测共享聚合/实体被多个 change 修改、API 签名变更影响、与全局架构锚点漂移、与原型 testid 契约漂移。只读审查。
+
 
 model: inherit
 color: red

package/agents/need-explorer.md

@@ -1,27 +1,6 @@
 ---
 name: need-explorer
-description: >-
-  需求探索 agent——在 workflow-start 路由后、spec-writer 之前,于 change 上下文内交互式
-  澄清意图/scope/约束/成功标准,稳定 change 定义并守 DP-1 门。只读型,不产出制品不写代码。
-  Examples:
-
-<example>
-Context: change 上下文内请求模糊,需要先澄清再写制品。
-user: "我想给这块加点东西,但还没想清楚"
-assistant: "I'll launch the need-explorer agent to clarify intent and scope before any artifact."
-<commentary>
-need-explorer 是 exploring 阶段的澄清 agent,一次一问、偏好选择题,稳定 change 定义。
-</commentary>
-</example>
-
-<example>
-Context: 本 change 由 workflow-orchestrator S4 分发,change-brief.md 已存在。
-user: "这是 orchestrator 拆出来的 change,帮我确认下范围"
-assistant: "I'll have need-explorer read the brief first and only probe what it leaves open."
-<commentary>
-brief 存在时先读再问,把 brief 的 Scope/约束/AC 作为默认值,默认不再二次拆分。
-</commentary>
-</example>
+description: 需求探索 agent——在 workflow-start 路由后、spec-writer 之前，于 change 上下文内交互式澄清意图/scope/约束/成功标准，稳定 change 定义并守 DP-1 门。只读型，不产出制品不写代码。
 
 model: inherit
 color: blue

package/agents/prd-completeness-reviewer.md

@@ -1,52 +1,6 @@
 ---
 name: prd-completeness-reviewer
-description: >-
-  PRD 完整性自动评审。在 PRD 写入后、冻结前，独立检查"需求描述是否完整到能支撑
-  后续 plan/spec 实施"（5 维度），输出分级完整性报告。只读审查，不修改任何文件。
-  与 claim verifier 分工：claim verifier 管"说得对不对"（核查事实声明），
-  本 agent 管"说得全不全、能否落地"。
-  Examples:
-
-<example>
-Context: PRD 刚写完，orchestrator 需要在冻结前做完整性门禁检查。
-user: "PRD 写好了，帮我看看完整不完整，能不能往下做 plan"
-assistant: "我来启动 prd-completeness-reviewer agent，独立审查 PRD 的 5 维度完整性。"
-<commentary>
-PRD 完整性评审是 orchestrator S2 阶段冻结前的关键门禁。本 agent 在独立上下文中运行，
-未参与 PRD 产出，规避锚定效应。审查报告写在 response 中，由编排层落盘到
-prd/vN/prd-completeness-review.md。FAIL（仅 Critical 触发）→ 回 ce-brainstorm Phase 1.3 补充。
-</commentary>
-</example>
-
-<example>
-Context: 用户担心 PRD 缺验收标准，导致后面 plan/spec 无法落地。
-user: "这份 PRD 的每个功能都有可验证的验收标准吗？"
-assistant: "让 prd-completeness-reviewer agent 做一次 D2 验收标准维度的结构化检查。"
-<commentary>
-D2 验收标准是 Critical 级维度——缺失即触发 FAIL。没有可验证的 AC，下游 plan/spec/build
-将失去判定基准。本 agent 逐功能核查 AC/成功信号是否存在且可验证。
-</commentary>
-</example>
-
-<example>
-Context: PRD 补充修订后需要重新评审（FAIL 后第 2 轮）。
-user: "PRD 按上一轮意见补充了边界场景，重新跑一下完整性检查"
-assistant: "我启动 prd-completeness-reviewer agent 进行第 2 轮完整性评审，对比上轮 Critical 项是否已补齐。"
-<commentary>
-FAIL→回 Phase 1.3 补充→重新评审，直到无 Critical。Important 不阻断，
-以 PASS_WITH_WARNINGS 交人工裁定。
-</commentary>
-</example>
-
-<example>
-Context: 人工冻结前想先确认 PRD 范围闭环、没有悬空功能。
-user: "帮我看看 PRD 的 in/out scope 是不是清楚，有没有写了但没人接的功能"
-assistant: "我启动 prd-completeness-reviewer agent 做 D5 范围闭环维度的检查。"
-<commentary>
-D5 范围闭环是 Important 级——悬空功能（in scope 写了但无对应实现路径）或 out scope
-未声明，会在 plan 阶段才暴露。提前在 PRD 层闭环可降低下游返工。
-</commentary>
-</example>
+description: PRD 完整性自动评审。在 PRD 写入后、冻结前，独立检查"需求描述是否完整到能支撑后续 plan/spec 实施"（5 维度），输出分级完整性报告。只读审查，不修改任何文件。与 claim verifier 分工——claim verifier 管"说得对不对"（核查事实声明），本 agent 管"说得全不全、能否落地"。
 
 model: inherit
 color: yellow

package/agents/prototype-builder.md

@@ -1,46 +1,6 @@
 ---
 name: prototype-builder
-description: >-
-  原型构建 agent——将设计稿（HTML/CSS/JS）转化为可运行的原型系统。在 prototype skill
-  编排中作为子代理调用，负责原型代码生成、设计系统集成、质量保证。只写不读 specs。
-  Examples:
-
-<example>
-Context: prototype skill 完成设计稿生成后，需要构建可运行的原型。
-user: "设计稿生成完了，帮我构建原型"
-assistant: "我来启动 prototype-builder agent，将设计稿转化为可运行的原型系统。"
-<commentary>
-原型构建是 prototype skill 的核心执行步骤。本 agent 读取设计稿（HTML/CSS/JS），
-集成设计系统，生成可运行的原型，执行质量保证检查。
-</commentary>
-</example>
-
-<example>
-Context: 需要修复原型中的问题。
-user: "原型跑起来了，但样式有点问题，帮我修一下"
-assistant: "让 prototype-builder agent 修复原型的样式问题。"
-<commentary>
-原型修复需要读取现有原型代码，定位问题，应用修复，重新验证。
-</commentary>
-</example>
-
-<example>
-Context: 需要为原型添加新功能。
-user: "原型需要加一个搜索功能，帮我实现"
-assistant: "我启动 prototype-builder agent，为原型添加搜索功能。"
-<commentary>
-原型扩展需要读取现有原型，理解结构，添加新功能，确保与设计系统一致。
-</commentary>
-</example>
-
-<example>
-Context: 需要将原型集成到真实系统。
-user: "原型验证通过了，帮我集成到真实系统"
-assistant: "我启动 prototype-builder agent，将原型代码集成到真实项目。"
-<commentary>
-原型集成需要提取原型中的有效代码，适配真实系统的技术栈，确保功能一致。
-</commentary>
-</example>
+description: 原型构建 agent——将设计稿（HTML/CSS/JS）转化为可运行的原型系统。在 prototype skill 编排中作为子代理调用，负责原型代码生成、设计系统集成、质量保证。只写不读 specs。
 
 model: inherit
 color: green

package/agents/prototype-env-scout.md

@@ -1,31 +1,6 @@
 ---
 name: prototype-env-scout
-description: >-
-  原型环境探查（prototype skill 内部编排步骤①）。只读探查设计系统现状（9 段 schema
-  完整度）、原型仓库分支、PRD 版本、已有页面，产出环境简报 + 推荐原型方案设计 +
-  readiness verdict。只读，不写 prototype/，不改 design-system.md。
-  Examples:
-
-<example>
-Context: prototype skill 进入步骤①，需要先摸清环境再设计原型方案。
-user: "要做驾驶舱原型，先帮我看看设计系统、分支、PRD 这些环境情况"
-assistant: "我启动 prototype-env-scout agent，只读探查设计系统/分支/PRD/已有页面，产出环境简报和原型方案建议。"
-<commentary>
-环境探查是 prototype 内部编排的第一步，为后续方案评审和 prototype-builder 绘制提供
-决策依据。本 agent 只读，发现设计系统缺失时把 verdict 标为 needs_design_system 交主代理
-决定是否先派 design-system-architect，而非自己阻断或写文件。
-</commentary>
-</example>
-
-<example>
-Context: 迭代已有原型，需要确认当前分支与 PRD 版本是否对齐。
-user: "PRD 升到 v2 了，原型分支对不对得上？已有哪些页面？"
-assistant: "让 prototype-env-scout agent 探查到原型分支与 PRD 版本的对齐情况和现有原型清单。"
-<commentary>
-原型随 PRD 当前版本分支维护（prd-vN 分支）。本 agent 检测当前分支是否匹配目标 PRD 版本，
-并清点现有 pages/components/flow.md，供迭代方案参考。
-</commentary>
-</example>
+description: 原型环境探查（prototype skill 内部编排步骤①）。只读探查设计系统现状（9 段 schema 完整度）、原型仓库分支、PRD 版本、已有页面，产出环境简报 + 推荐原型方案设计 + readiness verdict。只读，不写 prototype/，不改 design-system.md。
 
 model: inherit
 color: cyan

package/agents/prototype-reviewer.md

@@ -1,46 +1,6 @@
 ---
 name: prototype-reviewer
-description: >-
-  原型 vs PRD 一致性自动评审。在原型产出后、人工评审前，独立检查原型与 PRD
-  的结构化一致性（6 维度），输出分级一致性报告。只读审查，不修改任何文件。
-  Examples:
-
-<example>
-Context: 原型刚产出，orchestrator 需要在人工评审前做自动一致性检查。
-user: "原型做好了，帮我检查一下和 PRD 是否一致"
-assistant: "我来启动 prototype-reviewer agent，独立审查原型与 PRD 的 6 维度一致性。"
-<commentary>
-原型自动评审是 orchestrator S2 阶段的关键门禁。prototype-reviewer 在独立上下文中运行，
-未参与 PRD/原型产出，规避锚定效应。审查报告写在 response 中，由编排层落盘。
-</commentary>
-</example>
-
-<example>
-Context: 原型经过修正后需要重新评审（第 2 轮）。
-user: "原型修正完了，重新跑一下一致性检查"
-assistant: "我启动 prototype-reviewer agent 进行第 2 轮自动评审，对比修正前后不一致项是否收敛。"
-<commentary>
-FAIL 后修正→重新评审，最多 3 轮。连续两轮不一致项集合无缩小则转人工，避免死循环。
-</commentary>
-</example>
-
-<example>
-Context: 用户想确认原型是否覆盖了 PRD 中定义的所有页面和功能。
-user: "PRD 里定义了 8 个页面，原型是不是都有了？"
-assistant: "让 prototype-reviewer agent 做一次 D1 页面完整性 + D2 功能覆盖的结构化检查。"
-<commentary>
-D1/D4 走 Pre-check（Bash 结构化预检），机械化验证页面文件存在性和导航链接完整性。
-</commentary>
-</example>
-
-<example>
-Context: 人工评审前想先过一遍术语和字段是否对齐。
-user: "帮我看看原型里的字段名称和 PRD 定义的是否一致"
-assistant: "我启动 prototype-reviewer agent 做 D3 字段一致性 + D5 术语一致性的语义对比。"
-<commentary>
-D3/D5 走 Deep-check（LLM 语义对比），标注为建议级，误报可被人工推翻。
-</commentary>
-</example>
+description: 原型 vs PRD 一致性自动评审。在原型产出后、人工评审前，独立检查原型与 PRD 的结构化一致性（6 维度），输出分级一致性报告。只读审查，不修改任何文件。
 
 model: inherit
 color: green

package/agents/release-archivist.md

@@ -1,27 +1,6 @@
 ---
 name: release-archivist
-description: >-
-  发布归档 agent——在 build-executor 完成实施之后、change 关闭之前,执行验证、产出
-  closing 总结并完成归档就绪(arch-merge / prototype-sync / 复利晋升)。可写型,负责归档制品。
-  Examples:
-
-<example>
-Context: 实施完成,需要验证并收尾归档。
-user: "实施做完了,帮我验证并归档这个 change"
-assistant: "I'll launch the release-archivist agent to verify, summarize, and ready the archive."
-<commentary>
-release-archivist 是 closing 阶段的收尾 agent,守"验证先于完成"铁律,产出验证报告与归档。
-</commentary>
-</example>
-
-<example>
-Context: 验证发现实施偏离契约,需回退而非强行关闭。
-user: "验证发现 design 决策和代码对不上"
-assistant: "I'll have release-archivist route back to bridging instead of forcing closure."
-<commentary>
-若实施偏离契约,回退 bridging 再关闭;FAIL 不进 DP-7。
-</commentary>
-</example>
+description: 发布归档 agent——在 build-executor 完成实施之后、change 关闭之前，执行验证、产出 closing 总结并完成归档就绪（arch-merge / prototype-sync / 复利晋升）。可写型，负责归档制品。
 
 model: inherit
 color: yellow

package/agents/spec-writer.md

@@ -1,27 +1,6 @@
 ---
 name: spec-writer
-description: >-
-  规格编写 agent——在 need-explorer 完成 DP-1 之后、contract-builder 之前，产出并打磨
-  proposal.md / specs/ / design.md / tasks.md 四件规划制品。可写型,负责规划制品目录。
-  Examples:
-
-<example>
-Context: need-explorer 已记录 DP-1,change 意图稳定,可以落盘规划制品。
-user: "需求已经澄清清楚了,帮我把 proposal/specs/design/tasks 写出来"
-assistant: "I'll launch the spec-writer agent to produce the four planning artifacts in order."
-<commentary>
-spec-writer 是 exploring→bridging 之间的产出 agent。逐件生成、逐件确认,防止 scope 漂移。
-</commentary>
-</example>
-
-<example>
-Context: 本 change 经 architecture-design 判定为 required,architecture/ 三件套已产出。
-user: "架构设计做完了,写 design.md 时要对齐架构决策"
-assistant: "I'll have spec-writer read architecture/ and align design.md Decisions with it."
-<commentary>
-design.md 的 Decisions 必须引用 architecture/ 决策,tasks.md 须对齐 api.md 路由表与 sql/ 脚本。
-</commentary>
-</example>
+description: 规格编写 agent——在 need-explorer 完成 DP-1 之后、contract-builder 之前，产出并打磨 proposal.md / specs/ / design.md / tasks.md 四件规划制品。可写型，负责规划制品目录。
 
 model: inherit
 color: cyan

package/docs/README_en.md

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

package/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). 24 skills, one install.",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "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.32.1: auto-sync CLI version with plugin version
+# v0.33.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.32.1"
+PLUGIN_VERSION="0.33.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.32.1.
+Current version: v0.33.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "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": {
-    "tf": "./scripts/team-flow.mjs",
-    "team-flow": "./scripts/team-flow.mjs"
+    "tf": "scripts/team-flow.mjs",
+    "team-flow": "scripts/team-flow.mjs"
   },
   "type": "module",
   "scripts": {
@@ -41,12 +41,13 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/MageByte-Zero/team-flow"
+    "url": "git+https://github.com/MageByte-Zero/team-flow.git"
   },
   "engines": {
     "node": ">=20"
   },
   "devDependencies": {
+    "js-yaml": "^5.2.3",
     "typescript": "^6.0.3"
   }
 }

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.32.1",
+  "version": "0.33.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.",
   "author": {
     "name": "LT"

package/scripts/guard/guard.mjs

@@ -20,7 +20,12 @@ import { checkTestMatrixReady } from './checks/test-matrix-ready.mjs';
 // Transition matrix: <from>:<to> → required check dimensions
 const TRANSITION_CHECKS = {
   // Forward transitions
-  'exploring:specifying':           ['artifacts-exist', 'arch-design'],
+  // v0.32.2 (P3-10): artifacts-exist removed from exploring:specifying —
+  // the four planning artifacts are PRODUCED by spec-writer during specifying,
+  // so requiring them before the transition was a chicken-and-egg deadlock
+  // (C1 事件：主代理被此门禁逼出绕行行为)。Artifact completeness is enforced
+  // by specifying:bridging (artifacts-exist remains there, single owner).
+  'exploring:specifying':           ['arch-design'],
   'specifying:bridging':            ['artifacts-exist', 'schema-valid'],
   'bridging:approved-for-build':    ['artifacts-exist', 'schema-valid', 'contract-fresh', 'dp-gate-passed'],
   // v0.13 §49：test-matrix-ready 门禁前移——full 模式进入 executing 前强制测试准备度

package/scripts/lib/cmd-version.mjs

@@ -19,25 +19,30 @@ const MANIFESTS = [
 // ── Text files with regex patterns (first capture group = version to replace) ──
 // Note: CLAUDE.md is intentionally gitignored (project-local AI instructions).
 const TEXT_FILES = [
-  { file: 'README.md',              pattern: /(当前版本：`v?)0\.\d+\.\d+(`?)/g,                   replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'INSTALL.md',             pattern: /(当前发布版本：\*\*v)0\.\d+\.\d+(\*\*)/g,            replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'docs/README_en.md',      pattern: /(Current: `v)0\.\d+\.\d+(`)/g,                     replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'hooks/session-start',    pattern: /(# v)0\.\d+\.\d+(: conditional injection)/g,       replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'llms.txt',               pattern: /(Current version: v)0\.\d+\.\d+(\.)/g,             replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: '.claude/always/phase-guard.md', pattern: /(# team-flow v)0\.\d+\.\d+( \|)/g,      replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'GEMINI.md',              pattern: /(# team-flow v)0\.\d+\.\d+( \|)/g,              replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/workflow-start/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/need-explorer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/spec-writer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/contract-builder/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/build-executor/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/build-executor/implementer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/build-executor/task-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/code-reviewer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/code-reviewer/code-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/bug-investigator/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/release-archivist/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
-  { file: 'skills/spec-merger/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'README.md',              pattern: /(当前版本：`v?)\d+\.\d+\.\d+(`?)/g,                   replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'INSTALL.md',             pattern: /(当前发布版本：\*\*v)\d+\.\d+\.\d+(\*\*)/g,            replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'docs/README_en.md',      pattern: /(Current: `v)\d+\.\d+\.\d+(`)/g,                     replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  // v0.32.2（P2-40）：hooks/session-start 两处版本号都纳入同步——
+  // ① 头部注释行（后缀用通配 `:.*`，防止注释措辞变更导致 pattern 腐化失配，
+  //    v0.27.2~v0.32.1 四次发版中断的根因即旧 pattern 写死了后缀措辞）；
+  // ② PLUGIN_VERSION 变量（check-version-consistency 的门禁判据）。
+  { file: 'hooks/session-start',    pattern: /(# v)\d+\.\d+\.\d+(:.*)/g,                            replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'hooks/session-start',    pattern: /(PLUGIN_VERSION=")\d+\.\d+\.\d+(")/g,                 replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'llms.txt',               pattern: /(Current version: v)\d+\.\d+\.\d+(\.)/g,             replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: '.claude/always/phase-guard.md', pattern: /(# team-flow v)\d+\.\d+\.\d+( \|)/g,      replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'GEMINI.md',              pattern: /(# team-flow v)\d+\.\d+\.\d+( \|)/g,              replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/workflow-start/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/need-explorer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/spec-writer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/contract-builder/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/build-executor/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/build-executor/implementer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/build-executor/task-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/code-reviewer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/code-reviewer/code-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/bug-investigator/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/release-archivist/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
+  { file: 'skills/spec-merger/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)\d+\.\d+\.\d+( tf)/g, replacement: '$1%MAJOR%.%MINOR%.%PATCH%$2' },
 ];
 
 function getNestedValue(obj, pathParts) {
@@ -72,7 +77,7 @@ export async function run(args) {
     console.error(`Invalid semver: ${newVersion}`);
     process.exit(2);
   }
-  const [, , minor, patch] = match;
+  const [, major, minor, patch] = match;
 
   console.log(`Version sync → ${newVersion}${dryRun ? ' (dry run)' : ''}\n`);
   let changed = 0;
@@ -122,7 +127,7 @@ export async function run(args) {
 
     const content = readFileSync(filePath, 'utf-8');
     const replacement = entry.replacement
-      .replace('%MINOR%', minor)
+      .replace('%MAJOR%', major).replace('%MINOR%', minor)
       .replace('%PATCH%', patch);
 
     const newContent = content.replace(entry.pattern, replacement);

package/skills/e2e/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e2e
-description: 从 spec 验收场景生成 Playwright E2E 测试、执行并审计覆盖率（可选 overlay）。用法: /e2e [原型|集成|验收] [spec路径]
+description: "从 spec 验收场景生成 Playwright E2E 测试、执行并审计覆盖率（可选 overlay）。用法: /e2e [原型|集成|验收] [spec路径]"
 version: 0.1.0
 user-invocable: true
 ---

package/skills/test-strategy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-strategy
-description: 测试设计方法论 skill——design_method 选择、分层策略、对抗验证、复杂度分级。build-executor 通过 skills: 预加载。
+description: 测试设计方法论 skill——design_method 选择、分层策略、对抗验证、复杂度分级。build-executor / contract-builder 通过 skills 字段预加载。
 user-invocable: false
 ---