@aipper/aiws-spec 0.0.25 → 0.0.26

package/docs/aiws-governance-positioning.md

@@ -2,7 +2,7 @@
 
 ## 一句话定位
 
-`aiws` 不是“把模板分发到 Claude Code / OpenCode / Codex / iFlow 的 CLI 薄封装”，而是以 `packages/spec/` 为单一真值，通过 workflow contracts 统一约束、门禁、协同和证据的 AI workspace 工作流治理系统。
+`aiws` 不是“把模板分发到 Claude Code / OpenCode / Codex 的 CLI 薄封装”，而是以 `packages/spec/` 为单一真值，通过 workflow contracts 统一约束、门禁、协同和证据的 AI workspace 工作流治理系统。
 
 CLI 分发能力依然重要，但它只是治理内核的一层实现，不是产品的全部定义。
 

package/docs/cli-interface.md

@@ -33,11 +33,10 @@
 语义：
 - 在目标仓库根目录写入/补齐模板（默认 `workspace`）。
 - 默认生成 required + optional 文件/目录。
-- 写入/更新 tool-native 文件（默认覆盖 Claude/OpenCode/Codex/iFlow）：
+- 写入/更新 tool-native 文件（默认覆盖 Claude/OpenCode/Codex）：
   - Codex repo skills：`.agents/skills/`
   - Claude Code native skills + compatibility commands：`.claude/skills/` + `.claude/commands/`
   - OpenCode native skills + native commands + legacy compatibility commands：`.opencode/skills/` + `.opencode/commands/` + `.opencode/command/`
-  - iFlow commands：`.iflow/commands/`
 - 写入/更新 `.gitignore` 的 aiws 托管块（其余内容保留）。
 - 生成并写入 `.aiws/manifest.json`：
   - 记录 `template_id/spec_version/aiws_version`
@@ -57,11 +56,12 @@
 - 更新前必须备份将改动的文件到 `.aiws/backups/<timestamp>/`。
 - 只允许更新：
   - `replace_file` 文件：整文件覆盖
-  - `managed_blocks` 文件：仅更新托管块
+  - `managed_blocks` 文件：更新托管块；若文件顶部存在 YAML frontmatter，则同步该 frontmatter
   - required 但不在上述两类中的文件：不改动内容（最多补齐缺失文件）
 - 对于 `managed_blocks`：
   - 若文件在当前模板是新增项（旧 `.aiws/manifest.json` 里不存在该 path）：允许在 `update` 时自动补齐文件，再写入托管块。
   - 若文件在旧 `.aiws/manifest.json` 已存在，但缺失指定 block、marker 不成对、或 marker 被破坏：必须失败（退出码 `2`），不做自动修复（提示用户重新 `aiws init` 或手工修复）。
+  - 若该文件有 YAML frontmatter（例如 command 的 `description`）：允许在保留块外正文的前提下，用模板 frontmatter 覆盖工作区 frontmatter。
 - 更新完成后刷新 `.aiws/manifest.json`（版本与 hash）。
 
 接口（仅定义）：
@@ -309,6 +309,8 @@ Dashboard API（本地只读）：
   - 若 `--push` 后只完成了 push、但 cleanup 仍未完成，命令应返回非 0，并记录 `finish_cleanup_pending` 以提示修复后重跑
   - 旧版错误写入的 `finish_done`（例如 `push: false` 或 `cleanup: not_requested`）不得视为真正完成；CLI 应降级为未完成状态，允许重试
   - 只有完整 finish 成功（兼容旧事件 `finish`，新事件 `finish_done`）后，治理阶段才可进入 `ws-handoff`
+  - 当 `--push` 完整成功时，CLI 应自动执行 archive：将 `changes/<id>/` 移动到 `changes/archive/<YYYY-MM-DD>-<id>/`，生成 `handoff.md`，提交 `归档: <change-id>`，并将该 archive commit push 到同一目标分支
+  - 若 auto-archive commit/push 失败，应报错并保留已归档工件，提示用户继续提交/推送 archive 结果；不应要求重新做 merge
 
 接口（仅定义）：
 - `aiws change finish [<change-id>] [--into <branch> | --base <branch>]`
