@aipper/aiws 0.0.25 → 0.0.26

package/README.md

@@ -1,37 +1,68 @@
 # @aipper/aiws
 
-AI Workspace CLI：把 Claude Code / OpenCode / Codex / iFlow 对齐到同一套“真值文件 + 可审计工作流”，降低规则漂移。
+`@aipper/aiws` 是面向 AI coding workflow 的 CLI。
 
-核心能力：
-- 初始化/更新模板：`aiws init` / `aiws update`
-- 强门禁校验：`aiws validate`（可选证据落盘 `--stamp`）
-- 回滚：`aiws rollback`（从 `.aiws/backups/` 恢复）
-- 变更工件工作流（脱离 dotfiles）：`aiws change ...`
-- 本地治理看板：`aiws dashboard serve`
-- OpenCode/oMo 运行时探测：`aiws opencode status`
-- Git hooks：`aiws hooks install/status`
-- 跨工具 native 投影：Codex repo skills、Claude skills、OpenCode skills/commands
-- Codex：repo skills（推荐）+ 可选全局 skills 安装
+它负责把真值文件、变更工件、门禁和跨工具入口落到仓库里，让 Claude Code、OpenCode、Codex 可以共享同一套项目约束，而不是每个工具各写一份 prompt。
 
-真值来源（SSOT）：`@aipper/aiws-spec`（模板与契约）。
+## 当前能力
+
+- `aiws init` / `aiws update`：初始化或升级 workspace 模板
+- `aiws validate`：校验模板漂移与门禁，可选 `--stamp`
+- `aiws rollback`：从 `.aiws/backups/` 回滚
+- `aiws change ...`：变更工件工作流
+- `aiws dashboard serve`：本地 change/dashboard API
+- `aiws hooks install/status`
+- `aiws opencode status`
+- `aiws codex install-skills/status-skills/uninstall-skills`
+
+支持工具：
+- Claude Code
+- OpenCode
+- Codex
+
+说明：
+- `ws-dev-lite` 是当前推荐的小改动入口
 
 ## 安装
 
-二选一：
-- 全局安装（推荐，适合长期使用）：`npm i -g @aipper/aiws`
-- 临时运行（不污染全局版本）：`npx @aipper/aiws <command>`
+```bash
+npm i -g @aipper/aiws
+# 或
+npx @aipper/aiws --help
+```
 
 ## 快速开始
 
-在任意 git 仓库根目录：
 ```bash
 aiws init .
 aiws hooks install .
 
-# 建议：用 change 工作流生成可审计工件并切分支
 aiws change start demo-change --no-design --hooks
+aiws change validate demo-change --strict
+aiws validate . --stamp
+```
+
+初始化后会生成：
+- 真值文件：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`
+- 工件目录：`changes/`
+- AI 入口：`.agents/skills/`、`.claude/skills/`、`.claude/commands/`、`.opencode/skills/`、`.opencode/commands/`
+- hooks：`.githooks/`
+
+## 推荐用法
+
+AI 工具内：
+- 不确定该从哪里开始：`$using-aiws`
+- simple/local 单点修复：`$ws-dev-lite`
+- 常规实现：`$ws-dev`
+- 中大型任务：`$ws-plan` → `$ws-plan-verify` → `$ws-dev`
+- 提交前：`$ws-review` / `$ws-commit`
+- 交付前：`$ws-deliver` / `$ws-finish`
 
-# 提交前门禁（并落盘证据）
+shell 内：
+
+```bash
+aiws change start <change-id> --no-design
+aiws change validate <change-id> --strict
 aiws validate . --stamp
 ```
 
@@ -43,54 +74,51 @@ aiws update [path]
 aiws validate [path] [--stamp]
 aiws rollback [path] <timestamp|latest>
 
-aiws change <list|new|start|status|next|sync|validate|archive|templates>
+aiws change new <change-id> [--no-design]
+aiws change start <change-id> [--switch|--no-switch|--worktree]
+aiws change status [change-id]
+aiws change next [change-id]
+aiws change sync [change-id]
+aiws change validate [change-id] [--strict] [--check-evidence] [--check-scope]
+aiws change evidence [change-id]
+aiws change archive [change-id]
+
 aiws dashboard serve [--host 127.0.0.1] [--port 3456]
+aiws hooks install [path]
+aiws hooks status [path]
 aiws opencode status [path]
-aiws hooks <install|status>
-aiws codex <install-skills|status-skills|uninstall-skills|install-prompts|status|uninstall-prompts>
+aiws codex install-skills
+aiws codex status-skills
+aiws codex uninstall-skills
 ```
 
