@gong-ym/ai-spec-auto 0.2.14 → 0.2.15

package/.agents/commands/common/branch-review.md

@@ -1,117 +1,117 @@
----
-description: 启动分支代码评审,分析当前分支与主分支的差异和风险项
----
-# /branch-review - 分支代码评审
-
-启动分支代码评审流程,对比功能分支与主分支(master/main)的代码差异,自动识别技术风险和业务风险,生成可视化 HTML 评审报告。
-
-## 用法
-
-```
-/branch-review [需求文档路径]
-```
-
-## 参数
-
-- **需求文档路径**(可选): 本次开发需求的文档路径,用于业务风险分析
-  - 支持格式: PRD / 用户故事 / 需求规格说明 / Markdown
-  - 示例: `docs/prd-order-module.md`
-
-## 示例
-
-### 示例 1: 仅技术风险分析
-
-```
-/branch-review
-```
-
-**效果**: 
-- 对比当前分支与主分支的代码差异
-- 分析技术类风险(性能、安全、错误处理等)
-- 生成可视化 HTML 报告
-
-### 示例 2: 技术 + 业务风险分析
-
-```
-/branch-review docs/prd-order-module.md
-```
-
-**效果**:
-- 读取需求文档,提取业务目标和验收标准
-- 对比代码差异,分析技术风险
-- 对照需求文档,分析业务风险(功能缺失、流程错误等)
-- 生成包含技术风险和业务风险的完整报告
-
-### 示例 3: 指定分支对比
-
-在对话中说明:
-
-```
-请对比 feature/new-payment 和 master 分支的差异,需求文档在 docs/payment-requirements.md
-```
-
-**效果**:
-- 使用指定的功能分支和主分支
-- 读取需求文档进行业务风险分析
-- 生成完整评审报告
-
-## 报告输出
-
-报告将保存到:
-```
-.code-review/review-[分支名]-[日期].html
-```
-
-报告包含:
-1. **概览面板**: 变更统计、风险统计、通过率
-2. **文件导航**: 文件树、变更行数、风险标记
-3. **代码差异**: 并排/统一模式、语法高亮
-4. **技术风险**: 按严重程度分级、关联代码行
-5. **业务风险**: 需求覆盖度、缺失功能、流程问题
-6. **交互功能**: 搜索、过滤、评论、导出
-
-## 风险等级说明
-
-| 等级 | 技术风险 | 业务风险 |
-|------|---------|---------|
-| 🔴 严重 | 崩溃、安全漏洞、数据丢失 | 缺失核心功能、业务流程错误 |
-| 🟡 警告 | 性能问题、可维护性差 | 缺少异常处理、边界条件遗漏 |
-| 🔵 建议 | 代码优化、重构建议 | 体验优化、流程改进 |
-| ⚪ 提示 | 信息说明、最佳实践 | - |
-
-## 工作流程
-
-```mermaid
-graph LR
-    A[确认分支] --> B[收集代码差异]
-    B --> C{有需求文档?}
-    C -->|是| D[分析技术+业务风险]
-    C -->|否| E[仅分析技术风险]
-    D --> F[生成HTML报告]
-    E --> F
-    F --> G[输出评审结果]
-```
-
-## 相关命令
-
-- `/spec-start` - 启动需求交付
-- `/spec-continue` - 继续需求交付
-- `/spec-status` - 查看需求状态
-- `execute-task` 技能 - 基于评审结果创建修复任务
-
-## 注意事项
-
-- 必须在 Git 仓库中执行
-- 确保功能分支已提交变更
-- 业务风险分析需要提供需求文档
-- 报告为独立 HTML 文件,无需外部依赖
-- 不会修改任何源代码文件
-
-## 后续操作
-
-评审完成后可执行:
-
-1. **修复风险**: 使用 `execute-task` 技能创建修复任务
-2. **更新需求**: 使用 `/spec-update` 补充需求文档
-3. **重新评审**: 修复后再次运行 `/branch-review` 验证
-4. **合并代码**: 解决所有严重风险后可安全合并
+---
+description: 启动分支代码评审,分析当前分支与主分支的差异和风险项
+---
+# /branch-review - 分支代码评审
+
+启动分支代码评审流程,对比功能分支与主分支(master/main)的代码差异,自动识别技术风险和业务风险,生成可视化 HTML 评审报告。
+
+## 用法
+
+```
+/branch-review [需求文档路径]
+```
+
+## 参数
+
+- **需求文档路径**(可选): 本次开发需求的文档路径,用于业务风险分析
+  - 支持格式: PRD / 用户故事 / 需求规格说明 / Markdown
+  - 示例: `docs/prd-order-module.md`
+
+## 示例
+
+### 示例 1: 仅技术风险分析
+
+```
+/branch-review
+```
+
+**效果**: 
+- 对比当前分支与主分支的代码差异
+- 分析技术类风险(性能、安全、错误处理等)
+- 生成可视化 HTML 报告
+
+### 示例 2: 技术 + 业务风险分析
+
+```
+/branch-review docs/prd-order-module.md
+```
+
+**效果**:
+- 读取需求文档,提取业务目标和验收标准
+- 对比代码差异,分析技术风险
+- 对照需求文档,分析业务风险(功能缺失、流程错误等)
+- 生成包含技术风险和业务风险的完整报告
+
+### 示例 3: 指定分支对比
+
+在对话中说明:
+
+```
+请对比 feature/new-payment 和 master 分支的差异,需求文档在 docs/payment-requirements.md
+```
+
+**效果**:
+- 使用指定的功能分支和主分支
+- 读取需求文档进行业务风险分析
+- 生成完整评审报告
+
+## 报告输出
+
+报告将保存到:
+```
+.code-review/review-[分支名]-[日期].html
+```
+
+报告包含:
+1. **概览面板**: 变更统计、风险统计、通过率
+2. **文件导航**: 文件树、变更行数、风险标记
+3. **代码差异**: 并排/统一模式、语法高亮
+4. **技术风险**: 按严重程度分级、关联代码行
+5. **业务风险**: 需求覆盖度、缺失功能、流程问题
+6. **交互功能**: 搜索、过滤、评论、导出
+
+## 风险等级说明
+
+| 等级 | 技术风险 | 业务风险 |
+|------|---------|---------|
+| 🔴 严重 | 崩溃、安全漏洞、数据丢失 | 缺失核心功能、业务流程错误 |
+| 🟡 警告 | 性能问题、可维护性差 | 缺少异常处理、边界条件遗漏 |
+| 🔵 建议 | 代码优化、重构建议 | 体验优化、流程改进 |
+| ⚪ 提示 | 信息说明、最佳实践 | - |
+
+## 工作流程
+
+```mermaid
+graph LR
+    A[确认分支] --> B[收集代码差异]
+    B --> C{有需求文档?}
+    C -->|是| D[分析技术+业务风险]
+    C -->|否| E[仅分析技术风险]
+    D --> F[生成HTML报告]
+    E --> F
+    F --> G[输出评审结果]
+```
+
+## 相关命令
+
+- `/spec-start` - 启动需求交付
+- `/spec-continue` - 继续需求交付
+- `/spec-status` - 查看需求状态
+- `execute-task` 技能 - 基于评审结果创建修复任务
+
+## 注意事项
+
+- 必须在 Git 仓库中执行
+- 确保功能分支已提交变更
+- 业务风险分析需要提供需求文档
+- 报告为独立 HTML 文件,无需外部依赖
+- 不会修改任何源代码文件
+
+## 后续操作
+
+评审完成后可执行:
+
+1. **修复风险**: 使用 `execute-task` 技能创建修复任务
+2. **更新需求**: 使用 `/spec-update` 补充需求文档
+3. **重新评审**: 修复后再次运行 `/branch-review` 验证
+4. **合并代码**: 解决所有严重风险后可安全合并

