@aipper/aiws-spec 0.0.27 → 0.0.29

package/docs/cli-interface.md

@@ -67,6 +67,9 @@
 接口（仅定义）：
 - `aiws update [path]`
 
+兼容升级：
+- 若工作区缺失 `.aiws/manifest.json`，但已具备旧版 AIWS workspace 真值文件（例如 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 与 gate 脚本），`aiws update` 应视为“旧版升级”，允许补写 manifest 并刷新模板，而不是一律要求重新 `init`。
+
 ## `aiws rollback`
 
 语义：
@@ -80,6 +83,7 @@
 语义（强门禁）：
 - 缺 `python3` 或缺 required 脚本直接失败（退出码非 0）。
 - `.aiws/manifest.json` 若仍为占位（含 `<sha256>` / epoch 时间戳等）必须失败（退出码 `2`），提示先运行 `aiws init`。
+- 若缺失 `.aiws/manifest.json`，且可识别为旧版 AIWS workspace，应失败并明确提示先运行一次 `aiws update .` 完成升级，再重新 `validate`；不要把这种场景误报成“从未 init”。
 - 可选：开启 stamping（证据落盘）：
   - 方式 A：`aiws validate [path] --stamp`
   - 方式 B：设置环境变量 `AIWS_VALIDATE_STAMP=1` 后执行 `aiws validate [path]`
@@ -215,8 +219,8 @@
   - `@aipper/aiws-spec/docs/workflow-review-gates.json`（dual review / finish gate 真值）
 - 阶段推断约束：
   - `currentStage/recommendedStage` 必须来自共享 change 状态，而不是 dashboard 单独猜测
-  - 若存在独立 `change/<id>` worktree，优先读取该 worktree 的 `git status`
-  - 若 worktree 元数据已 stale，不应导致 API/UI 失败；应返回 warning 并回退到当前 worktree
+  - `git status` 优先读取 change 分支所在工作目录
+  - 若分支元数据已 stale，不应导致 API/UI 失败；应返回 warning 并回退到当前工作目录
   - 至少区分 `ws-review` / `ws-commit` / `ws-deliver` / `ws-finish` / `ws-handoff`
 - 页面应至少展示：
   - change 列表、tasks 进度、truth drift、strict blockers
@@ -238,7 +242,7 @@ Dashboard API（本地只读）：
     - `rationale`
     - `ruleId`
     - `source`
-    - `warning`（可选；例如 stale worktree metadata）
+    - `warning`（可选；例如 stale 分支元数据）
 - `GET /api/workflow-stages`
   - 返回从 spec 真值读取的 workflow stage contracts
 - `GET /api/change/<id>/validate?strict=1`
@@ -275,21 +279,16 @@ Dashboard API（本地只读）：
 
 语义：
 - 默认行为：切分支到 `change/<change-id>`（存在则切换；不存在则创建）；若仓库存在 `.gitmodules`，只切 superproject，本次不会递归切换 submodules。
-- 若检测到 `.gitmodules`（git submodules）且未显式指定 `--switch/--no-switch/--worktree`：默认优先采用 `--worktree`（避免切走 superproject 分支导致 submodule 状态混乱）；若不满足 `--worktree` 前置条件则回退为 `--no-switch`。
+- 若检测到 `.gitmodules`（git submodules）：默认采用 `--switch`（仅切 superproject 分支，不递归切换 submodule）。
 - 若 `changes/<change-id>/` 不存在：等价执行 `aiws change new ...`。
 - 可选：`--hooks` 等价于 `aiws hooks install .`。
 - 可选：`--switch` 显式允许切换 superproject 分支（仅在存在 `.gitmodules` 时有意义；否则等价于默认行为）。
   - 实现细节：当存在 `.gitmodules` 且使用 `--switch` 时，CLI 只切 superproject 分支；submodules 保持当前状态，由 `ws-pull` / `ws-finish` 再统一挂回 `aiws/pin/<target-branch>`。
 - 可选：`--no-switch` 不切换当前分支（仅确保目标分支存在，并初始化变更工件）；适用于 superproject + submodule 场景，避免意外切换 A 目录分支导致 submodule 状态混乱。
-- 可选：`--worktree` 使用 `git worktree` 创建一个独立工作区并在其中 checkout `change/<change-id>`，当前目录分支保持不变（推荐用于 superproject + submodule）。
 - 当 `.gitmodules` 存在时，submodule 的 detached HEAD 恢复应统一使用 `aiws/pin/<target-branch>`；不要把 submodule 切到 `change/<change-id>`。
