@xulthekl/team-flow 0.22.4 → 0.24.0

package/skills/workflow-start/SKILL.md

@@ -15,14 +15,14 @@ Do NOT invoke for: general coding tasks outside team-flow changes, casual questi
 
 ## 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`.
+`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.24.0 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.
+1. **Update check**: Run `npx --yes --package @xulthekl/team-flow@0.24.0 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.
+3. **Overlay recovery scan**: Run `npx --yes --package @xulthekl/team-flow@0.24.0 tf handoff list <change-dir> --json` and `npx --yes --package @xulthekl/team-flow@0.24.0 tf checkpoint list <change-dir> --json`. A `result-ready` handoff requires explicit review and `npx --yes --package @xulthekl/team-flow@0.24.0 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.24.0 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
 
@@ -36,17 +36,17 @@ Ask (manual path): change name + one-sentence intent, known constraints, related
 
 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)
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_decisions "<summary>"
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_result confirmed
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_confirmed true
+npx --yes --package @xulthekl/team-flow@0.24.0 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>`.
+If workflow is `auto`/`null`/unset: run `npx --yes --package @xulthekl/team-flow@0.24.0 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.24.0 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.
 
@@ -59,19 +59,19 @@ Change is fuzzy, scope unclear, comparing options, no stable change name.
 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.
+Guard: `npx --yes --package @xulthekl/team-flow@0.24.0 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.
+Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `npx --yes --package @xulthekl/team-flow@0.24.0 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.24.0 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.24.0 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.
+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.24.0 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: 归档确认`.
@@ -90,10 +90,10 @@ 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> \
+npx --yes --package @xulthekl/team-flow@0.24.0 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>
+npx --yes --package @xulthekl/team-flow@0.24.0 tf isolate <change-dir> prototype-<handoff-id>
 ```
 
 Never suggest or enter this route automatically for backend, CLI, configuration,
@@ -101,10 +101,13 @@ or internal-refactor work. Never pass `--force` to `tf isolate` for prototype
 work.
 
 ### Fast-Path Routing
+
+**DP-0 处理**（v0.22.5 F03 修复）：hotfix/tweak 路径隐式跳过 DP-0（`dp_0_confirmed` 保持 `null`），因为意图已明确（修复/微调），无需从零探索。contract-builder 的 DP-3 审批成为唯一门禁。
+
 - **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.
+Post-transition: 💡 `npx --yes --package @xulthekl/team-flow@0.24.0 tf inject <change-dir>` to update phase-guard artifacts.
 
 ## Staleness Detection
 
@@ -121,7 +124,7 @@ Use content inspection, not timestamps.
 ## 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 implementation for full/hotfix without a current `npx --yes --package @xulthekl/team-flow@0.24.0 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
@@ -133,6 +136,31 @@ Use content inspection, not timestamps.
 - 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 不豁免
 
+## State Writes (v0.22.5 F06 修复)
+
+workflow-start 负责写入以下字段到 `.team-flow.yaml`：
+
+**核心状态字段**：
+- `state`：当前状态（exploring/specifying/bridging/approved-for-build/executing/debugging/closing/abandoned）
+- `workflow`：工作流类型（auto/full/hotfix/tweak）
+
+**决策点字段**（各阶段确认后写入）：
+- `dp_0_*`：need-explorer 完成后的需求澄清决策
+- `dp_1_*`：spec-writer 完成后的规格决策
+- `dp_2_*`：contract-builder 完成后的契约决策
+- `dp_3_*`：build-executor 完成后的执行决策
+- `dp_5_*`：code-reviewer 完成后的审查决策
+- `dp_6_*`：release-archivist 完成后的发布决策
+- `dp_7_*`：其他决策点
+
+**架构设计门控字段**（v0.9 §26，v0.22.5 F02 修复）：
+- `arch_design_decision`：`required` | `skipped`（architecture-design 子代理返回，workflow-start 经 reasonableness check 后写入）
+- `arch_design_reason`：判断理由
+- `arch_design_timestamp`：ISO 8601 时间戳（UTC）
+- `arch_design_artifacts`：产出路径列表（required 时必填，skipped 时为空）
+
+**职责边界**：architecture-design 负责判断+产出，workflow-start 负责 reasonableness check + 状态写入。详细写入命令见 `references/routing-rules.md`「Route to architecture-design」。
+
 ## 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.

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