@@ -367,6 +369,7 @@ Dashboard API（本地只读）：
 
 语义：
 - 严格校验后归档：将 `changes/<id>/` 移动到 `changes/archive/<YYYY-MM-DD>-<id>/`。
+- 默认用于手工恢复 / 历史兼容场景；标准链路下应由 `aiws change finish --push` 自动触发。
 - 默认要求 `tasks.md` 无未勾选任务；`--force` 可跳过（不建议）。
 - 更新 `.ws-change.json`：
   - `archived_at`

package/docs/collaboration-artifacts.md

@@ -41,7 +41,7 @@ changes/<change-id>/
   - `.agentdocs/tmp/review/spec-review.md`
   - `.agentdocs/tmp/review/quality-review.md`
   - `.agentdocs/tmp/review/verify-before-complete.md`
-- `aiws change archive <change-id>` 生成的 `handoff.md` 应概述协同工件，帮助下一次会话快速接手。
+- 标准链路下，由 `aiws change finish --push` 自动归档生成的 `handoff.md` 应概述协同工件；`aiws change archive <change-id>` 仅保留为手工恢复 / 历史兼容入口。
 
 ## 生命周期映射
 

package/docs/spec-contract.md

@@ -51,6 +51,7 @@
 - 对于模板 manifest 声明为 `managed_blocks` 的文件：
   - 若该 path 是模板新增项（旧 `.aiws/manifest.json` 的 `managed` 中不存在），`aiws update` 可自动补齐文件并写入托管块。
   - 若该 path 在旧 `.aiws/manifest.json` 已存在，但缺失指定 block、marker 不成对、或 marker 被破坏，`aiws update` 必须失败（不做自动修复）。
+  - 若该文件带有**顶部 YAML frontmatter**（例如 command 的 `description`），`aiws update` 还应同步该 frontmatter，避免工具元数据漂移；块外其余正文仍保持用户可追加。
 
 ## `.gitignore` 托管块（默认约定）
 
@@ -89,7 +90,7 @@ secrets/test-accounts.json
 - `spec_version`：`@aipper/aiws-spec` 版本
 - `aiws_version`：`@aipper/aiws` 版本
 - `installed_at` / `updated_at`：ISO 8601 UTC 时间
-- `tools`：`["claude","opencode","codex","iflow"]` 的子集
+- `tools`：`["claude","opencode","codex"]` 的子集
 - `managed`：托管面清单（文件级或托管块级 hash）
 
 hash 规则（用于跨平台稳定性）：
@@ -108,7 +109,7 @@ hash 规则（用于跨平台稳定性）：
   "aiws_version": "0.0.0",
   "installed_at": "2026-01-25T00:00:00Z",
   "updated_at": "2026-01-25T00:00:00Z",
