@aipper/aiws 0.0.1

package/src/commands/change.js

@@ -0,0 +1,987 @@
+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 { copyTemplateFileToWorkspace } from "../template.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
+ */
+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} branch
+ * @returns {string}
+ */
+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)}.*?[:=]\\s*(.+)$`, "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} text
+ */
+function checkboxStats(text) {
+  const total = (text.match(/^- \[[ xX]\]/gm) || []).length;
+  const done = (text.match(/^- \[[xX]\]/gm) || []).length;
+  const unchecked = (text.match(/^- \[ \]/gm) || []).length;
+  return { total, done, unchecked, hasCheckboxes: total > 0 };
+}
+
+/**
+ * @param {string} text
+ */
+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 };
+}
+
+/**
+ * @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 }} options
+ */
+async function resolveChangeId(gitRoot, changeId, options) {
+  if (changeId) return changeId;
+  const branch = await currentBranch(gitRoot);
+  const inferred = inferChangeIdFromBranch(branch);
+  if (inferred) return inferred;
+  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
+ */
+function changeDirAbs(gitRoot, changeId) {
+  return path.join(gitRoot, "changes", changeId);
+}
+
+/**
+ * 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(", ")}`);
+}
+
+/**
+ * aiws change new
+ *
+ * @param {{ changeId: string, title?: string, noDesign: boolean }} options
+ */
+export async function changeNewCommand(options) {
+  const gitRoot = await resolveGitRoot(process.cwd());
+  await ensureTruthFiles(gitRoot);
+
+  const changeId = String(options.changeId || "").trim();
+  assertValidChangeId(changeId);
+
+  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);
+
+  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,
+  };
+  await writeText(path.join(changeDir, ".ws-change.json"), JSON.stringify(meta, null, 2) + "\n");
+
+  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(`  - validate: aiws change validate ${changeId}`);
+}
+
+/**
+ * aiws change start
+ *
+ * @param {{ changeId: string, title?: string, noDesign: boolean, enableHooks: 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 branch = `change/${changeId}`;
+
+  const hasBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: gitRoot }).then((r) => r.code === 0);
+  if (hasBranch) {
+    const sw = await runCommand("git", ["switch", branch], { cwd: gitRoot });
+    if (sw.code !== 0) {
+      const 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 {
+    const sw = await runCommand("git", ["switch", "-c", branch], { cwd: gitRoot });
+    if (sw.code !== 0) {
+      const 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 });
+    }
+  }
+
+  const changeDir = changeDirAbs(gitRoot, changeId);
+  if (!(await pathExists(changeDir))) {
+    await changeNewCommand({ changeId, title: options.title, noDesign: options.noDesign });
+  }
+
+  if (options.enableHooks) {
+    await hooksInstallCommand({ targetPath: gitRoot });
+  }
+
+  console.log(`ok: active change: ${changeId} (branch: ${branch})`);
+  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 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" });
+  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");
+  const tasks = await fileState(changeDir, "tasks.md");
+  const design = await fileState(changeDir, "design.md");
+
+  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 taskProgress = tasks.state === "ok" ? checkboxStats(tasks.text) : { total: 0, done: 0, unchecked: 0, hasCheckboxes: false };
+
+  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 (!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}\`)`);
+
+  blockersArchive.push(...blockersStrict);
+  if (taskProgress.unchecked > 0) blockersArchive.push(`tasks.md still has unchecked tasks (${taskProgress.unchecked} items)`);
+
+  console.log(`✓ aiws change status: ${changeId}`);
+  console.log(`dir: ${path.relative(gitRoot, changeDir)}`);
+  console.log(`meta: ${metaState}`);
+  if (reqId) console.log(`Req_ID: ${reqId}`);
+  if (probId) console.log(`Problem_ID: ${probId}`);
+  console.log(`tasks: ${taskProgress.done}/${taskProgress.total} (unchecked=${taskProgress.unchecked})`);
+  console.log(`baseline: ${baselineLabel}${baselineAt ? ` (at=${baselineAt})` : ""}`);
+  console.log(`drift: ${driftFiles.length > 0 ? driftFiles.join(", ") : "(none)"}`);
+
+  console.log("");
+  console.log("Blockers (strict):");
+  if (blockersStrict.length === 0) console.log("- (none)");
+  else for (const b of blockersStrict) console.log(`- ${b}`);
+
+  console.log("");
+  console.log("Blockers (archive):");
+  if (blockersArchive.length === 0) console.log("- (none)");
+  else for (const b of blockersArchive) console.log(`- ${b}`);
+}
+
+/**
+ * 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 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 = [];
+
+  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 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) {
+    actions.push(`严格校验：\`aiws change validate ${changeId} --strict\``);
+    for (const a of actions) console.log(`- ${a}`);
+    return;
+  }
+
+  console.log("- 生成交叉审计报告：在 AI 工具内运行 `/ws-review`（或按 AI_PROJECT.md 手工审计）");
+  console.log(`- 归档：\`aiws change archive ${changeId}\``);
+}
+
+/**
+ * aiws change validate
+ *
+ * @param {{ changeId?: string, strict: boolean, allowTruthDrift: 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" });
+  assertValidChangeId(changeId);
+
+  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");
+
+  const res = await runPython(gitRoot, ["-u", ...args]);
+  if (res.stdout) process.stdout.write(res.stdout);
+  if (res.stderr) process.stderr.write(res.stderr);
+  if (res.code !== 0) {
+    throw new UserError("");
+  }
+  console.log(`ok: change validated (${changeId})`);
+}
+
+/**
+ * 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 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");
+
+  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.");
+  }
+}
+
+/**
+ * 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 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 fs.rename(changeDir, dest);
+  console.log(`✓ aiws change archive: ${changeId}`);
+  console.log(`archived_to: ${path.relative(gitRoot, dest)}`);
+
+  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)}`);
+}