@@ -32,17 +32,17 @@ artifacts:                       # required 时必填
 - `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)
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> arch_design_decision "<required|skipped>"
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> arch_design_reason "<reason>"
+npx --yes --package @xulthekl/team-flow@0.24.0 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"
+npx --yes --package @xulthekl/team-flow@0.24.0 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.
+Guard: `npx --yes --package @xulthekl/team-flow@0.24.0 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.
 
@@ -55,12 +55,12 @@ 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 ...]
+npx --yes --package @xulthekl/team-flow@0.24.0 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
+npx --yes --package @xulthekl/team-flow@0.24.0 tf execution plan <change-dir> --mode <selected> --confirm ...
+npx --yes --package @xulthekl/team-flow@0.24.0 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.
@@ -71,7 +71,7 @@ Execution hit blockage: test failure, unexpected behavior, build error. After de
 ## 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>
+npx --yes --package @xulthekl/team-flow@0.24.0 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>
 ```
 
 ## Route to release-archivist
@@ -93,10 +93,10 @@ User explicitly requests, bug-investigator escalates after 3+ failures AND user
 
 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> \
+npx --yes --package @xulthekl/team-flow@0.24.0 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>
+npx --yes --package @xulthekl/team-flow@0.24.0 tf isolate <change-dir> prototype-<handoff-id>
 ```
 Never suggest for backend/CLI/config/internal-refactor work. Never pass `--force`.
 
@@ -130,17 +130,17 @@ else:
 
 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)
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_decisions "<summary>"
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_result confirmed
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_confirmed true
+npx --yes --package @xulthekl/team-flow@0.24.0 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>
+npx --yes --package @xulthekl/team-flow@0.24.0 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).
 
@@ -152,4 +152,4 @@ Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **twe
 - **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.
+💡 `npx --yes --package @xulthekl/team-flow@0.24.0 tf inject <change-dir>` to update phase-guard artifacts.

package/templates/api.md

