@aipper/aiws-spec 0.0.24 → 0.0.26

package/docs/workflow-stage-contracts.md

@@ -0,0 +1,70 @@
+# workflow-stage-contracts
+
+<!-- Generated from packages/spec/docs/workflow-stage-contracts.json by scripts/sync-workflow-stage-contracts.mjs. Do not hand edit. -->
+
+## 目的
+
+这份文档把 `aiws` 核心 `ws-*` workflow 的阶段契约写成统一真值，避免不同工具、不同协作者把同一个入口用成不同语义。
+
+重点不是“命令名长什么样”，而是每个阶段必须收什么输入、产出什么结果、在什么情况下必须停止。
+
+## 标准链路
+
+默认链路：
+
+`ws-preflight` -> `ws-plan` -> `ws-plan-verify` -> `ws-dev` -> `ws-review` -> `ws-commit` -> `ws-deliver` -> `ws-finish` -> `ws-handoff`
+
+说明：
+- ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。
+- ws-finish 用于 fast-forward 合并、push、worktree cleanup，并在完整 finish 后自动归档 change。
+- ws-handoff 通常在 finish 自动归档后使用，用于查看/补充归档交接说明。
+- 若存在独立 change worktree，治理信号应优先读取该 worktree；若 worktree metadata 已 stale，则降级为 warning 并回退到当前 worktree。
+
+## 阶段表
+
+| Stage | 目标 | 必需输入 | 必需输出 | 阻断条件 | 下一步 |
+| --- | --- | --- | --- | --- | --- |
+| `ws-preflight` | 对齐真值文件与协作约束 | 项目根；AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md | Root / Found / Missing / Key rules / Next | 无法确定项目根；真值缺失 | ws-plan 或 ws-dev |
+| `ws-plan` | 建立 change 绑定并落盘计划 | 任务描述；真值文件；proposal.md（若存在） | plan/...；Bindings；Verify；Risks；Evidence；Next | 绑定不清；dirty 工作区无法安全建 context；无法写盘 | ws-plan-verify |
+| `ws-plan-verify` | 检查计划是否满足严格契约 | plan/...；proposal.md；当前 change | Quality gate；Fix list；可执行最小计划摘要 | strict 校验失败；无法定位 change | 修计划后重跑或进入 ws-dev |
+| `ws-dev` | 实施最小改动并验证 | 真值文件；归因目标；计划（medium/complex） | Changed；Verify；Evidence；Next | 无法归因；没有验证入口；change 上下文不安全 | ws-review / ws-commit |
+| `ws-review` | 审计规范、风险与验证完整性 | 当前 diff；验证结果；真值文件 | review 文件；Top risks；Next | 无改动可审；无法写审计证据 | ws-commit 或修复后重审 |
+| `ws-commit` | 串联 review、validate、commit 确认 | staged diff；review 证据；validate stamp；用户确认的 message | Evidence；Context；Commit | 无 staged changes；submodule dirty；validate 失败；message 未确认 | ws-deliver / ws-finish |
+| `ws-deliver` | 在 submodule 场景下完成顺序提交与证据收敛 | change 上下文；.gitmodules；submodules.targets；各 repo 状态 | submodule 提交摘要；superproject 提交摘要；Evidence | submodule 真值不完整；不在正确 change；commit 未确认 | ws-finish |
+| `ws-finish` | 安全合并、push、cleanup，并自动归档 | 干净工作区；已提交的 change；push 目标；submodule 真值（若有） | Merge；Push；Worktree cleanup；Archive/Handoff；Evidence | dirty 工作区；ff 失败；submodule 无法安全 push | ws-handoff |
+| `ws-handoff` | 查看/补充可接力的归档交接说明 | 已归档的 change | changes/archive/.../handoff.md；Next | 无法定位已归档 change；handoff 无法生成或读取 | 新 change 通过 Depends_On 接力 |
+
+## 统一规则
+
+- 每个阶段都必须回指真值文件或 change 工件，不能只依赖会话上下文。
+- 每个阶段都必须有明确输出，不能只给“建议继续”而不留下工件或证据。
+- 遇到阻断条件时必须停止，不能为了推进速度跳过门禁。
+- 如果一个阶段没有留下可审计路径，它就不算真正完成。
+- `ws-finish` 只有在 merge、push、cleanup、archive 都完成后才算完成；仅本地 merge 成功不等于可进入 `ws-handoff`。
+
+## 证据约定
+
+最少证据集合：
+
+- planning：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`
+- review：`changes/<change-id>/review/...` 或 `.agentdocs/tmp/review/...`
+- validate：`.agentdocs/tmp/aiws-validate/*.json`
+- deliver / finish：`changes/<change-id>/evidence/...`、`state`、merge / push 结果
+- handoff：`changes/archive/.../handoff.md`
+
+补充：
+- tmp review 证据可以作为“进入 commit gate”的临时治理信号，但在交付前应通过 `aiws change evidence` 收敛为持久 review 证据。
+- finish 生命周期建议区分“本地开始”和“完整完成”两类信号，避免仅凭本地 merge 就误导到 handoff。
+
+## 与产品定位的关系
+
+这份阶段契约文档是 `aiws` “治理内核”定位的直接落点：
+
+- `packages/spec/` 继续作为规则真值层
+- `ws-*` 阶段契约是工作流治理层
+- `docs/workflow-stage-contracts.json` 是运行时阶段契约的机器可读真值
+- `docs/workflow-governance-rules.json` 是运行时阶段推断的机器可读真值
+- CLI / tool-native files 是执行与分发层
+- review / validate / handoff 等工件属于证据与审计层
+
+如果未来要吸收新的 skill、协同角色或外部 workflow，优先判断它能否被映射到这张阶段表；不能稳定映射的能力，不应直接成为核心真值。

package/docs/workflow-stage-contracts.schema.json

@@ -0,0 +1,98 @@
+{
+  "type": "object",
+  "required": [
+    "version",
+    "title",
+    "description",
+    "purpose",
+    "standardChain",
+    "notes",
+    "stages",
+    "unifiedRules",
+    "evidence",
+    "positioning"
+  ],
+  "properties": {
+    "version": { "type": "integer" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "purpose": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "standardChain": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1, "pattern": "^ws-[a-z0-9-]+$" }
+    },
+    "notes": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["stage", "goal", "requiredInputs", "requiredOutputs", "blockers", "next"],
+        "properties": {
+          "stage": { "type": "string", "minLength": 1, "pattern": "^ws-[a-z0-9-]+$" },
+          "goal": { "type": "string", "minLength": 1 },
+          "requiredInputs": { "type": "string", "minLength": 1 },
+          "requiredOutputs": { "type": "string", "minLength": 1 },
+          "blockers": { "type": "string", "minLength": 1 },
+          "next": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "unifiedRules": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["intro", "minimum", "notes"],
+      "properties": {
+        "intro": { "type": "string", "minLength": 1 },
+        "minimum": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["label", "value"],
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "value": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+          }
+        },
+        "notes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": false
+    },
+    "positioning": {
+      "type": "object",
+      "required": ["intro", "layers", "closing"],
+      "properties": {
+        "intro": { "type": "string", "minLength": 1 },
+        "layers": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "closing": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

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

package/templates/workspace/.agents/skills/using-aiws/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: using-aiws
+description: 默认 workflow bootstrap/router：先读真值，再路由到正确的 ws-* 入口
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 作为默认入口，先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 先判定当前任务属于哪个 workflow，再进入具体 `ws-*` skill
+- 若任务意图、归因或验证入口不明确：先澄清，不直接进入实现
+
+阶段定位：
+- bootstrap/router 阶段；负责 workflow 分流，而不是直接完成实现。
+
+必需输入：
+- 当前任务描述
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+- 若已存在：当前 `change/<change-id>` 上下文、`plan/...`、`changes/<change-id>/...`
+
+必需输出：
+- `Root:` 当前项目根
+- `Found:` 实际读取到的真值文件
+- `Task intent:` 当前任务意图分类
+- `Binding:` `Req_ID` / `Problem_ID` / change 上下文是否清晰
+- `Route:` 选中的下一步 skill
+- `Why:` 选择该 route 的原因
+- `Next:` 进入对应 skill，或先提澄清问题
+
+阻断条件：
+- 无法确定项目根目录
+- 缺失任一真值文件
+- 无法明确当前任务意图
+- 无法明确归因或验证入口，且不能安全推断
+
+完成判定：
+- 已经明确给出单一路由结果，并进入对应 `ws-*` skill；或已提出关键澄清问题并停止。
+
+执行步骤（强制）：
+1) 先遵守 `$ws-preflight` 的真值读取要求：
+   - 定位项目根目录
+   - 读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+   - 输出 `Root:` / `Found:` / `Missing:`
+2) 若缺失任一真值文件：
+   - 不进入实现
+   - 输出下一步：先 `aiws init .`（或 `npx @aipper/aiws init .`），然后重新执行 `$using-aiws`
+   - 此时 route 视为 `$ws-preflight`
+3) 根据 `packages/spec/docs/workflow-router-rules.json` 判定任务属于哪一类：
+   - 需求/验收/合同变更：`$ws-req-review`
+   - 评审/审计/找风险：`$ws-review`
+   - finish / merge / push / cleanup：`$ws-finish`
+   - handoff / archive summary：`$ws-handoff`
+   - 中大型实现、需要方案、需要 change/worktree：`$ws-plan`
+   - 小步明确实现/修复/配置调整：`$ws-dev`（若是 simple/local 单点修复，且用户明确希望走轻量入口，可显式进入 `$ws-dev-lite`）
+4) 若任务意图或归因不明确：
+   - 只问 1-3 个关键澄清问题
+   - 明确写出缺的是什么：意图、`Req_ID` / `Problem_ID`、verify、change 上下文
+   - 然后停止；不要直接写代码
+5) 若已确定 route：
+   - 先输出：
+     - `Task intent:`
+     - `Binding:`
+     - `Route:`
+     - `Why:`
+   - 若 `Route: $ws-dev` 且任务属于 simple/local 单点修复：
+     - `Next:` 可优先进入 `$ws-dev-lite`
+   - 否则：
+     - `Next:` 进入对应主 skill
+   - 然后在同一轮中继续遵循对应 skill 的契约
+6) 路由约束：
+   - router 自己不是实现阶段；不要在给出 route 之前直接改代码
+   - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
+   - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
+7) 若执行过程中发现复杂度升高：
+   - 从 `$ws-dev` 回退到 `$ws-plan`
+   - 从 `$ws-finish` 回退到前置门禁而不是硬推完成
+
+输出模板：
+- `Root:` <path>
+- `Found:` <files>
+- `Task intent:` <分类>
+- `Binding:` <清晰 / 缺失项>
+- `Route:` <$ws-... 或 clarify>
+- `Why:` <一句到三句>
+- `Next:` <继续执行对应 skill，或提出澄清问题>

package/templates/workspace/.agents/skills/ws-commit/SKILL.md

@@ -19,7 +19,33 @@ description: 提交（当前分支可直提；submodule 感知；先审计/门
 - 不写入任何 secrets
 - 检测到 submodule 有未提交改动时，不允许直接提交 superproject（先处理 submodule）
 - commit message 优先使用中文（命令/路径/代码标识符保持原样不翻译）；格式建议：`<类型>: <简述>`（例如 `修复: 登录页空指针`、`功能: 新增 submodule targets 校验`、`重构: 提取共享脚本`）
-- 若启用了 `.githooks/commit-msg`：默认会提示优先中文；只有在 `git config aiws.commitMessagePolicy strict` 时才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
+- 若启用了 `.githooks/commit-msg`：默认按仓库角色区分
+  - superproject / root 仓库（存在 `.gitmodules`）默认允许自由 commit message
+  - submodule / 普通仓库默认提示优先中文
+  - 只有在 `git config aiws.commitMessagePolicy strict` 时才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
+
+阶段定位：
+- commit gate；负责在提交前收敛 review、validate 和 message 确认，不允许跳过 hooks。
+
+必需输入：
+- 当前分支与 staged diff
+- `$ws-review` 生成的审计证据
+- `aiws validate . --stamp` 生成的校验证据
+- 用户确认后的 commit message
+
+必需输出：
+- `证据（Evidence）:` review 文件路径 + validate stamp 路径
+- `上下文（Context）:` 当前分支、submodule 检测结果、阻断原因（若有）
+- `提交信息（Commit）:` 最终提交信息
+
+阻断条件：
+- 没有 staged changes
+- submodule 工作区不干净或 detached 处理不完整
+- 用户未确认 commit message
+- validate 失败
+
+完成判定：
+- 提交已完成，证据路径明确，且没有通过 `--no-verify` 绕过门禁。
 
 执行步骤（建议）：
 1) 运行 `$ws-preflight`（确保真值文件就绪）。

package/templates/workspace/.agents/skills/ws-delegate/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ws-delegate
+description: 原生多 agent 委托入口（Codex 优先；先定义角色/边界/工件/降级，再决定是否委托）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 治理约束下，只有在任务已绑定且 scope 可控时，才使用当前工具的原生多 agent / sub-agent 能力；否则明确降级为单 agent + 协同工件模式。
+
+阶段定位：
+- implementation / review 的辅助入口；它不是独立 workflow 阶段，也不能绕过 `ws-plan`、`ws-dev`、`ws-review`、`ws-finish`。
+
+必需输入：
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- delegation contract：`packages/spec/docs/workflow-delegation-contracts.md`
+- 当前任务已绑定 `Req_ID` / change / Verify 入口
+- 拟委托子任务的角色划分、读写边界、artifact 目标与 fallback
+
+必需输出：
+- `Delegation Plan:` 逐项写清 role / task / readScope / writeScope / artifactTargets / fallback
+- `Execution Mode:` 明确是 `native multi-agent` 还是 `fallback single-agent`
+- `Evidence:` 委托产物路径（`analysis/` / `patches/` / `review/` / `evidence/`）
+- `Next:` 收敛后应回到 `ws-dev`、`ws-review`、`ws-commit` 或 `ws-finish`
+
+阻断条件：
+- 无法绑定到 `Req_ID` / change / Verify
+- 没有明确的 `writeScope` / `artifactTargets`
+- 当前工具缺少稳定 native delegation 能力，且你又不能接受降级执行
+- 任务规模太小，引入委托只会增加复杂度
+
+完成判定：
+- 已经明确本次是否适合委托
+- 若适合：delegation plan 已声明并执行，产物回收到 AIWS 约定路径
+- 若不适合：已明确降级原因，并回到单 agent 流程继续执行
+
+步骤（建议）：
+1) 先读取真值文件与 `packages/spec/docs/workflow-delegation-contracts.md`，确认这不是“为了多 agent 而多 agent”。
+2) 判断当前任务是否真的需要委托：
+   - 需要并行的只读探索
+   - 需要把实现与审查拆开
+   - 有明确、互不重叠的写入边界
+   - 委托收益大于协调成本
+3) 先写 `Delegation Plan:`，至少包含：
+   - `role`
+   - `task`
+   - `readScope`
+   - `writeScope`
+   - `artifactTargets`
+   - `fallback`
+4) 若当前环境支持原生多 agent：
+   - 优先把探索型工作交给 `explorer`
+   - 只把显式授权的文件范围交给 `worker`
+   - 至少保留一个独立 `reviewer`
+   - 由主 agent / `integrator` 统一收敛结果
+5) 若当前环境不支持，或无法稳定约束 scope：
+   - 明确输出 `Execution Mode: fallback single-agent`
+   - 仍按 AIWS 协同工件约定执行：
+     - `changes/<id>/analysis/`
+     - `changes/<id>/patches/`
+     - `changes/<id>/review/`
+     - `changes/<id>/evidence/`
+6) 不论是否启用原生多 agent，都不要跳过：
+   - 需求归因
+   - 验证命令
+   - review convergence
+   - finish / handoff gate
+
+Codex 优先说明：
+- 若当前环境支持原生多 agent / sub-agent，就按 delegation contract 显式拆 role 与 scope。
+- 若不支持，或你无法保证写边界，直接降级，不临时发明新的 runtime/controller。
+
+安全：
+- 不把 `aiws` 变成统一 orchestrator。
+- 不让 delegated agent 越权写未授权文件。
+- 不把 `patches/` 视为“已合并代码”。

package/templates/workspace/.agents/skills/ws-deliver/SKILL.md

@@ -25,6 +25,28 @@ description: 交付（submodules + superproject 分步提交，并安全合并
    - 该 repo 的 `git diff --staged`
    并让用户确认 commit message（每个 repo 单独确认）。
 
+阶段定位：
+- delivery 阶段；负责在多 repo / submodule 场景下完成顺序提交、证据收敛和最终合并前准备。
+
+必需输入：
+- 当前 `change/<change-id>` 上下文
+- 若存在 submodule：`.gitmodules` + `changes/<change-id>/submodules.targets`
+- 各 repo 当前状态与 staged diff
+
+必需输出：
+- `Submodules:` 每个 submodule 的提交摘要
+- `Superproject:` 主仓库提交摘要
+- `Evidence:` validate stamp 与持久证据路径
+- `Next:` 进入 `$ws-finish` 或 `aiws change finish`
+
+阻断条件：
+- 不在正确的 change 上下文
+- submodule branch / targets 真值不完整
+- 任一 repo 未确认 commit message 或存在未处理冲突
+
+完成判定：
+- submodule 与 superproject 提交都已完成，证据已收敛，且可以安全进入 finish 阶段。
+
 建议流程（按顺序）：
 
 ## 0) submodule branch 真值检查（减少 detached 与人为差异）
@@ -196,10 +218,9 @@ aiws change state "${change_id}" --write
 aiws change finish <change-id> --into <base-branch>
 ```
 
-## F) （可选）归档变更工件
-```bash
-aiws change archive <change-id>
-```
+## F) 归档说明
+- 标准链路下不需要再单独执行 `aiws change archive <change-id>`。
+- 进入 `$ws-finish` 并使用 `aiws change finish --push` 时，会自动完成 archive + handoff。
 
 输出要求：
 - `Submodules:` 每个 submodule 的分支/提交摘要（repo → commit sha → message）

package/templates/workspace/.agents/skills/ws-dev/SKILL.md

@@ -7,6 +7,29 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 
 目标：在 AIWS 约束下完成一个可回放、可验证的小步交付。
 
+阶段定位：
+- implementation 阶段；负责在既定计划/需求绑定下完成最小实现与验证。
+
+必需输入：
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 当前任务的归因目标（`Req_ID` 或 `Problem_ID`）
+- 若为 medium/complex：已通过 `$ws-plan` / `$ws-plan-verify` 的计划
+- 当前 `change/<change-id>` 上下文或等价变更归因
+
+必需输出：
+- `变更文件（Changed）:` 实际改动清单
+- `验证（Verify）:` 实际运行的命令与结果说明
+- `证据（Evidence）:` `plan/...`、`changes/<change-id>/...`、`.agentdocs/tmp/...` 等证据路径
+- `Next:` 若准备提交，建议 `$ws-review` 或 `$ws-commit`
+
+阻断条件：
+- 无法把改动归因到 `REQUIREMENTS.md` 或问题单
+- 没有可复现验证入口
+- 需要创建 change 上下文但当前工作区状态不允许安全切换
+
+完成判定：
+- 改动已落盘、验证已执行或明确未执行原因、证据路径可回放，并可进入 review/commit 阶段。
+
 建议流程：
 1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
    - 若是中大型任务：建议先用 `$ws-plan` 生成 `plan/` 工件，再进入实现（便于可回放与对齐验证入口）。
@@ -117,11 +140,16 @@ cat "${targets}"
 ```
    - 若你明确要在 superproject 直接切分支：`aiws change start <change-id> --hooks --switch`（仅在存在 `.gitmodules` 时有意义；会尝试让 submodules 工作区跟随 superproject 指针）
    - 或手工：`git switch -c change/<change-id>`，并创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）
-3) 如涉及需求调整：先做需求评审（可用 `$ws-req-review`）→ 用户确认后再做需求落盘（可用 `$ws-req-change`）（避免需求漂移）。
-4) 实施最小改动：任何改动都要能归因到 `REQUIREMENTS.md`（验收）或 `issues/problem-issues.csv`（问题）。
-5) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。
-6) 多步任务（≥2 步）：使用 `update_plan` 工具跟踪 `pending → in_progress → completed`，每完成一步立即更新（不要事后批量更新）。
-7) 提交前强制门禁（commit/push hooks 也会阻断）：
+3) 若需要外部 / 子 agent 协作：
+   - 分析结论落盘到 `changes/<change-id>/analysis/`
+   - patch 草案落盘到 `changes/<change-id>/patches/`
+   - 不要把 `patches/` 当成“已应用代码”；主 agent 必须先审查再决定是否采用
+   - 若采用了委托结果，后续在 `ws-review` 或 `changes/<change-id>/review/` 中收敛最终结论
+4) 如涉及需求调整：先做需求评审（可用 `$ws-req-review`）→ 用户确认后再做需求落盘（可用 `$ws-req-change`）（避免需求漂移）。
+5) 实施最小改动：任何改动都要能归因到 `REQUIREMENTS.md`（验收）或 `issues/problem-issues.csv`（问题）。
+6) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。
+7) 多步任务（≥2 步）：使用 `update_plan` 工具跟踪 `pending → in_progress → completed`，每完成一步立即更新（不要事后批量更新）。
+8) 提交前强制门禁（commit/push hooks 也会阻断）：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
   ./node_modules/.bin/aiws validate .
@@ -131,7 +159,8 @@ else
   npx @aipper/aiws validate .
 fi
 ```
-8) 交付收尾（推荐，减少手动 merge 出错）：运行 `$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward 安全合并回目标分支）。
+9) 若使用了协同工件，交付前建议执行 `aiws change evidence <change-id>`，把 review / validate / collaboration summary 收敛到 `changes/<change-id>/evidence/`。
+10) 交付收尾（推荐，减少手动 merge 出错）：运行 `$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward 安全合并回目标分支）。
 
 输出要求：
 - `变更文件（Changed）:` 文件清单

package/templates/workspace/.agents/skills/ws-dev-lite/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ws-dev-lite
+description: 轻量开发（simple/local 单点修复；最小改动 + 最小验证）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不引入完整重流程的前提下，完成一次 simple/local 小问题修复，并保持可验证、可追溯。
+
+定位：
+- `ws-dev` 的轻量入口，不是新的 workflow stage。
+- 适用于单点修复、局部配置调整、明确回归修复；不适用于中大型任务。
+
+适用前提：
+- 目标明确，且能归因到 `Req_ID` 或 `Problem_ID`
+- 验证入口明确，且能做最小可复现验证
+- 一般只影响单文件或紧密相关的小范围文件
+- 不需要先改 `REQUIREMENTS.md`，也不需要先单独做 review
+
+立即升级回主流程的情形：
+- 发现任务其实是 medium/complex、跨模块、跨目录或需要方案设计
+- 无法明确归因、verify、change 上下文
+- 需要新建复杂 change/worktree 或处理 submodule 目标分支真值
+- 修复过程中出现连锁改动、需要补系统性测试或需求调整
+
+默认约束：
+- 先做 `$ws-preflight`
+- 默认不创建 `plan/...`
+- 默认不跑 `$ws-plan-verify`
+- 默认不要求先做双 review
+- 若后续准备提交/交付，仍需进入 `$ws-review` / `$ws-commit` / `$ws-finish`
+
+执行步骤：
+1) 先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
+2) 先判断自己是否真的属于 lite：
+   - 用一句话写清 `Goal`
+   - 用一句话写清 `Why lite`
+   - 若说不清，立刻回退到 `$ws-dev` 或 `$ws-plan`
+3) 在当前 change 上下文内实施最小改动：
+   - 不为“形式完整”额外扩 scope
+   - 不默认补与本问题无关的重构或测试矩阵
+4) 运行最小可复现验证：
+   - 优先使用 `AI_WORKSPACE.md` 已声明的命令
+   - 若只需局部回归，允许运行更窄的验证，但要说明为什么足够
+5) 留下至少一个可追溯证据：
+   - 实际改动文件
+   - 或 `.agentdocs/tmp/...`
+   - 或 `changes/<change-id>/...`
+6) 输出：
+   - `变更文件（Changed）:`
+   - `验证（Verify）:`
+   - `证据（Evidence）:`
+   - `Next:` 若准备提交，进入 `$ws-review` 或 `$ws-commit`
+
+输出要求：
+- 明确说明为什么这是 lite，而不是完整 `ws-dev`
+- 未运行不声称已运行
+- 一旦发现复杂度升高，立刻停止 lite 叙事，切回 `$ws-dev` 或 `$ws-plan`

package/templates/workspace/.agents/skills/ws-finish/SKILL.md

@@ -17,6 +17,30 @@ description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push
 - 若使用 worktree：在目标分支所在 worktree 执行（`aiws change finish` 会提示正确的 worktree）
 - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则无法确定性减少 detached；先运行 `$ws-submodule-setup` 并提交 `.gitmodules`）
 
+阶段定位：
+- finish 阶段；负责把已提交的 change 安全合并回目标分支，并按约束完成 push / worktree cleanup。
+
+必需输入：
+- 干净的当前工作区
+- 已提交完成的 `change/<change-id>`
+- 若存在 submodule：`.gitmodules` 与 `changes/<change-id>/submodules.targets`
+- 当前 push 目标说明（remote / branch）
+
+必需输出：
+- `Merge:` `aiws change finish` 的结果（from / into）
+- `Push:` 实际 remote / branch 或未 push 原因
+- `Worktree cleanup:` 清理结果
+- `Evidence:` validate stamp / evidence / state 路径
+
+阻断条件：
+- 工作区不干净
+- 缺失 submodule branch / targets 真值
+- fast-forward 失败
+- 子模块目标分支无法安全 push
+
+完成判定：
+- change 已安全合并回目标分支，必要的 push 与 worktree cleanup 已完成或明确说明未完成原因。
+
 建议步骤：
 0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
 ```bash
@@ -182,15 +206,4 @@ fi
 ```
 说明：
 - 该命令内部已经包含主仓库 push 成功后安全清理独立 change worktree 的逻辑。
-
-7) （可选）归档变更工件（完成交付后推荐）：
-```bash
-change_id="<change-id>"
-if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws change archive "${change_id}"
-elif command -v aiws >/dev/null 2>&1; then
-  aiws change archive "${change_id}"
-else
-  npx @aipper/aiws change archive "${change_id}"
-fi
-```
+- 当 `--push` 完整成功时，还会自动把 `changes/<change-id>/` 归档到 `changes/archive/...`，生成 `handoff.md`，并补一个 `归档: <change-id>` commit。