@aipper/aiws 0.0.24 → 0.0.26

package/src/commands/change.js

@@ -5,12 +5,66 @@ import { runCommand } from "../exec.js";
 import { pathExists, readText, writeText, ensureDir } from "../fs.js";
 import { UserError } from "../errors.js";
 import { loadTemplate } from "../spec.js";
+import { effectiveReviewCount, governanceGuidanceLines, inferChangeGovernance } from "../governance.js";
 import { copyTemplateFileToWorkspace } from "../template.js";
+import { collectGitStatus } from "./change-git-status.js";
+import {
+  analyzeEvidencePaths,
+  collectCollaborationArtifacts,
+  planVerifyHint,
+  relFromRoot,
+} from "./change-evidence.js";
+import { runChangeEvidenceCommand } from "./change-evidence-entry.js";
+import { runChangeEvidenceWorkflow } from "./change-evidence-command.js";
+import { runChangeArchiveCommand, runChangeSyncCommand } from "./change-lifecycle-entry.js";
+import { runChangeArchiveWorkflow, runChangeSyncWorkflow } from "./change-lifecycle.js";
+import { renderMetricsSummaryOutput } from "./change-metrics-command.js";
+import { renderChangeNextOutput } from "./change-next-command.js";
+import { runChangeStateCommand } from "./change-state-command.js";
+import { runChangeValidateCommand } from "./change-validate-entry.js";
+import {
+  computeChangeNextAdvice as computeChangeNextAdviceModel,
+  renderChangeStateMarkdown,
+  resolveChangeWorktreeHint,
+} from "./change-advice.js";
+import {
+  cleanupWorktreePath,
+  isGitRepository,
+  listSubmodulesFromGitmodules,
+  pushSubmodulesForFinish,
+  resolveFinishContext,
+  resolvePushTarget,
+} from "./change-finish.js";
+import {
+  checkWorktreePrereqs,
+  maybeRecordBaseBranch,
+  prepareNoSwitchBranch,
+  resolveDefaultWorktreeDir,
+  switchOrCreateStartBranch,
+} from "./change-start.js";
+import {
+  collectFinishGateErrors,
+  collectReviewGates,
+  collectReviewSignals,
+} from "./change-review-gates.js";
+import {
+  computeScopeGate,
+  scopeGateFailureAction,
+  scopeGatePassedRecommendation,
+  scopeGatePendingRecommendation,
+} from "./change-scope-gate.js";
+import {
+  readChangeMetrics,
+  resolveChangeStatusContext,
+  summarizeLifecycleSignals,
+  truthDrift,
+} from "./change-status-context.js";
+import { renderChangeStatusOutput } from "./change-status-command.js";
+import { validateChangeArtifacts as validateChangeArtifactsModel } from "./change-validate.js";
 import { hooksInstallCommand } from "./hooks-install.js";
 
 const CHANGE_BRANCH_RE = /^(change|changes|ws|ws-change)\/([a-z0-9]+(?:-[a-z0-9]+)*)$/;
 const CHANGE_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-
 /**
  * @param {string} changeId
  */
@@ -107,62 +161,6 @@ async function checkGitClean(gitRoot) {
   return { clean: false, details: truncated };
 }
 
