@aipper/aiws-spec 0.0.46 → 0.0.48

package/docs/opencode-omo-adapter.md

@@ -244,6 +244,58 @@ aiws opencode supervise .
   - 临时状态允许写入 `.agentdocs/tmp/opencode-autonomy/`
   - 最终结论仍必须收敛到 `changes/<id>/...` 或 `.agentdocs/tmp/review/...`
 
+
+
+## Goal FSM 与续跑边界（TOOLING-003D / WP4）
+
+aiws **不**实现自有的 `session.idle` 多会话编排器，也不把 goal 协议升格为第二套 runtime orchestrator。
+
+### 分层职责
+
+| 层 | 权威 / 载体 | 职责 | 非职责 |
+|----|-------------|------|--------|
+| Goal FSM | `.aiws/goals/<id>.state.json` + `aiws goal advance` | phase/checkpoint 机器状态；sole writer 见 contract §10 | 不调度 OS 进程、不跑 multi-session loop |
+| Ralph（主马达） | `.opencode/ralph-loop.local.md` + `/ralph-loop` | 会话内自引用 continuation，直到任务声明完成 | **不**写 goal FSM 字段 |
+| Boulder（辅马达） | session.idle + 未完成 todos | 冷启动/idle 时再 nudge 未完成项 | **不**写 goal FSM；不替代 Ralph |
+| 入口 L1–L3 | session inject + using-aiws + 纪律 | 暴露 active/paused goal 与 `next_action`；medium+ 路由 `$ws-goal` | **不做 L4** programmatic skill invoke |
+
+### Ralph 主绑定（镜像刷新协议）
+
+在每个 **phase 验证通过** 且 **`aiws goal advance` 成功** 之后，主 session / skill **必须**刷新 Ralph 镜像任务（若本会话启用了 Ralph），使 continuation 提示包含：
+
+1. `goal_id`、`status`、`current_phase`、下一 pending checkpoint（读 state.json）
+2. 明确指令：继续 `/ws-goal` 管道（或 `continue`/`resume`），**下一 phase 边界再次调用** `aiws goal advance`
+3. 完成判定：**仅当** FSM `status=complete`（或等价终态）**且** completion audit 通过，才可在 Ralph 中输出 `<promise>DONE</promise>`
+4. **禁止**仅因 Ralph 迭代次数或模型“感觉做完了”而 DONE
+
+建议镜像任务标题形态：`goal:<id> phase=<current_phase> → advance@boundary`。
+
+Ralph 文件（`.opencode/ralph-loop.local.md`）是**会话级续跑状态**，不是 goal FSM；可被覆盖刷新，但不得手写复制 checkpoint complete。
+
+### Boulder 辅绑定
+
+- 将剩余 phases 映射为 **镜像 todos**（可选）：每项对应一个未 complete 的 checkpoint，文案指向 `/ws-goal continue <id>` + `aiws goal advance`
+- session.idle 时 Boulder 可再次注入“未完成 todo → 继续 goal”指令
+- Boulder **不得**直接编辑 `state.json`；推进仍走 advance
+
+### 失败语义
+
+| 情况 | 行为 |
+|------|------|
+| `aiws goal advance` 失败（结构/前置） | **不要** promise DONE；输出 CLI error；修复后重试 advance |
+| dirty state | `aiws goal advance --heal` 或 `aiws goal validate-state --heal`，再 advance |
+| 依赖链 UNHEALTHY / intake UNRESOLVED_BRANCH / PLAN 多分支需选择 | 协议级暂停或等人；**不要** advance 伪装 complete |
+| workspace HIGH（§2.5.4） | **自动解决**（stash/submodule 策略等）；仅自动化失败时提示，**默认不阻断** advance |
+| goal paused | session inject `next_action=/ws-goal resume`；Ralph/Boulder 应指向 resume，不强制跑完 |
+
+### 非目标（本适配器）
+
+- 不在 aiws 内实现 session.idle daemon / 第二 orchestrator
+- 不 fork oMo；不把 `ws-autonomy`/tmux helper 升格为 goal 主路径
+- plugin **只注入文本**，不静默改业务文件、不 L4 调 skill
+
+实验层边界仍适用：`ws-autonomy` / tmux helper 不替代 goal FSM，也不替代 Ralph/Boulder 作为主续跑路径。
+
 ## 非目标
 
 - 不由 `aiws` 接管 `.opencode/oh-my-opencode.json` 的完整配置。

package/docs/workflow-router-rules.md

@@ -48,6 +48,7 @@ router 在做任何 workflow 判断前，必须先读取：
 | `finish_request` | 收尾/合并/推送/cleanup | 用户要求 finish、merge、push、收尾、交付完成、清理 change 分支。 | `ws-finish` | 必须满足 finish gate，不能跳过 validate / push / cleanup。 | N/A | finish 是独立治理阶段，不能与普通实现混用。 |
 | `handoff_request` | 交接/归档总结 | 用户要求 handoff、交接说明、archive summary、会话总结或接力说明。 | `ws-handoff` | 先确认 change 已 finish 或 archive 上下文存在。 | N/A | handoff 依赖已有证据与归档上下文，不应在实现前触发。 |
 | `plan_first` | 中大型实现或需要建立 change 上下文 | 任务是多步实现、跨文件、跨模块、需要方案、需要新建 change 分支，且需求已经冻结或已有可消费的 intake 草案。 | `ws-plan` | plan 过 gate 前不进入 `ws-dev`。 | N/A | medium/complex 任务在需求冻结后必须先生成可落盘计划，避免 router 直接跳进实现。 |