-  - 默认 worktree 目录：`../<repo-name>-<change-id>`（相对于 git root）
-  - 可选：`--worktree-dir <path>` 覆盖 worktree 目录（推荐放在仓库外；相对路径按 `../` 作为基准理解）
-  - 可选：`--submodules` 在 worktree 内执行 `git submodule update --init --recursive`（避免新 worktree 下 submodule 目录为空）
-- 约束：`--worktree` 与 `--no-switch` 互斥。
 
 接口（仅定义）：
-- `aiws change start <change-id> [--title <title>] [--no-design] [--hooks] [--no-switch] [--switch] [--worktree] [--worktree-dir <path>] [--submodules]`
+- `aiws change start <change-id> [--title <title>] [--no-design] [--hooks] [--no-switch] [--switch]`
 
 ### `aiws change finish`
 
@@ -304,7 +303,6 @@ Dashboard API（本地只读）：
   - `changes/<id>/review/quality-review.md`
   - `.agentdocs/tmp/aiws-validate/*.json`
   - `changes/<id>/evidence/verify-before-complete.md`
-- worktree 场景：若目标分支正在其它 worktree 被 checkout，会提示到对应 worktree 执行。
 - 生命周期语义：
   - 本地 merge 成功但 push / cleanup 未完成时，只记为“finish 已开始”，治理阶段仍停留在 `ws-finish`
   - 若 `--push` 后只完成了 push、但 cleanup 仍未完成，命令应返回非 0，并记录 `finish_cleanup_pending` 以提示修复后重跑
@@ -396,7 +394,7 @@ Dashboard API（本地只读）：
   - collaboration 统计至少包含 `analysis` / `patches` / `review` / `evidence_dir`。
   - 若 review 仅来自 tmp fallback，应额外输出有效 review signal（如 `review_signal: effective=1 source=tmp_fallback`）。
   - 应显式输出 review gate 状态，至少覆盖：`spec_review` / `quality_review` / `validate_stamp` / `verify_before_complete`。
-  - 若 change worktree metadata 已 stale，应输出 warning 并提示 `git worktree prune`。
+  - 若 change 分支元数据已 stale，应输出 warning。
 - `next`：
   - 基于 blockers / 未完成任务 / collaboration 工件给出下一步建议。
   - 若存在委托 patch 草案，应提示“先人工审查，不要视为已自动应用”。

package/docs/opencode-autonomous-swarm.md

