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

package/.agents/commands/common/spec-start-review.md

@@ -1,82 +1,82 @@
-这是协议驱动入口，不是直接开发命令。
-
-这个入口的目标很单一：
-
-- 默认启用 `review-policy（审核策略） = main-flow-blocking（主流程阻塞审核）`
-- 允许开发者在命令尾部追加 `CLI flags（命令行标志位）`
-- 继续复用 `protocol-step（协议启动命令）`，不改运行状态机
-
-绝对红线：
-
-- 在执行 `protocol-step --json` 之前，禁止搜索项目、读取项目代码、调用实现技能、修改任何业务文件
-- 当前 `actor（执行角色）` 不是 `frontend-implementer（前端实现专家）` 时，禁止修改 Vue/TS/CSS 业务代码
-- 不允许跳过 `task-orchestrator（任务编排专家） -> requirement-analyst（需求解析专家） -> task-orchestrator（任务编排专家） -> frontend-implementer（前端实现专家） -> task-orchestrator（任务编排专家） -> code-guardian（规范守护专家） -> task-orchestrator（任务编排专家）`
-
-先解析本次 `/spec-start-review` 命令尾部输入：
-
-- 支持 `--mode <auto|suggest|manual>`
-- 支持 `--flow <flow-id>`
-- 支持 `--review-policy <none|main-flow-blocking>`
-- 未显式传入时，默认使用 `--mode auto --review-policy main-flow-blocking`
-- 除这些 `flags（标志位）` 之外的剩余文本，全部视为本次需求原文，并透传给 `--user-input`
-- 若 `flags（标志位）` 之外没有任何需求原文，先提示用户补完整需求，再执行
-- 若用户传了 `--mode manual` 但没有传 `--flow`，不要自行兜底，不要改写成别的模式；保持原样执行，让运行时自己返回 `manual-flow-required（手动流程必填门禁）`
-- 不要把 `manual（手动）` 理解成“每一步都人工审核”
-
-推荐示例：
-
-```text
-/spec-start-review 创建订单列表 mock 页面
-/spec-start-review --mode suggest 创建订单列表 mock 页面
-/spec-start-review --mode manual --flow prd-to-delivery 创建订单列表 mock 页面
-```
-
-完成解析后，执行等价协议命令：
-
-```bash
-./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<解析后的需求原文>" --mode <解析后的 mode（运行模式）> --review-policy <解析后的 review-policy（审核策略）> [--flow <解析后的 flow（流程模板）>] --json
-```
-
-然后只按返回的 `turn（当前轮次）` 执行：
-
-1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
-   若 `execute_current_command_first = true`，才需要先执行 `turn.enforcement.current_command`
-2. 原样向用户播报 `turn.announcements.enter`
-3. 只读取 `turn.reads`，只写 `turn.writes`
-4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令，不要自行补流程
-5. `task-orchestrator（任务编排专家）` 只写 `.ai-spec/internal/tmp/task-orchestrator-turn.json`，不写业务代码
-6. `requirement-analyst（需求解析专家）` 只产出 `proposal.md`、`spec.md`、`tasks.md`
-7. `frontend-implementer（前端实现专家）` 才允许改业务代码
-8. `code-guardian（规范守护专家）` 只产出 `checklist.md`、`iterations.md`
-9. 完成当前轮次后：
-   - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
-   - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
-   - 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command（当前命令）` 已完成归档与运行收尾；不要再写 `expert-execution（专家执行结果）` JSON，不要再执行 `protocol-advance（协议推进命令）`，直接读取当前运行态并输出最终摘要
-10. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
-11. 若用户中途补充新要求，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
-12. `advance（推进命令）` 返回后，直接读取返回结果里的下一个 `turn（当前轮次）` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
-13. 重复直到 `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`
-
-若 `turn.status = blocked` 且存在 `turn.guidance.confirm_gate`：
-
-- 先判断是否是 `start-review（启动确认门禁）` 或 `manual-flow-required（手动流程必填门禁）`
-- `start-review（启动确认门禁）`：提示用户当前是 `suggest（建议）` 模式，先确认建议计划，再恢复到第一位专家
-- `manual-flow-required（手动流程必填门禁）`：提示用户必须补充 `--flow <flow-id>`
-- 不要把 `manual（手动）` 理解成“每一步都审核”
-
-对用户只输出阶段语义和最终摘要，不回显 `scratch JSON（中间草稿 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`、浏览器打开路径等本地操作提示，除非用户明确要
+这是协议驱动入口，不是直接开发命令。
+
+这个入口的目标很单一：
+
+- 默认启用 `review-policy（审核策略） = main-flow-blocking（主流程阻塞审核）`
+- 允许开发者在命令尾部追加 `CLI flags（命令行标志位）`
+- 继续复用 `protocol-step（协议启动命令）`，不改运行状态机
+
+绝对红线：
+
+- 在执行 `protocol-step --json` 之前，禁止搜索项目、读取项目代码、调用实现技能、修改任何业务文件
+- 当前 `actor（执行角色）` 不是 `frontend-implementer（前端实现专家）` 时，禁止修改 Vue/TS/CSS 业务代码
+- 不允许跳过 `task-orchestrator（任务编排专家） -> requirement-analyst（需求解析专家） -> task-orchestrator（任务编排专家） -> frontend-implementer（前端实现专家） -> task-orchestrator（任务编排专家） -> code-guardian（规范守护专家） -> task-orchestrator（任务编排专家）`
+
+先解析本次 `/spec-start-review` 命令尾部输入：
+
+- 支持 `--mode <auto|suggest|manual>`
+- 支持 `--flow <flow-id>`
+- 支持 `--review-policy <none|main-flow-blocking>`
+- 未显式传入时，默认使用 `--mode auto --review-policy main-flow-blocking`
+- 除这些 `flags（标志位）` 之外的剩余文本，全部视为本次需求原文，并透传给 `--user-input`
+- 若 `flags（标志位）` 之外没有任何需求原文，先提示用户补完整需求，再执行
+- 若用户传了 `--mode manual` 但没有传 `--flow`，不要自行兜底，不要改写成别的模式；保持原样执行，让运行时自己返回 `manual-flow-required（手动流程必填门禁）`
+- 不要把 `manual（手动）` 理解成“每一步都人工审核”
+
+推荐示例：
+
+```text
+/spec-start-review 创建订单列表 mock 页面
+/spec-start-review --mode suggest 创建订单列表 mock 页面
+/spec-start-review --mode manual --flow prd-to-delivery 创建订单列表 mock 页面
+```
+
+完成解析后，执行等价协议命令：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<解析后的需求原文>" --mode <解析后的 mode（运行模式）> --review-policy <解析后的 review-policy（审核策略）> [--flow <解析后的 flow（流程模板）>] --json
+```
+
+然后只按返回的 `turn（当前轮次）` 执行：
+
+1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
+   若 `execute_current_command_first = true`，才需要先执行 `turn.enforcement.current_command`
+2. 原样向用户播报 `turn.announcements.enter`
+3. 只读取 `turn.reads`，只写 `turn.writes`
+4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令，不要自行补流程
+5. `task-orchestrator（任务编排专家）` 只写 `.ai-spec/internal/tmp/task-orchestrator-turn.json`，不写业务代码
+6. `requirement-analyst（需求解析专家）` 只产出 `proposal.md`、`spec.md`、`tasks.md`
+7. `frontend-implementer（前端实现专家）` 才允许改业务代码
+8. `code-guardian（规范守护专家）` 只产出 `checklist.md`、`iterations.md`
+9. 完成当前轮次后：
+   - 若不存在 `turn.finalize_contract.user_report_contract`，可简短播报 `turn.announcements.exit`
+   - 若存在最终摘要契约，直接输出符合契约的最终摘要，不再额外播报内部阶段完成语
+   - 若 `turn.enforcement.current_command_finalizes_run = true`，则 `current_command（当前命令）` 已完成归档与运行收尾；不要再写 `expert-execution（专家执行结果）` JSON，不要再执行 `protocol-advance（协议推进命令）`，直接读取当前运行态并输出最终摘要
+10. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
+11. 若用户中途补充新要求，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
+12. `advance（推进命令）` 返回后，直接读取返回结果里的下一个 `turn（当前轮次）` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
+13. 重复直到 `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`
+
+若 `turn.status = blocked` 且存在 `turn.guidance.confirm_gate`：
+
+- 先判断是否是 `start-review（启动确认门禁）` 或 `manual-flow-required（手动流程必填门禁）`
+- `start-review（启动确认门禁）`：提示用户当前是 `suggest（建议）` 模式，先确认建议计划，再恢复到第一位专家
+- `manual-flow-required（手动流程必填门禁）`：提示用户必须补充 `--flow <flow-id>`
+- 不要把 `manual（手动）` 理解成“每一步都审核”
+
+对用户只输出阶段语义和最终摘要，不回显 `scratch JSON（中间草稿 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`、浏览器打开路径等本地操作提示，除非用户明确要

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

