@aipper/aiws-spec 0.0.25 → 0.0.27

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）。
 
 接口（仅定义）：
@@ -274,14 +274,15 @@ Dashboard API（本地只读）：
 ### `aiws change start`
 
 语义：
-- 默认行为：切分支到 `change/<change-id>`（存在则切换；不存在则创建）。
+- 默认行为：切分支到 `change/<change-id>`（存在则切换；不存在则创建）；若仓库存在 `.gitmodules`，只切 superproject，本次不会递归切换 submodules。
 - 若检测到 `.gitmodules`（git submodules）且未显式指定 `--switch/--no-switch/--worktree`：默认优先采用 `--worktree`（避免切走 superproject 分支导致 submodule 状态混乱）；若不满足 `--worktree` 前置条件则回退为 `--no-switch`。
 - 若 `changes/<change-id>/` 不存在：等价执行 `aiws change new ...`。
 - 可选：`--hooks` 等价于 `aiws hooks install .`。
 - 可选：`--switch` 显式允许切换 superproject 分支（仅在存在 `.gitmodules` 时有意义；否则等价于默认行为）。
-  - 实现细节：当存在 `.gitmodules` 且使用 `--switch` 时，CLI 会尝试使用 `git switch/checkout --recurse-submodules` 让 submodules 工作区跟随 superproject 指针；若 git 不支持该选项，会降级为普通切分支并提示手工更新 submodules。
+  - 实现细节：当存在 `.gitmodules` 且使用 `--switch` 时，CLI 只切 superproject 分支；submodules 保持当前状态，由 `ws-pull` / `ws-finish` 再统一挂回 `aiws/pin/<target-branch>`。
 - 可选：`--no-switch` 不切换当前分支（仅确保目标分支存在，并初始化变更工件）；适用于 superproject + submodule 场景，避免意外切换 A 目录分支导致 submodule 状态混乱。
 - 可选：`--worktree` 使用 `git worktree` 创建一个独立工作区并在其中 checkout `change/<change-id>`，当前目录分支保持不变（推荐用于 superproject + submodule）。
+- 当 `.gitmodules` 存在时，submodule 的 detached HEAD 恢复应统一使用 `aiws/pin/<target-branch>`；不要把 submodule 切到 `change/<change-id>`。
   - 默认 worktree 目录：`../<repo-name>-<change-id>`（相对于 git root）
   - 可选：`--worktree-dir <path>` 覆盖 worktree 目录（推荐放在仓库外；相对路径按 `../` 作为基准理解）
   - 可选：`--submodules` 在 worktree 内执行 `git submodule update --init --recursive`（避免新 worktree 下 submodule 目录为空）
@@ -309,6 +310,9 @@ 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
+  - 若发现“已 finish 但 active `changes/<id>/` 仍存在”的 `finished_unarchived` 状态，应视为 finish closeout 未完成：默认恢复动作是重跑 `aiws change finish <id> --push`，而不是继续开发或要求从头再做 merge
 
 接口（仅定义）：
 - `aiws change finish [<change-id>] [--into <branch> | --base <branch>]`
@@ -367,6 +371,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

