@aipper/aiws-spec 0.0.40 → 0.0.41

package/docs/ws-goal-contract.md

@@ -249,7 +249,139 @@ ws_goal:
 <每次迭代更新，记录做了什么、什么阻塞、进度百分比>
 ```
 
-### 3.2 Evidence Type Registry
+### 3.2 Intake State
+
+#### 3.2.1 用途
+
+在 PHASE 0（INTAKE）期间记录机器可读状态，填补"ws-goal 开始 intake"到"创建 goal state.json"之间的持久化空白。避免 session 在 intake 阶段被中断后，恢复时无法检测到进行中的 work。
+
+#### 3.2.2 文件路径
+
+`.aiws/intake/<intake-id>.state.json`
+
+`<intake-id>` 与对应的 `.aiws/plan/<timestamp>-<slug>.intake.md` 文件 slug 一致。
+
+#### 3.2.3 Schema
+
+```json
+{
+  "$schema": "ws-goal-intake-schema.json",
+  "version": "1",
+  "intake_id": "<intake-id>",
+  "status": "in_progress",
+  "max_idle_minutes": 30,
+  "created_at": "<ISO 8601>",
+  "updated_at": "<ISO 8601>",
+  "questions": {
+    "total": 7,
+    "frozen": 1,
+    "open": 6,
+    "items": [
+      { "id": "Q1", "title": "目标用户是谁？", "status": "frozen", "frozen_at": "<ISO 8601>", "answer_summary": "开发者，macOS 用户" },
+      { "id": "Q2", "title": "目标用户的网络环境是什么？", "status": "in_progress", "frozen_at": null, "answer_summary": null }
+    ]
+  },
+  "current_question": "Q2: 目标用户的网络环境是什么？",
+  "background_tasks": [
+    {
+      "task_id": "bg_abc123",
+      "type": "librarian",
+      "description": "Explore ClashX.Meta repo architecture",
+      "started_at": "<ISO 8601>",
+      "status": "running"
+    }
+  ],
+  "last_error": null,
+  "session_metadata": {
+    "last_agent": "user",
+    "message_count": 42,
+    "last_activity_at": "<ISO 8601>"
+  }
+}
+```
+
+#### 3.2.4 字段说明
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `intake_id` | string | 对应 `.aiws/plan/<timestamp>-<slug>.intake.md` 的 slug 部分 |
+| `status` | enum | `pending` \| `in_progress` \| `paused` \| `complete` \| `archived` \| `timed_out` |
+| `max_idle_minutes` | number | 后台任务空闲超时阈值（分钟，默认 30）。ws-goal step 0 发现 background task 的 started_at 超过此阈值时自动标记为 timed_out |
+| `questions.total` | number | intake 问题总数 |
+| `questions.frozen` | number | 已冻结（已回答并确认）的问题数（status=frozen） |
+| `questions.open` | number | 待回答的问题数 |
+| `questions.items[]` | object[] | 逐问题详情列表，用于问题级恢复展示。可选，有值时 total/frozen/open 必须与 items 派生值一致 |
+| `questions.items[].id` | string | 问题标识，如 Q1、Q2 |
+| `questions.items[].title` | string | 问题标题，用于恢复时展示 |
+| `questions.items[].status` | enum | `pending` \| `in_progress` \| `frozen` \| `skipped` |
+| `questions.items[].frozen_at` | string \| null | 冻结时间（若 status=frozen） |
+| `questions.items[].answer_summary` | string \| null | 回答摘要，供跨 session 上下文保留 |
+| `current_question` | string \| null | 当前正在处理的问题，恢复时定位位置 |
+| `background_tasks[]` | object[] | 已启动的 subagent 任务追踪 |
+| `last_error` | string \| null | 最近的错误信息 |
+| `session_metadata` | object | 调试辅助，无程序化依赖 |
+
+#### 3.2.5 状态机
+
+```
+pending → in_progress → complete → archived
+                      → paused（用户主动暂停）
+                      → timed_out（超时检测：后台任务超过 max_idle_minutes 无响应）
+```
+
+- **pending**：state.json 已创建但 intake 尚未正式开始。用于 crash 恢复时区分"刚创建还没开始"和"已经卡住了"
+- **in_progress**：intake 正在执行中，可能有 frozen 问题进度
+- **paused**：用户主动暂停 intake
+- **timed_out**：系统在下一 session 的 step 0 检测时自动标记。背景任务超过 `max_idle_minutes` 无更新。Auto-resume 行为与 in_progress 相同，但附加超时警告通知
+- **complete**：intake 全部问题已冻结
+- **archived**：最终状态，已移动到 `archive/` 子目录
+
+#### 3.2.6 生命周期
+
+```
+1. ws-goal PHASE 0 开始 intake → 创建 .aiws/intake/<id>.state.json (status=in_progress)
+2. 每 frozen 一个 intake 问题      → 更新 questions.frozen + current_question
+3. 每次启动 background subagent   → 追加 background_tasks[] (status=running)
+4. Background task 完成/失败      → 更新对应 task status
+5. Intake 全部完成               → status=complete
+6. 进入 PHASE 1 创建 goal state.json 后 → 归档到 .aiws/intake/archive/<id>.state.json
+7. 归档后不再是扫描目标
+```
+
+#### 3.2.7 恢复检测（Auto-Resume）
+
+下一 session ws-goal step 0 扫描 `.aiws/intake/*.state.json`：
+
+| status | 行为 |
+|---|---|
+| `in_progress` 或 `paused` | auto-resume：从 current_question 直接恢复，不询问用户 |
+| `timed_out` | auto-resume + 附加超时警告通知，仍从 current_question 恢复 |
+| `complete`，且对应 goal 不存在 | 输出警告：intake 完成但 goal 未创建。建议运行 ws-goal 基于此 intake 继续 |
+| `complete`，且对应 goal 存在 | 跳过（正常状态，已被 PHASE 1 消费） |
+| `archived` | 跳过（已归档） |
+
+Auto-resume 时输出以下通知（含问题级进度展示，但不需要用户选择）：
+
+```
+↻ 恢复中断的 intake: <intake-id>
+问题进度（<frozen>/<total>）:
+  ✅ Q1: <title> — 已冻结
+  ▶  Q2: <title> — 处理中（从该问题继续）
+  ⬜ Q3: <title> — 待处理
+  ⬜ Q4: <title> — 待处理
+```
+
+#### 3.2.8 旧格式迁移
+
+检测到 `.aiws/plan/*.intake.md` 但无 `.aiws/intake/` state → 自动生成 intake state.json：
+
+1. 通过解析 intake.md 的 markdown 结构推断问题列表
+2. 启发式判断已 frozen 问题：找到第一个未回答的问题标记，之前的都算 frozen
+3. 生成 state.json，status=in_progress
+
+---
+
+### 3.3 Evidence Type Registry
 
 完成审计使用的证据类型：
 
@@ -261,7 +393,7 @@ ws_goal:
 | **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
+### 3.4 Budget Protocol
 
 三个约束维度，全部为软停止（soft-stop，不 abort）：
 
@@ -273,7 +405,7 @@ ws_goal:
 
 token_budget 依赖平台的 token 计数器。aiws 不提供独立的 token 监控，只定义协议：平台应能声明当前 token 用量和剩余预算。当平台无法提供 token 计数时，此维度应标记为 `unsupported`。
 
-### 3.4 Integration with Existing aiws Artifacts
+### 3.5 Integration with Existing aiws Artifacts
 
 | aiws 工件 | ws-goal 映射 |
 |---|---|
@@ -385,6 +517,9 @@ Group 是 goal 内部的一个自包含执行单元：
 | **verification** | string[] | 该组的验收标准。组完成时需逐条验证 |
 | **depends_on** | string[] | 依赖的其他 group id。默认 `[]`（无依赖） |
 | **status** | enum | `pending \| in_progress \| complete \| paused \| failed` |
+| **design_context** | string | 该组的设计草稿/意图说明，委托 subagent 前必须填写 |
+| **internal_tasks** | string[] | 组内部可安全委托的自包含子任务列表，每项应 ≤ 3 文件改动粒度 |
+| **granularity_ok** | boolean | 主 session 在 DEV phase 前设置，true = 该组 scope ≤ 5 文件且不跨模块 |
 
 #### 6.2.2 Group Dependencies
 
@@ -455,6 +590,12 @@ phase 间的主 session 验证是门禁：
 
 ### group-1: Foundation Pages
 - scope: index.tsx, category.tsx, search.tsx
+- design_context: "Foundation pages use shared Layout component, SSR with getServerSideProps"
+- internal_tasks:
+  - "Replace hardcoded grid with <ProductGrid> component"
+  - "Add category filter sidebar to category.tsx"
+  - "Wire search API endpoint to search.tsx"
+- granularity_ok: false
 - verification:
   - "Home page renders product grid"
   - "Category page renders with filters"
@@ -464,6 +605,12 @@ phase 间的主 session 验证是门禁：
 
 ### group-2: Purchase Conversion
 - scope: cart.tsx, checkout.tsx, payment-form.tsx
+- design_context: "Purchase flow is client-only, uses React context for cart state"
+- internal_tasks:
+  - "Refactor cart context to persist to localStorage"
+  - "Add shipping address form with validation"
+  - "Implement card number validation with Luhn check"
+- granularity_ok: false
 - verification:
   - "Add to cart updates badge count"
   - "Checkout collects shipping address"
@@ -498,7 +645,12 @@ ws-goal 执行 Phase-Level Sequential Dispatch 时遵循以下协议：
            - plan file exists with verification commands
            - plan-verify passed
            - Fail max 2x → group paused, blocker recorded, STOP
-   c. Group PHASE 2 - DEV:
+   c. Granularity Gate (before DEV):
+      i.   Read current group's granularity_ok field
+      ii.  If granularity_ok !== true: output block report (scope, file count, cross-module span), pause goal
+      iii. Verify design_context and internal_tasks non-empty
+      iv.  If either empty: output warning (non-blocking), suggest filling
+   d. Group PHASE 2 - DEV:
       i.   Construct phase delegation prompt:
            - Plan content, proposal links
            - Phase scope: ONLY implement per plan + local verify
@@ -510,7 +662,7 @@ ws-goal 执行 Phase-Level Sequential Dispatch 时遵循以下协议：
            - Diagnostics clean (lsp_diagnostics on changed files)
            - Changes match plan scope
            - Fail → group paused, blocker recorded, STOP
-   d. Group PHASE 3 - REVIEW:
+   e. Group PHASE 3 - REVIEW:
       i.   Construct phase delegation prompt:
            - Proposal + plan + changed files
            - Phase scope: ONLY audit, produce review evidence
@@ -522,7 +674,7 @@ ws-goal 执行 Phase-Level Sequential Dispatch 时遵循以下协议：
            - Review evidence files exist
            - No HIGH blocker unresolved
            - Fail → group paused, blocker recorded, STOP
-   e. Group PHASE 4 - FINISH:
+   f. Group PHASE 4 - FINISH:
       i.   Construct phase delegation prompt:
            - Phase scope: ONLY commit + finish
            - Phase constraints: NOT modify code
@@ -532,8 +684,8 @@ ws-goal 执行 Phase-Level Sequential Dispatch 时遵循以下协议：
       iii. Main session verify:
            - Change branch merged to target_base_branch
            - Pushed to remote
-   f. Update group status → complete
-   g. Update goal Progress Notes with group result
+   g. Update group status → complete
+   h. Update goal Progress Notes with group result
 4. All groups complete:
    - Run overall completion audit (all verification + goal-level checks)
    - Update goal state → complete
@@ -571,16 +723,8 @@ Phase-Level Pipeline Dispatch 的审计分散在各 phase 的门禁验证中，
 
 1. ws-goal 记录当前组停止位置到 Progress Notes
 2. 标记 goal state=paused
-3. 输出恢复命令建议，例如：
-   ```
-   Goal <id> paused at group <group-id>.
-   To resume: fix the reported issue, then restart ws-goal.
-   ws-goal will detect the paused goal and ask whether to:
-     a) Retry group <group-id> (re-delegate)
-     b) Skip group <group-id> (mark complete manually, proceed to next)
-     c) Pause and handoff
-   ```
-4. 下一 session 启动 ws-goal 时（step 0），检测到 paused goal → 输出恢复选项 → 用户选择后继续
+3. **默认重试**：下一 session 自动从失败 phase 重新委托（不询问 skip）
+4. 重试耗尽（3 次）后自动暂停并 handoff，输出恢复上下文供手动处理
 
 ### 6.7 Backward Compatibility
 
@@ -589,3 +733,141 @@ Phase-Level Pipeline Dispatch 的审计分散在各 phase 的门禁验证中，
 | 不含 groups 定义的 goal | 受影响：step 5 从单次 delegation 变为 4-phase 顺序执行。迁移后需按 phase-level 适配 |
 | 含 groups 定义的 goal（新格式） | 进入 Phase-Level Sequential Dispatch 模式，每 group 按 4-phase 执行 |
 | 已有 goal 工件（.md 文件） | 兼容。goal 文件格式不变，仅 delegation 执行方式变更 |
+
+## 7. Persistence & Resume
+
+### 7.1 Motivation & Gap Analysis
+
+Codex /goal 使用 machine state table（pursuing/paused/achieved/budget_limited）作为持久化状态源，独立于人类可读的格式展示。它的状态由 runtime 自动管理，session 重启时恢复 thread-level 状态，无需用户额外操作。
+
+ws-goal 当前仅依赖 `.md` YAML frontmatter 中的 `ws_goal.state` 字段管理状态。这导致两个问题：
+1. **Session 重启后 frontmatter 可能不被正确读取**：AI agent 的上下文窗口在重启后丢失，依赖人类可读文件恢复状态不可靠。
+2. **Phase 进度丢失**：没有 per-phase checkpoint，重启后无法判断哪些 phase 已完成。
+
+解决方案：引入 `.state.json` 作为机器可读的精确状态源，与 `.md` 文件共存。`.md` 保持人类可读，`.state.json` 作为程序化读取/写入的主状态源。
+
+### 7.2 State File Format
+
+文件路径：`.aiws/goals/<goal-id>.state.json`
+
+Schema：
+```json
+{
+  "$schema": "ws-goal-state-schema.json",
+  "version": "1",
+  "goal_id": "<goal-id>",
+  "status": "active",
+  "iteration": 1,
+  "current_phase": "intake",
+  "current_group": null,
+  "checkpoints": {
+    "intake":        { "status": "pending", "attempts": 0, "completed_at": null, "error": null },
+    "goal_def":      { "status": "pending", "attempts": 0, "completed_at": null, "error": null },
+    "dep_check":     { "status": "pending", "attempts": 0, "completed_at": null, "error": null },
+    "ws_analysis":   { "status": "pending", "attempts": 0, "completed_at": null, "error": null },
+    "plan":          { "status": "pending", "attempts": 0, "completed_at": null, "error": null },
+    "dev":           { "status": "pending", "attempts": 0, "completed_at": null, "error": null },
+    "review":        { "status": "pending", "attempts": 0, "completed_at": null, "error": null },
+    "finish":        { "status": "pending", "attempts": 0, "completed_at": null, "error": null }
+  },
+  "groups": {}
+}
+```
+
+字段说明：
+- `status`：`active` | `paused` | `complete` | `budget_limited` | `archived`
+- `iteration`：同组 goal 的重试次数（paused → resume 计数）
+- `current_phase`：当前正在执行的 phase 名称
+- `current_group`：当前正在执行的 group（无 groups 时为 null）
+- `checkpoints`：per-phase 状态记录，每个 checkpoint 含：
+  - `status`：`pending` | `in_progress` | `complete` | `failed`
+  - `attempts`：该 phase 重试次数
+  - `completed_at`：ISO 8601 时间戳（complete 时写入）
+  - `error`：失败时的错误信息（failed 时写入）
+- `groups`：group-level 的 checkpoints 映射（可选，§6 支持）
+
+### 7.3 Phase-Level Checkpoints
+
+每个 phase 边界记录 checkpoint。记录时机：
+
+| 时机 | Checkpoint | 动作 |
+|---|---|---|
+| PHASE 0 完成 | intake | status=complete + timestamp |
+| PHASE 1 完成 | goal_def | status=complete + timestamp |
+| PHASE 2 step 4 依赖链预检通过 | dep_check | status=complete + timestamp |
+| PHASE 2 step 4.5 workspace 分析通过 | ws_analysis | status=complete + timestamp |
+| PHASE 2 step 5 PHASE 1 (PLAN) 通过/失败 | plan | status=complete/failed + timestamp + error |
+| PHASE 2 step 5 PHASE 2 (DEV) 通过/失败 | dev | status=complete/failed + timestamp + error |
+| PHASE 2 step 5 PHASE 3 (REVIEW) 通过/失败 | review | status=complete/failed + timestamp + error |
+| PHASE 2 step 5 PHASE 4 (FINISH) 通过/失败 | finish | status=complete/failed + timestamp + error |
+
+进入 phase 时更新 `current_phase` 和对应 checkpoint status=in_progress。
+完成 phase 时更新 checkpoint status=complete + `completed_at` 时间戳。
+失败时更新 checkpoint status=failed + `error`。
+暂停 goal 时更新 `status=paused`。
+
+**FINISH checkpoint complete 后自动归档**：
+```
+mkdir -p .aiws/goals/archive
+mv .aiws/goals/<goal-id>.md .aiws/goals/archive/<goal-id>.md
+mv .aiws/goals/<goal-id>.state.json .aiws/goals/archive/<goal-id>.state.json
+```
+归档后 goal 不再出现在 step 0 扫描列表中。
+
+### 7.4 Resume Protocol (Auto-Resume)
+
+Session 重启后 ws-goal step 0 检测流程：
+
+1. 扫描 `.aiws/goals/*.state.json`
+2. 读取每个 state.json 的 `status` 字段
+3. 若发现 `status=active` 或 `status=paused`：
+   - **单个中断 goal**：直接从最后一个非 complete checkpoint 恢复，**不询问用户**
+     - 输出恢复通知："↻ 检测到中断 goal <id>（<phase>），正在恢复..."
+     - 设置 `current_phase` 到对应 phase
+     - 注入 §7.5 continuation context 并恢复执行
+   - **多个中断 goal**：列出所有可恢复 goal 让用户选一个，选定后按单人流程 auto-resume
+
+恢复后 phase 重试逻辑：
+- 从 checkpoint 中最后一个非 complete 的 phase 开始
+- 已 complete 的 phase 不重新执行
+- 每个 phase 最多重试 3 次（由 `attempts` 字段追踪）
+- 重试为默认行为（**不提供 skip 选项**），重试耗尽后自动暂停并 handoff
+- 若 checkpoint 没有记录（旧格式 .md 且无 .state.json），降级为从 PHASE 0 全量重跑
+
+> 设计原则：用户执行 ws-goal 即代表意图明确——继续未完成的工作。重复询问"是否要继续"增加摩擦、不增加价值。仅在无法自动决策时（如多个冲突 goal）才需要用户介入。
+
+### 7.5 Continuation Context Template
+
+当 session 重启后检测到 paused goal 并 auto-resume 时，ws-goal 技能注入以下上下文：
+
+```
+## Resumed Goal: <goal-id>
+
+- Objective: <outcome from .md>
+- Resume Point: Phase <X> (<phase-name>)
+- Previous Error: <error from checkpoint>
+- Attempts remaining: <3 - attempt_count>
+
+Instructions: Continue from the failed phase. Do NOT redo completed phases.
+```
+
+此模板作为 prompt 上下文由 ws-goal 技能注入，不写入独立文件。
+
+### 7.6 Migration from Existing Goals
+
+检测到旧格式 goal（只有 .md，无 state.json）时的处理：
+
+1. 读取 `.aiws/goals/<goal-id>.md` 的 `ws_goal.state` 和 `iteration` 字段
+2. 如果 status 为 active 或 paused：
+   - 自动生成 `.state.json`
+   - 所有 checkpoints 设为 pending
+   - `current_phase` 设为 null（需全量重跑）
+3. 如果 status 为 complete 或 archived：
+   - 不生成 state.json（不需要恢复）
+
+### 7.7 Limitations
+
+- state.json 是当前工作区本地文件，不支持跨设备同步
+- 如果用户手动删除或修改 state.json，ws-goal 降级为全量重跑（可重新生成）
+- 并行执行多个 goal 时，state.json 独立管理，互不依赖
+- state.json 不包含 secrets 或凭证信息

package/package.json

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

package/templates/workspace/.aiws/ws-goal-intake-schema.json

@@ -0,0 +1,174 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "ws-goal-intake-schema.json",
+  "title": "WS-Goal Intake State",
+  "description": "Machine-readable state for PHASE 0 (INTAKE) of ws-goal workflow. Persisted between AI agent sessions to enable recovery from interrupted intake processes.",
+  "type": "object",
+  "required": [
+    "version",
+    "intake_id",
+    "status",
+    "created_at",
+    "updated_at",
+    "questions"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Reference to this schema file"
+    },
+    "version": {
+      "type": "string",
+      "enum": ["1"],
+      "description": "Schema version for forward compatibility"
+    },
+    "intake_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
+      "description": "Slug matching the corresponding .intake.md file in .aiws/plan/"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "in_progress", "paused", "complete", "archived", "timed_out"],
+      "description": "Intake state machine status. timed_out = auto-detected when background tasks exceed max_idle_minutes"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when this intake state was first created"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last state update"
+    },
+    "questions": {
+      "type": "object",
+      "required": ["total", "frozen", "open"],
+      "properties": {
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total number of intake questions"
+        },
+        "frozen": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of questions with confirmed answers (status=frozen)"
+        },
+        "open": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of remaining unanswered questions"
+        },
+        "items": {
+          "type": "array",
+          "description": "Per-question detail list for question-level recovery. Counters (total/frozen/open) MUST equal derived values from items when present.",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "status"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Question identifier, e.g. Q1, Q2"
+              },
+              "title": {
+                "type": "string",
+                "description": "Short question title for display in recovery options"
+              },
+              "status": {
+                "type": "string",
+                "enum": ["pending", "in_progress", "frozen", "skipped"],
+                "description": "Per-question status"
+              },
+              "frozen_at": {
+                "type": ["string", "null"],
+                "format": "date-time",
+                "description": "When this question was frozen (if status=frozen)"
+              },
+              "answer_summary": {
+                "type": ["string", "null"],
+                "description": "Optional brief summary of the answer for context preservation"
+              }
+            }
+          }
+        }
+      }
+    },
+    "current_question": {
+      "type": ["string", "null"],
+      "description": "The question currently being processed, used for resume positioning"
+    },
+    "background_tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["task_id", "type", "description", "started_at", "status"],
+        "properties": {
+          "task_id": {
+            "type": "string",
+            "description": "Background task ID (bg_...)"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["explore", "librarian", "oracle", "general"],
+            "description": "Subagent type used"
+          },
+          "description": {
+            "type": "string",
+            "description": "Brief description of what this task was searching for"
+          },
+          "started_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the task was launched"
+          },
+          "status": {
+            "type": "string",
+             "enum": ["running", "completed", "failed", "orphaned", "timed_out"],
+             "description": "Current task status. timed_out = exceeded max_idle_minutes threshold"
+          },
+          "completed_at": {
+            "type": ["string", "null"],
+            "format": "date-time",
+            "description": "When the task completed (if applicable)"
+          },
+          "summary": {
+            "type": ["string", "null"],
+            "description": "Optional brief summary of task results"
+          }
+        }
+      },
+      "description": "Tracked background subagent tasks launched during intake"
+    },
+    "max_idle_minutes": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 30,
+      "description": "Idle timeout threshold in minutes. Background tasks with started_at older than this are auto-marked timed_out on next detection scan."
+    },
+    "last_error": {
+      "type": ["string", "null"],
+      "description": "Most recent error message, if any"
+    },
+    "session_metadata": {
+      "type": "object",
+      "properties": {
+        "last_agent": {
+          "type": "string",
+          "description": "The agent type that last updated this state"
+        },
+        "message_count": {
+          "type": "integer",
+          "description": "Approximate message count in the session that created this state"
+        },
+        "last_activity_at": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "Last user activity timestamp"
+        }
+      },
+      "description": "Debugging metadata, no programmatic dependencies"
+    }
+  }
+}

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

@@ -67,4 +67,21 @@ git commit -m "<message>"
 - `下一步（Next）:` 若存在 submodule 改动，先提示用户进入 submodule 提交
 <!-- AIWS_MANAGED_END:opencode:ws-commit -->
 
+---
+description: 提交：门禁/审计后提交（submodule 感知）
+---
+# ws-commit
+
+Thin CLI wrapper. Delegates to `aiws commit`.
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws commit
+elif command -v aiws >/dev/null 2>&1; then
+  aiws commit
+else
+  npx @aipper/aiws commit
+fi
+```
+
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -55,4 +55,21 @@ description: 交付：submodules+superproject 分步提交并安全合并回 bas
 - `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）
 <!-- AIWS_MANAGED_END:opencode:ws-deliver -->
 
+---
+description: 交付：submodules+superproject 分步提交并安全合并回 base
+---
+# ws-deliver
+
+Thin CLI wrapper. Delegates to `aiws deliver`.
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws deliver
+elif command -v aiws >/dev/null 2>&1; then
+  aiws deliver
+else
+  npx @aipper/aiws deliver
+fi
+```
+
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -76,4 +76,21 @@ fi
 - 不执行破坏性命令。
 <!-- AIWS_MANAGED_END:opencode:ws-finish -->
 
+---
+description: 收尾：fast-forward 合并并把 submodule 并回目标分支后顺序 push
+---
+# ws-finish
+
+Thin CLI wrapper. Delegates to `aiws finish`.
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws finish
+elif command -v aiws >/dev/null 2>&1; then
+  aiws finish
+else
+  npx @aipper/aiws finish
+fi
+```
+
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -25,15 +25,19 @@ ws-goal 只做三件事，不做更多：
 
 ## 执行流程
 
-0) 检查 `.aiws/goals/` 目录：
+0) 检查 `.aiws/goals/` 目录（先扫描 `.state.json`，再扫描 `.md`）：
    a) 若用户仅查询状态（无明确目标），列出所有 goal 文件及其 status 字段，然后结束。
-   b) 若存在 status=active 或 status=paused 的 goal 文件，优先读取并恢复执行，不再新建 goal。
+   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 后全量重跑
 
 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`
@@ -106,15 +110,16 @@ ws-goal 只做三件事，不做更多：
         [LOW]  .aiws/journal/ 日志文件 — 无影响
         ════════════════════════
         ```
-     g) 展示报告后要求用户选择：
-        - **继续** → 进入 step 5
-        - **暂停** → goal status=paused，报告写入 Audit Trail，结束
-        - **先清理** → goal status=paused，输出清理建议步骤，结束
-     用户未确认前，不得进入 step 5。
+      g) 展示报告后要求用户选择：
+         - **继续** → 更新 state.json checkpoint `ws_analysis=complete`，进入 step 5
+         - **暂停** → state.json status=paused，报告写入 Audit Trail，结束
+         - **先清理** → state.json status=paused，输出清理建议步骤，结束
+      用户未确认前，不得进入 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 继续」或「暂停」。
+     前置条件：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。
 
 5a) **Check for Groups**：读取 goal 文件，检查是否定义了 `Groups` 区域。
     - 若 goal **不含** groups → 走单组 phase-level pipeline（step 5b-5g）

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

@@ -23,4 +23,21 @@ sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
 - 若是历史/异常场景尚未归档，再手工运行 `/p-aiws-change-archive`。
 <!-- AIWS_MANAGED_END:opencode:ws-handoff -->
 
+---
+description: 交接：查看归档 change 的 handoff.md（标准由 aiws change finish --push 自动归档生成）
+---
+# ws-handoff
+
+Thin CLI wrapper. Delegates to `aiws handoff`.
+
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws handoff
+elif command -v aiws >/dev/null 2>&1; then
+  aiws handoff
+else
+  npx @aipper/aiws handoff
+fi
+```
+
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -9,7 +9,7 @@ description: 目标协议：设定可审计的 goal 目标；依赖链预检；
 目标：
 - 将用户需求转化为可审计的 goal 目标，按 ws-goal-contract.md 的目标模板写入目标文件。
 - 依赖链预检：阻断"死 change 阻塞下游"这类 chain 问题。
-- 管道委托：预检通过后将 goal 拆分为 phase-level 子任务（PLAN→DEV→REVIEW→FINISH），每个 phase 委托给独立轻量子 agent，主 session 编排调度与验证。
+- 管道委托：预检通过后将 goal 拆分为 phase-level 子任务（INTAKE→PLAN→DEV→REVIEW→FINISH），每个 phase 委托给独立轻量子 agent，主 session 编排调度与验证。
 - 完成审计：claim done 时验证 outcome 真伪。
 
 ws-goal 不做的事：
@@ -21,12 +21,69 @@ ws-goal 不做的事：
 1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
 
 执行流程：
-0) 检查 `.aiws/goals/` 目录：
+
+### PHASE 0 — INTAKE（对抗式目标审问）
+
+在写 goal 文件前，先对目标本身做对抗式审问：
+
+0) 检查 `.aiws/goals/` 目录（先扫描 `.state.json`，再扫描 `.md`）：
    a) 若用户仅查询状态（无明确目标），列出所有 goal 文件及其 status 字段，然后结束。
-   b) 若存在 status=active 或 status=paused 的 goal 文件，优先读取并恢复执行，不再新建 goal。
+   b) 扫描 `.aiws/goals/*.state.json`：
+      - 读取每个 state.json 的 `status` 字段
+      - 若发现 `status=active` 或 `status=paused` 的 state.json：
+        i.  读取对应 `.aiws/goals/<goal-id>.md` 文件获取完整目标描述
+        ii. 输出 goal 摘要：goal_id, status, current_phase, checkpoint 状态, error（若有）
+        iii. 输出恢复选项：
+             - （a）从失败的 phase 继续
+             - （b）跳过该 phase（标记 complete，继续下一个）
+             - （c）暂停并 handoff
+        iv. 用户选择后：
+             - 若选择 a）→ 设置 `current_phase` 到最近一个非 complete 的 checkpoint，注入 §7.5 continuation context 并恢复执行
+             - 若选择 b）→ 标记当前 failed phase 为 complete，设置 `current_phase` 到下一个 phase
+             - 若选择 c）→ 输出 handoff 建议，结束
+        v. 若用户选择全量重跑 → 重置 state.json 所有 checkpoints 为 pending，status=active，从头开始
+   c) 若未找到 state.json 但有 status=active 或 status=paused 的 .md 文件（旧格式迁移）：
+      - 按 §7.6 迁移策略处理（自动生成 state.json 后全量重跑）
 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) **Workspace State Analysis**：分析 dirty/submodule/change artifacts/git 状态，输出影响等级报告，用户确认后才能继续。参考 `/ws-goal` command 的 step 4.5 完整流程。
-6) **Phase-Level Pipeline Delegation**：预检 + 分析通过后，将 goal 拆分为 PLAN→DEV→REVIEW→FINISH 四个 phase 顺序执行，每个 phase 委托给独立轻量子 agent，主 session 验证每个 phase 产出后决定继续/重试/暂停。参考 `/ws-goal` command 的 step 5 完整流程。
+2) **运行改进后的 `/ws-intake`**（对抗式审问模式）对 goal objective 做逐条审问：
+   - 推荐答案模式：对事实类/选择类问题先给出推荐（参考 `recommendAnswers` 配置）
+   - 决策树分支遍历：每条回答展开对应子分支，直到所有叶节点被消费
+   - 对抗式审问层：自动探查代码库寻找矛盾信号，挑战隐含假设，探测边缘案例
+3) **产出 intake 草案**：写入 `plan/<timestamp>-<slug>.intake.md`，包含完整的决策树遍历记录
+4) **阻塞检查**：若 intake 草案中存在 `UNRESOLVED_BRANCH`，输出阻塞报告并暂停。用户必须显式确认忽略或补充信息后才能进入 PHASE 1。
+5) 将 intake 审问结果（已冻结的目标范围、约束、边界）传递到后续 goal objective 定义。
+5a) **记录 checkpoint**：更新 `.aiws/goals/<goal-id>.state.json` → checkpoint `intake=complete` + `completed_at`
+
+### PHASE 1 — GOAL 定义
+
+6) 接受用户输入的 goal objective，明确目标范围与验收标准（基于 PHASE 0 的 intake 产出）。
+7) 按 ws-goal-contract.md 的目标模板生成目标文件，写入 `.aiws/goals/<goal-id>.md`。
+7a) 同时创建 `.aiws/goals/<goal-id>.state.json`（§7.2 格式），初始状态：
+    - `status`: "active"
+    - `current_phase`: "intake"
+    - 所有 checkpoints: `{"status": "pending", "attempts": 0, "completed_at": null, "error": null}`
+8) 输出 completion audit checklist，列出每个 goal 的完成标准与验证方式。
+8a) **记录 checkpoint**：更新 `.aiws/goals/<goal-id>.state.json` → checkpoint `goal_def=complete` + `completed_at`
+
+### PHASE 2 — 预检与管道委托
+
+**Checkpoint 记录规则**（贯穿整个 Phase 2）：
+- 每个 phase 边界必须更新 `.aiws/goals/<goal-id>.state.json`：
+  - 进入 phase → `current_phase=<phase>`，对应 checkpoint `status=in_progress`
+  - 完成 phase → checkpoint `status=complete` + `completed_at=ISO8601`
+  - 失败 → checkpoint `status=failed` + `error=<message>`
+  - 暂停 goal → `status=paused`（全局）
+
+8b) **依赖链预检**：按 ws-goal-contract.md §2.4 执行上游依赖链健康检查。
+    - 通过后：更新 checkpoint `dep_check=complete`
+    - 阻断时：更新 state.json `status=paused`，记录 error，结束
+
+9) **Workspace State Analysis**：分析 dirty/submodule/change artifacts/git 状态，输出影响等级报告，用户确认后才能继续。参考 `/ws-goal` command 的 step 4.5 完整流程。
+   - 通过后：更新 checkpoint `ws_analysis=complete`
+10) **Phase-Level Pipeline Delegation**：预检 + 分析通过后，将 goal 拆分为 PLAN→DEV→REVIEW→FINISH 四个 phase 顺序执行，每个 phase 委托给独立轻量子 agent，主 session 验证每个 phase 产出后决定继续/重试/暂停。参考 `/ws-goal` command 的 step 5 完整流程。
+     - 每个 pipeline phase 开始前：更新 state.json `current_phase`，对应 checkpoint `status=in_progress`
+     - Granularity Gate（c-i）：在 DEV 委托前运行；检查 granularity_ok=true、design_context 和 internal_tasks 非空
+     - 粒度不达标（granularity_ok != true）→ 阻断并输出报告，暂停 goal
+     - 粒度达标后进入 DEV delegation（c-ii）
+     - 每个 pipeline phase 通过后：更新 checkpoint `status=complete` + `completed_at`
+    - 每个 pipeline phase 失败后：更新 checkpoint `status=failed` + `error`，递增 `attempts`

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

@@ -3,6 +3,15 @@ name: ws-intake
 description: 使用时机：新需求需要逐条澄清、冻结问题时。触发词：需求澄清、intake、冻结问题、前期沟通。注意：需求已冻结直接进 ws-plan。
 ---
 
+## 配置
+
+本 skill 支持以下配置项，用户可在 `.opencode/opencode.json` 的 `skills.ws-intake` 中覆盖：
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `recommendAnswers` | boolean | true | 提问时先给出推荐答案，用户确认即可。逐问题类型标注是否可推荐 |
+| `adversarial` | boolean | true | 启用对抗式审问：挑战假设 + 自动探查代码库寻找矛盾 |
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
@@ -91,18 +100,37 @@ Must-have / Should-have / Nice-to-have 三层分类，明确 scope 底线。
 2) 若存在最新 `plan/*.intake.md`，先续写它；否则新建一份 intake 草案。
 3) 把当前任务拆成 `Open Questions`，状态只允许 `open / in_discussion / frozen / deferred`。
 
-4) **探码后问**：在对每个 Open Question 提问前，先 spawn `explore` agent 探查代码库。如果代码库中已有足以回答该问题的信息，在 intake 草案的相应章节记录该信息，并跳过该问题的提问。只有当代码库无法回答时，才把该问题交给用户。记录每个问题属于以下哪一类：
-   - `codebase: answered` — 代码库已可回答，跳过提问
-   - `codebase: partial` — 代码库有部分信息，补充提问未覆盖的部分
-   - `user: required` — 必须问用户
+4) **对抗式探码后问**：在对每个 Open Question 提问前，先 spawn `explore` agent 探查代码库，执行以下三层操作：
+   a) **事实探查**：代码库中是否有足以回答该问题的信息？如果有，记录到 intake 草案并跳过提问。
+      - `codebase: answered` — 跳过提问
+      - `codebase: partial` — 补充提问未覆盖部分
+      - `user: required` — 必须问用户
+   b) **矛盾检索**：主动搜索代码库中与用户可能假设相矛盾的代码模式。例如用户说"这个功能很简单"，但代码库显示相关模块有 20 个调用点——这是一个矛盾信号，必须在提问时点出。
+   c) **边缘案例探测**：搜索边界条件模式——空值、并发写入、依赖不可用、超大输入等，在提问时自动补充边缘问题。
 
 5) 每次只推进 1 个当前问题，并显式输出：
    - `Current question:`
    - `Why it matters:`
    - `Current options / current understanding:`
-    - `Exit condition:`
+   - `Recommended answer:` — 如果该问题类型可推荐（事实确认类、二选一/多选一、最佳实践类），先给出推荐答案。开放型/创意型问题标注 `recommendation: N/A`
+   - `Exit condition:`
 - 每个问题独立线程：在未标记 frozen/deferred 前，不进入下一题。问答往返不限轮数，但一次只处理一个维度的决策。
-6) 若用户一次提出多个问题，必须显式排队：列出所有问题编号，按顺序逐个处理；不得同时推进多个问题的讨论。输出格式：`Queued questions: #1, #2, ...  | Current: #1`
+- **推荐答案模式**：对事实确认类、二选一/多选一、最佳实践类问题，agent 先在 `Recommended answer` 中给出推荐，用户只需确认或修正。推荐答案必须来自代码库探查、规范文件或公认最佳实践，不做编造。若 `recommendAnswers: false`（配置关闭），则不显示推荐答案直接提问。
+6) **决策树分支遍历**（替代扁平队列）：
+   - 问题组织为树而非列表：每个答案可能产生子问题（分支），每个分支必须走到叶节点（无子问题）才算完成。
+   - 交互式遍历：用户回答后，根据答案展开对应子分支；下一个问题由当前回答决定，而非预定顺序。
+   - 追踪状态：使用缩进树格式维护当前遍历位置：
+     ```
+     Tree:
+       ├─ Q1 (frozen)
+       │  ├─ Q1.1 (frozen)
+       │  └─ Q1.2 ← current
+       ├─ Q2 (pending, blocked by Q1.2)
+       └─ Q3 (pending)
+     ```
+   - 分支耗尽判据：所有叶节点均标记 `frozen` 或 `deferred` 时，intake 完成。
+   - `UNRESOLVED_BRANCH`：如果某分支因外部依赖或信息不足无法继续，标记为 `UNRESOLVED_BRANCH` 并写入 intake 草案的 `Decision Tree` 小节。goal 文件会读取此标记作为阻塞项。
+   - 用户一次性提出多个问题仍需要排队，但队列中的问题按决策树优先级重排（先主干、再分支）。
 7) 每轮都要把 intake 草案写盘，至少包含：
    - `Deep Interview` — 9 维分析：Why/非目标/影响面/假设/替代方案/约束/优先级/成功度量/风险
    - `Context`