@aipper/aiws 0.0.27 → 0.0.29

package/src/commands/change.js

@@ -26,23 +26,12 @@ import { runChangeValidateCommand } from "./change-validate-entry.js";
 import {
   computeChangeNextAdvice as computeChangeNextAdviceModel,
   renderChangeStateMarkdown,
-  resolveChangeWorktreeHint,
 } from "./change-advice.js";
 import {
-  cleanupWorktreePath,
   isGitRepository,
   listSubmodulesFromGitmodules,
-  pushSubmodulesForFinish,
   resolveFinishContext,
-  resolvePushTarget,
 } from "./change-finish.js";
-import {
-  checkWorktreePrereqs,
-  maybeRecordBaseBranch,
-  prepareNoSwitchBranch,
-  resolveDefaultWorktreeDir,
-  switchOrCreateStartBranch,
-} from "./change-start.js";
 import {
   collectFinishGateErrors,
   collectReviewGates,
@@ -50,9 +39,6 @@ import {
 } from "./change-review-gates.js";
 import {
   computeScopeGate,
-  scopeGateFailureAction,
-  scopeGatePassedRecommendation,
-  scopeGatePendingRecommendation,
 } from "./change-scope-gate.js";
 import {
   readChangeMetrics,
@@ -62,10 +48,176 @@ import {
 } from "./change-status-context.js";
 import { renderChangeStatusOutput } from "./change-status-command.js";
 import { validateChangeArtifacts as validateChangeArtifactsModel } from "./change-validate.js";
-import { hooksInstallCommand } from "./hooks-install.js";
+
+/**
+ * @param {string} text
+ */
+function countWsTodo(text) {
+  return (text.match(/WS:TODO/g) || []).length;
+}
+
+/**
+ * @param {string} text
+ */
+function countPlaceholders(text) {
+  return (text.match(/{{CHANGE_ID}}|{{TITLE}}|{{CREATED_AT}}/g) || []).length;
+}
+
+/**
+ * @param {string} changeDir
+ * @param {string} rel
+ */
+async function fileState(changeDir, rel) {
+  const abs = path.join(changeDir, rel);
+  if (!(await pathExists(abs))) return { state: "missing", wsTodo: 0, placeholders: 0, abs, text: "" };
+  const st = await fs.stat(abs);
+  if (st.size === 0) return { state: "empty", wsTodo: 0, placeholders: 0, abs, text: "" };
+  const text = await readText(abs);
+  return { state: "ok", wsTodo: countWsTodo(text), placeholders: countPlaceholders(text), abs, text };
+}
+
+/**
+ * Append a change lifecycle event into changes/<id>/metrics.json.
+ *
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {string} type
+ * @param {any} payload
+ */
+async function appendMetricsEventAtDir(changeDir, changeId, type, payload) {
+  const metricsAbs = path.join(changeDir, "metrics.json");
+  /** @type {{ version: number, change_id: string, events: any[], updated_at?: string } | null} */
+  let cur = null;
+  if (await pathExists(metricsAbs)) {
+    try {
+      cur = JSON.parse(await readText(metricsAbs));
+    } catch {
+      cur = null;
+    }
+  }
+  if (!cur || typeof cur !== "object") {
+    cur = { version: 1, change_id: changeId, events: [] };
+  }
+  if (!Array.isArray(cur.events)) cur.events = [];
+  cur.events.push({ type, timestamp: nowIsoUtc(), payload: payload ?? null });
+  cur.events = cur.events.slice(-200);
+  cur.updated_at = nowIsoUtc();
+  await writeText(metricsAbs, JSON.stringify(cur, null, 2) + "\n");
+}
+
+async function appendMetricsEvent(gitRoot, changeId, type, payload) {
+  const changeDir = changeDirAbs(gitRoot, changeId);
+  await appendMetricsEventAtDir(changeDir, changeId, type, payload);
+}
+
+/**
+ * @param {string} gitRoot
+ */
+async function resolveTemplateIdForRepo(gitRoot) {
+  const manifestPath = path.join(gitRoot, ".aiws", "manifest.json");
+  if (!(await pathExists(manifestPath))) return "workspace";
+  try {
+    const stored = JSON.parse(await readText(manifestPath));
+    const templateId = String(stored.template_id || "").trim();
+    return templateId || "workspace";
+  } catch {
+    return "workspace";
+  }
+}
+
+/**
+ * @param {string} gitRoot
+ * @returns {Promise<{ templateDir: string, resolvedFrom: string }>}
+ */
+async function resolveChangeTemplatesDir(gitRoot) {
+  const candidates = [
+    { dir: path.join(gitRoot, "changes", "templates"), label: `${gitRoot}/changes/templates` },
+    { dir: path.join(gitRoot, "workflow", "changes", "templates"), label: `${gitRoot}/workflow/changes/templates` },
+  ];
+
+  for (const c of candidates) {
+    if (!(await pathExists(path.join(c.dir, "proposal.md")))) continue;
+    if (!(await pathExists(path.join(c.dir, "tasks.md")))) continue;
+    return { templateDir: c.dir, resolvedFrom: c.label };
+  }
+
+  const templateId = await resolveTemplateIdForRepo(gitRoot);
+  const tpl = await loadTemplate(templateId);
+  const fallback = path.join(tpl.templateDir, "changes", "templates");
+
+  if (!(await pathExists(path.join(fallback, "proposal.md"))) || !(await pathExists(path.join(fallback, "tasks.md")))) {
+    throw new UserError("Missing change templates.", { details: `Expected proposal.md and tasks.md under: ${fallback}` });
+  }
+  return { templateDir: fallback, resolvedFrom: `@aipper/aiws-spec:${tpl.templateId}` };
+}
+
+/**
+ * @param {string} templateText
+ * @param {{ changeId: string, title: string, createdAt: string }} vars
+ */
+function renderTemplate(templateText, vars) {
+  return templateText.replaceAll("{{CHANGE_ID}}", vars.changeId).replaceAll("{{TITLE}}", vars.title).replaceAll("{{CREATED_AT}}", vars.createdAt);
+}
+
+/**
+ * @param {string} gitRoot
+ * @returns {Promise<{ path: string, args: string[] }>}
+ */
+async function resolveWsChangeChecker(gitRoot) {
+  const local = path.join(gitRoot, "tools", "ws_change_check.py");
+  if (await pathExists(local)) return { path: local, args: [local] };
+
+  const templateId = await resolveTemplateIdForRepo(gitRoot);
+  const tpl = await loadTemplate(templateId);
+  const fallback = path.join(tpl.templateDir, "tools", "ws_change_check.py");
+  if (!(await pathExists(fallback))) {
+    throw new UserError("Missing ws_change_check.py.", { details: "Hint: run `aiws init .` to install tools/ws_change_check.py in your repo." });
+  }
+  return { path: fallback, args: [fallback] };
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string[]} args
+ */
+async function runPython(gitRoot, args) {
+  let res;
+  try {
+    res = await runCommand("python3", args, { cwd: gitRoot });
+  } catch (e) {
+    throw new UserError("python3 is required.", { details: e instanceof Error ? e.message : String(e) });
+  }
+  return res;
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string | undefined} changeId
+ * @param {{ command: string, allowFinishedUnarchived?: boolean }} options
+ */
+async function resolveChangeId(gitRoot, changeId, options) {
+  const resolved = changeId || inferChangeIdFromBranch(await currentBranch(gitRoot));
+  if (resolved) {
+    const terminated = await detectTerminatedChange(gitRoot, resolved);
+    if (!isTerminatedAllowed(options.command, terminated, { allowFinishedUnarchived: options.allowFinishedUnarchived === true })) {
+      throw terminatedChangeError(gitRoot, resolved, terminated, `aiws change ${options.command}`);
+    }
+    return resolved;
+  }
+  throw new UserError(`usage: aiws change ${options.command} <change-id> (or switch to branch change/<change-id>)`);
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ */
+function changeDirAbs(gitRoot, changeId) {
+  return path.join(gitRoot, "changes", changeId);
+}
 
 const CHANGE_BRANCH_RE = /^(change|changes|ws|ws-change)\/([a-z0-9]+(?:-[a-z0-9]+)*)$/;
 const CHANGE_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
 /**
  * @param {string} changeId
  */
@@ -162,53 +314,8 @@ async function checkGitClean(gitRoot) {
   return { clean: false, details: truncated };
 }
 
-/**
- * @param {string} gitRoot
- * @returns {Promise<Array<{ worktree: string, head: string, branch: string, locked: boolean, lockReason: string }>>}
- */
-async function listGitWorktrees(gitRoot) {
-  const res = await runCommand("git", ["worktree", "list", "--porcelain"], { cwd: gitRoot });
-  if (res.code !== 0) {
-    throw new UserError("Failed to list git worktrees.", { details: res.stderr || res.stdout });
-  }
-  const lines = String(res.stdout || "")
-    .split(/\r?\n/)
-    .map((l) => l.trimEnd());
-
-  /** @type {Array<{ worktree: string, head: string, branch: string, locked: boolean, lockReason: string }>} */
-  const out = [];
-  /** @type {{ worktree: string, head: string, branch: string, locked: boolean, lockReason: string } | null} */
-  let cur = null;
-
-  for (const line of lines) {
-    if (!line) continue;
-    if (line.startsWith("worktree ")) {
-      if (cur) out.push(cur);
-      cur = { worktree: path.resolve(line.slice("worktree ".length).trim()), head: "", branch: "", locked: false, lockReason: "" };
-      continue;
-    }
-    if (!cur) continue;
-    if (line.startsWith("HEAD ")) {
-      cur.head = line.slice("HEAD ".length).trim();
-      continue;
-    }
-    if (line.startsWith("branch ")) {
-      cur.branch = line.slice("branch ".length).trim();
-      continue;
-    }
-    if (line === "locked" || line.startsWith("locked ")) {
-      cur.locked = true;
-      cur.lockReason = line === "locked" ? "" : line.slice("locked ".length).trim();
-      continue;
-    }
-  }
-  if (cur) out.push(cur);
-  return out;
-}
-
 /**
  * @param {string} branch
- * @returns {string}
  */
 function inferChangeIdFromBranch(branch) {
   const m = CHANGE_BRANCH_RE.exec(branch || "");
@@ -681,12 +788,6 @@ function inferChangePhase(blockersStrict, tasks) {
   return "deliver";
 }
 
-/**
- * Compute change status as JSON-friendly object (used by dashboard and CLI).
- *
- * @param {string} gitRoot
- * @param {string} changeId
- */
 export async function computeChangeStatus(gitRoot, changeId) {
   assertValidChangeId(changeId);
   await ensureTruthFiles(gitRoot);
@@ -695,7 +796,6 @@ export async function computeChangeStatus(gitRoot, changeId) {
   if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
   const context = await resolveChangeStatusContext(gitRoot, changeId, {
     currentBranch,
-    listGitWorktrees,
     pathExists,
     isGitRepository: (repoPath) => isGitRepository(repoPath, { pathExists, runCommand }),
     inferChangeIdFromBranch,
@@ -868,190 +968,21 @@ export async function computeChangeStatus(gitRoot, changeId) {
   };
 }
 
-/**
- * Run ws_change_check.py and return parsed results for dashboards/tools.
- *
- * @param {string} gitRoot
- * @param {string} changeId
- * @param {{ strict: boolean, allowTruthDrift: boolean, checkEvidence?: boolean, checkScope?: boolean }} options
- */
 export async function validateChangeArtifacts(gitRoot, changeId, options) {
   return validateChangeArtifactsModel(gitRoot, changeId, options, {
     assertValidChangeId,
     collectFinishGateErrors,
     computeChangeStatus,
     ensureTruthFiles,
+    pathExists,
+    readText,
     resolveWsChangeChecker,
+    runCommand,
     runPython,
+    UserError,
   });
 }
 
-/**
- * @param {string} text
- */
-function countWsTodo(text) {
-  return (text.match(/WS:TODO/g) || []).length;
-}
-
-/**
- * @param {string} text
- */
-function countPlaceholders(text) {
-  return (text.match(/{{CHANGE_ID}}|{{TITLE}}|{{CREATED_AT}}/g) || []).length;
-}
-
-/**
- * @param {string} changeDir
- * @param {string} rel
- */
-async function fileState(changeDir, rel) {
-  const abs = path.join(changeDir, rel);
-  if (!(await pathExists(abs))) return { state: "missing", wsTodo: 0, placeholders: 0, abs, text: "" };
-  const st = await fs.stat(abs);
-  if (st.size === 0) return { state: "empty", wsTodo: 0, placeholders: 0, abs, text: "" };
-  const text = await readText(abs);
-  return { state: "ok", wsTodo: countWsTodo(text), placeholders: countPlaceholders(text), abs, text };
-}
-
-/**
- * Append a change lifecycle event into changes/<id>/metrics.json.
- *
- * @param {string} gitRoot
- * @param {string} changeId
- * @param {string} type
- * @param {any} payload
- */
-async function appendMetricsEventAtDir(changeDir, changeId, type, payload) {
-  const metricsAbs = path.join(changeDir, "metrics.json");
-  /** @type {{ version: number, change_id: string, events: any[], updated_at?: string } | null} */
-  let cur = null;
-  if (await pathExists(metricsAbs)) {
-    try {
-      cur = JSON.parse(await readText(metricsAbs));
-    } catch {
-      cur = null;
-    }
-  }
-  if (!cur || typeof cur !== "object") {
-    cur = { version: 1, change_id: changeId, events: [] };
-  }
-  if (!Array.isArray(cur.events)) cur.events = [];
-  cur.events.push({ type, timestamp: nowIsoUtc(), payload: payload ?? null });
-  cur.events = cur.events.slice(-200);
-  cur.updated_at = nowIsoUtc();
-  await writeText(metricsAbs, JSON.stringify(cur, null, 2) + "\n");
-}
-
-async function appendMetricsEvent(gitRoot, changeId, type, payload) {
-  const changeDir = changeDirAbs(gitRoot, changeId);
-  await appendMetricsEventAtDir(changeDir, changeId, type, payload);
-}
-
-/**
- * @param {string} gitRoot
- */
-async function resolveTemplateIdForRepo(gitRoot) {
-  const manifestPath = path.join(gitRoot, ".aiws", "manifest.json");
-  if (!(await pathExists(manifestPath))) return "workspace";
-  try {
-    const stored = JSON.parse(await readText(manifestPath));
-    const templateId = String(stored.template_id || "").trim();
-    return templateId || "workspace";
-  } catch {
-    return "workspace";
-  }
-}
-
-/**
- * @param {string} gitRoot
- * @returns {Promise<{ templateDir: string, resolvedFrom: string }>}
- */
-async function resolveChangeTemplatesDir(gitRoot) {
-  const candidates = [
-    { dir: path.join(gitRoot, "changes", "templates"), label: `${gitRoot}/changes/templates` },
-    { dir: path.join(gitRoot, "workflow", "changes", "templates"), label: `${gitRoot}/workflow/changes/templates` },
-  ];
-
-  for (const c of candidates) {
-    if (!(await pathExists(path.join(c.dir, "proposal.md")))) continue;
-    if (!(await pathExists(path.join(c.dir, "tasks.md")))) continue;
-    return { templateDir: c.dir, resolvedFrom: c.label };
-  }
-
-  const templateId = await resolveTemplateIdForRepo(gitRoot);
-  const tpl = await loadTemplate(templateId);
-  const fallback = path.join(tpl.templateDir, "changes", "templates");
-
-  if (!(await pathExists(path.join(fallback, "proposal.md"))) || !(await pathExists(path.join(fallback, "tasks.md")))) {
-    throw new UserError("Missing change templates.", { details: `Expected proposal.md and tasks.md under: ${fallback}` });
-  }
-  return { templateDir: fallback, resolvedFrom: `@aipper/aiws-spec:${tpl.templateId}` };
-}
-
-/**
- * @param {string} templateText
- * @param {{ changeId: string, title: string, createdAt: string }} vars
- */
-function renderTemplate(templateText, vars) {
-  return templateText.replaceAll("{{CHANGE_ID}}", vars.changeId).replaceAll("{{TITLE}}", vars.title).replaceAll("{{CREATED_AT}}", vars.createdAt);
-}
-
-/**
- * @param {string} gitRoot
- * @returns {Promise<{ path: string, args: string[] }>}
- */
-async function resolveWsChangeChecker(gitRoot) {
-  const local = path.join(gitRoot, "tools", "ws_change_check.py");
-  if (await pathExists(local)) return { path: local, args: [local] };
-
-  const templateId = await resolveTemplateIdForRepo(gitRoot);
-  const tpl = await loadTemplate(templateId);
-  const fallback = path.join(tpl.templateDir, "tools", "ws_change_check.py");
-  if (!(await pathExists(fallback))) {
-    throw new UserError("Missing ws_change_check.py.", { details: "Hint: run `aiws init .` to install tools/ws_change_check.py in your repo." });
-  }
-  return { path: fallback, args: [fallback] };
-}
-
-/**
- * @param {string} gitRoot
- * @param {string[]} args
- */
-async function runPython(gitRoot, args) {
-  let res;
-  try {
-    res = await runCommand("python3", args, { cwd: gitRoot });
-  } catch (e) {
-    throw new UserError("python3 is required.", { details: e instanceof Error ? e.message : String(e) });
-  }
-  return res;
-}
-
-/**
- * @param {string} gitRoot
- * @param {string | undefined} changeId
- * @param {{ command: string, allowFinishedUnarchived?: boolean }} options
- */
-async function resolveChangeId(gitRoot, changeId, options) {
-  const resolved = changeId || inferChangeIdFromBranch(await currentBranch(gitRoot));
-  if (resolved) {
-    const terminated = await detectTerminatedChange(gitRoot, resolved);
-    if (!isTerminatedAllowed(options.command, terminated, { allowFinishedUnarchived: options.allowFinishedUnarchived === true })) {
-      throw terminatedChangeError(gitRoot, resolved, terminated, `aiws change ${options.command}`);
-    }
-    return resolved;
-  }
-  throw new UserError(`usage: aiws change ${options.command} <change-id> (or switch to branch change/<change-id>)`);
-}
-
-/**
- * @param {string} gitRoot
- * @param {string} changeId
- */
-function changeDirAbs(gitRoot, changeId) {
-  return path.join(gitRoot, "changes", changeId);
-}
-
 /**
  * aiws change list
  */
@@ -1289,7 +1220,7 @@ export async function changeNewCommand(options) {
 /**
  * aiws change start
  *
- * @param {{ changeId: string, title?: string, noDesign: boolean, enableHooks: boolean, noSwitch: boolean, forceSwitch: boolean, allowDirty?: boolean, worktree: boolean, worktreeDir?: string, submodules: boolean }} options
+ * @param {{ changeId: string, title?: string, noDesign: boolean, enableHooks: boolean, noSwitch: boolean, forceSwitch: boolean, allowDirty?: boolean }} options
  */
 export async function changeStartCommand(options) {
   const gitRoot = await resolveGitRoot(process.cwd());
@@ -1302,55 +1233,32 @@ 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");
-  }
   if (options.forceSwitch === true && options.noSwitch === true) {
     throw new UserError("change start: cannot combine --switch with --no-switch");
   }
-  if (options.forceSwitch === true && options.worktree === true) {
-    throw new UserError("change start: cannot combine --switch with --worktree");
-  }
 
   const hasBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: gitRoot }).then((r) => r.code === 0);
   const hasGitmodules = await pathExists(path.join(gitRoot, ".gitmodules"));
   let effectiveNoSwitch = options.noSwitch === true;
   const effectiveForceSwitch = options.forceSwitch === true;
-  let effectiveWorktree = options.worktree === true;
-
-  if (hasGitmodules && !effectiveNoSwitch && !effectiveWorktree && !effectiveForceSwitch) {
-    const prereq = await checkWorktreePrereqs(gitRoot, { hasHeadCommit, runCommand });
-    if (prereq.ok) {
-      effectiveWorktree = true;
-      console.error("warn: .gitmodules detected (git submodules). defaulting to --worktree to avoid switching the superproject branch.");
-      console.error("warn: to avoid worktree and just prepare artifacts: aiws change start <change-id> --no-switch");
-      console.error("warn: to switch anyway: aiws change start <change-id> --switch");
-    } else {
-      effectiveNoSwitch = true;
-      if (prereq.reason === "no_commit") {
-        console.error("warn: .gitmodules detected (git submodules). cannot use --worktree on a repo with no commits; defaulting to --no-switch.");
-      } else {
-        console.error("warn: .gitmodules detected (git submodules). cannot use --worktree without truth files committed in HEAD; defaulting to --no-switch.");
-      }
-      console.error("warn: to switch anyway: aiws change start <change-id> --switch");
-      console.error("warn: recommended for submodules: aiws change start <change-id> --worktree (after committing truth files)");
-    }
+
+  if (hasGitmodules && !effectiveNoSwitch && !effectiveForceSwitch) {
+    effectiveNoSwitch = true;
+    console.error("warn: .gitmodules detected (git submodules). defaulting to --no-switch (prepare artifacts only).");
+    console.error("warn: to switch anyway: aiws change start <change-id> --switch");
   } else if (hasGitmodules && effectiveForceSwitch) {
     console.error("warn: .gitmodules detected (git submodules). switching the superproject branch due to --switch.");
-    console.error("warn: recommended for submodules: aiws change start <change-id> --worktree");
+    console.error("warn: recommended for submodules: aiws change start <change-id> --no-switch");
   }
 
-  if (!allowDirty && (effectiveWorktree || !effectiveNoSwitch)) {
+  if (!allowDirty && !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).`, {
+      throw new UserError("Refusing to start change with a dirty working tree.", {
         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" +
@@ -1361,139 +1269,6 @@ export async function changeStartCommand(options) {
     }
   }
 
-  if (effectiveWorktree) {
-    const prereq = await checkWorktreePrereqs(gitRoot, { hasHeadCommit, runCommand });
-    if (!prereq.ok) {
-      if (prereq.reason === "no_commit") {
-        throw new UserError("change start --worktree requires a repo with at least one commit.", { details: "Hint: make an initial commit, then retry." });
-      }
-      const missingInHead = Array.isArray(prereq.missing) ? prereq.missing : [];
-      throw new UserError("change start --worktree requires truth files committed in HEAD.", {
-        details:
-          `Missing in HEAD:\n${missingInHead.map((f) => `- ${f}`).join("\n")}\n\n` +
-          "Why: git worktree checks out from HEAD, so uncommitted files won't be present in the new worktree.\n" +
-          "Hint: commit the truth files first, or use `aiws change start --no-switch`.",
-      });
-    }
-    const worktreeDir = resolveDefaultWorktreeDir(gitRoot, options.worktreeDir, changeId);
-
-    const rel = path.relative(gitRoot, worktreeDir);
-    if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
-      throw new UserError("worktree dir must be outside the git root.", {
-        details: `git_root: ${gitRoot}\nworktree_dir: ${worktreeDir}\nHint: use a sibling dir like ../<repo>-<change-id> (default) or pass --worktree-dir <path>.`,
-      });
-    }
-
-    const worktrees = await listGitWorktrees(gitRoot);
-    /** @type {Map<string, { worktree: string, head: string, branch: string }>} */
-    const byPath = new Map();
-    /** @type {Map<string, string>} */
-    const byBranch = new Map();
-    for (const w of worktrees) {
-      const k = path.resolve(w.worktree);
-      byPath.set(k, w);
-      if (w.branch) byBranch.set(w.branch, k);
-    }
-
-    const destKey = path.resolve(worktreeDir);
-    const destExisting = byPath.get(destKey);
-
-    if (!destExisting) {
-      if (await pathExists(destKey)) {
-        throw new UserError("worktree dir already exists and is not a registered worktree; refusing to overwrite.", {
-          details: `worktree_dir: ${destKey}`,
-        });
-      }
-      const used = byBranch.get(branchRef);
-      if (used) {
-        throw new UserError("change branch is already checked out in another worktree.", {
-          details: `branch: ${branch}\nworktree: ${used}\nHint: use that worktree, or pick another change-id.`,
-        });
-      }
-
-      const args = hasBranch ? ["worktree", "add", destKey, branch] : ["worktree", "add", "-b", branch, destKey];
-      const add = await runCommand("git", args, { cwd: gitRoot });
-      if (add.code !== 0) {
-        throw new UserError("Failed to create git worktree.", { details: add.stderr || add.stdout });
-      }
-    } else if (destExisting.branch && destExisting.branch !== branchRef) {
-      throw new UserError("worktree dir already exists but is on a different branch.", {
-        details: `worktree_dir: ${destKey}\nexpected_branch: ${branchRef}\nactual_branch: ${destExisting.branch}`,
-      });
-    } else if (!destExisting.branch) {
-      throw new UserError("worktree dir already exists but is detached; refusing to proceed.", {
-        details: `worktree_dir: ${destKey}\nHint: inspect with: git -C ${destKey} status`,
-      });
-    }
-
-    const changeDir = changeDirAbs(destKey, changeId);
-    if (!(await pathExists(changeDir))) {
-      await changeNewAtGitRoot(destKey, {
-        changeId,
-        title: options.title,
-        noDesign: options.noDesign,
-        baseBranch: startFromBranch && startFromBranch !== branch ? startFromBranch : undefined,
-      });
-    } else {
-      await maybeRecordBaseBranch(changeDir, startFromBranch, branch, { nowIsoUtc, pathExists, readText, writeText });
-    }
-
-    // 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}`);
-    console.log("next:");
-    console.log(`  - cd:       cd ${destKey}`);
-    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 .");
-    console.log("finish (safe merge):");
-    console.log(`  - from main worktree: git merge --ff-only ${branch}`);
-    return;
-  }
-
   const headReady = await hasHeadCommit(gitRoot);
   let branchReady = hasBranch;
 
@@ -1516,7 +1291,6 @@ export async function changeStartCommand(options) {
     await maybeRecordBaseBranch(changeDir, startFromBranch, branch, { nowIsoUtc, pathExists, readText, writeText });
   }
 
-  // Check Depends_On dependencies (non-worktree mode)
   await checkDependenciesAndPrintHandoff(gitRoot, changeId, changeDir);
 
   if (options.enableHooks) {
@@ -1527,7 +1301,6 @@ export async function changeStartCommand(options) {
   const curLabel = cur || "(detached)";
   await appendMetricsEvent(gitRoot, changeId, "change_start", {
     mode: effectiveNoSwitch ? "no-switch" : "switch",
-    worktree: gitRoot,
     branch,
     from_branch: startFromBranch || "",
     current_branch: curLabel,
@@ -1580,18 +1353,17 @@ export async function changeFinishCommand(options) {
         `fallback: if you intentionally only need local archive recovery, run \`aiws change archive ${resolvedChangeId}\``,
     });
   }
-  const { changeId, changeBranch, into, cur, changeWt } = await resolveFinishContext(gitRoot, { ...options, changeId: resolvedChangeId }, {
+  const { changeId, changeBranch, into, cur } = await resolveFinishContext(gitRoot, { ...options, changeId: resolvedChangeId }, {
     assertValidChangeId,
     checkGitClean,
     currentBranch,
-    listGitWorktrees,
     pathExists,
     readText,
     resolveChangeId,
     runCommand,
     UserError,
   });
-  const finishStatusRoot = changeWt?.worktree ? path.resolve(changeWt.worktree) : gitRoot;
+  const finishStatusRoot = gitRoot;
   const finishStatus = await computeChangeStatus(finishStatusRoot, changeId);
   const finishGateErrors = collectFinishGateErrors(changeId, finishStatus.reviewGates);
   if (finishGateErrors.length > 0) {
@@ -1633,11 +1405,12 @@ export async function changeFinishCommand(options) {
 
   const merge = await runCommand("git", ["merge", "--ff-only", changeBranch], { cwd: gitRoot });
   if (merge.code !== 0) {
-    const extra =
-      changeWt && changeWt.worktree
-        ? `\n\nIf not fast-forward, rebase the change branch then retry:\n  cd ${changeWt.worktree}\n  git rebase ${into}\n  cd ${gitRoot}\n  aiws change finish ${changeId}`
-        : `\n\nIf not fast-forward, rebase the change branch then retry:\n  git switch ${changeBranch}\n  git rebase ${into}\n  git switch ${into}\n  aiws change finish ${changeId}`;
-    throw new UserError("Failed to fast-forward merge change branch into target.", { details: `${merge.stderr || merge.stdout}${extra}` });
+    throw new UserError("Failed to fast-forward merge change branch into target.", {
+      details:
+        `${merge.stderr || merge.stdout}` +
+        `\n\nIf not fast-forward, rebase the change branch then retry:\n` +
+        `  git switch ${changeBranch}\n  git rebase ${into}\n  git switch ${into}\n  aiws change finish ${changeId}`,
+    });
   }
 
   await appendMetricsEvent(gitRoot, changeId, "finish_local", finishBasePayload);
@@ -1651,7 +1424,7 @@ export async function changeFinishCommand(options) {
   let handoffRel = "";
   if (options.push === true) {
     try {
-      const submodulePush = await pushSubmodulesForFinish(gitRoot, changeId, into, changeWt?.worktree, {
+      const submodulePush = await pushSubmodulesForFinish(gitRoot, changeId, into, {
         pathExists,
         readText,
         runCommand,
@@ -1676,37 +1449,9 @@ export async function changeFinishCommand(options) {
 
       console.log(`push: target ${pushTarget.remote} ${into}${pushTarget.remoteBranch !== into ? ` -> ${pushTarget.remoteBranch}` : ""}`);
 
-      if (changeWt?.worktree) {
-        const cleanup = await cleanupWorktreePath(gitRoot, changeWt.worktree, {
-          checkGitClean,
-          listGitWorktrees,
-          pathExists,
-          runCommand,
-          UserError,
-        });
-        cleanupNote = cleanup.status === "skipped" ? `skipped:${cleanup.reason || "unknown"}` : cleanup.status;
-        finishCompleted =
-          cleanup.status === "removed" ||
-          cleanup.status === "pruned-missing" ||
-          (cleanup.status === "skipped" && cleanup.reason === "current_worktree");
-        if (cleanup.status === "removed") {
-          console.log(`cleanup: removed worktree ${cleanup.worktree}`);
-        } else if (cleanup.status === "pruned-missing") {
-          console.log(`cleanup: pruned stale worktree metadata for ${cleanup.worktree}`);
-        } else if (cleanup.reason === "current_worktree") {
-          console.log("cleanup: skipped (change worktree is current worktree)");
-        } else if (cleanup.reason === "locked") {
-          console.log(`cleanup: skipped locked worktree ${cleanup.worktree}`);
-        } else if (cleanup.reason === "dirty") {
-          console.log(`cleanup: skipped dirty worktree ${cleanup.worktree}`);
-        } else {
-          console.log("cleanup: skipped");
-        }
-      } else {
-        cleanupNote = "skipped:no_separate_change_worktree";
-        finishCompleted = true;
-        console.log("cleanup: skipped (no separate change worktree)");
-      }
+      cleanupNote = "skipped:current_worktree";
+      finishCompleted = true;
+      console.log("cleanup: skipped (no separate worktree)");
     } catch (error) {
       await appendMetricsEvent(gitRoot, changeId, "finish_failed", {
         ...finishBasePayload,
@@ -1727,7 +1472,7 @@ export async function changeFinishCommand(options) {
       details:
         `change: ${changeId}\n` +
         `next: cleanup pending (${cleanupReason || "unknown"})\n` +
-        `  - resolve the change worktree state, then rerun: aiws change finish ${changeId} --push${options.remote ? ` --remote ${options.remote}` : ""}`,
+        `  - then rerun: aiws change finish ${changeId} --push${options.remote ? ` --remote ${options.remote}` : ""}`,
     });
   }
 
@@ -1788,7 +1533,7 @@ export async function changeFinishCommand(options) {
 
   if (options.push === true && (await listSubmodulesFromGitmodules(gitRoot, { pathExists, runCommand })).length > 0) {
     console.log("next:");
-    console.log("  - submodules already synced for finish --push; rerun `git submodule update --init --recursive` only if another worktree changed them later");
+    console.log("  - submodules already synced for finish --push; rerun `git submodule update --init --recursive` only if needed when submodule state changes");
   }
 }
 
@@ -1804,12 +1549,10 @@ 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);
-  const changeWorktreeHint = await resolveChangeWorktreeHint(gitRoot, changeId, { listGitWorktrees });
   const output = await renderChangeStatusOutput(
     {
       gitRoot,
       branch,
-      changeWorktreeHint,
       status: st,
     },
     {
@@ -1865,7 +1608,6 @@ export async function computeChangeNextAdvice(gitRoot, changeId) {
     computeChangeStatus,
     currentBranch,
     inferChangeIdFromBranch,
-    listGitWorktrees,
     changeDirAbs,
     governanceGuidanceLines,
     scopeGateFailureAction,