@aipper/aiws 0.0.29 → 0.0.31

package/src/commands/change.js

@@ -1,1829 +0,0 @@
-import crypto from "node:crypto";
-import path from "node:path";
-import fs from "node:fs/promises";
-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 { checkboxStats } from "./change-task-stats.js";
-import { runChangeValidateCommand } from "./change-validate-entry.js";
-import {
-  computeChangeNextAdvice as computeChangeNextAdviceModel,
-  renderChangeStateMarkdown,
-} from "./change-advice.js";
-import {
-  isGitRepository,
-  listSubmodulesFromGitmodules,
-  resolveFinishContext,
-} from "./change-finish.js";
-import {
-  collectFinishGateErrors,
-  collectReviewGates,
-  collectReviewSignals,
-} from "./change-review-gates.js";
-import {
-  computeScopeGate,
-} 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";
-
-/**
- * @param {string} text
- */
-function countWsTodo(text) {
-  return (text.match(/WS:TODO/g) || []).length;
-}
-
-/**
- * @param {string} text
- */
-function countPlaceholders(text) {
-  return (text.match(/{{CHANGE_ID}}|{{TITLE}}|{{CREATED_AT}}/g) || []).length;
-}
-
-/**
- * @param {string} changeDir
- * @param {string} rel
- */
-async function fileState(changeDir, rel) {
-  const abs = path.join(changeDir, rel);
-  if (!(await pathExists(abs))) return { state: "missing", wsTodo: 0, placeholders: 0, abs, text: "" };
-  const st = await fs.stat(abs);
-  if (st.size === 0) return { state: "empty", wsTodo: 0, placeholders: 0, abs, text: "" };
-  const text = await readText(abs);
-  return { state: "ok", wsTodo: countWsTodo(text), placeholders: countPlaceholders(text), abs, text };
-}
-
-/**
- * Append a change lifecycle event into changes/<id>/metrics.json.
- *
- * @param {string} gitRoot
- * @param {string} changeId
- * @param {string} type
- * @param {any} payload
- */
-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;
-  if (await pathExists(metricsAbs)) {
-    try {
-      cur = JSON.parse(await readText(metricsAbs));
-    } catch {
-      cur = null;
-    }
-  }
-  if (!cur || typeof cur !== "object") {
-    cur = { version: 1, change_id: changeId, events: [] };
-  }
-  if (!Array.isArray(cur.events)) cur.events = [];
-  cur.events.push({ type, timestamp: nowIsoUtc(), payload: payload ?? null });
-  cur.events = cur.events.slice(-200);
-  cur.updated_at = nowIsoUtc();
-  await writeText(metricsAbs, JSON.stringify(cur, null, 2) + "\n");
-}
-
-async function appendMetricsEvent(gitRoot, changeId, type, payload) {
-  const changeDir = changeDirAbs(gitRoot, changeId);
-  await appendMetricsEventAtDir(changeDir, changeId, type, payload);
-}
-
-/**
- * @param {string} gitRoot
- */
-async function resolveTemplateIdForRepo(gitRoot) {
-  const manifestPath = path.join(gitRoot, ".aiws", "manifest.json");
-  if (!(await pathExists(manifestPath))) return "workspace";
-  try {
-    const stored = JSON.parse(await readText(manifestPath));
-    const templateId = String(stored.template_id || "").trim();
-    return templateId || "workspace";
-  } catch {
-    return "workspace";
-  }
-}
-
-/**
- * @param {string} gitRoot
- * @returns {Promise<{ templateDir: string, resolvedFrom: string }>}
- */
-async function resolveChangeTemplatesDir(gitRoot) {
-  const candidates = [
-    { dir: path.join(gitRoot, "changes", "templates"), label: `${gitRoot}/changes/templates` },
-    { dir: path.join(gitRoot, "workflow", "changes", "templates"), label: `${gitRoot}/workflow/changes/templates` },
-  ];
-
-  for (const c of candidates) {
-    if (!(await pathExists(path.join(c.dir, "proposal.md")))) continue;
-    if (!(await pathExists(path.join(c.dir, "tasks.md")))) continue;
-    return { templateDir: c.dir, resolvedFrom: c.label };
-  }
-
-  const templateId = await resolveTemplateIdForRepo(gitRoot);
-  const tpl = await loadTemplate(templateId);
-  const fallback = path.join(tpl.templateDir, "changes", "templates");
-
-  if (!(await pathExists(path.join(fallback, "proposal.md"))) || !(await pathExists(path.join(fallback, "tasks.md")))) {
-    throw new UserError("Missing change templates.", { details: `Expected proposal.md and tasks.md under: ${fallback}` });
-  }
-  return { templateDir: fallback, resolvedFrom: `@aipper/aiws-spec:${tpl.templateId}` };
-}
-
-/**
- * @param {string} templateText
- * @param {{ changeId: string, title: string, createdAt: string }} vars
- */
-function renderTemplate(templateText, vars) {
-  return templateText.replaceAll("{{CHANGE_ID}}", vars.changeId).replaceAll("{{TITLE}}", vars.title).replaceAll("{{CREATED_AT}}", vars.createdAt);
-}
-
-/**
- * @param {string} gitRoot
- * @returns {Promise<{ path: string, args: string[] }>}
- */
-async function resolveWsChangeChecker(gitRoot) {
-  const local = path.join(gitRoot, "tools", "ws_change_check.py");
-  if (await pathExists(local)) return { path: local, args: [local] };
-
-  const templateId = await resolveTemplateIdForRepo(gitRoot);
-  const tpl = await loadTemplate(templateId);
-  const fallback = path.join(tpl.templateDir, "tools", "ws_change_check.py");
-  if (!(await pathExists(fallback))) {
-    throw new UserError("Missing ws_change_check.py.", { details: "Hint: run `aiws init .` to install tools/ws_change_check.py in your repo." });
-  }
-  return { path: fallback, args: [fallback] };
-}
-
-/**
- * @param {string} gitRoot
- * @param {string[]} args
- */
-async function runPython(gitRoot, args) {
-  let res;
-  try {
-    res = await runCommand("python3", args, { cwd: gitRoot });
-  } catch (e) {
-    throw new UserError("python3 is required.", { details: e instanceof Error ? e.message : String(e) });
-  }
-  return res;
-}
-
-/**
- * @param {string} gitRoot
- * @param {string | undefined} changeId
- * @param {{ command: string, allowFinishedUnarchived?: boolean }} options
- */
-async function resolveChangeId(gitRoot, changeId, options) {
-  const resolved = changeId || inferChangeIdFromBranch(await currentBranch(gitRoot));
-  if (resolved) {
-    const terminated = await detectTerminatedChange(gitRoot, resolved);
-    if (!isTerminatedAllowed(options.command, terminated, { allowFinishedUnarchived: options.allowFinishedUnarchived === true })) {
-      throw terminatedChangeError(gitRoot, resolved, terminated, `aiws change ${options.command}`);
-    }
-    return resolved;
-  }
-  throw new UserError(`usage: aiws change ${options.command} <change-id> (or switch to branch change/<change-id>)`);
-}
-
-/**
- * @param {string} gitRoot
- * @param {string} changeId
- */
-function changeDirAbs(gitRoot, changeId) {
-  return path.join(gitRoot, "changes", changeId);
-}
-
-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
- */
-export function assertValidChangeId(changeId) {
-  if (!changeId || !CHANGE_ID_RE.test(changeId)) {
-    throw new UserError(`Invalid change id (use kebab-case): ${changeId}`);
-  }
-}
-
-/**
- * @returns {string} e.g. 2026-01-28T14:00:26Z
- */
-function nowIsoUtc() {
-  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
-}
-
-/**
- * @returns {number} unix seconds
- */
-function nowUnixSeconds() {
-  return Math.floor(Date.now() / 1000);
-}
-
-/**
- * @returns {string} e.g. 20260128-140026Z
- */
-function nowStampUtc() {
-  const d = new Date();
-  const y = String(d.getUTCFullYear());
-  const m = String(d.getUTCMonth() + 1).padStart(2, "0");
-  const day = String(d.getUTCDate()).padStart(2, "0");
-  const hh = String(d.getUTCHours()).padStart(2, "0");
-  const mm = String(d.getUTCMinutes()).padStart(2, "0");
-  const ss = String(d.getUTCSeconds()).padStart(2, "0");
-  return `${y}${m}${day}-${hh}${mm}${ss}Z`;
-}
-
-/**
- * @returns {string} e.g. 2026-01-28 (local date)
- */
-function todayLocal() {
-  const d = new Date();
-  const y = String(d.getFullYear());
-  const m = String(d.getMonth() + 1).padStart(2, "0");
-  const day = String(d.getDate()).padStart(2, "0");
-  return `${y}-${m}-${day}`;
-}
-
-/**
- * @param {string} absPath
- */
-async function resolveGitRoot(absPath) {
-  let res;
-  try {
-    res = await runCommand("git", ["rev-parse", "--show-toplevel"], { cwd: absPath });
-  } catch (e) {
-    throw new UserError("git is required for aiws change commands.", { details: e instanceof Error ? e.message : String(e) });
-  }
-  if (res.code !== 0) {
-    throw new UserError("Not a git repository.", { details: res.stderr || res.stdout });
-  }
-  const root = String(res.stdout || "").trim();
-  if (!root) throw new UserError("Failed to resolve git repository root.");
-  return root;
-}
-
-/**
- * @param {string} gitRoot
- * @returns {Promise<string>} branch or empty
- */
-async function currentBranch(gitRoot) {
-  const res = await runCommand("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: gitRoot });
-  if (res.code !== 0) return "";
-  return String(res.stdout || "").trim();
-}
-
-/**
- * @param {string} gitRoot
- */
-async function hasHeadCommit(gitRoot) {
-  return runCommand("git", ["rev-parse", "--verify", "HEAD"], { cwd: gitRoot }).then((r) => r.code === 0);
-}
-
-/**
- * @param {string} gitRoot
- * @returns {Promise<{ clean: true } | { clean: false, details: string }>}
- */
-async function checkGitClean(gitRoot) {
-  const res = await runCommand("git", ["status", "--porcelain"], { cwd: gitRoot });
-  const out = String(res.stdout || "").trim();
-  if (!out) return { clean: true };
-  const lines = out.split("\n");
-  const truncated = lines.length > 20 ? `${lines.slice(0, 20).join("\n")}\n... (truncated)` : out;
-  return { clean: false, details: truncated };
-}
-
-/**
- * @param {string} branch
- */
-function inferChangeIdFromBranch(branch) {
-  const m = CHANGE_BRANCH_RE.exec(branch || "");
-  return m?.[2] || "";
-}
-
-/**
- * @param {string} gitRoot
- */
-async function ensureTruthFiles(gitRoot) {
-  const required = ["AI_PROJECT.md", "AI_WORKSPACE.md", "REQUIREMENTS.md"];
-  const missing = [];
-  for (const f of required) {
-    if (!(await pathExists(path.join(gitRoot, f)))) missing.push(f);
-  }
-  if (missing.length > 0) {
-    throw new UserError("AI Workspace truth files missing.", {
-      details: `Root: ${gitRoot}\nMissing:\n${missing.map((m) => `- ${m}`).join("\n")}\n\nHint: run \`aiws init .\` (new) or \`aiws update .\` (migrate).`,
-    });
-  }
-}
-
-/**
- * @param {string} filePath
- * @returns {Promise<string>}
- */
-async function sha256FileBytes(filePath) {
-  const buf = await fs.readFile(filePath);
-  return crypto.createHash("sha256").update(buf).digest("hex");
-}
-
-/**
- * @param {string} gitRoot
- * @returns {Promise<Record<string, {mtime: number, sha256: string}>>}
- */
-async function snapshotTruthFiles(gitRoot) {
-  /** @type {Record<string, {mtime: number, sha256: string}>} */
-  const truth = {};
-  for (const rel of ["AI_PROJECT.md", "AI_WORKSPACE.md", "REQUIREMENTS.md"]) {
-    const abs = path.join(gitRoot, rel);
-    if (!(await pathExists(abs))) continue;
-    const st = await fs.stat(abs);
-    truth[rel] = { mtime: Math.floor(st.mtimeMs / 1000), sha256: await sha256FileBytes(abs) };
-  }
-  return truth;
-}
-
-/**
- * @param {string} gitRoot
- * @returns {Promise<Record<string, string | null>>}
- */
-async function snapshotTruthShaOnly(gitRoot) {
-  /** @type {Record<string, string | null>} */
-  const out = {};
-  for (const rel of ["AI_PROJECT.md", "AI_WORKSPACE.md", "REQUIREMENTS.md"]) {
-    const abs = path.join(gitRoot, rel);
-    if (!(await pathExists(abs))) {
-      out[rel] = null;
-      continue;
-    }
-    try {
-      out[rel] = await sha256FileBytes(abs);
-    } catch {
-      out[rel] = null;
-    }
-  }
-  return out;
-}
-
-/**
- * @param {string} s
- */
-function escapeRegExp(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * @param {string} label
- * @param {string} text
- */
-function extractId(label, text) {
-  const re = new RegExp(`^.*${escapeRegExp(label)}.*?[:=][ \\t]*(.*)$`, "m");
-  const m = re.exec(text);
-  if (!m) return "";
-  let v = String(m[1] || "").trim();
-  v = v.replace(/<!--.*?-->/g, "").trim();
-  v = v.replace(/^`+/, "").replace(/`+$/, "").trim();
-  return v;
-}
-
-/**
- * @param {string} s
- */
-function splitDeclaredValues(s) {
-  return String(s || "")
-    .split(/[,;\n]+/g)
-    .map((x) => x.trim().replace(/^`+/, "").replace(/`+$/, "").trim())
-    .filter(Boolean);
-}
-
-/**
- * Extract bullet lines under a markdown "## ..." heading.
- *
- * @param {string} text
- * @param {RegExp} headingRe
- * @param {{ max?: number }} [options]
- * @returns {string[]} trimmed bullet lines like "- foo"
- */
-function extractBulletsUnderHeading(text, headingRe, options) {
-  const max = typeof options?.max === "number" ? options.max : 5;
-  const lines = String(text || "").split("\n");
-  let inSection = false;
-  /** @type {string[]} */
-  const out = [];
-  for (const raw of lines) {
-    const line = String(raw || "");
-    const trimmed = line.trim();
-    if (!inSection) {
-      if (headingRe.test(trimmed)) inSection = true;
-      continue;
-    }
-    if (/^##\s+/.test(trimmed)) break;
-    if (trimmed.startsWith("-")) {
-      out.push(trimmed);
-      if (out.length >= max) break;
-    }
-  }
-  return out;
-}
-
-/**
- * @param {string} bulletLine
- */
-function isMeaningfulBullet(bulletLine) {
-  const s = String(bulletLine || "").trim();
-  if (!s.startsWith("-")) return false;
-  if (s.includes("WS:TODO")) return false;
-  if (s.includes("<!--")) return false;
-  if (s === "-" || s === "- (none)" || s === "- (missing)") return false;
-  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
- * @param {string} changeId
- * @returns {Promise<string | null>} Full path to archived change dir, or null if not found.
- */
-async function findArchivedChange(archiveDir, changeId) {
-  if (!(await pathExists(archiveDir))) return null;
-  try {
-    const entries = await fs.readdir(archiveDir, { withFileTypes: true });
-    const matches = entries
-      .filter((e) => e.isDirectory())
-      .map((e) => ({ entry: e, parsed: parseArchivedChangeDirName(e.name) }))
-      .filter((item) => item.parsed?.changeId === changeId)
-      .sort((a, b) => a.entry.name.localeCompare(b.entry.name));
-    if (matches.length > 0) return path.join(archiveDir, matches.at(-1)?.entry.name || "");
-  } catch {
-    // ignore
-  }
-  return null;
-}
-
-/**
- * @param {string} gitRoot
- * @param {string} changeId
- * @returns {Promise<null | { kind: "archived" | "finished_unarchived", archivedChangeDir?: string, archivedHandoffRel?: string, lifecycle?: any }>}
- */
-async function detectTerminatedChange(gitRoot, changeId) {
-  const changeDir = changeDirAbs(gitRoot, changeId);
-  const archiveRoot = path.join(gitRoot, "changes", "archive");
-  const activeExists = await pathExists(changeDir);
-  if (!activeExists) {
-    const archivedChangeDir = await findArchivedChange(archiveRoot, changeId);
-    if (!archivedChangeDir) return null;
-    const archivedHandoffPath = path.join(archivedChangeDir, "handoff.md");
-    return {
-      kind: "archived",
-      archivedChangeDir,
-      archivedHandoffRel: (await pathExists(archivedHandoffPath)) ? path.relative(gitRoot, archivedHandoffPath) : "",
-    };
-  }
-
-  const lifecycle = summarizeLifecycleSignals(await readChangeMetrics(changeDir, { pathExists, readText }));
-  if (lifecycle.finishState !== "done") return null;
-  return { kind: "finished_unarchived", lifecycle };
-}
-
-/**
- * @param {string} gitRoot
- * @param {string} changeId
- * @param {Awaited<ReturnType<typeof detectTerminatedChange>>} terminated
- * @param {string} action
- */
-function terminatedChangeError(gitRoot, changeId, terminated, action) {
-  if (terminated?.kind === "archived") {
-    return new UserError(`Change ${changeId} is already archived.`, {
-      details:
-        `change: ${changeId}\n` +
-        `archived: ${path.relative(gitRoot, terminated.archivedChangeDir || "")}\n` +
-        (terminated.archivedHandoffRel ? `handoff: ${terminated.archivedHandoffRel}\n` : "") +
-        `next: create a new follow-up change instead of reusing change/${changeId}` +
-        (action ? `\nblocked: ${action}` : ""),
-    });
-  }
-  return new UserError(`Change ${changeId} has unfinished finish closeout; resume finish before any follow-up work.`, {
-    details:
-      `change: ${changeId}\n` +
-      `branch: change/${changeId}\n` +
-      `next: rerun \`aiws change finish ${changeId} --push\` to complete push/archive closeout` +
-      `\nfallback: if you intentionally only need local archive recovery, run \`aiws change archive ${changeId}\`` +
-      (action ? `\nblocked: ${action}` : ""),
-  });
-}
-
-/**
- * @param {string} command
- * @param {Awaited<ReturnType<typeof detectTerminatedChange>>} terminated
- * @param {{ allowFinishedUnarchived?: boolean }} [options]
- */
-function isTerminatedAllowed(command, terminated, options = {}) {
-  if (!terminated) return true;
-  if (terminated.kind === "finished_unarchived") {
-    if (command === "archive") return true;
-    if (command === "finish") return true;
-    if (command === "status" || command === "next") return true;
-    if (options.allowFinishedUnarchived === true) return true;
-  }
-  return false;
-}
-
-/**
- * Extract a brief summary from handoff.md content.
- * @param {string} text
- * @returns {string}
- */
-function extractHandoffSummary(text) {
-  // Try to extract "本次完成" or "What Changed" section
-  const lines = String(text || "").split("\n");
-  let inSection = false;
-  const summary = [];
-  for (const line of lines) {
-    if (/^##\s*(本次完成|What Changed|Completed)/i.test(line)) {
-      inSection = true;
-      continue;
-    }
-    if (inSection && /^##/.test(line)) break;
-    if (inSection && line.trim().startsWith("-")) {
-      summary.push(line.trim());
-      if (summary.length >= 3) break;
-    }
-  }
-  return summary.join(" ");
-}
-
-/**
- * Check Depends_On dependencies and print handoff summaries.
- * @param {string} gitRoot - The git root directory (main or worktree)
- * @param {string} changeId
- * @param {string} changeDir - The change directory (may be in worktree)
- */
-async function checkDependenciesAndPrintHandoff(gitRoot, changeId, changeDir) {
-  const proposalPath = path.join(changeDir, "proposal.md");
-  if (!(await pathExists(proposalPath))) return;
-
-  const proposalText = await readText(proposalPath);
-  const dependsOn = extractId("Depends_On", proposalText);
-  if (!dependsOn) return;
-
-  const deps = splitDeclaredValues(dependsOn).filter((d) => d && d !== changeId);
-  if (deps.length === 0) return;
-  const archiveDir = path.join(gitRoot, "changes", "archive");
-
-  for (const dep of deps) {
-    const depDir = changeDirAbs(gitRoot, dep);
-    const depArchived = await findArchivedChange(archiveDir, dep);
-    if (!depArchived && !(await pathExists(depDir))) {
-      console.error(`warn: Depends_On "${dep}" not found (neither active nor archived)`);
-      console.error(`hint: if you are using --worktree, ensure the dependency is archived under changes/archive/ and committed to HEAD in this worktree.`);
-    } else if (!depArchived) {
-      console.error(`warn: Depends_On "${dep}" is not yet archived (still active at changes/${dep})`);
-    } else {
-      // Dependency is archived, check for handoff.md
-      const handoffPath = path.join(depArchived, "handoff.md");
-      if (await pathExists(handoffPath)) {
-        console.log(`info: reading handoff from dependency "${dep}"`);
-        const handoffText = await readText(handoffPath);
-        const summary = extractHandoffSummary(handoffText);
-        if (summary) {
-          console.log(`  ${summary}`);
-        }
-      } else {
-        console.error(`warn: dependency "${dep}" is archived but missing handoff.md: ${path.relative(gitRoot, handoffPath)}`);
-      }
-    }
-  }
-}
-
-/**
- * Generate handoff.md content for a completed change.
- * @param {string} gitRoot
- * @param {string} changeDir - The archived change directory
- * @param {string} changeId
- * @returns {Promise<string>}
- */
-async function generateHandoffContent(gitRoot, changeDir, changeId) {
-  const proposalPath = path.join(changeDir, "proposal.md");
-  const designPath = path.join(changeDir, "design.md");
-
-  let reqId = "";
-  let problemId = "";
-  let blocks = "";
-  let goal = "";
-  let baseBranch = "main";
-  /** @type {string[]} */
-  const decisions = [];
-  const collaboration = await collectCollaborationArtifacts(gitRoot, changeDir);
-
-  if (await pathExists(proposalPath)) {
-    const text = await readText(proposalPath);
-    reqId = extractId("Req_ID", text);
-    problemId = extractId("Problem_ID", text);
-    blocks = extractId("Blocks", text);
-    const declaredBase = extractId("Base_Branch", text);
-    if (declaredBase) baseBranch = declaredBase;
-    // Extract goal from 目标 section
-    const goalMatch = text.match(/\*\*目标[：:]\*\*\s*\n([\s\S]*?)(?=\n\*\*非目标|$)/);
-    if (goalMatch) {
-      const goalLines = goalMatch[1].split("\n").filter((l) => l.trim().startsWith("-")).slice(0, 3);
-      goal = goalLines.map((l) => l.trim()).join("\n");
-    }
-  }
-
-  // Get changed files from git diff if possible
-  let changedFiles = [];
-  try {
-    const metaPath = path.join(changeDir, ".ws-change.json");
-    if (await pathExists(metaPath)) {
-      const meta = JSON.parse(await readText(metaPath));
-      if (meta && typeof meta === "object" && meta.base_branch) baseBranch = String(meta.base_branch || "").trim() || baseBranch;
-    }
-
-    const changeBranch = `change/${changeId}`;
-    const hasChangeBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", `refs/heads/${changeBranch}`], { cwd: gitRoot }).then((r) => r.code === 0);
-    const cur = await currentBranch(gitRoot);
-    const diffTarget = hasChangeBranch ? changeBranch : cur === changeBranch ? "HEAD" : "";
-    if (diffTarget) {
-      const diff = await runCommand("git", ["diff", "--name-only", `${baseBranch}...${diffTarget}`], { cwd: gitRoot });
-      if (diff.code === 0 && diff.stdout) {
-        changedFiles = diff.stdout.split("\n").filter(Boolean).slice(0, 20);
-      }
-    }
-  } catch {
-    // ignore
-  }
-
-  try {
-    if (await pathExists(designPath)) {
-      const designText = await readText(designPath);
-      decisions.push(...extractBulletsUnderHeading(designText, /^##\s*Decisions\s*$/i, { max: 12 }).filter(isMeaningfulBullet).slice(0, 8));
-      decisions.push(...extractBulletsUnderHeading(designText, /^##\s*关键决策\s*$/i, { max: 12 }).filter(isMeaningfulBullet).slice(0, 8));
-    } else if (await pathExists(proposalPath)) {
-      const proposalText = await readText(proposalPath);
-      const fromProposal = extractBulletsUnderHeading(proposalText, /^##\s*方案概述\b.*$/i, { max: 10 }).filter(isMeaningfulBullet).slice(0, 6);
-      for (const b of fromProposal) decisions.push(`- (from proposal) ${b.replace(/^-+\s*/, "")}`);
-    }
-  } catch {
-    // ignore
-  }
-
-  const lines = [
-    `# Handoff: ${changeId}`,
-    "",
-    `> Archived: ${nowIsoUtc()}`,
-    "",
-    "## 本次完成",
-    "",
-  ];
-
-  if (goal) {
-    lines.push(goal);
-  } else {
-    lines.push("- (see proposal.md for details)");
-  }
-
-  lines.push("");
-  lines.push("## 改动文件");
-  lines.push("");
-  if (changedFiles.length > 0) {
-    for (const f of changedFiles) {
-      lines.push(`- ${f}`);
-    }
-    if (changedFiles.length === 20) {
-      lines.push("- ...(truncated)");
-    }
-  } else {
-    lines.push("- (see git log for details)");
-  }
-
-  lines.push("");
-  lines.push("## 关键决策");
-  lines.push("");
-  if (decisions.length > 0) {
-    for (const d of decisions) lines.push(d);
-  } else {
-    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("");
-  if (blocks) {
-    const blockIds = splitDeclaredValues(blocks);
-    for (const b of blockIds) {
-      lines.push(`- 可以开始: ${b}`);
-    }
-  } else {
-    lines.push("- (no Blocks declared)");
-  }
-
-  lines.push("");
-  lines.push("## 绑定");
-  lines.push("");
-  lines.push(`- Change_ID: ${changeId}`);
-  if (reqId) lines.push(`- Req_ID: ${reqId}`);
-  if (problemId) lines.push(`- Problem_ID: ${problemId}`);
-
-  return lines.join("\n") + "\n";
-}
-
-/**
- * @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";
-}
-
-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,
-    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";
-  /** @type {any} */
-  let meta = null;
-  if (await pathExists(metaPath)) {
-    metaState = "ok";
-    try {
-      meta = JSON.parse(await readText(metaPath));
-    } catch {
-      metaState = "invalid";
-      meta = null;
-    }
-  }
-
-  const reqId = proposal.state === "ok" ? extractId("Req_ID", proposal.text) : "";
-  const probId = proposal.state === "ok" ? extractId("Problem_ID", proposal.text) : "";
-  const contractRow = proposal.state === "ok" ? extractId("Contract_Row", proposal.text) || extractId("Contract_Row(s)", proposal.text) : "";
-  const planFile = proposal.state === "ok" ? extractId("Plan_File", proposal.text) || extractId("Plan file", proposal.text) : "";
-  const evidencePath = proposal.state === "ok" ? extractId("Evidence_Path", proposal.text) || extractId("Evidence_Path(s)", proposal.text) : "";
-  const evidencePaths = splitDeclaredValues(evidencePath);
-  const evidence = await analyzeEvidencePaths(gitRoot, changeId, evidencePaths);
-  const taskProgress =
-    tasks.state === "ok"
-      ? checkboxStats(tasks.text)
-      : {
-          total: 0,
-          done: 0,
-          unchecked: 0,
-          hasCheckboxes: false,
-          totalAll: 0,
-          doneAll: 0,
-          uncheckedAll: 0,
-          optionalTotal: 0,
-          optionalUnchecked: 0,
-          naCount: 0,
-        };
-
-  const curTruth = await snapshotTruthShaOnly(gitRoot);
-  const { baselineLabel, baselineAt, driftFiles } = meta ? truthDrift(curTruth, meta) : { baselineLabel: "-", baselineAt: "", driftFiles: [] };
-
-  /** @type {string[]} */
-  const blockersStrict = [];
-  /** @type {string[]} */
-  const blockersArchive = [];
-
-  if (metaState !== "ok") {
-    blockersStrict.push("missing/invalid .ws-change.json (run `aiws change sync <id>` to regenerate)");
-  }
-
-  for (const [rel, st] of [
-    ["proposal.md", proposal],
-    ["tasks.md", tasks],
-  ]) {
-    if (st.state !== "ok") {
-      blockersStrict.push(`missing/empty ${rel}`);
-      continue;
-    }
-    if (st.placeholders > 0) blockersStrict.push(`unrendered template placeholders in ${rel}`);
-    if (st.wsTodo > 0) blockersStrict.push(`WS:TODO markers remain in ${rel}`);
-  }
-
-  if (design.state === "ok") {
-    if (design.placeholders > 0) blockersStrict.push("unrendered template placeholders in design.md");
-    if (design.wsTodo > 0) blockersStrict.push("WS:TODO markers remain in design.md");
-  }
-
-  if (proposal.state === "ok" && !(reqId || probId)) {
-    blockersStrict.push("proposal.md missing attribution (Req_ID or Problem_ID)");
-  }
-
-  if (proposal.state === "ok" && !contractRow) blockersStrict.push("proposal.md missing Contract_Row binding");
-
-  if (proposal.state === "ok") {
-    const planFiles = splitDeclaredValues(planFile);
-    if (planFiles.length !== 1) blockersStrict.push("proposal.md Plan_File must contain exactly one plan path");
-    else {
-      const planRel = String(planFiles[0] || "").replace(/^\.\//, "");
-      if (path.isAbsolute(planRel)) blockersStrict.push("proposal.md Plan_File must be workspace-relative (not absolute)");
-      else {
-        if (!planRel.startsWith("plan/")) blockersStrict.push("proposal.md Plan_File should be under plan/ (recommended)");
-        if (!(await pathExists(path.join(gitRoot, planRel)))) blockersStrict.push(`proposal.md Plan_File missing: ${planRel}`);
-      }
-    }
-  }
-
-  if (proposal.state === "ok" && evidencePaths.length === 0) blockersStrict.push("proposal.md missing Evidence_Path binding");
-
-  if (!taskProgress.hasCheckboxes) blockersStrict.push("tasks.md has no checkbox tasks ('- [ ]' or '- [x]')");
-  if (driftFiles.length > 0) blockersStrict.push(`truth drift vs ${baselineLabel} baseline (run \`aiws change sync ${changeId}\`)`);
-
-  const lifecycle = summarizeLifecycleSignals(metrics);
-  const terminatedReuse =
-    lifecycle.finishState === "done"
-      ? {
-          kind: "finished_unarchived",
-          message: `change/${changeId} has unfinished finish closeout; rerun \`aiws change finish ${changeId} --push\` to complete archive/push`,
-        }
-      : null;
-  if (terminatedReuse) {
-    blockersStrict.push(terminatedReuse.message);
-  }
-
-  blockersArchive.push(...blockersStrict);
-  if (taskProgress.unchecked > 0) blockersArchive.push(`tasks.md still has unchecked required tasks (${taskProgress.unchecked} items)`);
-  const phase = inferChangePhase(blockersStrict, taskProgress);
-  if (terminatedReuse) {
-    lifecycle.finishState = "resume_required";
-    lifecycle.finishStateReason = "archive_pending";
-  }
-  const scopeGate = computeScopeGate(lifecycle);
-
-  const baseStatus = {
-    ok: true,
-    changeId,
-    dir: path.relative(gitRoot, changeDir),
-    phase,
-    context,
-    metaState,
-    reqId,
-    probId,
-    bindings: {
-      contractRow,
-      planFile,
-      evidencePaths,
-    },
-    scopeGate,
-    evidence,
-    collaboration,
-    reviewSignals,
-    reviewGates,
-    git,
-    repo: {
-      submodules: submodules.length,
-    },
-    lifecycle,
-    tasks: taskProgress,
-    baselineLabel,
-    baselineAt,
-    driftFiles,
-    blockersStrict,
-    blockersArchive,
-    terminatedReuse,
-    hints: {
-      planVerify: planVerifyHint(changeId),
-      dev: "质量门通过后再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`",
-    },
-  };
-  const governance = await inferChangeGovernance(baseStatus);
-  return {
-    ...baseStatus,
-    governance: {
-      ...governance,
-      warning: context.warning || "",
-    },
-  };
-}
-
-export async function validateChangeArtifacts(gitRoot, changeId, options) {
-  return validateChangeArtifactsModel(gitRoot, changeId, options, {
-    assertValidChangeId,
-    collectFinishGateErrors,
-    computeChangeStatus,
-    ensureTruthFiles,
-    pathExists,
-    readText,
-    resolveWsChangeChecker,
-    runCommand,
-    runPython,
-    UserError,
-  });
-}
-
-/**
- * aiws change list
- */
-export async function changeListCommand() {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const changesRoot = path.join(gitRoot, "changes");
-  if (!(await pathExists(changesRoot))) {
-    console.log("(no changes dir)");
-    return;
-  }
-
-  const curTruth = await snapshotTruthShaOnly(gitRoot);
-
-  const entries = await fs.readdir(changesRoot, { withFileTypes: true });
-  const dirs = entries
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name)
-    .filter((name) => name && !name.startsWith(".") && name !== "archive" && name !== "templates")
-    .sort();
-
-  if (dirs.length === 0) {
-    console.log("(no active changes)");
-    return;
-  }
-
-  /** @type {Array<[string, string, string, string, number, string, string]>} */
-  const rows = [];
-
-  for (const name of dirs) {
-    const dir = path.join(changesRoot, name);
-    const proposalPath = path.join(dir, "proposal.md");
-    const tasksPath = path.join(dir, "tasks.md");
-    const metaPath = path.join(dir, ".ws-change.json");
-
-    const metaState = !(await pathExists(metaPath)) ? "missing" : "ok";
-    /** @type {any} */
-    let meta = null;
-    if (metaState === "ok") {
-      try {
-        meta = JSON.parse(await readText(metaPath));
-      } catch {
-        meta = null;
-      }
-    }
-    const finalMetaState = meta ? "ok" : metaState === "missing" ? "missing" : "invalid";
-
-    let proposalWsTodo = 0;
-    if (await pathExists(proposalPath)) {
-      try {
-        proposalWsTodo = countWsTodo(await readText(proposalPath));
-      } catch {
-        proposalWsTodo = 0;
-      }
-    }
-
-    let tasksTotal = 0;
-    let tasksDone = 0;
-    let tasksTodo = 0;
-    let tasksWsTodo = 0;
-    if (await pathExists(tasksPath)) {
-      try {
-        const t = await readText(tasksPath);
-        const stats = checkboxStats(t);
-        tasksTotal = stats.total;
-        tasksDone = stats.done;
-        tasksTodo = stats.unchecked;
-        tasksWsTodo = countWsTodo(t);
-      } catch {
-        // ignore
-      }
-    }
-
-    const { baselineLabel, driftFiles } = meta ? truthDrift(curTruth, meta) : { baselineLabel: "-", driftFiles: [] };
-
-    let nextStep = "archive";
-    if (finalMetaState !== "ok") nextStep = "sync";
-    else if (driftFiles.length > 0) nextStep = "sync";
-    else if (proposalWsTodo + tasksWsTodo > 0) nextStep = "edit";
-    else if (tasksTodo > 0) nextStep = "do";
-
-    rows.push([
-      name,
-      nextStep,
-      finalMetaState,
-      baselineLabel,
-      driftFiles.length,
-      `${tasksDone}/${tasksTotal} (unchecked=${tasksTodo})`,
-      `proposal=${proposalWsTodo} tasks=${tasksWsTodo}`,
-    ]);
-  }
-
-  console.log("change_id\tnext\tmeta\tbaseline\tdrift\ttasks\tWS:TODO");
-  for (const r of rows) {
-    console.log(r.join("\t"));
-  }
-}
-
-/**
- * aiws change templates which
- */
-export async function changeTemplatesWhichCommand() {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const templateId = await resolveTemplateIdForRepo(gitRoot);
-  const tpl = await loadTemplate(templateId);
-  const resolved = await resolveChangeTemplatesDir(gitRoot);
-
-  console.log(`templates: ${resolved.templateDir}`);
-  console.log(`resolved_from: ${resolved.resolvedFrom}`);
-  console.log("precedence:");
-  console.log(`  1) ${path.join(gitRoot, "changes", "templates")}`);
-  console.log(`  2) ${path.join(gitRoot, "workflow", "changes", "templates")}`);
-  console.log(`  3) ${path.join(tpl.templateDir, "changes", "templates")}`);
-}
-
-/**
- * aiws change templates init
- */
-export async function changeTemplatesInitCommand() {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const templateId = await resolveTemplateIdForRepo(gitRoot);
-  const tpl = await loadTemplate(templateId);
-
-  const rels = ["changes/templates/proposal.md", "changes/templates/tasks.md", "changes/templates/design.md"];
-  /** @type {string[]} */
-  const installed = [];
-  /** @type {string[]} */
-  const skipped = [];
-
-  for (const rel of rels) {
-    const destAbs = path.join(gitRoot, ...rel.split("/"));
-    if (await pathExists(destAbs)) {
-      skipped.push(rel);
-      continue;
-    }
-    await copyTemplateFileToWorkspace({ templateDir: tpl.templateDir, workspaceRoot: gitRoot, relPosix: rel });
-    installed.push(rel);
-  }
-
-  console.log(`✓ aiws change templates init: ${gitRoot}`);
-  if (installed.length > 0) console.log(`installed: ${installed.join(", ")}`);
-  if (skipped.length > 0) console.log(`skip: ${skipped.join(", ")}`);
-}
-
-/**
- * @param {string} gitRoot
- * @param {{ changeId: string, title?: string, noDesign: boolean, baseBranch?: string }} options
- */
-async function changeNewAtGitRoot(gitRoot, options) {
-  await ensureTruthFiles(gitRoot);
-
-  const changeId = String(options.changeId || "").trim();
-  assertValidChangeId(changeId);
-  const terminated = await detectTerminatedChange(gitRoot, changeId);
-  if (terminated) throw terminatedChangeError(gitRoot, changeId, terminated, "aiws change new");
-
-  const title = (options.title ? String(options.title) : changeId).trim() || changeId;
-  const createdAt = nowIsoUtc();
-
-  const changeRoot = path.join(gitRoot, "changes");
-  await ensureDir(changeRoot);
-  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"));
-  const tasksTpl = await readText(path.join(templates.templateDir, "tasks.md"));
-  await writeText(path.join(changeDir, "proposal.md"), renderTemplate(proposalTpl, { changeId, title, createdAt }));
-  await writeText(path.join(changeDir, "tasks.md"), renderTemplate(tasksTpl, { changeId, title, createdAt }));
-
-  if (!options.noDesign) {
-    const designTplPath = path.join(templates.templateDir, "design.md");
-    if (!(await pathExists(designTplPath))) {
-      throw new UserError("Missing design.md in templates dir; pass --no-design to skip.", { details: `templates: ${templates.templateDir}` });
-    }
-    const designTpl = await readText(designTplPath);
-    await writeText(path.join(changeDir, "design.md"), renderTemplate(designTpl, { changeId, title, createdAt }));
-  }
-
-  const truth = await snapshotTruthFiles(gitRoot);
-  const meta = {
-    ws_change_version: 1,
-    id: changeId,
-    title,
-    created_at: createdAt,
-    base_truth_files: truth,
-  };
-  const baseBranch = String(options.baseBranch || "").trim();
-  if (baseBranch) {
-    meta.base_branch = baseBranch;
-    meta.base_branch_set_at = createdAt;
-  }
-  await writeText(path.join(changeDir, ".ws-change.json"), JSON.stringify(meta, null, 2) + "\n");
-  await appendMetricsEvent(gitRoot, changeId, "change_new", {
-    title,
-    created_at: createdAt,
-    base_branch: baseBranch || "",
-    templates: templates.resolvedFrom,
-    no_design: options.noDesign === true,
-  });
-
-  console.log(`✓ aiws change new: ${changeId}`);
-  console.log(`dir: ${path.relative(gitRoot, changeDir)}`);
-  console.log(`templates: ${templates.resolvedFrom}`);
-  console.log("next:");
-  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}`);
-}
-
-/**
- * aiws change new
- *
- * @param {{ changeId: string, title?: string, noDesign: boolean }} options
- */
-export async function changeNewCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await changeNewAtGitRoot(gitRoot, options);
-}
-
-/**
- * aiws change start
- *
- * @param {{ changeId: string, title?: string, noDesign: boolean, enableHooks: boolean, noSwitch: boolean, forceSwitch: boolean, allowDirty?: boolean }} options
- */
-export async function changeStartCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const changeId = String(options.changeId || "").trim();
-  assertValidChangeId(changeId);
-  const terminated = await detectTerminatedChange(gitRoot, changeId);
-  if (terminated) throw terminatedChangeError(gitRoot, changeId, terminated, "aiws change start");
-
-  const startFromBranch = await currentBranch(gitRoot);
-  const branch = `change/${changeId}`;
-  const allowDirty = options.allowDirty === true;
-
-  if (options.forceSwitch === true && options.noSwitch === true) {
-    throw new UserError("change start: cannot combine --switch with --no-switch");
-  }
-
-  const hasBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: gitRoot }).then((r) => r.code === 0);
-  const hasGitmodules = await pathExists(path.join(gitRoot, ".gitmodules"));
-  let effectiveNoSwitch = options.noSwitch === true;
-  const effectiveForceSwitch = options.forceSwitch === true;
-
-  if (hasGitmodules && !effectiveNoSwitch && !effectiveForceSwitch) {
-    effectiveNoSwitch = true;
-    console.error("warn: .gitmodules detected (git submodules). defaulting to --no-switch (prepare artifacts only).");
-    console.error("warn: to switch anyway: aiws change start <change-id> --switch");
-  } else if (hasGitmodules && effectiveForceSwitch) {
-    console.error("warn: .gitmodules detected (git submodules). switching the superproject branch due to --switch.");
-    console.error("warn: recommended for submodules: aiws change start <change-id> --no-switch");
-  }
-
-  if (!allowDirty && !effectiveNoSwitch) {
-    const clean = await checkGitClean(gitRoot);
-    if (!clean.clean) {
-      throw new UserError("Refusing to start change with a dirty working tree.", {
-        details:
-          `${clean.details}\n\n` +
-          "Fix: commit first, then retry:\n" +
-          "  git add -A && git commit -m \"wip: save before change start\"\n" +
-          "Fix: or stash:\n" +
-          "  git stash\n" +
-          `Alt: prepare artifacts without switching: aiws change start ${changeId} --no-switch\n` +
-          "Alt: proceed anyway (not recommended): add --allow-dirty",
-      });
-    }
-  }
-
-  const headReady = await hasHeadCommit(gitRoot);
-  let branchReady = hasBranch;
-
-  if (effectiveNoSwitch) {
-    branchReady = await prepareNoSwitchBranch(gitRoot, { branch, hasBranch, headReady }, { runCommand, UserError });
-  } else {
-    await switchOrCreateStartBranch(gitRoot, { branch, hasBranch, hasGitmodules }, { runCommand, UserError });
-    branchReady = true;
-  }
-
-  const changeDir = changeDirAbs(gitRoot, changeId);
-  if (!(await pathExists(changeDir))) {
-    await changeNewAtGitRoot(gitRoot, {
-      changeId,
-      title: options.title,
-      noDesign: options.noDesign,
-      baseBranch: startFromBranch && startFromBranch !== branch ? startFromBranch : undefined,
-    });
-  } else {
-    await maybeRecordBaseBranch(changeDir, startFromBranch, branch, { nowIsoUtc, pathExists, readText, writeText });
-  }
-
-  await checkDependenciesAndPrintHandoff(gitRoot, changeId, changeDir);
-
-  if (options.enableHooks) {
-    await hooksInstallCommand({ targetPath: gitRoot });
-  }
-
-  const cur = await currentBranch(gitRoot);
-  const curLabel = cur || "(detached)";
-  await appendMetricsEvent(gitRoot, changeId, "change_start", {
-    mode: effectiveNoSwitch ? "no-switch" : "switch",
-    branch,
-    from_branch: startFromBranch || "",
-    current_branch: curLabel,
-    hooks: options.enableHooks === true,
-  });
-  if (effectiveNoSwitch && cur !== branch) {
-    console.log(`ok: prepared change: ${changeId} (branch: ${branch}${branchReady ? "" : " (pending)"}; current: ${curLabel})`);
-    console.log("next:");
-    if (branchReady) {
-      console.log(`  - switch:   git switch ${branch}`);
-    } else {
-      console.log("  - note:     repo has no commits; create the branch after your first commit");
-      console.log(`  - create:   git branch ${branch}`);
-      console.log(`  - switch:   git switch ${branch}`);
-    }
-    console.log(`  - status:   aiws change status ${changeId}`);
-    console.log(`  - next:     aiws change next ${changeId}`);
-    console.log(`  - validate: aiws change validate ${changeId} --strict`);
-    if (!options.enableHooks) console.log("  - (optional) enable hooks: aiws hooks install .");
-    return;
-  }
-
-  console.log(`ok: active change: ${changeId} (branch: ${branch}; current: ${curLabel})`);
-  console.log("next:");
-  console.log("  - status:   aiws change status");
-  console.log("  - next:     aiws change next");
-  console.log("  - validate: aiws change validate --strict");
-  if (!options.enableHooks) console.log("  - (optional) enable hooks: aiws hooks install .");
-}
-
-/**
- * aiws change finish
- *
- * @param {{ changeId?: string, into?: string, base?: string, push?: boolean, remote?: string }} options
- */
-export async function changeFinishCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const resolvedChangeId = await resolveChangeId(gitRoot, options.changeId, { command: "finish" });
-  assertValidChangeId(resolvedChangeId);
-  const terminated = await detectTerminatedChange(gitRoot, resolvedChangeId);
-  if (terminated?.kind === "archived") throw terminatedChangeError(gitRoot, resolvedChangeId, terminated, "aiws change finish");
-  const resumeFinishedUnarchived = terminated?.kind === "finished_unarchived";
-  if (resumeFinishedUnarchived && options.push !== true) {
-    throw new UserError("Change finish closeout is pending; rerun with --push.", {
-      details:
-        `change: ${resolvedChangeId}\n` +
-        `next: rerun \`aiws change finish ${resolvedChangeId} --push\` to complete archive/push closeout\n` +
-        `fallback: if you intentionally only need local archive recovery, run \`aiws change archive ${resolvedChangeId}\``,
-    });
-  }
-  const { changeId, changeBranch, into, cur } = await resolveFinishContext(gitRoot, { ...options, changeId: resolvedChangeId }, {
-    assertValidChangeId,
-    checkGitClean,
-    currentBranch,
-    pathExists,
-    readText,
-    resolveChangeId,
-    runCommand,
-    UserError,
-  });
-  const finishStatusRoot = 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 });
-    if (sw.code !== 0) {
-      const co = await runCommand("git", ["checkout", into], { cwd: gitRoot });
-      if (co.code !== 0) throw new UserError("Failed to switch target branch.", { details: co.stderr || co.stdout });
-    }
-  }
-
-  const merge = await runCommand("git", ["merge", "--ff-only", changeBranch], { cwd: gitRoot });
-  if (merge.code !== 0) {
-    throw new UserError("Failed to fast-forward merge change branch into target.", {
-      details:
-        `${merge.stderr || merge.stdout}` +
-        `\n\nIf not fast-forward, rebase the change branch then retry:\n` +
-        `  git switch ${changeBranch}\n  git rebase ${into}\n  git switch ${into}\n  aiws change finish ${changeId}`,
-    });
-  }
-
-  await appendMetricsEvent(gitRoot, changeId, "finish_local", finishBasePayload);
-  if (resumeFinishedUnarchived) {
-    console.log(`resume: continuing previously finished change ${changeId} to complete remaining finish steps`);
-  }
-
-  let cleanupNote = "not_requested";
-  let finishCompleted = false;
-  let archivedToRel = "";
-  let handoffRel = "";
-  if (options.push === true) {
-    try {
-      const submodulePush = await pushSubmodulesForFinish(gitRoot, changeId, into, {
-        pathExists,
-        readText,
-        runCommand,
-        UserError,
-      });
-      if (submodulePush.processed > 0) {
-        console.log(`submodule push: ok (${submodulePush.processed} repos)`);
-      }
-
-      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}` : ""}`);
-
-      cleanupNote = "skipped:current_worktree";
-      finishCompleted = true;
-      console.log("cleanup: skipped (no separate worktree)");
-    } catch (error) {
-      await appendMetricsEvent(gitRoot, changeId, "finish_failed", {
-        ...finishBasePayload,
-        error: error instanceof Error ? error.message : String(error),
-      });
-      throw error;
-    }
-  }
-
-  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` +
-        `  - 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}`,
-          });
-        }
-      }
-    }
-  }
-
-  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 needed when submodule state changes");
-  }
-}
-
-/**
- * aiws change status
- *
- * @param {{ changeId?: string }} options
- */
-export async function changeStatusCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "status" });
-  const st = await computeChangeStatus(gitRoot, changeId);
-  const branch = await currentBranch(gitRoot);
-  const output = await renderChangeStatusOutput(
-    {
-      gitRoot,
-      branch,
-      status: st,
-    },
-    {
-      effectiveReviewCount,
-      governanceGuidanceLines,
-      planVerifyHint,
-    },
-  );
-  process.stdout.write(output);
-}
-
-/**
- * aiws change next
- *
- * @param {{ changeId?: string }} options
- */
-export async function changeNextCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "next" });
-  assertValidChangeId(changeId);
-  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 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
- */
-export async function computeChangeNextAdvice(gitRoot, changeId) {
-  return computeChangeNextAdviceModel(gitRoot, changeId, {
-    computeChangeStatus,
-    currentBranch,
-    inferChangeIdFromBranch,
-    changeDirAbs,
-    governanceGuidanceLines,
-    scopeGateFailureAction,
-    scopeGatePendingRecommendation: (id) => scopeGatePendingRecommendation(id),
-    scopeGatePassedRecommendation,
-  });
-}
-
-/**
- * aiws change state
- *
- * @param {{ changeId?: string, write: boolean }} options
- */
-export async function changeStateCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "state" });
-  assertValidChangeId(changeId);
-  const result = await runChangeStateCommand(
-    {
-      gitRoot,
-      changeId,
-      options,
-    },
-    {
-      appendMetricsEvent,
-      changeDirAbs,
-      computeChangeNextAdvice,
-      computeChangeStatus,
-      nowIsoUtc,
-      planVerifyHint,
-      renderChangeStateMarkdown,
-      writeText,
-    },
-  );
-  process.stdout.write(result.output);
-}
-
-/**
- * aiws metrics summary
- *
- * @param {{ since?: string }} options
- */
-export async function metricsSummaryCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  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 output = await renderMetricsSummaryOutput(
-    {
-      gitRoot,
-      sinceRaw,
-      since,
-    },
-    {
-      pathExists,
-      readText,
-    },
-  );
-  process.stdout.write(output);
-}
-
-/**
- * aiws change evidence
- *
- * @param {{ changeId?: string, noValidate: boolean, allowFail: boolean }} options
- */
-export async function changeEvidenceCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "evidence" });
-  assertValidChangeId(changeId);
-  const result = await runChangeEvidenceCommand(
-    {
-      gitRoot,
-      changeId,
-      options,
-    },
-    {
-      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;
-}
-
-/**
- * aiws change validate
- *
- * @param {{ changeId?: string, strict: boolean, allowTruthDrift: boolean, checkEvidence: boolean, checkScope: boolean, allowFinishedUnarchived?: boolean }} options
- */
-export async function changeValidateCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const changeId = await resolveChangeId(gitRoot, options.changeId, {
-    command: "validate",
-    allowFinishedUnarchived: options.allowFinishedUnarchived === true,
-  });
-  assertValidChangeId(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);
-}
-
-/**
- * aiws change sync
- *
- * @param {{ changeId?: string }} options
- */
-export async function changeSyncCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "sync" });
-  assertValidChangeId(changeId);
-  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);
-}
-
-/**
- * aiws change archive
- *
- * @param {{ changeId?: string, datePrefix?: string, force: boolean }} options
- */
-export async function changeArchiveCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
-  await ensureTruthFiles(gitRoot);
-
-  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "archive" });
-  assertValidChangeId(changeId);
-  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);
-}