+| `goal_driven` | 中大型实现（ws-goal 可用时） | 任务是多步实现、跨文件、跨模块，且 ws-goal 已初始化（检测到 .aiws/goals/ 目录或 ws-goal skill 可用），且任务复杂度 ≥ medium（涉及文件 > 3 或涉及模块 > 1）。 | `ws-goal` | ws-goal 先做 intake/dep_check/ws_analysis，再进入 pipeline delegation。 | N/A | ws-goal 可用时，medium+ 任务优先使用 ws-goal 协议（目标设定→依赖链预检→管道委托→完成审计），**并且**在必要时可通过 degraded mode 降级回 ws-dev。当 ws-goal 不可用或路由结果不明确时，fallthrough 到 plan_first（ws-plan）。 |
 | `direct_implementation` | 小步实现/修复/配置调整 | 已知改动位置、已知改动内容、无需探索代码库；router 已收集项目上下文（涉及文件数、模块范围）确认是小步修复；归因清晰、验证入口明确，且无需先改 requirements 或单独评审。 | `ws-dev` | 若执行中发现复杂度升高，必须回退到 `ws-plan`。 | - router 必须先收集项目上下文（git status, 涉及文件范围, 当前 change 状态）确认任务确实是单点/小步修复，而非仅凭用户描述判定<br>- collected project context (git status/diff/stat)<br>- change file count ≤ 3<br>- change total lines ≤ 100<br>- verify entry confirmed<br>- design gate: for implementations changing >2 files, proposal.md and tasks.md must exist in changes/<id>/ | router 允许明确的小步任务直接实现，但前提是已验证项目上下文确认范围可控；若用户明确要走轻量入口，可在实现阶段显式使用 `ws-dev-lite` 作为 `ws-dev` 的 facade。router 不能仅凭用户描述判"小步"；必须读项目上下文验证。 |
 | `escape_hatch` | 用户显式跳过流程 | 用户明确说"直接改"/"跳过流程"/"do it inline"/"不要走流程"等表达 | `ws-dev-lite` | 仍须遵守最小约束：归因到 Req_ID、有验证入口、落盘 evidence 标记 [escape-hatch: direct-implementation] | N/A | 允许用户在明确知情的情况下跳过完整流程，但不免除基础治理约束 |
 | `design_first` | 需要先出设计方案 | 任务涉及新流程、新模块、新架构或对现有架构有显著影响的方向决策，需要先出设计方案再进入实现。 | `ws-plan` | plan 阶段需包含设计内容（design.md 或 plan 内 design 章节），plan 过 gate 前不进入 `ws-dev`。 | N/A | 复杂或高影响改动应先出设计方案，让设计过审后再投入实现，避免返工。当前通过 ws-plan 统一承载设计，无需单独 ws-design skill。 |
@@ -64,6 +65,7 @@ router 在做任何 workflow 判断前，必须先读取：
 | `case_review_request` | 用户明确要求 review、审计、找风险或检查回归。 | review 这批改动，先给我风险和回归点，不要先改代码。 | `review_request` | `ws-review` | 评审任务的输出契约是 findings，不应直接进入实现。 |
 | `case_finish_request` | 用户要求合并、push、cleanup 或 finish 当前 change。 | 把 demo-change finish 掉并 push，顺便 cleanup。 | `finish_request` | `ws-finish` | finish 是独立治理阶段，必须先走 finish gate。 |
 | `case_handoff_request` | 用户要求 handoff、交接说明、archive summary 或接力文档。 | 给这个 change 写 handoff，并补 archive summary。 | `handoff_request` | `ws-handoff` | handoff 依赖已有 finish/archive 上下文，不能当成普通实现。 |
+| `case_goal_driven` | 任务是跨文件、多步实现，且 ws-goal 已初始化。 | 实现 dashboard 的阶段治理视图，ws-goal 已经初始化。 | `goal_driven` | `ws-goal` | ws-goal 可用时优先走 ws-goal 协议（目标设定→pipeline delegation→completion audit），且必要时可降级回 ws-dev。 |
 | `case_plan_first` | 任务是跨文件、多步实现，且需要先建立 change 分支或方案。 | 实现 dashboard 的阶段治理视图并补测试，需要新建 change 和计划。 | `plan_first` | `ws-plan` | 中大型实现应先落盘计划，再进入 dev。 |
 | `case_direct_implementation` | 任务是小步明确修复，归因和验证入口都已清楚。 | 修复 install-skills 的默认路径，并补一条可复现回归。 | `direct_implementation` | `ws-dev` | 小步明确实现允许直接进入 dev；若用户明确要轻量直修，可进一步显式使用 ws-dev-lite，但治理归属仍收敛到 ws-dev。 |
 | `case_context_gate` | Router 必须先收集项目上下文再判 direct vs plan。 | 修复一个 auth bug。 | `direct_implementation` | `ws-dev` | Router 必须先 git status/读相关文件确认范围后才能判 direct；`precondition` 字段显式要求先收集上下文；不能仅凭任务描述判"小步"。 |
@@ -85,7 +87,7 @@ router 在做任何 workflow 判断前，必须先读取：
 - 除缺失真值场景外，router 至少要给出一个明确的 `Route:` 结果或明确的澄清问题。
 - 当 `routeTo=clarify` 时，必须停止，不直接写代码。
 - 当 `routeTo=ws-intake` 时，必须先逐条冻结问题并产出 intake 草案；不要跳过到 `ws-plan`。
-- 当 `routeTo=ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` / `ws-intake` 时，后续行为必须遵循对应 skill 契约。
+- 当 `routeTo=ws-goal` / `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` / `ws-intake` 时，后续行为必须遵循对应 skill 契约。
 - 任何 route 都不能绕过 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
 
 ## 说明
@@ -93,3 +95,4 @@ router 在做任何 workflow 判断前，必须先读取：
 - default-routed workflow 不等于 daemon / pane / runtime orchestration；这一版只固定真值和入口。
 - `using-aiws` 可以作为默认入口；若未来需要更短命名，可再引入 `ws-router` 作为等价别名。
 - OpenCode 的 native 目录不同，但 router 语义必须共用同一份 JSON 真值。
+- v2: 新增 goal_driven 路由规则。当 ws-goal 初始化完成时，medium+ 复杂度任务优先路由到 ws-goal（而非 ws-plan）。ws-goal 在必要时可通过 degraded mode 降级回 ws-dev。