-  "tools": ["claude", "opencode", "codex", "iflow"],
+  "tools": ["claude", "opencode", "codex"],
   "managed": [
     { "path": ".githooks/pre-commit", "mode": "replace_file", "sha256": "<sha256>" },
     { "path": ".gitignore", "mode": "managed_blocks", "blocks": { "gitignore": "<sha256>" } }
@@ -125,7 +126,7 @@ hash 规则（用于跨平台稳定性）：
 
 说明：
 - tool-native 文件是 derived 产物；aiws 按模板 `manifest.json` 的 `update` 策略维护（`managed_blocks` 或 `replace_file`）。
-- 默认覆盖：Claude Code / OpenCode / Codex / iFlow。
+- 默认覆盖：Claude Code / OpenCode / Codex。
 
 约定路径（示例；最终以模板 manifest 为准）：
 - Claude Code native：`.claude/skills/*/SKILL.md`（skills）
@@ -134,7 +135,6 @@ hash 规则（用于跨平台稳定性）：
 - OpenCode native commands：`.opencode/commands/p-aiws-*.md`
 - OpenCode legacy compatibility：`.opencode/command/p-aiws-*.md`（command；migration window）
 - Codex：`.agents/skills/*/SKILL.md`（skills）
-- iFlow：`.iflow/commands/aiws-*.toml`（commands）
 
 补充（workflow 入口，同样由模板提供；最终以模板 manifest 为准）：
 - Claude Code native：`.claude/skills/ws-*/SKILL.md`
@@ -143,7 +143,6 @@ hash 规则（用于跨平台稳定性）：
 - OpenCode native commands：`.opencode/commands/ws-*.md`
 - OpenCode legacy compatibility：`.opencode/command/ws-*.md`
 - Codex：`.agents/skills/ws-*/SKILL.md`
-- iFlow：`.iflow/commands/ws-*.toml`
 
 注意（Codex）：
 - Codex 的 repo skills 目录为 `.agents/skills/`（可随仓库共享；prompts 已 deprecated）。
@@ -164,7 +163,7 @@ hash 规则（用于跨平台稳定性）：
 - aiws 的最低承诺是：这些文件提供一致的“工作流入口”（例如引导执行 `npx @aipper/aiws init|update|validate|rollback`），从而把用户带回同一套真值文件与门禁。
 
 每个文件的托管方式（推荐）：
-- 对于 commands 类文件（如 `.claude/commands/*.md`、`.opencode/commands/*.md`、`.opencode/command/*.md`）：每个文件包含**一个且仅一个**托管块（block id 形如 `claude:aiws-init`），aiws update 只更新托管块，块外内容保留给用户追加说明。
+- 对于 commands 类文件（如 `.claude/commands/*.md`、`.opencode/commands/*.md`、`.opencode/command/*.md`）：每个文件包含**一个且仅一个**托管块（block id 形如 `claude:aiws-init`）；若文件顶部存在 YAML frontmatter（例如 `description`），`aiws update` 还会同步该 frontmatter，块外正文其余部分保留给用户追加说明。
 - 对于 skills 类文件（`.agents/skills/*/SKILL.md`、`.claude/skills/*/SKILL.md`、`.opencode/skills/*/SKILL.md`）：由于文件顶部 YAML front matter 需要保持一致性，默认采用 `replace_file` 全量托管；如需自定义请新增独立 skill 目录。
 
 最小矩阵（建议写清以下字段，便于未来实现与验收）：
@@ -193,9 +192,3 @@ hash 规则（用于跨平台稳定性）：
   - `autodiscovery`：不作为契约要求（由工具决定；aiws 不做保证）
   - `reload_needed`：不作为契约要求
   - `fallback`：显式使用 `$ws-preflight` / `$ws-plan` / `$ws-dev` / `$ws-review` / `$ws-commit`（或在 shell 直接运行 `npx @aipper/aiws init|update|validate|rollback`）
-- iFlow
-  - `path_pattern`：`.iflow/commands/aiws-*.toml`
-  - `purpose`：提供 commands/命令入口/说明（同上）
-  - `autodiscovery`：不作为契约要求
-  - `reload_needed`：不作为契约要求
-  - `fallback`：同上

package/docs/workflow-governance-rules.json

@@ -21,7 +21,7 @@
       "when": { "signal": "finish_state", "eq": "done" },
       "currentStage": "ws-finish",
       "recommendedStage": "ws-handoff",
-      "rationale": "finish completed; archive/handoff remains"
+      "rationale": "finish completed; archive should already exist and handoff is ready for follow-up"
     },
     {
       "id": "finish_failed",
@@ -266,7 +266,7 @@
       "id": "guidance_finish_handoff",
       "when": { "signal": "governance_rule_id", "eq": "finish_completed" },
       "lines": [
-        "收尾已完成：下一步运行 `$ws-handoff`，并归档 change"
+        "收尾已完成且 change 应已归档：下一步运行 `$ws-handoff` 检查/补充归档 handoff"
       ]
     },
     {
@@ -280,7 +280,7 @@
       "id": "guidance_handoff",
       "when": { "signal": "governance_current_stage", "eq": "ws-handoff" },
       "lines": [
-        "进入交接：在 AI 工具中运行 `$ws-handoff`，并生成/检查归档 handoff"
+        "进入交接：在 AI 工具中运行 `$ws-handoff`，并检查归档 handoff 是否足够支撑下一次接力"
       ]
     },
     {

package/docs/workflow-governance-rules.md

@@ -20,7 +20,7 @@
 | --- | --- | --- | --- | --- |
 | `strict_blockers` | `blockers_strict_count` > 0 | `ws-plan-verify` | `ws-plan-verify` | strict blockers remain unresolved |
 | `unchecked_tasks` | `tasks_unchecked` > 0 | `ws-dev` | `ws-dev` | {tasks_unchecked} unchecked task(s) remain |
-| `finish_completed` | `finish_state` == `done` | `ws-finish` | `ws-handoff` | finish completed; archive/handoff remains |
+| `finish_completed` | `finish_state` == `done` | `ws-finish` | `ws-handoff` | finish completed; archive should already exist and handoff is ready for follow-up |
 | `finish_failed` | `finish_state` == `failed` | `ws-finish` | `ws-finish` | finish started locally but push/cleanup failed; resolve and rerun finish |
 | `finish_cleanup_pending` | `finish_state` == `cleanup_pending` | `ws-finish` | `ws-finish` | push completed but cleanup is still pending ({finish_state_reason}); resolve and rerun finish |
 | `finish_local` | `finish_state` == `local` | `ws-finish` | `ws-finish` | finish started locally but is not fully completed yet |
@@ -51,9 +51,9 @@
 | `guidance_deliver_verify_before_complete_missing` | (`governance_current_stage` == `ws-deliver`) AND (`verify_before_complete_ready` is falsy) | 补齐完成前 gate：运行 `$ws-verify-before-complete`，并落盘 `changes/<change-id>/evidence/verify-before-complete.md` |
 | `guidance_deliver_finish` | (`governance_current_stage` == `ws-deliver`) AND (`governance_recommended_stage` == `ws-finish`) | 交付工件齐全后，进入 `$ws-finish`（安全合并 + push + cleanup） |
 | `guidance_finish_cleanup_pending` | `governance_rule_id` == `finish_cleanup_pending` | push 已完成，但 cleanup 仍未完成（{finish_state_reason}）；清理对应 worktree 后重跑 `$ws-finish` |
-| `guidance_finish_handoff` | `governance_rule_id` == `finish_completed` | 收尾已完成：下一步运行 `$ws-handoff`，并归档 change |
+| `guidance_finish_handoff` | `governance_rule_id` == `finish_completed` | 收尾已完成且 change 应已归档：下一步运行 `$ws-handoff` 检查/补充归档 handoff |
 | `guidance_finish_retry` | `governance_rule_id` in [`finish_failed`, `finish_local`] | 收尾未完整完成：检查 push / cleanup / submodule 状态后重跑 `$ws-finish` |
-| `guidance_handoff` | `governance_current_stage` == `ws-handoff` | 进入交接：在 AI 工具中运行 `$ws-handoff`，并生成/检查归档 handoff |
+| `guidance_handoff` | `governance_current_stage` == `ws-handoff` | 进入交接：在 AI 工具中运行 `$ws-handoff`，并检查归档 handoff 是否足够支撑下一次接力 |
 | `guidance_default` | `governance_current_stage` == `` | 按阶段契约继续推进当前 change |
 
 ## 说明

package/docs/workflow-router-rules.json

@@ -106,7 +106,7 @@
       "match": "目标明确、归因清晰、验证入口明确，且无需先改 requirements 或单独评审。",
       "routeTo": "ws-dev",
       "gate": "若执行中发现复杂度升高，必须回退到 `ws-plan`。",
-      "rationale": "router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门。"
+      "rationale": "router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门；若用户明确要走轻量入口，可在实现阶段显式使用 `ws-dev-lite` 作为 `ws-dev` 的 facade。"
     }
   ],
   "routeCases": [
@@ -172,7 +172,7 @@
       "request": "修复 codex install-skills 的默认路径，并补一条可复现回归。",
       "expectedRuleId": "direct_implementation",
       "expectedRoute": "ws-dev",
-      "why": "小步明确实现允许直接进入 dev，但仍保留回退到 plan 的门。"
+      "why": "小步明确实现允许直接进入 dev；若用户明确要轻量直修，可进一步显式使用 ws-dev-lite，但治理归属仍收敛到 ws-dev。"
     }
   ],
   "clarificationTriggers": [

package/docs/workflow-router-rules.md

@@ -46,7 +46,7 @@ router 在做任何 workflow 判断前，必须先读取：
 | `finish_request` | 收尾/合并/推送/cleanup | 用户要求 finish、merge、push、收尾、交付完成、清理 worktree 或 branch。 | `ws-finish` | 必须满足 finish gate，不能跳过 validate / push / cleanup。 | finish 是独立治理阶段，不能与普通实现混用。 |
 | `handoff_request` | 交接/归档总结 | 用户要求 handoff、交接说明、archive summary、会话总结或接力说明。 | `ws-handoff` | 先确认 change 已 finish 或 archive 上下文存在。 | handoff 依赖已有证据与归档上下文，不应在实现前触发。 |
 | `plan_first` | 中大型实现或需要建立 change 上下文 | 任务是多步实现、跨文件、跨模块、需要方案、需要新建 change/worktree，或当前还没有计划工件。 | `ws-plan` | plan 过 gate 前不进入 `ws-dev`。 | medium/complex 任务必须先生成可落盘计划，避免 router 直接跳进实现。 |
-| `direct_implementation` | 小步实现/修复/配置调整 | 目标明确、归因清晰、验证入口明确，且无需先改 requirements 或单独评审。 | `ws-dev` | 若执行中发现复杂度升高，必须回退到 `ws-plan`。 | router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门。 |
+| `direct_implementation` | 小步实现/修复/配置调整 | 目标明确、归因清晰、验证入口明确，且无需先改 requirements 或单独评审。 | `ws-dev` | 若执行中发现复杂度升高，必须回退到 `ws-plan`。 | router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门；若用户明确要走轻量入口，可在实现阶段显式使用 `ws-dev-lite` 作为 `ws-dev` 的 facade。 |
 
 ## Route Cases
 
@@ -59,7 +59,7 @@ router 在做任何 workflow 判断前，必须先读取：
 | `case_finish_request` | 用户要求合并、push、cleanup 或 finish 当前 change。 | 把 demo-change finish 掉并 push，顺便 cleanup worktree。 | `finish_request` | `ws-finish` | finish 是独立治理阶段，必须先走 finish gate。 |
 | `case_handoff_request` | 用户要求 handoff、交接说明、archive summary 或接力文档。 | 给这个 change 写 handoff，并补 archive summary。 | `handoff_request` | `ws-handoff` | handoff 依赖已有 finish/archive 上下文，不能当成普通实现。 |
 | `case_plan_first` | 任务是跨文件、多步实现，且需要先建立 change/worktree 或方案。 | 实现 dashboard 的阶段治理视图并补测试，需要新建 change 和计划。 | `plan_first` | `ws-plan` | 中大型实现应先落盘计划，再进入 dev。 |
-| `case_direct_implementation` | 任务是小步明确修复，归因和验证入口都已清楚。 | 修复 codex install-skills 的默认路径，并补一条可复现回归。 | `direct_implementation` | `ws-dev` | 小步明确实现允许直接进入 dev，但仍保留回退到 plan 的门。 |
+| `case_direct_implementation` | 任务是小步明确修复，归因和验证入口都已清楚。 | 修复 codex install-skills 的默认路径，并补一条可复现回归。 | `direct_implementation` | `ws-dev` | 小步明确实现允许直接进入 dev；若用户明确要轻量直修，可进一步显式使用 ws-dev-lite，但治理归属仍收敛到 ws-dev。 |
 
 ## 必须先澄清的情形
 

package/docs/workflow-stage-contracts.json

@@ -19,8 +19,8 @@
   ],
   "notes": [
     "ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。",
-    "ws-finish 用于 fast-forward 合并、push 和 worktree cleanup。",
-    "ws-handoff 通常在 archive 后使用，为下一次会话留下交接说明。",
+    "ws-finish 用于 fast-forward 合并、push、worktree cleanup，并在完整 finish 后自动归档 change。",
+    "ws-handoff 通常在 finish 自动归档后使用，用于查看/补充归档交接说明。",
     "若存在独立 change worktree，治理信号应优先读取该 worktree；若 worktree metadata 已 stale，则降级为 warning 并回退到当前 worktree。"
   ],
   "stages": [
@@ -82,18 +82,18 @@
     },
     {
       "stage": "ws-finish",
-      "goal": "安全合并、push、cleanup",
+      "goal": "安全合并、push、cleanup，并自动归档",
       "requiredInputs": "干净工作区；已提交的 change；push 目标；submodule 真值（若有）",
-      "requiredOutputs": "Merge；Push；Worktree cleanup；Evidence",
+      "requiredOutputs": "Merge；Push；Worktree cleanup；Archive/Handoff；Evidence",
       "blockers": "dirty 工作区；ff 失败；submodule 无法安全 push",
-      "next": "ws-handoff 或 archive"
+      "next": "ws-handoff"
     },
     {
       "stage": "ws-handoff",
-      "goal": "生成可接力的归档交接说明",
-      "requiredInputs": "已归档或待归档的 change",
+      "goal": "查看/补充可接力的归档交接说明",
+      "requiredInputs": "已归档的 change",
       "requiredOutputs": "changes/archive/.../handoff.md；Next",
-      "blockers": "无法定位 change；archive 失败；handoff 无法生成",
+      "blockers": "无法定位已归档 change；handoff 无法生成或读取",
       "next": "新 change 通过 Depends_On 接力"
     }
   ],
