@aipper/aiws 0.0.21 → 0.0.24

package/README.md

@@ -47,7 +47,7 @@ aiws codex <install-skills|status-skills|uninstall-skills|install-prompts|status
 
 ## Codex（repo skills 优先）
 
-- `aiws init .` 会生成 `.agents/skills/`（随仓库共享），在 Codex 中可显式调用（示例）：`$ws-preflight` / `$ws-plan` / `$ws-dev` / `$ws-review` / `$ws-commit`
+- `aiws init .` 会生成 `.agents/skills/`（随仓库共享），在 Codex 中可显式调用（示例）：`$ws-preflight` / `$ws-plan` / `$p-tasks-plan` / `$ws-handoff` / `$ws-dev` / `$ws-review` / `$ws-commit`
 - 交付收尾（submodules+superproject 分步提交 + 安全合并）：`$ws-deliver`
 - 收尾（安全合并回目标分支）：`$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward）
 - 可选：安装全局 skills 到 `~/.codex/skills/`（或 `$CODEX_HOME/skills`）：

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@aipper/aiws",
-  "version": "0.0.21",
+  "version": "0.0.24",
   "description": "AI Workspace CLI (init/update/validate) for Claude Code / OpenCode / Codex / iFlow.",
   "type": "module",
   "bin": {
     "aiws": "./bin/aiws.js"
   },
   "dependencies": {
-    "@aipper/aiws-spec": "0.0.21"
+    "@aipper/aiws-spec": "0.0.24"
   },
   "files": [
     "bin",

package/src/cli.js

@@ -260,6 +260,7 @@ export async function cliMain(argv) {
             hooks: { type: "boolean" },
             "no-switch": { type: "boolean" },
             switch: { type: "boolean" },
+            "allow-dirty": { type: "boolean" },
             worktree: { type: "boolean" },
             "worktree-dir": { type: "string" },
             submodules: { type: "boolean" },
@@ -268,7 +269,7 @@ export async function cliMain(argv) {
           if (!changeId)
             throw new UserError("change start requires <change-id>", {
               details:
-                "Usage: aiws change start <change-id> [--title <title>] [--no-design] [--hooks] [--no-switch] [--switch] [--worktree] [--worktree-dir <path>] [--submodules]",
+                "Usage: aiws change start <change-id> [--title <title>] [--no-design] [--hooks] [--no-switch] [--switch] [--allow-dirty] [--worktree] [--worktree-dir <path>] [--submodules]",
             });
           await changeStartCommand({
             changeId,
@@ -277,6 +278,7 @@ export async function cliMain(argv) {
             enableHooks: options.hooks === true,
             noSwitch: options["no-switch"] === true,
             forceSwitch: options.switch === true,
+            allowDirty: options["allow-dirty"] === true,
             worktree: options.worktree === true,
             worktreeDir: options["worktree-dir"],
             submodules: options.submodules === true,
@@ -368,12 +370,16 @@ export async function cliMain(argv) {
           const { positionals, options } = parseArgs(args, {
             into: { type: "string" },
             base: { type: "string" },
+            push: { type: "boolean" },
+            remote: { type: "string" },
           });
           const changeId = positionals[0];
           await changeFinishCommand({
             changeId,
             into: options.into,
             base: options.base,
+            push: options.push === true,
+            remote: options.remote,
           });
           return 0;
         }
@@ -490,8 +496,8 @@ function printChangeHelp() {
 
 Usage:
   aiws change list
-  aiws change start <change-id> [--title <title>] [--no-design] [--hooks] [--no-switch] [--switch] [--worktree] [--worktree-dir <path>] [--submodules]
-  aiws change finish [change-id] [--into <branch> | --base <branch>]
+  aiws change start <change-id> [--title <title>] [--no-design] [--hooks] [--no-switch] [--switch] [--allow-dirty] [--worktree] [--worktree-dir <path>]
+  aiws change finish [change-id] [--into <branch> | --base <branch>] [--push] [--remote <name>]
   aiws change new <change-id> [--title <title>] [--no-design]
   aiws change status [change-id]
   aiws change next [change-id]
@@ -510,6 +516,8 @@ Notes:
   - Execution quality gate first: aiws change validate [change-id] --strict
     (equivalent to running $ws-plan-verify in AI tools).
   - status/next now prioritize quality-gate guidance before coding ($ws-dev).
+  - start refuses to switch/create worktree with a dirty working tree (unless --allow-dirty).
+  - finish --push is submodule-aware: when .gitmodules exists it pushes submodules first, then the target branch, then safely cleans the separate change worktree if possible.
   - If .gitmodules exists and you didn't specify --switch/--no-switch/--worktree,
     start will prefer --worktree (fallback: --no-switch) to avoid switching the superproject branch.
   - archive runs strict validation and (by default) requires all tasks checked.

package/src/commands/change.js

@@ -165,7 +165,7 @@ async function maybeRecordBaseBranch(changeDir, baseBranch, changeBranch) {
 
 /**
  * @param {string} gitRoot
- * @returns {Promise<Array<{ worktree: string, head: string, branch: string }>>}
+ * @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 });
@@ -176,16 +176,16 @@ async function listGitWorktrees(gitRoot) {
     .split(/\r?\n/)
     .map((l) => l.trimEnd());
 
-  /** @type {Array<{ worktree: string, head: string, branch: string }>} */
+  /** @type {Array<{ worktree: string, head: string, branch: string, locked: boolean, lockReason: string }>} */
   const out = [];
-  /** @type {{ worktree: string, head: string, branch: string } | null} */
+  /** @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: "" };
+      cur = { worktree: path.resolve(line.slice("worktree ".length).trim()), head: "", branch: "", locked: false, lockReason: "" };
       continue;
     }
     if (!cur) continue;
@@ -197,11 +197,451 @@ async function listGitWorktrees(gitRoot) {
       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} gitRoot
+ * @param {string} branch
+ * @param {string | undefined} preferredRemote
+ */
+async function resolvePushTarget(gitRoot, branch, preferredRemote) {
+  const remoteRaw = String(preferredRemote || "").trim();
+  const branchRemoteRes = await runCommand("git", ["config", "--get", `branch.${branch}.remote`], { cwd: gitRoot });
+  const trackedRemote = String(branchRemoteRes.stdout || "").trim();
+
+  const branchMergeRes = await runCommand("git", ["config", "--get", `branch.${branch}.merge`], { cwd: gitRoot });
+  const trackedMergeRef = String(branchMergeRes.stdout || "").trim();
+  const trackedBranch = trackedMergeRef.startsWith("refs/heads/") ? trackedMergeRef.slice("refs/heads/".length) : "";
+
+  const remote = remoteRaw || trackedRemote || "origin";
+  const remoteBranch = trackedBranch || branch;
+  const refspec = remoteBranch === branch ? branch : `${branch}:${remoteBranch}`;
+
+  return { remote, remoteBranch, refspec, trackedRemote, trackedMergeRef };
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} worktreePath
+ */
+async function cleanupWorktreePath(gitRoot, worktreePath) {
+  const abs = path.resolve(worktreePath);
+  if (abs === path.resolve(gitRoot)) {
+    return { status: "skipped", reason: "current_worktree", worktree: abs };
+  }
+
+  const worktrees = await listGitWorktrees(gitRoot);
+  const worktreeEntry = worktrees.find((w) => path.resolve(w.worktree) === abs);
+  if (worktreeEntry?.locked) {
+    return { status: "skipped", reason: "locked", worktree: abs, details: worktreeEntry.lockReason };
+  }
+
+  if (!(await pathExists(abs))) {
+    const prune = await runCommand("git", ["worktree", "prune"], { cwd: gitRoot });
+    if (prune.code !== 0) {
+      throw new UserError("Failed to prune stale git worktree metadata.", { details: prune.stderr || prune.stdout });
+    }
+    return { status: "pruned-missing", worktree: abs };
+  }
+
+  const clean = await checkGitClean(abs);
+  if (!clean.clean) {
+    return { status: "skipped", reason: "dirty", worktree: abs, details: clean.details };
+  }
+
+  let rm = await runCommand("git", ["worktree", "remove", abs], { cwd: gitRoot });
+  if (rm.code !== 0) {
+    const out = `${rm.stderr || ""}\n${rm.stdout || ""}`;
+    if (out.includes("working trees containing submodules cannot be moved or removed")) {
+      rm = await runCommand("git", ["worktree", "remove", "--force", abs], { cwd: gitRoot });
+    }
+  }
+  if (rm.code !== 0) {
+    throw new UserError("Failed to remove change worktree.", { details: rm.stderr || rm.stdout });
+  }
+
+  const prune = await runCommand("git", ["worktree", "prune"], { cwd: gitRoot });
+  if (prune.code !== 0) {
+    throw new UserError("Failed to prune git worktree metadata after remove.", { details: prune.stderr || prune.stdout });
+  }
+
+  return { status: "removed", worktree: abs };
+}
+
+/**
+ * @param {string} gitRoot
+ * @returns {Promise<Array<{ name: string, path: string }>>}
+ */
+async function listSubmodulesFromGitmodules(gitRoot) {
+  const gitmodules = path.join(gitRoot, ".gitmodules");
+  if (!(await pathExists(gitmodules))) return [];
+
+  const list = await runCommand("git", ["config", "--file", ".gitmodules", "--get-regexp", "^submodule\\..*\\.path$"], { cwd: gitRoot });
+  if (list.code !== 0) return [];
+
+  /** @type {Array<{ name: string, path: string }>} */
+  const subs = [];
+  for (const raw of String(list.stdout || "").split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const idx = line.indexOf(" ");
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim();
+    const subPath = line.slice(idx + 1).trim();
+    const m = key.match(/^submodule\.(.+)\.path$/);
+    if (!m) continue;
+    const name = String(m[1] || "").trim();
+    if (!name || !subPath) continue;
+    subs.push({ name, path: subPath });
+  }
+  return subs;
+}
+
+/**
+ * @param {string} targetsPath
+ */
+async function parseSubmoduleTargetsFile(targetsPath) {
+  /** @type {Map<string, { branch: string, remote: string }>} */
+  const parsed = new Map();
+  /** @type {string[]} */
+  const errors = [];
+
+  if (!(await pathExists(targetsPath))) {
+    return { parsed, errors };
+  }
+
+  const text = await readText(targetsPath);
+  const lines = String(text || "").split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i] || "";
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const parts = line.split(/\s+/).filter(Boolean);
+    if (parts.length < 2) {
+      errors.push(`${path.basename(targetsPath)}:${i + 1} invalid line (expected: <path> <target_branch> [remote])`);
+      continue;
+    }
+    const subPath = String(parts[0] || "").trim();
+    const targetBranch = String(parts[1] || "").trim();
+    const remote = String(parts[2] || "origin").trim() || "origin";
+    if (!subPath) {
+      errors.push(`${path.basename(targetsPath)}:${i + 1} missing submodule path`);
+      continue;
+    }
+    if (parsed.has(subPath)) {
+      errors.push(`${path.basename(targetsPath)}:${i + 1} duplicate submodule path: ${subPath}`);
+      continue;
+    }
+    if (!targetBranch || ["<fill-me>", "<fill_me>", "tbd", "TBD"].includes(targetBranch)) {
+      errors.push(`${path.basename(targetsPath)}:${i + 1} missing/placeholder target_branch for ${subPath}`);
+      continue;
+    }
+    parsed.set(subPath, { branch: targetBranch, remote });
+  }
+
+  return { parsed, errors };
+}
+
+/**
+ * @param {string} repoPath
+ * @param {string} rev
+ */
+async function gitHasRevision(repoPath, rev) {
+  if (!(await pathExists(repoPath))) return false;
+  const res = await runCommand("git", ["-C", repoPath, "cat-file", "-e", `${rev}^{commit}`], { cwd: repoPath });
+  return res.code === 0;
+}
+
+/**
+ * @param {string} repoPath
+ * @returns {Promise<boolean>}
+ */
+async function isGitRepository(repoPath) {
+  if (!(await pathExists(repoPath))) return false;
+  const res = await runCommand("git", ["-C", repoPath, "rev-parse", "--git-dir"], { cwd: repoPath });
+  return res.code === 0;
+}
+
+/**
+ * @param {string} targetRepoPath
+ * @param {string} sha
+ * @param {string | undefined} fallbackRepoPath
+ */
+async function ensureRevisionAvailable(targetRepoPath, sha, fallbackRepoPath) {
+  if (await gitHasRevision(targetRepoPath, sha)) return;
+  const fallback = String(fallbackRepoPath || "").trim();
+  if (!fallback) {
+    throw new UserError("Required submodule commit is not available locally.", {
+      details: `repo: ${targetRepoPath}\ncommit: ${sha}`,
+    });
+  }
+  if (!(await gitHasRevision(fallback, sha))) {
+    throw new UserError("Required submodule commit is missing in both target and change worktrees.", {
+      details: `target_repo: ${targetRepoPath}\nchange_repo: ${fallback}\ncommit: ${sha}`,
+    });
+  }
+  const fetch = await runCommand("git", ["-C", targetRepoPath, "fetch", fallback, sha], { cwd: targetRepoPath });
+  if (fetch.code !== 0 || !(await gitHasRevision(targetRepoPath, sha))) {
+    throw new UserError("Failed to import submodule commit from change worktree.", {
+      details: `target_repo: ${targetRepoPath}\nchange_repo: ${fallback}\ncommit: ${sha}\n\n${fetch.stderr || fetch.stdout}`,
+    });
+  }
+}
+
+/**
+ * @param {string} repoPath
+ * @param {string} remote
+ * @param {string} branch
+ * @param {string} sha
+ */
+async function pushSubmoduleBranch(repoPath, remote, branch, sha) {
+  const fetch = await runCommand("git", ["-C", repoPath, "fetch", remote, "--prune"], { cwd: repoPath });
+  if (fetch.code !== 0) {
+    throw new UserError("Failed to fetch submodule remote before push.", {
+      details: `repo: ${repoPath}\nremote: ${remote}\n\n${fetch.stderr || fetch.stdout}`,
+    });
+  }
+
+  const remoteRef = `refs/remotes/${remote}/${branch}`;
+  const hasRemoteBranch = await runCommand("git", ["-C", repoPath, "show-ref", "--verify", "--quiet", remoteRef], { cwd: repoPath }).then((r) => r.code === 0);
+  if (!hasRemoteBranch) {
+    throw new UserError("Submodule target branch does not exist on remote.", {
+      details: `repo: ${repoPath}\nremote: ${remote}\nbranch: ${branch}`,
+    });
+  }
+
+  const remoteAncestor = await runCommand("git", ["-C", repoPath, "merge-base", "--is-ancestor", remoteRef, sha], { cwd: repoPath }).then((r) => r.code === 0);
+  if (remoteAncestor) {
+    const push = await runCommand("git", ["-C", repoPath, "push", remote, `${sha}:refs/heads/${branch}`], { cwd: repoPath });
+    if (push.code !== 0) {
+      throw new UserError("Failed to fast-forward push submodule target branch.", {
+        details: `repo: ${repoPath}\nremote: ${remote}\nbranch: ${branch}\ncommit: ${sha}\n\n${push.stderr || push.stdout}`,
+      });
+    }
+    return { status: "pushed", remoteRef };
+  }
+
+  const shaContained = await runCommand("git", ["-C", repoPath, "merge-base", "--is-ancestor", sha, remoteRef], { cwd: repoPath }).then((r) => r.code === 0);
+  if (shaContained) {
+    return { status: "already-contained", remoteRef };
+  }
+
+  throw new UserError("Submodule target branch diverged from gitlink commit.", {
+    details: `repo: ${repoPath}\nremote: ${remote}\nbranch: ${branch}\ncommit: ${sha}\n\nHint: reconcile the submodule branch manually, then retry.`,
+  });
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {string} baseBranch
+ * @param {string | undefined} changeWorktreePath
+ */
+async function pushSubmodulesForFinish(gitRoot, changeId, baseBranch, changeWorktreePath) {
+  const subs = await listSubmodulesFromGitmodules(gitRoot);
+  if (subs.length === 0) return { processed: 0 };
+
+  const targetsPath = path.join(gitRoot, "changes", changeId, "submodules.targets");
+  if (!(await pathExists(targetsPath))) {
+    throw new UserError("Missing submodules.targets for submodule-aware finish.", {
+      details: `required: ${path.relative(gitRoot, targetsPath)}\n\nHint: add one entry per submodule path before running \`aiws change finish --push\`.`,
+    });
+  }
+
+  const parsedTargets = await parseSubmoduleTargetsFile(targetsPath);
+  if (parsedTargets.errors.length > 0) {
+    throw new UserError("Invalid submodules.targets.", { details: parsedTargets.errors.join("\n") });
+  }
+
+  const missingPaths = subs.filter((s) => !parsedTargets.parsed.has(s.path)).map((s) => s.path);
+  if (missingPaths.length > 0) {
+    throw new UserError("submodules.targets missing declared submodule paths.", {
+      details: `file: ${path.relative(gitRoot, targetsPath)}\nmissing: ${missingPaths.join(", ")}`,
+    });
+  }
+
+  /** @type {Array<{ name: string, path: string, sha: string, branch: string, remote: string, pinBranch: string }>} */
+  const specs = [];
+  for (const sub of subs) {
+    const target = parsedTargets.parsed.get(sub.path);
+    if (!target) continue;
+    const targetBranch = target.branch === "." ? baseBranch : target.branch;
+    const gitlink = await runCommand("git", ["rev-parse", `HEAD:${sub.path}`], { cwd: gitRoot });
+    if (gitlink.code !== 0) {
+      throw new UserError("Failed to resolve submodule gitlink commit from merged superproject.", {
+        details: `path: ${sub.path}\n\n${gitlink.stderr || gitlink.stdout}`,
+      });
+    }
+    const sha = String(gitlink.stdout || "").trim();
+    specs.push({
+      name: sub.name,
+      path: sub.path,
+      sha,
+      branch: targetBranch,
+      remote: target.remote,
+      pinBranch: `aiws/pin/${targetBranch}`,
+    });
+  }
+
+  for (const spec of specs) {
+    const targetRepoPath = path.join(gitRoot, spec.path);
+    const changeRepoPath = changeWorktreePath ? path.join(changeWorktreePath, spec.path) : "";
+    const targetRepoReady = await isGitRepository(targetRepoPath);
+    const changeRepoReady = changeRepoPath ? await isGitRepository(changeRepoPath) : false;
+    if (!targetRepoReady && !changeRepoReady) {
+      throw new UserError("Submodule repository is not initialized in either target or change worktree.", {
+        details: `path: ${spec.path}\nHint: initialize submodules before finish, or keep using worktree mode for changes involving submodules.`,
+      });
+    }
+
+    const sourceRepoPath = (targetRepoReady && (await gitHasRevision(targetRepoPath, spec.sha))) ? targetRepoPath : changeRepoReady ? changeRepoPath : targetRepoPath;
+    if (!(await gitHasRevision(sourceRepoPath, spec.sha))) {
+      throw new UserError("Merged submodule gitlink commit is not available locally.", {
+        details: `path: ${spec.path}\ncommit: ${spec.sha}\nsource_repo: ${sourceRepoPath}`,
+      });
+    }
+
+    const pushResult = await pushSubmoduleBranch(sourceRepoPath, spec.remote, spec.branch, spec.sha);
+    console.log(
+      `submodule push: ${spec.path} (${spec.remote} ${spec.branch}${pushResult.status === "pushed" ? ` <= ${spec.sha}` : ", already contained"})`,
+    );
+  }
+
+  const sync = await runCommand("git", ["submodule", "update", "--init", "--recursive"], { cwd: gitRoot });
+  if (sync.code !== 0) {
+    throw new UserError("Submodule push succeeded, but failed to sync target worktree submodules.", {
+      details: sync.stderr || sync.stdout,
+    });
+  }
+
+  for (const spec of specs) {
+    const targetRepoPath = path.join(gitRoot, spec.path);
+    if (!(await isGitRepository(targetRepoPath))) {
+      throw new UserError("Submodule repo missing after sync.", { details: `path: ${spec.path}` });
+    }
+    await ensureRevisionAvailable(targetRepoPath, spec.sha, changeWorktreePath ? path.join(changeWorktreePath, spec.path) : "");
+    const fetch = await runCommand("git", ["-C", targetRepoPath, "fetch", spec.remote, "--prune"], { cwd: targetRepoPath });
+    if (fetch.code !== 0) {
+      throw new UserError("Failed to refresh target worktree submodule remote.", {
+        details: `path: ${spec.path}\nremote: ${spec.remote}\n\n${fetch.stderr || fetch.stdout}`,
+      });
+    }
+    const checkout = await runCommand("git", ["-C", targetRepoPath, "checkout", "-B", spec.pinBranch, spec.sha], { cwd: targetRepoPath });
+    if (checkout.code !== 0) {
+      throw new UserError("Failed to attach target worktree submodule to pin branch.", {
+        details: `path: ${spec.path}\npin_branch: ${spec.pinBranch}\ncommit: ${spec.sha}\n\n${checkout.stderr || checkout.stdout}`,
+      });
+    }
+    await runCommand("git", ["-C", targetRepoPath, "branch", "--set-upstream-to", `${spec.remote}/${spec.branch}`, spec.pinBranch], { cwd: targetRepoPath });
+  }
+
+  return { processed: specs.length };
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {{ changeId?: string, into?: string, base?: string }} options
+ */
+async function resolveFinishContext(gitRoot, options) {
+  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "finish" });
+  assertValidChangeId(changeId);
+
+  const changeBranch = `change/${changeId}`;
+  const changeBranchRef = `refs/heads/${changeBranch}`;
+
+  const hasChangeBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", changeBranchRef], { cwd: gitRoot }).then((r) => r.code === 0);
+  if (!hasChangeBranch) {
+    throw new UserError(`Missing change branch: ${changeBranch}`, {
+      details: "Hint: create it with `aiws change start <change-id>` (or `git switch -c change/<id>`).",
+    });
+  }
+
+  const clean = await checkGitClean(gitRoot);
+  if (!clean.clean) {
+    throw new UserError("Refusing to finish with a dirty working tree.", {
+      details: `${clean.details}\n\nHint: commit or stash your changes, then retry.`,
+    });
+  }
+
+  const cur = await currentBranch(gitRoot);
+  const intoRaw = String(options.into || "").trim();
+  const baseRaw = String(options.base || "").trim();
+  if (intoRaw && baseRaw && intoRaw !== baseRaw) {
+    throw new UserError("change finish: cannot combine --into with --base (values differ).", { details: `--into=${intoRaw}\n--base=${baseRaw}` });
+  }
+
+  /** @type {string} */
+  let into = intoRaw || baseRaw;
+
+  if (!into) {
+    if (!cur) {
+      throw new UserError("Detached HEAD: cannot infer target branch for finish.", {
+        details: "Hint: switch to the target branch (e.g. main) and retry, or pass `aiws change finish <id> --into <branch>`.",
+      });
+    }
+    if (cur !== changeBranch) {
+      into = cur;
+    } else {
+      const metaPath = path.join(gitRoot, "changes", changeId, ".ws-change.json");
+      /** @type {any} */
+      let meta = null;
+      if (await pathExists(metaPath)) {
+        try {
+          meta = JSON.parse(await readText(metaPath));
+        } catch {
+          meta = null;
+        }
+      }
+      if (!meta) {
+        const show = await runCommand("git", ["show", `${changeBranch}:changes/${changeId}/.ws-change.json`], { cwd: gitRoot });
+        if (show.code === 0) {
+          try {
+            meta = JSON.parse(String(show.stdout || ""));
+          } catch {
+            meta = null;
+          }
+        }
+      }
+      const inferred = meta && typeof meta === "object" ? String(meta.base_branch || "").trim() : "";
+      if (!inferred) {
+        throw new UserError("Cannot infer base branch for finish.", {
+          details: "Hint: run from the target branch (e.g. main), or pass: `aiws change finish <id> --into <branch>`.",
+        });
+      }
+      into = inferred;
+    }
+  }
+
+  if (into === changeBranch) {
+    throw new UserError("change finish: target branch cannot be the change branch.", { details: `target=${into}` });
+  }
+
+  const worktrees = await listGitWorktrees(gitRoot);
+  const intoRef = `refs/heads/${into}`;
+  const intoWt = worktrees.find((w) => String(w.branch || "") === intoRef);
+  if (intoWt && path.resolve(intoWt.worktree) !== path.resolve(gitRoot)) {
+    throw new UserError("Target branch is checked out in another worktree.", {
+      details: `branch: ${into}\nworktree: ${intoWt.worktree}\n\nHint: run finish in that worktree:\n  cd ${intoWt.worktree}\n  aiws change finish ${changeId}`,
+    });
+  }
+
+  const hasIntoBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", intoRef], { cwd: gitRoot }).then((r) => r.code === 0);
+  if (!hasIntoBranch) {
+    throw new UserError("Target branch does not exist.", { details: `branch: ${into}` });
+  }
+
+  const changeWt = worktrees.find((w) => String(w.branch || "") === changeBranchRef);
+  return { changeId, changeBranch, changeBranchRef, into, cur, worktrees, changeWt };
+}
+
 /**
  * @param {string} gitRoot
  * @param {string | undefined} worktreeDir
@@ -1417,7 +1857,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());
@@ -1429,6 +1869,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");
@@ -1468,6 +1909,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) {
@@ -1545,12 +2004,30 @@ 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) {
@@ -1562,7 +2039,7 @@ export async function changeStartCommand(options) {
       worktree: destKey,
       branch,
       from_branch: startFromBranch || "",
-      submodules: options.submodules === true,
+      submodules: true,
       hooks: options.enableHooks === true,
     });
 
@@ -1689,98 +2166,13 @@ export async function changeStartCommand(options) {
 /**
  * aiws change finish
  *
- * @param {{ changeId?: string, into?: string, base?: string }} options
+ * @param {{ changeId?: string, into?: string, base?: string, push?: boolean, remote?: string }} options
  */
 export async function changeFinishCommand(options) {
   const gitRoot = await resolveGitRoot(process.cwd());
   await ensureTruthFiles(gitRoot);
 
-  const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "finish" });
-  assertValidChangeId(changeId);
-
-  const changeBranch = `change/${changeId}`;
-  const changeBranchRef = `refs/heads/${changeBranch}`;
-
-  const hasChangeBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", changeBranchRef], { cwd: gitRoot }).then((r) => r.code === 0);
-  if (!hasChangeBranch) {
-    throw new UserError(`Missing change branch: ${changeBranch}`, {
-      details: "Hint: create it with `aiws change start <change-id>` (or `git switch -c change/<id>`).",
-    });
-  }
-
-  const clean = await checkGitClean(gitRoot);
-  if (!clean.clean) {
-    throw new UserError("Refusing to finish with a dirty working tree.", {
-      details: `${clean.details}\n\nHint: commit or stash your changes, then retry.`,
-    });
-  }
-
-  const cur = await currentBranch(gitRoot);
-  const intoRaw = String(options.into || "").trim();
-  const baseRaw = String(options.base || "").trim();
-  if (intoRaw && baseRaw && intoRaw !== baseRaw) {
-    throw new UserError("change finish: cannot combine --into with --base (values differ).", { details: `--into=${intoRaw}\n--base=${baseRaw}` });
-  }
-
-  /** @type {string} */
-  let into = intoRaw || baseRaw;
-
-  if (!into) {
-    if (!cur) {
-      throw new UserError("Detached HEAD: cannot infer target branch for finish.", {
-        details: "Hint: switch to the target branch (e.g. main) and retry, or pass `aiws change finish <id> --into <branch>`.",
-      });
-    }
-    if (cur !== changeBranch) {
-      into = cur;
-    } else {
-      const metaPath = path.join(gitRoot, "changes", changeId, ".ws-change.json");
-      /** @type {any} */
-      let meta = null;
-      if (await pathExists(metaPath)) {
-        try {
-          meta = JSON.parse(await readText(metaPath));
-        } catch {
-          meta = null;
-        }
-      }
-      if (!meta) {
-        const show = await runCommand("git", ["show", `${changeBranch}:changes/${changeId}/.ws-change.json`], { cwd: gitRoot });
-        if (show.code === 0) {
-          try {
-            meta = JSON.parse(String(show.stdout || ""));
-          } catch {
-            meta = null;
-          }
-        }
-      }
-      const inferred = meta && typeof meta === "object" ? String(meta.base_branch || "").trim() : "";
-      if (!inferred) {
-        throw new UserError("Cannot infer base branch for finish.", {
-          details: "Hint: run from the target branch (e.g. main), or pass: `aiws change finish <id> --into <branch>`.",
-        });
-      }
-      into = inferred;
-    }
-  }
-
-  if (into === changeBranch) {
-    throw new UserError("change finish: target branch cannot be the change branch.", { details: `target=${into}` });
-  }
-
-  const worktrees = await listGitWorktrees(gitRoot);
-  const intoRef = `refs/heads/${into}`;
-  const intoWt = worktrees.find((w) => String(w.branch || "") === intoRef);
-  if (intoWt && path.resolve(intoWt.worktree) !== path.resolve(gitRoot)) {
-    throw new UserError("Target branch is checked out in another worktree.", {
-      details: `branch: ${into}\nworktree: ${intoWt.worktree}\n\nHint: run finish in that worktree:\n  cd ${intoWt.worktree}\n  aiws change finish ${changeId}`,
-    });
-  }
-
-  const hasIntoBranch = await runCommand("git", ["show-ref", "--verify", "--quiet", intoRef], { cwd: gitRoot }).then((r) => r.code === 0);
-  if (!hasIntoBranch) {
-    throw new UserError("Target branch does not exist.", { details: `branch: ${into}` });
-  }
+  const { changeId, changeBranch, into, cur, changeWt } = await resolveFinishContext(gitRoot, options);
 
   if (cur && cur !== into) {
     const sw = await runCommand("git", ["switch", into], { cwd: gitRoot });
@@ -1792,8 +2184,6 @@ export async function changeFinishCommand(options) {
 
   const merge = await runCommand("git", ["merge", "--ff-only", changeBranch], { cwd: gitRoot });
   if (merge.code !== 0) {
-    const changeRef = changeBranchRef;
-    const changeWt = worktrees.find((w) => String(w.branch || "") === changeRef);
     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}`
@@ -1806,9 +2196,51 @@ export async function changeFinishCommand(options) {
   console.log(`ok: finished change: ${changeId}`);
   console.log(`into: ${into}`);
   console.log(`from: ${changeBranch}`);
-  if (await pathExists(path.join(gitRoot, ".gitmodules"))) {
+
+  if (options.push === true) {
+    const submodulePush = await pushSubmodulesForFinish(gitRoot, changeId, into, changeWt?.worktree);
+    if (submodulePush.processed > 0) {
+      console.log(`submodule push: ok (${submodulePush.processed} repos)`);
+    }
+
+    const pushTarget = await resolvePushTarget(gitRoot, into, options.remote);
+    const push = await runCommand("git", ["push", pushTarget.remote, pushTarget.refspec], { cwd: gitRoot });
+    if (push.code !== 0) {
+      throw new UserError("Finished locally, but failed to push target branch.", {
+        details:
+          `remote: ${pushTarget.remote}\nlocal_branch: ${into}\nremote_branch: ${pushTarget.remoteBranch}\n` +
+          (pushTarget.trackedMergeRef ? `tracked_merge: ${pushTarget.trackedMergeRef}\n` : "") +
+          `\n${push.stderr || push.stdout}`,
+      });
+    }
+
+    console.log(`push: ok (${pushTarget.remote} ${into}${pushTarget.remoteBranch !== into ? ` -> ${pushTarget.remoteBranch}` : ""})`);
+
+    console.log(`push: target ${pushTarget.remote} ${into}${pushTarget.remoteBranch !== into ? ` -> ${pushTarget.remoteBranch}` : ""}`);
+
+    if (changeWt?.worktree) {
+      const cleanup = await cleanupWorktreePath(gitRoot, changeWt.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 {
+      console.log("cleanup: skipped (no separate change worktree)");
+    }
+  }
+
+  if (options.push === true && (await listSubmodulesFromGitmodules(gitRoot)).length > 0) {
     console.log("next:");
-    console.log("  - (optional) update submodules: git submodule update --init --recursive");
+    console.log("  - submodules already synced for finish --push; rerun `git submodule update --init --recursive` only if another worktree changed them later");
   }
 }
 

package/src/commands/hooks-install.js

@@ -61,7 +61,7 @@ export async function hooksInstallCommand(options) {
   const templateId = await resolveTemplateIdForRepo(gitRoot);
   const tpl = await loadTemplate(templateId);
 
-  const hookFiles = [".githooks/pre-commit", ".githooks/pre-push"];
+  const hookFiles = [".githooks/commit-msg", ".githooks/pre-commit", ".githooks/pre-push"];
   /** @type {string[]} */
   const created = [];
   /** @type {string[]} */
@@ -90,4 +90,3 @@ export async function hooksInstallCommand(options) {
   if (created.length > 0) console.log(`created: ${created.join(", ")}`);
   if (chmodded.length > 0) console.log(`chmod: ${chmodded.join(", ")}`);
 }
-

package/src/commands/hooks-status.js

@@ -51,15 +51,22 @@ export async function hooksStatusCommand(options) {
   const normalizedHooksPath = hooksPath.replace(/[\\/]+$/, "");
 
   const githooksDir = path.join(gitRoot, ".githooks");
+  const commitMsg = path.join(githooksDir, "commit-msg");
   const preCommit = path.join(githooksDir, "pre-commit");
   const prePush = path.join(githooksDir, "pre-push");
 
   const githooksExists = await pathExists(githooksDir);
+  const commitMsgExists = await pathExists(commitMsg);
   const preCommitExists = await pathExists(preCommit);
   const prePushExists = await pathExists(prePush);
 
+  let commitMsgExec = false;
   let preCommitExec = false;
   let prePushExec = false;
+  if (commitMsgExists) {
+    const st = await fs.stat(commitMsg);
+    commitMsgExec = isExecutable(st);
+  }
   if (preCommitExists) {
     const st = await fs.stat(preCommit);
     preCommitExec = isExecutable(st);
@@ -72,6 +79,7 @@ export async function hooksStatusCommand(options) {
   console.log(`✓ aiws hooks status: ${gitRoot}`);
   console.log(`core.hooksPath: ${hooksPath ? hooksPath : "(default: .git/hooks)"}`);
   console.log(`.githooks/: ${githooksExists ? "ok" : "missing"}`);
+  console.log(`.githooks/commit-msg: ${commitMsgExists ? (commitMsgExec ? "ok" : "not-executable") : "missing"}`);
   console.log(`.githooks/pre-commit: ${preCommitExists ? (preCommitExec ? "ok" : "not-executable") : "missing"}`);
   console.log(`.githooks/pre-push: ${prePushExists ? (prePushExec ? "ok" : "not-executable") : "missing"}`);
 
@@ -80,7 +88,7 @@ export async function hooksStatusCommand(options) {
     console.log("Next: aiws hooks install .");
     return;
   }
-  if (!githooksExists || !preCommitExists || !prePushExists || !preCommitExec || !prePushExec) {
+  if (!githooksExists || !commitMsgExists || !preCommitExists || !prePushExists || !commitMsgExec || !preCommitExec || !prePushExec) {
     console.log("Next: aiws hooks install .");
     return;
   }

package/src/commands/update.js

@@ -1,3 +1,4 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { loadTemplate } from "../spec.js";
 import { loadAiwsPackage } from "../aiws-package.js";
@@ -59,13 +60,32 @@ export async function updateCommand(options) {
     }
   }
 
+  const removeFiles = (update.remove || []).map(normalizeRel);
+
   const backup = new BackupSession({ workspaceRoot, operation: "update" });
   // Backup every file we might touch (including missing, for rollback deletions).
   await backup.recordFile(".aiws/manifest.json", { recordMissing: true });
   for (const f of replaceFiles) await backup.recordFile(f, { recordMissing: true });
   for (const f of Object.keys(managedBlocks)) await backup.recordFile(f, { recordMissing: true });
+  for (const f of removeFiles) await backup.recordFile(f);
   await backup.finalize({ extra: { template_id: tpl.templateId } });
 
+  // Remove deprecated files (backed up above; restorable via `aiws rollback`).
+  let removedCount = 0;
+  for (const rel of removeFiles) {
+    if (!rel) continue;
+    const abs = joinRel(workspaceRoot, rel);
+    if (await pathExists(abs)) {
+      await fs.rm(abs, { force: true });
+      removedCount++;
+      // Remove empty parent directory (safe: rmdir fails on non-empty).
+      try { await fs.rmdir(path.dirname(abs)); } catch { /* non-empty or gone */ }
+    }
+  }
+  if (removedCount > 0) {
+    console.log(`  removed ${removedCount} deprecated file(s)`);
+  }
+
   // Replace files (except manifest, generated later).
   for (const rel of replaceFiles) {
     if (!rel || rel === ".aiws/manifest.json") continue;

package/src/commands/validate.js

@@ -36,7 +36,7 @@ async function validateSubmoduleBranchPolicy(workspaceRoot) {
     if (idx <= 0) continue;
     const key = t.slice(0, idx).trim();
     const subPath = t.slice(idx + 1).trim();
-    const m = key.match(/^submodule\.([^.]+)\.path$/);
+    const m = key.match(/^submodule\.(.+)\.path$/);
     if (!m) continue;
     const name = m[1] || "";
     if (!name || !subPath) continue;