package/docs/ws-goal-contract.md

@@ -205,6 +205,8 @@ ws-goal 在执行 pipeline delegation（管道委托，见 1.§ 第四步）之
 
 > 设计原则：工作区问题不应该是 ws-goal 的阻断项。ws-goal 应尽可能自动处理，让用户专注于目标本身，而不是被工作区状态打断。只有自动化处理真正失败时才通知用户——且即使通知也不阻断，只输出提示。
 
+> **SSOT 说明（TOOLING-003D）**：本节为 HIGH 工作区策略唯一真值（**HIGH → 自动解决**）。skill/command 文案**不得**再引入「HIGH → 阻断并等用户确认」；若历史 skill 仍有该表述，以本合同为准，后续 WP 对齐 skill 文本。
+
 ---
 
 ## 3. Protocol Specification
@@ -1463,6 +1465,8 @@ Session 重启后 ws-goal step 0 检测流程：
 
 > 设计原则：用户执行 ws-goal 即代表意图明确——继续未完成的工作。重复询问"是否要继续"增加摩擦、不增加价值。仅在无法自动决策时（如多个冲突 goal）才需要用户介入。
 
+> **机器推进写权威（TOOLING-003D）**：跨 session 的 Auto-Resume 语义仍由本协议定义；**机器侧 phase/checkpoint 推进与 state.json 写入**以 `aiws goal advance` 为唯一写者（见 §10）。手写或漂移的 dirty state 由 `aiws goal validate-state` / `validate` 拒绝或 heal，不依赖模型改 JSON。
+
 #### 7.4.1 Question Tool Interruption
 
 `question` tool 调用会中断当前会话，下一个会话是新的 session 边界。Auto-Resume（§7.4）适用：
@@ -1560,6 +1564,8 @@ Instructions: Continue from the failed phase. Do NOT redo completed phases.
 
 **CLI 编码**：此章节描述的自动推进决策逻辑由 `aiws goal advance` CLI 命令实现（§10）。CLI 读取 state.json，执行状态机校验，计算下一个 phase/group，然后写入更新后的 state.json。pre-commit hook 在每次提交时调用 `aiws goal validate-state` 校验 state.json 一致性。不再依赖 AI 对自然语言描述的理解来推导"下一步去哪"。
 
+> **Auto-Resume / Auto-Advance vs 续跑马达（TOOLING-003D）**：§7.4 与 §7.8 是**协议**；`aiws goal advance` 是 **sole phase-boundary writer**。会话内多 phase 续跑马达属于平台（**Ralph 主 / Boulder 辅**），不是 aiws runtime orchestrator。详见 §10 与 `opencode-omo-adapter.md`。
+
 #### 7.8.2 Mechanism
 
 使用基于 **state.json checkpoint 文件产出**的自动推进，不依赖文本标记（如 `PHASE_DONE` 字符串）：
@@ -1789,3 +1795,65 @@ oracle_advisor:
 - Oracle-Advisor 负责**决策点分析**（有分支或阻断时提供结构化建议）
 - 两者不重叠：Auto-Advance 在无阻断时自动推进；Oracle-Advisor 在决策点提供信息支持
 - Oracle-Advisor 分析完成后，主 session 或用户做出最终决定，然后 Auto-Advance 继续推进
+
+
+## 10. Authority CLI (TOOLING-003D)
+
+> 本章定义 **thin authority CLI** 与协议层的边界。协议仍是非 runtime：不实现 multi-session 调度器，不实现 Codex 级 budget 引擎，不自建 session.idle orchestrator。
+
+### 10.1 Commands
+
+| 命令 | 角色 |
+|------|------|
+| `aiws goal advance` | **phase 边界唯一写者（sole writer）**：读取 `.aiws/goals/<id>.state.json`，校验状态机，计算下一 phase/group，原子写入更新后的 state |
+| `aiws goal validate-state` | 校验单个/批量 state.json 与 checkpoint 一致性（可挂 pre-commit） |
+| `aiws goal validate` | 更广的 goal 工件/协议校验入口（含脏状态策略） |
+| `aiws goal help` | 帮助与权威边界说明 |
+
+实现可位于 `packages/aiws/src/commands/goal-*.ts`；行为语义以本合同 + 单测为准。
+
+### 10.2 Sole writer rules
+
+1. **Phase 边界写 state**：仅 `aiws goal advance`（及经其明确暴露的 dry-run / heal 路径）可把 checkpoint 推进为 complete / 启动下一 phase / 更新 `current_phase`。
+2. **禁止**把「模型手改 JSON」当作正常推进路径。手写或脚本直接改写导致的 dirty state：
+   - `validate` / `validate-state` **拒绝**不一致状态；或
+   - 提供 **heal** 路径恢复到合法 FSM 快照（实现细节见 TOOLING-003D 后续 WP）。
+3. 会话注入、skill 文案、续跑镜像可以**读** state；写权威仍收敛到 CLI。
+
+
+### 10.6 Dirty state catalog (TOOLING-003D)
+
+| Dirty 信号 | 典型原因 | 恢复 |
+|------------|----------|------|
+| 全部 checkpoint `complete` 但 `status` 仍为 `active`/`paused` | 手改或旧实现漏写终态 | `aiws goal advance --heal` 或 `validate-state --heal` → 收敛为 `complete` |
+| `status=complete` 但存在未 complete checkpoint | 手改或中途损坏 | heal → 重开 `active` 并对齐 `current_phase` |
+| 缺 checkpoint shell / `completed_at` | 部分写入 | heal 补齐合法壳字段 |
+| 有 active/paused `.md` 无 `state.json` | §7.6 旧格式 | `advance --heal` 迁移生成 state 后继续 |
+| validate 结构错误且不可 heal | 损坏 JSON / 未知 phase | 人工修复或重建 goal（**禁止** freehand 伪装 complete） |
+
+规则：dirty **拒绝**作为正常 advance 路径；必须 `--heal` 或先 `validate-state` 通过。Sole writer 仍是 `aiws goal advance`。
+
+### 10.3 Protocol vs platform continuation
+
+| 层 | 职责 | 非职责 |
+|----|------|--------|
+| 协议 §7.4 Auto-Resume | session 重启后恢复语义 | 不调度 OS 进程 |
+| 协议 §7.8 Auto-Advance | phase 完成后前向推进语义 | 不替代 CLI 写 state |
+| Authority CLI §10 | state.json 机器推进与校验 | 不跑 multi-session loop |
+| 平台续跑 | **Ralph 主 / Boulder 辅** 作为 continuation 马达 | 不拥有 goal FSM 权威 |
+
+OpenCode 绑定细节见 `packages/spec/docs/opencode-omo-adapter.md`（TOOLING-003D WP4 补全镜像刷新行为）。
+
+### 10.4 Entry loop levels (L1–L3, no L4)
+
+与 TOOLING-003D / intake 冻结一致：
+
+- **L1**：session inject（`getActiveGoal` / goal-context / `next_action`）
+- **L2**：using-aiws ↔ `workflow-router-rules` 投影（medium+ → `$ws-goal`，保留 escape-hatch）
+- **L3**：active/paused goal 时 skill/AGENTS 纪律（禁止无故直跳 ws-dev/ws-plan）
+- **不做 L4**：programmatic skill invoke
+
+### 10.5 HIGH workspace policy pointer
+
+工作区 HIGH 策略 **SSOT 为 §2.5.4（自动解决）**。Authority CLI 与 skill 不得重新引入「HIGH 必须用户确认才继续」作为默认门禁。
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