@@ -102,7 +102,7 @@
     "每个阶段都必须有明确输出，不能只给“建议继续”而不留下工件或证据。",
     "遇到阻断条件时必须停止，不能为了推进速度跳过门禁。",
     "如果一个阶段没有留下可审计路径，它就不算真正完成。",
-    "`ws-finish` 只有在 merge、push、cleanup 都完成后才算完成；仅本地 merge 成功不等于可进入 `ws-handoff`。"
+    "`ws-finish` 只有在 merge、push、cleanup、archive 都完成后才算完成；仅本地 merge 成功不等于可进入 `ws-handoff`。"
   ],
   "evidence": {
     "intro": "最少证据集合：",

package/docs/workflow-stage-contracts.md

@@ -16,8 +16,8 @@
 
 说明：
 - ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。
-- ws-finish 用于 fast-forward 合并、push 和 worktree cleanup。
-- ws-handoff 通常在 archive 后使用，为下一次会话留下交接说明。
+- ws-finish 用于 fast-forward 合并、push、worktree cleanup，并在完整 finish 后自动归档 change。
+- ws-handoff 通常在 finish 自动归档后使用，用于查看/补充归档交接说明。
 - 若存在独立 change worktree，治理信号应优先读取该 worktree；若 worktree metadata 已 stale，则降级为 warning 并回退到当前 worktree。
 
 ## 阶段表
@@ -31,8 +31,8 @@
 | `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；Evidence | dirty 工作区；ff 失败；submodule 无法安全 push | ws-handoff 或 archive |
-| `ws-handoff` | 生成可接力的归档交接说明 | 已归档或待归档的 change | changes/archive/.../handoff.md；Next | 无法定位 change；archive 失败；handoff 无法生成 | 新 change 通过 Depends_On 接力 |
+| `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 接力 |
 
 ## 统一规则
 
@@ -40,7 +40,7 @@
 - 每个阶段都必须有明确输出，不能只给“建议继续”而不留下工件或证据。
 - 遇到阻断条件时必须停止，不能为了推进速度跳过门禁。
 - 如果一个阶段没有留下可审计路径，它就不算真正完成。
-- `ws-finish` 只有在 merge、push、cleanup 都完成后才算完成；仅本地 merge 成功不等于可进入 `ws-handoff`。
+- `ws-finish` 只有在 merge、push、cleanup、archive 都完成后才算完成；仅本地 merge 成功不等于可进入 `ws-handoff`。
 
 ## 证据约定
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.25",
+  "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

@@ -53,7 +53,7 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
    - finish / merge / push / cleanup：`$ws-finish`
    - handoff / archive summary：`$ws-handoff`
    - 中大型实现、需要方案、需要 change/worktree：`$ws-plan`
-   - 小步明确实现/修复/配置调整：`$ws-dev`
+   - 小步明确实现/修复/配置调整：`$ws-dev`（若是 simple/local 单点修复，且用户明确希望走轻量入口，可显式进入 `$ws-dev-lite`）
 4) 若任务意图或归因不明确：
    - 只问 1-3 个关键澄清问题
    - 明确写出缺的是什么：意图、`Req_ID` / `Problem_ID`、verify、change 上下文
