@gong-ym/ai-spec-auto 0.2.3

package/.agents/orchestration/runtime-state-handoff-spec.md

@@ -0,0 +1,264 @@
+---
+id: runtime-state-handoff-spec
+name: 运行状态交接与控制规范
+status: active
+owner: task-orchestrator
+description: 定义专家交接以及审批、恢复、状态查询时如何更新或读取 .ai-spec/current-run.json 与 .ai-spec/runs/<run-id>.json。
+---
+
+# 运行状态交接与控制规范
+
+> **Profile 驱动说明（V1）**：本规范中的示例以 `frontend-implementer` 作为实现角色。实际运行时，应根据当前项目的 `.ai-spec/manifest.json` 中的 `profile`，查询 `.agents/registry/profiles.json` 的 `implementation_role` 字段，动态决定实现角色：
+> - `vue` / `react` → `frontend-implementer`
+> - `springboot` → `backend-implementer`
+> - `node-tooling` → `tooling-implementer`
+
+## 1. 目的
+
+这份规范用于约束一件很具体的事情：
+
+> 当任务从一个专家交给下一个专家时，`run-state（运行状态）` 应如何更新。
+
+它要解决的问题是：
+
+- `current_role（当前专家）` 不能只停留在首轮状态
+- 专家交接不能只存在对话里
+- 后续 `approve（审批） / resume（恢复） / status（状态）` 需要读取同一份运行态
+
+## 2. 最小更新对象
+
+发生交接时，至少要更新这些字段：
+
+- `status（状态）`
+- `current_role（当前专家）`
+- `pending_gate（待审批点）`
+- `anchor（任务锚点）`
+- `events（事件列表）`
+- `timestamps.updated_at（更新时间）`
+
+## 3. 推荐命令
+
+当前最小实现使用：
+
+```bash
+ai-spec-auto runtime-state handoff \
+  --to-role frontend-implementer \
+  --next-role code-guardian \
+  --task-anchor ./.ai-spec/internal/tmp/frontend-implementer-anchor.json \
+  --status running
+```
+
+如果当前运行不是 `current-run.json`，也可以显式指定：
+
+```bash
+ai-spec-auto runtime-state handoff \
+  --run-id run_20260330_001 \
+  --to-role code-guardian \
+  --status running
+```
+
+审批放行：
+
+```bash
+ai-spec-auto runtime-state approve \
+  --gate before-implementation \
+  --to-role frontend-implementer \
+  --status running
+```
+
+恢复执行：
+
+```bash
+ai-spec-auto runtime-state resume \
+  --to-role frontend-implementer \
+  --status running
+```
+
+查询状态：
+
+```bash
+ai-spec-auto runtime-state status
+```
+
+进入阻断：
+
+```bash
+ai-spec-auto runtime-state gate-blocked --gate before-implementation --status waiting-approval
+```
+
+标记完成：
+
+```bash
+ai-spec-auto runtime-state complete
+```
+
+标记失败：
+
+```bash
+ai-spec-auto runtime-state fail --error "组件规范检查未通过"
+```
+
+用户取消：
+
+```bash
+ai-spec-auto runtime-state cancel --message "用户主动取消当前任务"
+```
+
+## 4. 推荐更新规则
+
+### 4.1 普通专家交接
+
+例如：
+
+```text
+requirement-analyst（需求解析专家）
+  -> frontend-implementer（前端实现专家）
+```
+
+建议：
+
+- `status（状态）` 更新为 `running`
+- `current_role（当前专家）` 更新为 `frontend-implementer`
+- `pending_gate（待审批点）` 保持原值或清空
+- `anchor（任务锚点）` 替换为当前专家的最新锚点
+- `events（事件列表）` 追加一条 `role-handoff`
+
+### 4.2 进入审批等待
+
+如果发生：
+
+```text
+frontend-implementer（前端实现专家）
+  -> before-implementation（审批点）
+```
+
+建议：
+
+- `status（状态）` 更新为 `waiting-approval`
+- `pending_gate（待审批点）` 写入审批点 ID
+- `events（事件列表）` 追加审批相关事件
+
+### 4.3 审批恢复后继续交接
+
+如果审批通过并恢复执行：
+
+- `status（状态）` 更新回 `running`
+- `pending_gate（待审批点）` 清空
+- `current_role（当前专家）` 更新为恢复后的目标专家
+
+## 5. 事件建议
+
+当前阶段建议至少支持：
+
+- `role-handoff`
+- `gate-blocked`
+- `gate-cleared`
+- `run-completed`
+- `run-failed`
+
+最小事件结构：
+
+```json
+{
+  "at": "2026-03-30T20:10:00+08:00",
+  "type": "role-handoff",
+  "status": "running",
+  "from_role": "requirement-analyst",
+  "to_role": "frontend-implementer",
+  "pending_gate": null,
+  "message": "handoff from requirement-analyst to frontend-implementer"
+}
+```
+
+## 6. 审批、恢复与状态查询
+
+### 6.1 `approve（审批）`
+
+最小实现会：
+
+- 校验当前是否存在 `pending_gate（待审批点）`
+- 清空 `pending_gate（待审批点）`
+- 将 `status（状态）` 恢复为 `running`
+- 追加一条 `gate-cleared` 事件
+- 可选切换到新的 `current_role（当前专家）`
+
+### 6.2 `resume（恢复）`
+
+最小实现会：
+
+- 把 `status（状态）` 恢复为 `running`
+- 可选清空 `pending_gate（待审批点）`
+- 可选更新 `current_role（当前专家）`
+- 追加一条 `run-resumed` 事件
+
+### 6.3 `gate-blocked（阻断）`
+
+最小实现会：
+
+- 把 `status（状态）` 更新为 `waiting-approval` 或 `blocked`
+- 写入或保留 `pending_gate（待审批点）`
+- 追加一条 `gate-blocked` 事件
+
+### 6.4 `status（状态）`
+
+最小实现会：
+
+- 读取 `current-run.json` 或指定 `run-id（运行实例 ID）`
+- 输出当前 `status（状态）`
+- 输出当前 `current_role（当前专家）`
+- 输出 `pending_gate（待审批点）`
+- 输出最后一条事件摘要
+
+### 6.5 `complete（完成）`
+
+最小实现会：
+
+- 把 `status（状态）` 更新为 `success`
+- 清空 `pending_gate（待审批点）`
+- 追加一条 `run-completed` 事件
+- 记录 `timestamps.finished_at`
+
+### 6.6 `fail（失败）`
+
+最小实现会：
+
+- 把 `status（状态）` 更新为 `failed`
+- 清空 `pending_gate（待审批点）`
+- 追加一条 `run-failed` 事件
+- 将失败原因追加到 `errors（错误列表）`
+- 记录 `timestamps.finished_at`
+
+### 6.7 `cancel（取消）`
+
+最小实现会：
+
+- 把 `status（状态）` 更新为 `cancelled`
+- 清空 `pending_gate（待审批点）`
+- 追加一条 `run-cancelled` 事件
+- 记录 `timestamps.finished_at`
+
+## 7. 当前阶段边界
+
+当前最小实现只解决：
+
+- 单次交接更新
+- 当前专家更新
+- 事件追加
+- 可选锚点替换
+- 最小审批放行
+- 最小恢复执行
+- 最小阻断落盘
+- 最小状态查询
+- 最小完成落盘
+- 最小失败落盘
+- 最小取消落盘
+
+还没有完整覆盖：
+
+- 审批通过后的全链路状态机
+- 自动回滚
+- 多审批点并行处理
+
+## 8. 一句话要求
+
+> 只要发生专家交接，就不应只在对话里说“下一步交给谁”，而应同步更新 `run-state（运行状态）`，把当前专家、锚点和事件历史稳定落到 `.ai-spec/` 里。