package/.agents/commands/common/project-init.md

@@ -1,25 +1,25 @@
-这是项目规范初始化入口。目标不是只生成 `01/03`，而是按当前项目的 profiles 补齐本次应写的全部规范文件。
-
-先读取并严格遵守：
-
-- `.agents/skills/common/project-init/SKILL.md`
-
-执行要求：
-
-1. 读取 `.ai-spec/manifest.json` 中的 `profile`（字符串）或 `profiles`（数组），统一为 profile 列表。
-2. 从 `.agents/registry/profiles.json` 查询各 profile 的 `project_init_rule_ids`，合并为本次应生成的规则集合。
-3. 固定写入（统一写入 `.agents/rules/`）：
-   - `01-项目概述.md`
-   - `03-项目结构.md`
-   - `context/PROJECT.md`
-4. 若项目存在 `openspec/`，同步 `openspec/project.md`。
-5. 若 `.agents/rules/` 下缺失规则集合中任意文件，必须在本次一并补生成。
-
-绝对红线：
-
-- 不能只写 `01/03 + PROJECT` 就结束
-- 不能把缺失的能力规则只写进摘要或建议，不落盘
-- 对已存在的能力规则不覆盖
-- 内容必须基于当前仓库实际代码、目录和依赖，不能照搬通用模板
-
-把用户触发本命令视为明确授权：信息足够时直接完成写入；只有在项目事实明显不足、无法判断时，才先给出简短确认摘要。
+这是项目规范初始化入口。目标不是只生成 `01/03`，而是按当前项目的 profiles 补齐本次应写的全部规范文件。
+
+先读取并严格遵守：
+
+- `.agents/skills/common/project-init/SKILL.md`
+
+执行要求：
+
+1. 读取 `.ai-spec/manifest.json` 中的 `profile`（字符串）或 `profiles`（数组），统一为 profile 列表。
+2. 从 `.agents/registry/profiles.json` 查询各 profile 的 `project_init_rule_ids`，合并为本次应生成的规则集合。
+3. 固定写入（统一写入 `.agents/rules/`）：
+   - `01-项目概述.md`
+   - `03-项目结构.md`
+   - `context/PROJECT.md`
+4. 若项目存在 `openspec/`，同步 `openspec/project.md`。
+5. 若 `.agents/rules/` 下缺失规则集合中任意文件，必须在本次一并补生成。
+
+绝对红线：
+
+- 不能只写 `01/03 + PROJECT` 就结束
+- 不能把缺失的能力规则只写进摘要或建议，不落盘
+- 对已存在的能力规则不覆盖
+- 内容必须基于当前仓库实际代码、目录和依赖，不能照搬通用模板
+
+把用户触发本命令视为明确授权：信息足够时直接完成写入；只有在项目事实明显不足、无法判断时，才先给出简短确认摘要。