@@ -0,0 +1,177 @@
+# API Design (Command/Read/Query 增量)
+
+> **变更 ID**: <change-id>
+> **基线版本**: <commit-hash>
+> **设计日期**: YYYY-MM-DD
+
+## 1. As-Is 基线（冻结复制）
+
+> 从全局 `docs/architecture/API-INDEX.md`（若有）复制当前状态，标注版本锚点。
+
+### 1.1 现有 Command API
+<列出本 change 涉及的现有 Command API，若无则写"无">
+
+### 1.2 现有 Read API
+<列出本 change 涉及的现有 Read API，若无则写"无">
+
+### 1.3 现有 Query API
+<列出本 change 涉及的现有 Query API，若无则写"无">
+
+---
+
+## 2. To-Be 增量设计
+
+### 2.1 Command API（写操作）
+
+> **五项检查 #4**: 是否涉及 API 新增/变更（端点、方法签名、请求响应 schema）？
+
+#### 新增 Command
+| 端点 | 方法 | 所属聚合 | 事务边界 | 说明 |
+|------|------|---------|---------|------|
+| `<endpoint>` | `POST` / `PUT` / `DELETE` | `<Aggregate>` | `<boundary>` | `<description>` |
+
+#### 修改 Command
+<列出修改的 Command 及变更内容，若无则写"无">
+
+#### 删除 Command
+<列出删除的 Command，若无则写"无">
+
+### 2.2 Read API（读操作）
+
+#### 新增 Read
+| 端点 | 方法 | 所属聚合 | 数据来源 | 说明 |
+|------|------|---------|---------|------|
+| `<endpoint>` | `GET` | `<Aggregate>` | `<source>` | `<description>` |
+
+#### 修改 Read
+<列出修改的 Read 及变更内容，若无则写"无">
+
+#### 删除 Read
+<列出删除的 Read，若无则写"无">
+
+### 2.3 Query API（查询操作）
+
+> **阻断测试分流**: Query API 经阻断测试判断是否属于数据服务
+
+#### 新增 Query
+| 端点 | 方法 | 查询模型 | 阻断测试结果 | 说明 |
+|------|------|---------|--------------|------|
+| `<endpoint>` | `GET` / `POST` | `<QueryModel>` | `业务服务` / `数据服务` | `<description>` |
+
+#### 修改 Query
+<列出修改的 Query 及变更内容，若无则写"无">
+
+#### 删除 Query
+<列出删除的 Query，若无则写"无">
+
+---
+
+## 3. 端点详细设计
+
+### 3.1 Command API 详细设计
+
+#### `<METHOD> <endpoint>`
+**说明**: `<description>`
+
+**请求 Schema**:
+```json
+{
+  "field1": "<type>",
+  "field2": "<type>"
+}
+```
+
+**响应 Schema**:
+```json
+{
+  "success": true,
+  "data": {
+    "id": "<type>"
+  }
+}
+```
+
+**错误码**:
+| 错误码 | 说明 | 处理方式 |
+|--------|------|---------|
+| `<code>` | `<description>` | `<handling>` |
+
+### 3.2 Read API 详细设计
+
+#### `GET <endpoint>`
+**说明**: `<description>`
+
+**查询参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `<param>` | `<type>` | `是` / `否` | `<description>` |
+
+**响应 Schema**:
+```json
+{
+  "items": [
+    {
+      "id": "<type>",
+      "field": "<type>"
+    }
+  ],
+  "total": "<int>"
+}
+```
+
+### 3.3 Query API 详细设计
+
+#### `<METHOD> <endpoint>`
+**说明**: `<description>`
+
+**请求 Schema**:
+```json
+{
+  "filters": {
+    "field1": "<type>"
+  },
+  "pagination": {
+    "page": "<int>",
+    "pageSize": "<int>"
+  }
+}
+```
+
+**响应 Schema**:
+```json
+{
+  "items": [
+    {
+      "id": "<type>",
+      "field": "<type>"
+    }
+  ],
+  "total": "<int>",
+  "page": "<int>",
+  "pageSize": "<int>"
+}
+```
+
+---
+
+## 4. 跨域一致性检查
+
+> **F2 · 跨域一致性**
+
+### 4.1 API ↔ 数据实体对齐
+| API 端点 | 支撑的数据实体 | 一致性 |
+|---------|---------------|--------|
+| `<endpoint>` | `<entity>` | ✅ / ❌ |
+
+### 4.2 术语命名统一性
+| 术语 | 定义位置 | 命名统一性 |
+|------|---------|-----------|
+| `<term>` | `<location>` | ✅ / ❌ |
+
+---
+
+## 5. 演进日志
+
+| 日期 | 变更 ID | 变更内容 | 影响范围 |
+|------|---------|---------|---------|
+| YYYY-MM-DD | `<change-id>` | `<summary>` | `<scope>` |

package/templates/architecture.md

