@aipper/aiws-spec 0.0.47 → 0.0.49

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.47",
+  "version": "0.0.49",
   "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`）：
@@ -94,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）
@@ -160,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：
@@ -178,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：
@@ -197,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：
@@ -215,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

@@ -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`）：
@@ -94,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）
@@ -160,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：
@@ -178,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：
@@ -197,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：
@@ -215,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