package/.agents/commands/common/spec-continue.md

@@ -1,74 +1,74 @@
-这是协议继续入口，不是直接开发命令。
-
-绝对红线：
-
-- 在执行 `protocol-advance --json` 之前，禁止直接开始读项目代码、调用实现技能或修改业务文件
-- 不允许把当前轮次退化成“直接开始写页面/组件代码”
-- `task-orchestrator` 必须在每次专家完成后重新出现
-
-先判断当前这一轮用户输入：
-
-- 若用户这轮是在表达审批/放行意图，例如：
-  - `我同意继续实现`
-  - `同意`
-  - `继续`
-  - `开始`
-  - `愿意`
-- 或当前在归档确认门禁中，用户这轮是在表达归档决定，例如：
-  - `归档`
-  - `同意归档`
-  - `先不归档`
-  - `暂不归档`
-- 且当前运行态很可能已停在 `pending_gate`
-
-则优先执行：
-
-```bash
-./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前这条用户原话>" --json
-```
-
-不要先空跑 `protocol-advance`。
-
-若 `protocol-update` 返回 `fast_path.executed = true`：
-
-- 说明当前是本地 fast-path，已经直接完成“归档”或“结束运行”
-- 不要再执行 `/spec-continue`
-- 不要再执行 `protocol-advance`
-- 直接读取返回结果里的 `turn` 或当前运行态，输出最终摘要
-
-其它情况再先执行：
-
-```bash
-./node_modules/.bin/ai-spec-auto protocol-advance --target . --json
-```
-
-然后只按返回的 `turn` 执行：
-
-1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
-2. 原样向用户播报 `turn.announcements.enter`
-3. 只读取 `turn.reads`，只写 `turn.writes`
-4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令
-5. 完成当前轮次后：
-   - 若当前专家执行结果为 `partial（部分完成）` 或任何非 `done / success / completed` 状态，不得写“交付完成”，不得交给下一位专家；必须继续停留在当前专家补齐后再推进
-   - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
-   - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
-   - 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command` 已完成归档与运行收尾；不要再写 `expert-execution` JSON，不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
-6. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
-7. 若用户中途补充新要求，或当前这条输入本身就是审批/放行意见，或是归档确认门禁下的“归档 / 不归档”决定，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
-8. `advance` 返回后，直接读取返回结果里的下一个 `turn` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
-9. 重复直到 `turn.status = terminal | blocked`
-
-若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`：
-- 明确告诉用户：当前停在该审批门禁，尚未批准，不能继续实现
-- 若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要：
-  只保留“当前状态 / 关键原因 / 下一步”，不要写长篇阶段说明，不要罗列 proposal/specs/design/tasks 或仓库文件路径，不要输出任何“对内说明”
-- 不要继续执行 `advance`
-- 若用户随后给出明确批准意见，或在归档确认门禁下给出“归档 / 不归档”决定，先执行 `turn.commands.update` 记录说明；若 `protocol-update` 返回 `fast_path.executed = true`，直接结束当前轮次，否则再让用户重新执行 `/spec-continue`
-
-`proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md` 门禁必须真实落盘。
-若存在 `turn.finalize_contract.user_report_contract`，最终摘要严格服从它：
-- `micro`：压成三句式，只保留交付结论、验证结果、残留风险；不要文件路径、实现结构细节、命令名
-- `standard`：只保留关键结果、验证结果、残留风险，必要时补一句下一步；不要协议细节、路径、OpenSpec 文件名或长篇实现说明
-- 不要出现 `proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md`、`terminal`、`success`、`waiting-approval` 等内部词
-- 不要额外输出“阶段说明（语义）”式逐角色播报
-- 不要默认附加 `pnpm dev`、浏览器打开路径等本地操作提示，除非用户明确要
+这是协议继续入口，不是直接开发命令。
+
+绝对红线：
+
+- 在执行 `protocol-advance --json` 之前，禁止直接开始读项目代码、调用实现技能或修改业务文件
+- 不允许把当前轮次退化成“直接开始写页面/组件代码”
+- `task-orchestrator` 必须在每次专家完成后重新出现
+
+先判断当前这一轮用户输入：
+
+- 若用户这轮是在表达审批/放行意图，例如：
+  - `我同意继续实现`
+  - `同意`
+  - `继续`
+  - `开始`
+  - `愿意`
+- 或当前在归档确认门禁中，用户这轮是在表达归档决定，例如：
+  - `归档`
+  - `同意归档`
+  - `先不归档`
+  - `暂不归档`
+- 且当前运行态很可能已停在 `pending_gate`
+
+则优先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前这条用户原话>" --json
+```
+
+不要先空跑 `protocol-advance`。
+
+若 `protocol-update` 返回 `fast_path.executed = true`：
+
+- 说明当前是本地 fast-path，已经直接完成“归档”或“结束运行”
+- 不要再执行 `/spec-continue`
+- 不要再执行 `protocol-advance`
+- 直接读取返回结果里的 `turn` 或当前运行态，输出最终摘要
+
+其它情况再先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-advance --target . --json
+```
+
+然后只按返回的 `turn` 执行：
+
+1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
+2. 原样向用户播报 `turn.announcements.enter`
+3. 只读取 `turn.reads`，只写 `turn.writes`
+4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令
+5. 完成当前轮次后：
+   - 若当前专家执行结果为 `partial（部分完成）` 或任何非 `done / success / completed` 状态，不得写“交付完成”，不得交给下一位专家；必须继续停留在当前专家补齐后再推进
+   - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
+   - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
+   - 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command` 已完成归档与运行收尾；不要再写 `expert-execution` JSON，不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
+6. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
+7. 若用户中途补充新要求，或当前这条输入本身就是审批/放行意见，或是归档确认门禁下的“归档 / 不归档”决定，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
+8. `advance` 返回后，直接读取返回结果里的下一个 `turn` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
+9. 重复直到 `turn.status = terminal | blocked`
+
+若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`：
+- 明确告诉用户：当前停在该审批门禁，尚未批准，不能继续实现
+- 若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要：
+  只保留“当前状态 / 关键原因 / 下一步”，不要写长篇阶段说明，不要罗列 proposal/specs/design/tasks 或仓库文件路径，不要输出任何“对内说明”
+- 不要继续执行 `advance`
+- 若用户随后给出明确批准意见，或在归档确认门禁下给出“归档 / 不归档”决定，先执行 `turn.commands.update` 记录说明；若 `protocol-update` 返回 `fast_path.executed = true`，直接结束当前轮次，否则再让用户重新执行 `/spec-continue`
+
+`proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md` 门禁必须真实落盘。
+若存在 `turn.finalize_contract.user_report_contract`，最终摘要严格服从它：
+- `micro`：压成三句式，只保留交付结论、验证结果、残留风险；不要文件路径、实现结构细节、命令名
+- `standard`：只保留关键结果、验证结果、残留风险，必要时补一句下一步；不要协议细节、路径、OpenSpec 文件名或长篇实现说明
+- 不要出现 `proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md`、`terminal`、`success`、`waiting-approval` 等内部词
+- 不要额外输出“阶段说明（语义）”式逐角色播报
+- 不要默认附加 `pnpm dev`、浏览器打开路径等本地操作提示，除非用户明确要

