adspecs 0.1.19 → 0.1.21

package/skills/adspecs-update-status/SKILL.md

@@ -1,382 +1,382 @@
----
-name: adspecs-update-status
-description: "更新 .adspecs/feature.json 中各阶段数组的功能状态值。首次执行时输出功能追踪矩阵（各功能所处阶段、状态、创建时间及汇总统计）。支持 requirement、prd、frontDemos、endDesigns、frontDesigns、endCodes、unitTests、situationTests、uats、deploys 十类数组。Use when the user asks to update feature status, change stage status, mark requirement as reviewed, or update feature.json status."
-argument-hint: "[<功能ID> <状态值>] [--category <数组类别>] [--list]"
-user-invocable: true
----
-
-# 功能状态更新 (Feature Status Update)
-
-## 概述
-
-管理 `.adspecs/feature.json` 中各开发阶段数组里功能条目的 `status` 状态值。首次执行时自动输出**功能追踪矩阵**，展示各功能所处阶段、当前状态和创建时间，并按阶段和状态进行汇总统计。支持单个更新或批量更新。
-
-## 适用场景
-
-- 查看当前各阶段功能的状态分布（功能追踪矩阵）
-- 需求评审通过后，将 `requirement` 中的状态从"草稿"改为"评审通过"
-- PRD 进入评审阶段，更新 `prd` 数组中的状态
-- 系统设计完成评审，更新 `endDesigns` 中的状态
-- 批量推进功能状态
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-### 参数说明
-
-| 参数         | 必填 | 说明                                                                  | 示例                              |
-| ------------ | ---- | --------------------------------------------------------------------- | --------------------------------- |
-| `<功能ID>`   | 否   | 功能条目的 `id` 字段值（支持前缀匹配），省略时仅输出追踪矩阵          | `p05-01-aluminum-ingot-receiving` |
-| `<状态值>`   | 是   | 目标状态：`草稿` / `评审中` / `修改中` / `评审通过` / `暂停` / `取消` | `评审通过`                        |
-| `--category` | 是   | 指定数组类别（不指定时自动搜索全部数组）                              | `--category requirement`          |
-| `--list`     | 否   | 仅输出功能追踪矩阵（同省略参数）                                      | `--list`                          |
-
-### 状态值映射
-
-| 中文显示 | 内部存储值  | 说明                   |
-| -------- | ----------- | ---------------------- |
-| 草稿     | `drafting`  | 初始创建，尚未提交评审 |
-| 评审中   | `reviewing` | 已提交评审，等待审核   |
-| 修改中   | `revising`  | 评审发现问题，正在修改 |
-| 通过     | `approved`  | 评审通过，进入下一阶段 |
-| 暂停     | `paused`    | 功能暂停，暂不推进     |
-| 取消     | `canceled`  | 功能取消，不再推进     |
-
-### phase 阶段数组类别
-
-| 类别名称     | 对应 JSON 键     | 阶段说明           |
-| ------------ | ---------------- | ------------------ |
-| 业务需求     | `requirement`    | 业务需求分析阶段   |
-| 产品需求     | `prd`            | 产品需求说明书阶段 |
-| 前端演示     | `frontDemos`     | 前端演示项目       |
-| 后端设计     | `endDesigns`     | 后端系统设计阶段   |
-| 前端设计     | `frontDesigns`   | 前端功能设计阶段   |
-| 后端代码     | `endCodes`       | 后端代码实现阶段   |
-| 前端代码     | `frontCodes`     | 前端代码实现阶段   |
-| 单元测试     | `unitTests`      | 单元测试阶段       |
-| 集成测试     | `situationTests` | 系统集成测试阶段   |
-| 代码评审     | `codeReviews`    | 代码评审阶段       |
-| 用户验收测试 | `uats`           | 用户验收测试阶段   |
-| 部署         | `deploys`        | 部署上线阶段       |
-
-## CR 状态机
-
-```mermaid
-stateDiagram-v2
-  [*] --> drafting
-  drafting --> requirement_reviewing: review-requirement
-  requirement_reviewing --> requirement_approved: approve-requirement
-  requirement_approved --> tech_designing: write-tech-design
-  tech_designing --> tech_design_review_pending: write-tech-design complete
-  tech_design_review_pending --> tech_designing: review-tech-design block
-  tech_design_review_pending --> tech_design_reviewed: approve-tech-design
-  tech_design_reviewed --> task_breakdown: write-dev-tasks
-  task_breakdown --> developing: approve-dev-start
-  developing --> code_reviewing: review-code pass
-  code_reviewing --> code_approved: approve-code
-  code_approved --> merging: merge-feature-branch
-  merging --> writing_back: writeback-prd-sdd
-  writing_back --> archived: cr-archive
-```
-
-`human_approval` 只表示人工确认，不直接改状态。所有状态推进必须由显式 Skill 完成。`tech-design-review-pending` 同时覆盖”SDD 已写完待自动 Review”和”自动 Review 已通过待人工审批”，因此恢复/看板/人工接续时必须读取 `review-annotations/sdd.yml`：只有 `verdict=pass` 且 `blockers=[]` 时，下一步才是 `human_approval -> approve-tech-design`。
-
-### 状态流转表
-
-| #   | 当前状态                     | 目标状态                     | 触发 Skill                    | 触发条件                                | 说明                                                                                   |
-| --- | ---------------------------- | ---------------------------- | ----------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
-| 1   | `[*]`（初始）                | `drafting`                   | CR 注册                       | 用户发起 `/requirement`                 | 创建 CR 目录与 `cr.md`，进入需求草稿阶段                                               |
-| 2   | `drafting`                   | `requirement_reviewing`      | `review-requirement`          | PRD 草稿完成                            | 自动需求评审；若产出 blockers 则回退 `drafting` 修复，最多 3 次                        |
-| 3   | `requirement_reviewing`      | `requirement_approved`       | `approve-requirement`         | `verdict=pass` 且人工确认               | 需求评审通过后人工审批推进                                                             |
-| 4   | `requirement_approved`       | `tech_designing`             | `write-tech-design`           | 需求已审批                              | 开始编写技术设计文档（SDD）                                                            |
-| 5   | `tech_designing`             | `tech_design_review_pending` | `write-tech-design`（完成）   | SDD 编写完成                            | SDD 写完后进入待评审状态                                                               |
-| 6   | `tech_design_review_pending` | `tech_designing`             | `review-tech-design`（block） | 评审发现 blockers                       | SDD 评审不通过，回到设计修订，最多 3 次                                                |
-| 7   | `tech_design_review_pending` | `tech_design_reviewed`       | `approve-tech-design`         | `verdict=pass` 且人工确认               | 技术设计评审通过后人工审批推进                                                         |
-| 8   | `tech_design_reviewed`       | `task_breakdown`             | `write-dev-tasks`             | 技术设计已审批                          | 基于已审批的 SDD 拆解开发任务                                                          |
-| 9   | `task_breakdown`             | `developing`                 | `approve-dev-start`           | 任务拆解完成且人工确认                  | 开发启动确认，进入编码阶段                                                             |
-| 10  | `developing`                 | `code_reviewing`             | `review-code`（pass）         | 代码实现完成且测试报告 `status=pass`    | 代码评审通过，进入代码审批待确认                                                       |
-| 11  | `code_reviewing`             | `developing`                 | `review-code`（block）        | 评审发现 blockers                       | 代码评审不通过，按 `replayNodes` 重跑修复闭环，最多 3 次                               |
-| 12  | `code_reviewing`             | `code_approved`              | `approve-code`                | `verdict=pass` 且测试证据完备且人工确认 | 代码审批通过                                                                           |
-| 13  | `code_approved`              | `merging`                    | `merge-feature-branch`        | 代码已审批                              | 合并特性分支到主干                                                                     |
-| 14  | `merging`                    | `writing_back`               | `writeback-prd-sdd`           | 分支合并完成                            | 将 PRD / SDD 回写到 `specs/{id}/`，任务回写到 `delivery/task/`                         |
-| 15  | `writing_back`               | `archived`                   | `cr-archive`                  | 回写完成                                | CR 从 `_backlog.yml` 移至 `_history.yml`，保留 `change-requests/{CR-ID}/` 作为历史痕迹 |
-
-## 工作流程
-
-### 步骤 0：定位并读取 feature.json
-
-1. 检查项目根目录下是否存在 `.adspecs/feature.json`
-2. 如不存在 → 输出错误：`❌ 未找到 .adspecs/feature.json，请先执行 /project-init 初始化项目`
-3. 读取文件内容
-
-### 步骤 1：输出功能追踪矩阵
-
-**每次执行本技能时，必须先输出功能追踪矩阵**，然后再执行后续的状态更新操作。
-
-遍历 `feature.json` 中的十一个阶段数组，按以下格式输出：
-
-```markdown
-## 功能追踪矩阵 📊
-
-> 生成时间：{当前日期时间}
-
-### 各阶段功能明细
-
-#### 📋 业务需求 (requirement)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### 📄 产品需求 (prd)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### 🎨 前端演示 (frontDemos)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### 🔧 后端设计 (endDesigns)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### 🎯 前端设计 (frontDesigns)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### 💻 后端代码 (endCodes)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### 🖥️ 前端代码 (frontCodes)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### 🧪 单元测试 (unitTests)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### 🔬 集成测试 (situationTests)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### ✅ 用户验收测试 (uats)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-#### 🚀 部署 (depolys)
-
-| ID   | 名称   | 状态         | 创建时间  | 目录        |
-| ---- | ------ | ------------ | --------- | ----------- |
-| {id} | {name} | {status中文} | {created} | {directory} |
-
-> 空数组显示 "（暂无条目）"
-
-### 汇总统计
-
-#### 按阶段统计
-
-| 阶段     | 条目数      | 草稿     | 评审中   | 修改中   | 评审通过 |
-| -------- | ----------- | -------- | -------- | -------- | -------- |
-| 业务需求 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 产品需求 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 前端演示 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 后端设计 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 前端设计 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 后端代码 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 前端代码 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 单元测试 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 集成测试 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 用户验收 | {N}         | {n}      | {n}      | {n}      | {n}      |
-| 部署     | {N}         | {n}      | {n}      | {n}      | {n}      |
-| **合计** | **{total}** | **{t1}** | **{t2}** | **{t3}** | **{t4}** |
-
-#### 按状态统计
-
-| 状态                | 数量        | 占比     |
-| ------------------- | ----------- | -------- |
-| 草稿 (drafting)     | {N}         | {%}      |
-| 评审中 (reviewing)  | {N}         | {%}      |
-| 修改中 (revising)   | {N}         | {%}      |
-| 评审通过 (approved) | {N}         | {%}      |
-| **合计**            | **{total}** | **100%** |
-```
-
-**输出规则**：
-
-- 状态值自动转换为中文显示（`drafting` → 草稿、`reviewing` → 评审中、`revising` → 修改中、`approved` → 评审通过）
-- 空数组在明细表中显示"（暂无条目）"，在汇总统计中显示 0
-- 占比保留一位小数
-- 如果 `$ARGUMENTS` 仅为 `--list` 或为空 → 输出追踪矩阵后结束，不执行后续更新步骤
-
-### 步骤 2：解析参数
-
-从 `$ARGUMENTS` 中解析（如果提供了功能 ID 和状态值）：
-
-- `feature_id`：功能 ID
-- `target_status`：目标状态（支持中文或英文值）
-- `category`：数组类别（可选）
-
-**状态值转换**：
-
-- 用户输入"草稿" → 存储 `drafting`
-- 用户输入"评审中" → 存储 `reviewing`
-- 用户输入"修改中" → 存储 `revising`
-- 用户输入"评审通过" → 存储 `approved`
-- 用户直接输入英文值（如 `approved`）→ 直接使用
-
-**类别名称转换**：
-
-- 用户输入"业务需求"或"requirement" → `requirement`
-- 用户输入"产品需求"或"prd" → `prd`
-- 用户输入"前端演示"或"frontDemos" → `frontDemos`
-- 用户输入"后端设计"或"endDesigns" → `endDesigns`
-- 用户输入"前端设计"或"frontDesigns" → `frontDesigns`
-- 用户输入"后端代码"或"endCodes" → `endCodes`
-- 用户输入"前端代码"或"frontCodes" → `frontCodes`
-- 用户输入"单元测试"或"unitTests" → `unitTests`
-- 用户输入"集成测试"或"situationTests" → `situationTests`
-- 用户输入"用户验收"或"uats" → `uats`
-- 用户输入"部署"或"depolys" → `depolys`
-
-### 步骤 3：查找匹配条目
-
-1. 如果指定了 `category` → 仅在对应数组中搜索
-2. 如果未指定 `category` → 按以下顺序搜索全部数组：
-   `requirement` → `prd` → `frontDemos` → `endDesigns` → `frontDesigns` → `endCodes` → `frontCodes` → `unitTests` → `situationTests` → `uats` → `depolys`
-
-3. **匹配规则**（按优先级）：
-   - **精确匹配**：`id` 字段完全等于 `feature_id`
-   - **前缀匹配**：`id` 字段以 `feature_id` 开头（当精确匹配无结果时）
-   - **名称匹配**：`name` 字段包含 `feature_id`（当前缀匹配也无结果时）
-
-4. 如果找到多个匹配 → 列出所有匹配项，询问用户确认要更新哪一个
-5. 如果无匹配 → 输出错误：`❌ 未找到匹配的功能条目（ID: {feature_id}），请检查 ID 是否正确`
-
-### 步骤 4：执行更新
-
-1. 显示当前状态和目标状态：
-
-   ```
-   📋 功能: {name}
-   📂 ID: {id}
-   📁 目录: {directory}
-   🔄 状态变更: {旧状态中文} → {新状态中文}
-   ```
-
-2. 将匹配条目的 `status` 字段更新为目标状态值
-
-### 步骤 5：写回文件
-
-1. 使用 Write 工具将更新后的 JSON 写回 `.adspecs/feature.json`
-2. 保持 2-space 缩进格式
-3. 保持文件末尾有一个换行符
-
-4. **同步 YAML 文件**：如果项目根目录下存在 `.adspecs/feature.yml`，将更新后的数据同步写入该文件：
-   - 读取刚写入的 `feature.json` 内容
-   - 转换为 YAML 格式（保持键顺序一致）
-   - 使用 Write 工具写回 `.adspecs/feature.yml`
-   - YAML 文件头部保留注释说明（`# adspecs Feature Tracking - YAML format`）
-   - 如果 `feature.yml` 不存在，跳过此步骤（不自动创建）
-
-### 步骤 6：输出结果
-
-```
-✅ 状态更新完成
-
-功能: {name}
-ID: {id}
-类别: {类别中文名称}
-状态: {旧状态中文} → {新状态中文}
-```
-
-### 批量更新模式
-
-当 `feature_id` 使用通配符或关键词匹配到多个条目时，支持批量更新。
-
-**触发条件**：
-
-- `feature_id` 为 `*` 或 `all` → 更新指定类别（或全部类别）中的所有条目
-- `feature_id` 匹配到多个条目且用户确认批量更新
-
-**执行流程**：
-
-1. 列出所有将被更新的条目及其当前状态
-2. 询问用户确认：`确认将以上 {N} 个条目的状态更新为 {目标状态}？`
-3. 用户确认后，批量更新所有匹配条目
-4. 输出批量更新结果摘要
-
-## 扩展钩子
-
-### 执行前检查
-
-检查项目根目录下是否存在 `.adspecs/extensions.yml`。如果存在且配置了 `before_update_status` 钩子，执行相应操作。
-
-### 执行后钩子
-
-状态更新完成后，检查 `.adspecs/extensions.yml` 中 `hooks.after_update_status` 键下的条目，按规则处理。
-
-## 错误处理
-
-| 场景                                   | 处理方式                                                |
-| -------------------------------------- | ------------------------------------------------------- |
-| `.adspecs/feature.json` 不存在         | 输出错误并提示执行 `/project-init`                      |
-| `feature.json` 格式错误（非有效 JSON） | 输出错误并提示检查文件格式                              |
-| 功能 ID 未找到                         | 输出错误并列出所有可用 ID（前 10 个）                   |
-| 状态值无效                             | 输出错误并列出有效状态值                                |
-| 目标数组不存在或为 null                | 输出警告并跳过该数组                                    |
-| 条目当前状态已与目标相同               | 输出提示 `ℹ️ 状态未变更（当前已是 {状态}）`，不写入文件 |
-
-## 使用示例
-
-```bash
-# 仅查看功能追踪矩阵
-/adspecs-update-status
-
-# 更新业务需求状态为评审通过
-/adspecs-update-status p05-01-aluminum-ingot-receiving 评审通过 --category requirement
-
-# 自动搜索所有数组，找到匹配 ID 后更新
-/adspecs-update-status p05-01 评审中
-
-# 列出所有功能状态（同省略参数）
-/adspecs-update-status --list
-
-# 批量更新所有业务需求为评审通过
-/adspecs-update-status all 评审通过 --category requirement
-
-# 使用中文类别名
-/adspecs-update-status p05-01 草稿 --category 后端设计
-```
-
-## 完成标志
-
-- [ ] 已正确定位并读取 `.adspecs/feature.json` 文件
-- [ ] 已输出功能追踪矩阵（含各阶段明细和汇总统计）
-- [ ] 已正确解析功能 ID 和目标状态值（如有提供）
-- [ ] 已按匹配规则找到目标功能条目（如有提供）
-- [ ] 状态值已正确转换（中文 → 英文存储值）
-- [ ] 已更新 `status` 字段并写回 `feature.json`（保持 JSON 格式）
-- [ ] 已同步 `feature.yml`（如存在）
-- [ ] 已输出更新结果（含变更前后状态对比）
+---
+name: adspecs-update-status
+description: "更新 .adspecs/feature.json 中各阶段数组的功能状态值。首次执行时输出功能追踪矩阵（各功能所处阶段、状态、创建时间及汇总统计）。支持 requirement、prd、frontDemos、endDesigns、frontDesigns、endCodes、unitTests、situationTests、uats、deploys 十类数组。Use when the user asks to update feature status, change stage status, mark requirement as reviewed, or update feature.json status."
+argument-hint: "[<功能ID> <状态值>] [--category <数组类别>] [--list]"
+user-invocable: true
+---
+
+# 功能状态更新 (Feature Status Update)
+
+## 概述
+
+管理 `.adspecs/feature.json` 中各开发阶段数组里功能条目的 `status` 状态值。首次执行时自动输出**功能追踪矩阵**，展示各功能所处阶段、当前状态和创建时间，并按阶段和状态进行汇总统计。支持单个更新或批量更新。
+
+## 适用场景
+
+- 查看当前各阶段功能的状态分布（功能追踪矩阵）
+- 需求评审通过后，将 `requirement` 中的状态从"草稿"改为"评审通过"
+- PRD 进入评审阶段，更新 `prd` 数组中的状态
+- 系统设计完成评审，更新 `endDesigns` 中的状态
+- 批量推进功能状态
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+### 参数说明
+
+| 参数         | 必填 | 说明                                                                  | 示例                              |
+| ------------ | ---- | --------------------------------------------------------------------- | --------------------------------- |
+| `<功能ID>`   | 否   | 功能条目的 `id` 字段值（支持前缀匹配），省略时仅输出追踪矩阵          | `p05-01-aluminum-ingot-receiving` |
+| `<状态值>`   | 是   | 目标状态：`草稿` / `评审中` / `修改中` / `评审通过` / `暂停` / `取消` | `评审通过`                        |
+| `--category` | 是   | 指定数组类别（不指定时自动搜索全部数组）                              | `--category requirement`          |
+| `--list`     | 否   | 仅输出功能追踪矩阵（同省略参数）                                      | `--list`                          |
+
+### 状态值映射
+
+| 中文显示 | 内部存储值  | 说明                   |
+| -------- | ----------- | ---------------------- |
+| 草稿     | `drafting`  | 初始创建，尚未提交评审 |
+| 评审中   | `reviewing` | 已提交评审，等待审核   |
+| 修改中   | `revising`  | 评审发现问题，正在修改 |
+| 通过     | `approved`  | 评审通过，进入下一阶段 |
+| 暂停     | `paused`    | 功能暂停，暂不推进     |
+| 取消     | `canceled`  | 功能取消，不再推进     |
+
+### phase 阶段数组类别
+
+| 类别名称     | 对应 JSON 键     | 阶段说明           |
+| ------------ | ---------------- | ------------------ |
+| 业务需求     | `requirement`    | 业务需求分析阶段   |
+| 产品需求     | `prd`            | 产品需求说明书阶段 |
+| 前端演示     | `frontDemos`     | 前端演示项目       |
+| 后端设计     | `endDesigns`     | 后端系统设计阶段   |
+| 前端设计     | `frontDesigns`   | 前端功能设计阶段   |
+| 后端代码     | `endCodes`       | 后端代码实现阶段   |
+| 前端代码     | `frontCodes`     | 前端代码实现阶段   |
+| 单元测试     | `unitTests`      | 单元测试阶段       |
+| 集成测试     | `situationTests` | 系统集成测试阶段   |
+| 代码评审     | `codeReviews`    | 代码评审阶段       |
+| 用户验收测试 | `uats`           | 用户验收测试阶段   |
+| 部署         | `deploys`        | 部署上线阶段       |
+
+## CR 状态机
+
+```mermaid
+stateDiagram-v2
+  [*] --> drafting
+  drafting --> requirement_reviewing: review-requirement
+  requirement_reviewing --> requirement_approved: approve-requirement
+  requirement_approved --> tech_designing: write-tech-design
+  tech_designing --> tech_design_review_pending: write-tech-design complete
+  tech_design_review_pending --> tech_designing: review-tech-design block
+  tech_design_review_pending --> tech_design_reviewed: approve-tech-design
+  tech_design_reviewed --> task_breakdown: write-dev-tasks
+  task_breakdown --> developing: approve-dev-start
+  developing --> code_reviewing: review-code pass
+  code_reviewing --> code_approved: approve-code
+  code_approved --> merging: merge-feature-branch
+  merging --> writing_back: writeback-prd-sdd
+  writing_back --> archived: cr-archive
+```
+
+`human_approval` 只表示人工确认，不直接改状态。所有状态推进必须由显式 Skill 完成。`tech-design-review-pending` 同时覆盖”SDD 已写完待自动 Review”和”自动 Review 已通过待人工审批”，因此恢复/看板/人工接续时必须读取 `review-annotations/sdd.yml`：只有 `verdict=pass` 且 `blockers=[]` 时，下一步才是 `human_approval -> approve-tech-design`。
+
+### 状态流转表
+
+| #   | 当前状态                     | 目标状态                     | 触发 Skill                    | 触发条件                                | 说明                                                                                   |
+| --- | ---------------------------- | ---------------------------- | ----------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
+| 1   | `[*]`（初始）                | `drafting`                   | CR 注册                       | 用户发起 `/requirement`                 | 创建 CR 目录与 `cr.md`，进入需求草稿阶段                                               |
+| 2   | `drafting`                   | `requirement_reviewing`      | `review-requirement`          | PRD 草稿完成                            | 自动需求评审；若产出 blockers 则回退 `drafting` 修复，最多 3 次                        |
+| 3   | `requirement_reviewing`      | `requirement_approved`       | `approve-requirement`         | `verdict=pass` 且人工确认               | 需求评审通过后人工审批推进                                                             |
+| 4   | `requirement_approved`       | `tech_designing`             | `write-tech-design`           | 需求已审批                              | 开始编写技术设计文档（SDD）                                                            |
+| 5   | `tech_designing`             | `tech_design_review_pending` | `write-tech-design`（完成）   | SDD 编写完成                            | SDD 写完后进入待评审状态                                                               |
+| 6   | `tech_design_review_pending` | `tech_designing`             | `review-tech-design`（block） | 评审发现 blockers                       | SDD 评审不通过，回到设计修订，最多 3 次                                                |
+| 7   | `tech_design_review_pending` | `tech_design_reviewed`       | `approve-tech-design`         | `verdict=pass` 且人工确认               | 技术设计评审通过后人工审批推进                                                         |
+| 8   | `tech_design_reviewed`       | `task_breakdown`             | `write-dev-tasks`             | 技术设计已审批                          | 基于已审批的 SDD 拆解开发任务                                                          |
+| 9   | `task_breakdown`             | `developing`                 | `approve-dev-start`           | 任务拆解完成且人工确认                  | 开发启动确认，进入编码阶段                                                             |
+| 10  | `developing`                 | `code_reviewing`             | `review-code`（pass）         | 代码实现完成且测试报告 `status=pass`    | 代码评审通过，进入代码审批待确认                                                       |
+| 11  | `code_reviewing`             | `developing`                 | `review-code`（block）        | 评审发现 blockers                       | 代码评审不通过，按 `replayNodes` 重跑修复闭环，最多 3 次                               |
+| 12  | `code_reviewing`             | `code_approved`              | `approve-code`                | `verdict=pass` 且测试证据完备且人工确认 | 代码审批通过                                                                           |
+| 13  | `code_approved`              | `merging`                    | `merge-feature-branch`        | 代码已审批                              | 合并特性分支到主干                                                                     |
+| 14  | `merging`                    | `writing_back`               | `writeback-prd-sdd`           | 分支合并完成                            | 将 PRD / SDD 回写到 `specs/{id}/`，任务回写到 `delivery/task/`                         |
+| 15  | `writing_back`               | `archived`                   | `cr-archive`                  | 回写完成                                | CR 从 `_backlog.yml` 移至 `_history.yml`，保留 `change-requests/{CR-ID}/` 作为历史痕迹 |
+
+## 工作流程
+
+### 步骤 0：定位并读取 feature.json
+
+1. 检查项目根目录下是否存在 `.adspecs/feature.json`
+2. 如不存在 → 输出错误：`❌ 未找到 .adspecs/feature.json，请先执行 /project-init 初始化项目`
+3. 读取文件内容
+
+### 步骤 1：输出功能追踪矩阵
+
+**每次执行本技能时，必须先输出功能追踪矩阵**，然后再执行后续的状态更新操作。
+
+遍历 `feature.json` 中的十一个阶段数组，按以下格式输出：
+
+```markdown
+## 功能追踪矩阵 📊
+
+> 生成时间：{当前日期时间}
+
+### 各阶段功能明细
+
+#### 📋 业务需求 (requirement)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### 📄 产品需求 (prd)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### 🎨 前端演示 (frontDemos)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### 🔧 后端设计 (endDesigns)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### 🎯 前端设计 (frontDesigns)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### 💻 后端代码 (endCodes)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### 🖥️ 前端代码 (frontCodes)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### 🧪 单元测试 (unitTests)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### 🔬 集成测试 (situationTests)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### ✅ 用户验收测试 (uats)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+#### 🚀 部署 (depolys)
+
+| ID   | 名称   | 状态         | 创建时间  | 目录        |
+| ---- | ------ | ------------ | --------- | ----------- |
+| {id} | {name} | {status中文} | {created} | {directory} |
+
+> 空数组显示 "（暂无条目）"
+
+### 汇总统计
+
+#### 按阶段统计
+
+| 阶段     | 条目数      | 草稿     | 评审中   | 修改中   | 评审通过 |
+| -------- | ----------- | -------- | -------- | -------- | -------- |
+| 业务需求 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 产品需求 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 前端演示 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 后端设计 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 前端设计 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 后端代码 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 前端代码 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 单元测试 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 集成测试 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 用户验收 | {N}         | {n}      | {n}      | {n}      | {n}      |
+| 部署     | {N}         | {n}      | {n}      | {n}      | {n}      |
+| **合计** | **{total}** | **{t1}** | **{t2}** | **{t3}** | **{t4}** |
+
+#### 按状态统计
+
+| 状态                | 数量        | 占比     |
+| ------------------- | ----------- | -------- |
+| 草稿 (drafting)     | {N}         | {%}      |
+| 评审中 (reviewing)  | {N}         | {%}      |
+| 修改中 (revising)   | {N}         | {%}      |
+| 评审通过 (approved) | {N}         | {%}      |
+| **合计**            | **{total}** | **100%** |
+```
+
+**输出规则**：
+
+- 状态值自动转换为中文显示（`drafting` → 草稿、`reviewing` → 评审中、`revising` → 修改中、`approved` → 评审通过）
+- 空数组在明细表中显示"（暂无条目）"，在汇总统计中显示 0
+- 占比保留一位小数
+- 如果 `$ARGUMENTS` 仅为 `--list` 或为空 → 输出追踪矩阵后结束，不执行后续更新步骤
+
+### 步骤 2：解析参数
+
+从 `$ARGUMENTS` 中解析（如果提供了功能 ID 和状态值）：
+
+- `feature_id`：功能 ID
+- `target_status`：目标状态（支持中文或英文值）
+- `category`：数组类别（可选）
+
+**状态值转换**：
+
+- 用户输入"草稿" → 存储 `drafting`
+- 用户输入"评审中" → 存储 `reviewing`
+- 用户输入"修改中" → 存储 `revising`
+- 用户输入"评审通过" → 存储 `approved`
+- 用户直接输入英文值（如 `approved`）→ 直接使用
+
+**类别名称转换**：
+
+- 用户输入"业务需求"或"requirement" → `requirement`
+- 用户输入"产品需求"或"prd" → `prd`
+- 用户输入"前端演示"或"frontDemos" → `frontDemos`
+- 用户输入"后端设计"或"endDesigns" → `endDesigns`
+- 用户输入"前端设计"或"frontDesigns" → `frontDesigns`
+- 用户输入"后端代码"或"endCodes" → `endCodes`
+- 用户输入"前端代码"或"frontCodes" → `frontCodes`
+- 用户输入"单元测试"或"unitTests" → `unitTests`
+- 用户输入"集成测试"或"situationTests" → `situationTests`
+- 用户输入"用户验收"或"uats" → `uats`
+- 用户输入"部署"或"depolys" → `depolys`
+
+### 步骤 3：查找匹配条目
+
+1. 如果指定了 `category` → 仅在对应数组中搜索
+2. 如果未指定 `category` → 按以下顺序搜索全部数组：
+   `requirement` → `prd` → `frontDemos` → `endDesigns` → `frontDesigns` → `endCodes` → `frontCodes` → `unitTests` → `situationTests` → `uats` → `depolys`
+
+3. **匹配规则**（按优先级）：
+   - **精确匹配**：`id` 字段完全等于 `feature_id`
+   - **前缀匹配**：`id` 字段以 `feature_id` 开头（当精确匹配无结果时）
+   - **名称匹配**：`name` 字段包含 `feature_id`（当前缀匹配也无结果时）
+
+4. 如果找到多个匹配 → 列出所有匹配项，询问用户确认要更新哪一个
+5. 如果无匹配 → 输出错误：`❌ 未找到匹配的功能条目（ID: {feature_id}），请检查 ID 是否正确`
+
+### 步骤 4：执行更新
+
+1. 显示当前状态和目标状态：
+
+   ```
+   📋 功能: {name}
+   📂 ID: {id}
+   📁 目录: {directory}
+   🔄 状态变更: {旧状态中文} → {新状态中文}
+   ```
+
+2. 将匹配条目的 `status` 字段更新为目标状态值
+
+### 步骤 5：写回文件
+
+1. 使用 Write 工具将更新后的 JSON 写回 `.adspecs/feature.json`
+2. 保持 2-space 缩进格式
+3. 保持文件末尾有一个换行符
+
+4. **同步 YAML 文件**：如果项目根目录下存在 `.adspecs/feature.yml`，将更新后的数据同步写入该文件：
+   - 读取刚写入的 `feature.json` 内容
+   - 转换为 YAML 格式（保持键顺序一致）
+   - 使用 Write 工具写回 `.adspecs/feature.yml`
+   - YAML 文件头部保留注释说明（`# adspecs Feature Tracking - YAML format`）
+   - 如果 `feature.yml` 不存在，跳过此步骤（不自动创建）
+
+### 步骤 6：输出结果
+
+```
+✅ 状态更新完成
+
+功能: {name}
+ID: {id}
+类别: {类别中文名称}
+状态: {旧状态中文} → {新状态中文}
+```
+
+### 批量更新模式
+
+当 `feature_id` 使用通配符或关键词匹配到多个条目时，支持批量更新。
+
+**触发条件**：
+
+- `feature_id` 为 `*` 或 `all` → 更新指定类别（或全部类别）中的所有条目
+- `feature_id` 匹配到多个条目且用户确认批量更新
+
+**执行流程**：
+
+1. 列出所有将被更新的条目及其当前状态
+2. 询问用户确认：`确认将以上 {N} 个条目的状态更新为 {目标状态}？`
+3. 用户确认后，批量更新所有匹配条目
+4. 输出批量更新结果摘要
+
+## 扩展钩子
+
+### 执行前检查
+
+检查项目根目录下是否存在 `.adspecs/extensions.yml`。如果存在且配置了 `before_update_status` 钩子，执行相应操作。
+
+### 执行后钩子
+
+状态更新完成后，检查 `.adspecs/extensions.yml` 中 `hooks.after_update_status` 键下的条目，按规则处理。
+
+## 错误处理
+
+| 场景                                   | 处理方式                                                |
+| -------------------------------------- | ------------------------------------------------------- |
+| `.adspecs/feature.json` 不存在         | 输出错误并提示执行 `/project-init`                      |
+| `feature.json` 格式错误（非有效 JSON） | 输出错误并提示检查文件格式                              |
+| 功能 ID 未找到                         | 输出错误并列出所有可用 ID（前 10 个）                   |
+| 状态值无效                             | 输出错误并列出有效状态值                                |
+| 目标数组不存在或为 null                | 输出警告并跳过该数组                                    |
+| 条目当前状态已与目标相同               | 输出提示 `ℹ️ 状态未变更（当前已是 {状态}）`，不写入文件 |
+
+## 使用示例
+
+```bash
+# 仅查看功能追踪矩阵
+/adspecs-update-status
+
+# 更新业务需求状态为评审通过
+/adspecs-update-status p05-01-aluminum-ingot-receiving 评审通过 --category requirement
+
+# 自动搜索所有数组，找到匹配 ID 后更新
+/adspecs-update-status p05-01 评审中
+
+# 列出所有功能状态（同省略参数）
+/adspecs-update-status --list
+
+# 批量更新所有业务需求为评审通过
+/adspecs-update-status all 评审通过 --category requirement
+
+# 使用中文类别名
+/adspecs-update-status p05-01 草稿 --category 后端设计
+```
+
+## 完成标志
+
+- [ ] 已正确定位并读取 `.adspecs/feature.json` 文件
+- [ ] 已输出功能追踪矩阵（含各阶段明细和汇总统计）
+- [ ] 已正确解析功能 ID 和目标状态值（如有提供）
+- [ ] 已按匹配规则找到目标功能条目（如有提供）
+- [ ] 状态值已正确转换（中文 → 英文存储值）
+- [ ] 已更新 `status` 字段并写回 `feature.json`（保持 JSON 格式）
+- [ ] 已同步 `feature.yml`（如存在）
+- [ ] 已输出更新结果（含变更前后状态对比）