@@ -1,67 +1,67 @@
-这是协议驱动入口，不是直接开发命令。
-
-绝对红线：
-
-- 在执行 `protocol-step --json` 之前，禁止搜索项目、读取项目代码、调用实现技能、修改任何业务文件
-- 当前 `actor` 不是 `frontend-implementer` 时，禁止修改 Vue/TS/CSS 业务代码
-- 不允许跳过 `task-orchestrator -> requirement-analyst -> task-orchestrator -> frontend-implementer -> task-orchestrator -> code-guardian -> task-orchestrator`
-
-先执行：
-
-```bash
-./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<本次 /spec-start 的用户原始需求>" --mode auto --review-policy none --json
-```
-
-若用户明确要求先看建议计划，再改用：
-
-```bash
-./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<本次 /spec-start 的用户原始需求>" --mode suggest --review-policy none --json
-```
-
-若用户明确要求手动锁定流程模板，再改用：
-
-```bash
-./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<本次 /spec-start 的用户原始需求>" --mode manual --flow <flow-id> --review-policy main-flow-blocking --json
-```
-
-然后只按返回的 `turn` 执行：
-
-1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
-   若 `execute_current_command_first = true`，才需要先执行 `turn.enforcement.current_command`
-2. 原样向用户播报 `turn.announcements.enter`
-3. 只读取 `turn.reads`，只写 `turn.writes`
-4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令，不要自行补流程
-5. `task-orchestrator` 只写 `.ai-spec/internal/tmp/task-orchestrator-turn.json`，不写业务代码
-6. `requirement-analyst` 只产出 `proposal.md`、`spec.md`、`tasks.md`
-7. `frontend-implementer` 才允许改业务代码
-8. `code-guardian` 只产出 `checklist.md`、`iterations.md`
-9. 完成当前轮次后：
-   - 若当前专家执行结果为 `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`，直接读取当前运行态并输出最终摘要
-10. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
-11. 若用户中途补充新要求，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
-12. `advance` 返回后，直接读取返回结果里的下一个 `turn` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
-13. 重复直到 `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`
-
-若 `turn.status = blocked` 且存在 `turn.guidance.confirm_gate`：
-- 先判断是否是 `start-review（启动确认门禁）` 或 `manual-flow-required（手动流程必填门禁）`
-- `start-review（启动确认门禁）`：提示用户当前是 `suggest（建议）` 模式，先确认建议计划，再恢复到第一位专家
-- `manual-flow-required（手动流程必填门禁）`：提示用户必须补充 `--flow <flow-id>`
-- 不要把 `manual（手动）` 理解成“每一步都审核”
-
-对用户只输出阶段语义和最终摘要，不回显 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`、浏览器打开路径等本地操作提示，除非用户明确要
+这是协议驱动入口，不是直接开发命令。
+
+绝对红线：
+
+- 在执行 `protocol-step --json` 之前，禁止搜索项目、读取项目代码、调用实现技能、修改任何业务文件
+- 当前 `actor` 不是 `frontend-implementer` 时，禁止修改 Vue/TS/CSS 业务代码
+- 不允许跳过 `task-orchestrator -> requirement-analyst -> task-orchestrator -> frontend-implementer -> task-orchestrator -> code-guardian -> task-orchestrator`
+
+先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<本次 /spec-start 的用户原始需求>" --mode auto --review-policy none --json
+```
+
+若用户明确要求先看建议计划，再改用：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<本次 /spec-start 的用户原始需求>" --mode suggest --review-policy none --json
+```
+
+若用户明确要求手动锁定流程模板，再改用：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-step --target . --user-input "<本次 /spec-start 的用户原始需求>" --mode manual --flow <flow-id> --review-policy main-flow-blocking --json
+```
+
+然后只按返回的 `turn` 执行：
+
+1. 若存在 `turn.enforcement`，先完全遵守它；尤其是 `allowed_actor`、`allow_code_write`、`forbidden_skills`
+   若 `execute_current_command_first = true`，才需要先执行 `turn.enforcement.current_command`
+2. 原样向用户播报 `turn.announcements.enter`
+3. 只读取 `turn.reads`，只写 `turn.writes`
+4. 若存在 `turn.guidance`、`turn.execution_contract`、`turn.commands`、`turn.finalize_contract`，以它们为最终执行契约，不要自行拼命令，不要自行补流程
+5. `task-orchestrator` 只写 `.ai-spec/internal/tmp/task-orchestrator-turn.json`，不写业务代码
+6. `requirement-analyst` 只产出 `proposal.md`、`spec.md`、`tasks.md`
+7. `frontend-implementer` 才允许改业务代码
+8. `code-guardian` 只产出 `checklist.md`、`iterations.md`
+9. 完成当前轮次后：
+   - 若当前专家执行结果为 `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`，直接读取当前运行态并输出最终摘要
+10. 若 `turn.requires_advance = true`，立即执行 `turn.finalize_contract.advance_command`
+11. 若用户中途补充新要求，优先执行 `turn.finalize_contract.update_command` 或 `turn.commands.update`
+12. `advance` 返回后，直接读取返回结果里的下一个 `turn` 并继续；不要 `sleep`、`tail`、`timeout`、`cat` 日志，也不要额外重跑 `protocol-step`
+13. 重复直到 `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`
+
+若 `turn.status = blocked` 且存在 `turn.guidance.confirm_gate`：
+- 先判断是否是 `start-review（启动确认门禁）` 或 `manual-flow-required（手动流程必填门禁）`
+- `start-review（启动确认门禁）`：提示用户当前是 `suggest（建议）` 模式，先确认建议计划，再恢复到第一位专家
+- `manual-flow-required（手动流程必填门禁）`：提示用户必须补充 `--flow <flow-id>`
+- 不要把 `manual（手动）` 理解成“每一步都审核”
+
+对用户只输出阶段语义和最终摘要，不回显 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`、浏览器打开路径等本地操作提示，除非用户明确要

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

@@ -1,22 +1,22 @@
-这是协议状态查看入口，只读，不推进、不修改运行态。
-
-先执行：
-
-```bash
-./node_modules/.bin/ai-spec-auto protocol-status --target . --json
-```
-
-然后只输出高信号摘要：
-
-- 当前阶段
-- 当前状态
-- 是否存在审批门禁
-- 是否有待吸收的补充输入
-- 下一步建议
-
-不要输出：
-
-- 协议过程日志
-- scratch/current-run/current-dispatch/current-execution 等内部文件名
-- 大段文件清单
-- 无关实现细节
+这是协议状态查看入口，只读，不推进、不修改运行态。
+
+先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-status --target . --json
+```
+
+然后只输出高信号摘要：
+
+- 当前阶段
+- 当前状态
+- 是否存在审批门禁
+- 是否有待吸收的补充输入
+- 下一步建议
+
+不要输出：
+
+- 协议过程日志
+- scratch/current-run/current-dispatch/current-execution 等内部文件名
+- 大段文件清单
+- 无关实现细节

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

