@xulthekl/team-flow 0.22.4

package/skills/workflow-orchestrator/references/state-model.md

@@ -0,0 +1,185 @@
+# 编排状态模型（v0.7 新增，v0.15.0 多需求重构 + `.team-flow/` 治理）
+
+> orchestrator 的持久化记忆 / checkpointer（对标 LangGraph Checkpointer），跨阶段、跨 session 的状态一律读 yaml 而非依赖上下文记忆。设计依据：设计增强方案 v0.7 §17.9 + v0.8 §18.2/§18.3。
+
+## 状态文件布局（v0.15.0：每需求一份 + 注册表）
+
+> **v0.15.0 重构**：从「单需求单文件 `.workflow-orchestrator.yaml`（项目根）」升级为「每需求一份 + 注册表索引」，支持多需求并行；所有状态文件收敛到 `.team-flow/` 目录（P1-6 第一阶段）。
+
+```
+.team-flow/
+├── registry.yaml                        # 需求注册表（索引 + 活跃指针）
+└── requirements/
+    └── <req-id>/                        # 每个需求独立目录（req-id = prd 迭代主题短码）
+        └── orchestrator.yaml            # 该需求的产品级编排状态（原 .workflow-orchestrator.yaml）
+```
+
+- **迁移兼容**：检测到旧 `<root>/.workflow-orchestrator.yaml` 存在时，自动迁移到 `.team-flow/requirements/<req-id>/orchestrator.yaml` 并提示用户（一次性）。
+- **变更级状态**：各 change 的状态文件**当前仍为** `<change>/.team-flow.yaml`，检测逻辑不动；**计划 v1.0.0（P1-6 第二阶段）改名**为 `.team-flow.yaml`（对齐设计增强方案 v0.8 §18.3）。改名落地前，编排层与变更层一律以 `.team-flow.yaml` 为准。
+
+## registry.yaml Schema
+
+```yaml
+schema_version: 1
+active_requirement: <req-id>          # 当前活跃需求（orchestrator 默认操作对象）
+requirements:
+  - id: <req-id>
+    title: <需求标题>
+    prd_version: v1
+    phase: S3                          # 冗余快照，真相源仍是各 orchestrator.yaml
+    orchestrator_state: .team-flow/requirements/<req-id>/orchestrator.yaml
+    created_at: "..."
+    updated_at: "..."
+```
+
+## 单需求 orchestrator.yaml Schema
+
+```yaml
+schema_version: 1                     # schema 版本号
+requirement_id: <req-id>              # 需求标识（与 registry 对应）
+workflow_phase: S2                    # 当前阶段
+phases:                               # 各阶段状态
+  - { id: S1, status: completed, started_at: "...", completed_at: "...", artifacts: [...] }
+  - { id: S2, status: active, started_at: "...", artifacts: [...] }
+  - { id: S3, status: pending }
+custom_phases: []                     # reserved
+replan_log:                           # 重规划履历
+  - { seq: 1, trigger: "用户要求跳过原型", before: "S2→S3", after: "S2(skip-proto)→S3", approved_by: user }
+change_dag:                           # change 依赖图（S4 后填充）
+  - id: change-1
+    change_dir: changes/change-1/                      # 项目根 changes/<change-name>/（非 specs/，非 .team-flow/）
+    state_file: changes/change-1/.team-flow.yaml   # 变更级状态文件（P1-6 第二阶段 v1.0.0 改名为 .team-flow.yaml）
+    depends_on: []
+    priority: 1
+    parallel_group: A                 # 同组可并行
+    status: executing                 # 从 .team-flow.yaml 同步（计划 v1.0.0 改名 .team-flow.yaml）
+  - id: change-2
+    depends_on: [change-1]
+    status: pending
+prd_version: v1                       # PRD 版本
+```
+
+## 状态枚举
+
+`pending | active | completed | skipped | blocked | aborted`
+
+## 状态转换规则
+
+- **正向**：pending → active → completed
+- **跳过**：pending → skipped（用户确认）
+- **回退**：active → pending（**必须写 replan_log**）
+- **阻塞**：active → blocked → active（S5 检测到 change 卡死）或 blocked → aborted
+- **终止**：任何非 completed 状态 → aborted（用户放弃编排）
+
+## 双层冻结语义（解决 §17.3 与 §17.9.1 矛盾）
+
+- **`frozen_downstream`**（S2 完成时设置）：下游阶段（S3/S4/S5）不可直接修改 PRD，只能通过回退到 S2 修改。**S3→S2 回退 = 临时解除 frozen_downstream**，S2 重新完成后恢复。
+- **`frozen_absolute`**（用户显式确认或 vN+1 启动时设置）：任何修改都必须升版 vN+1。
+- **单一真相源**：frozen 状态以 `prd/vN/prd.md` frontmatter 为准，yaml 只存指针不重复存 frozen 值，避免双写不一致。
+
+## 原型补跑/重跑：部分重入语义（v0.20.0，S1 第 7 入口）
+
+S1 判定「原型补跑/重跑」（PRD `frozen_downstream` ∧ `prototype/` 缺失/需重做）时的状态转换规则，**区别于 S3→S2 回退**：
+
+- **状态转换**：`workflow_phase` 临时回 `S2`，S2 阶段状态置 `active` 并加子标记 `prototype-only`（仅重跑 S2 步骤 2 判断→3 原型循环→4 冻结）；**不重置** S3/S4 已 `completed` 的 phases。记录原 phase（如 `S4`）到 `replan_log`，闭环后恢复。
+- **冻结语义**：PRD `frozen_downstream` **保持不变**（与 S3→S2 回退会临时解除 frozen 不同）——原型补跑不修 PRD，故无需解除冻结。
+- **制品保留**：S3 `plan.md` / S4 `changes/` 已存在且仍有效则**保留不动**，不重做、不归档。
+- **闭环恢复**：原型循环闭环（自动评审 PASS / 人工通过）后，`workflow_phase` 恢复原 phase（如 `s4-distribution`），S2 状态回 `completed`（去掉 `prototype-only` 子标记）。
+- **replan_log 必写**：`{ seq, trigger: "prototype-rerun", before: <原 phase>, after: "S2(prototype-only)", approved_by }`，并记结论「未暴露 scope 问题、changes 保持有效」。
+- **升级路径**：若原型循环暴露 PRD scope 问题 → **脱离本路径**，升级为 S3→S2 回退修订（临时解除 `frozen_downstream`，PRD vN 内修订 + 变更履历），不再按 prototype-only 处理。
+
+## change_dag 结构
+
+S4 后填充。每个节点字段：
+- `id`：change 标识（与 C-ID 对应）
+- `change_dir` / `state_file`：change 目录与状态文件路径。`change_dir` 固定为项目根 `changes/<change-name>/`，不是 `specs/<cap>/`（change 内部行为规格目录）或 `architecture/`（change 内部架构设计目录），也不是 `.team-flow/`（仅存产品级编排状态）
+- `depends_on`：依赖的 change id 列表（构成 DAG）
+- `priority`：优先级数值
+- `parallel_group`：同组可并行（如 A、B）
+- `status`：从该 change 的 `.team-flow.yaml` 同步（变更级状态文件，P1-6 第二阶段改名 `.team-flow.yaml`）
+
+## yaml 定位与并发约束
+
+- **持久化记忆 / checkpointer**：跨阶段、跨 session 状态读 yaml，不依赖上下文记忆
+- **幂等恢复**：S1「继续执行」入口通过 yaml + 制品实际存在性双重校验重建状态
+- **多需求隔离（v0.15.0）**：每个需求的 `orchestrator.yaml` 只由该需求的 orchestrator 实例单写——多需求并行时**天然隔离，无写冲突**（原「单写者」约束自动成立）。
+- **registry 写入**：`registry.yaml` 只在需求创建/切换/状态快照时由 orchestrator 写，频率低。
+- **变更级单写者**：各 change 只写自己的状态文件（当前 `.team-flow.yaml`，P1-6 第二阶段改名 `.team-flow.yaml`），避免并发写冲突。
+
+---
+
+## 动态重规划（§17.9）
+
+> 从「固定管道」升级为「默认路径 + 任意时刻可重规划」。
+
+### 三级意图分类器（宁可漏判，不可误触发）
+
+| 级别 | 方法 | 触发条件 | 动作 |
+|------|------|---------|------|
+| L1 关键词 | 零成本匹配（**宾语须为 orchestrator 阶段或 change 全局结构**） | 「改阶段顺序/跳过原型阶段/插入一个评审阶段/回退到S2/重规划工作流」 | → 重规划评估 |
+| L2 语义分析 | LLM 判断 | 对阶段顺序的不满 / 对缺失环节的要求 / 对已完成产出的否定 | → **建议模式**：输出轻量提示「你似乎想调整工作流？输入'重规划'进入重规划模式」，**不自动进入评估** |
+| L3 默认 | — | 不改变工作流结构 | 普通问答处理 |
+
+> **L1 上下文限定**：「跳过这个功能」（PRD 内容讨论）不触发；「跳过原型阶段」（orchestrator 阶段）才触发。L2 从「自动触发」降级为「建议模式」（B2），将触发权交还用户。
+
+### 重规划评估流程
+
+```
+边界检查（红/绿/灰区）→ 影响分析 → before/after 对比呈现
+  → DP-R 用户确认（硬门禁，阻塞式）→ 执行 + 写入 replan_log
+  → 触发复利捕获（workflow_pattern）
+```
+
+### 重规划边界
+
+| 区域 | 范围 | 规则 |
+|------|------|------|
+| **绿区（可重规划）** | 调整未完成阶段顺序；跳过未完成阶段；插入新阶段；修改未执行 change 的优先级/依赖；S4 后新增 change | 用户确认即可 |
+| **红区（不可重规划）** | 修改已冻结 PRD（只能升版）；删除已执行 change（只能走 abandoned）；重做已完成阶段；改变已合并 delta spec | 硬阻断 |
+| **灰区（二次确认）** | 回退 active 阶段（半成品可能丢失）；修改有下游执行的 change 依赖图 | 需二次确认 + 影响说明 |
+
+### replan_log
+
+每次回退/重规划必须写入 `replan_log`：`{ seq, trigger, before, after, approved_by }`。是 ACM/CMMN Case Event Log 的 LLM 简化版。
+
+---
+
+## 工作流模式复利 L2（§17.9.4）
+
+与现有 solutions 体系完全兼容，新增 `type: workflow_pattern`：
+
+| 字段 | 值 |
+|------|---|
+| type | `workflow_pattern`（新增值） |
+| domain | `workflow`（固定） |
+| phase | `cross-phase`（固定） |
+| pattern_kind | stage-insertion / stage-skip / reorder / change-split-adjust / gate-adding |
+| outcome | positive / negative / neutral |
+| confidence | 浮点数（0.3 基础 + occurrences×0.1 + outcome 加成） |
+| occurrences | 出现次数 |
+
+**捕获时机**：DP-R 确认的重规划、阶段回退、用户主动反馈、PRD 升版、change closing 回顾。
+
+**注入时机**（全部 advisory 级，不阻断）：
+- S1 路由时：历史模式 top-3（confidence ≥ 0.5）
+- 阶段转换时：applicable_when 匹配
+- DP-R 触发时：类似历史重规划
+
+**置信度阈值**：≥0.7 强建议 / ≥0.5 弱建议 / <0.5 仅记录 / ≤0.1 淘汰。晋升：confidence ≥ 0.7 且 occurrences ≥ 3 → 建议固化到 SOP。
+
+---
+
+## 实施路线图（§17.9.6）
+
+| 阶段 | 版本 | 内容 | 依赖 |
+|------|------|------|------|
+| Phase 0 | v0.14.0 | `.workflow-orchestrator.yaml` 状态持久化 | 无（一切前提） |
+| Phase 1 | v0.14.0 | DP-R 决策点 + 阶段跳过/插入/重排 + replan_log | Phase 0 |
+| Phase 2 | v0.15.0 | 三级意图分类器 + 红/绿/灰区边界检查 | Phase 1 |
+| Phase 3 | v0.15.0 | workflow_pattern 注册 + 捕获 + INDEX.md 兼容 | Phase 1 |
+| Phase 4 | v0.16.0 | confidence 模型 + 三处注入 + 用户反馈回写 | Phase 3 |
+| Phase 5 | v0.17.0+ | 高 confidence 模式固化 SOP + 失效淘汰 | Phase 4 |
+
+**关键约束**：Phase 0 是一切前提；所有 L2 注入为 advisory 级；L3（自动工作流修改）明确不做，人在环。
+
+> **当前实现状态**：状态持久化（Phase 0）已于 **v0.15.0** 落地，并升级为多需求模型（`.team-flow/registry.yaml` + `.team-flow/requirements/<req-id>/orchestrator.yaml`）。动态重规划相关能力（三级意图分类器、红/绿/灰区、workflow_pattern 复利）随路线图分版本交付。

