@aipper/aiws 0.0.1 → 0.0.3

package/README.md

@@ -1,54 +1,67 @@
 # @aipper/aiws
 
-AI Workspace CLI：`aiws init/update/validate/rollback`。
-
-真值来源（SSOT）：`@aipper/aiws-spec`（模板与契约在 `packages/spec/`）。
-
-需求真值：仓库根 `REQUIREMENTS.md`（TOOLING-001B）。
-
-开发期最小验证（本仓库内）：
-- `node packages/aiws/bin/aiws.js --help`
-
-Codex repo skills（推荐）：
-- `aiws init .` 会生成 `.agents/skills/`（随仓库共享）
-- 在 Codex 中可显式调用（示例）：`$ws-preflight` / `$ws-plan` / `$ws-dev` / `$ws-review` / `$ws-commit`
-
-Codex 全局 skills（推荐；可选）：
-- 安装到 `~/.codex/skills/`（或 `$CODEX_HOME/skills`）：`aiws codex install-skills`
-- 预演（不写入）：`aiws codex install-skills --dry-run`
-- 状态检查：`aiws codex status-skills`
-- 卸载（仅移除 AIWS 托管 skills；会备份）：`aiws codex uninstall-skills`
-- 本仓库内可复现验证（不写入 home）：`CODEX_HOME="$(mktemp -d)" node packages/aiws/bin/aiws.js codex install-skills`
-
-Codex 全局 prompts（遗留；deprecated）：
-- 安装到 `~/.codex/prompts/`（或 `$CODEX_HOME/prompts`）：`aiws codex install-prompts`
-- 预演（不写入）：`aiws codex install-prompts --dry-run`
-- 状态检查：`aiws codex status`
-- 卸载（仅移除 AIWS 托管 prompts；会备份）：`aiws codex uninstall-prompts`
-- 本仓库内可复现验证（不写入 home）：`CODEX_HOME="$(mktemp -d)" node packages/aiws/bin/aiws.js codex install-prompts`
-
-Git hooks 门禁（推荐）：
-- 启用（会自动补齐 `.githooks/*`，并设置 `core.hooksPath=.githooks`）：`aiws hooks install .`
-- 查看状态：`aiws hooks status .`
-- 证据落盘（可选）：`AIWS_VALIDATE_STAMP=1 aiws validate .` 会写入 `.agentdocs/tmp/aiws-validate/*.json`（`.agentdocs/` 被 `.gitignore` 忽略）
-
-Change 工作流（脱离 dotfiles）：
-- 创建工件：`aiws change new <change-id>`（生成 `changes/<change-id>/{proposal,tasks,design}.md` 与 `.ws-change.json`）
-- 切分支并初始化：`aiws change start <change-id> [--hooks]`
-- 进度/建议：`aiws change list` / `aiws change status <change-id>` / `aiws change next <change-id>`
-- 同步真值基线：`aiws change sync <change-id>`
-- 严格校验：`aiws change validate <change-id> --strict`（在你把 `WS:TODO` 与归因补齐前，预期会失败）
-- 归档：`aiws change archive <change-id>`
-
-本仓库内可复现验证（不污染本仓库）：
+AI Workspace CLI：把 Claude Code / OpenCode / Codex / iFlow 对齐到同一套“真值文件 + 可审计工作流”，降低规则漂移。
+
+核心能力：
+- 初始化/更新模板：`aiws init` / `aiws update`
+- 强门禁校验：`aiws validate`（可选证据落盘 `--stamp`）
+- 回滚：`aiws rollback`（从 `.aiws/backups/` 恢复）
+- 变更工件工作流（脱离 dotfiles）：`aiws change ...`
+- Git hooks：`aiws hooks install/status`
+- Codex：repo skills（推荐）+ 可选全局 skills 安装
+
+真值来源（SSOT）：`@aipper/aiws-spec`（模板与契约）。
+
+## 安装
+
+二选一：
+- 全局安装（推荐，适合长期使用）：`npm i -g @aipper/aiws`
+- 临时运行（不污染全局版本）：`npx @aipper/aiws <command>`
+
+## 快速开始
+
+在任意 git 仓库根目录：
 ```bash
-repo_root="$(pwd)"
-tmpdir="$(mktemp -d)"
-cd "$tmpdir"
-git init
-node "$repo_root/packages/aiws/bin/aiws.js" init .
-node "$repo_root/packages/aiws/bin/aiws.js" change new demo-change --no-design
-node "$repo_root/packages/aiws/bin/aiws.js" change list
-node "$repo_root/packages/aiws/bin/aiws.js" change sync demo-change
-node "$repo_root/packages/aiws/bin/aiws.js" change validate demo-change --strict
+aiws init .
+aiws hooks install .
+
+# 建议：用 change 工作流生成可审计工件并切分支
+aiws change start demo-change --no-design --hooks
+
+# 提交前门禁（并落盘证据）
+aiws validate . --stamp
 ```
