@aipper/aiws 0.0.25 → 0.0.27

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.27",
+  "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.27"
   },
   "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

@@ -71,6 +71,13 @@ export async function computeChangeNextAdvice(gitRoot, changeId, deps) {
     advice.actions.push("真值/合同已变化：先对齐 `AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md` 与 proposal/tasks");
     advice.actions.push(`确认后同步基线：\`aiws change sync ${changeId}\``);
   }
+  if (status.terminatedReuse) {
+    advice.actions.push(status.terminatedReuse.message);
+    advice.prohibitions.push(`不要继续在 change/${changeId} 上开发或提交新改动`);
+    advice.recommended.push(`优先续跑收尾：\`aiws change finish ${changeId} --push\``);
+    advice.recommended.push(`仅在你明确只需要本地归档恢复时，才手工运行 \`aiws change archive ${changeId}\``);
+    return advice;
+  }
 
   const proposalPath = path.join(deps.changeDirAbs(gitRoot, changeId), "proposal.md");
   const tasksPath = path.join(deps.changeDirAbs(gitRoot, changeId), "tasks.md");
@@ -96,6 +103,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 +114,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 +132,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/`");
   }
@@ -153,7 +163,9 @@ export function renderChangeStateMarkdown(input) {
   lines.push("");
   lines.push("## Phase");
   lines.push(`- Phase: \`${input.status.phase}\``);
-  lines.push(`- Tasks: ${input.status.tasks.done}/${input.status.tasks.total} (unchecked=${input.status.tasks.unchecked})`);
+  lines.push(
+    `- Tasks: ${input.status.tasks.done}/${input.status.tasks.total} (unchecked=${input.status.tasks.unchecked}, optional_open=${input.status.tasks.optionalUnchecked || 0}, n_a=${input.status.tasks.naCount || 0})`,
+  );
   lines.push("");
   lines.push("## Bindings");
   if (input.status.reqId) lines.push(`- Req_ID: \`${input.status.reqId}\``);

package/src/commands/change-evidence.js