package/skills/workflow-start/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: workflow-start
+description: Primary entry point for the team-flow state-machine workflow. Invoke when the user is inside an active team-flow change directory (look for .team-flow.yaml, changes/<name>/, proposal.md, specs/, design.md, tasks.md, or execution-contract.md) and asks to start, continue, resume, implement, plan, or figure out the next workflow step. Also invoke when the user explicitly asks to start a new team-flow change or route through the team-flow workflow. Do not invoke for unrelated coding tasks that happen to use words like start, continue, implement, or plan.
+---
+
+# Workflow Start
+
+Primary entry point for `team-flow`. Jobs: inspect change context, check for updates, confirm DP-0, determine state, route to correct skill, block invalid transitions.
+
+## Use This Skill When
+
+Only invoke when team-flow context is present: `.team-flow.yaml` exists, artifacts like `proposal.md`/`specs/`/`design.md`/`tasks.md`/`execution-contract.md` are present, or user explicitly invokes team-flow by name. When in doubt, check for `.team-flow.yaml` first.
+
+Do NOT invoke for: general coding tasks outside team-flow changes, casual questions, unrelated work.
+
+## States
+
+`exploring` → `specifying` → `bridging` → `approved-for-build` → `executing` → `closing`, with `debugging` side-path from `executing`, and `abandoned` as terminal. If a transition is ambiguous, run `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime asset read docs/state-machine.md`.
+
+## Initialization
+
+1. **Update check**: Run `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime check-update`. Exit 0 → continue. Exit 1 → non-blocking upgrade reminder. Exit 2 → skip.
+2. **Inspect change folder**: Check for `proposal.md`, `specs/`, `design.md`, `tasks.md`, `execution-contract.md`. Answer: Is the change fuzzy? Artifacts missing/unstable? Contract exist? User approved contract? Execution in progress or blocked? In verification/wrap-up?
+3. **Overlay recovery scan**: Run `npx --yes --package @xulthekl/team-flow@0.22.4 tf handoff list <change-dir> --json` and `npx --yes --package @xulthekl/team-flow@0.22.4 tf checkpoint list <change-dir> --json`. A `result-ready` handoff requires explicit review and `npx --yes --package @xulthekl/team-flow@0.22.4 tf handoff resolve` before resuming the affected work. An `active` handoff is non-blocking side work. Show a non-stale checkpoint as recovery context; show a stale checkpoint only as historical evidence.
+4. **Execution-control recovery scan**: For `approved-for-build`, `executing`, `debugging`, or `closing`, run `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution show <change-dir> --json`. Treat only `current: true` plus `waves[].eligible: true` as permission to start a wave; report plan revision, mode, next eligible wave, and every wave's receipt/blockers. A missing, invalid, or stale plan blocks implementation and routes to `build-executor`; do not infer progress from chat history.
+
+## DP-0: User Confirmation Gate
+
+Run DP-0 when: change folder doesn't exist, planning artifacts missing/empty, or `dp_0_confirmed` ≠ `true`. Skip if `dp_0_confirmed` is `true`.
+
+### Upstream Inheritance (v0.9)
+
+若 `change-brief.md` 存在且 `upstream_source == orchestrator`（本 change 由 orchestrator S4 分发），**继承** brief 的 scope/约束/AC 为默认值，DP-0 从"从零问"改为"一次确认继承或修正"，**不**重新问"你想做什么"。否则（手动新建 / hotfix / 单 change 快速通道 / 存量 change 无 brief）照常 DP-0。**主信号 = brief 文件存在**（非 yaml 字段——可天然排除无 brief 的快速通道，且对存量手动 change 零误伤）；双源冲突以 `prd/vN/plan.md` 为准并触发 Brief drift（见「Staleness Detection」）。完整判定伪代码与主信号理由见 `references/routing-rules.md`「DP-0」。
+
+Ask (manual path): change name + one-sentence intent, known constraints, related optimizations (include or stay focused?), communication preference (ask per decision or draft for review).
+
+After confirmation:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_0_decisions "<summary>"
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_0_result confirmed
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_0_confirmed true
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_0_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+```
+
+Config-aware routing: check `artifacts.order` and `artifacts.skip` from project config.
+
+## Mode Detection
+
+If workflow is `auto`/`null`/unset: run `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime infer <change-dir>`. Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **tweak** (≤4 tasks, config/doc only), **full** (anything larger). Persist with `npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <dir> workflow <mode>`.
+
+Validate mode against artifact content. If hotfix/tweak criteria not met → upgrade to `full` and output reason. Don't overwrite explicit mode unless user asks.
+
+## Routing Rules
+
+### Route to need-explorer
+Change is fuzzy, scope unclear, comparing options, no stable change name.
+
+### Route to architecture-design (v0.9 §26)
+Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before spec-writer. Dispatch `architecture-design` as sub-agent; after return, run reasonableness check and write yaml. Full protocol in `references/routing-rules.md`「Route to architecture-design」.
+
+### Route to spec-writer
+Guard: `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK. **arch_design_decision must not be null** → fail = BLOCK (v0.9 §26). User knows what they want, artifacts missing/incomplete.
+
+### Route to contract-builder
+Guard: `... check <dir> specifying bridging --json` → fail = BLOCK. Artifacts exist, implementation requested, contract missing/stale. Include `DP-3: 契约批准`.
+
+### Route to build-executor
+Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution recommend <change-dir> [--wave ...]`, show the user every available mode plus evidence and the recommendation, then obtain a clear selection. The command saves a current receipt; before the first implementation edit, `build-executor` must run `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution plan <change-dir> --mode <selected> --confirm ...` (and `--acknowledge-recommendation` when the selected mode differs from the recommendation) using matching artifacts, contract, and waves, then `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution show <change-dir> --json`; report the saved revision, selected mode, recommendation alignment, ordered waves, and actual concurrent-dispatch capability. A revision must repeat recommend and confirmation. Do not transition to `executing` until `show` reports `current: true`; then run `... check <dir> approved-for-build executing --json` → fail = BLOCK.
+
+### Route to bug-investigator
+Execution hit blockage: test failure, unexpected behavior, build error, task cannot proceed. After debugging, route back to build-executor.
+
+### Route to code-reviewer
+The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition.
+
+### Route to release-archivist
+Guard: `... check <dir> executing closing --json` → fail = BLOCK. Implementation complete, verification complete/nearly complete. Include `DP-7: 归档确认`.
+
+### Route to spec-merger
+Delta specs exist that need merging, change closing with ADDED/MODIFIED/REMOVED/RENAMED specs.
+
+### Route to abandoned
+User explicitly requests, bug-investigator escalates after 3+ failures AND user chooses, scope change makes change no longer worthwhile AND user confirms. Block from `closing` or `abandoned`.
+
+### Optional Prototype Handoff
+
+When the user's brief explicitly contains UI, screen, interaction, layout, UX,
+or product-experience uncertainty, ask once whether a prototype would reduce
+uncertainty. Do not create a prototype handoff or enter a prototype worktree
+until the user confirms. After confirmation:
+
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf handoff create <change-dir> \
+  --type prototype --objective "<confirmed objective>" \
+  --expected-output "<expected evidence>" --acceptance "<completion criterion>"
+npx --yes --package @xulthekl/team-flow@0.22.4 tf isolate <change-dir> prototype-<handoff-id>
+```
+
+Never suggest or enter this route automatically for backend, CLI, configuration,
+or internal-refactor work. Never pass `--force` to `tf isolate` for prototype
+work.
+
+### Fast-Path Routing
+- **Hotfix**: Route to contract-builder (minimal), skip need-explorer + spec-writer, guard check `exploring bridging --workflow hotfix`, then `bridging -> approved-for-build`, after DP-3 → build-executor (recommend, show, and confirm an execution mode), after → release-archivist (lightweight). Hotfix may skip `proposal.md`, `design.md`, `tasks.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md`, DP-3 approval, and a current execution plan before build. **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门，快速判定是否涉及架构变更（hotfix 可能正是架构缺陷导致）
+- **Tweak**: Route to build-executor (direct edit), skip need-explorer + spec-writer + contract-builder, guard check `exploring approved-for-build --workflow tweak`, after → release-archivist (lightweight). **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门
+
+Post-transition: 💡 `npx --yes --package @xulthekl/team-flow@0.22.4 tf inject <change-dir>` to update phase-guard artifacts.
+
+## Staleness Detection
+
+Use content inspection, not timestamps.
+
+**Stale contract**: proposal scope expanded beyond contract scope fence, or contract references capabilities no longer in proposal → route back to `contract-builder`.
+
+**Stale planning artifacts**: capability in proposal has no spec file, or spec exists for capability not in proposal → drift detected.
+
+**Stale tasks**: requirement in specs has no corresponding task → stale tasks.
+
+**Brief drift (advisory, v0.9, 不阻断)**: change-brief.md 是上游输入（非 team-flow 产物），**不**混入上述三条产物互查、**不**进入 `artifacts_hash`。当 brief 的 `plan_hash` 与当前 `prd/vN/plan.md` 不一致，或 brief AC 列表与 PRD 功能清单明显出入 → 提示"产品层已变更，brief 可能过期，建议回 orchestrator 重新分发（S4→S3 环路）"，**不**触发产物重审。
+
+## Guardrails
+
+- No implementation before planning artifacts or contract exist
+- No implementation for full/hotfix without a current `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution plan`; no state transition based on an unverified DP-4 string
+- No "continue" without state inspection
+- No implementation past stale contract
+- No implementation past bug without investigation
+- No closure without all planned wave review receipts recorded as `pass`
+- No closure with unsynced delta specs
+- No transitions from `abandoned` (terminal)
+- No transition to `abandoned` from `closing` or `abandoned`
+- No auto-abandon without user confirmation
+- No merging delta specs from abandoned change
+- **No routing to spec-writer without architecture-design gate pass** (v0.9 §26): `arch_design_decision` must be `required` or `skipped` (not `null`). hotfix/tweak 不豁免
+
+## Output Standard
+
+Always state: (1) current detected state, (2) why (cite file/content/condition), (3) which skill should run next. If blocking, explain missing artifact/approval.
+
+Decision point references when routing:
+- architecture-design → DP-A（架构设计判断门，v0.9 §26）, contract-builder → DP-3, build-executor → DP-4, bug-investigator (escalation) → DP-5, release-archivist (verification failure) → DP-6, release-archivist → DP-7
+
+## Exception Handling
+
+- **Parse failures**: Fall back to content-level detection if `.team-flow.yaml` is malformed
+- **Missing files**: Route to the skill that generates the missing files
+- **User interruption**: Re-inspect change directory content (not cached state) on resume