@@ -64,6 +64,10 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
      - `Binding:`
      - `Route:`
      - `Why:`
+   - 若 `Route: $ws-dev` 且任务属于 simple/local 单点修复：
+     - `Next:` 可优先进入 `$ws-dev-lite`
+   - 否则：
+     - `Next:` 进入对应主 skill
    - 然后在同一轮中继续遵循对应 skill 的契约
 6) 路由约束：
    - router 自己不是实现阶段；不要在给出 route 之前直接改代码

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

@@ -19,7 +19,10 @@ 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。

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

@@ -218,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-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

@@ -206,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。

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

@@ -11,15 +11,15 @@ description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
 - 指引在归档与依赖场景下如何使用 handoff
 
 说明：
-- `handoff.md` 由 `aiws change archive` 自动生成：`changes/archive/<date>-<change-id>/handoff.md`
+- `handoff.md` 默认由 `aiws change finish --push` 自动归档时生成：`changes/archive/<date>-<change-id>/handoff.md`
 - `Depends_On` 依赖若已归档，`aiws change start` 会尝试读取依赖的 `handoff.md` 并输出摘要
 
 阶段定位：
-- handoff / archive 阶段；负责把已完成 change 的上下文压缩成后续协作者可直接接手的说明。
+- handoff / archive 阶段；负责查看或补充已归档 change 的交接说明。
 
 必需输入：