package/templates/workspace/.opencode/command/ws-goal.md

@@ -23,6 +23,26 @@ ws-goal 只做三件事，不做更多：
 
 1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
 
+
+## Phase Boundary Authority (TOOLING-003D / contract §10)
+
+**Sole writer**: `aiws goal advance` is the **only** allowed writer for phase-boundary fields in `.aiws/goals/<goal-id>.state.json` (`status`, `current_phase`, checkpoint transitions).
+
+**MUST after each phase verifies complete**:
+```bash
+aiws goal advance --goal-id <goal-id> [--json]
+aiws goal advance --goal-id <goal-id> --phase <next>   # explicit (prereqs required)
+aiws goal advance --goal-id <goal-id> --heal           # dirty / §7.6 migrate missing state
+aiws goal advance --goal-id <goal-id> --dry-run
+```
+
+**FORBIDDEN**: hand-edit `state.json` to mark complete / start next phase. Dirty → `validate-state --heal` or `advance --heal`, then continue with advance.
+
+**Continuation (WP4)**: After each successful advance, refresh Ralph mirror (primary) and optional Boulder todos (secondary). Ralph/Boulder never write state.json. DONE only when FSM complete + audit. See `opencode-omo-adapter.md` Goal FSM 与续跑边界.
+
+**Allowed**: create initial pending state when defining a goal; read state; write Progress Notes in `.md` (not FSM fields).
+
+
 ## 执行流程
 
 0) 检查 `.aiws/goals/` 目录（先扫描 `.state.json`，再扫描 `.md`）：
@@ -31,6 +51,20 @@ ws-goal 只做三件事，不做更多：
       - 若发现 status=active 或 status=paused 的 state.json，输出恢复选项（从失败的 phase 继续 / 跳过 / handoff）
       - 用户选择后设置 current_phase 到对应 phase 并继续执行
    c) 若未找到 state.json 但有 status=active 或 status=paused 的 .md 文件（旧格式迁移），按 §7.6 自动生成 state.json 后全量重跑