package/skills/workflow-start/references/routing-rules.md

@@ -0,0 +1,155 @@
+# Routing Rules Reference
+
+> 从 workflow-start SKILL.md 提取的详细路由规则和 CLI 命令。
+
+## Route to need-explorer
+Change is fuzzy, scope unclear, comparing options, no stable change name.
+
+## Route to architecture-design (v0.9 §26)
+
+Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before spec-writer.
+
+Dispatch `architecture-design` as sub-agent with inputs:
+- `change-brief.md`（scope / AC / 技术方向）
+- `prd/vN/plan.md` 高阶技术设计段
+- existing `specs/`
+- global `docs/architecture/`（As-Is 基线）
+
+Sub-agent returns structured output:
+```yaml
+decision: required | skipped
+reason: "..."                    # skipped 时：不涉及架构变更的理由
+                                 # required 时：涉及的变更项摘要
+artifacts:                       # required 时必填
+  - architecture/architecture.md
+  - architecture/database.md
+  - architecture/api.md
+```
+
+**Reasonableness check**（workflow-start 确认后写入 yaml）：
+- `skipped` + reason inconsistent with brief/plan scope → **BLOCK**（如 scope 含"新增 API"但 reason 说"不涉及架构变更"）
+- `required` + artifacts files missing on disk → **BLOCK**
+- `null`（未判定）→ **BLOCK**
+
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> arch_design_decision "<required|skipped>"
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> arch_design_reason "<reason>"
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> arch_design_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+# if required:
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> arch_design_artifacts "architecture/architecture.md,architecture/database.md,architecture/api.md"
+```
+
+**hotfix / tweak 不豁免**：同样过 architecture-design 子代理判断门。
+
+## Route to spec-writer
+Guard: `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK.
+**arch_design_decision must not be null** → fail = BLOCK（architecture-design gate not passed，v0.9 §26）。
+User knows what they want, artifacts missing/incomplete.
+
+## Route to contract-builder
+Guard: `... check <dir> specifying bridging --json` → fail = BLOCK.
+Artifacts exist, implementation requested, contract missing/stale. Include DP-3: 契约批准.
+
+## Route to build-executor
+Contract exists and approved, contract matches artifacts. Include DP-4: 执行模式选择.
+
+Propose waves, run:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution recommend <change-dir> [--wave ...]
+```
+Show every available mode plus evidence and recommendation, obtain clear selection. Then:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution plan <change-dir> --mode <selected> --confirm ...
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution show <change-dir> --json
+```
+Do not transition to `executing` until `show` reports `current: true`.
+Guard: `... check <dir> approved-for-build executing --json` → fail = BLOCK.
+
+## Route to bug-investigator
+Execution hit blockage: test failure, unexpected behavior, build error. After debugging, route back to build-executor.
+
+## Route to code-reviewer
+Current planned wave implemented and ready for review. Reviewer must write:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>
+```
+
+## Route to release-archivist
+Guard: `... check <dir> executing closing --json` → fail = BLOCK. Include DP-7: 归档确认.
+
+## Route to spec-merger
+Delta specs exist that need merging, change closing with ADDED/MODIFIED/REMOVED/RENAMED specs.
+
+## Route to abandoned
+User explicitly requests, bug-investigator escalates after 3+ failures AND user chooses, scope change makes change no longer worthwhile AND user confirms. Block from `closing` or `abandoned`.
+
+## Fast-Path Routing
+
+- **Hotfix**: Route to contract-builder (minimal), skip need-explorer + spec-writer, guard check `exploring bridging --workflow hotfix`, then `bridging -> approved-for-build`, after DP-3 → build-executor, after → release-archivist (lightweight).
+- **Tweak**: Route to build-executor (direct edit), skip need-explorer + spec-writer + contract-builder, guard check `exploring approved-for-build --workflow tweak`, after → release-archivist (lightweight).
+- **architecture-design 不豁免**（v0.9 §26）：hotfix / tweak 同样过 architecture-design 子代理判断门（hotfix 可能正是架构缺陷导致）。
+
+## Optional Prototype Handoff
+
+When the user's brief explicitly contains UI/screen/interaction/layout/UX uncertainty, ask once whether a prototype would reduce uncertainty. After confirmation:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf handoff create <change-dir> \
+  --type prototype --objective "<confirmed objective>" \
+  --expected-output "<expected evidence>" --acceptance "<completion criterion>"
+npx --yes --package @xulthekl/team-flow@0.22.4 tf isolate <change-dir> prototype-<handoff-id>
+```
+Never suggest for backend/CLI/config/internal-refactor work. Never pass `--force`.
+
+## DP-0: User Confirmation Gate
+
+Run when: change folder doesn't exist, planning artifacts missing/empty, or `dp_0_confirmed` ≠ `true`.
+
+**Upstream Inheritance (v0.9)**：主信号 = `change-brief.md` 是否存在（非 yaml 字段）。
+
+判定伪代码：
+```
+brief = read(<change-dir>/change-brief.md)
+if brief 存在 and brief.upstream_source == "orchestrator":
+    # 编排分发：继承但允许修正（DP-0 仍执行，从"从零问"改为"一次确认继承或修正"）
+    defaults = { name: brief.upstream_change_id/<dir basename>,
+                 intent: brief.Scope,
+                 constraints: brief.约束,
+                 AC: brief.AC 列表 }
+    问用户(一次): "本 change 由 orchestrator 分发，继承意图/约束/AC 如下 {…}。
+                   [A] 继承并开始  [B] 我要修正（逐项覆盖 defaults）"
+    # 绝不重新问"你想做什么"——那是手动路径的问题
+else:
+    # 手动新建 / hotfix / 单 change 快速通道 / 存量 change（均无 brief）→ 照常 DP-0
+    问用户(原题): change name + 一句话意图 + 已知约束
+                 + 相关优化(纳入还是聚焦) + 沟通偏好
+两分支最终都写 dp_0_confirmed=true（命令见下）
+```
+
+- **为何以 brief 存在为主信号**：hotfix / 单 change 快速通道也是 orchestrator 创建的 change，但不产 brief；以 brief 存在为信号可天然排除这两条路径，且对存量手动 change（无 brief）零误伤。
+- **双源权威**：继承的 scope/AC 若与 `prd/vN/plan.md` 冲突，以 plan.md 为准（brief 是 S4 时刻快照，非真相源）；冲突时触发 Brief drift 提示（见「Staleness Detection」）。
+
+After confirmation:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_0_decisions "<summary>"
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_0_result confirmed
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_0_confirmed true
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_0_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+```
+
+## Mode Detection
+
+If workflow is `auto`/`null`/unset:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime infer <change-dir>
+```
+Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **tweak** (≤4 tasks, config/doc only), **full** (anything larger).
+
+## Staleness Detection
+
+- **Stale contract**: proposal scope expanded beyond contract scope fence → route to contract-builder
+- **Stale planning artifacts**: capability in proposal has no spec file, or vice versa → drift detected
+- **Stale tasks**: requirement in specs has no corresponding task → stale tasks
+- **Brief drift (advisory, v0.9)**: change-brief.md 的 `plan_hash` 与当前 plan.md 不一致 → 提示回 orchestrator 重新分发；**不**阻断、**不**进 artifacts_hash、**不**混入上述三条产物互查
+
+## Post-transition
+💡 `npx --yes --package @xulthekl/team-flow@0.22.4 tf inject <change-dir>` to update phase-guard artifacts.