-- 当前或已归档的 `change/<change-id>`
-- 对应 archive 目录或准备归档的 change 工件
+- 已归档的 `change/<change-id>`
+- 对应 archive 目录
 
 必需输出：
 - `Change_ID:` 当前交接对象
@@ -28,7 +28,6 @@ description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
 
 阻断条件：
 - 无法定位目标 change
-- 未归档且无法执行 `aiws change archive <change-id>`
 - `handoff.md` 无法生成或读取
 
 完成判定：
@@ -36,15 +35,16 @@ description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
 
 执行建议：
 1) 先运行 `$ws-preflight`。
-2) 若本 change 已完成并准备归档：运行 `aiws change archive <change-id>`（会先做严格校验，并移动目录到 `changes/archive/`，同时生成 `handoff.md`）。
+2) 先确认本 change 已通过 `aiws change finish <change-id> --push` 完成自动归档。
 3) 查看 handoff：
 ```bash
 change_id="<change-id>"
 ls -1 changes/archive/*-"${change_id}"/handoff.md
 sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
 ```
-4) 若要让后续 change 可接力：在 `proposal.md` 里声明 `Blocks`（下一步建议会据此生成）。
-5) 若本 change 使用了外部 / 子 agent 协作：确认关键结论已经进入 `review/` 或 `evidence/`，避免 handoff 只留下原始 patch/分析文件而没有最终结论。
+4) 若是历史/异常场景，尚未归档且需要手工恢复，再运行 `aiws change archive <change-id>`。
+5) 若要让后续 change 可接力：在 `proposal.md` 里声明 `Blocks`（下一步建议会据此生成）。
+6) 若本 change 使用了外部 / 子 agent 协作：确认关键结论已经进入 `review/` 或 `evidence/`，避免 handoff 只留下原始 patch/分析文件而没有最终结论。
 
 输出要求：
 - `Change_ID:` <change-id>

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", "iflow"],
+  "tools": ["claude", "opencode", "codex"],
   "managed": [
     { "path": ".githooks/pre-commit", "mode": "replace_file", "sha256": "<sha256>" },
     { "path": ".githooks/pre-push", "mode": "replace_file", "sha256": "<sha256>" },
@@ -27,10 +27,6 @@
     { "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": ".iflow/commands/aiws-init.md", "mode": "managed_blocks", "blocks": { "iflow:aiws-init": "<sha256>" } },
-    { "path": ".iflow/commands/aiws-update.md", "mode": "managed_blocks", "blocks": { "iflow:aiws-update": "<sha256>" } },
-    { "path": ".iflow/commands/aiws-validate.md", "mode": "managed_blocks", "blocks": { "iflow:aiws-validate": "<sha256>" } },
-    { "path": ".iflow/commands/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "iflow:aiws-rollback": "<sha256>" } }
+    { "path": ".codex/prompts/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "codex:aiws-rollback": "<sha256>" } }
   ]
 }

package/templates/workspace/.claude/commands/using-aiws.md

@@ -13,12 +13,13 @@
 4) 路由规则：
    - 需求/验收/合同变更：`/ws-req-review`
    - 中大型实现或需要 change/worktree：`/ws-plan`