-/**
- * @param {string} gitRoot
- * @returns {Promise<{ ok: true } | { ok: false, reason: "no_commit" | "missing_truth", missing?: string[] }>}
- */
-async function checkWorktreePrereqs(gitRoot) {
-  if (!(await hasHeadCommit(gitRoot))) return { ok: false, reason: "no_commit" };
-  /** @type {string[]} */
-  const missingInHead = [];
-  for (const rel of ["AI_PROJECT.md", "AI_WORKSPACE.md", "REQUIREMENTS.md"]) {
-    const ok = await runCommand("git", ["cat-file", "-e", `HEAD:${rel}`], { cwd: gitRoot }).then((r) => r.code === 0);
-    if (!ok) missingInHead.push(rel);
-  }
-  if (missingInHead.length > 0) return { ok: false, reason: "missing_truth", missing: missingInHead };
-  return { ok: true };
-}
-
-/**
- * Best-effort detection for "unknown option" errors related to --recurse-submodules.
- *
- * We only fall back when the option itself appears in output, to avoid silently
- * bypassing submodule safety checks when switching fails for real reasons
- * (e.g. dirty submodules).
- *
- * @param {{ stdout: string, stderr: string }} res
- */
-function outputMentionsRecurseSubmodules(res) {
-  const out = `${res.stderr || ""}\n${res.stdout || ""}`;
-  return out.includes("recurse-submodules");
-}
-
-/**
- * @param {string} changeDir
- * @param {string} baseBranch
- * @param {string} changeBranch
- */
-async function maybeRecordBaseBranch(changeDir, baseBranch, changeBranch) {
-  const b = String(baseBranch || "").trim();
-  if (!b) return;
-  if (b === String(changeBranch || "").trim()) return;
-  const metaPath = path.join(changeDir, ".ws-change.json");
-  if (!(await pathExists(metaPath))) return;
-  /** @type {any} */
-  let meta = null;
-  try {
-    meta = JSON.parse(await readText(metaPath));
-  } catch {
-    meta = null;
-  }
-  if (!meta || typeof meta !== "object") return;
-  const cur = String(meta.base_branch || "").trim();
-  if (cur) return;
-  meta.base_branch = b;
-  meta.base_branch_set_at = nowIsoUtc();
-  await writeText(metaPath, JSON.stringify(meta, null, 2) + "\n");
-}
-
 /**
  * @param {string} gitRoot
  * @returns {Promise<Array<{ worktree: string, head: string, branch: string, locked: boolean, lockReason: string }>>}
@@ -207,456 +205,6 @@ async function listGitWorktrees(gitRoot) {
   return out;
 }
 
-/**
- * @param {string} gitRoot
- * @param {string} branch
- * @param {string | undefined} preferredRemote
- */
-async function resolvePushTarget(gitRoot, branch, preferredRemote) {
-  const remoteRaw = String(preferredRemote || "").trim();
-  const branchRemoteRes = await runCommand("git", ["config", "--get", `branch.${branch}.remote`], { cwd: gitRoot });
-  const trackedRemote = String(branchRemoteRes.stdout || "").trim();
-
-  const branchMergeRes = await runCommand("git", ["config", "--get", `branch.${branch}.merge`], { cwd: gitRoot });
-  const trackedMergeRef = String(branchMergeRes.stdout || "").trim();
-  const trackedBranch = trackedMergeRef.startsWith("refs/heads/") ? trackedMergeRef.slice("refs/heads/".length) : "";
-
-  const remote = remoteRaw || trackedRemote || "origin";
-  const remoteBranch = trackedBranch || branch;
-  const refspec = remoteBranch === branch ? branch : `${branch}:${remoteBranch}`;
-
-  return { remote, remoteBranch, refspec, trackedRemote, trackedMergeRef };
-}
-
-/**
- * @param {string} gitRoot
- * @param {string} worktreePath
- */
-async function cleanupWorktreePath(gitRoot, worktreePath) {
-  const abs = path.resolve(worktreePath);
-  if (abs === path.resolve(gitRoot)) {
-    return { status: "skipped", reason: "current_worktree", worktree: abs };
-  }
-
-  const worktrees = await listGitWorktrees(gitRoot);
-  const worktreeEntry = worktrees.find((w) => path.resolve(w.worktree) === abs);
-  if (worktreeEntry?.locked) {
-    return { status: "skipped", reason: "locked", worktree: abs, details: worktreeEntry.lockReason };
-  }
-
-  if (!(await pathExists(abs))) {
-    const prune = await runCommand("git", ["worktree", "prune"], { cwd: gitRoot });
-    if (prune.code !== 0) {
-      throw new UserError("Failed to prune stale git worktree metadata.", { details: prune.stderr || prune.stdout });
-    }
-    return { status: "pruned-missing", worktree: abs };
-  }
-
-  const clean = await checkGitClean(abs);
-  if (!clean.clean) {
-    return { status: "skipped", reason: "dirty", worktree: abs, details: clean.details };
-  }
-
-  let rm = await runCommand("git", ["worktree", "remove", abs], { cwd: gitRoot });
-  if (rm.code !== 0) {
-    const out = `${rm.stderr || ""}\n${rm.stdout || ""}`;
-    if (out.includes("working trees containing submodules cannot be moved or removed")) {
-      rm = await runCommand("git", ["worktree", "remove", "--force", abs], { cwd: gitRoot });
-    }
-  }
-  if (rm.code !== 0) {
-    throw new UserError("Failed to remove change worktree.", { details: rm.stderr || rm.stdout });
-  }
-
-  const prune = await runCommand("git", ["worktree", "prune"], { cwd: gitRoot });
-  if (prune.code !== 0) {
-    throw new UserError("Failed to prune git worktree metadata after remove.", { details: prune.stderr || prune.stdout });
-  }
-
-  return { status: "removed", worktree: abs };
-}
-
-/**
- * @param {string} gitRoot
- * @returns {Promise<Array<{ name: string, path: string }>>}
- */
-async function listSubmodulesFromGitmodules(gitRoot) {
-  const gitmodules = path.join(gitRoot, ".gitmodules");
-  if (!(await pathExists(gitmodules))) return [];
-
-  const list = await runCommand("git", ["config", "--file", ".gitmodules", "--get-regexp", "^submodule\\..*\\.path$"], { cwd: gitRoot });
-  if (list.code !== 0) return [];
-
-  /** @type {Array<{ name: string, path: string }>} */
-  const subs = [];
-  for (const raw of String(list.stdout || "").split("\n")) {
-    const line = raw.trim();
-    if (!line) continue;
-    const idx = line.indexOf(" ");
-    if (idx <= 0) continue;
-    const key = line.slice(0, idx).trim();
-    const subPath = line.slice(idx + 1).trim();
-    const m = key.match(/^submodule\.(.+)\.path$/);
-    if (!m) continue;
-    const name = String(m[1] || "").trim();
-    if (!name || !subPath) continue;
-    subs.push({ name, path: subPath });
-  }
-  return subs;
-}
-
-/**
- * @param {string} targetsPath
- */
-async function parseSubmoduleTargetsFile(targetsPath) {
-  /** @type {Map<string, { branch: string, remote: string }>} */
-  const parsed = new Map();
-  /** @type {string[]} */
-  const errors = [];
-
-  if (!(await pathExists(targetsPath))) {
-    return { parsed, errors };
-  }
-
-  const text = await readText(targetsPath);
-  const lines = String(text || "").split(/\r?\n/);
-  for (let i = 0; i < lines.length; i += 1) {
-    const raw = lines[i] || "";
-    const line = raw.trim();
-    if (!line || line.startsWith("#")) continue;
-    const parts = line.split(/\s+/).filter(Boolean);
-    if (parts.length < 2) {
-      errors.push(`${path.basename(targetsPath)}:${i + 1} invalid line (expected: <path> <target_branch> [remote])`);
-      continue;
-    }
-    const subPath = String(parts[0] || "").trim();
-    const targetBranch = String(parts[1] || "").trim();
-    const remote = String(parts[2] || "origin").trim() || "origin";
-    if (!subPath) {
-      errors.push(`${path.basename(targetsPath)}:${i + 1} missing submodule path`);
-      continue;
-    }
-    if (parsed.has(subPath)) {
-      errors.push(`${path.basename(targetsPath)}:${i + 1} duplicate submodule path: ${subPath}`);
-      continue;
-    }
-    if (!targetBranch || ["<fill-me>", "<fill_me>", "tbd", "TBD"].includes(targetBranch)) {
-      errors.push(`${path.basename(targetsPath)}:${i + 1} missing/placeholder target_branch for ${subPath}`);
-      continue;
-    }
-    parsed.set(subPath, { branch: targetBranch, remote });
-  }
-
-  return { parsed, errors };
-}
-
-/**
- * @param {string} repoPath
- * @param {string} rev
- */
-async function gitHasRevision(repoPath, rev) {
-  if (!(await pathExists(repoPath))) return false;
-  const res = await runCommand("git", ["-C", repoPath, "cat-file", "-e", `${rev}^{commit}`], { cwd: repoPath });
-  return res.code === 0;
-}
-
-/**
- * @param {string} repoPath
- * @returns {Promise<boolean>}
- */
-async function isGitRepository(repoPath) {
-  if (!(await pathExists(repoPath))) return false;
-  const res = await runCommand("git", ["-C", repoPath, "rev-parse", "--git-dir"], { cwd: repoPath });
-  return res.code === 0;
-}
-
-/**
- * @param {string} targetRepoPath
- * @param {string} sha
- * @param {string | undefined} fallbackRepoPath
- */
-async function ensureRevisionAvailable(targetRepoPath, sha, fallbackRepoPath) {
-  if (await gitHasRevision(targetRepoPath, sha)) return;
-  const fallback = String(fallbackRepoPath || "").trim();
-  if (!fallback) {
-    throw new UserError("Required submodule commit is not available locally.", {
-      details: `repo: ${targetRepoPath}\ncommit: ${sha}`,
-    });
-  }
-  if (!(await gitHasRevision(fallback, sha))) {
-    throw new UserError("Required submodule commit is missing in both target and change worktrees.", {
-      details: `target_repo: ${targetRepoPath}\nchange_repo: ${fallback}\ncommit: ${sha}`,
-    });
-  }
-  const fetch = await runCommand("git", ["-C", targetRepoPath, "fetch", fallback, sha], { cwd: targetRepoPath });
-  if (fetch.code !== 0 || !(await gitHasRevision(targetRepoPath, sha))) {
-    throw new UserError("Failed to import submodule commit from change worktree.", {
-      details: `target_repo: ${targetRepoPath}\nchange_repo: ${fallback}\ncommit: ${sha}\n\n${fetch.stderr || fetch.stdout}`,
-    });
-  }
-}
-
-/**
- * @param {string} repoPath
- * @param {string} remote
- * @param {string} branch
- * @param {string} sha
- */
-async function pushSubmoduleBranch(repoPath, remote, branch, sha) {
-  const fetch = await runCommand("git", ["-C", repoPath, "fetch", remote, "--prune"], { cwd: repoPath });
-  if (fetch.code !== 0) {
-    throw new UserError("Failed to fetch submodule remote before push.", {
-      details: `repo: ${repoPath}\nremote: ${remote}\n\n${fetch.stderr || fetch.stdout}`,
-    });
-  }
-
-  const remoteRef = `refs/remotes/${remote}/${branch}`;
-  const hasRemoteBranch = await runCommand("git", ["-C", repoPath, "show-ref", "--verify", "--quiet", remoteRef], { cwd: repoPath }).then((r) => r.code === 0);
-  if (!hasRemoteBranch) {
-    throw new UserError("Submodule target branch does not exist on remote.", {
-      details: `repo: ${repoPath}\nremote: ${remote}\nbranch: ${branch}`,
-    });
-  }
-
-  const remoteAncestor = await runCommand("git", ["-C", repoPath, "merge-base", "--is-ancestor", remoteRef, sha], { cwd: repoPath }).then((r) => r.code === 0);
-  if (remoteAncestor) {
-    const push = await runCommand("git", ["-C", repoPath, "push", remote, `${sha}:refs/heads/${branch}`], { cwd: repoPath });
-    if (push.code !== 0) {
-      throw new UserError("Failed to fast-forward push submodule target branch.", {
-        details: `repo: ${repoPath}\nremote: ${remote}\nbranch: ${branch}\ncommit: ${sha}\n\n${push.stderr || push.stdout}`,
-      });
-    }
-    return { status: "pushed", remoteRef };
-  }
-
-  const shaContained = await runCommand("git", ["-C", repoPath, "merge-base", "--is-ancestor", sha, remoteRef], { cwd: repoPath }).then((r) => r.code === 0);
-  if (shaContained) {
-    return { status: "already-contained", remoteRef };
-  }
-
-  throw new UserError("Submodule target branch diverged from gitlink commit.", {
-    details: `repo: ${repoPath}\nremote: ${remote}\nbranch: ${branch}\ncommit: ${sha}\n\nHint: reconcile the submodule branch manually, then retry.`,
-  });
-}
-
-/**
- * @param {string} gitRoot
- * @param {string} changeId
- * @param {string} baseBranch
- * @param {string | undefined} changeWorktreePath
- */
-async function pushSubmodulesForFinish(gitRoot, changeId, baseBranch, changeWorktreePath) {
-  const subs = await listSubmodulesFromGitmodules(gitRoot);
-  if (subs.length === 0) return { processed: 0 };
-
-  const targetsPath = path.join(gitRoot, "changes", changeId, "submodules.targets");
-  if (!(await pathExists(targetsPath))) {
-    throw new UserError("Missing submodules.targets for submodule-aware finish.", {
-      details: `required: ${path.relative(gitRoot, targetsPath)}\n\nHint: add one entry per submodule path before running \`aiws change finish --push\`.`,
-    });
-  }
-
-  const parsedTargets = await parseSubmoduleTargetsFile(targetsPath);
-  if (parsedTargets.errors.length > 0) {
-    throw new UserError("Invalid submodules.targets.", { details: parsedTargets.errors.join("\n") });
-  }
-
-  const missingPaths = subs.filter((s) => !parsedTargets.parsed.has(s.path)).map((s) => s.path);
-  if (missingPaths.length > 0) {
-    throw new UserError("submodules.targets missing declared submodule paths.", {
-      details: `file: ${path.relative(gitRoot, targetsPath)}\nmissing: ${missingPaths.join(", ")}`,
-    });
-  }
-
-  /** @type {Array<{ name: string, path: string, sha: string, branch: string, remote: string, pinBranch: string }>} */
-  const specs = [];
-  for (const sub of subs) {
-    const target = parsedTargets.parsed.get(sub.path);
-    if (!target) continue;
-    const targetBranch = target.branch === "." ? baseBranch : target.branch;
-    const gitlink = await runCommand("git", ["rev-parse", `HEAD:${sub.path}`], { cwd: gitRoot });
-    if (gitlink.code !== 0) {
-      throw new UserError("Failed to resolve submodule gitlink commit from merged superproject.", {
-        details: `path: ${sub.path}\n\n${gitlink.stderr || gitlink.stdout}`,
-      });
-    }
-    const sha = String(gitlink.stdout || "").trim();
-    specs.push({
-      name: sub.name,
-      path: sub.path,
-      sha,
-      branch: targetBranch,
-      remote: target.remote,
-      pinBranch: `aiws/pin/${targetBranch}`,
-    });
-  }
-
-  for (const spec of specs) {
-    const targetRepoPath = path.join(gitRoot, spec.path);
-    const changeRepoPath = changeWorktreePath ? path.join(changeWorktreePath, spec.path) : "";
-    const targetRepoReady = await isGitRepository(targetRepoPath);
-    const changeRepoReady = changeRepoPath ? await isGitRepository(changeRepoPath) : false;
-    if (!targetRepoReady && !changeRepoReady) {
-      throw new UserError("Submodule repository is not initialized in either target or change worktree.", {
-        details: `path: ${spec.path}\nHint: initialize submodules before finish, or keep using worktree mode for changes involving submodules.`,
-      });
-    }
-
-    const sourceRepoPath = (targetRepoReady && (await gitHasRevision(targetRepoPath, spec.sha))) ? targetRepoPath : changeRepoReady ? changeRepoPath : targetRepoPath;
-    if (!(await gitHasRevision(sourceRepoPath, spec.sha))) {
-      throw new UserError("Merged submodule gitlink commit is not available locally.", {
-        details: `path: ${spec.path}\ncommit: ${spec.sha}\nsource_repo: ${sourceRepoPath}`,
-      });
-    }
-
-    const pushResult = await pushSubmoduleBranch(sourceRepoPath, spec.remote, spec.branch, spec.sha);
-    console.log(
-      `submodule push: ${spec.path} (${spec.remote} ${spec.branch}${pushResult.status === "pushed" ? ` <= ${spec.sha}` : ", already contained"})`,
-    );
-  }
-
-  const sync = await runCommand("git", ["submodule", "update", "--init", "--recursive"], { cwd: gitRoot });
-  if (sync.code !== 0) {
-    throw new UserError("Submodule push succeeded, but failed to sync target worktree submodules.", {
-      details: sync.stderr || sync.stdout,
-    });
-  }
-
-  for (const spec of specs) {
-    const targetRepoPath = path.join(gitRoot, spec.path);
-    if (!(await isGitRepository(targetRepoPath))) {
-      throw new UserError("Submodule repo missing after sync.", { details: `path: ${spec.path}` });
-    }
-    await ensureRevisionAvailable(targetRepoPath, spec.sha, changeWorktreePath ? path.join(changeWorktreePath, spec.path) : "");
-    const fetch = await runCommand("git", ["-C", targetRepoPath, "fetch", spec.remote, "--prune"], { cwd: targetRepoPath });
-    if (fetch.code !== 0) {
-      throw new UserError("Failed to refresh target worktree submodule remote.", {
-        details: `path: ${spec.path}\nremote: ${spec.remote}\n\n${fetch.stderr || fetch.stdout}`,
-      });
-    }
-    const checkout = await runCommand("git", ["-C", targetRepoPath, "checkout", "-B", spec.pinBranch, spec.sha], { cwd: targetRepoPath });
-    if (checkout.code !== 0) {
-      throw new UserError("Failed to attach target worktree submodule to pin branch.", {
-        details: `path: ${spec.path}\npin_branch: ${spec.pinBranch}\ncommit: ${spec.sha}\n\n${checkout.stderr || checkout.stdout}`,
-      });
-    }
-    await runCommand("git", ["-C", targetRepoPath, "branch", "--set-upstream-to", `${spec.remote}/${spec.branch}`, spec.pinBranch], { cwd: targetRepoPath });
-  }
-
-  return { processed: specs.length };
-}
-
-/**
- * @param {string} gitRoot
- * @param {{ changeId?: string, into?: string, base?: string }} options
- */
-async function resolveFinishContext(gitRoot, options) {
-  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "finish" });
-  assertValidChangeId(changeId);
-
-  const changeBranch = `change/${changeId}`;
-  const changeBranchRef = `refs/heads/${changeBranch}`;
-
-  const hasChangeBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", changeBranchRef], { cwd: gitRoot }).then((r) => r.code === 0);
-  if (!hasChangeBranch) {
-    throw new UserError(`Missing change branch: ${changeBranch}`, {
-      details: "Hint: create it with `aiws change start <change-id>` (or `git switch -c change/<id>`).",
-    });
-  }
-
-  const clean = await checkGitClean(gitRoot);
-  if (!clean.clean) {
-    throw new UserError("Refusing to finish with a dirty working tree.", {
-      details: `${clean.details}\n\nHint: commit or stash your changes, then retry.`,
-    });
-  }
-
-  const cur = await currentBranch(gitRoot);
-  const intoRaw = String(options.into || "").trim();
-  const baseRaw = String(options.base || "").trim();
-  if (intoRaw && baseRaw && intoRaw !== baseRaw) {
-    throw new UserError("change finish: cannot combine --into with --base (values differ).", { details: `--into=${intoRaw}\n--base=${baseRaw}` });
-  }
-
-  /** @type {string} */
-  let into = intoRaw || baseRaw;
-
-  if (!into) {
-    if (!cur) {
-      throw new UserError("Detached HEAD: cannot infer target branch for finish.", {
-        details: "Hint: switch to the target branch (e.g. main) and retry, or pass `aiws change finish <id> --into <branch>`.",
-      });
-    }
-    if (cur !== changeBranch) {
-      into = cur;
-    } else {
-      const metaPath = path.join(gitRoot, "changes", changeId, ".ws-change.json");
-      /** @type {any} */
-      let meta = null;
-      if (await pathExists(metaPath)) {
-        try {
-          meta = JSON.parse(await readText(metaPath));
-        } catch {
-          meta = null;
-        }
-      }
-      if (!meta) {
-        const show = await runCommand("git", ["show", `${changeBranch}:changes/${changeId}/.ws-change.json`], { cwd: gitRoot });
-        if (show.code === 0) {
-          try {
-            meta = JSON.parse(String(show.stdout || ""));
-          } catch {
-            meta = null;
-          }
-        }
-      }
-      const inferred = meta && typeof meta === "object" ? String(meta.base_branch || "").trim() : "";
-      if (!inferred) {
-        throw new UserError("Cannot infer base branch for finish.", {
-          details: "Hint: run from the target branch (e.g. main), or pass: `aiws change finish <id> --into <branch>`.",
-        });
-      }
-      into = inferred;
-    }
-  }
-
-  if (into === changeBranch) {
-    throw new UserError("change finish: target branch cannot be the change branch.", { details: `target=${into}` });
-  }
-
-  const worktrees = await listGitWorktrees(gitRoot);
-  const intoRef = `refs/heads/${into}`;
-  const intoWt = worktrees.find((w) => String(w.branch || "") === intoRef);
-  if (intoWt && path.resolve(intoWt.worktree) !== path.resolve(gitRoot)) {
-    throw new UserError("Target branch is checked out in another worktree.", {
-      details: `branch: ${into}\nworktree: ${intoWt.worktree}\n\nHint: run finish in that worktree:\n  cd ${intoWt.worktree}\n  aiws change finish ${changeId}`,
-    });
-  }
-
-  const hasIntoBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", intoRef], { cwd: gitRoot }).then((r) => r.code === 0);
-  if (!hasIntoBranch) {
-    throw new UserError("Target branch does not exist.", { details: `branch: ${into}` });
-  }
-
-  const changeWt = worktrees.find((w) => String(w.branch || "") === changeBranchRef);
-  return { changeId, changeBranch, changeBranchRef, into, cur, worktrees, changeWt };
-}
-
-/**
- * @param {string} gitRoot
- * @param {string | undefined} worktreeDir
- * @param {string} changeId
- */
-function resolveDefaultWorktreeDir(gitRoot, worktreeDir, changeId) {
-  const parent = path.dirname(gitRoot);
-  const raw = String(worktreeDir || "").trim();
-  if (raw) {
-    return path.isAbsolute(raw) ? raw : path.resolve(parent, raw);
-  }
-  const repoName = path.basename(gitRoot);
-  return path.resolve(parent, `${repoName}-${changeId}`);
-}
-
 /**
  * @param {string} branch
  * @returns {string}
@@ -760,13 +308,6 @@ function splitDeclaredValues(s) {
     .filter(Boolean);
 }
 
-/**
- * @param {string} p
- */
-function normalizeSlashes(p) {
-  return String(p || "").replaceAll("\\", "/");
-}
-
 /**
  * Extract bullet lines under a markdown "## ..." heading.
  *
@@ -809,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
@@ -819,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
   }
@@ -917,6 +473,7 @@ async function generateHandoffContent(gitRoot, changeDir, changeId) {
   let baseBranch = "main";
   /** @type {string[]} */
   const decisions = [];