@@ -0,0 +1,122 @@
+# Architecture Design (4A + DDD 增量)
+
+> **变更 ID**: <change-id>
+> **基线版本**: <commit-hash>
+> **设计日期**: YYYY-MM-DD
+
+## 1. As-Is 基线（冻结复制）
+
+> 从全局 `docs/architecture/ARCHITECTURE.md` 复制当前状态，标注版本锚点。
+
+### 1.1 现有聚合
+<列出本 change 涉及的现有聚合，若无则写"无">
+
+### 1.2 现有限界上下文
+<列出本 change 涉及的现有限界上下文，若无则写"无">
+
+### 1.3 现有 Context Map
+<列出本 change 涉及的现有上下文映射关系，若无则写"无">
+
+---
+
+## 2. To-Be 增量设计（DDD）
+
+### 2.1 聚合变更
+
+> **五项检查 #1**: 是否新增/修改聚合或聚合根？
+
+#### 新增聚合
+| 聚合名称 | 聚合根 | 实体/值对象 | 事务边界 | 所属限界上下文 |
+|---------|--------|------------|---------|---------------|
+| `<Aggregate>` | `<Root>` | `<Entity1>`, `<VO1>` | `<boundary>` | `<BC>` |
+
+#### 修改聚合
+<列出修改的聚合及变更内容，若无则写"无">
+
+#### 删除聚合
+<列出删除的聚合，若无则写"无">
+
+### 2.2 限界上下文变更
+
+> **五项检查 #2**: 是否涉及限界上下文边界变化或新增上下文映射关系？
+
+#### 新增限界上下文
+| 上下文名称 | 职责描述 | 包含聚合 | 语言类型 |
+|-----------|---------|---------|---------|
+| `<BC>` | `<responsibility>` | `<aggregates>` | `<ubiquitous language>` |
+
+#### 修改限界上下文
+<列出修改的限界上下文及变更内容，若无则写"无">
+
+#### 删除限界上下文
+<列出删除的限界上下文，若无则写"无">
+
+### 2.3 Context Map 变更
+
+> **五项检查 #2（续）**: 新增上下文映射关系
+
+#### 新增映射
+| 上游上下文 | 下游上下文 | 映射类型 | 说明 |
+|-----------|-----------|---------|------|
+| `<upstream>` | `<downstream>` | `Shared Kernel` / `ACL` / `OHS` | `<description>` |
+
+#### 修改映射
+<列出修改的映射关系，若无则写"无">
+
+#### 删除映射
+<列出删除的映射关系，若无则写"无">
+
+### 2.4 CQRS 写/读模型变更
+
+> **五项检查 #3**: 是否涉及 CQRS 写模型或读模型变化？
+
+#### 写模型变更（事务型对象）
+| 聚合 | 操作类型 | 命令/查询 | 事务边界 |
+|------|---------|----------|---------|
+| `<Aggregate>` | `Command` / `Read` | `<operation>` | `<boundary>` |
+
+#### 读模型变更（分析型对象）
+| 查询模型 | 数据来源 | 派生逻辑 | 用途 |
+|---------|---------|---------|------|
+| `<QueryModel>` | `<source>` | `<derivation>` | `<usage>` |
+
+---
+
+## 3. 变更分叉级联分析
+
+> **F3 · 变更分叉级联（三层次必覆盖）**
+
+### 3.1 直接依赖
+<BA→AA/IA 同变：列出直接依赖的架构变更>
+
+### 3.2 间接依赖
+<AA/IA→TA、IA↔AA 对齐调整：列出间接依赖>
+
+### 3.3 隐式依赖
+<表面无关却牵动的变更：列出隐式依赖>
+
+---
+
+## 4. 跨域一致性检查（双对齐，质量门禁）
+
+> **F2 · 跨域一致性**
+
+### 4.1 结构一致性检查
+| AA 功能 | 支撑的 IA 数据实体 | 一致性 |
+|---------|-------------------|--------|
+| `<function>` | `<entity>` | ✅ / ❌ |
+
+### 4.2 语义一致性检查
+| 术语 | 定义位置 | 命名统一性 |
+|------|---------|-----------|
+| `<term>` | `<location>` | ✅ / ❌ |
+
+---
+
+## 5. 演进日志
+
+> **F8 · 增量设计 + 复利回写闭环**
+
+| 日期 | 变更 ID | 变更内容 | 影响范围 |
+|------|---------|---------|---------|
+| YYYY-MM-DD | `<change-id>` | `<summary>` | `<scope>` |

package/templates/change-brief.md

@@ -0,0 +1,24 @@
+---
+upstream_source: orchestrator          # orchestrator | manual | null
+upstream_req_id: <req-id>              # 对应 .team-flow/requirements/<req-id>/
+upstream_plan_ref: prd/vN/plan.md      # hotfix/快速通道为 null
+upstream_change_id: C2                 # 对应 change_dag.id
+plan_hash: sha256:<plan.md 内容摘要>    # 检测产品层改动后变更层未同步
+---
+# Change Brief: <change-name>
+
+## Scope
+<用户故事/功能模块级 scope 描述，与 plan.md 该 change 的 Scope 一致>
+
+## 约束
+<来自 plan.md 的全局约束 / 该 change 的已知约束>
+
+## AC 列表
+<取自 auditor 报告 Dim1 覆盖矩阵中映射到本 change 的 AC，逐条列出>
+
+## 全局技术方向
+<取自 plan.md 高阶技术设计段的要点指针：模块边界/技术选型/数据流方向，供 spec-writer 作 design.md 约束>
+
+## PRD & plan 引用
+- PRD: prd/vN/prd.md §<相关章节>
+- Plan: prd/vN/plan.md ### <C-ID>