+
+## CLI 速查
+
+```bash
+aiws init [path] [--template <id>]
+aiws update [path]
+aiws validate [path] [--stamp]
+aiws rollback [path] <timestamp|latest>
+
+aiws change <list|new|start|status|next|sync|validate|archive|templates>
+aiws hooks <install|status>
+aiws codex <install-skills|status-skills|uninstall-skills|install-prompts|status|uninstall-prompts>
+```
+
+## Codex（repo skills 优先）
+
+- `aiws init .` 会生成 `.agents/skills/`（随仓库共享），在 Codex 中可显式调用（示例）：`$ws-preflight` / `$ws-plan` / `$ws-dev` / `$ws-review` / `$ws-commit`
+- 收尾（安全合并回目标分支）：`$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward）
+- 可选：安装全局 skills 到 `~/.codex/skills/`（或 `$CODEX_HOME/skills`）：
+  - `aiws codex install-skills`
+  - `aiws codex status-skills`
+  - `aiws codex uninstall-skills`
+- legacy prompts（deprecated，仅兼容）：`aiws codex install-prompts`
+
+## 证据落盘与协作
+
+- `aiws validate --stamp` 会写入：`.agentdocs/tmp/aiws-validate/*.json`（默认被 `.gitignore` 忽略）
+- `$ws-review` 会落盘：`.agentdocs/tmp/review/codex-review.md`（默认被 `.gitignore` 忽略）
+- 建议把“可协作/可审计”的内容放进 `changes/<change-id>/`（proposal/tasks/design）并提交；`.agentdocs/tmp/` 作为本地缓存更稳
+
+## 运行要求
+
+- Node.js：>= 20
+- `aiws validate`：需要 `python3`（用于执行 `tools/ws_change_check.py` 与 `tools/requirements_contract.py`）

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@aipper/aiws",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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.1"
+    "@aipper/aiws-spec": "0.0.3"
   },
   "files": [
     "bin",

package/src/cli.js

@@ -16,6 +16,7 @@ import { hooksInstallCommand } from "./commands/hooks-install.js";
 import { hooksStatusCommand } from "./commands/hooks-status.js";
 import {
   changeArchiveCommand,
+  changeFinishCommand,
   changeListCommand,
   changeNewCommand,
   changeNextCommand,
@@ -224,14 +225,28 @@ export async function cliMain(argv) {
             title: { type: "string" },
             "no-design": { type: "boolean" },
             hooks: { type: "boolean" },
+            "no-switch": { type: "boolean" },
+            switch: { type: "boolean" },
+            worktree: { type: "boolean" },
+            "worktree-dir": { type: "string" },
+            submodules: { type: "boolean" },
           });
           const changeId = positionals[0] ?? "";
-          if (!changeId) throw new UserError("change start requires <change-id>", { details: "Usage: aiws change start <change-id> [--title <title>] [--no-design] [--hooks]" });
+          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]",
+            });
           await changeStartCommand({
             changeId,
             title: options.title,
             noDesign: options["no-design"] === true,
             enableHooks: options.hooks === true,
+            noSwitch: options["no-switch"] === true,
+            forceSwitch: options.switch === true,
+            worktree: options.worktree === true,
+            worktreeDir: options["worktree-dir"],
+            submodules: options.submodules === true,
           });
           return 0;
         }
@@ -293,6 +308,19 @@ export async function cliMain(argv) {
           });
           return 0;
         }
+        case "finish": {
+          const { positionals, options } = parseArgs(args, {
+            into: { type: "string" },
+            base: { type: "string" },
+          });
+          const changeId = positionals[0];
+          await changeFinishCommand({
+            changeId,
+            into: options.into,
+            base: options.base,
+          });
+          return 0;
+        }
         case "templates": {
           const templatesSub = args.shift();
           if (!templatesSub) throw new UserError("change templates requires <which|init>", { details: "Usage: aiws change templates which|init" });
@@ -378,7 +406,8 @@ function printChangeHelp() {
 
 Usage:
   aiws change list
-  aiws change start <change-id> [--title <title>] [--no-design] [--hooks]
+  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 new <change-id> [--title <title>] [--no-design]
   aiws change status [change-id]
   aiws change next [change-id]
@@ -391,7 +420,9 @@ Usage:
 Notes:
   - change-id must be kebab-case: ^[a-z0-9]+(-[a-z0-9]+)*$
   - If your git branch matches change/<change-id> (or changes/ws/ws-change prefixes),
-    you can omit <change-id> for status/next/validate/sync/archive.
+    you can omit <change-id> for status/next/validate/sync/archive/finish.
+  - 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.
   - archive --force also bypasses truth drift gating (not recommended).
 `);

package/src/commands/change.js

@@ -87,6 +87,122 @@ async function currentBranch(gitRoot) {
   return String(res.stdout || "").trim();
 }
 
+/**
+ * @param {string} gitRoot
+ */
+async function hasHeadCommit(gitRoot) {
+  return runCommand("git", ["rev-parse", "--verify", "HEAD"], { cwd: gitRoot }).then((r) => r.code === 0);
+}
+
+/**
+ * @param {string} gitRoot
+ * @returns {Promise<{ clean: true } | { clean: false, details: string }>}
+ */
+async function checkGitClean(gitRoot) {
+  const res = await runCommand("git", ["status", "--porcelain"], { cwd: gitRoot });
+  const out = String(res.stdout || "").trim();
+  if (!out) return { clean: true };
+  const lines = out.split("\n");
+  const truncated = lines.length > 20 ? `${lines.slice(0, 20).join("\n")}\n... (truncated)` : out;
+  return { clean: false, details: truncated };
+}
+
+/**
+ * @param {string} gitRoot
+ * @returns {Promise<{ ok: true } | { ok: false, reason: "no_commit" | "missing_truth", missing?: string[] }>}
+ */
+async function checkWorktreePrereqs(gitRoot) {
+  if (!(await 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 runCommand("git", ["cat-file", "-e", `HEAD:${rel}`], { cwd: gitRoot }).then((r) => r.code === 0);
+    if (!ok) missingInHead.push(rel);
+  }
+  if (missingInHead.length > 0) return { ok: false, reason: "missing_truth", missing: missingInHead };
+  return { ok: true };
+}
+
+/**
+ * @param {string} changeDir
+ * @param {string} baseBranch
+ * @param {string} changeBranch
+ */
+async function maybeRecordBaseBranch(changeDir, baseBranch, changeBranch) {
+  const b = String(baseBranch || "").trim();
+  if (!b) return;
+  if (b === String(changeBranch || "").trim()) return;
+  const metaPath = path.join(changeDir, ".ws-change.json");
+  if (!(await pathExists(metaPath))) return;
+  /** @type {any} */
+  let meta = null;
+  try {
+    meta = JSON.parse(await readText(metaPath));
+  } catch {
+    meta = null;
+  }
+  if (!meta || typeof meta !== "object") return;
+  const cur = String(meta.base_branch || "").trim();
+  if (cur) return;
+  meta.base_branch = b;
+  meta.base_branch_set_at = nowIsoUtc();
+  await writeText(metaPath, JSON.stringify(meta, null, 2) + "\n");
+}
+
+/**
+ * @param {string} gitRoot
+ * @returns {Promise<Array<{ worktree: string, head: string, branch: 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 }>} */
+  const out = [];
+  /** @type {{ worktree: string, head: string, branch: 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: "" };
+      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 (cur) out.push(cur);
+  return out;
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string | undefined} worktreeDir
+ * @param {string} changeId
+ */
+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} branch
  * @returns {string}
