@aipper/aiws-spec 0.0.32 → 0.0.34

package/docs/workflow-stage-contracts.json

@@ -137,11 +137,11 @@
       },
       {
         "label": "review",
-        "value": "`changes/<change-id>/review/...` 或 `.agentdocs/tmp/review/...`"
+      "value": "`changes/<change-id>/review/...` 或 `.aiws/tmp/review/...`"
       },
       {
         "label": "validate",
-        "value": "`.agentdocs/tmp/aiws-validate/*.json`"
+      "value": "`.aiws/tmp/aiws-validate/*.json`"
       },
       {
         "label": "verify-before-complete",

package/docs/workflow-stage-contracts.md

@@ -48,8 +48,8 @@
 最少证据集合：
 
 - planning：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`
-- review：`changes/<change-id>/review/...` 或 `.agentdocs/tmp/review/...`
-- validate：`.agentdocs/tmp/aiws-validate/*.json`
+- review：`changes/<change-id>/review/...` 或 `.aiws/tmp/review/...`
+- validate：`.aiws/tmp/aiws-validate/*.json`
 - verify-before-complete：`changes/<change-id>/evidence/verify-before-complete.md`；结构化逐项 gate 结果（spec-review ✓/✗, quality-review ✓/✗, validate ✓/✗, no-Critical ✓/✗, handoff ✓/✗）
 - deliver / finish：`changes/<change-id>/evidence/...`、`state`、merge / push 结果
 - handoff：`changes/archive/.../handoff.md`

package/docs/ws-goal-contract.md

@@ -0,0 +1,230 @@
+# ws-goal-contract
+
+ws-goal 协议层规范：目标定义、完成审计、预算约束与工具适配矩阵。
+
+---
+
+## 1. Background & Motivation
+
+### /goal 类指令的五层架构
+
+一些工具引入了 `/goal` 类指令。它的实现分五层：
+
+| 层 | 实现 | 职责 |
+|---|---|---|
+| 持久化层 | Rust `thread_goals` 状态表 | 目标状态 pursuing/paused/achieved/budget_limited，token 用量，耗时 |
+| App-Server API | `thread/goal/get/set/clear` + 通知 | 跨客户端同步，断线重连恢复 |
+| Model Tools | `get_goal` / `create_goal` / `update_goal` | 模型只读 / 受限写入，不能暂停或清除 |
+| Runtime | continuation 调度 + budget 追踪 | 自动续跑、interrupt 暂停、resume 恢复、soft-stop |
+| TUI | `/goal` `/goal pause/resume/clear` | 创建、查看、控制生命周期 |
+
+核心运行机制：用户输入 `/goal <objective>` 后，runtime 将目标持久化为 thread-level 状态。每轮结束时注入 `continuation.md` 模板，跟踪已用时间、已消耗 token、总预算、剩余 token。模型通过 `update_goal(complete)` 声明完成，runtime 在预算耗尽时注入 `budget_limit.md` 执行 soft stop（非 abort），整理进度报告而不是直接终止。
+
+### aiws 的现状与机会
+
+aiws 当前没有等价协议。OpenCode + oh-my-opencode 已经提供了 3 层递进的自执行机制：
+
+- **L1 Todo Continuation Enforcer（Boulder 模式）**：session.idle + 未完成 todo 时自动注入 continuation 指令，5s 冷却 + 指数退避，最多 5 次连续失败后退出
+- **L2 Ralph Loop（自引用迭代执行）**：通过 `/ralph-loop <task>` 触发，状态持久化在 `.opencode/ralph-loop.local.md`，持续注入 continuation prompt 直到模型输出 `<promise>DONE</promise>`
+- **L3 Ultrawork（审计闭环）**：模型输出 DONE 后启动独立 Oracle 审查，必须输出 `<promise>VERIFIED</promise>` 才能通过；审查失败回 loop 继续修复
+
+这三层机制已经提供了续跑调度和基本持久化，但没有标准的"目标设定"协议，没有预算约束定义，也没有可移植的完成审计规范。
+
+### 方案：ws-goal 作为协议层
+
+ws-goal 定义为**协议层**（prompt-template + artifact spec），不是运行时引擎。它负责任务目标的结构化定义、完成审计的证据规范、预算耗尽协议。续跑调度继续借用各平台已有的能力。
+
+这样做的好处是：不重复造 runtime，不绑定特定工具，只写一份规范就能投影到所有平台。
+
+---
+
+## 2. Core Concepts
+
+### 2.1 Goal Objective Contract
+
+每个 goal objective 必须包含以下 6 个元素：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| **outcome** | string | 具体的可交付物描述。必须是可验证的，不能是模糊意图 |
+| **verification** | string | 如何证明完成。可以是文件路径 + 校验、测试命令 + 预期输出、benchmark 阈值、artifact URL |
+| **constraints** | object | 预算限制：token_budget（token 上限）、time_budget（wall clock 上限）、max_iterations（turn 次数上限） |
+| **boundaries** | string[] | 显式的非目标、范围限制。什么不在本次 goal 内 |
+| **iteration_policy** | object | max_attempts（重试次数）、reaudit_frequency（每几次迭代重新审计一次） |
+| **blocked_stop** | boolean | 遇到 blocker 时是否暂停并报告。true = 报告并等待，不能静默失败 |
+
+### 2.2 Goal State Machine
+
+```
+active → paused (optional) → complete | budget_limited → archived
+```
+
+- **active**：目标正在执行中。可能有多个 iteration
+- **paused**（可选）：目标被暂停。运行时能力取决于平台。
+- **complete**：完成审计通过，目标已被证明达成
+- **budget_limited**：预算耗尽，目标未完成但无法继续。产生进度报告和 TODO 列表供继续
+- **archived**：最终状态。goal artifact 归档到 evidence 目录
+
+### 2.3 Completion Audit Protocol
+
+8 步完成审计方法：
+
+1. **Derive requirements**：从 objective 推导出具体的、可验证的需求列表。不是重复 objective 原文，而是分解为可逐个检查的原子项
+2. **Preserve scope**：保持原始目标范围。不要将"已经做了什么"重新定义为目标——audit 评判的是原始目标是否达成
+3. **Identify evidence sources**：对每个需求，指定权威证据来源（文件内容、测试命令、benchmark 数据、artifact）
+4. **Inspect current state**：检查当前状态中与每个需求相关的证据源
+5. **Classify evidence**：对每个证据分类——proves completion（证明完成）/ contradicts（矛盾，证明未完成）/ incomplete（部分完成但不足）/ too weak（证据太弱，不能作为完成依据）/ missing（缺失，没有找到对应证据）
+6. **Match scope**：验证范围必须匹配需求范围。窄验证不能推导出宽结论。例如"一个函数返回 200"不能证明"整个 API 端点正常工作"
+7. **Uncertain = NOT achieved**：不确定的、间接的、推论性的证据不能作为完成依据。audit 需要确定的证明
+8. **Prove, not disprove**：audit 必须正面证明完成，而不是反面证明"没找到未完成的工作"。找不出 bug 不等于代码正确
+
+---
+
+## 3. Protocol Specification
+
+### 3.1 Goal Objective Markdown Template
+
+```markdown
+---
+ws_goal:
+  version: 1
+  state: active          # active | paused | complete | budget_limited | archived
+  created_at: <ISO 8601>
+  updated_at: <ISO 8601>
+  iteration: 1
+  max_iterations: <number>
+---
+
+# Goal: <简短标题>
+
+## Outcome
+
+<具体的可交付物描述。必须可验证>
+
+## Verification
+
+- **Type**: file | test | command | benchmark | artifact
+- **Target**: <文件路径 / 测试命令 / benchmark ID 等>
+- **Expected**: <预期结果>
+
+## Constraints
+
+- token_budget: <number> | null
+- time_budget: <minutes> | null
+- max_iterations: <number>
+
+## Boundaries
+
+- <不做什么 1>
+- <不做什么 2>
+
+## Iteration Policy
+
+- max_attempts: <number>
+- reaudit_frequency: <number>  # 每 N 次 iteration 重新做一次完成审计
+
+## Blocked Stop
+
+- enabled: true | false
+- report_to: user | log
+
+## Progress Notes
+
+<每次迭代更新，记录做了什么、什么阻塞、进度百分比>
+```
+
+### 3.2 Evidence Type Registry
+
+完成审计使用的证据类型：
+
+| Type | Schema | 说明 |
+|---|---|---|
+| **file** | `{ path: string, checksum?: string }` | 文件存在且内容匹配。checksum 可选，用于精确内容验证 |
+| **test** | `{ command: string, expected_exit: number, expected_output?: string }` | 运行测试命令，检查退出码和输出 |
+| **command** | `{ command: string, stdout?: string, stderr?: string, exit_code: number }` | 运行任意命令，捕获标准输出、错误输出、退出码 |
+| **benchmark** | `{ metric: string, before: number, after: number, threshold: string }` | 性能基准。threshold 格式 `"<N"` `">N"` `"±N%"` |
+| **artifact** | `{ url: string, metadata?: object }` | 外部交付物（部署 URL、PR 链接、发布包等）。metadata 可包含版本号、commit sha 等 |
+
+### 3.3 Budget Protocol
+
+三个约束维度，全部为软停止（soft-stop，不 abort）：
+
+| 维度 | 类型 | 默认 | 软停止行为 |
+|---|---|---|---|
+| **token_budget** | number | null（无限制） | 接近上限时注入 budget 警告，到达上限时记录进度报告并暂停。**不**中断模型输出 |
+| **time_budget** | number (minutes) | null（无限制） | 到达时限时发出超时信号，运行中的 tool 调用完成后自然停止，不走 kill |
+| **max_iterations** | number | null（无限制） | 达到上限后阻止下次续跑，产出进度摘要和剩余 TODO |
+
+token_budget 依赖平台的 token 计数器。aiws 不提供独立的 token 监控，只定义协议：平台应能声明当前 token 用量和剩余预算。当平台无法提供 token 计数时，此维度应标记为 `unsupported`。
+
+### 3.4 Integration with Existing aiws Artifacts
+
+| aiws 工件 | ws-goal 映射 |
+|---|---|
+| `changes/<id>/tasks.md` | tasks.md 中的每个 item 可携带 `ws_goal_id: <id>` 引用，表示该 task 通过 goal 自动执行。`update_plan` 的 progress tracking 反映 goal iteration 进度 |
+| `.aiws/plan/...` proposal | proposal 中的 `Plan_File` 可以指向 goal objective markdown，表示该 change 使用 goal-driven 执行模式 |
+| `aiws validate` + evidence | validate 的门禁检查可以包含对 goal 的完成审计证据的校验。goal 的 evidence 应落盘到 `changes/<id>/evidence/`，与其他 change 工件统一 |
+
+---
+
+## 4. Tool Integration Matrix
+
+| Tool | Continuation Engine | Goal Persistence | Budget Tracking | Audit Method |
+|---|---|---|---|---|
+| **OpenCode** | Ralph Loop L2（`/ralph-loop` 自引循环） / Ultrawork L3（Ralph Loop + Oracle 审计） | `.opencode/ralph-loop.local.md`（YAML frontmatter，active/iteration 状态） | max_iterations 硬限制（L2），无 token/time budget | L2: `<promise>DONE</promise>` 语义声明；L3: Oracle 独立审计 + `<promise>VERIFIED</promise>` |
+| **aiws ws-goal protocol** | 不提供。依赖各平台已有 continuation 引擎 | `.aiws/goals/<goal-id>.md`（标准模板工件）+ `changes/<id>/evidence/` 审计证据 | 定义协议但依赖平台能力 | 8 步完成审计（协议层规范，平台层执行） |
+
+### 关键说明
+
+- **OpenCode L2 vs L3**：L2 只有自检声明（DONE），可信度较低；L3 引入独立审计者（Oracle），可信度较高但成本也高。ws-goal 协议推荐的审计模式是 L3，但允许 L2 作为轻度使用的降级
+- ws-goal 协议可以投影到各平台时绑定其 continuation 能力，只需补充完成审计的规范约束
+
+---
+
+## 5. Protocol Limitations
+
+### 5.1 NOT a Runtime
+
+ws-goal 协议层不实现任何 continuation/scheduling/pause/resume 机制。这些能力完全依赖于各平台：
+
+- OpenCode：依赖 Ralph Loop（文件状态轮询 + prompt 注入）
+
+这意味着跨工具的"暂停/恢复"行为会不一致。
+
+### 5.2 Budget Tracking 依赖平台能力
+
+token_budget 和 time_budget 的监控需要平台提供接口。当前：
+
+- OpenCode（oh-my-opencode）：无 token 计数，只有 max_iterations
+
+aiws 只定义"预算耗尽时应该做什么"的协议，不提供跨平台的统一计费层。在缺少平台支持的维度上，goal 应标记为 unsupported 而不是假装能工作。
+
+### 5.3 Cross-Tool Goal Persistence 是 Best-Effort
+
+不同工具使用不同的持久化机制：
+
+- OpenCode（Ralph Loop）：文件 `.opencode/ralph-loop.local.md`（会话级）
+
+没有共享数据库。如果一个目标在一个工具开始，无法在另一个工具中恢复。goal objective markdown 文件 `.aiws/goals/<goal-id>.md` 可以作为人类可读的参考，但状态同步不保证。
+
+### 5.4 State Machine 的工具依赖
+
+完整状态机 `active → paused → complete | budget_limited → archived` 中各状态的支持情况：
+
+| 状态转换 | OpenCode (Ralph Loop) |
+|---|---|---|
+| active → paused | 不支持（只能 cancel） |
+| paused → active | 不支持 |
+| active → complete | 支持（DONE 声明 + oracle 验证） |
+| active → budget_limited | 不支持 |
+| complete → archived | 手动 |
+
+aiws 协议层定义了完整的语义状态，但各平台只能实现其中一部分。goal 创建时应注意平台的能力边界。
+
+### 5.5 Completion Audit 的执行成本
+
+8 步完成审计方法在完整执行时需要独立审计者（在 OpenCode L3 中需要额外模型调用）。对于小目标（比如"修复一个 lint 错误"），完整审计的 overhead 可能超过实际工作的成本。建议根据目标复杂度选择审计级别：
+
+- **轻量**（< 3 步，单文件改动）：只做 step 1-2（derive + preserve），跳过完整证据链
+- **标准**（3-10 步，多文件改动）：完整 8 步审计
+- **严格**（跨模块、跨 repo）：8 步审计 + 独立审计者 + ws-review 门禁

package/package.json

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

package/templates/workspace/.aiws/continuation/CONTINUATION_PROTOCOL.md

@@ -0,0 +1,101 @@
+# ws-* Pipeline Continuation Protocol
+
+## 问题
+
+每个 ws-* skill 完成当前 phase 后输出 `Next:` 文本建议，然后停下。用户需要手动输入下一 phase 的 slash 命令。本协议定义了一套标准化机制，让所有 ws-* skill 在完成后自动推进到下一 phase。
+
+## 核心机制
+
+### 1. Pipeline 状态文件
+
+`.aiws/continuation/pipeline.json` — 共享状态文件，记录当前流水线所有 phase 的状态。
+
+```json
+{
+  "pipeline_id": "<pipeline-id>",
+  "goal_id": "<goal-id>",
+  "change_id": "<change-id>",
+  "created_at": "<UTC timestamp>",
+  "updated_at": "<UTC timestamp>",
+  "phases": [
+    {"name": "preflight",    "status": "completed",   "evidence": ""},
+    {"name": "ws-goal",      "status": "completed",   "evidence": ".aiws/goals/<goal-id>.md"},
+    {"name": "ws-plan",      "status": "in_progress", "evidence": ""},
+    {"name": "ws-plan-verify","status": "pending",    "evidence": ""},
+    {"name": "ws-dev",       "status": "pending",     "evidence": ""},
+    {"name": "ws-review",    "status": "pending",     "evidence": ""},
+    {"name": "ws-commit",    "status": "pending",     "evidence": ""},
+    {"name": "ws-finish",    "status": "pending",     "evidence": ""}
+  ],
+  "current_phase_index": 2,
+  "blockers": []
+}
+```
+
+状态值: `pending` | `in_progress` | `completed` | `blocked`
+
+### 2. Phase Completion Protocol（所有 ws-* skill 共享）
+
+每个 ws-* skill 完成后执行（替代原有 `Next:` 输出 + 结束）：
+
+```
+1. 更新 pipeline.json：
+   - 当前 phase → status: "completed", evidence: <路径>
+   - 下一 phase → status: "in_progress"
+   - current_phase_index → 下一 phase 索引号
+   - updated_at → 当前时间
+
+2. 更新 todo：
+   - 当前 phase 的 todo → completed
+   - 下一 phase 的 todo → in_progress（若还不存在则创建）
+
+3. 若还有下一 phase：
+   - 输出 "→ Auto-continuing to <next_phase>"
+   - 立即开始执行下一 phase 的逻辑（不输出"是否继续"等待文本）
+
+4. 若已是最后一个 phase：
+   - 输出 pipeline 完成摘要
+   - 标记 goal 为 complete
+```
+
+### 3. Continuation Detection（所有 ws-* skill 共享）
+
+当 skill 被调用时（包括 slash command 直接调用 和 Boulder/Ralph Loop continuation）：
+
+```
+检查 .aiws/continuation/pipeline.json：
+- 若存在且有 in_progress phase：
+  a) 如果 in_progress phase 名称 == 当前 skill 名称 → 正常执行当前 skill
+  b) 如果 in_progress phase 名称 ≠ 当前 skill 名称 → 跳到该 phase 的执行逻辑
+  c) 如果所有 phase completed → 输出 pipeline 完成摘要，不再执行新工作
+- 若不存在 → 正常执行当前 skill（独立模式）
+```
+
+### 4. Skill Entry 改造
+
+每个 ws-* SKILL.md 顶部增加 Pipeline Continuation Detection 段。
+
+### 5. Skill Ending 改造
+
+每个 ws-* SKILL.md 的 `输出要求` / `Next:` 段替换为 Phase Completion Protocol。
+
+### 6. ws-goal 作为 Pipeline 启动器
+
+ws-goal 在复杂度评估后：
+- 创建 pipeline.json（预填所有 phase）
+- 创建所有 phase 对应的 todo
+- 直接执行第一个 phase 的逻辑（不停下）
+
+## 默认 Pipeline 链路
+
+preflight → ws-goal → ws-plan → ws-plan-verify → ws-dev → ws-review → ws-commit → ws-finish
+
+根据复杂度评估选择包含哪些 phase：
+- 简单路径: ws-goal → dev → commit → finish
+- 标准路径: ws-goal → plan → plan-verify → dev → review → commit → finish
+- 复杂路径: 标准路径 + intake + deliver + handoff
+
+## 文件位置
+
+- 状态文件: `.aiws/continuation/pipeline.json`
+- 协议文档: `.aiws/continuation/CONTINUATION_PROTOCOL.md`

package/templates/workspace/.aiws/manifest.json

@@ -5,7 +5,7 @@
   "aiws_version": "0.0.0",
   "installed_at": "1970-01-01T00:00:00Z",
   "updated_at": "1970-01-01T00:00:00Z",
-  "tools": ["claude", "opencode", "codex"],
+  "tools": ["opencode"],
   "managed": [
     { "path": ".githooks/pre-commit", "mode": "replace_file", "sha256": "<sha256>" },
     { "path": ".githooks/pre-push", "mode": "replace_file", "sha256": "<sha256>" },
@@ -16,17 +16,9 @@
     { "path": "AI_WORKSPACE.md", "mode": "managed_blocks", "blocks": { "ai-workspace:core": "<sha256>" } },
     { "path": "REQUIREMENTS.md", "mode": "managed_blocks", "blocks": { "requirements:contract": "<sha256>" } },
     { "path": ".gitignore", "mode": "managed_blocks", "blocks": { "gitignore": "<sha256>" } },
-    { "path": ".claude/commands/aiws-init.md", "mode": "managed_blocks", "blocks": { "claude:aiws-init": "<sha256>" } },
-    { "path": ".claude/commands/aiws-update.md", "mode": "managed_blocks", "blocks": { "claude:aiws-update": "<sha256>" } },
-    { "path": ".claude/commands/aiws-validate.md", "mode": "managed_blocks", "blocks": { "claude:aiws-validate": "<sha256>" } },
-    { "path": ".claude/commands/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "claude:aiws-rollback": "<sha256>" } },
     { "path": ".opencode/command/aiws-init.md", "mode": "managed_blocks", "blocks": { "opencode:aiws-init": "<sha256>" } },
     { "path": ".opencode/command/aiws-update.md", "mode": "managed_blocks", "blocks": { "opencode:aiws-update": "<sha256>" } },
     { "path": ".opencode/command/aiws-validate.md", "mode": "managed_blocks", "blocks": { "opencode:aiws-validate": "<sha256>" } },
-    { "path": ".opencode/command/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "opencode:aiws-rollback": "<sha256>" } },
-    { "path": ".codex/prompts/aiws-init.md", "mode": "managed_blocks", "blocks": { "codex:aiws-init": "<sha256>" } },
-    { "path": ".codex/prompts/aiws-update.md", "mode": "managed_blocks", "blocks": { "codex:aiws-update": "<sha256>" } },
-    { "path": ".codex/prompts/aiws-validate.md", "mode": "managed_blocks", "blocks": { "codex:aiws-validate": "<sha256>" } },
-    { "path": ".codex/prompts/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "codex:aiws-rollback": "<sha256>" } }
+    { "path": ".opencode/command/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "opencode:aiws-rollback": "<sha256>" } }
   ]
 }

package/templates/workspace/.aiws/tools/ws_change_check.py

@@ -323,6 +323,13 @@ def extract_first_id(labels: List[str], text: str) -> str:
     return ""
 
 
+def normalize_optional_id(value: str) -> str:
+    normalized = (value or "").strip()
+    if normalized.upper() in {"N/A", "NA", "NONE", "NULL", "-"}:
+        return ""
+    return normalized
+
+
 def split_declared_values(value: str) -> List[str]:
     parts = re.split(r"[,;\n]+", value or "")
     out: List[str] = []
@@ -910,8 +917,8 @@ def validate_change(
             warnings.append("proposal.md does not reference AI_WORKSPACE.md (recommended)")
 
         change_id_decl = extract_id("Change_ID", t)
-        req_id = extract_id("Req_ID", t)
-        prob_id = extract_id("Problem_ID", t)
+        req_id = normalize_optional_id(extract_id("Req_ID", t))
+        prob_id = normalize_optional_id(extract_id("Problem_ID", t))
         contract_row_decl = extract_first_id(["Contract_Row", "Contract_Row(s)"], t)
         plan_file_decl = extract_first_id(["Plan_File", "Plan file"], t)
         evidence_path_decl = extract_first_id(["Evidence_Path", "Evidence_Path(s)"], t)
@@ -1009,8 +1016,8 @@ def validate_change(
                 else:
                     plan_text = read_text(plan_abs)
                     plan_change_id = extract_id("Change_ID", plan_text)
-                    plan_req_id = extract_id("Req_ID", plan_text)
-                    plan_prob_id = extract_id("Problem_ID", plan_text)
+                    plan_req_id = normalize_optional_id(extract_id("Req_ID", plan_text))
+                    plan_prob_id = normalize_optional_id(extract_id("Problem_ID", plan_text))
                     plan_contract_row = extract_first_id(["Contract_Row", "Contract_Row(s)"], plan_text)
                     plan_file_from_plan = extract_first_id(["Plan_File", "Plan file"], plan_text)
                     plan_evidence_path = extract_first_id(["Evidence_Path", "Evidence_Path(s)"], plan_text)

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

@@ -66,6 +66,10 @@ fi
 7) submodules 全部成功后，再回到主仓库执行：
    - `aiws change finish <change-id> --push`
 8) `aiws change finish --push` 成功后会自动归档并生成 handoff；只有历史/异常场景才需要手工运行 `aiws change archive <change-id>`。
+9) 输出本轮 change 的中文工作摘要，包含：
+   - 目标：解决了什么问题
+   - 改动范围：改了哪些文件/模块（可引用 handoff 或 evidence）
+   - 验证结果：构建/测试/LSP/validate 等关键门禁的结果
 
 安全：
 - push 前先输出状态并说明远端/分支。

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

@@ -0,0 +1,44 @@
+---
+description: 目标协议：设定可审计的 goal 目标并执行完成闭环
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-goal -->
+# ws goal
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 将用户需求转化为可审计的 goal 目标，按 ws-goal-contract.md 的目标模板写入目标文件，驱动完成闭环。
+
+前置条件：
+1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
+
+执行流程：
+0) 检查 `.aiws/goals/` 目录：
+   a) 若用户仅查询状态（无明确目标），列出所有 goal 文件及其 status 字段，然后结束。
+   b) 若存在 status=active 或 status=paused 的 goal 文件，优先读取并恢复执行，不再新建 goal。
+1) 读取真值文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`），确认项目规则与边界。
+2) 接受用户输入的 goal objective，明确目标范围与验收标准。
+3) 按 ws-goal-contract.md 的目标模板生成目标文件，写入 `.aiws/goals/<goal-id>.md`。
+4) 输出 completion audit checklist，列出每个 goal 的完成标准与验证方式。
+5) **Scope Assessment + 路由**：评估目标复杂度，自动选择执行路径：
+   a) 简单（≤5 文件、配置/doc/规范为主、低风险）→ 直行：后续步骤 6-8 auto-finish 闭环
+   b) 复杂（多模块、代码改动 >5 文件、架构/安全/迁移风险）→ 自动触发 `ws-plan` 启动 change 流水线（ws-plan → ws-dev → review → ws-commit → ws-finish），完成后更新 goal status=complete
+   c) 将路由决策写入 goal 文件 Audit Trail
+6) 建议续跑方式：简单路径直行 auto-finish；复杂路径进入 change 流水线后建议 `ws-dev`
+7) 每轮 execution 结束后执行 completion audit，比对 checklist 判断 goal 是否达成；未达成则继续下一轮。
+8) 若 completion audit 确认 goal 达成，自动执行闭环 pipeline：
+   a) Review 检查（按改动类型）：
+      - 配置/文档/规范类（markdown）：内容一致性、引用完整性、内容正确性、无 secrets、格式统一
+      - 代码类（ts/js/py 等）：lint/typecheck 通过、符合现有代码模式、无 secrets、测试通过或覆盖缺口已记录
+      - 混合类：以上两种合并
+   b) 简单路径：`git add` 目标产出文件 → `git commit -m "goal(<goal-id>): <objective 摘要>"` → `git push` → 更新 goal status=complete
+   c) 复杂路径：走 `ws-commit` → `ws-finish` → archive change → 更新 goal status=complete
+   d) 不通过：记录 blocker → 继续 fix 循环
+9) **Auto-chain to next goal**：当前 goal pipeline 完成后：
+   a) 扫描 `.aiws/goals/*.md`，按文件名排序找出第一个 status=pending 的 goal
+   b) 若找到：读取其 objective，输出 "→ Auto-continuing to <goal-id>"，回到步骤 5 创建新 pipeline 自动继续
+   c) 若未找到：输出 "All goals completed" 并结束
+   d) 若找到的 pending goal 缺少 Success Criteria：输出 blocker 并停止（不自动跳过）
+<!-- AIWS_MANAGED_END:opencode:ws-goal -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -66,6 +66,10 @@ fi
 7) submodules 全部成功后，再回到主仓库执行：
    - `aiws change finish <change-id> --push`
 8) `aiws change finish --push` 成功后会自动归档并生成 handoff；只有历史/异常场景才需要手工运行 `aiws change archive <change-id>`。
+9) 输出本轮 change 的中文工作摘要，包含：
+   - 目标：解决了什么问题
+   - 改动范围：改了哪些文件/模块（可引用 handoff 或 evidence）
+   - 验证结果：构建/测试/LSP/validate 等关键门禁的结果
 
 安全：
 - push 前先输出状态并说明远端/分支。

package/templates/workspace/.opencode/lib/aiws-context.js

@@ -833,10 +833,44 @@ Read and follow the context below.
 
   const activeChange = ctx.getActiveChange()
   if (activeChange) {
-    const phaseSummary = ctx.getPhaseSummary(activeChange.id)
-    parts.push("<change-context>")
-    parts.push(phaseSummary)
-    parts.push("</change-context>")
+    // Prefer STATE.md (derived from journal by aiws change state --write)
+    let stateContent = ""
+    try {
+      const statePath = join(ctx.directory, ".aiws", "changes", activeChange.id, "STATE.md")
+      if (existsSync(statePath)) {
+        stateContent = readFileSync(statePath, "utf8")
+      }
+    } catch {
+      // STATE.md not available, fall back to phase summary
+    }
+
+    if (stateContent) {
+      parts.push("<change-state-state-md>")
+      parts.push("## Current Change State (from STATE.md)")
+      parts.push(stateContent.trimEnd())
+      parts.push("</change-state-state-md>")
+    } else {
+      const phaseSummary = ctx.getPhaseSummary(activeChange.id)
+      parts.push("<change-context>")
+      parts.push(phaseSummary)
+      parts.push("</change-context>")
+    }
+
+    // .ws-change.json baseline
+    try {
+      const wsChangePath = join(ctx.directory, ".aiws", "changes", activeChange.id, ".ws-change.json")
+      if (existsSync(wsChangePath)) {
+        const wsChangeRaw = readFileSync(wsChangePath, "utf8")
+        const wsChange = JSON.parse(wsChangeRaw)
+        parts.push("<change-baseline>")
+        parts.push("## Change Baseline (.ws-change.json)")
+        parts.push(`Base Branch: ${wsChange.base_branch || "unknown"}`)
+        parts.push(`Template ID: ${wsChange.template_id || "unknown"}`)
+        parts.push("</change-baseline>")
+      }
+    } catch {
+      // .ws-change.json not available
+    }
 
     // Continuation resume recommendation
     try {

package/templates/workspace/.opencode/oh-my-opencode.json.example

@@ -55,12 +55,17 @@
           "git diff"
         ],
         "write_allow_paths": [
+          ".aiws/tmp/",
+          ".aiws/changes/*/analysis/",
+          ".aiws/changes/*/review/",
+          ".aiws/changes/*/evidence/",
           ".agentdocs/tmp/",
           "changes/*/analysis/",
           "changes/*/review/",
           "changes/*/evidence/"
         ],
         "deny_paths": [
+          ".aiws/secrets/",
           "secrets/",
           ".env*"
         ],