+  const collaboration = await collectCollaborationArtifacts(gitRoot, changeDir);
 
   if (await pathExists(proposalPath)) {
     const text = await readText(proposalPath);
@@ -1008,6 +565,21 @@ async function generateHandoffContent(gitRoot, changeDir, changeId) {
     lines.push("- (missing) add decisions to changes/<id>/design.md#Decisions");
   }
 
+  lines.push("");
+  lines.push("## 协同记录");
+  lines.push("");
+  if ((collaboration.counts.total || 0) === 0) {
+    lines.push("- (none)");
+  } else {
+    for (const key of ["analysis", "patches", "review", "evidence"]) {
+      const group = collaboration.dirs[key];
+      if (!group) continue;
+      lines.push(`- ${group.label}: ${group.count} file(s)`);
+      for (const rel of group.files) lines.push(`  - ${rel}`);
+      if (group.truncated) lines.push("  - ...(truncated)");
+    }
+  }
+
   lines.push("");
   lines.push("## 下一步建议");
   lines.push("");
@@ -1031,174 +603,44 @@ async function generateHandoffContent(gitRoot, changeDir, changeId) {
 }
 
 /**
- * Evidence_Path is user-declared; we treat it as best-effort hints, not hard gates.
- *
- * @param {string} gitRoot
- * @param {string} changeId
- * @param {string[]} evidencePaths
- * @returns {Promise<{
- *   entries: Array<{rel: string, abs: string, exists: boolean, kind: string, isAbsolute: boolean}>,
- *   counts: { total: number, exists: number, missing: number, tmp: number, persistent: number, other: number, absolute: number },
- *   missing: string[]
- * }>}
- */
-async function analyzeEvidencePaths(gitRoot, changeId, evidencePaths) {
-  const changePrefix = `changes/${changeId}/`;
-  const evidencePrefix = `changes/${changeId}/evidence/`;
-  const reviewPrefix = `changes/${changeId}/review/`;
-
-  const entries = await Promise.all(
-    (evidencePaths || []).map(async (raw) => {
-      const rel = String(raw || "").trim();
-      const isAbsolute = path.isAbsolute(rel);
-      const abs = isAbsolute ? rel : path.join(gitRoot, rel);
-      const exists = rel ? await pathExists(abs) : false;
-
-      const relNorm = normalizeSlashes(rel);
-      let kind = "other";
-      if (relNorm.startsWith(".agentdocs/tmp/") || relNorm.startsWith(".agentdocs/")) kind = "tmp";
-      else if (relNorm.startsWith(evidencePrefix) || relNorm.startsWith(reviewPrefix) || relNorm.startsWith(changePrefix)) kind = "persistent";
-
-      return { rel, abs: path.resolve(abs), exists, kind, isAbsolute };
-    }),
-  );
-
-  const missing = entries.filter((e) => e.rel && !e.exists).map((e) => e.rel);
-  const counts = {
-    total: entries.filter((e) => e.rel).length,
-    exists: entries.filter((e) => e.rel && e.exists).length,
-    missing: missing.length,
-    tmp: entries.filter((e) => e.rel && e.kind === "tmp").length,
-    persistent: entries.filter((e) => e.rel && e.kind === "persistent").length,
-    other: entries.filter((e) => e.rel && e.kind === "other").length,
-    absolute: entries.filter((e) => e.rel && e.isAbsolute).length,
-  };
-
-  return { entries: entries.filter((e) => e.rel), counts, missing };
-}
-
-/**
- * @param {string[]} a
- * @param {string[]} b
- */
-function mergeDeclaredValues(a, b) {
-  const seen = new Set();
-  /** @type {string[]} */
-  const out = [];
-  for (const raw of [...(a || []), ...(b || [])]) {
-    const v = String(raw || "").trim().replace(/^`+/, "").replace(/`+$/, "").trim();
-    if (!v) continue;
-    if (seen.has(v)) continue;
-    seen.add(v);
-    out.push(v);
-  }
-  return out;
-}
-
-/**
- * @param {string[]} values
+ * @param {string[]} blockersStrict
+ * @param {{ unchecked: number }} tasks
  */
-function formatDeclaredValues(values) {
-  return (values || []).join(", ");
+function inferChangePhase(blockersStrict, tasks) {
+  if ((blockersStrict || []).length > 0) return "planning";
+  if ((tasks?.unchecked || 0) > 0) return "dev";
+  return "deliver";
 }
 
 /**
- * Replace or insert a simple "ID: value" style line in Markdown.
+ * Compute change status as JSON-friendly object (used by dashboard and CLI).
  *
- * @param {string} text
- * @param {string[]} labelCandidates
- * @param {string} value
- * @param {{ insertAfterLabels?: string[] }} options
+ * @param {string} gitRoot
+ * @param {string} changeId
  */
-function upsertIdLine(text, labelCandidates, value, options) {
-  const src = String(text || "");
-  const labels = Array.isArray(labelCandidates) ? labelCandidates : [];
-  for (const label of labels) {
-    const re = new RegExp(`^(.*${escapeRegExp(label)}.*?[:=][ \\t]*)(.*)$`, "m");
-    const m = re.exec(src);
-    if (!m) continue;
-    const prefix = m[1] || "";
-    const replaced = src.replace(re, `${prefix}${value}`);
-    return { ok: true, changed: replaced !== src, text: replaced, mode: "replaced", label };
-  }
-
-  // Insert near the top (best-effort), after a nearby label if present.
-  const insertAfter = Array.isArray(options?.insertAfterLabels) ? options.insertAfterLabels : [];
-  const lines = src.split(/\r?\n/);
-  let idx = 0;
-  for (let i = 0; i < Math.min(lines.length, 80); i++) {
-    const line = lines[i] || "";
-    if (insertAfter.some((l) => line.includes(l))) idx = i + 1;
-  }
-  const insertedLabel = labels[0] || "Evidence_Path";
-  const newLine = `- ${insertedLabel}: ${value}`;
-  lines.splice(idx, 0, newLine);
-  const inserted = lines.join("\n");
-  return { ok: true, changed: inserted !== src, text: inserted, mode: "inserted", label: labels[0] || "" };
-}
-
-/**
- * Special-case insertion for proposal.md template style.
- *
- * @param {string} proposalText
- * @param {string} value
- */
-function upsertProposalEvidencePath(proposalText, value) {
-  const src = String(proposalText || "");
-  const re = new RegExp(`^(.*${escapeRegExp("Evidence_Path")}.*?[:=][ \\t]*)(.*)$`, "m");
-  if (re.test(src)) {
-    const m = re.exec(src);
-    const prefix = m?.[1] || "";
-    const out = src.replace(re, `${prefix}${value}`);
-    return { changed: out !== src, text: out, mode: "replaced" };
-  }
-  // Insert right after Plan_File binding if possible.
-  const lines = src.split(/\r?\n/);
-  let idx = 0;
-  for (let i = 0; i < Math.min(lines.length, 120); i++) {
-    if ((lines[i] || "").includes("Plan_File")) {
-      idx = i + 1;
-      break;
-    }
-  }
-  lines.splice(idx, 0, `- \`Evidence_Path\` = ${value}`);
-  const inserted = lines.join("\n");
-  return { changed: inserted !== src, text: inserted, mode: "inserted" };
-}
-
-/**
- * @param {string} changeId
- */
-function planVerifyHint(changeId) {
-  return `执行前质量门（优先）：\`aiws change validate ${changeId} --strict\`（AI 工具中等价于 \`$ws-plan-verify\`）`;
-}
-
-/**
- * @param {string[]} blockersStrict
- * @param {{ unchecked: number }} tasks
- */
-function inferChangePhase(blockersStrict, tasks) {
-  if ((blockersStrict || []).length > 0) return "planning";
-  if ((tasks?.unchecked || 0) > 0) return "dev";
-  return "deliver";
-}
-
-/**
- * Compute change status as JSON-friendly object (used by dashboard and CLI).
- *
- * @param {string} gitRoot
- * @param {string} changeId
- */
-export async function computeChangeStatus(gitRoot, changeId) {
-  assertValidChangeId(changeId);
-  await ensureTruthFiles(gitRoot);
+export async function computeChangeStatus(gitRoot, changeId) {
+  assertValidChangeId(changeId);
+  await ensureTruthFiles(gitRoot);
 
   const changeDir = changeDirAbs(gitRoot, changeId);
   if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
+  const context = await resolveChangeStatusContext(gitRoot, changeId, {
+    currentBranch,
+    listGitWorktrees,
+    pathExists,
+    isGitRepository: (repoPath) => isGitRepository(repoPath, { pathExists, runCommand }),
+    inferChangeIdFromBranch,
+  });
 
   const proposal = await fileState(changeDir, "proposal.md");
   const tasks = await fileState(changeDir, "tasks.md");
   const design = await fileState(changeDir, "design.md");
+  const collaboration = await collectCollaborationArtifacts(gitRoot, changeDir);
+  const reviewSignals = await collectReviewSignals(gitRoot, changeId, context, collaboration);
+  const reviewGates = await collectReviewGates(gitRoot, changeId, context);
+  const git = await collectGitStatus(context.worktree);
+  const submodules = await listSubmodulesFromGitmodules(gitRoot, { pathExists, runCommand });
+  const metrics = await readChangeMetrics(changeDir, { pathExists, readText });
 
   const metaPath = path.join(changeDir, ".ws-change.json");
   let metaState = "missing";
@@ -1279,12 +721,15 @@ export async function computeChangeStatus(gitRoot, changeId) {
   blockersArchive.push(...blockersStrict);
   if (taskProgress.unchecked > 0) blockersArchive.push(`tasks.md still has unchecked tasks (${taskProgress.unchecked} items)`);
   const phase = inferChangePhase(blockersStrict, taskProgress);
+  const lifecycle = summarizeLifecycleSignals(metrics);
+  const scopeGate = computeScopeGate(lifecycle);
 
-  return {
+  const baseStatus = {
     ok: true,
     changeId,
     dir: path.relative(gitRoot, changeDir),
     phase,
+    context,
     metaState,
     reqId,
     probId,
@@ -1293,7 +738,16 @@ export async function computeChangeStatus(gitRoot, changeId) {
       planFile,
       evidencePaths,
     },
+    scopeGate,
     evidence,
+    collaboration,
+    reviewSignals,
+    reviewGates,
+    git,
+    repo: {
+      submodules: submodules.length,
+    },
+    lifecycle,
     tasks: taskProgress,
     baselineLabel,
     baselineAt,
@@ -1302,57 +756,17 @@ export async function computeChangeStatus(gitRoot, changeId) {
     blockersArchive,
     hints: {
       planVerify: planVerifyHint(changeId),
-      dev: "质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`",
+      dev: "质量门通过后再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`",
     },
   };
-}
-
-function parseChangeCheckerOutput(stdout, stderr) {
-  const text = [String(stdout || ""), String(stderr || "")].filter(Boolean).join("\n");
-  /** @type {string[]} */
-  const errors = [];
-  /** @type {string[]} */
-  const warnings = [];
-  for (const raw of text.split("\n")) {
-    const line = raw.trim();
-    if (!line) continue;
-    if (line.startsWith("error: ")) errors.push(line.replace(/^error:\s*/, ""));
-    else if (line.startsWith("warn: ")) warnings.push(line.replace(/^warn:\s*/, ""));
-  }
-  return { errors, warnings, raw: text.trim() };
-}
-
-function classifyCheckMessage(msg) {
-  const s = String(msg || "");
-  if (s.includes("truth file") || s.includes("truth drift") || s.includes("allow-truth-drift")) return "truth_drift";
-  if (s.includes("WS:TODO") || s.includes("unrendered template placeholders")) return "placeholders";
-  if (s.includes("missing:") || s.includes("empty:") || s.includes("Missing change dir")) return "missing_files";
-  if (s.includes("Change_ID") || s.includes("Req_ID") || s.includes("Problem_ID") || s.includes("Contract_Row") || s.includes("Plan_File") || s.includes("Evidence_Path")) return "bindings";
-  if (s.includes("missing required sections") || s.includes("has empty sections") || s.includes("Plan section") || s.includes("Verify section") || s.includes("scope is too broad") || s.includes("too abstract")) {
-    return "plan_quality";
-  }
-  return "other";
-}
-
-function groupCheckMessages(errors, warnings) {
-  const groups = {
-    truth_drift: { errors: [], warnings: [] },
-    missing_files: { errors: [], warnings: [] },
-    placeholders: { errors: [], warnings: [] },
-    bindings: { errors: [], warnings: [] },
-    plan_quality: { errors: [], warnings: [] },
-    other: { errors: [], warnings: [] },
+  const governance = await inferChangeGovernance(baseStatus);
+  return {
+    ...baseStatus,
+    governance: {
+      ...governance,
+      warning: context.warning || "",
+    },
   };
-
-  for (const m of errors || []) {
-    const k = classifyCheckMessage(m);
-    groups[k].errors.push(m);
-  }
-  for (const m of warnings || []) {
-    const k = classifyCheckMessage(m);
-    groups[k].warnings.push(m);
-  }
-  return groups;
 }
 
 /**
@@ -1363,29 +777,14 @@ function groupCheckMessages(errors, warnings) {
  * @param {{ strict: boolean, allowTruthDrift: boolean, checkEvidence?: boolean, checkScope?: boolean }} options
  */
 export async function validateChangeArtifacts(gitRoot, changeId, options) {
-  assertValidChangeId(changeId);
-  await ensureTruthFiles(gitRoot);
-
-  const checker = await resolveWsChangeChecker(gitRoot);
-  const args = [...checker.args, "--workspace-root", gitRoot, "--change-id", changeId];
-  if (options.strict) args.push("--strict");
-  if (options.allowTruthDrift) args.push("--allow-truth-drift");
-  if (options.checkEvidence) args.push("--check-evidence");
-  if (options.checkScope) args.push("--check-scope");
-
-  const res = await runPython(gitRoot, ["-u", ...args]);
-  const parsed = parseChangeCheckerOutput(res.stdout, res.stderr);
-  return {
-    ok: res.code === 0,
-    changeId,
-    strict: options.strict === true,
-    allowTruthDrift: options.allowTruthDrift === true,
-    exitCode: res.code,
-    errors: parsed.errors,
-    warnings: parsed.warnings,
-    groups: groupCheckMessages(parsed.errors, parsed.warnings),
-    raw: parsed.raw,
-  };
+  return validateChangeArtifactsModel(gitRoot, changeId, options, {
+    assertValidChangeId,
+    collectFinishGateErrors,
+    computeChangeStatus,
+    ensureTruthFiles,
+    resolveWsChangeChecker,
+    runPython,
+  });
 }
 
 /**
@@ -1433,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;
@@ -1455,37 +853,9 @@ async function appendMetricsEvent(gitRoot, changeId, type, payload) {
   await writeText(metricsAbs, JSON.stringify(cur, null, 2) + "\n");
 }
 
-/**
- * @param {string} absDir
- * @param {(name: string) => boolean} predicate
- */
-async function findLatestFileByMtime(absDir, predicate) {
-  if (!(await pathExists(absDir))) return "";
-  const entries = await fs.readdir(absDir, { withFileTypes: true });
-  /** @type {{ abs: string, mtimeMs: number } | null} */
-  let best = null;
-  for (const e of entries) {
-    if (!e.isFile()) continue;
-    if (!predicate(e.name)) continue;
-    const abs = path.join(absDir, e.name);
-    let st;
-    try {
-      st = await fs.stat(abs);
-    } catch {
-      continue;
-    }
-    const mtimeMs = Number(st.mtimeMs || 0);
-    if (!best || mtimeMs > best.mtimeMs) best = { abs, mtimeMs };
-  }
-  return best ? best.abs : "";
-}
-
-/**
- * @param {string} gitRoot
- * @param {string} absPath
- */
-function relFromRoot(gitRoot, absPath) {
-  return normalizeSlashes(path.relative(gitRoot, absPath));
+async function appendMetricsEvent(gitRoot, changeId, type, payload) {
+  const changeDir = changeDirAbs(gitRoot, changeId);
+  await appendMetricsEventAtDir(changeDir, changeId, type, payload);
 }
 
 /**
@@ -1581,46 +951,6 @@ async function resolveChangeId(gitRoot, changeId, options) {
   throw new UserError(`usage: aiws change ${options.command} <change-id> (or switch to branch change/<change-id>)`);
 }
 
-/**
- * @param {any} meta
- */
-function baselineFromMeta(meta) {
-  const createdTruth = meta?.base_truth_files && typeof meta.base_truth_files === "object" ? meta.base_truth_files : {};
-  const syncedTruth = meta?.synced_truth_files && typeof meta.synced_truth_files === "object" ? meta.synced_truth_files : {};
-  if (Object.keys(syncedTruth).length > 0) {
-    return { baseline: syncedTruth, label: "last sync", at: String(meta?.synced_at || "") };
-  }
-  return { baseline: createdTruth, label: "creation", at: String(meta?.created_at || "") };
-}
-
-/**
- * @param {Record<string, string | null>} curTruth
- * @param {any} baseline
- * @returns {{ baselineLabel: string, baselineAt: string, driftFiles: string[] }}
- */
-function truthDrift(curTruth, baseline) {
-  /** @type {string[]} */
-  const driftFiles = [];
-
-  const createdTruth = baseline?.base_truth_files && typeof baseline.base_truth_files === "object" ? baseline.base_truth_files : {};
-  const syncedTruth = baseline?.synced_truth_files && typeof baseline.synced_truth_files === "object" ? baseline.synced_truth_files : {};
-  const effective = Object.keys(syncedTruth).length > 0 ? syncedTruth : createdTruth;
-  const baselineLabel = Object.keys(syncedTruth).length > 0 ? "sync" : "creation";
-  const baselineAt = Object.keys(syncedTruth).length > 0 ? String(baseline?.synced_at || "") : String(baseline?.created_at || "");
-
-  for (const [rel, info] of Object.entries(effective || {})) {
-    const baseSha = info && typeof info === "object" ? String(info.sha256 || "") : "";
-    const curSha = curTruth[rel] ?? null;
-    if (curSha == null) {
-      driftFiles.push(rel);
-      continue;
-    }
-    if (baseSha && curSha !== baseSha) driftFiles.push(rel);
-  }
-
-  return { baselineLabel, baselineAt, driftFiles };
-}
-
 /**
  * @param {string} gitRoot
  * @param {string} changeId
@@ -1796,6 +1126,10 @@ async function changeNewAtGitRoot(gitRoot, options) {
   const changeDir = path.join(changeRoot, changeId);
   if (await pathExists(changeDir)) throw new UserError(`Change already exists: ${changeDir}`);
   await ensureDir(changeDir);
+  await ensureDir(path.join(changeDir, "analysis"));
+  await ensureDir(path.join(changeDir, "patches"));
+  await ensureDir(path.join(changeDir, "review"));
+  await ensureDir(path.join(changeDir, "evidence"));
 
   const templates = await resolveChangeTemplatesDir(gitRoot);
   const proposalTpl = await readText(path.join(templates.templateDir, "proposal.md"));
@@ -1841,6 +1175,9 @@ async function changeNewAtGitRoot(gitRoot, options) {
   console.log(`  - edit: changes/${changeId}/proposal.md`);
   console.log(`  - edit: changes/${changeId}/tasks.md`);
   if (!options.noDesign) console.log(`  - optional: changes/${changeId}/design.md`);
+  console.log(`  - optional: changes/${changeId}/analysis/ (委托分析)`);
+  console.log(`  - optional: changes/${changeId}/patches/ (patch 草案)`);
+  console.log(`  - optional: changes/${changeId}/review/ (多审查结果)`);
   console.log(`  - validate: aiws change validate ${changeId}`);
 }
 
@@ -1888,7 +1225,7 @@ export async function changeStartCommand(options) {
   let effectiveWorktree = options.worktree === true;
 
   if (hasGitmodules && !effectiveNoSwitch && !effectiveWorktree && !effectiveForceSwitch) {
-    const prereq = await checkWorktreePrereqs(gitRoot);
+    const prereq = await checkWorktreePrereqs(gitRoot, { hasHeadCommit, runCommand });
     if (prereq.ok) {
       effectiveWorktree = true;
       console.error("warn: .gitmodules detected (git submodules). defaulting to --worktree to avoid switching the superproject branch.");
@@ -1928,7 +1265,7 @@ export async function changeStartCommand(options) {
   }
 
   if (effectiveWorktree) {
-    const prereq = await checkWorktreePrereqs(gitRoot);
+    const prereq = await checkWorktreePrereqs(gitRoot, { hasHeadCommit, runCommand });
     if (!prereq.ok) {
       if (prereq.reason === "no_commit") {
         throw new UserError("change start --worktree requires a repo with at least one commit.", { details: "Hint: make an initial commit, then retry." });
@@ -2001,7 +1338,7 @@ export async function changeStartCommand(options) {
         baseBranch: startFromBranch && startFromBranch !== branch ? startFromBranch : undefined,
       });
     } else {
-      await maybeRecordBaseBranch(changeDir, startFromBranch, branch);
+      await maybeRecordBaseBranch(changeDir, startFromBranch, branch, { nowIsoUtc, pathExists, readText, writeText });
     }
 
     // Worktree mode: if this repo declares submodules, always initialize them in the new worktree.
@@ -2064,48 +1401,9 @@ export async function changeStartCommand(options) {
   let branchReady = hasBranch;
 
   if (effectiveNoSwitch) {
-    if (!hasBranch) {
-      if (!headReady) {
-        // On an unborn branch, `git branch <name>` fails because HEAD doesn't point to a commit yet.
-        // We still allow initializing change artifacts without switching branches.
-        console.error(`warn: repo has no commits; cannot create branch "${branch}" without switching (skipped)`);
-        branchReady = false;
-      } else {
-        const br = await runCommand("git", ["branch", branch], { cwd: gitRoot });
-        if (br.code !== 0) throw new UserError("Failed to create branch.", { details: br.stderr || br.stdout });
-        branchReady = true;
-      }
-    }
+    branchReady = await prepareNoSwitchBranch(gitRoot, { branch, hasBranch, headReady }, { runCommand, UserError });
   } else {
-    if (hasBranch) {
-      let sw = await runCommand("git", ["switch", ...(hasGitmodules ? ["--recurse-submodules"] : []), branch], { cwd: gitRoot });
-      if (sw.code !== 0 && hasGitmodules && outputMentionsRecurseSubmodules(sw)) {
-        console.error("warn: git switch does not support --recurse-submodules; switching without it (submodules may be out of sync).");
-        sw = await runCommand("git", ["switch", branch], { cwd: gitRoot });
-      }
-      if (sw.code !== 0) {
-        let co = await runCommand("git", ["checkout", ...(hasGitmodules ? ["--recurse-submodules"] : []), branch], { cwd: gitRoot });
-        if (co.code !== 0 && 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 runCommand("git", ["checkout", branch], { cwd: gitRoot });
-        }
-        if (co.code !== 0) throw new UserError("Failed to switch branch.", { details: co.stderr || co.stdout });
-      }
-    } else {
-      let sw = await runCommand("git", ["switch", ...(hasGitmodules ? ["--recurse-submodules"] : []), "-c", branch], { cwd: gitRoot });
-      if (sw.code !== 0 && hasGitmodules && outputMentionsRecurseSubmodules(sw)) {
-        console.error("warn: git switch does not support --recurse-submodules; switching without it (submodules may be out of sync).");
-        sw = await runCommand("git", ["switch", "-c", branch], { cwd: gitRoot });
-      }
-      if (sw.code !== 0) {
-        let co = await runCommand("git", ["checkout", ...(hasGitmodules ? ["--recurse-submodules"] : []), "-b", branch], { cwd: gitRoot });
-        if (co.code !== 0 && 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 runCommand("git", ["checkout", "-b", branch], { cwd: gitRoot });
-        }
-        if (co.code !== 0) throw new UserError("Failed to create branch.", { details: co.stderr || co.stdout });
-      }
-    }
+    await switchOrCreateStartBranch(gitRoot, { branch, hasBranch, hasGitmodules }, { runCommand, UserError });
     branchReady = true;
   }
 
@@ -2118,7 +1416,7 @@ export async function changeStartCommand(options) {
       baseBranch: startFromBranch && startFromBranch !== branch ? startFromBranch : undefined,
     });
   } else {
-    await maybeRecordBaseBranch(changeDir, startFromBranch, branch);
+    await maybeRecordBaseBranch(changeDir, startFromBranch, branch, { nowIsoUtc, pathExists, readText, writeText });
   }
 
   // Check Depends_On dependencies (non-worktree mode)
@@ -2172,7 +1470,73 @@ export async function changeFinishCommand(options) {
   const gitRoot = await resolveGitRoot(process.cwd());
   await ensureTruthFiles(gitRoot);
 
-  const { changeId, changeBranch, into, cur, changeWt } = await resolveFinishContext(gitRoot, 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.", {
+      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\``,
+    });
+  }
+  const { changeId, changeBranch, into, cur, changeWt } = await resolveFinishContext(gitRoot, { ...options, changeId: resolvedChangeId }, {
+    assertValidChangeId,
+    checkGitClean,
+    currentBranch,
+    listGitWorktrees,
+    pathExists,
+    readText,
+    resolveChangeId,
+    runCommand,
+    UserError,
+  });
+  const finishStatusRoot = changeWt?.worktree ? path.resolve(changeWt.worktree) : gitRoot;
+  const finishStatus = await computeChangeStatus(finishStatusRoot, changeId);
+  const finishGateErrors = collectFinishGateErrors(changeId, finishStatus.reviewGates);
+  if (finishGateErrors.length > 0) {
+    throw new UserError("Refusing to finish without complete review gates.", {
+      details:
+        `change: ${changeId}\n` +
+        "missing:\n" +
+        finishGateErrors.map((line) => `- ${line}`).join("\n") +
+        `\n\nnext:\n` +
+        `- aiws change validate ${changeId} --strict --check-evidence\n` +
+        `- aiws change evidence ${changeId}\n` +
+        `- re-run finish after all finish gates are green`,
+    });
+  }
+  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 });
@@ -2191,54 +1555,150 @@ export async function changeFinishCommand(options) {
     throw new UserError("Failed to fast-forward merge change branch into target.", { details: `${merge.stderr || merge.stdout}${extra}` });
   }
 
-  await appendMetricsEvent(gitRoot, changeId, "finish", { into, from: changeBranch });
-
-  console.log(`ok: finished change: ${changeId}`);
-  console.log(`into: ${into}`);
-  console.log(`from: ${changeBranch}`);
+  await appendMetricsEvent(gitRoot, changeId, "finish_local", finishBasePayload);
 
+  let cleanupNote = "not_requested";
+  let finishCompleted = false;
+  let archivedToRel = "";
+  let handoffRel = "";
   if (options.push === true) {
-    const submodulePush = await pushSubmodulesForFinish(gitRoot, changeId, into, changeWt?.worktree);
-    if (submodulePush.processed > 0) {
-      console.log(`submodule push: ok (${submodulePush.processed} repos)`);
-    }
+    try {
+      const submodulePush = await pushSubmodulesForFinish(gitRoot, changeId, into, changeWt?.worktree, {
+        pathExists,
+        readText,
+        runCommand,
+        UserError,
+      });
+      if (submodulePush.processed > 0) {
+        console.log(`submodule push: ok (${submodulePush.processed} repos)`);
+      }
 
-    const pushTarget = await resolvePushTarget(gitRoot, into, options.remote);
-    const push = await runCommand("git", ["push", pushTarget.remote, pushTarget.refspec], { cwd: gitRoot });
-    if (push.code !== 0) {
-      throw new UserError("Finished locally, but failed to push target branch.", {
-        details:
-          `remote: ${pushTarget.remote}\nlocal_branch: ${into}\nremote_branch: ${pushTarget.remoteBranch}\n` +
-          (pushTarget.trackedMergeRef ? `tracked_merge: ${pushTarget.trackedMergeRef}\n` : "") +
-          `\n${push.stderr || push.stdout}`,
+      const pushTarget = await resolvePushTarget(gitRoot, into, options.remote, { runCommand });
+      const push = await runCommand("git", ["push", pushTarget.remote, pushTarget.refspec], { cwd: gitRoot });
+      if (push.code !== 0) {
+        throw new UserError("Finished locally, but failed to push target branch.", {
+          details:
+            `remote: ${pushTarget.remote}\nlocal_branch: ${into}\nremote_branch: ${pushTarget.remoteBranch}\n` +
+            (pushTarget.trackedMergeRef ? `tracked_merge: ${pushTarget.trackedMergeRef}\n` : "") +
+            `\n${push.stderr || push.stdout}`,
+        });
+      }
+
+      console.log(`push: ok (${pushTarget.remote} ${into}${pushTarget.remoteBranch !== into ? ` -> ${pushTarget.remoteBranch}` : ""})`);
+
+      console.log(`push: target ${pushTarget.remote} ${into}${pushTarget.remoteBranch !== into ? ` -> ${pushTarget.remoteBranch}` : ""}`);
+
+      if (changeWt?.worktree) {
+        const cleanup = await cleanupWorktreePath(gitRoot, changeWt.worktree, {
+          checkGitClean,
+          listGitWorktrees,
+          pathExists,
+          runCommand,
+          UserError,
+        });
+        cleanupNote = cleanup.status === "skipped" ? `skipped:${cleanup.reason || "unknown"}` : cleanup.status;
+        finishCompleted =
+          cleanup.status === "removed" ||
+          cleanup.status === "pruned-missing" ||
+          (cleanup.status === "skipped" && cleanup.reason === "current_worktree");
+        if (cleanup.status === "removed") {
+          console.log(`cleanup: removed worktree ${cleanup.worktree}`);
+        } else if (cleanup.status === "pruned-missing") {
+          console.log(`cleanup: pruned stale worktree metadata for ${cleanup.worktree}`);
+        } else if (cleanup.reason === "current_worktree") {
+          console.log("cleanup: skipped (change worktree is current worktree)");
+        } else if (cleanup.reason === "locked") {
+          console.log(`cleanup: skipped locked worktree ${cleanup.worktree}`);
+        } else if (cleanup.reason === "dirty") {
+          console.log(`cleanup: skipped dirty worktree ${cleanup.worktree}`);
+        } else {
+          console.log("cleanup: skipped");
+        }
+      } else {
+        cleanupNote = "skipped:no_separate_change_worktree";
+        finishCompleted = true;
+        console.log("cleanup: skipped (no separate change worktree)");
+      }
+    } catch (error) {
+      await appendMetricsEvent(gitRoot, changeId, "finish_failed", {
+        ...finishBasePayload,
+        error: error instanceof Error ? error.message : String(error),
       });
+      throw error;
     }
+  }
 
-    console.log(`push: ok (${pushTarget.remote} ${into}${pushTarget.remoteBranch !== into ? ` -> ${pushTarget.remoteBranch}` : ""})`);
-
-    console.log(`push: target ${pushTarget.remote} ${into}${pushTarget.remoteBranch !== into ? ` -> ${pushTarget.remoteBranch}` : ""}`);
-
-    if (changeWt?.worktree) {
-      const cleanup = await cleanupWorktreePath(gitRoot, changeWt.worktree);
-      if (cleanup.status === "removed") {
-        console.log(`cleanup: removed worktree ${cleanup.worktree}`);
-      } else if (cleanup.status === "pruned-missing") {
-        console.log(`cleanup: pruned stale worktree metadata for ${cleanup.worktree}`);
-      } else if (cleanup.reason === "current_worktree") {
-        console.log("cleanup: skipped (change worktree is current worktree)");
-      } else if (cleanup.reason === "locked") {
-        console.log(`cleanup: skipped locked worktree ${cleanup.worktree}`);
-      } else if (cleanup.reason === "dirty") {
-        console.log(`cleanup: skipped dirty worktree ${cleanup.worktree}`);
-      } else {
-        console.log("cleanup: skipped");
+  if (options.push === true && !finishCompleted) {
+    const cleanupReason = cleanupNote.startsWith("skipped:") ? cleanupNote.slice("skipped:".length) : cleanupNote;
+    await appendMetricsEvent(gitRoot, changeId, "finish_cleanup_pending", {
+      ...finishBasePayload,
+      cleanup: cleanupNote,
+      reason: cleanupReason,
+    });
+    throw new UserError("Change finish incomplete: cleanup pending.", {
+      details:
+        `change: ${changeId}\n` +
+        `next: cleanup pending (${cleanupReason || "unknown"})\n` +
+        `  - resolve the change worktree state, then rerun: aiws change finish ${changeId} --push${options.remote ? ` --remote ${options.remote}` : ""}`,
+    });
+  }
+
+  if (finishCompleted) {
+    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}`,
+          });
+        }
       }
-    } else {
-      console.log("cleanup: skipped (no separate change worktree)");
     }
   }
 
-  if (options.push === true && (await listSubmodulesFromGitmodules(gitRoot)).length > 0) {
+  const outcomeLabel =
+    options.push === true ? (finishCompleted ? "finished change" : "pushed change; cleanup pending") : "finished locally";
+  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:");
     console.log("  - submodules already synced for finish --push; rerun `git submodule update --init --recursive` only if another worktree changed them later");
   }
@@ -2256,70 +1716,21 @@ export async function changeStatusCommand(options) {
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "status" });
   const st = await computeChangeStatus(gitRoot, changeId);
   const branch = await currentBranch(gitRoot);
-  /** @type {{ changeWorktree?: string, targetWorktree?: string }} */
-  const wtHint = {};
-  try {
-    const worktrees = await listGitWorktrees(gitRoot);
-    const changeRef = `refs/heads/change/${changeId}`;
-    const changeWt = worktrees.find((w) => String(w.branch || "") === changeRef);
-    if (changeWt?.worktree && path.resolve(changeWt.worktree) !== path.resolve(gitRoot)) wtHint.changeWorktree = changeWt.worktree;
-  } catch {
-    // best-effort; ignore
-  }
-
-  console.log(`✓ aiws change status: ${st.changeId}`);
-  console.log(`dir: ${st.dir}`);
-  console.log(`phase: ${st.phase}`);
-  console.log(`worktree: ${gitRoot}`);
-  console.log(`branch: ${branch || "(detached HEAD)"}`);
-  if (wtHint.changeWorktree) console.log(`note: change/<id> checked out in another worktree: ${wtHint.changeWorktree}`);
-  console.log(`meta: ${st.metaState}`);
-  if (st.reqId) console.log(`Req_ID: ${st.reqId}`);
-  if (st.probId) console.log(`Problem_ID: ${st.probId}`);
-  console.log(`tasks: ${st.tasks.done}/${st.tasks.total} (unchecked=${st.tasks.unchecked})`);
-  console.log(`baseline: ${st.baselineLabel}${st.baselineAt ? ` (at=${st.baselineAt})` : ""}`);
-  console.log(`drift: ${st.driftFiles.length > 0 ? st.driftFiles.join(", ") : "(none)"}`);
-  if (st.evidence?.counts) {
-    const c = st.evidence.counts;
-    console.log(`evidence: declared=${c.total} (exists=${c.exists}, missing=${c.missing}, persistent=${c.persistent}, tmp=${c.tmp})`);
-  }
-
-  console.log("");
-  console.log("Blockers (strict):");
-  if (st.blockersStrict.length === 0) console.log("- (none)");
-  else for (const b of st.blockersStrict) console.log(`- ${b}`);
-
-  console.log("");
-  console.log("Blockers (archive):");
-  if (st.blockersArchive.length === 0) console.log("- (none)");
-  else for (const b of st.blockersArchive) console.log(`- ${b}`);
-
-  console.log("");
-  console.log("Next (recommended):");
-  console.log(`- ${planVerifyHint(st.changeId)}`);
-  if (st.blockersStrict.length > 0) {
-    console.log("- 先修复 Blockers (strict) 后复跑质量门，再进入 `$ws-dev`");
-    if (wtHint.changeWorktree) console.log(`- 若需要写代码：先切到 change worktree 再改动：\`cd ${wtHint.changeWorktree}\``);
-    return;
-  }
-
-  if (st.tasks.unchecked > 0) {
-    console.log("- 继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）");
-    console.log("- 提交/交付前强制门禁：`aiws validate .`（可选落盘：`aiws validate . --stamp`）");
-    console.log(`- （可选）状态快照：\`aiws change state ${st.changeId} --write\``);
-    return;
-  }
-
-  // deliver-ready hints
-  if (st.evidence?.counts && st.evidence.counts.persistent === 0) {
-    console.log("- 交付前建议生成持久证据：`changes/<id>/evidence/...`（并把路径回填到 proposal.md 的 Evidence_Path）");
-  }
-  if (st.evidence?.missing && st.evidence.missing.length > 0) {
-    const show = st.evidence.missing.slice(0, 5);
-    console.log(`- 交付前建议补齐缺失证据文件（missing=${st.evidence.missing.length}）：${show.join(", ")}${st.evidence.missing.length > show.length ? ", ..." : ""}`);
-  }
-  console.log(`- （可选）状态快照：\`aiws change state ${st.changeId} --write\``);
-  console.log("- 进入交付：在 AI 工具中运行 `$ws-deliver`（submodule 感知提交 + 门禁 + 最终 `$ws-finish`）");
+  const changeWorktreeHint = await resolveChangeWorktreeHint(gitRoot, changeId, { listGitWorktrees });
+  const output = await renderChangeStatusOutput(
+    {
+      gitRoot,
+      branch,
+      changeWorktreeHint,
+      status: st,
+    },
+    {
+      effectiveReviewCount,
+      governanceGuidanceLines,
+      planVerifyHint,
+    },
+  );
+  process.stdout.write(output);
 }
 
 /**
@@ -2333,216 +1744,46 @@ export async function changeNextCommand(options) {
 
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "next" });
   assertValidChangeId(changeId);
-  const branch = await currentBranch(gitRoot);
+  const st = await computeChangeStatus(gitRoot, changeId);
 
   const changeDir = changeDirAbs(gitRoot, changeId);
   if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
-
-  const proposal = await fileState(changeDir, "proposal.md");
-  const tasks = await fileState(changeDir, "tasks.md");
-  const design = await fileState(changeDir, "design.md");
-
-  const metaPath = path.join(changeDir, ".ws-change.json");
-  /** @type {any} */
-  let meta = null;
-  if (await pathExists(metaPath)) {
-    try {
-      meta = JSON.parse(await readText(metaPath));
-    } catch {
-      meta = null;
-    }
-  }
-
-  const curTruth = await snapshotTruthShaOnly(gitRoot);
-  const drift = meta ? truthDrift(curTruth, meta).driftFiles : [];
-
-  /** @type {string[]} */
-  const actions = [];
-
-  const inferred = inferChangeIdFromBranch(branch);
-  if (!branch) {
-    actions.push("当前为 detached HEAD：建议切到 `change/<change-id>` 分支后再继续（或显式传入 `<change-id>`）");
-  } else if (inferred && inferred !== changeId) {
-    actions.push(`当前分支为 \`${branch}\`（推断 change=${inferred}），但你在查看 change=${changeId}：建议先切换到 \`change/${changeId}\` 再执行开发/交付`);
-  } else if (!inferred) {
-    actions.push(`当前分支为 \`${branch}\`（非 change 分支）：建议 \`aiws change start ${changeId} --hooks --switch\` 或 \`git switch change/${changeId}\``);
-  }
-
-  try {
-    const worktrees = await listGitWorktrees(gitRoot);
-    const changeRef = `refs/heads/change/${changeId}`;
-    const changeWt = worktrees.find((w) => String(w.branch || "") === changeRef);
-    if (changeWt?.worktree && path.resolve(changeWt.worktree) !== path.resolve(gitRoot)) {
-      actions.push(`change/${changeId} 分支在另一个 worktree：\`cd ${changeWt.worktree}\`（建议在该目录执行开发/交付相关命令）`);
-    }
-  } catch {
-    // best-effort; ignore
-  }
-
-  if (!meta) {
-    actions.push(`补齐元信息并建立真值基线：\`aiws change sync ${changeId}\``);
-  }
-
-  if (meta && drift.length > 0) {
-    actions.push("真值/合同已变化：先对齐 `AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md` 与 proposal/tasks");
-    actions.push(`确认后同步基线：\`aiws change sync ${changeId}\``);
-  }
-
-  if (proposal.state !== "ok" || proposal.wsTodo > 0 || proposal.placeholders > 0) {
-    actions.push(`完善 proposal：\`$EDITOR ${path.join(changeDir, "proposal.md")}\``);
-  }
-
-  if (design.state === "ok" && (design.wsTodo > 0 || design.placeholders > 0)) {
-    actions.push(`(可选) 完善 design：\`$EDITOR ${path.join(changeDir, "design.md")}\``);
-  }
-
-  if (tasks.state !== "ok" || tasks.wsTodo > 0 || tasks.placeholders > 0) {
-    actions.push(`完善 tasks：\`$EDITOR ${path.join(changeDir, "tasks.md")}\``);
-  }
-
-  if (proposal.state === "ok") {
-    const reqId = extractId("Req_ID", proposal.text);
-    const probId = extractId("Problem_ID", proposal.text);
-    if (!(reqId || probId)) {
-      actions.push("补齐归因：在 proposal.md 填写非空 `Req_ID` 或 `Problem_ID`（严格校验需要）");
-    }
-
-    const contractRow = extractId("Contract_Row", proposal.text) || extractId("Contract_Row(s)", proposal.text);
-    if (!contractRow) actions.push("补齐绑定：在 proposal.md 填写非空 `Contract_Row`（严格校验需要）");
-
-    const planFile = extractId("Plan_File", proposal.text) || extractId("Plan file", proposal.text);
-    const planFiles = splitDeclaredValues(planFile);
-    if (planFiles.length !== 1) actions.push("补齐绑定：proposal.md `Plan_File` 必须且只能包含 1 个 plan 路径（严格校验需要）");
-    else {
-      const planRel = String(planFiles[0] || "").replace(/^\.\//, "");
-      if (path.isAbsolute(planRel)) actions.push("修正绑定：proposal.md `Plan_File` 必须是工作区相对路径（不要绝对路径）");
-      else if (!(await pathExists(path.join(gitRoot, planRel)))) actions.push(`补齐计划文件：缺少 ${planRel}（或修正 proposal.md 的 Plan_File）`);
-    }
-
-    const evidenceDecl = extractId("Evidence_Path", proposal.text) || extractId("Evidence_Path(s)", proposal.text);
-    const evidencePaths = splitDeclaredValues(evidenceDecl);
-    if (evidencePaths.length === 0) {
-      actions.push("补齐绑定：在 proposal.md 填写非空 `Evidence_Path`（严格校验需要；建议优先写 `changes/<id>/evidence/...`）");
-    } else {
-      const evidence = await analyzeEvidencePaths(gitRoot, changeId, evidencePaths);
-      if (evidence.counts.persistent === 0) {
-        actions.push("交付前建议生成持久证据：`changes/<id>/evidence/...`（并把路径回填到 Evidence_Path；`.agentdocs/tmp/...` 可作为原始证据引用）");
-      }
-      if (evidence.missing.length > 0) {
-        const show = evidence.missing.slice(0, 5);
-        actions.push(`补齐缺失证据文件（missing=${evidence.missing.length}）：${show.join(", ")}${evidence.missing.length > show.length ? ", ..." : ""}`);
-      }
-    }
-  }
-
-  const prog = tasks.state === "ok" ? checkboxStats(tasks.text) : { total: 0, done: 0, unchecked: 0, hasCheckboxes: false };
-  if (!prog.hasCheckboxes) {
-    actions.push("tasks.md 需要至少一条 checkbox 任务（`- [ ]` / `- [x]`）");
-  } else if (prog.unchecked > 0) {
-    actions.push(`完成未勾选任务（${prog.unchecked} 项）`);
-  }
-
-  if (actions.length > 0) {
-    console.log(`- ${planVerifyHint(changeId)}`);
-    for (const a of actions) console.log(`- ${a}`);
-    console.log(`- 修复后复跑质量门：\`aiws change validate ${changeId} --strict\``);
-    console.log("- 质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`");
-    return;
-  }
-
-  console.log(`- ${planVerifyHint(changeId)}`);
-  if (prog.unchecked > 0) {
-    console.log("- 若仍需继续编码，先通过质量门，再在 AI 工具中运行 `$ws-dev`");
-  } else {
-    console.log("- 进入交付：在 AI 工具中运行 `$ws-deliver`（门禁 + submodule 感知提交 + 最终 `$ws-finish`）");
-    console.log("- 交付前门禁（推荐落盘）：`aiws validate . --stamp`");
-  }
-  console.log("- 审计与证据（推荐）：在 AI 工具内运行 `/ws-review`（或按 AI_PROJECT.md 手工审计）");
-  console.log(`- 归档：\`aiws change archive ${changeId}\``);
+  const output = await renderChangeNextOutput(
+    {
+      gitRoot,
+      changeId,
+      changeDir,
+      status: st,
+    },
+    {
+      analyzeEvidencePaths,
+      computeChangeNextAdvice,
+      extractId,
+      fileState,
+      pathExists,
+      planVerifyHint,
+      splitDeclaredValues,
+    },
+  );
+  process.stdout.write(output);
 }
 
 /**
  * @param {string} gitRoot
  * @param {string} changeId
  */
-async function computeChangeNextAdvice(gitRoot, changeId) {
-  const st = await computeChangeStatus(gitRoot, changeId);
-  const branch = await currentBranch(gitRoot);
-  const inferred = inferChangeIdFromBranch(branch);
-  const advice = {
-    changeId,
-    branch: branch || "",
-    inferredChangeId: inferred || "",
-    phase: st.phase,
-    blockersStrict: st.blockersStrict,
-    evidence: st.evidence?.counts || null,
-    actions: [],
-    prohibitions: [],
-    recommended: [],
-  };
-
-  if (!branch) {
-    advice.actions.push("当前为 detached HEAD：建议切到 `change/<change-id>` 分支后再继续（或显式传入 `<change-id>`）");
-  } else if (inferred && inferred !== changeId) {
-    advice.actions.push(`当前分支为 \`${branch}\`（推断 change=${inferred}），但你在查看 change=${changeId}：建议先切换到 \`change/${changeId}\` 再执行开发/交付`);
-  } else if (!inferred) {
-    advice.actions.push(`当前分支为 \`${branch}\`（非 change 分支）：建议 \`aiws change start ${changeId} --hooks --switch\` 或 \`git switch change/${changeId}\``);
-  }
-
-  try {
-    const worktrees = await listGitWorktrees(gitRoot);
-    const changeRef = `refs/heads/change/${changeId}`;
-    const changeWt = worktrees.find((w) => String(w.branch || "") === changeRef);
-    if (changeWt?.worktree && path.resolve(changeWt.worktree) !== path.resolve(gitRoot)) {
-      advice.actions.push(`change/${changeId} 分支在另一个 worktree：\`cd ${changeWt.worktree}\`（建议在该目录执行开发/交付相关命令）`);
-      advice.prohibitions.push("不要在当前 worktree 继续写代码（很可能不在 change 分支上）");
-    }
-  } catch {
-    // ignore
-  }
-
-  if (st.metaState !== "ok") advice.actions.push(`补齐元信息并建立真值基线：\`aiws change sync ${changeId}\``);
-  if (st.driftFiles.length > 0) {
-    advice.actions.push("真值/合同已变化：先对齐 `AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md` 与 proposal/tasks");
-    advice.actions.push(`确认后同步基线：\`aiws change sync ${changeId}\``);
-  }
-
-  if (st.blockersStrict.some((b) => b.includes("proposal.md") && b.includes("WS:TODO"))) {
-    advice.actions.push(`完善 proposal：\`$EDITOR ${path.join(changeDirAbs(gitRoot, changeId), "proposal.md")}\``);
-  }
-  if (st.blockersStrict.some((b) => b.includes("tasks.md") && b.includes("WS:TODO"))) {
-    advice.actions.push(`完善 tasks：\`$EDITOR ${path.join(changeDirAbs(gitRoot, changeId), "tasks.md")}\``);
-  }
-  if (st.blockersStrict.some((b) => b.includes("proposal.md missing attribution"))) {
-    advice.actions.push("补齐归因：在 proposal.md 填写非空 `Req_ID` 或 `Problem_ID`（严格校验需要）");
-  }
-  if (st.blockersStrict.some((b) => b.includes("missing Contract_Row"))) {
-    advice.actions.push("补齐绑定：在 proposal.md 填写非空 `Contract_Row`（严格校验需要）");
-  }
-  if (st.blockersStrict.some((b) => b.includes("Plan_File"))) {
-    advice.actions.push("补齐绑定：修正 proposal.md 的 `Plan_File`（严格校验需要；必须存在且仅 1 个）");
-  }
-  if (st.blockersStrict.some((b) => b.includes("missing Evidence_Path"))) {
-    advice.actions.push("补齐绑定：在 proposal.md 填写非空 `Evidence_Path`（严格校验需要；建议优先写 `changes/<id>/evidence/...`）");
-  }
-  if (st.tasks.unchecked > 0) advice.actions.push(`完成未勾选任务（${st.tasks.unchecked} 项）`);
-
-  if (st.blockersStrict.length > 0 && advice.actions.length === 0) {
-    advice.actions.push("先修复 Blockers (strict) 后复跑质量门，再进入 `$ws-dev`");
-  }
-
-  if (advice.actions.length === 0) {
-    if (st.tasks.unchecked > 0) {
-      advice.recommended.push("继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）");
-    } else {
-      advice.recommended.push("进入交付：在 AI 工具中运行 `$ws-deliver`（门禁 + submodule 感知提交 + 最终 `$ws-finish`）");
-      if (advice.evidence && advice.evidence.persistent === 0) {
-        advice.recommended.push("交付前建议生成持久证据并回填：`aiws change evidence <change-id>`");
-      }
-    }
-  }
-
-  return advice;
+export async function computeChangeNextAdvice(gitRoot, changeId) {
+  return computeChangeNextAdviceModel(gitRoot, changeId, {
+    computeChangeStatus,
+    currentBranch,
+    inferChangeIdFromBranch,
+    listGitWorktrees,
+    changeDirAbs,
+    governanceGuidanceLines,
+    scopeGateFailureAction,
+    scopeGatePendingRecommendation: (id) => scopeGatePendingRecommendation(id),
+    scopeGatePassedRecommendation,
+  });
 }
 
 /**
@@ -2556,62 +1797,24 @@ export async function changeStateCommand(options) {
 
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "state" });
   assertValidChangeId(changeId);
-
-  const st = await computeChangeStatus(gitRoot, changeId);
-  const advice = await computeChangeNextAdvice(gitRoot, changeId);
-
-  const now = nowIsoUtc();
-  /** @type {string[]} */
-  const lines = [];
-  lines.push(`# AIWS STATE: ${changeId}`);
-  lines.push("");
-  lines.push(`Generated: ${now}`);
-  lines.push("");
-  lines.push("## Context");
-  lines.push(`- Worktree: \`${gitRoot}\``);
-  lines.push(`- Branch: \`${advice.branch || "(detached)"}\``);
-  lines.push("");
-  lines.push("## Phase");
-  lines.push(`- Phase: \`${st.phase}\``);
-  lines.push(`- Tasks: ${st.tasks.done}/${st.tasks.total} (unchecked=${st.tasks.unchecked})`);
-  lines.push("");
-  lines.push("## Bindings");
-  if (st.reqId) lines.push(`- Req_ID: \`${st.reqId}\``);
-  if (st.probId) lines.push(`- Problem_ID: \`${st.probId}\``);
-  if (st.bindings?.contractRow) lines.push(`- Contract_Row: \`${st.bindings.contractRow}\``);
-  if (st.bindings?.planFile) lines.push(`- Plan_File: \`${st.bindings.planFile}\``);
-  lines.push("");
-  lines.push("## Evidence");
-  if (st.evidence?.counts) {
-    const c = st.evidence.counts;
-    lines.push(`- Declared: \`${c.total}\` (exists=\`${c.exists}\`, missing=\`${c.missing}\`, persistent=\`${c.persistent}\`, tmp=\`${c.tmp}\`)`);
-  } else {
-    lines.push("- (unknown)");
-  }
-  lines.push("");
-  lines.push("## Blockers (strict)");
-  if (st.blockersStrict.length === 0) lines.push("- (none)");
-  else for (const b of st.blockersStrict) lines.push(`- ${b}`);
-  lines.push("");
-  lines.push("## Next");
-  lines.push(`- ${planVerifyHint(changeId)}`);
-  for (const a of advice.actions) lines.push(`- ${a}`);
-  for (const r of advice.recommended) lines.push(`- ${r}`);
-  if (advice.prohibitions.length > 0) {
-    lines.push("");
-    lines.push("## Do Not");
-    for (const p of advice.prohibitions) lines.push(`- ${p}`);
-  }
-
-  const out = lines.join("\n") + "\n";
-  const dest = path.join(changeDirAbs(gitRoot, changeId), "STATE.md");
-  if (options.write === true) {
-    await writeText(dest, out);
-    await appendMetricsEvent(gitRoot, changeId, "state_written", { path: path.relative(gitRoot, dest) });
-    console.log(`ok: state written: ${path.relative(gitRoot, dest)}`);
-    return;
-  }
-  process.stdout.write(out);
+  const result = await runChangeStateCommand(
+    {
+      gitRoot,
+      changeId,
+      options,
+    },
+    {
+      appendMetricsEvent,
+      changeDirAbs,
+      computeChangeNextAdvice,
+      computeChangeStatus,
+      nowIsoUtc,
+      planVerifyHint,
+      renderChangeStateMarkdown,
+      writeText,
+    },
+  );
+  process.stdout.write(result.output);
 }
 
 /**
@@ -2626,98 +1829,18 @@ export async function metricsSummaryCommand(options) {
   const sinceRaw = String(options.since || "").trim();
   const since = sinceRaw ? new Date(`${sinceRaw}T00:00:00Z`).getTime() : 0;
   if (sinceRaw && Number.isNaN(since)) throw new UserError("Invalid --since (expected YYYY-MM-DD).", { details: `since=${sinceRaw}` });
-
-  const changesRoot = path.join(gitRoot, "changes");
-  if (!(await pathExists(changesRoot))) {
-    console.log("(no changes dir)");
-    return;
-  }
-
-  /** @type {Array<{ changeId: string, path: string, metrics: any }>} */
-  const all = [];
-  const scanDirs = [changesRoot, path.join(changesRoot, "archive")];
-  for (const base of scanDirs) {
-    if (!(await pathExists(base))) continue;
-    const entries = await fs.readdir(base, { withFileTypes: true });
-    for (const e of entries) {
-      if (!e.isDirectory()) continue;
-      const dir = path.join(base, e.name);
-      const mAbs = path.join(dir, "metrics.json");
-      if (!(await pathExists(mAbs))) continue;
-      try {
-        const m = JSON.parse(await readText(mAbs));
-        const cid = String(m?.change_id || "").trim() || e.name;
-        all.push({ changeId: cid, path: path.relative(gitRoot, mAbs), metrics: m });
-      } catch {
-        // ignore invalid
-      }
-    }
-  }
-
-  if (all.length === 0) {
-    console.log("(no metrics.json found)");
-    return;
-  }
-
-  /** @type {Record<string, number>} */
-  const eventCounts = {};
-  let strictValidations = 0;
-  let strictPass = 0;
-  let evidenceRuns = 0;
-  let finishRuns = 0;
-  /** @type {number[]} */
-  const durations = [];
-
-  for (const row of all) {
-    const events = Array.isArray(row.metrics?.events) ? row.metrics.events : [];
-    const filtered = since
-      ? events.filter((ev) => {
-          const t = Date.parse(String(ev?.timestamp || ""));
-          return Number.isFinite(t) && t >= since;
-        })
-      : events;
-
-    for (const ev of filtered) {
-      const type = String(ev?.type || "unknown");
-      eventCounts[type] = (eventCounts[type] || 0) + 1;
-      if (type === "validate") {
-        const p = ev?.payload || {};
-        if (p.strict === true) {
-          strictValidations += 1;
-          if (p.ok === true) strictPass += 1;
-        }
-      }
-      if (type === "evidence") evidenceRuns += 1;
-      if (type === "finish") finishRuns += 1;
-    }
-
-    // Cycle time (best-effort): change_new -> finish
-    const tNew = events.find((e) => e?.type === "change_new")?.timestamp;
-    const tFin = events.find((e) => e?.type === "finish")?.timestamp;
-    if (tNew && tFin) {
-      const a = Date.parse(String(tNew));
-      const b = Date.parse(String(tFin));
-      if (Number.isFinite(a) && Number.isFinite(b) && b >= a) durations.push(Math.floor((b - a) / 1000));
-    }
-  }
-
-  const avgSec = durations.length > 0 ? Math.floor(durations.reduce((x, y) => x + y, 0) / durations.length) : 0;
-  const avgMin = avgSec ? Math.floor(avgSec / 60) : 0;
-
-  console.log(`AIWS Metrics Summary${sinceRaw ? ` (since ${sinceRaw})` : ""}`);
-  console.log("================================================");
-  console.log(`Total metric files: ${all.length}`);
-  console.log("");
-  console.log("Event counts:");
-  for (const k of Object.keys(eventCounts).sort()) console.log(`- ${k}: ${eventCounts[k]}`);
-  console.log("");
-  console.log("Quality:");
-  console.log(`- Strict validate pass rate: ${strictValidations > 0 ? `${strictPass}/${strictValidations}` : "(no data)"}`);
-  console.log(`- Evidence runs: ${evidenceRuns}`);
-  console.log(`- Finish runs: ${finishRuns}`);
-  console.log("");
-  console.log("Cycle time (best-effort):");
-  console.log(`- Avg change_new -> finish: ${durations.length > 0 ? `${avgMin} min` : "(no data)"}`);
+  const output = await renderMetricsSummaryOutput(
+    {
+      gitRoot,
+      sinceRaw,
+      since,
+    },
+    {
+      pathExists,
+      readText,
+    },
+  );
+  process.stdout.write(output);
 }
 
 /**
@@ -2731,201 +1854,38 @@ export async function changeEvidenceCommand(options) {
 
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "evidence" });
   assertValidChangeId(changeId);
-
-  const changeDir = changeDirAbs(gitRoot, changeId);
-  if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
-
-  const proposal = await fileState(changeDir, "proposal.md");
-  if (proposal.state !== "ok") throw new UserError("proposal.md is required for evidence generation.", { details: path.relative(gitRoot, proposal.abs) });
-
-  const planDecl = extractId("Plan_File", proposal.text) || extractId("Plan file", proposal.text);
-  const planFiles = splitDeclaredValues(planDecl).map((p) => String(p || "").replace(/^\.\//, ""));
-  const planRel = planFiles.length === 1 ? planFiles[0] : "";
-  const planAbs = planRel ? path.join(gitRoot, planRel) : "";
-  const planText = planAbs && (await pathExists(planAbs)) ? await readText(planAbs) : "";
-
-  const now = nowStampUtc();
-  const evidenceDir = path.join(changeDir, "evidence");
-  const reviewDir = path.join(changeDir, "review");
-  await ensureDir(evidenceDir);
-  await ensureDir(reviewDir);
-
-  /** @type {string[]} */
-  const created = [];
-
-  const branch = await currentBranch(gitRoot);
-
-  const status = await computeChangeStatus(gitRoot, changeId);
-  const statusOut = {
-    generated_at: nowIsoUtc(),
-    ws_root: gitRoot,
-    change_id: changeId,
-    branch: branch || "",
-    phase: status.phase,
-    tasks: status.tasks,
-    bindings: status.bindings,
-    truth: {
-      baseline: { label: status.baselineLabel, at: status.baselineAt },
-      drift_files: status.driftFiles,
+  const result = await runChangeEvidenceCommand(
+    {
+      gitRoot,
+      changeId,
+      options,
     },
-    evidence: status.evidence?.counts || null,
-    note: "aiws change evidence status snapshot; does not contain secrets.",
-  };
-  const statusPath = path.join(evidenceDir, `change-status-${now}.json`);
-  await writeText(statusPath, JSON.stringify(statusOut, null, 2) + "\n");
-  created.push(relFromRoot(gitRoot, statusPath));
-
-  /** @type {any | null} */
-  let validateRes = null;
-  let validateFailed = false;
-  /** @type {string} */
-  let validatePathForError = "";
-  if (!options.noValidate) {
-    validateRes = await validateChangeArtifacts(gitRoot, changeId, { strict: true, allowTruthDrift: false });
-    const validatePath = path.join(evidenceDir, `change-validate-strict-${now}.json`);
-    await writeText(validatePath, JSON.stringify(validateRes, null, 2) + "\n");
-    created.push(relFromRoot(gitRoot, validatePath));
-    validateFailed = validateRes.ok !== true;
-    validatePathForError = validatePath;
-  }
-
-  const validateStampDir = path.join(gitRoot, ".agentdocs", "tmp", "aiws-validate");
-  const latestValidateStamp = await findLatestFileByMtime(validateStampDir, (n) => n.endsWith(".json"));
-  if (latestValidateStamp) {
-    const dst = path.join(evidenceDir, `aiws-validate-stamp-${now}.json`);
-    await fs.copyFile(latestValidateStamp, dst);
-    created.push(relFromRoot(gitRoot, dst));
-  }
-
-  const syncStampDir = path.join(gitRoot, ".agentdocs", "tmp", "change-sync");
-  const latestSyncStamp = await findLatestFileByMtime(syncStampDir, (n) => n.endsWith(`-${changeId}.json`));
-  if (latestSyncStamp) {
-    const dst = path.join(evidenceDir, `change-sync-stamp-${now}.json`);
-    await fs.copyFile(latestSyncStamp, dst);
-    created.push(relFromRoot(gitRoot, dst));
-  }
-
-  const reviewAbs = path.join(reviewDir, "codex-review.md");
-  if (!(await pathExists(reviewAbs))) {
-    const tmpReview = path.join(gitRoot, ".agentdocs", "tmp", "review", "codex-review.md");
-    if (await pathExists(tmpReview)) {
-      await fs.copyFile(tmpReview, reviewAbs);
-    }
-  }
-  if (await pathExists(reviewAbs)) created.push(relFromRoot(gitRoot, reviewAbs));
-
-  // Collect all review files (support multiple reviewers)
-  if (await pathExists(reviewDir)) {
-    try {
-      const reviewEntries = await fs.readdir(reviewDir, { withFileTypes: true });
-      for (const e of reviewEntries) {
-        if (!e.isFile()) continue;
-        if (e.name === "codex-review.md") continue; // already added
-        if (e.name.endsWith(".md")) {
-          created.push(relFromRoot(gitRoot, path.join(reviewDir, e.name)));
-        }
-      }
-    } catch {
-      // ignore
-    }
-  }
-
-  // Delivery summary (persistent, human-readable).
-  const summaryAbs = path.join(evidenceDir, `delivery-summary-${now}.md`);
-  /** @type {string[]} */
-  const summaryLines = [];
-  summaryLines.push(`# Delivery Summary: ${changeId}`);
-  summaryLines.push("");
-  summaryLines.push(`Generated: ${nowIsoUtc()}`);
-  summaryLines.push("");
-  summaryLines.push("## Context");
-  summaryLines.push(`- Worktree: \`${gitRoot}\``);
-  summaryLines.push(`- Branch: \`${branch || "(detached)"}\``);
-  summaryLines.push("");
-  summaryLines.push("## Status");
-  summaryLines.push(`- Phase: \`${status.phase}\``);
-  summaryLines.push(`- Tasks: ${status.tasks.done}/${status.tasks.total} (unchecked=${status.tasks.unchecked})`);
-  summaryLines.push(`- Truth drift: ${status.driftFiles.length > 0 ? status.driftFiles.join(", ") : "(none)"}`);
-  summaryLines.push("");
-  summaryLines.push("## Bindings");
-  if (status.reqId) summaryLines.push(`- Req_ID: \`${status.reqId}\``);
-  if (status.probId) summaryLines.push(`- Problem_ID: \`${status.probId}\``);
-  if (status.bindings?.contractRow) summaryLines.push(`- Contract_Row: \`${status.bindings.contractRow}\``);
-  if (status.bindings?.planFile) summaryLines.push(`- Plan_File: \`${status.bindings.planFile}\``);
-  summaryLines.push("");
-  summaryLines.push("## Evidence (Created/Collected)");
-  if (created.length === 0) summaryLines.push("- (none)");
-  else for (const p of created) summaryLines.push(`- \`${p}\``);
-  summaryLines.push("");
-  summaryLines.push("## Quality Gate");
-  if (options.noValidate) {
-    summaryLines.push("- Strict validation: (skipped via --no-validate)");
-  } else if (validateRes) {
-    summaryLines.push(`- Strict validation ok: \`${validateRes.ok === true}\``);
-    summaryLines.push(`- Errors: \`${Array.isArray(validateRes.errors) ? validateRes.errors.length : 0}\``);
-    summaryLines.push(`- Warnings: \`${Array.isArray(validateRes.warnings) ? validateRes.warnings.length : 0}\``);
-  } else {
-    summaryLines.push("- Strict validation: (unknown)");
-  }
-  summaryLines.push("");
-  summaryLines.push("## Next");
-  summaryLines.push(`- ${planVerifyHint(changeId)}`);
-  if (validateFailed) summaryLines.push("- Fix strict validation errors, then re-run `aiws change evidence`");
-  else summaryLines.push(`- Verify evidence gate: \`aiws change validate ${changeId} --strict --check-evidence\``);
-  await writeText(summaryAbs, summaryLines.join("\n") + "\n");
-  created.push(relFromRoot(gitRoot, summaryAbs));
-
-  const declaredEvidence = extractId("Evidence_Path", proposal.text) || extractId("Evidence_Path(s)", proposal.text);
-  const existingProposalEvidence = splitDeclaredValues(declaredEvidence).map((p) => String(p || "").replace(/^\.\//, ""));
-  const mergedEvidence = mergeDeclaredValues(existingProposalEvidence, created);
-  const mergedEvidenceText = formatDeclaredValues(mergedEvidence);
-
-  const updatedProposal = upsertProposalEvidencePath(proposal.text, mergedEvidenceText);
-  if (updatedProposal.changed) {
-    await writeText(path.join(changeDir, "proposal.md"), updatedProposal.text);
-  }
-
-  if (planAbs && planText) {
-    const existingPlanEvidence = splitDeclaredValues(extractId("Evidence_Path", planText) || extractId("Evidence_Path(s)", planText)).map((p) =>
-      String(p || "").replace(/^\.\//, ""),
-    );
-    const mergedPlanEvidence = mergeDeclaredValues(existingPlanEvidence, mergedEvidence);
-    const mergedPlanEvidenceText = formatDeclaredValues(mergedPlanEvidence);
-    const updatedPlan = upsertIdLine(planText, ["Evidence_Path", "Evidence_Path(s)"], mergedPlanEvidenceText, { insertAfterLabels: ["Plan_File", "Contract_Row"] });
-    if (updatedPlan.changed) await writeText(planAbs, updatedPlan.text);
-  }
-
-  await appendMetricsEvent(gitRoot, changeId, "evidence", {
-    generated_at: nowIsoUtc(),
-    created: created.length,
-    strict_validate: options.noValidate ? "skipped" : validateRes && validateRes.ok === true ? "ok" : "failed",
-    allow_fail: options.allowFail === true,
-  });
-
-  console.log(`✓ aiws change evidence: ${changeId}`);
-  console.log(`dir: ${path.relative(gitRoot, changeDir)}`);
-  if (planRel) console.log(`Plan_File: ${planRel}`);
-  if (created.length > 0) {
-    console.log("created:");
-    for (const p of created) console.log(`- ${p}`);
-  } else {
-    console.log("created:");
-    console.log("- (none)");
-  }
-  console.log("updated:");
-  console.log(`- ${path.relative(gitRoot, path.join(changeDir, "proposal.md"))} (Evidence_Path)`);
-  if (planRel && planText) console.log(`- ${planRel} (Evidence_Path)`);
-  console.log("");
-  console.log("next:");
-  console.log(`- ${planVerifyHint(changeId)}`);
-  if (validateFailed) console.log("- fix validation errors, then re-run evidence (or run with --allow-fail to proceed)");
-  else console.log(`- verify evidence gate: \`aiws change validate ${changeId} --strict --check-evidence\``);
-
-  if (validateFailed && !options.allowFail) {
-    const details = (validateRes && validateRes.raw ? String(validateRes.raw) : "").trim() || "Validation failed (see evidence JSON for details).";
-    const hint = validatePathForError ? `\n\nevidence:\n- ${path.relative(gitRoot, validatePathForError)}` : "";
-    throw new UserError("Failed to generate evidence due to strict validation errors.", { details: `${details}${hint}` });
-  }
+    {
+      changeDirAbs,
+      fileState,
+      pathExists,
+      runChangeEvidenceWorkflow,
+      workflowDeps: {
+        appendMetricsEvent,
+        computeChangeStatus,
+        currentBranch,
+        ensureDir,
+        extractId,
+        nowIsoUtc,
+        nowStampUtc,
+        pathExists,
+        planVerifyHint,
+        readText,
+        splitDeclaredValues,
+        validateChangeArtifacts,
+        writeText,
+        UserError,
+      },
+      UserError,
+    },
+  );
+  process.stdout.write(result.output);
+  if (result.errorToThrow) throw result.errorToThrow;
 }
 
 /**
@@ -2939,26 +1899,21 @@ export async function changeValidateCommand(options) {
 
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "validate" });
   assertValidChangeId(changeId);
-
-  const res = await validateChangeArtifacts(gitRoot, changeId, {
-    strict: options.strict === true,
-    allowTruthDrift: options.allowTruthDrift === true,
-    checkEvidence: options.checkEvidence === true,
-    checkScope: options.checkScope === true,
-  });
-  await appendMetricsEvent(gitRoot, changeId, "validate", {
-    ok: res.ok === true,
-    strict: options.strict === true,
-    allow_truth_drift: options.allowTruthDrift === true,
-    check_evidence: options.checkEvidence === true,
-    check_scope: options.checkScope === true,
-    errors: Array.isArray(res.errors) ? res.errors.length : 0,
-    warnings: Array.isArray(res.warnings) ? res.warnings.length : 0,
-    exit_code: res.exitCode,
-  });
-  if (res.raw) process.stderr.write(res.raw + "\n");
-  if (!res.ok) throw new UserError("");
-  console.log(`ok: change validated (${changeId})`);
+  const result = await runChangeValidateCommand(
+    {
+      gitRoot,
+      changeId,
+      options,
+    },
+    {
+      appendMetricsEvent,
+      validateChangeArtifacts,
+      UserError,
+    },
+  );
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.errorToThrow) throw result.errorToThrow;
+  process.stdout.write(result.output);
 }
 
 /**
@@ -2972,100 +1927,30 @@ export async function changeSyncCommand(options) {
 
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "sync" });
   assertValidChangeId(changeId);
-
-  const changeDir = changeDirAbs(gitRoot, changeId);
-  if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
-
-  const metaPath = path.join(changeDir, ".ws-change.json");
-  /** @type {any} */
-  let meta = null;
-  if (await pathExists(metaPath)) {
-    try {
-      meta = JSON.parse(await readText(metaPath));
-    } catch {
-      meta = null;
-    }
-  }
-
-  const truth = await snapshotTruthFiles(gitRoot);
-  const nowIso = nowIsoUtc();
-  const nowTs = nowUnixSeconds();
-
-  if (!meta) {
-    meta = { ws_change_version: 1, id: changeId, title: changeId, created_at: nowIso, base_truth_files: truth };
-  }
-
-  const createdTruth = meta.base_truth_files && typeof meta.base_truth_files === "object" ? meta.base_truth_files : {};
-  const syncedTruth = meta.synced_truth_files && typeof meta.synced_truth_files === "object" ? meta.synced_truth_files : {};
-  const baseline = Object.keys(syncedTruth).length > 0 ? syncedTruth : createdTruth;
-  const baselineLabel = Object.keys(syncedTruth).length > 0 ? "last sync" : "creation";
-  const baselineAt = Object.keys(syncedTruth).length > 0 ? String(meta.synced_at || "") : String(meta.created_at || "");
-
-  /** @type {Array<{file: string, from: string | null, to: string | null}>} */
-  const changed = [];
-
-  for (const [rel, info] of Object.entries(truth)) {
-    const curSha = info && typeof info === "object" ? String(info.sha256 || "") : "";
-    const baseSha =
-      baseline && typeof baseline === "object" && baseline[rel] && typeof baseline[rel] === "object" ? String(baseline[rel].sha256 || "") : "";
-    if (baseSha && curSha && baseSha !== curSha) {
-      changed.push({ file: rel, from: baseSha, to: curSha });
-    } else if (!baseSha && curSha) {
-      changed.push({ file: rel, from: null, to: curSha });
-    }
-  }
-
-  if (baseline && typeof baseline === "object") {
-    for (const rel of Object.keys(baseline)) {
-      if (!truth[rel]) {
-        const fromSha = baseline[rel] && typeof baseline[rel] === "object" ? String(baseline[rel].sha256 || "") : null;
-        changed.push({ file: rel, from: fromSha || null, to: null });
-      }
-    }
-  }
-
-  meta.synced_at = nowIso;
-  meta.synced_truth_files = truth;
-  let events = meta.sync_events;
-  if (!Array.isArray(events)) events = [];
-  events.push({ synced_at: nowIso, baseline_from: baselineLabel, baseline_at: baselineAt, changed });
-  meta.sync_events = events.slice(-20);
-
-  await writeText(metaPath, JSON.stringify(meta, null, 2) + "\n");
-
-  const stampDir = path.join(gitRoot, ".agentdocs", "tmp", "change-sync");
-  await ensureDir(stampDir);
-  const stampPath = path.join(stampDir, `${nowStampUtc()}-${changeId}.json`);
-  const stamp = {
-    timestamp: nowTs,
-    ws_root: gitRoot,
-    change_id: changeId,
-    change_dir: changeDir,
-    synced_at: nowIso,
-    previous_baseline: { label: baselineLabel, at: baselineAt, truth_files: baseline },
-    new_baseline: truth,
-    changed,
-    note: "aiws change sync stamp; does not contain secrets.",
-  };
-  await writeText(stampPath, JSON.stringify(stamp, null, 2) + "\n");
-  await appendMetricsEvent(gitRoot, changeId, "truth_sync", {
-    synced_at: nowIso,
-    baseline_from: baselineLabel,
-    baseline_at: baselineAt,
-    changed_files: changed.map((c) => c.file),
-  });
-
-  console.log(`✓ aiws change sync: ${changeId}`);
-  console.log(`meta: ${path.relative(gitRoot, metaPath)}`);
-  console.log(`stamp: ${path.relative(gitRoot, stampPath)}`);
-  if (changed.length > 0) {
-    console.log("");
-    console.log("Changed files:");
-    for (const c of changed) console.log(`- ${c.file}`);
-  } else {
-    console.log("");
-    console.log("No changes detected vs baseline.");
-  }
+  const result = await runChangeSyncCommand(
+    {
+      gitRoot,
+      changeId,
+    },
+    {
+      changeDirAbs,
+      pathExists,
+      runChangeSyncWorkflow,
+      workflowDeps: {
+        appendMetricsEvent,
+        ensureDir,
+        nowIsoUtc,
+        nowStampUtc,
+        nowUnixSeconds,
+        pathExists,
+        readText,
+        snapshotTruthFiles,
+        writeText,
+      },
+      UserError,
+    },
+  );
+  process.stdout.write(result.output);
 }
 
 /**
@@ -3079,70 +1964,33 @@ export async function changeArchiveCommand(options) {
 
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "archive" });
   assertValidChangeId(changeId);
-
-  const changeDir = changeDirAbs(gitRoot, changeId);
-  if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
-
-  // Strict validate before archiving.
-  await changeValidateCommand({ changeId, strict: true, allowTruthDrift: options.force });
-
-  const tasksAbs = path.join(changeDir, "tasks.md");
-  if (await pathExists(tasksAbs)) {
-    const t = await readText(tasksAbs);
-    if (/- \[ \]/.test(t)) {
-      if (!options.force) {
-        throw new UserError("tasks.md still has unchecked tasks; complete them or pass --force");
-      }
-      console.error("warn: tasks.md still has unchecked tasks; continuing due to --force");
-    }
-  }
-
-  const archiveRoot = path.join(gitRoot, "changes", "archive");
-  await ensureDir(archiveRoot);
-
-  const prefix = (options.datePrefix ? String(options.datePrefix) : todayLocal()).trim() || todayLocal();
-  let dest = path.join(archiveRoot, `${prefix}-${changeId}`);
-  if (await pathExists(dest)) {
-    dest = path.join(archiveRoot, `${prefix}-${changeId}-${nowStampUtc()}`);
-  }
-
-  await appendMetricsEvent(gitRoot, changeId, "archive", { archived_to: path.relative(gitRoot, dest) });
-  await fs.rename(changeDir, dest);
-  console.log(`✓ aiws change archive: ${changeId}`);
-  console.log(`archived_to: ${path.relative(gitRoot, dest)}`);
-
-  // Generate handoff.md
-  const handoffPath = path.join(dest, "handoff.md");
-  const handoffContent = await generateHandoffContent(gitRoot, dest, changeId);
-  await writeText(handoffPath, handoffContent);
-  console.log(`handoff: ${path.relative(gitRoot, handoffPath)}`);
-
-  const metaPath = path.join(dest, ".ws-change.json");
-  if (await pathExists(metaPath)) {
-    try {
-      const meta = JSON.parse(await readText(metaPath));
-      const truth = await snapshotTruthFiles(gitRoot);
-      meta.archived_at = nowIsoUtc();
-      meta.archived_to = dest;
-      meta.archived_truth_files = truth;
-      await writeText(metaPath, JSON.stringify(meta, null, 2) + "\n");
-      console.log(`meta_updated: ${path.relative(gitRoot, metaPath)}`);
-    } catch {
-      // ignore invalid meta
-    }
-  }
-
-  const stampDir = path.join(gitRoot, ".agentdocs", "tmp", "change-archive");
-  await ensureDir(stampDir);
-  const stampPath = path.join(stampDir, `${nowStampUtc()}-${changeId}.json`);
-  const truth = await snapshotTruthFiles(gitRoot);
-  const stamp = {
-    timestamp: nowUnixSeconds(),
-    ws_root: gitRoot,
-    archived_to: dest,
-    truth_files: truth,
-    note: "aiws change archive stamp; does not contain secrets.",
-  };
-  await writeText(stampPath, JSON.stringify(stamp, null, 2) + "\n");
-  console.log(`stamp: ${path.relative(gitRoot, stampPath)}`);
+  const result = await runChangeArchiveCommand(
+    {
+      gitRoot,
+      changeId,
+      options,
+    },
+    {
+      changeDirAbs,
+      pathExists,
+      runChangeArchiveWorkflow,
+      workflowDeps: {
+        appendMetricsEvent,
+        changeValidateCommand,
+        ensureDir,
+        generateHandoffContent,
+        nowIsoUtc,
+        nowStampUtc,
+        nowUnixSeconds,
+        pathExists,
+        readText,
+        snapshotTruthFiles,
+        todayLocal,
+        writeText,
+        UserError,
+      },
+      UserError,
+    },
+  );
+  process.stdout.write(result.output);
 }