package/.agents/orchestration/task-anchor-spec.md

@@ -0,0 +1,212 @@
+---
+id: task-anchor-spec
+name: 任务锚点规范
+status: active
+owner: task-orchestrator
+description: 定义 run（运行编排） 中 task-anchor（任务锚点） 的最小结构、注入时机和交接规则，供主代理和下游专家长期复用。
+---
+
+# task-anchor（任务锚点）注入规范
+
+## 1. 文档目的
+
+本文档定义 `run（运行编排）` 中 `task-anchor（任务锚点）` 的最小结构、注入时机和交接规则。
+
+这份规范要解决的问题是：
+
+- 多专家协同时，原始任务意图不能越传越偏
+- 专家之间不应依赖长对话历史来理解任务
+- `task-orchestrator（任务主代理）` 每次交接都应重新注入核心目标和关键约束
+
+一句话：
+
+> `task-anchor（任务锚点）` 是每轮专家执行前都要重新注入的“任务原点”。
+
+## 2. 什么是 `task-anchor（任务锚点）`
+
+`task-anchor（任务锚点）` 不是完整上下文，也不是运行状态全文。
+
+它更像一份最小执行锚点，只回答 5 个问题：
+
+1. 原始任务目标是什么
+2. 当前处于哪一阶段
+3. 本轮专家是谁
+4. 本轮必须遵守哪些约束
+5. 本轮应该产出什么
+
+所以：
+
+- `run-plan（运行计划）` 解决“整次任务怎么跑”
+- `run-state（运行状态）` 解决“当前跑到哪里了”
+- `task-anchor（任务锚点）` 解决“这位专家这一轮该盯住什么”
+
+## 3. 最小结构
+
+当前阶段建议最小 `task-anchor（任务锚点）` 结构如下：
+
+```json
+{
+  "schema_version": 1,
+  "kind": "task-anchor",
+  "run_id": "run_20260330_001",
+  "task": {
+    "raw_goal": "创建一个商品组件",
+    "change_id": "add-product-card",
+    "input_kind": "natural-language"
+  },
+  "stage": {
+    "flow_id": "prd-to-delivery",
+    "current_role": "requirement-analyst",
+    "next_role": "frontend-implementer"
+  },
+  "constraints": {
+    "rules": ["component-standard", "style-standard"],
+    "must_not": ["不要跳过规则检查", "不要超出当前需求范围"]
+  },
+  "artifacts": {
+    "proposal": "openspec/changes/add-product-card/proposal.md",
+    "tasks": "openspec/changes/add-product-card/tasks.md"
+  },
+  "expected_output": [
+    "补齐 proposal（提案）",
+    "输出 tasks（任务清单）",
+    "列出缺失输入"
+  ]
+}
+```
+
+## 4. 推荐 Markdown（标记语言）格式
+
+如果当前阶段由 `IDE（开发工具） AI（智能体）` 直接消费，也可以使用下面这种更便于阅读的格式：
+
+```md
+## task-anchor（任务锚点）
+- 原始目标：创建一个商品组件
+- 变更 ID：add-product-card
+- 当前流程模板：prd-to-delivery（需求到交付）
+- 当前专家：requirement-analyst（需求解析专家）
+- 下一位专家：frontend-implementer（前端实现专家）
+
+## 本轮约束
+- 必须遵守：组件规范、样式规范
+- 不得越界：不要扩展到无关页面
+- 当前可用产物：proposal.md、tasks.md
+
+## 本轮目标
+- 产出 proposal（提案）和 tasks（任务清单）
+- 如果信息不足，先列缺口，不直接进入实现
+```
+
+## 5. 注入时机
+
+当前阶段建议在以下 4 个节点注入：
+
+### 5.1 主代理首轮生成 `run-plan（运行计划）` 后
+
+当 `task-orchestrator（任务主代理）` 首次识别任务并输出 `run-plan（运行计划）` 后，应立即生成一份对应的 `task-anchor（任务锚点）`。
+
+### 5.2 每次交给下一位专家前
+
+只要发生角色切换，就应重新注入一份新的 `task-anchor（任务锚点）`。
+
+例如：
+
+```text
+task-orchestrator（任务主代理）
+  -> requirement-analyst（需求解析专家）
+  -> frontend-implementer（前端实现专家）
+  -> code-guardian（规范守护者）
+```
+
+每一跳都应有自己的锚点，而不是复用同一份长上下文。
+
+### 5.3 审批通过或恢复执行后
+
+如果任务经过：
+
+- `approve（审批）`
+- `resume（恢复）`
+
+则重新进入执行前，也应重新注入锚点，避免上下文漂移。
+
+### 5.4 状态明显变化后
+
+当以下内容发生明显变化时，建议刷新锚点：
+
+- 当前专家变化
+- 审批点变化
+- 当前阶段产物变化
+- 缺失输入被补齐
+
+## 6. 不同专家的注入差异
+
+`task-anchor（任务锚点）` 不是对所有专家都一模一样。
+
+### 6.1 `requirement-analyst（需求解析专家）`
+
+重点注入：
+
+- 原始目标
+- 当前需求边界
+- 缺失输入
+- 需要沉淀的 `proposal（提案） / tasks（任务清单）`
+
+### 6.2 `frontend-implementer（前端实现专家）`
+
+重点注入：
+
+- 当前任务范围
+- 相关 `tasks（任务清单）`
+- 项目规则
+- 代码目录和目标位置
+- 本轮需要修改的产物
+
+### 6.3 `code-guardian（规范守护者）`
+
+重点注入：
+
+- 当前代码变更范围
+- 规则列表
+- 当前验收目标
+- `checklist（检查清单）` 与残留风险
+
+因此：
+
+> `task-anchor（任务锚点）` 的骨架固定，但具体注入内容允许按专家做裁剪。
+
+## 7. 与其它对象的关系
+
+### 7.1 与 `run-plan（运行计划）`
+
+- `run-plan（运行计划）` 是全局计划
+- `task-anchor（任务锚点）` 是当前专家的本轮执行锚点
+
+### 7.2 与 `run-state（运行状态）`
+
+- `run-state（运行状态）` 是全局运行状态快照
+- `task-anchor（任务锚点）` 是给当前专家看的最小执行摘要
+
+### 7.3 与 `OpenSpec（规范产物）`
+
+- `OpenSpec（规范产物）` 是长期沉淀的黑板
+- `task-anchor（任务锚点）` 是本轮从黑板里裁剪出来的最小执行片段
+
+## 8. 当前阶段的最小要求
+
+当前阶段不要求把 `task-anchor（任务锚点）` 做成单独文件。
+
+最小可行做法是：
+
+1. 在主代理交接时显式输出 `task-anchor（任务锚点）`
+2. 先把字段结构和交接协议定稳
+3. 允许后续再决定是否落到 `.ai-spec/anchors/`
+
+也就是说，当前阶段重点是：
+
+- 先统一格式
+- 先统一注入时机
+- 先统一不同专家拿到的最小信息结构
+
+## 9. 一句话结论
+
+> `task-anchor（任务锚点）` 的作用不是增加上下文，而是压缩上下文。它让每位专家在每一轮执行前，都重新回到“原始目标 + 当前阶段 + 本轮约束 + 本轮输出”的最小闭环里。

