@aipper/aiws 0.0.26 → 0.0.28

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@aipper/aiws",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "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.26"
+    "@aipper/aiws-spec": "0.0.28"
   },
   "files": [
     "bin",

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");
@@ -156,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");
     }
   }
 

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,6 +91,12 @@ 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}`);
@@ -120,13 +127,3 @@ export async function renderChangeNextOutput(input, deps) {
   }
   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,6 +91,12 @@ 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) 后复跑质量门，再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`");

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,
@@ -388,6 +389,74 @@ async function findArchivedChange(archiveDir, changeId) {
   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
@@ -663,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: [] };
@@ -718,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 = {
@@ -754,6 +852,7 @@ export async function computeChangeStatus(gitRoot, changeId) {
     driftFiles,
     blockersStrict,
     blockersArchive,
+    terminatedReuse,
     hints: {
       planVerify: planVerifyHint(changeId),
       dev: "质量门通过后再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`",
@@ -787,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
  */
@@ -941,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>)`);
 }
 
@@ -1117,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();
@@ -1202,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}`;
@@ -1472,27 +1569,15 @@ export async function changeFinishCommand(options) {
 
   const resolvedChangeId = await resolveChangeId(gitRoot, options.changeId, { command: "finish" });
   assertValidChangeId(resolvedChangeId);
-  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.", {
+  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` +
-        `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}\n` +
-        `next: legacy finish is already done; run \`aiws change archive ${resolvedChangeId}\` once, then continue with \`$ws-handoff\``,
+        `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 }, {
@@ -1556,6 +1641,9 @@ 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;
@@ -1891,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/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),