@aipper/aiws 0.0.20 → 0.0.23

package/src/commands/change.js

@@ -320,6 +320,412 @@ function splitDeclaredValues(s) {
     .filter(Boolean);
 }
 
+/**
+ * @param {string} p
+ */
+function normalizeSlashes(p) {
+  return String(p || "").replaceAll("\\", "/");
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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 });
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      // Archive dirs are named like: 2026-03-12-<change-id> or 2026-03-12-<change-id>-<timestamp>
+      if (e.name.endsWith(`-${changeId}`) || e.name.includes(`-${changeId}-`)) {
+        return path.join(archiveDir, e.name);
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * 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 = [];
+
+  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 (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";
+}
+
+/**
+ * Evidence_Path is user-declared; we treat it as best-effort hints, not hard gates.
+ *
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {string[]} evidencePaths
+ * @returns {Promise<{
+ *   entries: Array<{rel: string, abs: string, exists: boolean, kind: string, isAbsolute: boolean}>,
+ *   counts: { total: number, exists: number, missing: number, tmp: number, persistent: number, other: number, absolute: number },
+ *   missing: string[]
+ * }>}
+ */
+async function analyzeEvidencePaths(gitRoot, changeId, evidencePaths) {
+  const changePrefix = `changes/${changeId}/`;
+  const evidencePrefix = `changes/${changeId}/evidence/`;
+  const reviewPrefix = `changes/${changeId}/review/`;
+
+  const entries = await Promise.all(
+    (evidencePaths || []).map(async (raw) => {
+      const rel = String(raw || "").trim();
+      const isAbsolute = path.isAbsolute(rel);
+      const abs = isAbsolute ? rel : path.join(gitRoot, rel);
+      const exists = rel ? await pathExists(abs) : false;
+
+      const relNorm = normalizeSlashes(rel);
+      let kind = "other";
+      if (relNorm.startsWith(".agentdocs/tmp/") || relNorm.startsWith(".agentdocs/")) kind = "tmp";
+      else if (relNorm.startsWith(evidencePrefix) || relNorm.startsWith(reviewPrefix) || relNorm.startsWith(changePrefix)) kind = "persistent";
+
+      return { rel, abs: path.resolve(abs), exists, kind, isAbsolute };
+    }),
+  );
+
+  const missing = entries.filter((e) => e.rel && !e.exists).map((e) => e.rel);
+  const counts = {
+    total: entries.filter((e) => e.rel).length,
+    exists: entries.filter((e) => e.rel && e.exists).length,
+    missing: missing.length,
+    tmp: entries.filter((e) => e.rel && e.kind === "tmp").length,
+    persistent: entries.filter((e) => e.rel && e.kind === "persistent").length,
+    other: entries.filter((e) => e.rel && e.kind === "other").length,
+    absolute: entries.filter((e) => e.rel && e.isAbsolute).length,
+  };
+
+  return { entries: entries.filter((e) => e.rel), counts, missing };
+}
+
+/**
+ * @param {string[]} a
+ * @param {string[]} b
+ */
+function mergeDeclaredValues(a, b) {
+  const seen = new Set();
+  /** @type {string[]} */
+  const out = [];
+  for (const raw of [...(a || []), ...(b || [])]) {
+    const v = String(raw || "").trim().replace(/^`+/, "").replace(/`+$/, "").trim();
+    if (!v) continue;
+    if (seen.has(v)) continue;
+    seen.add(v);
+    out.push(v);
+  }
+  return out;
+}
+
+/**
+ * @param {string[]} values
+ */
+function formatDeclaredValues(values) {
+  return (values || []).join(", ");
+}
+
+/**
+ * Replace or insert a simple "ID: value" style line in Markdown.
+ *
+ * @param {string} text
+ * @param {string[]} labelCandidates
+ * @param {string} value
+ * @param {{ insertAfterLabels?: string[] }} options
+ */
+function upsertIdLine(text, labelCandidates, value, options) {
+  const src = String(text || "");
+  const labels = Array.isArray(labelCandidates) ? labelCandidates : [];
+  for (const label of labels) {
+    const re = new RegExp(`^(.*${escapeRegExp(label)}.*?[:=][ \\t]*)(.*)$`, "m");
+    const m = re.exec(src);
+    if (!m) continue;
+    const prefix = m[1] || "";
+    const replaced = src.replace(re, `${prefix}${value}`);
+    return { ok: true, changed: replaced !== src, text: replaced, mode: "replaced", label };
+  }
+
+  // Insert near the top (best-effort), after a nearby label if present.
+  const insertAfter = Array.isArray(options?.insertAfterLabels) ? options.insertAfterLabels : [];
+  const lines = src.split(/\r?\n/);
+  let idx = 0;
+  for (let i = 0; i < Math.min(lines.length, 80); i++) {
+    const line = lines[i] || "";
+    if (insertAfter.some((l) => line.includes(l))) idx = i + 1;
+  }
+  const insertedLabel = labels[0] || "Evidence_Path";
+  const newLine = `- ${insertedLabel}: ${value}`;
+  lines.splice(idx, 0, newLine);
+  const inserted = lines.join("\n");
+  return { ok: true, changed: inserted !== src, text: inserted, mode: "inserted", label: labels[0] || "" };
+}
+
+/**
+ * Special-case insertion for proposal.md template style.
+ *
+ * @param {string} proposalText
+ * @param {string} value
+ */
+function upsertProposalEvidencePath(proposalText, value) {
+  const src = String(proposalText || "");
+  const re = new RegExp(`^(.*${escapeRegExp("Evidence_Path")}.*?[:=][ \\t]*)(.*)$`, "m");
+  if (re.test(src)) {
+    const m = re.exec(src);
+    const prefix = m?.[1] || "";
+    const out = src.replace(re, `${prefix}${value}`);
+    return { changed: out !== src, text: out, mode: "replaced" };
+  }
+  // Insert right after Plan_File binding if possible.
+  const lines = src.split(/\r?\n/);
+  let idx = 0;
+  for (let i = 0; i < Math.min(lines.length, 120); i++) {
+    if ((lines[i] || "").includes("Plan_File")) {
+      idx = i + 1;
+      break;
+    }
+  }
+  lines.splice(idx, 0, `- \`Evidence_Path\` = ${value}`);
+  const inserted = lines.join("\n");
+  return { changed: inserted !== src, text: inserted, mode: "inserted" };
+}
+
 /**
  * @param {string} changeId
  */
@@ -327,6 +733,16 @@ function planVerifyHint(changeId) {
   return `执行前质量门（优先）：\`aiws change validate ${changeId} --strict\`（AI 工具中等价于 \`$ws-plan-verify\`）`;
 }
 
+/**
+ * @param {string[]} blockersStrict
+ * @param {{ unchecked: number }} tasks
+ */
+function inferChangePhase(blockersStrict, tasks) {
+  if ((blockersStrict || []).length > 0) return "planning";
+  if ((tasks?.unchecked || 0) > 0) return "dev";
+  return "deliver";
+}
+
 /**
  * Compute change status as JSON-friendly object (used by dashboard and CLI).
  *
@@ -364,6 +780,7 @@ export async function computeChangeStatus(gitRoot, changeId) {
   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 };
 
   const curTruth = await snapshotTruthShaOnly(gitRoot);
@@ -399,16 +816,35 @@ export async function computeChangeStatus(gitRoot, changeId) {
     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}\`)`);
 
   blockersArchive.push(...blockersStrict);
   if (taskProgress.unchecked > 0) blockersArchive.push(`tasks.md still has unchecked tasks (${taskProgress.unchecked} items)`);
+  const phase = inferChangePhase(blockersStrict, taskProgress);
 
   return {
     ok: true,
     changeId,
     dir: path.relative(gitRoot, changeDir),
+    phase,
     metaState,
     reqId,
     probId,
@@ -417,6 +853,7 @@ export async function computeChangeStatus(gitRoot, changeId) {
       planFile,
       evidencePaths,
     },
+    evidence,
     tasks: taskProgress,
     baselineLabel,
     baselineAt,
@@ -483,7 +920,7 @@ function groupCheckMessages(errors, warnings) {
  *
  * @param {string} gitRoot
  * @param {string} changeId
- * @param {{ strict: boolean, allowTruthDrift: boolean }} options
+ * @param {{ strict: boolean, allowTruthDrift: boolean, checkEvidence?: boolean, checkScope?: boolean }} options
  */
 export async function validateChangeArtifacts(gitRoot, changeId, options) {
   assertValidChangeId(changeId);
@@ -493,6 +930,8 @@ export async function validateChangeArtifacts(gitRoot, changeId, options) {
   const args = [...checker.args, "--workspace-root", gitRoot, "--change-id", changeId];
   if (options.strict) args.push("--strict");
   if (options.allowTruthDrift) args.push("--allow-truth-drift");
+  if (options.checkEvidence) args.push("--check-evidence");
+  if (options.checkScope) args.push("--check-scope");
 
   const res = await runPython(gitRoot, ["-u", ...args]);
   const parsed = parseChangeCheckerOutput(res.stdout, res.stderr);
@@ -546,6 +985,69 @@ async function fileState(changeDir, rel) {
   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 appendMetricsEvent(gitRoot, changeId, type, payload) {
+  const changeDir = changeDirAbs(gitRoot, changeId);
+  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");
+}
+
+/**
+ * @param {string} absDir
+ * @param {(name: string) => boolean} predicate
+ */
+async function findLatestFileByMtime(absDir, predicate) {
+  if (!(await pathExists(absDir))) return "";
+  const entries = await fs.readdir(absDir, { withFileTypes: true });
+  /** @type {{ abs: string, mtimeMs: number } | null} */
+  let best = null;
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    if (!predicate(e.name)) continue;
+    const abs = path.join(absDir, e.name);
+    let st;
+    try {
+      st = await fs.stat(abs);
+    } catch {
+      continue;
+    }
+    const mtimeMs = Number(st.mtimeMs || 0);
+    if (!best || mtimeMs > best.mtimeMs) best = { abs, mtimeMs };
+  }
+  return best ? best.abs : "";
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} absPath
+ */
+function relFromRoot(gitRoot, absPath) {
+  return normalizeSlashes(path.relative(gitRoot, absPath));
+}
+
 /**
  * @param {string} gitRoot
  */
@@ -884,6 +1386,13 @@ async function changeNewAtGitRoot(gitRoot, options) {
     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)}`);
@@ -908,7 +1417,7 @@ export async function changeNewCommand(options) {
 /**
  * aiws change start
  *
- * @param {{ changeId: string, title?: string, noDesign: boolean, enableHooks: boolean, noSwitch: boolean, forceSwitch: boolean, worktree: boolean, worktreeDir?: string, submodules: boolean }} options
+ * @param {{ changeId: string, title?: string, noDesign: boolean, enableHooks: boolean, noSwitch: boolean, forceSwitch: boolean, allowDirty?: boolean, worktree: boolean, worktreeDir?: string, submodules: boolean }} options
  */
 export async function changeStartCommand(options) {
   const gitRoot = await resolveGitRoot(process.cwd());
@@ -920,6 +1429,7 @@ export async function changeStartCommand(options) {
   const startFromBranch = await currentBranch(gitRoot);
   const branch = `change/${changeId}`;
   const branchRef = `refs/heads/${branch}`;
+  const allowDirty = options.allowDirty === true;
 
   if (options.worktree === true && options.noSwitch === true) {
     throw new UserError("change start: cannot combine --worktree with --no-switch");
@@ -959,6 +1469,24 @@ export async function changeStartCommand(options) {
     console.error("warn: recommended for submodules: aiws change start <change-id> --worktree");
   }
 
+  if (!allowDirty && (effectiveWorktree || !effectiveNoSwitch)) {
+    const clean = await checkGitClean(gitRoot);
+    if (!clean.clean) {
+      const mode = effectiveWorktree ? "worktree" : "switch";
+      throw new UserError(`Refusing to start change with a dirty working tree (${mode} mode).`, {
+        details:
+          `${clean.details}\n\n` +
+          `Why: starting in ${mode} mode changes your checkout context; uncommitted changes may not appear where you expect.\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",
+      });
+    }
+  }
+
   if (effectiveWorktree) {
     const prereq = await checkWorktreePrereqs(gitRoot);
     if (!prereq.ok) {
@@ -1036,18 +1564,48 @@ export async function changeStartCommand(options) {
       await maybeRecordBaseBranch(changeDir, startFromBranch, branch);
     }
 
-    if (options.submodules === true) {
-      const sm = await runCommand("git", ["submodule", "update", "--init", "--recursive"], { cwd: destKey });
-      if (sm.code !== 0) throw new UserError("Failed to init/update submodules in worktree.", { details: sm.stderr || sm.stdout });
-    } else if (hasGitmodules) {
-      console.error("warn: .gitmodules detected; new worktree may have empty submodule dirs.");
-      console.error("warn: consider running in the worktree: git submodule update --init --recursive (or re-run with --submodules)");
+    // Worktree mode: if this repo declares submodules, always initialize them in the new worktree.
+    // --submodules is now implicit (kept for backwards compat but has no effect).
+    if (hasGitmodules) {
+      const hasEntries = await runCommand("git", ["config", "--file", ".gitmodules", "--get-regexp", "^submodule\\..*\\.path$"], { cwd: destKey }).then(
+        (r) => r.code === 0 && String(r.stdout || "").trim().length > 0
+      );
+      if (hasEntries) {
+        console.error("info: .gitmodules detected; initializing submodules in the new worktree.");
+        const sm = await runCommand("git", ["submodule", "update", "--init", "--recursive"], { cwd: destKey });
+        if (sm.code !== 0) throw new UserError("Failed to init/update submodules in worktree.", { details: sm.stderr || sm.stdout });
+
+        // Sanity check: fail fast if anything remains uninitialized or conflicted.
+        const st = await runCommand("git", ["submodule", "status", "--recursive"], { cwd: destKey });
+        const lines = String(st.stdout || "")
+          .split("\n")
+          .map((l) => l.trimEnd())
+          .filter(Boolean);
+        const bad = lines.filter((l) => l.startsWith("-") || l.startsWith("U"));
+        if (bad.length > 0) {
+          throw new UserError("Submodules not fully initialized in worktree.", {
+            details: `${bad.slice(0, 20).join("\n")}${bad.length > 20 ? "\n..." : ""}\n\nHint: run in the worktree:\n  git submodule update --init --recursive`,
+          });
+        }
+      }
     }
 
     if (options.enableHooks) {
       await hooksInstallCommand({ targetPath: gitRoot });
     }
 
+    await appendMetricsEvent(destKey, changeId, "change_start", {
+      mode: "worktree",
+      worktree: destKey,
+      branch,
+      from_branch: startFromBranch || "",
+      submodules: true,
+      hooks: options.enableHooks === true,
+    });
+
+    // Check Depends_On dependencies (worktree mode)
+    await checkDependenciesAndPrintHandoff(destKey, changeId, changeDir);
+
     console.log(`ok: change worktree ready: ${changeId}`);
     console.log(`worktree: ${destKey}`);
     console.log(`branch: ${branch}`);
@@ -1123,12 +1681,23 @@ export async function changeStartCommand(options) {
     await maybeRecordBaseBranch(changeDir, startFromBranch, branch);
   }
 
+  // Check Depends_On dependencies (non-worktree mode)
+  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",
+    worktree: gitRoot,
+    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:");
@@ -1269,6 +1838,8 @@ export async function changeFinishCommand(options) {
     throw new UserError("Failed to fast-forward merge change branch into target.", { details: `${merge.stderr || merge.stdout}${extra}` });
   }
 
+  await appendMetricsEvent(gitRoot, changeId, "finish", { into, from: changeBranch });
+
   console.log(`ok: finished change: ${changeId}`);
   console.log(`into: ${into}`);
   console.log(`from: ${changeBranch}`);
@@ -1289,15 +1860,34 @@ export async function changeStatusCommand(options) {
 
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "status" });
   const st = await computeChangeStatus(gitRoot, changeId);
+  const branch = await currentBranch(gitRoot);
+  /** @type {{ changeWorktree?: string, targetWorktree?: string }} */
+  const wtHint = {};
+  try {
+    const worktrees = await listGitWorktrees(gitRoot);
+    const changeRef = `refs/heads/change/${changeId}`;
+    const changeWt = worktrees.find((w) => String(w.branch || "") === changeRef);
+    if (changeWt?.worktree && path.resolve(changeWt.worktree) !== path.resolve(gitRoot)) wtHint.changeWorktree = changeWt.worktree;
+  } catch {
+    // best-effort; ignore
+  }
 
   console.log(`✓ aiws change status: ${st.changeId}`);
   console.log(`dir: ${st.dir}`);
+  console.log(`phase: ${st.phase}`);
+  console.log(`worktree: ${gitRoot}`);
+  console.log(`branch: ${branch || "(detached HEAD)"}`);
+  if (wtHint.changeWorktree) console.log(`note: change/<id> checked out in another worktree: ${wtHint.changeWorktree}`);
   console.log(`meta: ${st.metaState}`);
   if (st.reqId) console.log(`Req_ID: ${st.reqId}`);
   if (st.probId) console.log(`Problem_ID: ${st.probId}`);
   console.log(`tasks: ${st.tasks.done}/${st.tasks.total} (unchecked=${st.tasks.unchecked})`);
   console.log(`baseline: ${st.baselineLabel}${st.baselineAt ? ` (at=${st.baselineAt})` : ""}`);
   console.log(`drift: ${st.driftFiles.length > 0 ? st.driftFiles.join(", ") : "(none)"}`);
+  if (st.evidence?.counts) {
+    const c = st.evidence.counts;
+    console.log(`evidence: declared=${c.total} (exists=${c.exists}, missing=${c.missing}, persistent=${c.persistent}, tmp=${c.tmp})`);
+  }
 
   console.log("");
   console.log("Blockers (strict):");
@@ -1312,11 +1902,29 @@ export async function changeStatusCommand(options) {
   console.log("");
   console.log("Next (recommended):");
   console.log(`- ${planVerifyHint(st.changeId)}`);
-  if (st.blockersStrict.length === 0) {
-    console.log("- 质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）");
-  } else {
+  if (st.blockersStrict.length > 0) {
     console.log("- 先修复 Blockers (strict) 后复跑质量门，再进入 `$ws-dev`");
+    if (wtHint.changeWorktree) console.log(`- 若需要写代码：先切到 change worktree 再改动：\`cd ${wtHint.changeWorktree}\``);
+    return;
+  }
+
+  if (st.tasks.unchecked > 0) {
+    console.log("- 继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）");
+    console.log("- 提交/交付前强制门禁：`aiws validate .`（可选落盘：`aiws validate . --stamp`）");
+    console.log(`- （可选）状态快照：\`aiws change state ${st.changeId} --write\``);
+    return;
+  }
+
+  // deliver-ready hints
+  if (st.evidence?.counts && st.evidence.counts.persistent === 0) {
+    console.log("- 交付前建议生成持久证据：`changes/<id>/evidence/...`（并把路径回填到 proposal.md 的 Evidence_Path）");
   }
+  if (st.evidence?.missing && st.evidence.missing.length > 0) {
+    const show = st.evidence.missing.slice(0, 5);
+    console.log(`- 交付前建议补齐缺失证据文件（missing=${st.evidence.missing.length}）：${show.join(", ")}${st.evidence.missing.length > show.length ? ", ..." : ""}`);
+  }
+  console.log(`- （可选）状态快照：\`aiws change state ${st.changeId} --write\``);
+  console.log("- 进入交付：在 AI 工具中运行 `$ws-deliver`（submodule 感知提交 + 门禁 + 最终 `$ws-finish`）");
 }
 
 /**
@@ -1330,6 +1938,7 @@ export async function changeNextCommand(options) {
 
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "next" });
   assertValidChangeId(changeId);
+  const branch = await currentBranch(gitRoot);
 
   const changeDir = changeDirAbs(gitRoot, changeId);
   if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
@@ -1355,6 +1964,26 @@ export async function changeNextCommand(options) {
   /** @type {string[]} */
   const actions = [];
 
+  const inferred = inferChangeIdFromBranch(branch);
+  if (!branch) {
+    actions.push("当前为 detached HEAD：建议切到 `change/<change-id>` 分支后再继续（或显式传入 `<change-id>`）");
+  } else if (inferred && inferred !== changeId) {
+    actions.push(`当前分支为 \`${branch}\`（推断 change=${inferred}），但你在查看 change=${changeId}：建议先切换到 \`change/${changeId}\` 再执行开发/交付`);
+  } else if (!inferred) {
+    actions.push(`当前分支为 \`${branch}\`（非 change 分支）：建议 \`aiws change start ${changeId} --hooks --switch\` 或 \`git switch change/${changeId}\``);
+  }
+
+  try {
+    const worktrees = await listGitWorktrees(gitRoot);
+    const changeRef = `refs/heads/change/${changeId}`;
+    const changeWt = worktrees.find((w) => String(w.branch || "") === changeRef);
+    if (changeWt?.worktree && path.resolve(changeWt.worktree) !== path.resolve(gitRoot)) {
+      actions.push(`change/${changeId} 分支在另一个 worktree：\`cd ${changeWt.worktree}\`（建议在该目录执行开发/交付相关命令）`);
+    }
+  } catch {
+    // best-effort; ignore
+  }
+
   if (!meta) {
     actions.push(`补齐元信息并建立真值基线：\`aiws change sync ${changeId}\``);
   }
@@ -1382,6 +2011,33 @@ export async function changeNextCommand(options) {
     if (!(reqId || probId)) {
       actions.push("补齐归因：在 proposal.md 填写非空 `Req_ID` 或 `Problem_ID`（严格校验需要）");
     }
+
+    const contractRow = extractId("Contract_Row", proposal.text) || extractId("Contract_Row(s)", proposal.text);
+    if (!contractRow) actions.push("补齐绑定：在 proposal.md 填写非空 `Contract_Row`（严格校验需要）");
+
+    const planFile = extractId("Plan_File", proposal.text) || extractId("Plan file", proposal.text);
+    const planFiles = splitDeclaredValues(planFile);
+    if (planFiles.length !== 1) actions.push("补齐绑定：proposal.md `Plan_File` 必须且只能包含 1 个 plan 路径（严格校验需要）");
+    else {
+      const planRel = String(planFiles[0] || "").replace(/^\.\//, "");
+      if (path.isAbsolute(planRel)) actions.push("修正绑定：proposal.md `Plan_File` 必须是工作区相对路径（不要绝对路径）");
+      else if (!(await pathExists(path.join(gitRoot, planRel)))) actions.push(`补齐计划文件：缺少 ${planRel}（或修正 proposal.md 的 Plan_File）`);
+    }
+
+    const evidenceDecl = extractId("Evidence_Path", proposal.text) || extractId("Evidence_Path(s)", proposal.text);
+    const evidencePaths = splitDeclaredValues(evidenceDecl);
+    if (evidencePaths.length === 0) {
+      actions.push("补齐绑定：在 proposal.md 填写非空 `Evidence_Path`（严格校验需要；建议优先写 `changes/<id>/evidence/...`）");
+    } else {
+      const evidence = await analyzeEvidencePaths(gitRoot, changeId, evidencePaths);
+      if (evidence.counts.persistent === 0) {
+        actions.push("交付前建议生成持久证据：`changes/<id>/evidence/...`（并把路径回填到 Evidence_Path；`.agentdocs/tmp/...` 可作为原始证据引用）");
+      }
+      if (evidence.missing.length > 0) {
+        const show = evidence.missing.slice(0, 5);
+        actions.push(`补齐缺失证据文件（missing=${evidence.missing.length}）：${show.join(", ")}${evidence.missing.length > show.length ? ", ..." : ""}`);
+      }
+    }
   }
 
   const prog = tasks.state === "ok" ? checkboxStats(tasks.text) : { total: 0, done: 0, unchecked: 0, hasCheckboxes: false };
@@ -1400,15 +2056,487 @@ export async function changeNextCommand(options) {
   }
 
   console.log(`- ${planVerifyHint(changeId)}`);
-  console.log("- 若仍需继续编码，先通过质量门，再在 AI 工具中运行 `$ws-dev`");
-  console.log("- 生成交叉审计报告：在 AI 工具内运行 `/ws-review`（或按 AI_PROJECT.md 手工审计）");
+  if (prog.unchecked > 0) {
+    console.log("- 若仍需继续编码，先通过质量门，再在 AI 工具中运行 `$ws-dev`");
+  } else {
+    console.log("- 进入交付：在 AI 工具中运行 `$ws-deliver`（门禁 + submodule 感知提交 + 最终 `$ws-finish`）");
+    console.log("- 交付前门禁（推荐落盘）：`aiws validate . --stamp`");
+  }
+  console.log("- 审计与证据（推荐）：在 AI 工具内运行 `/ws-review`（或按 AI_PROJECT.md 手工审计）");
   console.log(`- 归档：\`aiws change archive ${changeId}\``);
 }
 
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ */
+async function computeChangeNextAdvice(gitRoot, changeId) {
+  const st = await computeChangeStatus(gitRoot, changeId);
+  const branch = await currentBranch(gitRoot);
+  const inferred = inferChangeIdFromBranch(branch);
+  const advice = {
+    changeId,
+    branch: branch || "",
+    inferredChangeId: inferred || "",
+    phase: st.phase,
+    blockersStrict: st.blockersStrict,
+    evidence: st.evidence?.counts || null,
+    actions: [],
+    prohibitions: [],
+    recommended: [],
+  };
+
+  if (!branch) {
+    advice.actions.push("当前为 detached HEAD：建议切到 `change/<change-id>` 分支后再继续（或显式传入 `<change-id>`）");
+  } else if (inferred && inferred !== changeId) {
+    advice.actions.push(`当前分支为 \`${branch}\`（推断 change=${inferred}），但你在查看 change=${changeId}：建议先切换到 \`change/${changeId}\` 再执行开发/交付`);
+  } else if (!inferred) {
+    advice.actions.push(`当前分支为 \`${branch}\`（非 change 分支）：建议 \`aiws change start ${changeId} --hooks --switch\` 或 \`git switch change/${changeId}\``);
+  }
+
+  try {
+    const worktrees = await listGitWorktrees(gitRoot);
+    const changeRef = `refs/heads/change/${changeId}`;
+    const changeWt = worktrees.find((w) => String(w.branch || "") === changeRef);
+    if (changeWt?.worktree && path.resolve(changeWt.worktree) !== path.resolve(gitRoot)) {
+      advice.actions.push(`change/${changeId} 分支在另一个 worktree：\`cd ${changeWt.worktree}\`（建议在该目录执行开发/交付相关命令）`);
+      advice.prohibitions.push("不要在当前 worktree 继续写代码（很可能不在 change 分支上）");
+    }
+  } catch {
+    // ignore
+  }
+
+  if (st.metaState !== "ok") advice.actions.push(`补齐元信息并建立真值基线：\`aiws change sync ${changeId}\``);
+  if (st.driftFiles.length > 0) {
+    advice.actions.push("真值/合同已变化：先对齐 `AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md` 与 proposal/tasks");
+    advice.actions.push(`确认后同步基线：\`aiws change sync ${changeId}\``);
+  }
+
+  if (st.blockersStrict.some((b) => b.includes("proposal.md") && b.includes("WS:TODO"))) {
+    advice.actions.push(`完善 proposal：\`$EDITOR ${path.join(changeDirAbs(gitRoot, changeId), "proposal.md")}\``);
+  }
+  if (st.blockersStrict.some((b) => b.includes("tasks.md") && b.includes("WS:TODO"))) {
+    advice.actions.push(`完善 tasks：\`$EDITOR ${path.join(changeDirAbs(gitRoot, changeId), "tasks.md")}\``);
+  }
+  if (st.blockersStrict.some((b) => b.includes("proposal.md missing attribution"))) {
+    advice.actions.push("补齐归因：在 proposal.md 填写非空 `Req_ID` 或 `Problem_ID`（严格校验需要）");
+  }
+  if (st.blockersStrict.some((b) => b.includes("missing Contract_Row"))) {
+    advice.actions.push("补齐绑定：在 proposal.md 填写非空 `Contract_Row`（严格校验需要）");
+  }
+  if (st.blockersStrict.some((b) => b.includes("Plan_File"))) {
+    advice.actions.push("补齐绑定：修正 proposal.md 的 `Plan_File`（严格校验需要；必须存在且仅 1 个）");
+  }
+  if (st.blockersStrict.some((b) => b.includes("missing Evidence_Path"))) {
+    advice.actions.push("补齐绑定：在 proposal.md 填写非空 `Evidence_Path`（严格校验需要；建议优先写 `changes/<id>/evidence/...`）");
+  }
+  if (st.tasks.unchecked > 0) advice.actions.push(`完成未勾选任务（${st.tasks.unchecked} 项）`);
+
+  if (st.blockersStrict.length > 0 && advice.actions.length === 0) {
+    advice.actions.push("先修复 Blockers (strict) 后复跑质量门，再进入 `$ws-dev`");
+  }
+
+  if (advice.actions.length === 0) {
+    if (st.tasks.unchecked > 0) {
+      advice.recommended.push("继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）");
+    } else {
+      advice.recommended.push("进入交付：在 AI 工具中运行 `$ws-deliver`（门禁 + submodule 感知提交 + 最终 `$ws-finish`）");
+      if (advice.evidence && advice.evidence.persistent === 0) {
+        advice.recommended.push("交付前建议生成持久证据并回填：`aiws change evidence <change-id>`");
+      }
+    }
+  }
+
+  return advice;
+}
+
+/**
+ * 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 st = await computeChangeStatus(gitRoot, changeId);
+  const advice = await computeChangeNextAdvice(gitRoot, changeId);
+
+  const now = nowIsoUtc();
+  /** @type {string[]} */
+  const lines = [];
+  lines.push(`# AIWS STATE: ${changeId}`);
+  lines.push("");
+  lines.push(`Generated: ${now}`);
+  lines.push("");
+  lines.push("## Context");
+  lines.push(`- Worktree: \`${gitRoot}\``);
+  lines.push(`- Branch: \`${advice.branch || "(detached)"}\``);
+  lines.push("");
+  lines.push("## Phase");
+  lines.push(`- Phase: \`${st.phase}\``);
+  lines.push(`- Tasks: ${st.tasks.done}/${st.tasks.total} (unchecked=${st.tasks.unchecked})`);
+  lines.push("");
+  lines.push("## Bindings");
+  if (st.reqId) lines.push(`- Req_ID: \`${st.reqId}\``);
+  if (st.probId) lines.push(`- Problem_ID: \`${st.probId}\``);
+  if (st.bindings?.contractRow) lines.push(`- Contract_Row: \`${st.bindings.contractRow}\``);
+  if (st.bindings?.planFile) lines.push(`- Plan_File: \`${st.bindings.planFile}\``);
+  lines.push("");
+  lines.push("## Evidence");
+  if (st.evidence?.counts) {
+    const c = st.evidence.counts;
+    lines.push(`- Declared: \`${c.total}\` (exists=\`${c.exists}\`, missing=\`${c.missing}\`, persistent=\`${c.persistent}\`, tmp=\`${c.tmp}\`)`);
+  } else {
+    lines.push("- (unknown)");
+  }
+  lines.push("");
+  lines.push("## Blockers (strict)");
+  if (st.blockersStrict.length === 0) lines.push("- (none)");
+  else for (const b of st.blockersStrict) lines.push(`- ${b}`);
+  lines.push("");
+  lines.push("## Next");
+  lines.push(`- ${planVerifyHint(changeId)}`);
+  for (const a of advice.actions) lines.push(`- ${a}`);
+  for (const r of advice.recommended) lines.push(`- ${r}`);
+  if (advice.prohibitions.length > 0) {
+    lines.push("");
+    lines.push("## Do Not");
+    for (const p of advice.prohibitions) lines.push(`- ${p}`);
+  }
+
+  const out = lines.join("\n") + "\n";
+  const dest = path.join(changeDirAbs(gitRoot, changeId), "STATE.md");
+  if (options.write === true) {
+    await writeText(dest, out);
+    await appendMetricsEvent(gitRoot, changeId, "state_written", { path: path.relative(gitRoot, dest) });
+    console.log(`ok: state written: ${path.relative(gitRoot, dest)}`);
+    return;
+  }
+  process.stdout.write(out);
+}
+
+/**
+ * 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 changesRoot = path.join(gitRoot, "changes");
+  if (!(await pathExists(changesRoot))) {
+    console.log("(no changes dir)");
+    return;
+  }
+
+  /** @type {Array<{ changeId: string, path: string, metrics: any }>} */
+  const all = [];
+  const scanDirs = [changesRoot, path.join(changesRoot, "archive")];
+  for (const base of scanDirs) {
+    if (!(await pathExists(base))) continue;
+    const entries = await fs.readdir(base, { withFileTypes: true });
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const dir = path.join(base, e.name);
+      const mAbs = path.join(dir, "metrics.json");
+      if (!(await pathExists(mAbs))) continue;
+      try {
+        const m = JSON.parse(await readText(mAbs));
+        const cid = String(m?.change_id || "").trim() || e.name;
+        all.push({ changeId: cid, path: path.relative(gitRoot, mAbs), metrics: m });
+      } catch {
+        // ignore invalid
+      }
+    }
+  }
+
+  if (all.length === 0) {
+    console.log("(no metrics.json found)");
+    return;
+  }
+
+  /** @type {Record<string, number>} */
+  const eventCounts = {};
+  let strictValidations = 0;
+  let strictPass = 0;
+  let evidenceRuns = 0;
+  let finishRuns = 0;
+  /** @type {number[]} */
+  const durations = [];
+
+  for (const row of all) {
+    const events = Array.isArray(row.metrics?.events) ? row.metrics.events : [];
+    const filtered = since
+      ? events.filter((ev) => {
+          const t = Date.parse(String(ev?.timestamp || ""));
+          return Number.isFinite(t) && t >= since;
+        })
+      : events;
+
+    for (const ev of filtered) {
+      const type = String(ev?.type || "unknown");
+      eventCounts[type] = (eventCounts[type] || 0) + 1;
+      if (type === "validate") {
+        const p = ev?.payload || {};
+        if (p.strict === true) {
+          strictValidations += 1;
+          if (p.ok === true) strictPass += 1;
+        }
+      }
+      if (type === "evidence") evidenceRuns += 1;
+      if (type === "finish") finishRuns += 1;
+    }
+
+    // Cycle time (best-effort): change_new -> finish
+    const tNew = events.find((e) => e?.type === "change_new")?.timestamp;
+    const tFin = events.find((e) => e?.type === "finish")?.timestamp;
+    if (tNew && tFin) {
+      const a = Date.parse(String(tNew));
+      const b = Date.parse(String(tFin));
+      if (Number.isFinite(a) && Number.isFinite(b) && b >= a) durations.push(Math.floor((b - a) / 1000));
+    }
+  }
+
+  const avgSec = durations.length > 0 ? Math.floor(durations.reduce((x, y) => x + y, 0) / durations.length) : 0;
+  const avgMin = avgSec ? Math.floor(avgSec / 60) : 0;
+
+  console.log(`AIWS Metrics Summary${sinceRaw ? ` (since ${sinceRaw})` : ""}`);
+  console.log("================================================");
+  console.log(`Total metric files: ${all.length}`);
+  console.log("");
+  console.log("Event counts:");
+  for (const k of Object.keys(eventCounts).sort()) console.log(`- ${k}: ${eventCounts[k]}`);
+  console.log("");
+  console.log("Quality:");
+  console.log(`- Strict validate pass rate: ${strictValidations > 0 ? `${strictPass}/${strictValidations}` : "(no data)"}`);
+  console.log(`- Evidence runs: ${evidenceRuns}`);
+  console.log(`- Finish runs: ${finishRuns}`);
+  console.log("");
+  console.log("Cycle time (best-effort):");
+  console.log(`- Avg change_new -> finish: ${durations.length > 0 ? `${avgMin} min` : "(no data)"}`);
+}
+
+/**
+ * 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 changeDir = changeDirAbs(gitRoot, changeId);
+  if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
+
+  const proposal = await fileState(changeDir, "proposal.md");
+  if (proposal.state !== "ok") throw new UserError("proposal.md is required for evidence generation.", { details: path.relative(gitRoot, proposal.abs) });
+
+  const planDecl = extractId("Plan_File", proposal.text) || extractId("Plan file", proposal.text);
+  const planFiles = splitDeclaredValues(planDecl).map((p) => String(p || "").replace(/^\.\//, ""));
+  const planRel = planFiles.length === 1 ? planFiles[0] : "";
+  const planAbs = planRel ? path.join(gitRoot, planRel) : "";
+  const planText = planAbs && (await pathExists(planAbs)) ? await readText(planAbs) : "";
+
+  const now = nowStampUtc();
+  const evidenceDir = path.join(changeDir, "evidence");
+  const reviewDir = path.join(changeDir, "review");
+  await ensureDir(evidenceDir);
+  await ensureDir(reviewDir);
+
+  /** @type {string[]} */
+  const created = [];
+
+  const branch = await currentBranch(gitRoot);
+
+  const status = await computeChangeStatus(gitRoot, changeId);
+  const statusOut = {
+    generated_at: nowIsoUtc(),
+    ws_root: gitRoot,
+    change_id: changeId,
+    branch: branch || "",
+    phase: status.phase,
+    tasks: status.tasks,
+    bindings: status.bindings,
+    truth: {
+      baseline: { label: status.baselineLabel, at: status.baselineAt },
+      drift_files: status.driftFiles,
+    },
+    evidence: status.evidence?.counts || null,
+    note: "aiws change evidence status snapshot; does not contain secrets.",
+  };
+  const statusPath = path.join(evidenceDir, `change-status-${now}.json`);
+  await writeText(statusPath, JSON.stringify(statusOut, null, 2) + "\n");
+  created.push(relFromRoot(gitRoot, statusPath));
+
+  /** @type {any | null} */
+  let validateRes = null;
+  let validateFailed = false;
+  /** @type {string} */
+  let validatePathForError = "";
+  if (!options.noValidate) {
+    validateRes = await validateChangeArtifacts(gitRoot, changeId, { strict: true, allowTruthDrift: false });
+    const validatePath = path.join(evidenceDir, `change-validate-strict-${now}.json`);
+    await writeText(validatePath, JSON.stringify(validateRes, null, 2) + "\n");
+    created.push(relFromRoot(gitRoot, validatePath));
+    validateFailed = validateRes.ok !== true;
+    validatePathForError = validatePath;
+  }
+
+  const validateStampDir = path.join(gitRoot, ".agentdocs", "tmp", "aiws-validate");
+  const latestValidateStamp = await findLatestFileByMtime(validateStampDir, (n) => n.endsWith(".json"));
+  if (latestValidateStamp) {
+    const dst = path.join(evidenceDir, `aiws-validate-stamp-${now}.json`);
+    await fs.copyFile(latestValidateStamp, dst);
+    created.push(relFromRoot(gitRoot, dst));
+  }
+
+  const syncStampDir = path.join(gitRoot, ".agentdocs", "tmp", "change-sync");
+  const latestSyncStamp = await findLatestFileByMtime(syncStampDir, (n) => n.endsWith(`-${changeId}.json`));
+  if (latestSyncStamp) {
+    const dst = path.join(evidenceDir, `change-sync-stamp-${now}.json`);
+    await fs.copyFile(latestSyncStamp, dst);
+    created.push(relFromRoot(gitRoot, dst));
+  }
+
+  const reviewAbs = path.join(reviewDir, "codex-review.md");
+  if (!(await pathExists(reviewAbs))) {
+    const tmpReview = path.join(gitRoot, ".agentdocs", "tmp", "review", "codex-review.md");
+    if (await pathExists(tmpReview)) {
+      await fs.copyFile(tmpReview, reviewAbs);
+    }
+  }
+  if (await pathExists(reviewAbs)) created.push(relFromRoot(gitRoot, reviewAbs));
+
+  // Collect all review files (support multiple reviewers)
+  if (await pathExists(reviewDir)) {
+    try {
+      const reviewEntries = await fs.readdir(reviewDir, { withFileTypes: true });
+      for (const e of reviewEntries) {
+        if (!e.isFile()) continue;
+        if (e.name === "codex-review.md") continue; // already added
+        if (e.name.endsWith(".md")) {
+          created.push(relFromRoot(gitRoot, path.join(reviewDir, e.name)));
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // Delivery summary (persistent, human-readable).
+  const summaryAbs = path.join(evidenceDir, `delivery-summary-${now}.md`);
+  /** @type {string[]} */
+  const summaryLines = [];
+  summaryLines.push(`# Delivery Summary: ${changeId}`);
+  summaryLines.push("");
+  summaryLines.push(`Generated: ${nowIsoUtc()}`);
+  summaryLines.push("");
+  summaryLines.push("## Context");
+  summaryLines.push(`- Worktree: \`${gitRoot}\``);
+  summaryLines.push(`- Branch: \`${branch || "(detached)"}\``);
+  summaryLines.push("");
+  summaryLines.push("## Status");
+  summaryLines.push(`- Phase: \`${status.phase}\``);
+  summaryLines.push(`- Tasks: ${status.tasks.done}/${status.tasks.total} (unchecked=${status.tasks.unchecked})`);
+  summaryLines.push(`- Truth drift: ${status.driftFiles.length > 0 ? status.driftFiles.join(", ") : "(none)"}`);
+  summaryLines.push("");
+  summaryLines.push("## Bindings");
+  if (status.reqId) summaryLines.push(`- Req_ID: \`${status.reqId}\``);
+  if (status.probId) summaryLines.push(`- Problem_ID: \`${status.probId}\``);
+  if (status.bindings?.contractRow) summaryLines.push(`- Contract_Row: \`${status.bindings.contractRow}\``);
+  if (status.bindings?.planFile) summaryLines.push(`- Plan_File: \`${status.bindings.planFile}\``);
+  summaryLines.push("");
+  summaryLines.push("## Evidence (Created/Collected)");
+  if (created.length === 0) summaryLines.push("- (none)");
+  else for (const p of created) summaryLines.push(`- \`${p}\``);
+  summaryLines.push("");
+  summaryLines.push("## Quality Gate");
+  if (options.noValidate) {
+    summaryLines.push("- Strict validation: (skipped via --no-validate)");
+  } else if (validateRes) {
+    summaryLines.push(`- Strict validation ok: \`${validateRes.ok === true}\``);
+    summaryLines.push(`- Errors: \`${Array.isArray(validateRes.errors) ? validateRes.errors.length : 0}\``);
+    summaryLines.push(`- Warnings: \`${Array.isArray(validateRes.warnings) ? validateRes.warnings.length : 0}\``);
+  } else {
+    summaryLines.push("- Strict validation: (unknown)");
+  }
+  summaryLines.push("");
+  summaryLines.push("## Next");
+  summaryLines.push(`- ${planVerifyHint(changeId)}`);
+  if (validateFailed) summaryLines.push("- Fix strict validation errors, then re-run `aiws change evidence`");
+  else summaryLines.push(`- Verify evidence gate: \`aiws change validate ${changeId} --strict --check-evidence\``);
+  await writeText(summaryAbs, summaryLines.join("\n") + "\n");
+  created.push(relFromRoot(gitRoot, summaryAbs));
+
+  const declaredEvidence = extractId("Evidence_Path", proposal.text) || extractId("Evidence_Path(s)", proposal.text);
+  const existingProposalEvidence = splitDeclaredValues(declaredEvidence).map((p) => String(p || "").replace(/^\.\//, ""));
+  const mergedEvidence = mergeDeclaredValues(existingProposalEvidence, created);
+  const mergedEvidenceText = formatDeclaredValues(mergedEvidence);
+
+  const updatedProposal = upsertProposalEvidencePath(proposal.text, mergedEvidenceText);
+  if (updatedProposal.changed) {
+    await writeText(path.join(changeDir, "proposal.md"), updatedProposal.text);
+  }
+
+  if (planAbs && planText) {
+    const existingPlanEvidence = splitDeclaredValues(extractId("Evidence_Path", planText) || extractId("Evidence_Path(s)", planText)).map((p) =>
+      String(p || "").replace(/^\.\//, ""),
+    );
+    const mergedPlanEvidence = mergeDeclaredValues(existingPlanEvidence, mergedEvidence);
+    const mergedPlanEvidenceText = formatDeclaredValues(mergedPlanEvidence);
+    const updatedPlan = upsertIdLine(planText, ["Evidence_Path", "Evidence_Path(s)"], mergedPlanEvidenceText, { insertAfterLabels: ["Plan_File", "Contract_Row"] });
+    if (updatedPlan.changed) await writeText(planAbs, updatedPlan.text);
+  }
+
+  await appendMetricsEvent(gitRoot, changeId, "evidence", {
+    generated_at: nowIsoUtc(),
+    created: created.length,
+    strict_validate: options.noValidate ? "skipped" : validateRes && validateRes.ok === true ? "ok" : "failed",
+    allow_fail: options.allowFail === true,
+  });
+
+  console.log(`✓ aiws change evidence: ${changeId}`);
+  console.log(`dir: ${path.relative(gitRoot, changeDir)}`);
+  if (planRel) console.log(`Plan_File: ${planRel}`);
+  if (created.length > 0) {
+    console.log("created:");
+    for (const p of created) console.log(`- ${p}`);
+  } else {
+    console.log("created:");
+    console.log("- (none)");
+  }
+  console.log("updated:");
+  console.log(`- ${path.relative(gitRoot, path.join(changeDir, "proposal.md"))} (Evidence_Path)`);
+  if (planRel && planText) console.log(`- ${planRel} (Evidence_Path)`);
+  console.log("");
+  console.log("next:");
+  console.log(`- ${planVerifyHint(changeId)}`);
+  if (validateFailed) console.log("- fix validation errors, then re-run evidence (or run with --allow-fail to proceed)");
+  else console.log(`- verify evidence gate: \`aiws change validate ${changeId} --strict --check-evidence\``);
+
+  if (validateFailed && !options.allowFail) {
+    const details = (validateRes && validateRes.raw ? String(validateRes.raw) : "").trim() || "Validation failed (see evidence JSON for details).";
+    const hint = validatePathForError ? `\n\nevidence:\n- ${path.relative(gitRoot, validatePathForError)}` : "";
+    throw new UserError("Failed to generate evidence due to strict validation errors.", { details: `${details}${hint}` });
+  }
+}
+
 /**
  * aiws change validate
  *
- * @param {{ changeId?: string, strict: boolean, allowTruthDrift: boolean }} options
+ * @param {{ changeId?: string, strict: boolean, allowTruthDrift: boolean, checkEvidence: boolean, checkScope: boolean }} options
  */
 export async function changeValidateCommand(options) {
   const gitRoot = await resolveGitRoot(process.cwd());
@@ -1420,6 +2548,18 @@ export async function changeValidateCommand(options) {
   const res = await validateChangeArtifacts(gitRoot, changeId, {
     strict: options.strict === true,
     allowTruthDrift: options.allowTruthDrift === true,
+    checkEvidence: options.checkEvidence === true,
+    checkScope: options.checkScope === true,
+  });
+  await appendMetricsEvent(gitRoot, changeId, "validate", {
+    ok: res.ok === true,
+    strict: options.strict === true,
+    allow_truth_drift: options.allowTruthDrift === true,
+    check_evidence: options.checkEvidence === true,
+    check_scope: options.checkScope === true,
+    errors: Array.isArray(res.errors) ? res.errors.length : 0,
+    warnings: Array.isArray(res.warnings) ? res.warnings.length : 0,
+    exit_code: res.exitCode,
   });
   if (res.raw) process.stderr.write(res.raw + "\n");
   if (!res.ok) throw new UserError("");
@@ -1513,6 +2653,12 @@ export async function changeSyncCommand(options) {
     note: "aiws change sync stamp; does not contain secrets.",
   };
   await writeText(stampPath, JSON.stringify(stamp, null, 2) + "\n");
+  await appendMetricsEvent(gitRoot, changeId, "truth_sync", {
+    synced_at: nowIso,
+    baseline_from: baselineLabel,
+    baseline_at: baselineAt,
+    changed_files: changed.map((c) => c.file),
+  });
 
   console.log(`✓ aiws change sync: ${changeId}`);
   console.log(`meta: ${path.relative(gitRoot, metaPath)}`);
@@ -1565,10 +2711,17 @@ export async function changeArchiveCommand(options) {
     dest = path.join(archiveRoot, `${prefix}-${changeId}-${nowStampUtc()}`);
   }
 
+  await appendMetricsEvent(gitRoot, changeId, "archive", { archived_to: path.relative(gitRoot, dest) });
   await fs.rename(changeDir, dest);
   console.log(`✓ aiws change archive: ${changeId}`);
   console.log(`archived_to: ${path.relative(gitRoot, dest)}`);
 
+  // Generate handoff.md
+  const handoffPath = path.join(dest, "handoff.md");
+  const handoffContent = await generateHandoffContent(gitRoot, dest, changeId);
+  await writeText(handoffPath, handoffContent);
+  console.log(`handoff: ${path.relative(gitRoot, handoffPath)}`);
+
   const metaPath = path.join(dest, ".ws-change.json");
   if (await pathExists(metaPath)) {
     try {