-   - 小步明确实现：`/ws-dev`
+   - 小步明确实现：`/ws-dev`（若是 simple/local 单点修复，可显式进入 `/ws-dev-lite`）
    - 评审/审计：`/ws-review`
    - finish / merge / push / cleanup：`/ws-finish`
    - handoff / archive summary：`/ws-handoff`
 5) 输出 `Task intent:` / `Binding:` / `Route:` / `Why:` / `Next:`。
-6) 除非用户只要路由判断，否则给出 route 后继续遵循对应入口的契约。
+6) 若 `Route: ws-dev` 且任务属于 simple/local 单点修复：`Next` 可显式建议 `/ws-dev-lite`。
+7) 除非用户只要路由判断，否则给出 route 后继续遵循对应入口的契约。
 <!-- AIWS_MANAGED_END:claude:using-aiws -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-dev-lite.md

@@ -0,0 +1,31 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-dev-lite -->
+# ws dev lite
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：处理 simple/local 单点修复，走最小改动 + 最小验证，不默认拉起完整重流程。
+
+使用条件：
+- 目标明确、归因明确、验证入口明确
+- 一般只影响单文件或紧密相关的小范围文件
+- 不需要先改 `REQUIREMENTS.md`
+
+强制流程：
+1) 先运行 `/ws-preflight`。
+2) 先说明：
+   - `Goal:`
+   - `Why lite:`
+   - 若说不清，立刻回到 `/ws-dev` 或 `/ws-plan`
+3) 实施最小改动；不要为形式完整额外扩 scope。
+4) 运行最小可复现验证；允许比全量更窄，但必须说明为什么足够。
+5) 输出 `Changed / Verify / Evidence / Next`。
+6) 若准备提交或交付：后续仍进入 `/ws-review`、`/ws-commit`、`/ws-finish`。
+
+边界：
+- 默认不创建 `plan/...`
+- 默认不跑 `ws-plan-verify`
+- 默认不要求先做双 review
+- 一旦复杂度升高，停止 lite，切回主流程
+<!-- AIWS_MANAGED_END:claude:ws-dev-lite -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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