package/src/index.ts

@@ -0,0 +1,16 @@
+export type { Scenario, Requirement } from './schema/base.js';
+export type { DeltaOperationType, Rename, Delta, Change } from './schema/change.js';
+export type { Spec } from './schema/spec.js';
+
+export type { ValidationLevel, ValidationIssue, ValidationReport } from './validation/types.js';
+export type { VerificationDimension, VerificationStatus, VerificationFinding, VerificationReport } from './validation/types.js';
+export type { ConflictReport, SyncConflict } from './validation/types.js';
+export { VALIDATION_MESSAGES, MIN_WHY_SECTION_LENGTH, MIN_PURPOSE_LENGTH, MAX_WHY_SECTION_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, MAX_DELTAS_PER_CHANGE, VERIFICATION_DIMENSIONS, VERIFICATION_MESSAGES, MIN_ABANDONMENT_REASON_LENGTH } from './validation/constants.js';
+export { Validator } from './validation/validator.js';
+
+export type { RequirementBlock, RequirementsSectionParts, DeltaPlan } from './parsing/requirement-blocks.js';
+export { REQUIREMENT_HEADER_REGEX, normalizeRequirementName, extractRequirementsSection, parseDeltaSpec } from './parsing/requirement-blocks.js';
+export type { ParsedDelta, ParsedChange } from './parsing/change-parser.js';
+export { parseChangeMarkdown } from './parsing/change-parser.js';
+
+export { tokenize, detectLanguage } from './validation/tokenizer.js';