-Dashboard 说明：
-- 读取本地 `changes/<id>/`、`.agentdocs/tmp/...` 与 spec 中的阶段契约 / governance / review-gate 真值，展示 phase、collaboration、strict blockers、review gates、next advice
-- 阶段治理视图会基于共享 change 状态细分 `ws-review` / `ws-commit` / `ws-deliver` / `ws-finish` / `ws-handoff`
-- 本地 API：
-  - `/api/changes`
-  - `/api/workflow-stages`
-  - `/api/change/<id>/validate?strict=1`
-
-## Codex（repo skills 优先）
-
-- 若你不想先判断当前该走 plan、dev、review 还是 finish：先用 `$using-aiws`
-- `aiws init .` 会生成 `.agents/skills/`（随仓库共享），在 Codex 中可显式调用（示例）：`$ws-preflight` / `$ws-plan` / `$p-tasks-plan` / `$ws-handoff` / `$ws-dev` / `$ws-review` / `$ws-commit`
-- 现在也会生成默认 router 入口：`$using-aiws`（Claude/OpenCode 对应 `/using-aiws`）
-- `aiws init .` 也会同步投影 `Claude Code` native skills（`.claude/skills/`）与 `OpenCode` native skills / commands（`.opencode/skills/` / `.opencode/commands/`），并保留 `.claude/commands/`、`.opencode/command/` 兼容入口
-- 高风险改动或准备 finish 时，建议补跑：`$ws-spec-review`、`$ws-quality-review`、`$ws-verify-before-complete`
-- 交付收尾（submodules+superproject 分步提交 + 安全合并）：`$ws-deliver`
-- 收尾（安全合并回目标分支）：`$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward；现在会硬阻断缺失的 review gate）
-- 可选：安装全局 skills 到 `~/.agents/skills/`：
-  - `aiws codex install-skills`
-  - `aiws codex status-skills`
-  - `aiws codex uninstall-skills`
-- 测试/沙箱场景可用 `--dir <path>`；若设置 `CODEX_HOME`，全局 skills 会解析到 `$CODEX_HOME/.agents/skills`
-- legacy prompts（deprecated，仅兼容）：`aiws codex install-prompts`
-
-## OpenCode / oMo
-
-- `aiws init .` 会生成 `.opencode/skills/`、`.opencode/commands/` 与 `.opencode/oh-my-opencode.json.example`
-- `aiws opencode status .` 会检查当前项目是否真正启用了 `.opencode/oh-my-opencode.json`，并输出 `oMo-enabled` 或 `standard-opencode`
-- 若只存在 `.opencode/oh-my-opencode.json.example`，说明项目已具备建议配置，但还没有真正启用 oMo
-- 启用后，`using-aiws` / `ws-preflight` / `ws-plan` / `ws-review` 会优先按 `planner-sisyphus` / `explore` / `librarian` / `oracle` 路由；缺失时按 fallback 退回标准 OpenCode
-
-## 证据落盘与协作
-
-- `aiws validate --stamp` 会写入：`.agentdocs/tmp/aiws-validate/*.json`（默认被 `.gitignore` 忽略）
-- `$ws-review` 会落盘：`.agentdocs/tmp/review/codex-review.md`（默认被 `.gitignore` 忽略）
-- `change status` / `change next` / dashboard 会显式显示：`spec_review` / `quality_review` / `validate_stamp` / `verify_before_complete`
-- `aiws change validate <id> --strict --check-scope` 会按计划文件的 `## Scope` / `### In Scope` 检查越界改动；最新结果也会显示在 `change status` / `change next` / dashboard
-- 交付前建议执行：`aiws change validate <id> --strict --check-evidence`；`aiws change finish <id>` 也会对同一套 gate 做硬阻断
-- 建议把“可协作/可审计”的内容放进 `changes/<change-id>/`（proposal/tasks/design）并提交；`.agentdocs/tmp/` 作为本地缓存更稳
+## Dashboard
+
+`aiws dashboard serve` 会显示：
+- change phase
+- strict blockers
+- review gates
+- scope gate
+- collaboration 统计
+- next advice
+
+本地 API：
+- `/api/changes`
+- `/api/workflow-stages`
+- `/api/change/<id>/validate?strict=1`
+
+## 跨工具入口
+
+`aiws init .` 会把入口投影到：
+- Codex：`.agents/skills/*`
+- Claude：`.claude/skills/*` + `.claude/commands/*`
+- OpenCode：`.opencode/skills/*` + `.opencode/commands/*` + `.opencode/command/*`
+
+目标是统一 workflow 入口，不保证工具自动发现或自动加载。
 
 ## 运行要求
 
-- Node.js：>= 20
-- `aiws validate`：需要 `python3`（用于执行 `tools/ws_change_check.py` 与 `tools/requirements_contract.py`）
+- Node.js >= 20
+- `aiws validate` 需要 `python3`
+
+更多仓库级说明见根 README：[`../../README.md`](../../README.md)

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@aipper/aiws",
-  "version": "0.0.25",
-  "description": "AI Workspace CLI (init/update/validate) for Claude Code / OpenCode / Codex / iFlow.",
+  "version": "0.0.26",
+  "description": "AI Workspace CLI (init/update/validate) for Claude Code / OpenCode / Codex.",
   "type": "module",
   "bin": {
     "aiws": "./bin/aiws.js"
   },
   "dependencies": {
-    "@aipper/aiws-spec": "0.0.25"
+    "@aipper/aiws-spec": "0.0.26"
   },
   "files": [
     "bin",

package/src/cli.js

@@ -553,7 +553,7 @@ Notes:
     you can omit <change-id> for status/next/validate/sync/archive/finish.
   - Execution quality gate first: aiws change validate [change-id] --strict
     (equivalent to running $ws-plan-verify in AI tools).
-  - status/next now prioritize quality-gate guidance before coding ($ws-dev).
+  - status/next now prioritize quality-gate guidance before coding ($ws-dev-lite / $ws-dev).
   - start refuses to switch/create worktree with a dirty working tree (unless --allow-dirty).
   - finish --push is submodule-aware: when .gitmodules exists it pushes submodules first, then the target branch, then safely cleans the separate change worktree if possible.
   - If .gitmodules exists and you didn't specify --switch/--no-switch/--worktree,

package/src/commands/change-advice.js

@@ -96,6 +96,9 @@ export async function computeChangeNextAdvice(gitRoot, changeId, deps) {
     advice.actions.push(deps.scopeGateFailureAction(changeId));
   }
   if (status.tasks.unchecked > 0) advice.actions.push(`完成未勾选任务（${status.tasks.unchecked} 项）`);
+  if (status.blockersStrict.length === 0 && status.tasks.unchecked > 0) {
+    advice.actions.push("质量门通过后继续开发：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`");
+  }
   if ((status.collaboration?.counts?.analysis || 0) > 0 && (status.collaboration?.counts?.review || 0) === 0) {
     advice.actions.push("已有委托分析但还没有 review 汇总结论：建议在 `changes/<id>/review/` 落盘结论后再交付");
   }
@@ -104,7 +107,7 @@ export async function computeChangeNextAdvice(gitRoot, changeId, deps) {
   }
 
   if (status.blockersStrict.length > 0 && advice.actions.length === 0) {
-    advice.actions.push("先修复 Blockers (strict) 后复跑质量门，再进入 `$ws-dev`");
+    advice.actions.push("先修复 Blockers (strict) 后复跑质量门，再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`");
   }
 
   if (status.blockersStrict.length === 0 && status.tasks.unchecked === 0) {
@@ -122,7 +125,7 @@ export async function computeChangeNextAdvice(gitRoot, changeId, deps) {
     }
     if ((status.collaboration?.counts?.review || 0) > 1) advice.recommended.push("存在多份 review：交付前建议在 handoff 或 review 汇总里收敛最终结论");
   } else if (advice.actions.length === 0) {
-    advice.recommended.push("继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）");
+    advice.recommended.push("继续开发：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`（小步实现 + 可复现验证）");
     if ((status.collaboration?.counts?.analysis || 0) > 0) advice.recommended.push("已有委托分析：进入实现前先收敛 `changes/<id>/analysis/` 结论");
     if ((status.collaboration?.counts?.patches || 0) > 0) advice.recommended.push("已有 patch 草案：应用前先人工审查 `changes/<id>/patches/`");
   }

package/src/commands/change-lifecycle.js

@@ -208,12 +208,27 @@ export async function runChangeArchiveWorkflow(input, deps) {
     ) + "\n",
   );
 
+  const archivedToRel = path.relative(gitRoot, dest);
+  const handoffRel = path.relative(gitRoot, handoffPath);
+  const metaRel = path.relative(gitRoot, metaPath);
+  const stampRel = path.relative(gitRoot, stampPath);
+
   /** @type {string[]} */
   const outputLines = [];
   outputLines.push(`✓ aiws change archive: ${changeId}`);