@@ -293,7 +293,9 @@ export function buildDeliverySummary(options) {
   lines.push("");
   lines.push("## Status");
   lines.push(`- Phase: \`${status.phase}\``);
-  lines.push(`- Tasks: ${status.tasks.done}/${status.tasks.total} (unchecked=${status.tasks.unchecked})`);
+  lines.push(
+    `- Tasks: ${status.tasks.done}/${status.tasks.total} (unchecked=${status.tasks.unchecked}, optional_open=${status.tasks.optionalUnchecked || 0}, n_a=${status.tasks.naCount || 0})`,
+  );
   lines.push(`- Truth drift: ${status.driftFiles.length > 0 ? status.driftFiles.join(", ") : "(none)"}`);
   lines.push("");
   lines.push("## Collaboration");

package/src/commands/change-lifecycle.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import fs from "node:fs/promises";
+import { checkboxStats } from "./change-task-stats.js";
 
 /**
  * @param {{
@@ -144,16 +145,17 @@ export async function runChangeSyncWorkflow(input, deps) {
  */
 export async function runChangeArchiveWorkflow(input, deps) {
   const { gitRoot, changeId, changeDir } = input;
-  await deps.changeValidateCommand({ changeId, strict: true, allowTruthDrift: input.force });
+  await deps.changeValidateCommand({ changeId, strict: true, allowTruthDrift: input.force, allowFinishedUnarchived: true });
 
   const tasksAbs = path.join(changeDir, "tasks.md");
   if (await deps.pathExists(tasksAbs)) {
     const tasksText = await deps.readText(tasksAbs);
-    if (/- \[ \]/.test(tasksText)) {
+    const taskStats = checkboxStats(tasksText);
+    if (taskStats.unchecked > 0) {
       if (!input.force) {
-        throw new deps.UserError("tasks.md still has unchecked tasks; complete them or pass --force");
+        throw new deps.UserError("tasks.md still has unchecked required tasks; complete them or pass --force");
       }
-      console.error("warn: tasks.md still has unchecked tasks; continuing due to --force");
+      console.error("warn: tasks.md still has unchecked required tasks; continuing due to --force");
     }
   }
 
@@ -208,12 +210,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

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { checkboxStats } from "./change-task-stats.js";
 
 /**
  * @param {{
@@ -90,15 +91,21 @@ export async function renderChangeNextOutput(input, deps) {
 
   /** @type {string[]} */
   const lines = [];
+  if (status.terminatedReuse) {
+    for (const action of advice.actions) lines.push(`- ${action}`);
+    for (const recommendation of advice.recommended) lines.push(`- ${recommendation}`);
+    for (const prohibition of advice.prohibitions) lines.push(`- ${prohibition}`);
+    return lines.join("\n") + "\n";
+  }
   if (advice.actions.length > 0) {
     lines.push(`- ${deps.planVerifyHint(changeId)}`);
     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,21 +114,16 @@ 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";
 }
-
-/**
- * @param {string} text
- */
-function checkboxStats(text) {
-  const total = (text.match(/^- \[[ xX]\]/gm) || []).length;
-  const done = (text.match(/^- \[[xX]\]/gm) || []).length;
-  const unchecked = (text.match(/^- \[ \]/gm) || []).length;
-  return { total, done, unchecked, hasCheckboxes: total > 0 };
-}

package/src/commands/change-start.js

@@ -20,14 +20,6 @@ export async function checkWorktreePrereqs(gitRoot, deps) {
   return { ok: true };
 }
 
-/**
- * @param {{ stdout: string, stderr: string }} res
- */
-export function outputMentionsRecurseSubmodules(res) {
-  const out = `${res.stderr || ""}\n${res.stdout || ""}`;
-  return out.includes("recurse-submodules");
-}
-
 /**
  * @param {string} changeDir
  * @param {string} baseBranch
@@ -85,34 +77,24 @@ export function resolveDefaultWorktreeDir(gitRoot, worktreeDir, changeId) {
  */
 export async function switchOrCreateStartBranch(gitRoot, options, deps) {
   if (options.hasBranch) {
-    let sw = await deps.runCommand("git", ["switch", ...(options.hasGitmodules ? ["--recurse-submodules"] : []), options.branch], { cwd: gitRoot });
-    if (sw.code !== 0 && options.hasGitmodules && outputMentionsRecurseSubmodules(sw)) {
-      console.error("warn: git switch does not support --recurse-submodules; switching without it (submodules may be out of sync).");
-      sw = await deps.runCommand("git", ["switch", options.branch], { cwd: gitRoot });
+    if (options.hasGitmodules) {
+      console.error("warn: .gitmodules detected; switching only the superproject branch (submodules stay on their current/pin branches).");
     }
+    let sw = await deps.runCommand("git", ["switch", options.branch], { cwd: gitRoot });
     if (sw.code === 0) return;
 
-    let co = await deps.runCommand("git", ["checkout", ...(options.hasGitmodules ? ["--recurse-submodules"] : []), options.branch], { cwd: gitRoot });
-    if (co.code !== 0 && options.hasGitmodules && outputMentionsRecurseSubmodules(co)) {
-      console.error("warn: git checkout does not support --recurse-submodules; checking out without it (submodules may be out of sync).");
-      co = await deps.runCommand("git", ["checkout", options.branch], { cwd: gitRoot });
-    }
+    let co = await deps.runCommand("git", ["checkout", options.branch], { cwd: gitRoot });
     if (co.code !== 0) throw new deps.UserError("Failed to switch branch.", { details: co.stderr || co.stdout });
     return;
   }
 
-  let sw = await deps.runCommand("git", ["switch", ...(options.hasGitmodules ? ["--recurse-submodules"] : []), "-c", options.branch], { cwd: gitRoot });
-  if (sw.code !== 0 && options.hasGitmodules && outputMentionsRecurseSubmodules(sw)) {
-    console.error("warn: git switch does not support --recurse-submodules; switching without it (submodules may be out of sync).");
-    sw = await deps.runCommand("git", ["switch", "-c", options.branch], { cwd: gitRoot });
+  if (options.hasGitmodules) {
+    console.error("warn: .gitmodules detected; creating and switching only the superproject branch (submodules stay on their current/pin branches).");
   }
+  let sw = await deps.runCommand("git", ["switch", "-c", options.branch], { cwd: gitRoot });
   if (sw.code === 0) return;
 
-  let co = await deps.runCommand("git", ["checkout", ...(options.hasGitmodules ? ["--recurse-submodules"] : []), "-b", options.branch], { cwd: gitRoot });
-  if (co.code !== 0 && options.hasGitmodules && outputMentionsRecurseSubmodules(co)) {
-    console.error("warn: git checkout does not support --recurse-submodules; checking out without it (submodules may be out of sync).");
-    co = await deps.runCommand("git", ["checkout", "-b", options.branch], { cwd: gitRoot });
-  }
+  let co = await deps.runCommand("git", ["checkout", "-b", options.branch], { cwd: gitRoot });
   if (co.code !== 0) throw new deps.UserError("Failed to create branch.", { details: co.stderr || co.stdout });
 }
 

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

@@ -32,7 +32,9 @@ export async function renderChangeStatusOutput(input, deps) {
   lines.push(`meta: ${status.metaState}`);
   if (status.reqId) lines.push(`Req_ID: ${status.reqId}`);
   if (status.probId) lines.push(`Problem_ID: ${status.probId}`);
-  lines.push(`tasks: ${status.tasks.done}/${status.tasks.total} (unchecked=${status.tasks.unchecked})`);
+  lines.push(
+    `tasks: ${status.tasks.done}/${status.tasks.total} (unchecked=${status.tasks.unchecked}, optional_open=${status.tasks.optionalUnchecked || 0}, n_a=${status.tasks.naCount || 0})`,
+  );
   if (status.reviewSignals) {
     lines.push(`review_signal: effective=${status.reviewSignals.effectiveCount} source=${status.reviewSignals.source}`);
   }
@@ -89,15 +91,21 @@ export async function renderChangeStatusOutput(input, deps) {
 
   lines.push("");
   lines.push("Next (recommended):");
+  if (status.terminatedReuse) {
+    lines.push(`- ${status.terminatedReuse.message}`);
+    lines.push(`- rerun \`aiws change finish ${status.changeId} --push\` to resume the unfinished finish/archive flow`);
+    lines.push(`- do not continue development or commit on \`change/${status.changeId}\``);
+    return lines.join("\n") + "\n";
+  }
   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-task-stats.js

@@ -0,0 +1,64 @@
+/**
+ * Parse checkbox tasks with AIWS-specific control markers.
+ *
+ * Supported markers:
+ * - `[optional]`: unchecked optional tasks do not block archive/finish.
+ * - `[n/a: ...]` / `[na: ...]` / `[not-applicable: ...]`: task is treated as closed.
+ *
+ * Returned `total/done/unchecked` are the effective gate counts. Optional open
+ * tasks are reported separately via `optionalUnchecked`.
+ *
+ * @param {string} text
+ */
+export function checkboxStats(text) {
+  const lines = String(text || "").split(/\r?\n/);
+  let total = 0;
+  let done = 0;
+  let unchecked = 0;
+  let totalAll = 0;
+  let doneAll = 0;
+  let uncheckedAll = 0;
+  let optionalTotal = 0;
+  let optionalUnchecked = 0;
+  let naCount = 0;
+
+  for (const rawLine of lines) {
+    const match = rawLine.match(/^\s*-\s+\[([ xX])\]\s+(.*)$/);
+    if (!match) continue;
+    totalAll += 1;
+    const checked = String(match[1] || "").toLowerCase() === "x";
+    const body = String(match[2] || "");
+    const isOptional = /\[(?:optional|Optional)\]/.test(body);
+    const isNa = /\[(?:n\/a|na|not-applicable)\s*:[^\]]+\]/i.test(body);
+
+    if (checked) doneAll += 1;
+    else uncheckedAll += 1;
+
+    if (isOptional) {
+      optionalTotal += 1;
+      if (!checked && !isNa) optionalUnchecked += 1;
+      continue;
+    }
+
+    total += 1;
+    if (checked || isNa) {
+      done += 1;
+      if (isNa) naCount += 1;
+    } else {
+      unchecked += 1;
+    }
+  }
+
+  return {
+    total,
+    done,
+    unchecked,
+    hasCheckboxes: totalAll > 0,
+    totalAll,
+    doneAll,
+    uncheckedAll,
+    optionalTotal,
+    optionalUnchecked,
+    naCount,
+  };
+}

package/src/commands/change.js

@@ -21,6 +21,7 @@ import { runChangeArchiveWorkflow, runChangeSyncWorkflow } from "./change-lifecy
 import { renderMetricsSummaryOutput } from "./change-metrics-command.js";
 import { renderChangeNextOutput } from "./change-next-command.js";
 import { runChangeStateCommand } from "./change-state-command.js";
+import { checkboxStats } from "./change-task-stats.js";
 import { runChangeValidateCommand } from "./change-validate-entry.js";
 import {
   computeChangeNextAdvice as computeChangeNextAdviceModel,
@@ -350,6 +351,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,19 +377,86 @@ 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
   }
   return null;
 }
 
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @returns {Promise<null | { kind: "archived" | "finished_unarchived", archivedChangeDir?: string, archivedHandoffRel?: string, lifecycle?: any }>}
+ */
+async function detectTerminatedChange(gitRoot, changeId) {
+  const changeDir = changeDirAbs(gitRoot, changeId);
+  const archiveRoot = path.join(gitRoot, "changes", "archive");
+  const activeExists = await pathExists(changeDir);
+  if (!activeExists) {
+    const archivedChangeDir = await findArchivedChange(archiveRoot, changeId);
+    if (!archivedChangeDir) return null;
+    const archivedHandoffPath = path.join(archivedChangeDir, "handoff.md");
+    return {
+      kind: "archived",
+      archivedChangeDir,
+      archivedHandoffRel: (await pathExists(archivedHandoffPath)) ? path.relative(gitRoot, archivedHandoffPath) : "",
+    };
+  }
+
+  const lifecycle = summarizeLifecycleSignals(await readChangeMetrics(changeDir, { pathExists, readText }));
+  if (lifecycle.finishState !== "done") return null;
+  return { kind: "finished_unarchived", lifecycle };
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {Awaited<ReturnType<typeof detectTerminatedChange>>} terminated
+ * @param {string} action
+ */
+function terminatedChangeError(gitRoot, changeId, terminated, action) {
+  if (terminated?.kind === "archived") {
+    return new UserError(`Change ${changeId} is already archived.`, {
+      details:
+        `change: ${changeId}\n` +
+        `archived: ${path.relative(gitRoot, terminated.archivedChangeDir || "")}\n` +
+        (terminated.archivedHandoffRel ? `handoff: ${terminated.archivedHandoffRel}\n` : "") +
+        `next: create a new follow-up change instead of reusing change/${changeId}` +
+        (action ? `\nblocked: ${action}` : ""),
+    });
+  }
+  return new UserError(`Change ${changeId} has unfinished finish closeout; resume finish before any follow-up work.`, {
+    details:
+      `change: ${changeId}\n` +
+      `branch: change/${changeId}\n` +
+      `next: rerun \`aiws change finish ${changeId} --push\` to complete push/archive closeout` +
+      `\nfallback: if you intentionally only need local archive recovery, run \`aiws change archive ${changeId}\`` +
+      (action ? `\nblocked: ${action}` : ""),
+  });
+}
+
+/**
+ * @param {string} command
+ * @param {Awaited<ReturnType<typeof detectTerminatedChange>>} terminated
+ * @param {{ allowFinishedUnarchived?: boolean }} [options]
+ */
+function isTerminatedAllowed(command, terminated, options = {}) {
+  if (!terminated) return true;
+  if (terminated.kind === "finished_unarchived") {
+    if (command === "archive") return true;
+    if (command === "finish") return true;
+    if (command === "status" || command === "next") return true;
+    if (options.allowFinishedUnarchived === true) return true;
+  }
+  return false;
+}
+
 /**
  * Extract a brief summary from handoff.md content.
  * @param {string} text
@@ -648,7 +732,21 @@ export async function computeChangeStatus(gitRoot, changeId) {
   const evidencePath = proposal.state === "ok" ? extractId("Evidence_Path", proposal.text) || extractId("Evidence_Path(s)", proposal.text) : "";
   const evidencePaths = splitDeclaredValues(evidencePath);
   const evidence = await analyzeEvidencePaths(gitRoot, changeId, evidencePaths);
-  const taskProgress = tasks.state === "ok" ? checkboxStats(tasks.text) : { total: 0, done: 0, unchecked: 0, hasCheckboxes: false };
+  const taskProgress =
+    tasks.state === "ok"
+      ? checkboxStats(tasks.text)
+      : {
+          total: 0,
+          done: 0,
+          unchecked: 0,
+          hasCheckboxes: false,
+          totalAll: 0,
+          doneAll: 0,
+          uncheckedAll: 0,
+          optionalTotal: 0,
+          optionalUnchecked: 0,
+          naCount: 0,
+        };
 
   const curTruth = await snapshotTruthShaOnly(gitRoot);
   const { baselineLabel, baselineAt, driftFiles } = meta ? truthDrift(curTruth, meta) : { baselineLabel: "-", baselineAt: "", driftFiles: [] };
@@ -703,10 +801,25 @@ export async function computeChangeStatus(gitRoot, changeId) {
   if (!taskProgress.hasCheckboxes) blockersStrict.push("tasks.md has no checkbox tasks ('- [ ]' or '- [x]')");
   if (driftFiles.length > 0) blockersStrict.push(`truth drift vs ${baselineLabel} baseline (run \`aiws change sync ${changeId}\`)`);
 
+  const lifecycle = summarizeLifecycleSignals(metrics);
+  const terminatedReuse =
+    lifecycle.finishState === "done"
+      ? {
+          kind: "finished_unarchived",
+          message: `change/${changeId} has unfinished finish closeout; rerun \`aiws change finish ${changeId} --push\` to complete archive/push`,
+        }
+      : null;
+  if (terminatedReuse) {
+    blockersStrict.push(terminatedReuse.message);
+  }
+
   blockersArchive.push(...blockersStrict);
-  if (taskProgress.unchecked > 0) blockersArchive.push(`tasks.md still has unchecked tasks (${taskProgress.unchecked} items)`);
+  if (taskProgress.unchecked > 0) blockersArchive.push(`tasks.md still has unchecked required tasks (${taskProgress.unchecked} items)`);
   const phase = inferChangePhase(blockersStrict, taskProgress);
-  const lifecycle = summarizeLifecycleSignals(metrics);
+  if (terminatedReuse) {
+    lifecycle.finishState = "resume_required";
+    lifecycle.finishStateReason = "archive_pending";
+  }
   const scopeGate = computeScopeGate(lifecycle);
 
   const baseStatus = {
@@ -739,9 +852,10 @@ export async function computeChangeStatus(gitRoot, changeId) {
     driftFiles,
     blockersStrict,
     blockersArchive,
+    terminatedReuse,
     hints: {
       planVerify: planVerifyHint(changeId),
-      dev: "质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`",
+      dev: "质量门通过后再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`",
     },
   };
   const governance = await inferChangeGovernance(baseStatus);
@@ -772,16 +886,6 @@ export async function validateChangeArtifacts(gitRoot, changeId, options) {
   });
 }
 
-/**
- * @param {string} text
- */
-function checkboxStats(text) {
-  const total = (text.match(/^- \[[ xX]\]/gm) || []).length;
-  const done = (text.match(/^- \[[xX]\]/gm) || []).length;
-  const unchecked = (text.match(/^- \[ \]/gm) || []).length;
-  return { total, done, unchecked, hasCheckboxes: total > 0 };
-}
-
 /**
  * @param {string} text
  */
@@ -817,8 +921,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 +942,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
  */
@@ -922,13 +1030,17 @@ async function runPython(gitRoot, args) {
 /**
  * @param {string} gitRoot
  * @param {string | undefined} changeId
- * @param {{ command: string }} options
+ * @param {{ command: string, allowFinishedUnarchived?: boolean }} options
  */
 async function resolveChangeId(gitRoot, changeId, options) {
-  if (changeId) return changeId;
-  const branch = await currentBranch(gitRoot);
-  const inferred = inferChangeIdFromBranch(branch);
-  if (inferred) return inferred;
+  const resolved = changeId || inferChangeIdFromBranch(await currentBranch(gitRoot));
+  if (resolved) {
+    const terminated = await detectTerminatedChange(gitRoot, resolved);
+    if (!isTerminatedAllowed(options.command, terminated, { allowFinishedUnarchived: options.allowFinishedUnarchived === true })) {
+      throw terminatedChangeError(gitRoot, resolved, terminated, `aiws change ${options.command}`);
+    }
+    return resolved;
+  }
   throw new UserError(`usage: aiws change ${options.command} <change-id> (or switch to branch change/<change-id>)`);
 }
 
@@ -1098,6 +1210,8 @@ async function changeNewAtGitRoot(gitRoot, options) {
 
   const changeId = String(options.changeId || "").trim();
   assertValidChangeId(changeId);
+  const terminated = await detectTerminatedChange(gitRoot, changeId);
+  if (terminated) throw terminatedChangeError(gitRoot, changeId, terminated, "aiws change new");
 
   const title = (options.title ? String(options.title) : changeId).trim() || changeId;
   const createdAt = nowIsoUtc();
@@ -1183,6 +1297,8 @@ export async function changeStartCommand(options) {
 
   const changeId = String(options.changeId || "").trim();
   assertValidChangeId(changeId);
+  const terminated = await detectTerminatedChange(gitRoot, changeId);
+  if (terminated) throw terminatedChangeError(gitRoot, changeId, terminated, "aiws change start");
 
   const startFromBranch = await currentBranch(gitRoot);
   const branch = `change/${changeId}`;
@@ -1453,10 +1569,15 @@ 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 }));
-  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\``,
+  const terminated = await detectTerminatedChange(gitRoot, resolvedChangeId);
+  if (terminated?.kind === "archived") throw terminatedChangeError(gitRoot, resolvedChangeId, terminated, "aiws change finish");
+  const resumeFinishedUnarchived = terminated?.kind === "finished_unarchived";
+  if (resumeFinishedUnarchived && options.push !== true) {
+    throw new UserError("Change finish closeout is pending; rerun with --push.", {
+      details:
+        `change: ${resolvedChangeId}\n` +
+        `next: rerun \`aiws change finish ${resolvedChangeId} --push\` to complete archive/push closeout\n` +
+        `fallback: if you intentionally only need local archive recovery, run \`aiws change archive ${resolvedChangeId}\``,
     });
   }
   const { changeId, changeBranch, into, cur, changeWt } = await resolveFinishContext(gitRoot, { ...options, changeId: resolvedChangeId }, {
@@ -1486,6 +1607,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 });
@@ -1505,9 +1641,14 @@ export async function changeFinishCommand(options) {
   }
 
   await appendMetricsEvent(gitRoot, changeId, "finish_local", finishBasePayload);
+  if (resumeFinishedUnarchived) {
+    console.log(`resume: continuing previously finished change ${changeId} to complete remaining finish steps`);
+  }
 
   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 +1732,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 +1783,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:");
@@ -1793,13 +1979,16 @@ export async function changeEvidenceCommand(options) {
 /**
  * aiws change validate
  *
- * @param {{ changeId?: string, strict: boolean, allowTruthDrift: boolean, checkEvidence: boolean, checkScope: boolean }} options
+ * @param {{ changeId?: string, strict: boolean, allowTruthDrift: boolean, checkEvidence: boolean, checkScope: boolean, allowFinishedUnarchived?: boolean }} options
  */
 export async function changeValidateCommand(options) {
   const gitRoot = await resolveGitRoot(process.cwd());
   await ensureTruthFiles(gitRoot);
 
-  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "validate" });
+  const changeId = await resolveChangeId(gitRoot, options.changeId, {
+    command: "validate",
+    allowFinishedUnarchived: options.allowFinishedUnarchived === true,
+  });
   assertValidChangeId(changeId);
   const result = await runChangeValidateCommand(
     {

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/governance.js

@@ -26,7 +26,9 @@ function collectGovernanceSignals(status, governance) {
   const validateStampReady = reviewGates?.validateStamp?.ready === true;
 
   return {
+    change_id: String(status?.changeId || ""),
     blockers_strict_count: Array.isArray(status?.blockersStrict) ? status.blockersStrict.length : 0,
+    finish_resume_required: status?.terminatedReuse?.kind === "finished_unarchived",
     tasks_unchecked: Number(status?.tasks?.unchecked || 0),
     review_effective_count: reviewEffectiveCount,
     evidence_persistent_count: Number(status?.evidence?.counts?.persistent || 0),

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);