package/src/parsing/change-parser.ts

@@ -0,0 +1,79 @@
+export interface ParsedDelta {
+  spec: string;
+  operation: string;
+  description: string;
+}
+
+export interface ParsedChange {
+  name: string;
+  why: string;
+  whatChanges: string;
+  deltas: ParsedDelta[];
+}
+
+function normalizeLineEndings(content: string): string {
+  return content.replace(/\r\n?/g, '\n');
+}
+
+function extractSection(content: string, heading: string): string {
+  const normalized = normalizeLineEndings(content);
+  const lines = normalized.split('\n');
+  // Match headings that contain the English keyword — supports both
+  // "## Why" and "## 背景（Why）" style bilingual headings.
+  const headingRegex = new RegExp(
+    `^##\\s+.*\\b${heading.replace(/\s+/g, '\\s+')}\\b.*$`,
+    'i'
+  );
+  const idx = lines.findIndex((l) => headingRegex.test(l));
+  if (idx === -1) return '';
+
+  let endIdx = lines.length;
+  for (let i = idx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      endIdx = i;
+      break;
+    }
+  }
+
+  return lines.slice(idx + 1, endIdx).join('\n').trim();
+}
+
+export function parseChangeMarkdown(
+  content: string,
+  changeName: string
+): ParsedChange {
+  const why = extractSection(content, 'Why');
+  const whatChanges = extractSection(content, 'What Changes');
+
+  const deltas: ParsedDelta[] = [];
+
+  const deltaSectionRegex =
+    /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/im;
+
+  const sections = content.split(/(?=^##\s)/m);
+  for (const section of sections) {
+    const match = section.match(deltaSectionRegex);
+    if (match) {
+      const operation = match[1].toUpperCase();
+      const body = section.substring(match[0].length).trim();
+      const descLines: string[] = [];
+      for (const line of body.split('\n')) {
+        if (/^###\s+/.test(line)) break;
+        const trimmed = line.trim();
+        if (trimmed) descLines.push(trimmed);
+      }
+      deltas.push({
+        spec: '',
+        operation,
+        description: descLines.join('\n'),
+      });
+    }
+  }
+
+  return {
+    name: changeName,
+    why,
+    whatChanges,
+    deltas,
+  };
+}