@@ -1,29 +1,29 @@
-这是协议暂停入口，不是取消命令。
-
-语义固定为：
-
-- 暂停当前 run
-- 保留当前产物、当前专家停点和门禁上下文
-- 后续可通过 `/spec-continue` 或自然语言“继续 / 恢复执行”恢复
-
-先执行：
-
-```bash
-./node_modules/.bin/ai-spec-auto protocol-stop --target . --json
-```
-
-然后：
-
-1. 若当前没有活动 run 或当前已是终态，只输出当前状态说明
-2. 若成功暂停，只告诉用户：
-   - 当前已暂停
-   - 当前停在哪个阶段
-   - 如何恢复
-3. 不要把 `/spec-stop` 解释成取消
-4. 不要清理当前 OpenSpec 产物、运行态或上下文
-
-对用户摘要保持简洁：
-
-- 当前状态
-- 当前停点
-- 恢复方式
+这是协议暂停入口，不是取消命令。
+
+语义固定为：
+
+- 暂停当前 run
+- 保留当前产物、当前专家停点和门禁上下文
+- 后续可通过 `/spec-continue` 或自然语言“继续 / 恢复执行”恢复
+
+先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-stop --target . --json
+```
+
+然后：
+
+1. 若当前没有活动 run 或当前已是终态，只输出当前状态说明
+2. 若成功暂停，只告诉用户：
+   - 当前已暂停
+   - 当前停在哪个阶段
+   - 如何恢复
+3. 不要把 `/spec-stop` 解释成取消
+4. 不要清理当前 OpenSpec 产物、运行态或上下文
+
+对用户摘要保持简洁：
+
+- 当前状态
+- 当前停点
+- 恢复方式

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

@@ -1,40 +1,60 @@
-这是协议增量更新入口，不是重新开新任务，也不是直接开始写代码。
-
-绝对红线：
-
-- 优先把当前输入当作“补充需求 / 修正方向 / 归档前修正说明”处理
-- 先执行 `protocol-update --json`，不要跳过主代理直接改业务文件
-- 不要把当前 change 的产物整份重写；默认只做增量修订
-
-先执行：
-
-```bash
-./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前这条用户原话>" --json
-```
-
-然后只按返回的 `turn` 执行：
-
-1. 若 `fast_path.executed = true`，优先消费 fast-path 结果：
-   - `archive-approved` / `complete-without-archive`：直接输出最终摘要，不再执行 `protocol-advance`
-   - `followup-patch-opened`：说明已打开补丁变更，再按返回的下一个 `turn` 继续
-   - `resume-paused-run`：说明已恢复停点，再按返回的下一个 `turn` 继续
-2. 若返回 `turn.mode = update-review`，必须先遵守 `turn.guidance.update_contract`
-3. 只读取 `turn.reads`，只写 `turn.writes`
-4. 若 `change_impact = patch | scope-delta | archive-fix`，默认在同一 `change_id` 内增量更新，不要推倒已有 proposal/specs/design/tasks/checklist/iterations
-5. 若 `change_impact = re-scope`，不要强行吞进当前 run；按 `reconcile_strategy` 给出“建议新建 change”的最小结论
-6. 若 `change_impact = followup-patch`，这是对已归档变更的补丁修正；继续沿返回的 patch run 推进，不要改旧 archive 目录
-7. 若存在 `turn.finalize_contract`，完成当前轮次后按契约推进，不要自行拼命令
-
-对用户只输出：
-
-- 当前识别到的变更类型
-- 会不会回退
-- 预计增量更新哪些产物
-- 下一步是什么
-
-不要输出：
-
-- 大段协议日志
-- scratch JSON
-- 内部运行态文件名
-- “整份重写 proposal/tasks/design/specs” 这类误导性说法
+这是协议增量更新入口，不是重新开新任务，也不是直接开始写代码。
+
+绝对红线：
+
+- 优先把当前输入当作“补充需求 / 修正方向 / 归档前修正说明”处理
+- 先执行 `protocol-update --json`，不要跳过主代理直接改业务文件
+- 不要把当前 change 的产物整份重写；默认只做增量修订
+
+## 指定历史需求修改（--change-id）
+
+当用户明确要对某个已归档的需求做增量修改时（如“改一下用户管理那个需求”），使用 `--change-id` 参数：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-update --target . --change-id "<change-id>" --user-input "<当前这条用户原话>" --json
+```
+
+- `change-id` 是需求归档时的标识符，对应 `openspec/changes/archive/YYYY-MM-DD-{change-id}/` 目录
+- 系统会自动找到归档目录，创建一个新的补丁变更（followup-patch），并关联原需求
+- 用户只需说出要改什么，不用重新走 /spec-start
+
+## 默认流程（未指定 --change-id）
+
+先执行：
+
+```bash
+./node_modules/.bin/ai-spec-auto protocol-update --target . --user-input "<当前这条用户原话>" --json
+```
+
+若返回 `fast_path.action = 'archived-changes-matched'`，说明系统找到了可能相关的归档需求：
+- 向用户展示 `fast_path.candidates` 列表（change_id、title、archive_date）
+- 让用户确认要对哪个需求做修改
+- 用户确认后，用 `--change-id <选中的change_id>` 重新执行本命令
+
+然后只按返回的 `turn` 执行：
+
+1. 若 `fast_path.executed = true`，优先消费 fast-path 结果：
+   - `archive-approved` / `complete-without-archive`：直接输出最终摘要，不再执行 `protocol-advance`
+   - `followup-patch-opened`：说明已打开补丁变更，再按返回的下一个 `turn` 继续
+   - `archived-changes-matched`：系统找到了可能相关的归档需求，展示候选列表让用户确认，用户确认后用 `--change-id` 重新执行
+   - `resume-paused-run`：说明已恢复停点，再按返回的下一个 `turn` 继续
+2. 若返回 `turn.mode = update-review`，必须先遵守 `turn.guidance.update_contract`
+3. 只读取 `turn.reads`，只写 `turn.writes`
+4. 若 `change_impact = patch | scope-delta | archive-fix`，默认在同一 `change_id` 内增量更新，不要推倒已有 proposal/specs/design/tasks/checklist/iterations
+5. 若 `change_impact = re-scope`，不要强行吞进当前 run；按 `reconcile_strategy` 给出“建议新建 change”的最小结论
+6. 若 `change_impact = followup-patch`，这是对已归档变更的补丁修正；继续沿返回的 patch run 推进，不要改旧 archive 目录
+7. 若存在 `turn.finalize_contract`，完成当前轮次后按契约推进，不要自行拼命令
+
+对用户只输出：
+
+- 当前识别到的变更类型
+- 会不会回退
+- 预计增量更新哪些产物
+- 下一步是什么
+
+不要输出：
+
+- 大段协议日志
+- scratch JSON
+- 内部运行态文件名
+- “整份重写 proposal/tasks/design/specs” 这类误导性说法