+   d) 若发现 status=complete 的 state.json 但 checkpoints 中仍有未完成项（status != complete）：
+      - 读取对应 `.aiws/goals/<goal-id>.md` 文件，输出 goal 摘要
+      - 列出所有未完成的 checkpoints（status=in_progress/pending/failed 的项）
+      - 输出续跑选项：
+        - （a）跳过 PHASE 0，从依赖链预检（step 4）恢复执行
+            自动跳过 step 1-3（真值读取/目标输入/文件生成），使用已有 goal 文件
+        - （b）查看 goal 详情
+        - （c）忽略，按新目标处理
+      - 若用户选择 a）：
+        - 设置 state.json：status=active，current_phase 到最近一个未完成 checkpoint 对应 phase
+        - 输出"跳过 PHASE 0，从 step 4 依赖链预检恢复"
+        - 直接进入 step 4 继续执行
+      - 若用户选择 b）：输出完整 goal 详情后回到选项
+      - 若用户选择 c）：作为新目标正常走 step 0→1→2 完整流程
 
 1) 读取真值文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`），确认项目规则与边界。
 
@@ -80,46 +114,19 @@ ws-goal 只做三件事，不做更多：
        - 若用户未放行：设置 goal status=paused 并结束
 
 4.5) **Workspace State Analysis**：依赖链预检通过后、delegation 前，分析工作区状态并输出报告。
-     必须用户确认后才能进入 step 5。
-     a) 检查 dirty 状态：
-        - staged changes（`git diff --cached --stat`）
-        - unstaged changes（`git diff --stat`）
-        - untracked files（`git status --porcelain` 中 `??` 开头项）
-     b) 检查 submodule 状态：
-        - 每个 submodule 的 dirty 状态（`git submodule status`）
-        - detached HEAD（`git -C <path> symbolic-ref HEAD` 失败）
-        - unpushed 提交（`git -C <path> log @{u}..HEAD --oneline`）
-     c) 检查 change artifacts：
-        - 存在哪些 change 分支（`git branch --list 'change/*'`）
-        - 是否有未完成的 change（proposal/tasks 仍含 WS:TODO）
-        - 是否与当前 goal 冲突（同名、同域）
-     d) 检查 git 状态：
-        - 是否有 unpushed 提交（`git log @{u}..HEAD --oneline`）
-        - 是否有 stash（`git stash list`）
-     e) 评估影响：逐项判断与当前 goal 的关联度：
-        - HIGH：阻碍 goal 执行，必须处理
-        - MED：可能干扰或产生误报
-        - LOW：无影响，仅提示
-        - NONE：完全无关，忽略
-     f) 输出结构化分析报告：
-        用格式化的文本块输出，每行标注影响等级：
-        ```
-        ═══ 工作区状态报告 ═══
-        [HIGH] 子模块 web/ dirty（7 文件）— 与 goal 同一目录，可能干扰
-        [MED]  旧 change contract-ai-rag 残留 — 可能干扰依赖链判断
-        [LOW]  .aiws/journal/ 日志文件 — 无影响
-        ════════════════════════
-        ```
-      g) 展示报告后要求用户选择：
-         - **继续** → 更新 state.json checkpoint `ws_analysis=complete`，进入 step 5
-         - **暂停** → state.json status=paused，报告写入 Audit Trail，结束
-         - **先清理** → state.json status=paused，输出清理建议步骤，结束
-      用户未确认前，不得进入 step 5。
+     策略 SSOT：`ws-goal-contract.md` §2.5.4 — **HIGH → 自动解决，默认不阻断**。
+     a) 检查 dirty / submodule / change artifacts / git 状态（同 skill 扫描项）
+     b) 评估影响等级 NONE/LOW/MED/HIGH
+     c) 输出结构化报告到 Audit Trail
+     d) 按 §2.5.4 自动处理 HIGH（stash / submodule update / 警告后继续等）；仅自动化失败时提示
+     e) 通过后：`aiws goal advance --goal-id <goal-id>`（完成 ws_analysis），进入 step 5
+     f) 可选：用户主动要求暂停 → status=paused（非 HIGH 默认门禁）
+     **禁止**再要求「用户确认 HIGH 后才能进 step 5」作为默认路径。
 
 5) **Phase-Level Pipeline Delegation**：依赖链预检 + workspace 分析通过后，将 goal 拆分为 PLAN→DEV→REVIEW→FINISH 四个 phase 顺序执行，每个 phase 委托给独立轻量子 agent，主 session 验证每个 phase 产出后决定继续/重试/暂停。
      前置条件：step 4 必须通过（ALL HEALTHY 或 UNHEALTHY 已显式放行）。若 step 4 阻断，不允许 delegation。
      前置条件 2：不存在 status=active 的 change 分支。若有，让用户选择「使用已有 change 继续」或「暂停」。
-     前置条件 3：每个 pipeline phase 开始前更新 state.json `current_phase` + checkpoint `status=in_progress`；完成/失败后对应更新 checkpoint。
+     前置条件 3：每个 pipeline phase 验证通过后 **必须** `aiws goal advance --goal-id <goal-id>`（sole writer）；禁止手改 state.json。
 
 5a) **Check for Groups**：读取 goal 文件，检查是否定义了 `Groups` 区域。
     - 若 goal **不含** groups → 走单组 phase-level pipeline（step 5b-5g）
@@ -146,8 +153,8 @@ ws-goal 只做三件事，不做更多：
         - proposal.md 文件存在
         - plan 文件存在
         - plan-verify 通过
-    4. 验证通过 → 进入 PHASE 2
-    5. 验证失败 → 可重试最多 2 次 → 仍失败则 goal state=paused，记录 blocker
+    4. 验证通过 → `aiws goal advance --goal-id <goal-id>` → 进入 PHASE 2
+    5. 验证失败 → 可重试最多 2 次 → 仍失败则暂停并记录 blocker（勿手改 JSON）
 
 5d) **PHASE 2 - DEV**（委托子 agent 做 dev）：
     1. 委托子 agent 执行 DEV phase：
@@ -164,8 +171,8 @@ ws-goal 只做三件事，不做更多：
     2. 主 session 验证产出：
         - diagnostics 干净（`lsp_diagnostics` 检查改动文件）
         - 改动范围与 plan 一致
-    3. 验证通过 → 进入 PHASE 3
-    4. 验证失败 → goal state=paused，记录 blocker
+    3. 验证通过 → `aiws goal advance --goal-id <goal-id>` → 进入 PHASE 3
+    4. 验证失败 → 暂停并记录 blocker（勿手改 JSON）
 
 5e) **PHASE 3 - REVIEW**（委托子 agent 做 review）：
     1. 委托子 agent 执行 REVIEW phase：
@@ -183,8 +190,8 @@ ws-goal 只做三件事，不做更多：
     2. 主 session 验证产出：
         - review 证据文件存在
         - 无未解决的 HIGH blocker
-    3. 验证通过 → 进入 PHASE 4
-    4. 验证失败 → goal state=paused，记录 blocker
+    3. 验证通过 → `aiws goal advance --goal-id <goal-id>` → 进入 PHASE 4
+    4. 验证失败 → 暂停并记录 blocker（勿手改 JSON）
 
 5f) **PHASE 4 - FINISH**（委托子 agent 做 commit + finish）：
     1. 委托子 agent 执行 FINISH phase：
@@ -201,8 +208,8 @@ ws-goal 只做三件事，不做更多：
     2. 主 session 验证产出：
         - 确认 change 分支已合并到 target_base_branch
         - 确认已推送
-    3. 验证通过 → goal state=complete，输出 "Goal <goal-id> complete"
-    4. 验证失败 → goal state=paused，记录 blocker
+    3. 验证通过 → `aiws goal advance --goal-id <goal-id>`（至 complete）→ 输出 "Goal <goal-id> complete"
+    4. 验证失败 → 暂停并记录 blocker（勿手改 JSON）
 
 5g) **Simple Goal Escape Hatch**：若 goal 为简单改动（≤3 文件，配置/doc/规范变更，无架构风险）：
     - 可跳过 PHASE 3（REVIEW），在 PHASE 2 验证后直接进入 PHASE 4

package/templates/workspace/.opencode/commands/ws-goal.md

@@ -0,0 +1,278 @@
+---
+description: 目标协议：设定可审计的 goal 目标；依赖链预检；完成审计
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-goal -->
+# ws goal
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+## 职责边界
+
+ws-goal 只做三件事，不做更多：
+
+| 做 | 不做 |
+|---|---|---|
+| 录入目标（写 `.aiws/goals/<id>.md`） | 直接在 main session 创建/驱动 change（通过 pipeline subagent 委托执行） |
+| 依赖链预检（上游死 change → 阻断） | 评估复杂度、路由执行路径 |
+| 完成审计（claim done 时验证 outcome） | git add/commit/push、finish |
+| 记录 target_base_branch 约束 | auto-chain 到下一个 goal（但在同一 goal 内支持多组顺序调度 §6） |
+
+超出以上范围的需求，路由到对应 ws-* 技能，ws-goal 不碰。
+
+## 前置条件
+
+1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
+
+
+## Phase Boundary Authority (TOOLING-003D / contract §10)
+
+**Sole writer**: `aiws goal advance` is the **only** allowed writer for phase-boundary fields in `.aiws/goals/<goal-id>.state.json` (`status`, `current_phase`, checkpoint transitions).
+
+**MUST after each phase verifies complete**:
+```bash
+aiws goal advance --goal-id <goal-id> [--json]
+aiws goal advance --goal-id <goal-id> --phase <next>   # explicit (prereqs required)
+aiws goal advance --goal-id <goal-id> --heal           # dirty / §7.6 migrate missing state
+aiws goal advance --goal-id <goal-id> --dry-run
+```
+
+**FORBIDDEN**: hand-edit `state.json` to mark complete / start next phase. Dirty → `validate-state --heal` or `advance --heal`, then continue with advance.
+
+**Continuation (WP4)**: After each successful advance, refresh Ralph mirror (primary) and optional Boulder todos (secondary). Ralph/Boulder never write state.json. DONE only when FSM complete + audit. See `opencode-omo-adapter.md` Goal FSM 与续跑边界.
+
+**Allowed**: create initial pending state when defining a goal; read state; write Progress Notes in `.md` (not FSM fields).
+
+
+## 执行流程
+
+0) 检查 `.aiws/goals/` 目录（先扫描 `.state.json`，再扫描 `.md`）：
+   a) 若用户仅查询状态（无明确目标），列出所有 goal 文件及其 status 字段，然后结束。
+   b) 扫描 `.aiws/goals/*.state.json`：
+      - 若发现 status=active 或 status=paused 的 state.json，输出恢复选项（从失败的 phase 继续 / 跳过 / handoff）
+      - 用户选择后设置 current_phase 到对应 phase 并继续执行
+   c) 若未找到 state.json 但有 status=active 或 status=paused 的 .md 文件（旧格式迁移），按 §7.6 自动生成 state.json 后全量重跑
+   d) 若发现 status=complete 的 state.json 但 checkpoints 中仍有未完成项（status != complete）：
+      - 读取对应 `.aiws/goals/<goal-id>.md` 文件，输出 goal 摘要
+      - 列出所有未完成的 checkpoints（status=in_progress/pending/failed 的项）
+      - 输出续跑选项：
+        - （a）跳过 PHASE 0，从依赖链预检（step 4）恢复执行
+            自动跳过 step 1-3（真值读取/目标输入/文件生成），使用已有 goal 文件
+        - （b）查看 goal 详情
+        - （c）忽略，按新目标处理
+      - 若用户选择 a）：
+        - 设置 state.json：status=active，current_phase 到最近一个未完成 checkpoint 对应 phase
+        - 输出"跳过 PHASE 0，从 step 4 依赖链预检恢复"
+        - 直接进入 step 4 继续执行
+      - 若用户选择 b）：输出完整 goal 详情后回到选项
+      - 若用户选择 c）：作为新目标正常走 step 0→1→2 完整流程
+
+1) 读取真值文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`），确认项目规则与边界。
+
+2) 接受用户输入的 goal objective，明确目标范围与验收标准。
+
+3) 按 ws-goal-contract.md 的目标模板生成目标文件，写入 `.aiws/goals/<goal-id>.md`。
+   并同时创建 `.aiws/goals/<goal-id>.state.json`（§7.2 格式），初始状态 `status=active`、`current_phase=intake`、所有 checkpoints pending。
+   a) 生成时填入 `Target Base Branch` 字段：
+      - `target_base_branch`：从当前分支追踪或用户声明确定。默认 `main`
+      - `base_branch_mismatch_action`：默认 `block`
+   b) 生成时填入初始 `Dependency Chain` 字段：
+      - `base_branch`：当前检出分支或用户指定的基分支
+      - `chain`：追溯完整的 change 链到 main
+      - `chain_verified_at`：当前时间
+      - `user_confirmed_unhealthy`：初始为 null
+
+4) **Dependency Chain Validation**：上游依赖链健康检查（不创建任何 change/plan/commit）。
+   a) 确定 base_branch：
+      - 若当前已存在 change 分支，读取 `.ws-change.json` 或 proposal.md 的 `base_branch`
+      - 若用户显式指定 base_branch，以用户指定为准
+      - 否则默认 main
+   a1) **target_base_branch 一致性检查**（Rule C）：
+      - 读取 goal 文件的 `Target Base Branch.target_base_branch`
+      - 若 `base_branch != target_base_branch`：
+        - 输出 "goal 声明 target_base_branch = X，但当前 base_branch = Y"
+        - 若 `base_branch_mismatch_action` 为 `block`（默认）：**强制 blocker**，必须用户修正 base_branch 或显式确认 mismatch 才能继续
+        - 若为 `warn`：输出警告并允许继续
+        - 将 mismatch 记录到 goal 文件的 Audit Trail
+      - 若一致：继续 step b
+   b) 追溯 chain：从 base_branch 逐级向上追溯到 main
+      - 每级检查 `.ws-change.json` 的 `base_branch` 或 git 分支关系
+      - 若无法追溯（孤儿分支），标记 UNKNOWN 并输出警告
+   c) 对 chain 中每个 link 做健康检查（按 ws-goal-contract.md 2.4.2 标准）：
+      - artifacts 完整性：proposal/tasks/design 是否存在
+      - task 完成率：WS:TODO 占比
+      - review 状态：是否有 HIGH blocker
+      - 活跃度：最后更新时间
+      - truth drift：`aiws validate .` 是否通过
+   d) 结果：
+      - ALL HEALTHY → 输出 "依赖链健康" 并继续
+      - 存在 STALE → 输出链拓扑 + 警告，允许继续
+      - 存在 UNHEALTHY → 输出完整 chain 拓扑 + 每级健康报告，**强制 blocker**，必须用户显式确认才能继续
+      - UNKNOWN（无法追溯）→ 输出警告"无法验证上游依赖链"，不阻断但要求用户确认
+   e) 将验证结果写入 goal 文件的 `Dependency Chain` 字段：
+       - 更新 `chain` 中每个 link 的健康状态与判定理由
+       - 若用户放行 UNHEALTHY：设置 `user_confirmed_unhealthy: true` 并记录到 `Audit Trail`
+       - 若用户未放行：设置 goal status=paused 并结束
+
+4.5) **Workspace State Analysis**：依赖链预检通过后、delegation 前，分析工作区状态并输出报告。
+     策略 SSOT：`ws-goal-contract.md` §2.5.4 — **HIGH → 自动解决，默认不阻断**。
+     a) 检查 dirty / submodule / change artifacts / git 状态（同 skill 扫描项）
+     b) 评估影响等级 NONE/LOW/MED/HIGH
+     c) 输出结构化报告到 Audit Trail
+     d) 按 §2.5.4 自动处理 HIGH（stash / submodule update / 警告后继续等）；仅自动化失败时提示
+     e) 通过后：`aiws goal advance --goal-id <goal-id>`（完成 ws_analysis），进入 step 5
+     f) 可选：用户主动要求暂停 → status=paused（非 HIGH 默认门禁）
+     **禁止**再要求「用户确认 HIGH 后才能进 step 5」作为默认路径。
+
+5) **Phase-Level Pipeline Delegation**：依赖链预检 + workspace 分析通过后，将 goal 拆分为 PLAN→DEV→REVIEW→FINISH 四个 phase 顺序执行，每个 phase 委托给独立轻量子 agent，主 session 验证每个 phase 产出后决定继续/重试/暂停。
+     前置条件：step 4 必须通过（ALL HEALTHY 或 UNHEALTHY 已显式放行）。若 step 4 阻断，不允许 delegation。
+     前置条件 2：不存在 status=active 的 change 分支。若有，让用户选择「使用已有 change 继续」或「暂停」。
+     前置条件 3：每个 pipeline phase 验证通过后 **必须** `aiws goal advance --goal-id <goal-id>`（sole writer）；禁止手改 state.json。
+
+5a) **Check for Groups**：读取 goal 文件，检查是否定义了 `Groups` 区域。
+    - 若 goal **不含** groups → 走单组 phase-level pipeline（step 5b-5g）
+    - 若 goal **包含** groups → 走 Sequential Group Phase-Level Dispatch（step 5.1）
+
+--- 以下为 phase-level pipeline（无 groups 的 goal） ---
+
+5b) **Phase-Level Sequential Execution**：主 session 按 PLAN→DEV→REVIEW→FINISH 顺序执行 4 个 phase，每个 phase 前检查当前进度（支持断点续跑）。共用一个 change 分支，change id = goal-id。
+
+5c) **PHASE 1 - PLAN**（主 session 执行 change start + 委托子 agent 做 plan）：
+    1. 主 session 执行 `aiws change start <goal-id> --allow-dirty`（若 change 已存在则跳过）
+    2. 委托子 agent 执行 PLAN phase：
+        ```
+        task(
+          category="unspecified-high",
+          description="PLAN phase for goal <goal-id>",
+          prompt="TASK: Write proposal.md + plan file + run plan-verify for goal <goal-id>.
+                  INPUT: goal file at .aiws/goals/<goal-id>.md, truth files at AI_PROJECT.md/REQUIREMENTS.md/AI_WORKSPACE.md.
+                  CONSTRAINTS: Do NOT implement code. Do NOT do review. Do NOT commit.
+                  COMPLETION: proposal.md exists, plan file exists, plan-verify passes."
+        )
+        ```
+    3. 主 session 验证产出：
+        - proposal.md 文件存在
+        - plan 文件存在
+        - plan-verify 通过
+    4. 验证通过 → `aiws goal advance --goal-id <goal-id>` → 进入 PHASE 2
+    5. 验证失败 → 可重试最多 2 次 → 仍失败则暂停并记录 blocker（勿手改 JSON）
+
+5d) **PHASE 2 - DEV**（委托子 agent 做 dev）：
+    1. 委托子 agent 执行 DEV phase：
+        ```
+        task(
+          category="deep",
+          description="DEV phase for goal <goal-id>",
+          prompt="TASK: Implement all code changes per plan for goal <goal-id>.
+                  INPUT: proposal.md at .aiws/changes/<goal-id>/proposal.md, plan file.
+                  CONSTRAINTS: Do NOT modify proposal or plan files. Do NOT commit.
+                  COMPLETION: All changes implemented, lint/typecheck clean."
+        )
+        ```
+    2. 主 session 验证产出：
+        - diagnostics 干净（`lsp_diagnostics` 检查改动文件）
+        - 改动范围与 plan 一致
+    3. 验证通过 → `aiws goal advance --goal-id <goal-id>` → 进入 PHASE 3
+    4. 验证失败 → 暂停并记录 blocker（勿手改 JSON）
+
+5e) **PHASE 3 - REVIEW**（委托子 agent 做 review）：
+    1. 委托子 agent 执行 REVIEW phase：
+        ```
+        task(
+          category="unspecified-high",
+          load_skills=["review-work"],
+          description="REVIEW phase for goal <goal-id>",
+          prompt="TASK: Audit code changes for goal <goal-id>, produce review evidence.
+                  INPUT: proposal.md, plan file, changed files.
+                  CONSTRAINTS: Do NOT modify code. Do NOT commit.
+                  COMPLETION: Review evidence files exist, no HIGH blockers."
+        )
+        ```
+    2. 主 session 验证产出：
+        - review 证据文件存在
+        - 无未解决的 HIGH blocker
+    3. 验证通过 → `aiws goal advance --goal-id <goal-id>` → 进入 PHASE 4
+    4. 验证失败 → 暂停并记录 blocker（勿手改 JSON）
+
+5f) **PHASE 4 - FINISH**（委托子 agent 做 commit + finish）：
+    1. 委托子 agent 执行 FINISH phase：
+        ```
+        task(
+          category="quick",
+          load_skills=["git-master"],
+          description="FINISH phase for goal <goal-id>",
+          prompt="TASK: Commit and finish (merge + push) for goal <goal-id> change branch.
+                  CONSTRAINTS: Do NOT modify code. Git operations only.
+                  COMPLETION: Change branch merged to target_base_branch and pushed."
+        )
+        ```
+    2. 主 session 验证产出：
+        - 确认 change 分支已合并到 target_base_branch
+        - 确认已推送
+    3. 验证通过 → `aiws goal advance --goal-id <goal-id>`（至 complete）→ 输出 "Goal <goal-id> complete"
+    4. 验证失败 → 暂停并记录 blocker（勿手改 JSON）
+
+5g) **Simple Goal Escape Hatch**：若 goal 为简单改动（≤3 文件，配置/doc/规范变更，无架构风险）：
+    - 可跳过 PHASE 3（REVIEW），在 PHASE 2 验证后直接进入 PHASE 4
+    - 必须在 goal 文件的 Progress Notes 标注 "skipped review phase (simple goal)"
+
+--- 以下为 Sequential Group Phase-Level Dispatch（含 groups 的 goal） ---
+
+5.1) **Sequential Group Phase-Level Dispatch**：
+     当 goal 文件包含 Groups 定义时，ws-goal 按依赖顺序逐个调度每个 group，每个 group 内按 5c-5f 的 4-phase 流程执行。主 session 负责编排每个 group 的 4 个 phase 并验证每个 phase 的产出。
+
+5.1a) **解析并验证 groups**：
+     - 提取 goal 文件中所有 group 定义（id, scope, verification, depends_on, status）
+     - 验证 DAG：无循环依赖，depends_on 引用正确的已知 group
+     - 将所有 group status 初始化为 `pending`
+     - 若解析失败（格式错误、循环依赖）→ 输出错误，不允许 delegation
+
+5.1b) **计算拓扑顺序**：
+     - 按 depends_on 确定执行顺序。默认：声明顺序
+     - 输出 group 执行计划列表：
+       ```
+       ═══ Group 执行计划 ═══
+       [1] group-1: Foundation Pages（depends_on: none）
+       [2] group-2: Purchase Conversion（depends_on: group-1）
+       [3] group-3: Account & Orders（depends_on: group-1）
+       ═══════════════════════════
+       ```
+     - 展示计划后要求用户确认是否继续。用户确认后才开始调度
+
+5.1c) **按顺序执行每个 group（phase-level）**：
+     FOR each group in 拓扑顺序：
+       1. 更新 group status → `in_progress`，写入 goal 文件 Progress Notes
+       2. **PHASE 1 - PLAN**（同 5c，但 change id = `<goal-id>-<group-id>`）：
+          - 主 session 执行 `aiws change start <goal-id>-<group-id> --allow-dirty`
+          - 委托子 agent 写 proposal.md + plan 文件 + plan-verify
+          - 主 session 验证：proposal/plan 存在，plan-verify 通过
+       3. **PHASE 2 - DEV**（同 5d，scope 限定到当前 group）：
+          - 委托子 agent 按 plan 实现当前 group 的代码改动
+          - 主 session 验证：diagnostics 干净，改动匹配 group scope
+       4. **PHASE 3 - REVIEW**（同 5e，scope 限定到当前 group）：
+          - 委托子 agent 审计当前 group 改动
+          - 主 session 验证：review 证据存在，无 HIGH blocker
+       5. **PHASE 4 - FINISH**（同 5f）：
+          - 委托子 agent 做 commit + finish
+          - 主 session 验证：分支已合并推送
+       6. 任一 phase 失败 → group status = paused/failed，记录 blocker，**STOP**（后续 group 不再调度）
+       7. 全部 phase 通过 → 更新 group status → `complete`，更新 Progress Notes
+          - 若 goal 配置了多组并行：可在 PLANNING 通过且 DAG 无冲突前提下的顺序执行
+
+5.1d) **所有 group 完成后**：
+     - 运行整体完成审计：
+       - goal 级别的 outcome 是否满足
+       - 所有 group 均为 complete（无 paused/failed）
+       - 全局 lint/type 检查无新增错误
+       - 输出每 group 结果 + 整体结论
+     - 全部通过 → 更新 goal state=complete，输出 "Goal <id> complete（<N> groups executed）"
+     - 有未通过 → 更新 goal state=paused
+
+5.1e) **恢复机制**（下一 session 进入 step 0 时触发）：
+     - 检测到 paused goal 且含 groups → 输出恢复选项：
+       - （a）重试失败的 group（从失败的 phase 重新开始）
+       - （b）跳过该 group（标记 complete，继续下游）
+       - （c）暂停并 handoff
+     - 用户选择后执行对应操作
+<!-- AIWS_MANAGED_END:opencode:ws-goal -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。