package/.agents/commands/common/spec-orchestrate.md

@@ -1,35 +1,35 @@
-这是统一协议编排入口。
-
-规则：
-
-- 在任何项目搜索、文件读取、技能调用、代码修改之前，必须先执行当前轮次命令
-- 新任务：先执行 `./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<用户需求>" --json`
-- 已有运行态：
-  - 若当前这条用户输入本身是在表达审批/放行（如“我同意继续实现 / 同意 / 继续 / 开始 / 愿意”），优先执行 `./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前用户原话>" --json`
-  - 若当前在归档确认门禁，且用户输入是在表达“归档 / 不归档”决定（如“归档 / 同意归档 / 先不归档 / 暂不归档”），同样优先执行 `./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前用户原话>" --json`
-  - 否则执行 `./node_modules/.bin/ai-spec-auto protocol-advance --target . --json`
-- 之后一律按返回的 `turn.enforcement`、`turn.actor`、`turn.announcements`、`turn.reads`、`turn.writes`、`turn.guidance`、`turn.execution_contract` 执行
-- 若存在 `turn.commands`、`turn.requires_advance`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令
-- 每进入新 `turn` 前，必须原样播报 `turn.announcements.enter`
-- 每完成当前轮次后：
-  - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
-  - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
-- 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command` 已完成归档与运行收尾；不要再写 `expert-execution` JSON，不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
-- 若 `protocol-update` 返回 `fast_path.executed = true`，说明归档确认已走本地 fast-path；不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
-- 每完成一轮，若 `turn.requires_advance = true`，按 `turn.finalize_contract.advance_command` 执行推进；若用户补充了新需求，或当前输入本身是审批/放行意见，或归档确认门禁下的“归档 / 不归档”决定，使用 `turn.finalize_contract.update_command`
-- `advance` 返回后，必须直接消费返回结果里的下一个 `turn`；禁止 `sleep`、`tail`、`timeout`、`cat` 日志或额外重跑 `protocol-step`
-- 直到 `turn.status` 变成 `terminal` 或 `blocked`
-- 若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`，明确告诉用户当前在审批门禁中；若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要：只保留“当前状态 / 关键原因 / 下一步”，不要长篇说明、文件路径或任何“对内说明”；不要继续执行 `advance`；收到明确批准意见，或在归档确认门禁下收到“归档 / 不归档”决定后，先执行 `turn.commands.update` 记录说明；若 `protocol-update` 返回 `fast_path.executed = true`，直接结束当前轮次，否则再让用户重新执行 `/spec-continue`
-
-硬性要求：
-
-- 这是协议驱动，不是自由发挥
-- 未轮到 `frontend-implementer` 前禁止写业务代码
-- 未执行当前轮次命令前禁止调用 `create-view`、`create-component`、`theme-variables`、`execute-task`
-- 对用户只展示阶段进度与最终结果，不回显 scratch JSON
-- 若存在 `turn.finalize_contract.user_report_contract`，最终摘要严格服从它：
-  `micro`：压成三句式，只保留交付结论、验证结果、残留风险；不要文件路径、实现结构细节、命令名
-  `standard`：只保留关键结果、验证结果、残留风险，必要时补一句下一步；不要协议细节、路径、OpenSpec 文件名或长篇实现说明
-- 不要出现 `proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md`、`terminal`、`success`、`waiting-approval` 等内部词
-- 不要额外输出“阶段说明（语义）”式逐角色播报
-- 不要默认附加 `pnpm dev`、浏览器打开路径等本地操作提示，除非用户明确要
+这是统一协议编排入口。
+
+规则：
+
+- 在任何项目搜索、文件读取、技能调用、代码修改之前，必须先执行当前轮次命令
+- 新任务：先执行 `./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<用户需求>" --json`
+- 已有运行态：
+  - 若当前这条用户输入本身是在表达审批/放行（如“我同意继续实现 / 同意 / 继续 / 开始 / 愿意”），优先执行 `./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前用户原话>" --json`
+  - 若当前在归档确认门禁，且用户输入是在表达“归档 / 不归档”决定（如“归档 / 同意归档 / 先不归档 / 暂不归档”），同样优先执行 `./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前用户原话>" --json`
+  - 否则执行 `./node_modules/.bin/ai-spec-auto protocol-advance --target . --json`
+- 之后一律按返回的 `turn.enforcement`、`turn.actor`、`turn.announcements`、`turn.reads`、`turn.writes`、`turn.guidance`、`turn.execution_contract` 执行
+- 若存在 `turn.commands`、`turn.requires_advance`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令
+- 每进入新 `turn` 前，必须原样播报 `turn.announcements.enter`
+- 每完成当前轮次后：
+  - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
+  - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
+- 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command` 已完成归档与运行收尾；不要再写 `expert-execution` JSON，不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
+- 若 `protocol-update` 返回 `fast_path.executed = true`，说明归档确认已走本地 fast-path；不要再执行 `protocol-advance`，直接读取当前运行态并输出最终摘要
+- 每完成一轮，若 `turn.requires_advance = true`，按 `turn.finalize_contract.advance_command` 执行推进；若用户补充了新需求，或当前输入本身是审批/放行意见，或归档确认门禁下的“归档 / 不归档”决定，使用 `turn.finalize_contract.update_command`
+- `advance` 返回后，必须直接消费返回结果里的下一个 `turn`；禁止 `sleep`、`tail`、`timeout`、`cat` 日志或额外重跑 `protocol-step`
+- 直到 `turn.status` 变成 `terminal` 或 `blocked`
+- 若 `turn.status = blocked` 且存在 `turn.summary.pending_gate`，明确告诉用户当前在审批门禁中；若存在 `turn.guidance.approval_gate.user_report_contract`，严格按它输出极简摘要：只保留“当前状态 / 关键原因 / 下一步”，不要长篇说明、文件路径或任何“对内说明”；不要继续执行 `advance`；收到明确批准意见，或在归档确认门禁下收到“归档 / 不归档”决定后，先执行 `turn.commands.update` 记录说明；若 `protocol-update` 返回 `fast_path.executed = true`，直接结束当前轮次，否则再让用户重新执行 `/spec-continue`
+
+硬性要求：
+
+- 这是协议驱动，不是自由发挥
+- 未轮到 `frontend-implementer` 前禁止写业务代码
+- 未执行当前轮次命令前禁止调用 `create-view`、`create-component`、`theme-variables`、`execute-task`
+- 对用户只展示阶段进度与最终结果，不回显 scratch JSON
+- 若存在 `turn.finalize_contract.user_report_contract`，最终摘要严格服从它：
+  `micro`：压成三句式，只保留交付结论、验证结果、残留风险；不要文件路径、实现结构细节、命令名
+  `standard`：只保留关键结果、验证结果、残留风险，必要时补一句下一步；不要协议细节、路径、OpenSpec 文件名或长篇实现说明
+- 不要出现 `proposal.md`、`spec.md`、`tasks.md`、`checklist.md`、`iterations.md`、`terminal`、`success`、`waiting-approval` 等内部词
+- 不要额外输出“阶段说明（语义）”式逐角色播报
+- 不要默认附加 `pnpm dev`、浏览器打开路径等本地操作提示，除非用户明确要