package/templates/database.md

@@ -0,0 +1,114 @@
+# Database Design (CQRS 增量)
+
+> **变更 ID**: <change-id>
+> **基线版本**: <commit-hash>
+> **设计日期**: YYYY-MM-DD
+
+## 1. As-Is 基线（冻结复制）
+
+> 从全局 `docs/architecture/DATABASE.md` 复制当前状态，标注版本锚点。
+
+### 1.1 现有写模型
+<列出本 change 涉及的现有写模型（聚合对应的事务型表），若无则写"无">
+
+### 1.2 现有读模型
+<列出本 change 涉及的现有读模型（查询模型对应的表/视图），若无则写"无">
+
+---
+
+## 2. To-Be 增量设计
+
+### 2.1 写模型变更（事务型对象）
+
+> **五项检查 #5**: 是否涉及数据库表结构、字段、索引变更？
+
+#### 新增表
+| 表名 | 所属聚合 | 主键类型 | 事务边界 | 说明 |
+|------|---------|---------|---------|------|
+| `<table>` | `<Aggregate>` | `<pk-type>` | `<boundary>` | `<description>` |
+
+#### 修改表
+| 表名 | 变更类型 | 变更内容 |
+|------|---------|---------|
+| `<table>` | `ADD COLUMN` / `MODIFY COLUMN` / `DROP COLUMN` / `ADD INDEX` | `<details>` |
+
+#### 删除表
+<列出删除的表，若无则写"无">
+
+### 2.2 读模型变更（分析型对象）
+
+#### 新增查询模型
+| 查询模型 | 数据来源 | 派生逻辑 | 用途 |
+|---------|---------|---------|------|
+| `<QueryModel>` | `<source tables>` | `<derivation>` | `<usage>` |
+
+#### 修改查询模型
+<列出修改的查询模型及变更内容，若无则写"无">
+
+#### 删除查询模型
+<列出删除的查询模型，若无则写"无">
+
+---
+
+## 3. Schema 变更详情
+
+### 3.1 新增表 DDL
+```sql
+CREATE TABLE <table_name> (
+    id BIGINT PRIMARY KEY,
+    -- 字段定义
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### 3.2 修改表 DDL
+```sql
+ALTER TABLE <table_name> ADD COLUMN <column> <type>;
+ALTER TABLE <table_name> ADD INDEX idx_<name> (<columns>);
+```
+
+### 3.3 索引变更
+| 表名 | 索引名 | 索引类型 | 字段 | 说明 |
+|------|--------|---------|------|------|
+| `<table>` | `idx_<name>` | `PRIMARY` / `UNIQUE` / `INDEX` | `<columns>` | `<description>` |
+
+---
+
+## 4. 实体关系变更
+
+### 4.1 新增实体
+| 实体名称 | 所属聚合 | 实体类型 | 唯一标识 | 说明 |
+|---------|---------|---------|---------|------|
+| `<Entity>` | `<Aggregate>` | `实体` / `值对象` | `<identifier>` | `<description>` |
+
+### 4.2 修改实体
+<列出修改的实体及变更内容，若无则写"无">
+
+### 4.3 删除实体
+<列出删除的实体，若无则写"无">
+
+---
+
+## 5. 数据迁移脚本
+
+> 若涉及数据迁移，提供迁移脚本（幂等、可回滚）
+
+### 5.1 迁移脚本
+```sql
+-- 迁移描述：<description>
+-- 执行顺序：<order>
+-- 回滚方式：<rollback>
+
+BEGIN;
+-- 迁移逻辑
+COMMIT;
+```
+
+---
+
+## 6. 演进日志
+
+| 日期 | 变更 ID | 变更内容 | 影响范围 |
+|------|---------|---------|---------|
+| YYYY-MM-DD | `<change-id>` | `<summary>` | `<scope>` |