@@ -508,12 +624,10 @@ export async function changeTemplatesInitCommand() {
 }
 
 /**
- * aiws change new
- *
- * @param {{ changeId: string, title?: string, noDesign: boolean }} options
+ * @param {string} gitRoot
+ * @param {{ changeId: string, title?: string, noDesign: boolean, baseBranch?: string }} options
  */
-export async function changeNewCommand(options) {
-  const gitRoot = await resolveGitRoot(process.cwd());
+async function changeNewAtGitRoot(gitRoot, options) {
   await ensureTruthFiles(gitRoot);
 
   const changeId = String(options.changeId || "").trim();
@@ -551,6 +665,11 @@ export async function changeNewCommand(options) {
     created_at: createdAt,
     base_truth_files: truth,
   };
+  const baseBranch = String(options.baseBranch || "").trim();
+  if (baseBranch) {
+    meta.base_branch = baseBranch;
+    meta.base_branch_set_at = createdAt;
+  }
   await writeText(path.join(changeDir, ".ws-change.json"), JSON.stringify(meta, null, 2) + "\n");
 
   console.log(`✓ aiws change new: ${changeId}`);
@@ -563,10 +682,20 @@ export async function changeNewCommand(options) {
   console.log(`  - validate: aiws change validate ${changeId}`);
 }
 
+/**
+ * aiws change new
+ *
+ * @param {{ changeId: string, title?: string, noDesign: boolean }} options
+ */
+export async function changeNewCommand(options) {
+  const gitRoot = await resolveGitRoot(process.cwd());
+  await changeNewAtGitRoot(gitRoot, options);
+}
+
 /**
  * aiws change start
  *
- * @param {{ changeId: string, title?: string, noDesign: boolean, enableHooks: boolean }} options
+ * @param {{ changeId: string, title?: string, noDesign: boolean, enableHooks: boolean, noSwitch: boolean, forceSwitch: boolean, worktree: boolean, worktreeDir?: string, submodules: boolean }} options
  */
 export async function changeStartCommand(options) {
   const gitRoot = await resolveGitRoot(process.cwd());
@@ -575,33 +704,220 @@ export async function changeStartCommand(options) {
   const changeId = String(options.changeId || "").trim();
   assertValidChangeId(changeId);
 
+  const startFromBranch = await currentBranch(gitRoot);
   const branch = `change/${changeId}`;
+  const branchRef = `refs/heads/${branch}`;
+
+  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);
-  if (hasBranch) {
-    const sw = await runCommand("git", ["switch", branch], { cwd: gitRoot });
-    if (sw.code !== 0) {
-      const co = await runCommand("git", ["checkout", branch], { cwd: gitRoot });
-      if (co.code !== 0) throw new UserError("Failed to switch branch.", { details: co.stderr || co.stdout });
+  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);
+    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)");
+    }
+  } 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");
+  }
+
+  if (effectiveWorktree) {
+    const prereq = await checkWorktreePrereqs(gitRoot);
+    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);
+    }
+
+    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)");
+    }
+
+    if (options.enableHooks) {
+      await hooksInstallCommand({ targetPath: gitRoot });
+    }
+
+    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;
+
+  if (effectiveNoSwitch) {
+    if (!hasBranch) {
+      if (!headReady) {
+        // On an unborn branch, `git branch <name>` fails because HEAD doesn't point to a commit yet.
+        // We still allow initializing change artifacts without switching branches.
+        console.error(`warn: repo has no commits; cannot create branch "${branch}" without switching (skipped)`);
+        branchReady = false;
+      } else {
+        const br = await runCommand("git", ["branch", branch], { cwd: gitRoot });
+        if (br.code !== 0) throw new UserError("Failed to create branch.", { details: br.stderr || br.stdout });
+        branchReady = true;
+      }
     }
   } else {
-    const sw = await runCommand("git", ["switch", "-c", branch], { cwd: gitRoot });
-    if (sw.code !== 0) {
-      const co = await runCommand("git", ["checkout", "-b", branch], { cwd: gitRoot });
-      if (co.code !== 0) throw new UserError("Failed to create branch.", { details: co.stderr || co.stdout });
+    if (hasBranch) {
+      const sw = await runCommand("git", ["switch", branch], { cwd: gitRoot });
+      if (sw.code !== 0) {
+        const co = await runCommand("git", ["checkout", branch], { cwd: gitRoot });
+        if (co.code !== 0) throw new UserError("Failed to switch branch.", { details: co.stderr || co.stdout });
+      }
+    } else {
+      const sw = await runCommand("git", ["switch", "-c", branch], { cwd: gitRoot });
+      if (sw.code !== 0) {
+        const co = await runCommand("git", ["checkout", "-b", branch], { cwd: gitRoot });
+        if (co.code !== 0) throw new UserError("Failed to create branch.", { details: co.stderr || co.stdout });
+      }
     }
+    branchReady = true;
   }
 
   const changeDir = changeDirAbs(gitRoot, changeId);
   if (!(await pathExists(changeDir))) {
-    await changeNewCommand({ changeId, title: options.title, noDesign: options.noDesign });
+    await changeNewAtGitRoot(gitRoot, {
+      changeId,
+      title: options.title,
+      noDesign: options.noDesign,
+      baseBranch: startFromBranch && startFromBranch !== branch ? startFromBranch : undefined,
+    });
+  } else {
+    await maybeRecordBaseBranch(changeDir, startFromBranch, branch);
   }
 
   if (options.enableHooks) {
     await hooksInstallCommand({ targetPath: gitRoot });
   }
 
-  console.log(`ok: active change: ${changeId} (branch: ${branch})`);
+  const cur = await currentBranch(gitRoot);
+  const curLabel = cur || "(detached)";
+  if (effectiveNoSwitch && cur !== branch) {
+    console.log(`ok: prepared change: ${changeId} (branch: ${branch}${branchReady ? "" : " (pending)"}; current: ${curLabel})`);
+    console.log("next:");
+    if (branchReady) {
+      console.log(`  - switch:   git switch ${branch}`);
+    } else {
+      console.log("  - note:     repo has no commits; create the branch after your first commit");
+      console.log(`  - create:   git branch ${branch}`);
+      console.log(`  - switch:   git switch ${branch}`);
+    }
+    console.log(`  - status:   aiws change status ${changeId}`);
+    console.log(`  - next:     aiws change next ${changeId}`);
+    console.log(`  - validate: aiws change validate ${changeId} --strict`);
+    if (!options.enableHooks) console.log("  - (optional) enable hooks: aiws hooks install .");
+    return;
+  }
+
+  console.log(`ok: active change: ${changeId} (branch: ${branch}; current: ${curLabel})`);
   console.log("next:");
   console.log("  - status:   aiws change status");
   console.log("  - next:     aiws change next");
@@ -609,6 +925,130 @@ export async function changeStartCommand(options) {
   if (!options.enableHooks) console.log("  - (optional) enable hooks: aiws hooks install .");
 }
 
+/**
+ * aiws change finish
+ *
+ * @param {{ changeId?: string, into?: string, base?: 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}` });
+  }
+
+  if (cur && cur !== into) {
+    const sw = await runCommand("git", ["switch", into], { cwd: gitRoot });
+    if (sw.code !== 0) {
+      const co = await runCommand("git", ["checkout", into], { cwd: gitRoot });
+      if (co.code !== 0) throw new UserError("Failed to switch target branch.", { details: co.stderr || co.stdout });
+    }
+  }
+
+  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}`
+        : `\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}` });
+  }
+
+  console.log(`ok: finished change: ${changeId}`);
+  console.log(`into: ${into}`);
+  console.log(`from: ${changeBranch}`);
+  if (await pathExists(path.join(gitRoot, ".gitmodules"))) {
+    console.log("next:");
+    console.log("  - (optional) update submodules: git submodule update --init --recursive");
+  }
+}
+
 /**
  * aiws change status
  *

package/src/template.js

@@ -6,6 +6,40 @@ import { normalizeNewlines } from "./hash.js";
 import { extractTemplateBlock, upsertManagedBlock } from "./managed-blocks.js";
 import { UserError } from "./errors.js";
 
+/**
+ * Template file candidates for a given manifest/workspace path.
+ *
+ * NOTE: npm excludes files named `.gitignore` from published tarballs, even when placed under templates/.
+ * We store it as `gitignore` in templates and map it back at runtime.
+ *
+ * @param {string} relPosix
+ * @returns {string[]}
+ */
+function templateRelCandidates(relPosix) {
+  const rel = normalizeRel(relPosix);
+  if (!rel) return [];
+  /** @type {string[]} */
+  const out = [rel];
+  if (rel === ".gitignore" || rel.endsWith("/.gitignore")) {
+    out.push(rel.replace(/(^|\/)\.gitignore$/, "$1gitignore"));
+  }
+  return Array.from(new Set(out));
+}
+
+/**
+ * Resolve a template source file path for a given workspace-relative path.
+ *
+ * @param {string} templateDir
+ * @param {string} relPosix
+ */
+async function resolveTemplateSourcePath(templateDir, relPosix) {
+  for (const cand of templateRelCandidates(relPosix)) {
+    const abs = templatePath(templateDir, cand);
+    if (await pathExists(abs)) return abs;
+  }
+  return templatePath(templateDir, relPosix);
+}
+
 /**
  * Expand manifest paths, supporting patterns ending with `/**`.
  *
@@ -48,9 +82,13 @@ export function templatePath(templateDir, relPosix) {
  * @param {{ templateDir: string, workspaceRoot: string, relPosix: string, chmod?: number }} options
  */
 export async function copyTemplateFileToWorkspace(options) {
-  const src = templatePath(options.templateDir, options.relPosix);
-  const dest = joinRel(options.workspaceRoot, options.relPosix);
-  if (!(await pathExists(src))) throw new UserError(`Template file missing: ${options.relPosix}`, { details: `Missing: ${src}` });
+  const rel = normalizeRel(options.relPosix);
+  const src = await resolveTemplateSourcePath(options.templateDir, rel);
+  const dest = joinRel(options.workspaceRoot, rel);
+  if (!(await pathExists(src))) {
+    const tried = templateRelCandidates(rel).map((c) => templatePath(options.templateDir, c));
+    throw new UserError(`Template file missing: ${options.relPosix}`, { details: `Tried:\n- ${tried.join("\n- ")}` });
+  }
   await copyFile(src, dest, typeof options.chmod === "number" ? { chmod: options.chmod } : undefined);
 }
 
@@ -63,9 +101,12 @@ export async function copyTemplateFileToWorkspace(options) {
 export async function applyManagedBlocksFromTemplate(options) {
   const fileRel = normalizeRel(options.fileRel);
   const dest = joinRel(options.workspaceRoot, fileRel);
-  const src = templatePath(options.templateDir, fileRel);
+  const src = await resolveTemplateSourcePath(options.templateDir, fileRel);
 
-  if (!(await pathExists(src))) throw new UserError(`Template file missing: ${fileRel}`);
+  if (!(await pathExists(src))) {
+    const tried = templateRelCandidates(fileRel).map((c) => templatePath(options.templateDir, c));
+    throw new UserError(`Template file missing: ${fileRel}`, { details: `Tried:\n- ${tried.join("\n- ")}` });
+  }
   const templateText = normalizeNewlines(await readText(src));
 
   if (!(await pathExists(dest))) {
@@ -104,4 +145,3 @@ export async function ensureWorkspaceDir(workspaceRoot, relPosix) {
   const abs = joinRel(workspaceRoot, relPosix);
   await fs.mkdir(abs, { recursive: true });
 }
-