package/templates/workspace/.opencode/skills/ws-goal/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ws-goal
+description: 目标协议：设定可审计的 goal 目标并执行完成闭环（基于 ws-goal-contract.md）
+---
+# ws-goal
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 将用户需求转化为可审计的 goal 目标，按 ws-goal-contract.md 的目标模板写入目标文件，驱动完成闭环。
+
+前置条件：
+1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
+
+执行流程：
+0) 检查 `.aiws/goals/` 目录：
+   a) 若用户仅查询状态（无明确目标），列出所有 goal 文件及其 status 字段，然后结束。
+   b) 若存在 status=active 或 status=paused 的 goal 文件，优先读取并恢复执行，不再新建 goal。
+1) 读取真值文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`），确认项目规则与边界。
+2) 接受用户输入的 goal objective，明确目标范围与验收标准。
+3) 按 ws-goal-contract.md 的目标模板生成目标文件，写入 `.aiws/goals/<goal-id>.md`。
+4) 输出 completion audit checklist，列出每个 goal 的完成标准与验证方式。
+5) **Scope Assessment + 路由**：评估目标复杂度，自动选择执行路径：
+   a) 简单（≤5 文件、配置/doc/规范为主、低风险）→ 直行：后续步骤 6-8 auto-finish 闭环
+   b) 复杂（多模块、代码改动 >5 文件、架构/安全/迁移风险）→ 自动触发 `ws-plan` 启动 change 流水线（ws-plan → ws-dev → review → ws-commit → ws-finish），完成后更新 goal status=complete
+   c) 将路由决策写入 goal 文件 Audit Trail
+6) 建议续跑方式：简单路径直行 auto-finish；复杂路径进入 change 流水线后建议 `ws-dev`
+7) 每轮 execution 结束后执行 completion audit，比对 checklist 判断 goal 是否达成；未达成则继续下一轮。
+8) 若 completion audit 确认 goal 达成，自动执行闭环 pipeline：
+   a) Review 检查（按改动类型）：
+      - 配置/文档/规范类（markdown）：内容一致性、引用完整性、内容正确性、无 secrets、格式统一
+      - 代码类（ts/js/py 等）：lint/typecheck 通过、符合现有代码模式、无 secrets、测试通过或覆盖缺口已记录
+      - 混合类：以上两种合并
+   b) 简单路径：`git add` 目标产出文件 → `git commit -m "goal(<goal-id>): <objective 摘要>"` → `git push` → 更新 goal status=complete
+   c) 复杂路径：走 `ws-commit` → `ws-finish` → archive change → 更新 goal status=complete
+   d) 不通过：记录 blocker → 继续 fix 循环
+9) **Auto-chain to next goal**：当前 goal pipeline 完成后：
+   a) 扫描 `.aiws/goals/*.md`，按文件名排序找出第一个 status=pending 的 goal
+   b) 若找到：读取其 objective，输出 "→ Auto-continuing to <goal-id>"，回到步骤 5 创建新 pipeline 自动继续
+   c) 若未找到：输出 "All goals completed" 并结束
+   d) 若找到的 pending goal 缺少 Success Criteria：输出 blocker 并停止（不自动跳过）