@aipper/aiws 0.0.24 → 0.0.26

package/src/commands/change-review-gates.js

@@ -0,0 +1,315 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { pathExists } from "../fs.js";
+import { loadWorkflowReviewGates } from "../spec.js";
+
+export const TMP_REVIEW_FALLBACKS = [
+  { fileName: "codex-review.md", persistentKind: "review" },
+  { fileName: "spec-review.md", persistentKind: "review" },
+  { fileName: "quality-review.md", persistentKind: "review" },
+  { fileName: "verify-before-complete.md", persistentKind: "evidence" },
+];
+
+/**
+ * @param {string} input
+ */
+function normalizeSlashes(input) {
+  return String(input || "").replaceAll("\\", "/");
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} absPath
+ */
+function relFromRoot(gitRoot, absPath) {
+  return normalizeSlashes(path.relative(gitRoot, absPath));
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} fileName
+ */
+export function tmpReviewFallbackPath(gitRoot, fileName) {
+  return path.join(gitRoot, ".agentdocs", "tmp", "review", fileName);
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {string} fileName
+ */
+function persistentReviewPath(gitRoot, changeId, fileName) {
+  return path.join(gitRoot, "changes", changeId, "review", fileName);
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {string} fileName
+ */
+function persistentEvidencePath(gitRoot, changeId, fileName) {
+  return path.join(gitRoot, "changes", changeId, "evidence", fileName);
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {string} gateId
+ */
+function reviewGateArtifactPaths(gitRoot, changeId, gateId) {
+  switch (gateId) {
+    case "spec_review":
+      return {
+        primaryAbs: persistentReviewPath(gitRoot, changeId, "spec-review.md"),
+        fallbackAbs: tmpReviewFallbackPath(gitRoot, "spec-review.md"),
+      };
+    case "quality_review":
+      return {
+        primaryAbs: persistentReviewPath(gitRoot, changeId, "quality-review.md"),
+        fallbackAbs: tmpReviewFallbackPath(gitRoot, "quality-review.md"),
+      };
+    case "verify_before_complete":
+      return {
+        primaryAbs: persistentEvidencePath(gitRoot, changeId, "verify-before-complete.md"),
+        fallbackAbs: tmpReviewFallbackPath(gitRoot, "verify-before-complete.md"),
+      };
+    default:
+      return null;
+  }
+}
+
+/**
+ * @param {string} absDir
+ * @param {(fileName: string) => boolean} predicate
+ */
+async function findLatestFileByMtime(absDir, predicate) {
+  /** @type {Array<{ abs: string, mtimeMs: number }>} */
+  const matches = [];
+  if (!(await pathExists(absDir))) return "";
+  try {
+    const entries = await fs.readdir(absDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!predicate(entry.name)) continue;
+      const abs = path.join(absDir, entry.name);
+      const st = await fs.stat(abs);
+      matches.push({ abs, mtimeMs: st.mtimeMs });
+    }
+  } catch {
+    return "";
+  }
+  matches.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return matches[0]?.abs || "";
+}
+
+/**
+ * @param {string} gitRoot
+ */
+async function listActiveChangeIds(gitRoot) {
+  const changesRoot = path.join(gitRoot, "changes");
+  try {
+    const entries = await fs.readdir(changesRoot, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .filter((name) => name && !name.startsWith(".") && name !== "archive" && name !== "templates")
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{ branchMatchesChange?: boolean }} [context]
+ */
+async function canAttributeTmpReviewFallback(gitRoot, changeId, context) {
+  if (context?.branchMatchesChange === true) return true;
+  const activeChangeIds = await listActiveChangeIds(gitRoot);
+  return activeChangeIds.length === 1 && activeChangeIds[0] === changeId;
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{ branchMatchesChange?: boolean }} [context]
+ * @param {{ counts?: { review?: number } }} [collaboration]
+ */
+export async function collectReviewSignals(gitRoot, changeId, context, collaboration) {
+  const persistentCount = Number(collaboration?.counts?.review || 0);
+  const tmpFallbackPaths = [];
+  const canAttributeTmpFallback = await canAttributeTmpReviewFallback(gitRoot, changeId, context);
+
+  for (const { fileName, persistentKind } of TMP_REVIEW_FALLBACKS) {
+    if (persistentKind !== "review") continue;
+    const tmpReviewPath = tmpReviewFallbackPath(gitRoot, fileName);
+    if (!(await pathExists(tmpReviewPath))) continue;
+    const persistentPath = persistentReviewPath(gitRoot, changeId, fileName);
+    if (await pathExists(persistentPath)) continue;
+    if (!canAttributeTmpFallback) continue;
+    tmpFallbackPaths.push(relFromRoot(gitRoot, tmpReviewPath));
+  }
+
+  const tmpFallbackExists = tmpFallbackPaths.length > 0;
+  const effectiveCount = persistentCount + tmpFallbackPaths.length;
+  let source = "none";
+  if (persistentCount > 0 && tmpFallbackExists) source = "persistent+tmp_fallback";
+  else if (persistentCount > 0) source = "persistent";
+  else if (tmpFallbackExists) source = "tmp_fallback";
+
+  return {
+    persistentCount,
+    tmpFallbackExists,
+    tmpFallbackCount: tmpFallbackPaths.length,
+    tmpFallbackPath: tmpFallbackPaths[0] || "",
+    tmpFallbackPaths,
+    effectiveCount,
+    source,
+  };
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{ branchMatchesChange?: boolean }} [context]
+ */
+export async function collectReviewGates(gitRoot, changeId, context) {
+  const spec = await loadWorkflowReviewGates();
+  const canAttributeTmpFallback = await canAttributeTmpReviewFallback(gitRoot, changeId, context);
+
+  /** @type {Array<any>} */
+  const gates = [];
+  for (const gate of spec.gates) {
+    const paths = reviewGateArtifactPaths(gitRoot, changeId, gate.id);
+    if (!paths) continue;
+    const primaryExists = await pathExists(paths.primaryAbs);
+    const fallbackExists = await pathExists(paths.fallbackAbs);
+    const primaryPath = relFromRoot(gitRoot, paths.primaryAbs);
+    const fallbackPath = relFromRoot(gitRoot, paths.fallbackAbs);
+
+    let ready = false;
+    let status = "missing";
+    let foundPath = "";
+    if (primaryExists) {
+      ready = true;
+      status = "persistent";
+      foundPath = primaryPath;
+    } else if (fallbackExists && canAttributeTmpFallback) {
+      ready = true;
+      status = "tmp_fallback";
+      foundPath = fallbackPath;
+    } else if (fallbackExists) {
+      ready = false;
+      status = "tmp_unattributed";
+      foundPath = fallbackPath;
+    }
+
+    gates.push({
+      id: gate.id,
+      name: gate.name,
+      stage: gate.stage,
+      focus: gate.focus,
+      next: gate.next,
+      ready,
+      status,
+      primaryPath,
+      fallbackPath,
+      foundPath,
+    });
+  }
+
+  const specReview = gates.find((gate) => gate.id === "spec_review") || null;
+  const qualityReview = gates.find((gate) => gate.id === "quality_review") || null;
+  const verifyBeforeComplete = gates.find((gate) => gate.id === "verify_before_complete") || null;
+  const validateStampDir = path.join(gitRoot, ".agentdocs", "tmp", "aiws-validate");
+  const latestValidateStamp = await findLatestFileByMtime(validateStampDir, (name) => name.endsWith(".json"));
+  const validateStamp = {
+    id: "validate_stamp",
+    name: "validate-stamp",
+    ready: Boolean(latestValidateStamp),
+    status: latestValidateStamp ? "latest" : "missing",
+    dir: relFromRoot(gitRoot, validateStampDir),
+    foundPath: latestValidateStamp ? relFromRoot(gitRoot, latestValidateStamp) : "",
+  };
+
+  const dualReviewMissingIds = [specReview, qualityReview].filter((gate) => !(gate && gate.ready)).map((gate) => gate?.id || "");
+  const finishGateMissingIds = [];
+  if (!specReview?.ready) finishGateMissingIds.push("spec_review");
+  if (!qualityReview?.ready) finishGateMissingIds.push("quality_review");
+  if (!validateStamp.ready) finishGateMissingIds.push("validate_stamp");
+  if (!verifyBeforeComplete?.ready) finishGateMissingIds.push("verify_before_complete");
+
+  return {
+    source: spec.source,
+    specVersion: spec.specVersion,
+    version: spec.version,
+    gates,
+    specReview,
+    qualityReview,
+    verifyBeforeComplete,
+    validateStamp,
+    summary: {
+      gateCount: gates.length,
+      gateReadyCount: gates.filter((gate) => gate.ready).length,
+      dualReviewReady: dualReviewMissingIds.length === 0,
+      dualReviewMissingIds,
+      dualReviewMissingCount: dualReviewMissingIds.length,
+      finishGateReady: finishGateMissingIds.length === 0,
+      finishGateMissingIds,
+      finishGateMissingCount: finishGateMissingIds.length,
+    },
+  };
+}
+
+/**
+ * @param {string} changeId
+ * @param {any} reviewGates
+ */
+export function collectFinishGateErrors(changeId, reviewGates) {
+  const summary = reviewGates?.summary && typeof reviewGates.summary === "object" ? reviewGates.summary : {};
+  const missingIds = Array.isArray(summary.finishGateMissingIds) ? summary.finishGateMissingIds : [];
+  if (missingIds.length === 0) return [];
+
+  /** @type {string[]} */
+  const errors = [];
+  for (const missingId of missingIds) {
+    if (missingId === "spec_review") {
+      const gate = reviewGates?.specReview || {};
+      if (gate.status === "tmp_unattributed") {
+        errors.push(`finish gate has unattributed tmp spec review (persist it to changes/${changeId}/review/spec-review.md or rerun in the owning change context)`);
+      } else {
+        errors.push(`finish gate missing spec review (run \`$ws-spec-review\` or write changes/${changeId}/review/spec-review.md)`);
+      }
+      continue;
+    }
+    if (missingId === "quality_review") {
+      const gate = reviewGates?.qualityReview || {};
+      if (gate.status === "tmp_unattributed") {
+        errors.push(`finish gate has unattributed tmp quality review (persist it to changes/${changeId}/review/quality-review.md or rerun in the owning change context)`);
+      } else {
+        errors.push(`finish gate missing quality review (run \`$ws-quality-review\` or write changes/${changeId}/review/quality-review.md)`);
+      }
+      continue;
+    }
+    if (missingId === "validate_stamp") {
+      errors.push("finish gate missing validate stamp (run `aiws validate . --stamp`)");
+      continue;
+    }
+    if (missingId === "verify_before_complete") {
+      const gate = reviewGates?.verifyBeforeComplete || {};
+      if (gate.status === "tmp_unattributed") {
+        errors.push(
+          `finish gate has unattributed tmp verify-before-complete evidence (persist it to changes/${changeId}/evidence/verify-before-complete.md or rerun in the owning change context)`,
+        );
+      } else {
+        errors.push(
+          `finish gate missing verify-before-complete evidence (run \`$ws-verify-before-complete\` or write changes/${changeId}/evidence/verify-before-complete.md)`,
+        );
+      }
+      continue;
+    }
+    errors.push(`finish gate missing required artifact: ${missingId}`);
+  }
+  return errors;
+}

package/src/commands/change-scope-gate.js

@@ -0,0 +1,34 @@
+/**
+ * @param {any} lifecycle
+ */
+export function computeScopeGate(lifecycle) {
+  const runs = Number(lifecycle?.strictScopeValidateRuns || 0);
+  const pass = lifecycle?.strictScopeValidatePass === true;
+  return {
+    checked: runs > 0,
+    ready: runs > 0 && pass,
+    status: runs === 0 ? "not_run" : pass ? "passed" : "failed",
+    source: runs > 0 ? "metrics.validate.check_scope" : "",
+    lastRunAt: String(lifecycle?.strictScopeValidateAt || ""),
+    errors: Number(lifecycle?.strictScopeValidateErrors || 0),
+    warnings: Number(lifecycle?.strictScopeValidateWarnings || 0),
+  };
+}
+
+/**
+ * @param {string} changeId
+ */
+export function scopeGateFailureAction(changeId) {
+  return `scope gate 未通过：更新 plan 的 \`## Scope\` / \`### In Scope\` 或收敛改动后复跑 \`aiws change validate ${changeId} --strict --check-scope\``;
+}
+
+/**
+ * @param {string} changeId
+ */
+export function scopeGatePendingRecommendation(changeId) {
+  return `范围门禁：\`aiws change validate ${changeId} --strict --check-scope\``;
+}
+
+export function scopeGatePassedRecommendation() {
+  return "范围门禁：最近一次 `--check-scope` 已通过";
+}

package/src/commands/change-start.js

@@ -0,0 +1,138 @@
+import path from "node:path";
+
+/**
+ * @param {string} gitRoot
+ * @param {{
+ *   hasHeadCommit: (gitRoot: string) => Promise<boolean>,
+ *   runCommand: typeof import("../exec.js").runCommand
+ * }} deps
+ * @returns {Promise<{ ok: true } | { ok: false, reason: "no_commit" | "missing_truth", missing?: string[] }>}
+ */
+export async function checkWorktreePrereqs(gitRoot, deps) {
+  if (!(await deps.hasHeadCommit(gitRoot))) return { ok: false, reason: "no_commit" };
+  /** @type {string[]} */
+  const missingInHead = [];
+  for (const rel of ["AI_PROJECT.md", "AI_WORKSPACE.md", "REQUIREMENTS.md"]) {
+    const ok = await deps.runCommand("git", ["cat-file", "-e", `HEAD:${rel}`], { cwd: gitRoot }).then((result) => result.code === 0);
+    if (!ok) missingInHead.push(rel);
+  }
+  if (missingInHead.length > 0) return { ok: false, reason: "missing_truth", missing: missingInHead };
+  return { ok: true };
+}
+
+/**
+ * @param {{ stdout: string, stderr: string }} res
+ */
+export function outputMentionsRecurseSubmodules(res) {
+  const out = `${res.stderr || ""}\n${res.stdout || ""}`;
+  return out.includes("recurse-submodules");
+}
+
+/**
+ * @param {string} changeDir
+ * @param {string} baseBranch
+ * @param {string} changeBranch
+ * @param {{
+ *   nowIsoUtc: () => string,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   readText: (path: string) => Promise<string>,
+ *   writeText: (path: string, content: string) => Promise<void>
+ * }} deps
+ */
+export async function maybeRecordBaseBranch(changeDir, baseBranch, changeBranch, deps) {
+  const base = String(baseBranch || "").trim();
+  if (!base) return;
+  if (base === String(changeBranch || "").trim()) return;
+  const metaPath = path.join(changeDir, ".ws-change.json");
+  if (!(await deps.pathExists(metaPath))) return;
+  /** @type {any} */
+  let meta = null;
+  try {
+    meta = JSON.parse(await deps.readText(metaPath));
+  } catch {
+    meta = null;
+  }
+  if (!meta || typeof meta !== "object") return;
+  const current = String(meta.base_branch || "").trim();
+  if (current) return;
+  meta.base_branch = base;
+  meta.base_branch_set_at = deps.nowIsoUtc();
+  await deps.writeText(metaPath, JSON.stringify(meta, null, 2) + "\n");
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string | undefined} worktreeDir
+ * @param {string} changeId
+ */
+export function resolveDefaultWorktreeDir(gitRoot, worktreeDir, changeId) {
+  const parent = path.dirname(gitRoot);
+  const raw = String(worktreeDir || "").trim();
+  if (raw) {
+    return path.isAbsolute(raw) ? raw : path.resolve(parent, raw);
+  }
+  const repoName = path.basename(gitRoot);
+  return path.resolve(parent, `${repoName}-${changeId}`);
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {{ branch: string, hasBranch: boolean, hasGitmodules: boolean }} options
+ * @param {{
+ *   runCommand: typeof import("../exec.js").runCommand,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function switchOrCreateStartBranch(gitRoot, options, deps) {
+  if (options.hasBranch) {
+    let sw = await deps.runCommand("git", ["switch", ...(options.hasGitmodules ? ["--recurse-submodules"] : []), options.branch], { cwd: gitRoot });
+    if (sw.code !== 0 && options.hasGitmodules && outputMentionsRecurseSubmodules(sw)) {
+      console.error("warn: git switch does not support --recurse-submodules; switching without it (submodules may be out of sync).");
+      sw = await deps.runCommand("git", ["switch", options.branch], { cwd: gitRoot });
+    }
+    if (sw.code === 0) return;
+
+    let co = await deps.runCommand("git", ["checkout", ...(options.hasGitmodules ? ["--recurse-submodules"] : []), options.branch], { cwd: gitRoot });
+    if (co.code !== 0 && options.hasGitmodules && outputMentionsRecurseSubmodules(co)) {
+      console.error("warn: git checkout does not support --recurse-submodules; checking out without it (submodules may be out of sync).");
+      co = await deps.runCommand("git", ["checkout", options.branch], { cwd: gitRoot });
+    }
+    if (co.code !== 0) throw new deps.UserError("Failed to switch branch.", { details: co.stderr || co.stdout });
+    return;
+  }
+
+  let sw = await deps.runCommand("git", ["switch", ...(options.hasGitmodules ? ["--recurse-submodules"] : []), "-c", options.branch], { cwd: gitRoot });
+  if (sw.code !== 0 && options.hasGitmodules && outputMentionsRecurseSubmodules(sw)) {
+    console.error("warn: git switch does not support --recurse-submodules; switching without it (submodules may be out of sync).");
+    sw = await deps.runCommand("git", ["switch", "-c", options.branch], { cwd: gitRoot });
+  }
+  if (sw.code === 0) return;
+
+  let co = await deps.runCommand("git", ["checkout", ...(options.hasGitmodules ? ["--recurse-submodules"] : []), "-b", options.branch], { cwd: gitRoot });
+  if (co.code !== 0 && options.hasGitmodules && outputMentionsRecurseSubmodules(co)) {
+    console.error("warn: git checkout does not support --recurse-submodules; checking out without it (submodules may be out of sync).");
+    co = await deps.runCommand("git", ["checkout", "-b", options.branch], { cwd: gitRoot });
+  }
+  if (co.code !== 0) throw new deps.UserError("Failed to create branch.", { details: co.stderr || co.stdout });
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {{ branch: string, hasBranch: boolean, headReady: boolean }} options
+ * @param {{
+ *   runCommand: typeof import("../exec.js").runCommand,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function prepareNoSwitchBranch(gitRoot, options, deps) {
+  if (options.hasBranch) return true;
+  if (!options.headReady) {
+    console.error(`warn: repo has no commits; cannot create branch "${options.branch}" without switching (skipped)`);
+    return false;
+  }
+  const branchResult = await deps.runCommand("git", ["branch", options.branch], { cwd: gitRoot });
+  if (branchResult.code !== 0) {
+    throw new deps.UserError("Failed to create branch.", { details: branchResult.stderr || branchResult.stdout });
+  }
+  return true;
+}

package/src/commands/change-state-command.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   changeId: string,
+ *   options: { write: boolean }
+ * }} input
+ * @param {{
+ *   appendMetricsEvent: (gitRoot: string, changeId: string, type: string, payload: any) => Promise<void>,
+ *   changeDirAbs: (gitRoot: string, changeId: string) => string,
+ *   computeChangeNextAdvice: (gitRoot: string, changeId: string) => Promise<any>,
+ *   computeChangeStatus: (gitRoot: string, changeId: string) => Promise<any>,
+ *   nowIsoUtc: () => string,
+ *   planVerifyHint: (changeId: string) => string,
+ *   renderChangeStateMarkdown: (input: any) => string,
+ *   writeText: (path: string, content: string) => Promise<void>
+ * }} deps
+ */
+export async function runChangeStateCommand(input, deps) {
+  const { gitRoot, changeId, options } = input;
+  const status = await deps.computeChangeStatus(gitRoot, changeId);
+  const advice = await deps.computeChangeNextAdvice(gitRoot, changeId);
+
+  const output = deps.renderChangeStateMarkdown({
+    changeId,
+    gitRoot,
+    now: deps.nowIsoUtc(),
+    status,
+    advice,
+    planVerifyLine: deps.planVerifyHint(changeId),
+  });
+  const dest = path.join(deps.changeDirAbs(gitRoot, changeId), "STATE.md");
+  if (options.write === true) {
+    await deps.writeText(dest, output);
+    await deps.appendMetricsEvent(gitRoot, changeId, "state_written", { path: path.relative(gitRoot, dest) });
+    return { output: `ok: state written: ${path.relative(gitRoot, dest)}\n` };
+  }
+  return { output };
+}

package/src/commands/change-status-command.js

@@ -0,0 +1,126 @@
+import path from "node:path";
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   branch: string,
+ *   changeWorktreeHint: string,
+ *   status: any
+ * }} input
+ * @param {{
+ *   effectiveReviewCount: (status: any) => number,
+ *   governanceGuidanceLines: (status: any) => Promise<string[]>,
+ *   planVerifyHint: (changeId: string) => string
+ * }} deps
+ */
+export async function renderChangeStatusOutput(input, deps) {
+  const { gitRoot, branch, changeWorktreeHint, status } = input;
+  /** @type {string[]} */
+  const lines = [];
+
+  lines.push(`✓ aiws change status: ${status.changeId}`);
+  lines.push(`dir: ${status.dir}`);
+  lines.push(`phase: ${status.phase}`);
+  lines.push(`worktree: ${gitRoot}`);
+  lines.push(`branch: ${branch || "(detached HEAD)"}`);
+  if (changeWorktreeHint) lines.push(`note: change/<id> checked out in another worktree: ${changeWorktreeHint}`);
+  if (status.context?.worktree && path.resolve(status.context.worktree) !== path.resolve(gitRoot)) {
+    lines.push(`status_context: ${status.context.worktree}`);
+    lines.push(`status_branch: ${status.context.branch || "(detached HEAD)"}`);
+  }
+  if (status.context?.warning) lines.push(`warning: ${status.context.warning}`);
+  lines.push(`meta: ${status.metaState}`);
+  if (status.reqId) lines.push(`Req_ID: ${status.reqId}`);
+  if (status.probId) lines.push(`Problem_ID: ${status.probId}`);
+  lines.push(`tasks: ${status.tasks.done}/${status.tasks.total} (unchecked=${status.tasks.unchecked})`);
+  if (status.reviewSignals) {
+    lines.push(`review_signal: effective=${status.reviewSignals.effectiveCount} source=${status.reviewSignals.source}`);
+  }
+  if (status.reviewGates?.summary) {
+    const summary = status.reviewGates.summary;
+    const missing = summary.finishGateMissingIds.length > 0 ? summary.finishGateMissingIds.join(", ") : "(none)";
+    lines.push(`review_gates: dual_ready=${summary.dualReviewReady} finish_ready=${summary.finishGateReady} missing=${missing}`);
+    for (const gate of status.reviewGates.gates || []) {
+      lines.push(`review_gate:${gate.id} ready=${gate.ready} status=${gate.status}${gate.foundPath ? ` path=${gate.foundPath}` : ""}`);
+    }
+    if (status.reviewGates.validateStamp) {
+      const validateStamp = status.reviewGates.validateStamp;
+      lines.push(
+        `review_gate:${validateStamp.id} ready=${validateStamp.ready} status=${validateStamp.status}${validateStamp.foundPath ? ` path=${validateStamp.foundPath}` : ""}`,
+      );
+    }
+  }
+  if (status.scopeGate) {
+    lines.push(
+      `scope_gate: status=${status.scopeGate.status} ready=${status.scopeGate.ready} checked=${status.scopeGate.checked} errors=${status.scopeGate.errors} warnings=${status.scopeGate.warnings}${status.scopeGate.lastRunAt ? ` at=${status.scopeGate.lastRunAt}` : ""}`,
+    );
+  }
+  if (status.git) {
+    lines.push(
+      `git: clean=${status.git.clean} staged=${status.git.staged} unstaged=${status.git.unstaged} untracked=${status.git.untracked} conflicted=${status.git.conflicted}`,
+    );
+  }
+  if (status.governance) {
+    lines.push(`governance: current=${status.governance.currentStage} next=${status.governance.recommendedStage}`);
+    if (status.governance.rationale) lines.push(`governance_reason: ${status.governance.rationale}`);
+    if (status.governance.ruleId) lines.push(`governance_rule: ${status.governance.ruleId}`);
+    if (status.governance.source) lines.push(`governance_source: ${status.governance.source}`);
+  }
+  lines.push(`baseline: ${status.baselineLabel}${status.baselineAt ? ` (at=${status.baselineAt})` : ""}`);
+  lines.push(`drift: ${status.driftFiles.length > 0 ? status.driftFiles.join(", ") : "(none)"}`);
+  if (status.evidence?.counts) {
+    const counts = status.evidence.counts;
+    lines.push(`evidence: declared=${counts.total} (exists=${counts.exists}, missing=${counts.missing}, persistent=${counts.persistent}, tmp=${counts.tmp})`);
+  }
+  if (status.collaboration?.counts) {
+    const counts = status.collaboration.counts;
+    lines.push(`collaboration: analysis=${counts.analysis}, patches=${counts.patches}, review=${counts.review}, evidence_dir=${counts.evidence}`);
+  }
+
+  lines.push("");
+  lines.push("Blockers (strict):");
+  if (status.blockersStrict.length === 0) lines.push("- (none)");
+  else for (const blocker of status.blockersStrict) lines.push(`- ${blocker}`);
+
+  lines.push("");
+  lines.push("Blockers (archive):");
+  if (status.blockersArchive.length === 0) lines.push("- (none)");
+  else for (const blocker of status.blockersArchive) lines.push(`- ${blocker}`);
+
+  lines.push("");
+  lines.push("Next (recommended):");
+  lines.push(`- ${deps.planVerifyHint(status.changeId)}`);
+  if (status.blockersStrict.length > 0) {
+    lines.push("- 先修复 Blockers (strict) 后复跑质量门，再进入编码：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`");
+    if (changeWorktreeHint) lines.push(`- 若需要写代码：先切到 change worktree 再改动：\`cd ${changeWorktreeHint}\``);
+    return lines.join("\n") + "\n";
+  }
+
+  if (status.tasks.unchecked > 0) {
+    lines.push("- 继续开发：simple/local 单点修复优先 `$ws-dev-lite`；否则 `$ws-dev`（小步实现 + 可复现验证）");
+    if ((status.collaboration?.counts?.analysis || 0) > 0) lines.push("- 已有委托分析：在编码前先收敛 `changes/<id>/analysis/` 中的结论");
+    if ((status.collaboration?.counts?.patches || 0) > 0) lines.push("- 已有 patch 草案：应用前先人工审查 `changes/<id>/patches/`");
+    lines.push("- 提交/交付前强制门禁：`aiws validate .`（可选落盘：`aiws validate . --stamp`）");
+    lines.push(`- （可选）状态快照：\`aiws change state ${status.changeId} --write\``);
+    return lines.join("\n") + "\n";
+  }
+
+  if (status.evidence?.counts && status.evidence.counts.persistent === 0) {
+    lines.push("- 交付前建议生成持久证据：`changes/<id>/evidence/...`（并把路径回填到 proposal.md 的 Evidence_Path）");
+  }
+  if (status.evidence?.missing && status.evidence.missing.length > 0) {
+    const show = status.evidence.missing.slice(0, 5);
+    lines.push(`- 交付前建议补齐缺失证据文件（missing=${status.evidence.missing.length}）：${show.join(", ")}${status.evidence.missing.length > show.length ? ", ..." : ""}`);
+  }
+  if ((status.collaboration?.counts?.patches || 0) > 0) {
+    lines.push("- 存在委托 patch 草案：交付前确认其已被人工审查，并在 review/handoff 中记录结论");
+  }
+  if ((status.collaboration?.counts?.analysis || 0) > 0 && deps.effectiveReviewCount(status) === 0) {
+    lines.push("- 存在委托分析但尚无 review 汇总：建议先在 `changes/<id>/review/` 形成结论后再交付");
+  }
+  lines.push(`- （可选）状态快照：\`aiws change state ${status.changeId} --write\``);
+  for (const line of await deps.governanceGuidanceLines(status)) lines.push(`- ${line}`);
+  if (status.governance?.rationale) lines.push(`- 阶段判定：${status.governance.rationale}`);
+  if (status.governance?.warning) lines.push(`- 注意：${status.governance.warning}`);
+  return lines.join("\n") + "\n";
+}