@@ -0,0 +1,178 @@
+# OpenCode/oMo Autonomous Swarm
+
+目标：为 OpenCode + `oh-my-opencode` 提供一层**实验性**自主协作适配，让“尽量无人值守直到任务完成”有可审计的合同、示例配置与安全边界。
+
+## 定位
+
+- `aiws`：继续负责 workflow contract、artifact convention、review gate、completion contract。
+- oMo：继续负责 agent harness、background tasks、session continuity、hooks 与 runtime orchestration。
+- tmux helper：作为**可选**外部协助层，提供巡检与安全救援；不升格为 AIWS 核心 runtime。
+- approval whitelist policy：作为**项目级策略声明**，定义“哪些操作可被外部 helper 自动放行”，但不直接接管宿主权限弹窗。
+
+## Execution Mode
+
+允许的执行模式：
+
+- `single-agent`
+  - 未启用 oMo，或明确选择不用 autonomous 辅助。
+- `omo-native`
+  - 已启用 oMo；使用 `prompt_append`、`backgroundTasks`、`experimental.auto_resume` 与 hooks 兼容层推进任务。
+- `omo-native + tmux-swarm`
+  - 在 `omo-native` 基础上，额外启用 `.opencode/helpers/tmux-swarm-*.sh` 做外部巡检/救援。
+
+## Completion Contract
+
+“完成”至少同时满足：
+
+- 已读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 已绑定 `Req_ID` / `Problem_ID` / `change`
+- 已产出当前阶段要求的工件
+- 已执行最小验证，且结果被写入 evidence
+- 若适用：`aiws validate .` 或 `aiws change validate --strict` 已通过
+- review / evidence 已落盘到 `changes/<id>/...` 或 `.agentdocs/tmp/...`
+
+若不满足上述条件，不应宣称“已完成”并停止。
+
+## Retry Contract
+
+自动回跳只允许在既有 AIWS 阶段语义内进行：
+
+- `ws-plan-verify` 失败 -> 回到 `ws-plan`
+- `ws-review` 发现 blocker -> 回到 `ws-dev`
+- `validate` 失败且可修复 -> 回到 `ws-dev`
+
+约束：
+
+- 必须保留 `retry_count`
+- 达到熔断阈值后停止自动重试
+- 最后一次失败摘要必须写入 evidence
+
+## Approval Whitelist Policy
+
+当你希望把“读文件 / 写 evidence”这类低风险动作尽量自动放行时，建议在项目级 oMo 配置中显式声明一份 approval whitelist policy。
+
+建议最小范围：
+
+- `read_only_commands`
+  - 只允许仓库内只读命令，例如 `rg`、`cat`、`sed`、`ls`、`find`、`git status`、`git diff`
+- `write_allow_paths`
+  - 只允许写入 AIWS 约定的证据路径：
+    - `.agentdocs/tmp/`
+    - `changes/*/analysis/`
+    - `changes/*/review/`
+    - `changes/*/evidence/`
+- `deny_paths`
+  - 显式拒绝敏感路径，例如 `secrets/`、`.env*`
+- `deny_commands`
+  - 显式拒绝高风险命令，例如 `rm`、`mv`、`git commit`、`git push`、`npm publish`
+- `host_permission_mode`
+  - 固定为 `manual-only`
+  - 表示宿主工具的真实提权 / sandbox / 系统级权限申请仍需人工确认
+
+注意：
+
+- 这份 policy 是给外部 helper / hook / 审计流程消费的声明，不代表 AIWS 本身已经拥有“自动批准宿主权限”的能力。
+- 若命中 `deny_paths` / `deny_commands`，或需要宿主提权，必须停止自动流程并交还人工确认。
+
+## Rescue Contract
+
+tmux swarm 只允许做**安全白名单**救援：
+
+- 发现 `(y/n)` 提示时发送 `y` + `Enter`
+- 发现 `Press Enter to continue` 时发送 `Enter`
+- 发现 pane 处于 copy-mode 时执行 `send-keys -X cancel`
+- 先 `capture-pane` 审核，再允许发送按键
+- 所有动作必须写入审计日志
+
+禁止：
+
+- blind `Ctrl+C`
+- blind 广播 shell 命令
+- 自动 `git commit` / `git push`
+- 删除文件或执行破坏性命令
+
+## 推荐配置
+
+模板提供以下文件：
+
+- `.opencode/oh-my-opencode.json.example`
+- `.claude/settings.json.example`
+- `.opencode/skills/ws-auto/SKILL.md`
+- `.opencode/helpers/tmux-swarm-scan.sh`
+- `.opencode/helpers/tmux-swarm-rescue.sh`
+- `.opencode/helpers/approval-whitelist-check.sh`
+- `.opencode/helpers/approval-whitelist-run.sh`
+- `.opencode/helpers/approval-whitelist-watchdog.sh`
+
+说明：
+
+- `.opencode/oh-my-opencode.json.example` 负责声明 agent、`prompt_append`、`backgroundTasks`、`experimental.auto_resume`
+- `.opencode/oh-my-opencode.json.example` 也可声明 `aiws.autonomy.approval_whitelist`
+- `/ws-auto` 与 `aiws opencode auto .` 负责把“需要 update 吗 / watchdog 能否启动”这类 bootstrap 检查前置掉
+- `.claude/settings.json.example` 只作为 hook 兼容层示例，不充当 controller
+- `approval-whitelist-check.sh` 负责把项目级 whitelist policy 转成 `allow` / `deny` / `manual` 判定，并写审计日志
+- `approval-whitelist-run.sh` 负责在 `allow` 场景下执行简单命令，并写执行摘要
+- `approval-whitelist-watchdog.sh` 负责轮询 JSONL 队列，串行调用 runner，并写 watchdog 状态/结果
+- `aiws opencode supervise .` 是显式启动入口：若当前已在 tmux session 内，就补一个 watchdog window；否则为当前工作区起一个 detached tmux session
+- tmux helper 是可选层，仅在用户明确接受 `tmux` 依赖时启用
+
+## `ws-autonomy`
+
+OpenCode 实验入口：`/ws-autonomy`
+
+职责：
+
+- 声明 `Execution Mode`
+- 声明 `Completion Contract`
+- 声明 `Retry Contract`
+- 声明 `Rescue Policy`
+- 指向 evidence 路径
+
+不负责：
+
+- 直接接管 oMo runtime
+- 直接替代 `ws-plan` / `ws-dev` / `ws-review`
+- 越权写盘
+- 自动批准宿主工具的真实权限弹窗
+
+## `ws-auto`
+
+OpenCode bootstrap 入口：`/ws-auto`
+
+职责：
+
+- 先跑 preflight
+- 触发 `aiws opencode auto .`
+- 必要时先刷新 AIWS 托管内容
+- 在条件满足时显式确保 watchdog 已运行
+- 给出下一步 route
+
+不负责：
+
+- 自动启用 `.opencode/oh-my-opencode.json`
+- 自动批准宿主工具的真实权限弹窗
+- 自动执行 tmux rescue
+
+## Evidence
+
+建议使用：
+
+- 临时状态：`.agentdocs/tmp/opencode-autonomy/current-run.json`
+- whitelist 判定：`.agentdocs/tmp/opencode-autonomy/approval-whitelist-last.json`
+- whitelist 审计日志：`.agentdocs/tmp/opencode-autonomy/approval-whitelist.log`
+- whitelist 执行摘要：`.agentdocs/tmp/opencode-autonomy/approval-whitelist-exec-last.json`
+- whitelist 执行日志：`.agentdocs/tmp/opencode-autonomy/approval-whitelist-exec.log`
+- watchdog 队列：`.agentdocs/tmp/opencode-autonomy/approval-watchdog-queue.jsonl`
+- watchdog 状态：`.agentdocs/tmp/opencode-autonomy/approval-watchdog-state.json`
+- watchdog 结果：`.agentdocs/tmp/opencode-autonomy/approval-watchdog-results.jsonl`
+- watchdog 日志：`.agentdocs/tmp/opencode-autonomy/approval-watchdog.log`
+- tmux 巡检：`.agentdocs/tmp/opencode-autonomy/tmux-scan.json`
+- tmux 救援日志：`.agentdocs/tmp/opencode-autonomy/tmux-rescue.log`
+- 持久 evidence：`changes/<id>/evidence/`
+
+## 边界提醒
+
+- 本能力是 OpenCode/oMo 优先的实验层，不代表 AIWS 已经转向“pane / session orchestration 产品”。
+- approval whitelist 只声明项目边界，不等于宿主权限自动批准器。
+- `aiws opencode supervise .` 只是显式 ensure watchdog 的启动器，不会自动批准 host permission，也不会自动执行 tmux rescue。
+- 若未来工具原生能力变化，优先更新 example config、status readiness 与 helper，而不是把 runtime 逻辑硬编码进核心 workflow 真值。