package/.agents/commands/cursor/opsx-apply.md

@@ -1,55 +1,55 @@
----
-name: /opsx-apply
-id: opsx-apply
-category: Workflow
-description: Cursor 兼容入口：按 tasks.md 执行 OpenSpec 任务实现
----
-
-这是 Cursor 的兼容入口，语义对齐 `/opsx:apply`。
-
-目标：
-- 选定一个 OpenSpec 变更
-- 读取 proposal / design / tasks 作为上下文
-- 按 `execute-task` 技能默认要求实施任务
-- 任务完成后更新 `tasks.md`
-- 全部完成时提示 `/opsx-archive`
-
-执行要求：
-
-1. 先确定当前要实施的变更  
-   - 若用户明确给了 change name，直接用它
-   - 若上下文里只有一个活跃变更，可直接采用
-   - 若存在多个候选，先用简短自然语言让用户确认，不使用旧版问答工具口吻
-
-2. 先读取变更状态与关键产物  
-   推荐先执行：
-   ```bash
-   npx openspec status --change "<change-name>" --json
-   ```
-   再读取：
-   - `openspec/changes/<change-name>/proposal.md`
-   - `openspec/changes/<change-name>/design.md`（若存在）
-   - `openspec/changes/<change-name>/tasks.md`
-
-3. 默认按 `execute-task` 技能执行  
-   优先读取：
-   - `.agents/skills/execute-task/SKILL.md`
-   若仓库仍保留源结构，再看：
-   - `.agents/skills/common/execute-task/SKILL.md`
-
-4. 实施时保持当前架构要求：
-   - 默认走 Superpowers 四步循环
-   - 逐项完成 `tasks.md` 中未勾选任务
-   - 每完成一项立即把 `- [ ]` 改成 `- [x]`
-   - 若遇到阻断、需求不清或高风险偏差，暂停并说明，不要硬猜
-
-5. 输出保持简洁：
-   - 当前使用的 change name
-   - 本轮完成了哪些任务
-   - 剩余任务或阻断
-   - 若全部完成，提示下一步 `/opsx-archive`
-
-守卫：
-- 不跳过 `proposal / design / tasks` 直接写代码
-- 不回退到旧版长篇流程播报
-- 不把 Cursor 连字符命令复制到其他 IDE
+---
+name: /opsx-apply
+id: opsx-apply
+category: Workflow
+description: Cursor 兼容入口：按 tasks.md 执行 OpenSpec 任务实现
+---
+
+这是 Cursor 的兼容入口，语义对齐 `/opsx:apply`。
+
+目标：
+- 选定一个 OpenSpec 变更
+- 读取 proposal / design / tasks 作为上下文
+- 按 `execute-task` 技能默认要求实施任务
+- 任务完成后更新 `tasks.md`
+- 全部完成时提示 `/opsx-archive`
+
+执行要求：
+
+1. 先确定当前要实施的变更  
+   - 若用户明确给了 change name，直接用它
+   - 若上下文里只有一个活跃变更，可直接采用
+   - 若存在多个候选，先用简短自然语言让用户确认，不使用旧版问答工具口吻
+
+2. 先读取变更状态与关键产物  
+   推荐先执行：
+   ```bash
+   npx openspec status --change "<change-name>" --json
+   ```
+   再读取：
+   - `openspec/changes/<change-name>/proposal.md`
+   - `openspec/changes/<change-name>/design.md`（若存在）
+   - `openspec/changes/<change-name>/tasks.md`
+
+3. 默认按 `execute-task` 技能执行  
+   优先读取：
+   - `.agents/skills/execute-task/SKILL.md`
+   若仓库仍保留源结构，再看：
+   - `.agents/skills/common/execute-task/SKILL.md`
+
+4. 实施时保持当前架构要求：
+   - 默认走 Superpowers 四步循环
+   - 逐项完成 `tasks.md` 中未勾选任务
+   - 每完成一项立即把 `- [ ]` 改成 `- [x]`
+   - 若遇到阻断、需求不清或高风险偏差，暂停并说明，不要硬猜
+
+5. 输出保持简洁：
+   - 当前使用的 change name
+   - 本轮完成了哪些任务
+   - 剩余任务或阻断
+   - 若全部完成，提示下一步 `/opsx-archive`
+
+守卫：
+- 不跳过 `proposal / design / tasks` 直接写代码
+- 不回退到旧版长篇流程播报
+- 不把 Cursor 连字符命令复制到其他 IDE