-  outputLines.push(`archived_to: ${path.relative(gitRoot, dest)}`);
-  outputLines.push(`handoff: ${path.relative(gitRoot, handoffPath)}`);
-  if (metaUpdated) outputLines.push(`meta_updated: ${path.relative(gitRoot, metaPath)}`);
-  outputLines.push(`stamp: ${path.relative(gitRoot, stampPath)}`);
-  return { output: outputLines.join("\n") + "\n" };
+  outputLines.push(`archived_to: ${archivedToRel}`);
+  outputLines.push(`handoff: ${handoffRel}`);
+  if (metaUpdated) outputLines.push(`meta_updated: ${metaRel}`);
+  outputLines.push(`stamp: ${stampRel}`);
+  return {
+    output: outputLines.join("\n") + "\n",
+    archivedTo: dest,
+    archivedToRel,
+    handoffPath,
+    handoffRel,
+    metaPath: metaUpdated ? metaPath : "",
+    metaRel: metaUpdated ? metaRel : "",
+    stampPath,
+    stampRel,
+  };
 }

package/src/commands/change-next-command.js

@@ -95,10 +95,10 @@ export async function renderChangeNextOutput(input, deps) {
     for (const action of advice.actions) lines.push(`- ${action}`);
     if (status.blockersStrict.length > 0) {
       lines.push(`- 修复后复跑质量门：\`aiws change validate ${changeId} --strict\``);
-      lines.push("- 质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`");
+      lines.push("- 质量门通过后再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`");
     } else if (status.tasks.unchecked > 0) {
       lines.push(`- 处理完上述事项后复跑质量门：\`aiws change validate ${changeId} --strict\``);
-      lines.push("- 质量门通过后继续开发：在 AI 工具中运行 `$ws-dev`");
+      lines.push("- 质量门通过后继续开发：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`");
     } else {
       for (const recommendation of advice.recommended) lines.push(`- ${recommendation}`);
     }
@@ -107,12 +107,17 @@ export async function renderChangeNextOutput(input, deps) {
 
   lines.push(`- ${deps.planVerifyHint(changeId)}`);
   if (prog.unchecked > 0) {
-    lines.push("- 若仍需继续编码，先通过质量门，再在 AI 工具中运行 `$ws-dev`");
+    lines.push("- 若仍需继续编码，先通过质量门；simple/local 单点修复优先 `$ws-dev-lite`，否则 `$ws-dev`");
   } else {
     for (const recommendation of advice.recommended) lines.push(`- ${recommendation}`);
   }
   lines.push("- 审计与证据（推荐）：在 AI 工具内运行 `/ws-review`（或按 AI_PROJECT.md 手工审计）");
-  lines.push(`- 归档：\`aiws change archive ${changeId}\``);
+  const recommendedStage = String(status.governance?.recommendedStage || "");
+  if (recommendedStage === "ws-finish") {
+    lines.push(`- 收尾：\`aiws change finish ${changeId} --push\`（成功后会自动归档并生成 handoff）`);
+  } else if (recommendedStage === "ws-handoff") {
+    lines.push("- 交接：运行 `$ws-handoff` 检查归档 handoff；当前已无额外 finish 工作，无需重复执行 `aiws change finish`");
+  }
   return lines.join("\n") + "\n";
 }
 

package/src/commands/change-status-command.js

@@ -91,13 +91,13 @@ export async function renderChangeStatusOutput(input, deps) {
   lines.push("Next (recommended):");
   lines.push(`- ${deps.planVerifyHint(status.changeId)}`);
   if (status.blockersStrict.length > 0) {
-    lines.push("- 先修复 Blockers (strict) 后复跑质量门，再进入 `$ws-dev`");
+    lines.push("- 先修复 Blockers (strict) 后复跑质量门，再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`");
     if (changeWorktreeHint) lines.push(`- 若需要写代码：先切到 change worktree 再改动：\`cd ${changeWorktreeHint}\``);
     return lines.join("\n") + "\n";
   }
 
   if (status.tasks.unchecked > 0) {
-    lines.push("- 继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）");
+    lines.push("- 继续开发：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`（小步实现 + 可复现验证）");
     if ((status.collaboration?.counts?.analysis || 0) > 0) lines.push("- 已有委托分析：在编码前先收敛 `changes/<id>/analysis/` 中的结论");
     if ((status.collaboration?.counts?.patches || 0) > 0) lines.push("- 已有 patch 草案：应用前先人工审查 `changes/<id>/patches/`");
     lines.push("- 提交/交付前强制门禁：`aiws validate .`（可选落盘：`aiws validate . --stamp`）");

package/src/commands/change.js

@@ -350,6 +350,22 @@ function isMeaningfulBullet(bulletLine) {
   return true;
 }
 
+/**
+ * @param {string} entryName
+ * @returns {{ datePrefix: string, changeId: string, stamp: string } | null}
+ */
+function parseArchivedChangeDirName(entryName) {
+  const m = /^(\d{4}-\d{2}-\d{2})-(.+?)(?:-(\d{8}-\d{6}Z))?$/.exec(String(entryName || ""));
+  if (!m) return null;
+  const changeId = m[2] || "";
+  if (!CHANGE_ID_RE.test(changeId)) return null;
+  return {
+    datePrefix: m[1] || "",
+    changeId,
+    stamp: m[3] || "",
+  };
+}
+
 /**
  * Find an archived change by ID in the archive directory.
  * @param {string} archiveDir
@@ -360,13 +376,12 @@ async function findArchivedChange(archiveDir, changeId) {
   if (!(await pathExists(archiveDir))) return null;
   try {
     const entries = await fs.readdir(archiveDir, { withFileTypes: true });
-    for (const e of entries) {
-      if (!e.isDirectory()) continue;
-      // Archive dirs are named like: 2026-03-12-<change-id> or 2026-03-12-<change-id>-<timestamp>
-      if (e.name.endsWith(`-${changeId}`) || e.name.includes(`-${changeId}-`)) {
-        return path.join(archiveDir, e.name);
-      }
-    }
+    const matches = entries
+      .filter((e) => e.isDirectory())
+      .map((e) => ({ entry: e, parsed: parseArchivedChangeDirName(e.name) }))
+      .filter((item) => item.parsed?.changeId === changeId)
+      .sort((a, b) => a.entry.name.localeCompare(b.entry.name));
+    if (matches.length > 0) return path.join(archiveDir, matches.at(-1)?.entry.name || "");
   } catch {
     // ignore
   }
@@ -741,7 +756,7 @@ export async function computeChangeStatus(gitRoot, changeId) {
     blockersArchive,
     hints: {
       planVerify: planVerifyHint(changeId),
-      dev: "质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`",
+      dev: "质量门通过后再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`",
     },
   };
   const governance = await inferChangeGovernance(baseStatus);
@@ -817,8 +832,7 @@ async function fileState(changeDir, rel) {
  * @param {string} type
  * @param {any} payload
  */
-async function appendMetricsEvent(gitRoot, changeId, type, payload) {
-  const changeDir = changeDirAbs(gitRoot, changeId);
+async function appendMetricsEventAtDir(changeDir, changeId, type, payload) {
   const metricsAbs = path.join(changeDir, "metrics.json");
   /** @type {{ version: number, change_id: string, events: any[], updated_at?: string } | null} */
   let cur = null;
@@ -839,6 +853,11 @@ async function appendMetricsEvent(gitRoot, changeId, type, payload) {
   await writeText(metricsAbs, JSON.stringify(cur, null, 2) + "\n");
 }
 
+async function appendMetricsEvent(gitRoot, changeId, type, payload) {
+  const changeDir = changeDirAbs(gitRoot, changeId);
+  await appendMetricsEventAtDir(changeDir, changeId, type, payload);
+}
+
 /**
  * @param {string} gitRoot
  */
@@ -1453,10 +1472,27 @@ export async function changeFinishCommand(options) {
 
   const resolvedChangeId = await resolveChangeId(gitRoot, options.changeId, { command: "finish" });
   assertValidChangeId(resolvedChangeId);
-  const existingLifecycle = summarizeLifecycleSignals(await readChangeMetrics(changeDirAbs(gitRoot, resolvedChangeId), { pathExists, readText }));
+  const activeChangeDir = changeDirAbs(gitRoot, resolvedChangeId);
+  const activeChangeExists = await pathExists(activeChangeDir);
+  const archiveRoot = path.join(gitRoot, "changes", "archive");
+  const archivedChangeDir = activeChangeExists ? null : await findArchivedChange(archiveRoot, resolvedChangeId);
+  const existingLifecycle = summarizeLifecycleSignals(await readChangeMetrics(activeChangeDir, { pathExists, readText }));
+  const archivedHandoffPath = archivedChangeDir ? path.join(archivedChangeDir, "handoff.md") : "";
+  const archivedHandoffRel = archivedHandoffPath && (await pathExists(archivedHandoffPath)) ? path.relative(gitRoot, archivedHandoffPath) : "";
+  if (archivedChangeDir) {
+    throw new UserError("No finish work remaining for this change.", {
+      details:
+        `change: ${resolvedChangeId}\n` +
+        `archived: ${path.relative(gitRoot, archivedChangeDir)}\n` +
+        (archivedHandoffRel ? `handoff: ${archivedHandoffRel}\n` : "") +
+        "next: continue with `$ws-handoff`",
+    });
+  }
   if (existingLifecycle.finishState === "done") {
     throw new UserError("Change finish already completed.", {
-      details: `change: ${resolvedChangeId}\nnext: run \`aiws change archive ${resolvedChangeId}\` or continue with \`$ws-handoff\``,
+      details:
+        `change: ${resolvedChangeId}\n` +
+        `next: legacy finish is already done; run \`aiws change archive ${resolvedChangeId}\` once, then continue with \`$ws-handoff\``,
     });
   }
   const { changeId, changeBranch, into, cur, changeWt } = await resolveFinishContext(gitRoot, { ...options, changeId: resolvedChangeId }, {
@@ -1486,6 +1522,21 @@ export async function changeFinishCommand(options) {
     });
   }
   const finishBasePayload = { into, from: changeBranch, push: options.push === true };
+  const archiveWorkflowDeps = {
+    appendMetricsEvent,
+    changeValidateCommand,
+    ensureDir,
+    generateHandoffContent,
+    nowIsoUtc,
+    nowStampUtc,
+    nowUnixSeconds,
+    pathExists,
+    readText,
+    snapshotTruthFiles,
+    todayLocal,
+    writeText,
+    UserError,
+  };
 
   if (cur && cur !== into) {
     const sw = await runCommand("git", ["switch", into], { cwd: gitRoot });
@@ -1508,6 +1559,8 @@ export async function changeFinishCommand(options) {
 
   let cleanupNote = "not_requested";
   let finishCompleted = false;
+  let archivedToRel = "";
+  let handoffRel = "";
   if (options.push === true) {
     try {
       const submodulePush = await pushSubmodulesForFinish(gitRoot, changeId, into, changeWt?.worktree, {
@@ -1591,7 +1644,50 @@ export async function changeFinishCommand(options) {
   }
 
   if (finishCompleted) {
-    await appendMetricsEvent(gitRoot, changeId, "finish_done", { ...finishBasePayload, cleanup: cleanupNote });
+    const archiveResult = await runChangeArchiveWorkflow(
+      {
+        gitRoot,
+        changeId,
+        changeDir: changeDirAbs(gitRoot, changeId),
+        force: false,
+      },
+      archiveWorkflowDeps,
+    );
+    archivedToRel = archiveResult.archivedToRel;
+    handoffRel = archiveResult.handoffRel;
+    await appendMetricsEventAtDir(archiveResult.archivedTo, changeId, "finish_done", { ...finishBasePayload, cleanup: cleanupNote });
+
+    if (options.push === true) {
+      const stageArchive = await runCommand("git", ["add", "-A", "--", "changes"], { cwd: gitRoot });
+      if (stageArchive.code !== 0) {
+        throw new UserError("Finish completed, but failed to stage archived change artifacts.", {
+          details: stageArchive.stderr || stageArchive.stdout,
+        });
+      }
+
+      const stagedArchive = await runCommand("git", ["diff", "--cached", "--quiet", "--", "changes"], { cwd: gitRoot });
+      if (stagedArchive.code !== 0) {
+        const archiveCommit = await runCommand("git", ["commit", "-m", `归档: ${changeId}`], { cwd: gitRoot });
+        if (archiveCommit.code !== 0) {
+          throw new UserError("Finish completed, but failed to commit archived change artifacts.", {
+            details: `archived_to: ${archivedToRel}\nhandoff: ${handoffRel}\n\n${archiveCommit.stderr || archiveCommit.stdout}`,
+          });
+        }
+
+        const archivePushTarget = await resolvePushTarget(gitRoot, into, options.remote, { runCommand });
+        const archivePush = await runCommand("git", ["push", archivePushTarget.remote, archivePushTarget.refspec], { cwd: gitRoot });
+        if (archivePush.code !== 0) {
+          throw new UserError("Finish completed, but failed to push archived change artifacts.", {
+            details:
+              `archived_to: ${archivedToRel}\n` +
+              `handoff: ${handoffRel}\n` +
+              `remote: ${archivePushTarget.remote}\nlocal_branch: ${into}\nremote_branch: ${archivePushTarget.remoteBranch}\n` +
+              (archivePushTarget.trackedMergeRef ? `tracked_merge: ${archivePushTarget.trackedMergeRef}\n` : "") +
+              `\n${archivePush.stderr || archivePush.stdout}`,
+          });
+        }
+      }
+    }
   }
 
   const outcomeLabel =
@@ -1599,6 +1695,8 @@ export async function changeFinishCommand(options) {
   console.log(`ok: ${outcomeLabel}: ${changeId}`);
   console.log(`into: ${into}`);
   console.log(`from: ${changeBranch}`);
+  if (archivedToRel) console.log(`archived_to: ${archivedToRel}`);
+  if (handoffRel) console.log(`handoff: ${handoffRel}`);
 
   if (options.push === true && (await listSubmodulesFromGitmodules(gitRoot, { pathExists, runCommand })).length > 0) {
     console.log("next:");

package/src/commands/init.js

@@ -19,7 +19,7 @@ export async function initCommand(options) {
 
   const defaults = tpl.manifest.defaults || {};
   const includeOptional = defaults.include_optional !== false;
-  const tools = Array.isArray(defaults.tools) ? defaults.tools.map(String) : ["claude", "opencode", "codex", "iflow"];
+  const tools = Array.isArray(defaults.tools) ? defaults.tools.map(String) : ["claude", "opencode", "codex"];
 
   const required = await expandManifestEntries(tpl.templateDir, tpl.manifest.required || []);
   const optional = includeOptional ? await expandManifestEntries(tpl.templateDir, tpl.manifest.optional || []) : [];

package/src/commands/update.js

@@ -31,6 +31,9 @@ export async function updateCommand(options) {
       .filter((entry) => entry && typeof entry === "object")
       .map((entry) => [normalizeRel(String(entry.path || "")), entry]),
   );
+  const defaults = tpl.manifest.defaults || {};
+  const defaultTools = Array.isArray(defaults.tools) ? defaults.tools.map(String) : ["claude", "opencode", "codex"];
+  const allowedTools = new Set(defaultTools);
 
   const update = tpl.manifest.update || {};
   const replaceFiles = (update.replace_file || []).map(normalizeRel);
@@ -112,7 +115,8 @@ export async function updateCommand(options) {
 
   const now = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
   const installedAt = String(stored.installed_at || now);
-  const tools = Array.isArray(stored.tools) ? stored.tools.map(String) : ["claude", "opencode", "codex", "iflow"];
+  const storedTools = Array.isArray(stored.tools) ? stored.tools.map(String).filter((tool) => allowedTools.has(tool)) : [];
+  const tools = storedTools.length > 0 ? storedTools : defaultTools;
 
   await writeWorkspaceManifest({
     workspaceRoot,

package/src/dashboard/index.html

@@ -42,7 +42,7 @@
           </table>
         </div>
         <div class="hint">
-          建议：先看 Details 里的 <code>Next</code>，优先通过 <code>aiws change validate &lt;id&gt; --strict</code>，再按阶段进入 <code>$ws-dev</code> 或 <code>$ws-deliver</code>。
+          建议：先看 Details 里的 <code>Next</code>，优先通过 <code>aiws change validate &lt;id&gt; --strict</code>；simple/local 单点修复优先 <code>$ws-dev-lite</code>，否则按阶段进入 <code>$ws-dev</code> 或 <code>$ws-deliver</code>。
         </div>
       </section>
 

package/src/template.js

@@ -6,6 +6,45 @@ import { normalizeNewlines } from "./hash.js";
 import { extractTemplateBlock, upsertManagedBlock } from "./managed-blocks.js";
 import { UserError } from "./errors.js";
 
+/**
+ * Extract a leading YAML frontmatter chunk when present.
+ *
+ * @param {string} text normalized
+ * @returns {{ chunk: string, rest: string } | null}
+ */
+function extractLeadingFrontmatter(text) {
+  const t = normalizeNewlines(text);
+  if (!t.startsWith("---\n")) return null;
+  const end = t.indexOf("\n---\n", 4);
+  if (end === -1) return null;
+  const closeEnd = end + "\n---\n".length;
+  return {
+    chunk: t.slice(0, closeEnd),
+    rest: t.slice(closeEnd),
+  };
+}
+
+/**
+ * Keep command metadata in sync without overwriting managed-block files wholesale.
+ *
+ * @param {string} currentText normalized
+ * @param {string} templateText normalized
+ * @returns {{ nextText: string, changed: boolean }}
+ */
+function syncLeadingFrontmatter(currentText, templateText) {
+  const templateFm = extractLeadingFrontmatter(templateText);
+  if (!templateFm) return { nextText: currentText, changed: false };
+
+  const currentFm = extractLeadingFrontmatter(currentText);
+  if (!currentFm) {
+    const nextText = `${templateFm.chunk}${currentText}`;
+    return { nextText, changed: nextText !== currentText };
+  }
+
+  const nextText = `${templateFm.chunk}${currentFm.rest}`;
+  return { nextText, changed: nextText !== currentText };
+}
+
 /**
  * Template file candidates for a given manifest/workspace path.
  *
@@ -116,8 +155,9 @@ export async function applyManagedBlocksFromTemplate(options) {
   }
 
   const currentText = normalizeNewlines(await readText(dest));
-  let nextText = currentText;
-  let anyChanged = false;
+  const syncedFrontmatter = syncLeadingFrontmatter(currentText, templateText);
+  let nextText = syncedFrontmatter.nextText;
+  let anyChanged = syncedFrontmatter.changed;
 
   for (const blockId of options.blockIds) {
     const { blockChunk, innerText } = extractTemplateBlock(templateText, blockId);