package/docs/opencode-omo-adapter.md

@@ -21,11 +21,13 @@
 
 CLI 辅助探测：
 - 可在项目根运行 `aiws opencode status .`
-- 该命令只做探测与提示，不接管 OpenCode / oMo 的运行时编排
+- 若你想一条命令做 bootstrap + update 检查 + watchdog ensure：`aiws opencode auto .`
+- 如需由 `aiws` 显式确保 watchdog 已在 tmux 中运行：`aiws opencode supervise .`
+- `aiws opencode status .` 只做探测与提示，不接管 OpenCode / oMo 的运行时编排
 
 ## 推荐项目级配置
 
-若你希望按项目把 oMo agent 集合与 AIWS workflow 对齐，建议只做最小 `agents` override，不接管 hooks / MCP / LSP。
+若你希望按项目把 oMo agent 集合与 AIWS workflow 对齐，建议保持最小配置面：agent + autonomy 必要字段，不接管 hooks / MCP / LSP。
 
 模板建议文件：
 - `packages/spec/templates/workspace/.opencode/oh-my-opencode.json.example`
@@ -37,7 +39,8 @@ CLI 辅助探测：
   "agents": {
     "planner-sisyphus": {
       "enabled": true,
-      "replace_plan": false
+      "replace_plan": false,
+      "prompt_append": "<AIWS completion contract>"
     },
     "librarian": {
       "enabled": true
@@ -48,15 +51,127 @@ CLI 辅助探测：
     "oracle": {
       "enabled": true
     }
+  },
+  "backgroundTasks": {
+    "enabled": true,
+    "maxJobs": 3,
+    "defaultTimeoutMs": 1200000
+  },
+  "experimental": {
+    "auto_resume": true
+  },
+  "aiws": {
+    "autonomy": {
+      "approval_whitelist": {
+        "enabled": true,
+        "mode": "assist-only",
+        "host_permission_mode": "manual-only",
+        "read_only_commands": [
+          "rg",
+          "cat",
+          "sed",
+          "ls",
+          "find",
+          "git status",
+          "git diff"
+        ],
+        "write_allow_paths": [
+          ".agentdocs/tmp/",
+          "changes/*/analysis/",
+          "changes/*/review/",
+          "changes/*/evidence/"
+        ],
+        "deny_paths": [
+          "secrets/",
+          ".env*"
+        ],
+        "deny_commands": [
+          "rm",
+          "mv",
+          "git commit",
+          "git push",
+          "npm publish"
+        ]
+      }
+    }
   }
 }
 ```
 
 说明：
 - `replace_plan=false` 是保守默认，避免项目级配置直接替换掉 OpenCode 默认 `plan` 行为。
-- 这份示例的目的只是让 `ws-plan` / `ws-review` / `ws-spec-review` / `ws-quality-review` / `ws-delegate` 有稳定的优先 agent 可用。
+- 这份示例的目的不仅是提供稳定 agent，也为 `ws-autonomy` 准备 `prompt_append` / `backgroundTasks` / `auto_resume`。
+- `aiws.autonomy.approval_whitelist` 是项目级策略声明，只定义可自动放行的低风险操作范围，不自动批准宿主提权。
 - 若你已经在用户级配置里启用了这些 agent，项目级配置可以不写。
 
+## 自主协作实验层（Autonomous Swarm）
+
+当你希望 OpenCode 尽量无人值守地持续推进任务时，建议把 AIWS 的要求前移到 oMo 配置与 hook 兼容层，而不是让 `aiws` 自己变成 runtime orchestrator。
+
+推荐最小组合：
+
+- `.opencode/oh-my-opencode.json`
+  - `planner-sisyphus.prompt_append`：写入 AIWS completion contract
+  - `backgroundTasks`：只用于 analysis / review / doc-search 型并行任务
+  - `experimental.auto_resume=true`
+  - `aiws.autonomy.approval_whitelist`：只声明只读命令与 evidence 写路径白名单；宿主权限仍是 `manual-only`
+- `.claude/settings.json.example`
+  - 作为 oMo 可读取的 hook 兼容层示例
+- `.opencode/helpers/tmux-swarm-scan.sh`
+  - 巡检当前 tmux panes，输出状态摘要
+- `.opencode/helpers/tmux-swarm-rescue.sh`
+  - 只执行安全白名单救援
+- `.opencode/helpers/approval-whitelist-check.sh`
+  - 把 `approval_whitelist` 策略转成命令级 `allow` / `deny` / `manual` 判定
+- `.opencode/helpers/approval-whitelist-run.sh`
+  - 先调用 checker；只有 `allow` 才以非 shell 模式执行简单命令，并写执行摘要
+- `.opencode/helpers/approval-whitelist-watchdog.sh`
+  - 轮询 `approval-watchdog-queue.jsonl`，把外部蜂群写入的待执行项交给 runner
+- `/ws-auto`
+  - OpenCode 侧的 bootstrap skill；会优先触发 `aiws opencode auto .`
+- `aiws opencode auto .`
+  - 显式检查是否需要 `aiws update .`，并在条件满足时继续 ensure watchdog
+- `aiws opencode supervise .`
+  - 显式确保 watchdog 已在 tmux 中运行；若当前不在 tmux，则为工作区创建一个 detached session
+
+边界：
+
+- `ws-autonomy` 只声明合同与路径，不替代 `ws-plan` / `ws-dev` / `ws-review`
+- tmux helper 只是可选外部辅助层，不升格为 AIWS 核心 runtime
+- blind pane control、自动 commit/push、未知命令广播都不属于该实验层
+- 宿主工具的真实权限申请不属于自动批准范围
+
+示例：
+
+```bash
+bash .opencode/helpers/approval-whitelist-check.sh . \
+  --kind read \
+  --command "cat .opencode/oh-my-opencode.json"
+
+bash .opencode/helpers/approval-whitelist-check.sh . \
+  --kind write \
+  --command "node scripts/collect-evidence.mjs" \
+  --path "changes/demo/evidence/run.json"
+
+bash .opencode/helpers/approval-whitelist-check.sh . \
+  --kind host-permission \
+  --command "sudo npm install"
+
+bash .opencode/helpers/approval-whitelist-run.sh . \
+  --kind read \
+  --command "cat .opencode/oh-my-opencode.json"
+
+printf '%s\n' \
+  '{"id":"read-config","kind":"read","command":"cat .opencode/oh-my-opencode.json"}' \
+  >> .agentdocs/tmp/opencode-autonomy/approval-watchdog-queue.jsonl
+
+bash .opencode/helpers/approval-whitelist-watchdog.sh . --once
+
+aiws opencode auto .
+
+aiws opencode supervise .
+```
+
 ## 角色映射
 
 `aiws` 的治理角色与 oMo agent 的推荐映射如下：
@@ -127,9 +242,13 @@ CLI 辅助探测：
   - `changes/<id>/patches/`
   - `changes/<id>/review/`
   - `changes/<id>/evidence/`
+- 若启用了 autonomy helper：
+  - 临时状态允许写入 `.agentdocs/tmp/opencode-autonomy/`
+  - 最终结论仍必须收敛到 `changes/<id>/...` 或 `.agentdocs/tmp/review/...`
 
 ## 非目标
 
 - 不由 `aiws` 接管 `.opencode/oh-my-opencode.json` 的完整配置。
 - 不由 `aiws` 覆盖 oMo 的 hooks、session recovery、compaction 或 agent harness。
 - 不要求 skill 一定“自动调起” oMo 的全部 agent；只要求写清优先顺序与回退策略。
+- 不把 tmux pane/session orchestration 升格为跨工具核心真值。

package/docs/opencode-omo-validation-checklist.md

@@ -82,6 +82,53 @@ aiws opencode status .
    - skill 文案明确进入 fallback，而不是宣称 `aiws` 自己接管调度
    - 产物仍统一落盘到 `changes/<id>/analysis/`、`patches/`、`review/`、`evidence/`
 
+## 场景 E：自主协作实验层
+
+1. 在项目内启用：
+```bash
+cp .opencode/oh-my-opencode.json.example .opencode/oh-my-opencode.json
+test -f .claude/settings.json.example
+test -f .opencode/helpers/approval-whitelist-check.sh
+test -f .opencode/helpers/approval-whitelist-run.sh
+test -f .opencode/helpers/approval-whitelist-watchdog.sh
+test -f .opencode/helpers/tmux-swarm-scan.sh
+test -f .opencode/helpers/tmux-swarm-rescue.sh
+```
+2. 运行：
+```bash
+aiws opencode status .
+aiws opencode auto . --once
+aiws opencode supervise . --once
+```
+3. 预期：
+   - 输出 `background_tasks:`、`auto_resume:`、`claude_hooks_example:`、`tmux_helpers:`
+   - 若示例配置完整：输出 `planner-sisyphus.prompt_append: configured`
+   - 输出 `approval_whitelist:` 与 `host_permission_mode: manual-only`
+   - `aiws opencode auto . --once` 会先检查是否需要 `aiws update .`，再在条件满足时输出 watchdog bootstrap 结果
+   - `aiws opencode supervise . --once` 会输出 tmux session / watchdog window 信息，且不会宣称自动批准 host permission
+4. helper 验证：
+```bash
+bash .opencode/helpers/approval-whitelist-check.sh . --kind read --command "rg approval_whitelist packages/spec"
+bash .opencode/helpers/approval-whitelist-run.sh . --kind read --command "cat .opencode/oh-my-opencode.json"
+printf '%s\n' '{"id":"read-config","kind":"read","command":"cat .opencode/oh-my-opencode.json"}' >> .agentdocs/tmp/opencode-autonomy/approval-watchdog-queue.jsonl
+bash .opencode/helpers/approval-whitelist-watchdog.sh . --once
+```
+5. 预期：
+   - 两次都输出 JSON，包含 `decision=allow` 或等价字段
+   - `approval-whitelist-run.sh` 额外包含 `executed=true`
+   - watchdog 会更新 `approval-watchdog-state.json` 与 `approval-watchdog-results.jsonl`
+   - `.agentdocs/tmp/opencode-autonomy/approval-whitelist-last.json`、`approval-whitelist.log`、`approval-whitelist-exec-last.json` 与 `approval-whitelist-exec.log` 被更新
+6. 在 OpenCode 中执行：
+   - `/ws-auto`
+   - `/ws-autonomy`
+7. 预期：
+   - `/ws-auto` 会先做 bootstrap，并把 update/watchdog 结果收敛成 `Auto Bootstrap:` / `Watchdog:`
+   - 输出 `Execution Mode:`
+   - 输出 `Completion Contract:`
+   - 输出 `Retry Contract:` / `Rescue Policy:`
+   - 不宣称能自动批准宿主 sandbox / 提权弹窗
+   - 明确这是实验层，不接管 runtime controller
+
 ## 记录建议
 
 - 将本次人工验收结论落盘到：

package/docs/opencode-subagent-first.md

@@ -0,0 +1,187 @@
+# OpenCode Subagent-First Execution
+
+<!-- Managed by aiws. Do not hand edit. -->
+
+**规范 ID**: `opencode-subagent-first`
+**版本**: 1
+
+## 目的
+
+定义 OpenCode 环境中 subagent-first 的默认执行纪律，将主 session 的角色从"实现者"转变为"协调者/集成者"，实现更接近 Trellis/Superpowers 执行纪律的轻量级持续循环。
+
+## 核心原则
+
+1. **Subagent-first**: 实现工作默认由 `aiws-worker` subagent 完成，主 session 负责 context curation、dispatch、review convergence 与 escape hatch 记录。
+2. **Review loop**: 每个 worker dispatch 后至少经过一次审查（`aiws-reviewer` 或 `ws-quality-review`），审查未通过则修复后再审查。
+3. **Continuous**: 主 session 不主动中断工作流去问"下一步做什么"——除非遇到 BLOCKED/NEEDS_CONTEXT 或所有任务完成。
+4. **Explicit override**: 允许用户显式声明 inline 模式，但必须记录理由。
+
+## 执行循环（Continuous Loop）
+
+### 标准循环
+
+```text
+主 session 策划上下文（JSONL curation）
+  → dispatch aiws-worker（带 curated context）
+  → worker 返回 DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
+  → 若 DONE → dispatch aiws-reviewer（审查实现）
+  → 若 reviewer pass → 收敛 evidence，准备 ws-finish
+  → 若 reviewer fail → 返回 worker 修复（最多 3 次循环）
+  → 若 DONE_WITH_CONCERNS → 先 ws-quality-review 评估残余风险
+  → 若 NEEDS_CONTEXT → 补充上下文重试（最多 2 次）
+  → 若 BLOCKED → 停止，输出 blocker 详情
+```
+
+### Worker dispatch
+
+Worker dispatch 必须包含：
+- curated JSONL context file (`changes/<id>/analysis/worker-context.jsonl`)
+- 明确的任务描述与 scope 边界
+- 期望的报告格式（四状态 + 文件清单 + 验证命令）
+
+Worker 报告格式：
+
+```text
+**Status:** DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+**Completed:** 实现内容摘要
+**Files Changed:** 文件清单
+**Verification:** 运行的命令 + 结果
+**Artifacts:** changes/<id>/analysis|patches|evidence 下的路径
+**Concerns:** 疑虑、未完成项（若有）
+```
+
+### Reviewer dispatch
+
+Reviewer dispatch 必须包含：
+- worker 产出的 patches/evidence 路径
+- 审查范围（spec review、quality review 或两者）
+- 期望的报告格式
+
+Reviewer 接收的是**工作产物**（patch、evidence、analysis），不是主 session 的会话历史。
+
+### 停止条件
+
+连续执行在以下条件停止：
+- **BLOCKED**: 治理规则阻断（缺工件、dirty 工作区、validate 失败等）
+- **NEEDS_CONTEXT** 超过 2 次重试上限
+- 验证命令缺失或失败
+- 需要 host permission / manual approval
+- 用户明确要求改变 scope
+- 所有任务完成，evidence 已收敛
+
+### Inline Escape Hatch
+
+当用户**在当前消息中**显式包含以下短语之一时，主 session 可直接写实现代码：
+- "直接改" / "do it inline" / "你直接改"
+- "别派 sub-agent" / "main session 写就行"
+- "不用 sub-agent" / "no sub-agent"
+
+**规则**：
+- 必须由用户**当前**消息触发，不能是"上一条说过"或"上轮说过"
+- 主 session 不得自行推断 inline 模式
+- 使用 inline 后必须落盘 evidence 记录理由
+- 记录到 `changes/<id>/evidence/inline-escape-hatch.md`
+
+### 与 Trellis/Superpowers 对比
+
+| 特性 | Trellis | Superpowers | aiws (Subagent-First) |
+|------|---------|-------------|----------------------|
+| 默认实现者 | sub-agent (`trellis-implement`) | sub-agent (implementer) | sub-agent (`aiws-worker`) |
+| 默认审查者 | sub-agent (`trellis-check`) | spec-reviewer + quality-reviewer | `aiws-reviewer` |
+| 主 session 角色 | coordinator + commit | coordinator + dispatch | coordinator + convergence |
+| Inline override | 显式短语 | 显式短语 | 显式短语 |
+| 连续执行 | 是（不主动停顿） | 是（不主动停顿） | 是（不主动停顿） |
+| 停止条件 | blocked / NEEDS_CONTEXT / done | blocked / NEEDS_CONTEXT / done | blocked / NEEDS_CONTEXT / done / missing verify |
+
+## Context 纪律
+
+### JSONL Curated Context
+
+每个 worker dispatch 前，主 session 必须为其策划上下文 JSONL 文件：
+
+1. **读取合同基线**: 从 `workflow-delegation-contracts.json` 中对应角色的 `contextFiles` 条目
+2. **展开并填充**: 将 `<id>` 替换为实际 change-id，将 glob 模式展开为具体路径
+3. **委托者调整**: 添加任务特定文件，删除不相关条目，调整 priority/sections
+4. **预算检查**: 确保 high+medium ≤ 5 文件，总行数 ≤ 4000
+5. **写入 JSONL**: 写入 `changes/<id>/analysis/<role>-context.jsonl`
+
+详见 `workflow-delegation-context-injection.md`。
+
+### Reviewer 上下文
+
+Reviewer 接收的上下文应该是**工作产物**，不是主 session 的完整历史：
+- worker 产出的 patches
+- 相关 evidence
+- 对应的分析文件
+- 委托合同与 scope 边界
+
+### 主 session 不需要的上下文
+
+主 session 不应在 dispatch 时携带的：
+- 子 agent 的工作细节（这是子 agent 自己的事）
+- 完整的会话历史
+- 不相关的 analysis/evidence 文件
+
+## 子 agent 四状态协议
+
+| 状态 | 含义 | 后续动作 |
+|------|------|----------|
+| `DONE` | 任务完成 + 验证通过 + 证据路径有效 | 进入 review；若已过 review 则准备 ws-finish |
+| `DONE_WITH_CONCERNS` | 实现完成但质量有残余风险 | 先 ws-quality-review，根据结果决定是否阻断 |
+| `NEEDS_CONTEXT` | 缺关键上下文 | 主 agent 补充后重试（最多 2 次）；仍失败则回退单 agent |
+| `BLOCKED` | 治理规则阻断 | 停止委托流程；主 agent 解 blocker 后重试 |
+
+## Worker → Reviewer → Fix 循环
+
+```text
+[dispatch aiws-worker]
+    ↓
+worker 返回 DONE ──────────────────→ [dispatch aiws-reviewer]
+worker 返回 DONE_WITH_CONCERNS ────→ [ws-quality-review] ─→ pass? → [dispatch aiws-reviewer]
+                                                             fail? → [dispatch aiws-worker 修复]
+worker 返回 NEEDS_CONTEXT ────────→ 补 context → [dispatch aiws-worker]（最多 2 次）
+worker 返回 BLOCKED ──────────────→ [stop: 输出 blocker]
+    ↓
+[aiws-reviewer returns]
+    ├─ pass → [主 session 收敛 evidence → ws-finish]
+    ├─ fail with findings → [aiws-worker 修复]（最多 3 次循环）
+    └─ BLOCKED/NEEDS_CONTEXT → [stop: 输出详情]
+```
+
+### Review 未通过的修复
+
+当 reviewer 返回 fail 时，返回 worker 修复：
+- 将 reviewer findings 作为 worker 的额外上下文
+- worker 修复后，再次 dispatch reviewer
+- 最多 3 次循环；超过后升级给用户决策
+
+## 主 Session 职责清单
+
+### Dispatch 前
+- [ ] 已创建/确认 `changes/<id>/analysis/worker-context.jsonl`
+- [ ] Worker 的 readScope / writeScope / artifactTargets 已声明
+- [ ] 上下文预算检查通过
+- [ ] Worker prompt 包含期望的报告格式
+
+### Dispatch 后
+- [ ] 解析 worker 返回的 Status 行
+- [ ] 非 DONE → 按四状态协议处理
+- [ ] DONE → dispatch reviewer
+
+### Review 后
+- [ ] 收敛 reviewer findings 到 `changes/<id>/review/`
+- [ ] 决定是否接受、返回修复或升级
+- [ ] 最终收敛 evidence 到 `changes/<id>/evidence/`
+
+## 引用关系
+
+本规范被以下文件引用（通过文件名或规范 ID）：
+- `ws-dev/SKILL.md` — 默认执行策略
+- `ws-delegate/SKILL.md` — 委托循环参考
+- `using-aiws/SKILL.md` — 路由决策参考
+- `workflow-delegation-contracts.md` — 角色/scope/artifact 契约
+- `workflow-delegation-context-injection.md` — JSONL curation 规范
+
+## 更新历史
+
+- v1 (2026-05-16): 初版。基于 trellis workflow-state 纪律 + superpowers subagent-driven-development 模式。