package/.agents/orchestration/task-orchestrator-adapter-payload.md

@@ -0,0 +1,153 @@
+---
+id: task-orchestrator-adapter-payload
+name: 主代理自动执行适配载荷规范
+status: active
+owner: task-orchestrator
+description: 定义 task-orchestrator 输出给自动执行适配层消费的最小 payload 结构；该适配层仅作为宿主 Runner 不可用时的回退桥接。
+---
+
+# 主代理自动执行适配载荷规范
+
+## 1. 目的
+
+这份规范解决的是一个具体问题：
+
+> `task-orchestrator（任务主代理）` 已经产出了结构化结果，但运行环境不想手工拼 `runtime-state（运行状态）` 命令。
+
+当宿主 `Runner（运行器）` 不可用时，需要一个稳定的回退适配入口：
+
+```bash
+ai-spec-auto task-orchestrator-adapter apply --payload <file>
+```
+
+由适配层自动识别当前属于：
+
+- `bootstrap（首轮桥接）`
+- `handoff（专家交接）`
+- `gate-blocked（阻断）`
+- `approve（审批）`
+- `resume（恢复）`
+- `complete（完成）`
+- `fail（失败）`
+- `cancel（取消）`
+- `status（状态）`
+
+## 2. 支持的两类 payload
+
+### 2.1 首轮桥接 payload
+
+直接复用：
+
+- [task-orchestrator-bootstrap-payload.md](../roles/common/task-orchestrator-bootstrap-payload.md)
+
+也就是说，这类输入本身就可直接交给适配器：
+
+```bash
+ai-spec-auto task-orchestrator-adapter apply --payload ./.ai-spec/internal/tmp/task-orchestrator-bootstrap.json
+```
+
+### 2.2 运行态动作 payload
+
+最小结构：
+
+```json
+{
+  "schema_version": 1,
+  "kind": "task-orchestrator-runtime-action",
+  "action": "handoff"
+}
+```
+
+其中 `action` 允许：
+
+- `handoff`
+- `gate-blocked`
+- `approve`
+- `resume`
+- `complete`
+- `fail`
+- `cancel`
+- `status`
+
+并在关键动作成功后，为下一轮 `task-orchestrator（任务主代理）` 产出新的 `expert-dispatch（专家派发载荷）`、为当前专家产出新的 `expert-execution（专家执行载荷）` 清出干净状态。
+
+## 3. 推荐字段
+
+适配器会读取这些字段并映射到 `runtime-state（运行状态）`：
+
+```json
+{
+  "schema_version": 1,
+  "kind": "task-orchestrator-runtime-action",
+  "action": "handoff",
+  "run_id": "run_20260331_101010_abcd",
+  "to_role": "frontend-implementer",
+  "next_role": "code-guardian",
+  "from_role": "requirement-analyst",
+  "status": "running",
+  "pending_gate": null,
+  "clear_pending_gate": true,
+  "message": "handoff to frontend-implementer",
+  "task_anchor": {
+    "schema_version": 1,
+    "kind": "task-anchor"
+  }
+}
+```
+
+说明：
+
+- `run_id` 可选；缺省时读取 `.ai-spec/current-run.json`
+- `task_anchor` 推荐直接内联，不要求单独落文件
+- `status`、`message`、`gate` 按动作类型按需提供
+
+## 4. 示例
+
+### 4.1 阻断
+
+```json
+{
+  "schema_version": 1,
+  "kind": "task-orchestrator-runtime-action",
+  "action": "gate-blocked",
+  "gate": "before-implementation",
+  "status": "waiting-approval",
+  "message": "等待实现前审批"
+}
+```
+
+### 4.2 交接
+
+```json
+{
+  "schema_version": 1,
+  "kind": "task-orchestrator-runtime-action",
+  "action": "handoff",
+  "to_role": "frontend-implementer",
+  "next_role": "code-guardian",
+  "status": "running",
+  "task_anchor": {
+    "schema_version": 1,
+    "kind": "task-anchor",
+    "stage": {
+      "current_role": "frontend-implementer",
+      "next_role": "code-guardian"
+    }
+  }
+}
+```
+
+### 4.3 完成
+
+```json
+{
+  "schema_version": 1,
+  "kind": "task-orchestrator-runtime-action",
+  "action": "complete",
+  "message": "规范检查通过，任务完成"
+}
+```
+
+## 5. 一句话约束
+
+> 主代理若要进入自动执行链，应优先输出最小结构化 scratch 交给宿主 `Runner（运行器）` 消费；若 `Runner` 不可用，再回退为 adapter payload，由 `ai-spec-auto task-orchestrator-adapter apply` 统一翻译为 `runtime-state（运行状态）` 更新，而不是在对话里手写命令。