@@ -2,6 +2,13 @@
   "version": 1,
   "description": "Machine-readable governance inference rules for aiws change status/next/dashboard.",
   "governanceRules": [
+    {
+      "id": "finish_resume_required",
+      "when": { "signal": "finish_resume_required", "truthy": true },
+      "currentStage": "ws-finish",
+      "recommendedStage": "ws-finish",
+      "rationale": "finish already completed locally, but archive/push closeout is still pending; rerun finish to resume"
+    },
     {
       "id": "strict_blockers",
       "when": { "signal": "blockers_strict_count", "gt": 0 },
@@ -21,7 +28,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,12 +273,19 @@
       "id": "guidance_finish_handoff",
       "when": { "signal": "governance_rule_id", "eq": "finish_completed" },
       "lines": [
-        "收尾已完成：下一步运行 `$ws-handoff`，并归档 change"
+        "收尾已完成且 change 应已归档：下一步运行 `$ws-handoff` 检查/补充归档 handoff"
+      ]
+    },
+    {
+      "id": "guidance_finish_resume_required",
+      "when": { "signal": "governance_rule_id", "eq": "finish_resume_required" },
+      "lines": [
+        "finish closeout 未完成：直接重跑 `aiws change finish {change_id} --push`（不要先在目标分支 worktree 运行 `aiws validate . --stamp`）"
       ]
     },
     {
       "id": "guidance_finish_retry",
-      "when": { "signal": "governance_rule_id", "in": ["finish_failed", "finish_local"] },
+      "when": { "signal": "governance_rule_id", "in": ["finish_failed", "finish_local", "finish_resume_required"] },
       "lines": [
         "收尾未完整完成：检查 push / cleanup / submodule 状态后重跑 `$ws-finish`"
       ]
@@ -280,7 +294,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

@@ -11,16 +11,17 @@
 
 - version: `1`
 - description: Machine-readable governance inference rules for aiws change status/next/dashboard.
-- governance rules: 16
-- guidance rules: 16
+- governance rules: 17
+- guidance rules: 17
 
 ## 阶段推断规则
 
 | Rule ID | Match | Current | Next | Rationale |
 | --- | --- | --- | --- | --- |
+| `finish_resume_required` | `finish_resume_required` is truthy | `ws-finish` | `ws-finish` | finish already completed locally, but archive/push closeout is still pending; rerun finish to resume |
 | `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 +52,10 @@
 | `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_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_finish_handoff` | `governance_rule_id` == `finish_completed` | 收尾已完成且 change 应已归档：下一步运行 `$ws-handoff` 检查/补充归档 handoff |
+| `guidance_finish_resume_required` | `governance_rule_id` == `finish_resume_required` | finish closeout 未完成：直接重跑 `aiws change finish {change_id} --push`（不要先在目标分支 worktree 运行 `aiws validate . --stamp`） |
+| `guidance_finish_retry` | `governance_rule_id` in [`finish_failed`, `finish_local`, `finish_resume_required`] | 收尾未完整完成：检查 push / cleanup / submodule 状态后重跑 `$ws-finish` |
+| `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.27",
   "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

@@ -14,7 +14,8 @@ description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push
 前置（必须）：
 - 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
 - change 分支已存在：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
-- 若使用 worktree：在目标分支所在 worktree 执行（`aiws change finish` 会提示正确的 worktree）
+- 若使用 worktree：普通 finish 的 `validate/evidence/state` 先在 `change/<change-id>` worktree 完成；真正执行 `aiws change finish` 时再切到目标分支所在 worktree（命令会提示正确的 worktree）
+- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`：说明 merge 已发生，只剩 push / archive / cleanup closeout；直接在该 worktree 运行 `aiws change finish <change-id> --push`，不要先跑 `aiws validate . --stamp`
 - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则无法确定性减少 detached；先运行 `$ws-submodule-setup` 并提交 `.gitmodules`）
 
 阶段定位：
@@ -60,7 +61,11 @@ if [[ -f .gitmodules ]]; then
   fi
 fi
 ```
-1) （推荐）先跑一次门禁并落盘证据：
+0.5) 先运行 `aiws change status <change-id>`，优先看稳定字段 `governance_rule:`：
+- 若为 `finish_resume_required`：直接跳到步骤 2 执行 `aiws change finish <change-id> --push`
+- 若不是该值：按普通 finish 继续；不要依赖自然语言提示句做分支判断
+
+1) （推荐，仅适用于普通 finish，且应在 `change/<change-id>` worktree 执行）先跑一次门禁并落盘证据：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
   ./node_modules/.bin/aiws validate . --stamp
@@ -70,7 +75,10 @@ else
   npx @aipper/aiws validate . --stamp
 fi
 ```
-1.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：
+若你已经位于目标分支 worktree，且 `governance_rule` 不是 `finish_resume_required`：
+- 不要在这里跑 `aiws validate . --stamp`
+- 先回 `change/<change-id>` worktree 补齐 finish gate，或先跑 `$ws-verify-before-complete`
+1.1) （强烈建议，仅适用于普通 finish）收敛持久证据并回填 `Evidence_Path`：
 ```bash
 change_id="<change-id>"
 if [[ -x "./node_modules/.bin/aiws" ]]; then
@@ -81,7 +89,7 @@ else
   npx @aipper/aiws change evidence "${change_id}"
 fi
 ```
-1.2) （可选）生成状态快照（建议）：
+1.2) （可选，仅适用于普通 finish）生成状态快照（建议）：
 ```bash
 aiws change state "${change_id}" --write
 ```
@@ -206,15 +214,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>" } }
   ]
 }