@@ -58,7 +58,7 @@ fi
 6) 任一 submodule 不满足 fast-forward 条件时立即停止（不要继续 push 主仓库）。
 7) submodules 全部成功后，再回到主仓库执行：
    - `aiws change finish <change-id> --push`
-8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+8) `aiws change finish --push` 成功后会自动归档并生成 handoff；只有历史/异常场景才需要手工运行 `aiws change archive <change-id>`。
 
 安全：
 - push 前先输出状态并说明远端/分支。

package/templates/workspace/.claude/commands/ws-handoff.md

@@ -5,10 +5,10 @@
 
 目标：
 - 交接与回放：通过 `handoff.md` 让已归档的 change 可被下一位/下一次会话快速接力。
-- handoff 文件位置：`changes/archive/<date>-<change-id>/handoff.md`（由 `aiws change archive` 自动生成）。
+- handoff 文件位置：`changes/archive/<date>-<change-id>/handoff.md`（默认由 `aiws change finish --push` 自动归档时生成）。
 
 执行建议：
-1) 若 change 已完成并准备归档：运行 `/p-aiws-change-archive`（会先严格校验，再归档并生成 `handoff.md`）。
+1) 先确认 change 已通过 `/ws-finish` 或 `aiws change finish --push` 完成自动归档。
 2) 查看 handoff：
 ```bash
 change_id="<change-id>"
@@ -17,6 +17,7 @@ sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
 ```
 3) 依赖提示：
 - 若你在某个 change 的 `proposal.md` 声明了 `Depends_On`，`aiws change start` 会尝试读取依赖 change 的 `handoff.md` 并输出摘要（前提：依赖已归档且 handoff 存在）。
+- 若是历史/异常场景尚未归档，再手工运行 `/p-aiws-change-archive`。
 <!-- AIWS_MANAGED_END:claude:ws-handoff -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-review.md

@@ -12,8 +12,8 @@
    - 是否有可复现验证命令与证据
    - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
 3) 将审计落盘到（目录不存在则创建）：
-   - 默认：`changes/<change-id>/review/claude-review.md`
-   - 回退：`.agentdocs/tmp/review/claude-review.md`（仅在无法确定 `change-id` 时使用）
+   - 默认：`changes/<change-id>/review/codex-review.md`
+   - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
 4) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）