pan-wizard 3.24.0 → 3.25.0

package/agents/pan-conductor.md

@@ -192,7 +192,7 @@ This agent file ships to all runtimes (keeps the installer uniform), but only ge
 When invoked by `/pan:army` (ADR-0033), you are **Mission Control** for a whole-project campaign, not a single phase — same harness, wider scope. The differences:
 
 - **You delegate to squads, not bare agents.** Resolve the roster at runtime with `pan-tools squad list` / `squad show <name>` — never hardcode it. Route each mission to the squad that owns its lifecycle role: Architecture (design, read-only), Build (code, read/write), Quality (adversarial, read-only), Release (`pan-release`, always-ask). Workers (document_code, distiller) take narrow, high-volume jobs; they are the agents the `budget` profile drops to the `fast` tier, and run at the inherited reasoning tier otherwise.
-- **Build parallelizes by worktree.** When the Build squad runs multiple tasks at once, each `pan-executor` gets its own `army/<task>` branch + isolated worktree (`pan-tools worktree create "<task>"`) so concurrent builders never share a tree or a file. The spawn cap and budget ceiling still bound the fan-out.
+- **Build parallelizes by worktree — and you tear the worktrees down.** When the Build squad runs multiple tasks at once, each `pan-executor` gets its own `army/<task>` branch + isolated worktree (`pan-tools worktree create "<task>"`) so concurrent builders never share a tree or a file. The spawn cap and budget ceiling still bound the fan-out. Those worktrees are scaffolding: after each task's squash-merge lands, `pan-tools worktree remove <path> --branch army/<task>`; at campaign end or on any abort, `pan-tools worktree cleanup` sweeps the strays (`--force` to also discard dirty or unintegrated ones). Leaving `pan-army-*` sibling directories behind is a campaign defect, not residue (P-1815).
 - **Integration is human-gated.** You never merge to a protected branch. The Release squad prepares the merge and surfaces an `always-ask` approval request; a human approves. Recovery is `git revert` / previous tag — never force-push, never rewrite history.
 - **The loop carries learnings.** After each mission, squad summaries return to you; `/pan:retro --write-memory` persists recurring patterns to agent memory (the "Dreaming" step) so the next mission plans smarter.
 

package/commands/pan/army.md

@@ -133,6 +133,8 @@ Spawn the Quality squad on the built tree (parallel, read-only). Merge findings
 ### Phase 5 — Integrate (Release, human-gated)
 Spawn `pan-release`. It prepares the squash-merge, runs the configured `verification`, and surfaces an **always-ask** approval request. A human approves the merge to the protected branch; release then tags and records the rollback target. `--push` pushes the approved result.
 
+**Teardown after the merge lands (P-1815):** worktrees are scaffolding, not deliverables — the squash-merge is the permanent artifact. Once the approval lands, remove each integrated task's worktree **and** its branch in one call: `pan-tools worktree remove ../pan-army-<slug> --branch army/<slug>`. The `--branch` half is not optional: a squash-merged branch never looks merged to git, so nothing else will ever clean it. At campaign end — and on **any** abort path — sweep whatever remains: `pan-tools worktree cleanup` (`--force` also discards dirty worktrees and unintegrated branches; without it the sweep keeps anything that might hold the only copy of work, and says exactly why and how to delete it). A campaign that ends with `pan-tools worktree list` non-empty has skipped this step.
+
 **Phase report (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the mission's self-contained per-phase HTML report **in the built tree, before staging the squash-merge** — `pan-tools report phase <N>` — so the report rides along in the merge as a phase deliverable. **Never run `report index` inside a squad worktree:** the timeline index is a single shared file that aggregates *all* phases, so a worktree would see only its own phase and concurrent squads would race on it. The index is a single-writer, post-merge concern (Phase 6). Never opens a browser.
 
 ### Phase 6 — Learn (Dreaming)
@@ -142,6 +144,18 @@ Squad summaries return to Mission Control. Run `/pan:retro --write-memory` (and
 
 ---
 
+<output_paths>
+
+- the project tree + `.planning/orchestration/` — mission state, reports, loop-state (permanent)
+- `<parent-of-project>/pan-army-<task-slug>/` — one worktree per Build task, a **sibling of the project directory** (temporary — removed per task by the Phase 5 teardown; strays swept by `pan-tools worktree cleanup`)
+- branches `army/<task-slug>` — the worktrees' branches (temporary — deleted with their worktree once the squash-merge lands; squash-merged branches never look merged to git and must be deleted explicitly)
+
+Nothing under `pan-army-*` or on an `army/*` branch is a deliverable: the squash-merge into the protected branch is the permanent artifact, same doctrine as what-if's disposable worktrees.
+
+</output_paths>
+
+---
+
 ## Scheduled, self-resuming campaigns (ADR-0034)
 
 PAN is not a daemon — it cannot wake itself while the session is closed. `--schedule` arms a campaign and lets an external trigger drive it; the human merge gate is never relaxed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.24.0",
+  "version": "3.25.0",
   "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"

package/pan-wizard-core/bin/lib/worktree.cjs

@@ -89,6 +89,91 @@ function listArmyWorktrees(cwd) {
   return out;
 }
 
+/**
+ * Sweep every army worktree and orphaned army/ branch (P-1815, PanLoop
+ * finding 13). The what-if subsystem always had this (`whatif cleanup`); the
+ * army path created worktrees that nothing removed — sibling `pan-army-*`
+ * directories and `army/*` branches accumulated after every campaign.
+ *
+ * Safety posture (the L3 lesson — never trade clutter for silent data loss):
+ * - A DIRTY worktree is kept unless `force` — git refuses, we surface why.
+ * - A branch is deleted only when its tip is reachable from HEAD (truly
+ *   integrated). Squash-merged and aborted branches are NOT reachable and may
+ *   hold the only copy of real work, so by default they are KEPT and listed
+ *   with the exact command to delete them; `force` sweeps them too.
+ *   (The per-task Phase 5 teardown — `worktree remove --branch` right after
+ *   the merge lands — deletes unconditionally; at that moment the deletion is
+ *   the documented intent. The sweeper is the abort/orphan tool, so it errs
+ *   the other way.)
+ * @param {string} cwd - main project root
+ * @param {Object} [opts] - { force: boolean }
+ * @returns {{removed_worktrees, deleted_branches, kept, pruned, clean}|{error}}
+ */
+function cleanupArmyWorktrees(cwd, opts) {
+  if (!isGitRepo(cwd)) return { error: 'Not a git repo' };
+  const force = opts?.force === true;
+  const removedWorktrees = [];
+  const deletedBranches = [];
+  const kept = [];
+
+  const branchIsIntegrated = (branch) =>
+    execGit(cwd, ['merge-base', '--is-ancestor', branch, 'HEAD']).exitCode === 0;
+
+  const deleteBranch = (branch, hadWorktree) => {
+    if (force || branchIsIntegrated(branch)) {
+      const del = execGit(cwd, ['branch', '-D', branch]);
+      if (del.exitCode === 0) deletedBranches.push(branch);
+      else kept.push({ branch, reason: `branch -D failed: ${del.stderr.trim()}` });
+    } else {
+      kept.push({
+        branch,
+        reason: `carries commits not reachable from HEAD (squash-merged or aborted work${hadWorktree ? '' : '; no worktree attached'}) — rerun with --force, or: git branch -D ${branch}`,
+      });
+    }
+  };
+
+  // 1. Registered army worktrees. Track every branch step 1 has already
+  //    decided on — deleted OR deliberately kept — so the orphan scan below
+  //    does not re-process (and double-report) it.
+  const handledBranches = new Set();
+  for (const t of listArmyWorktrees(cwd)) {
+    const rmArgs = ['worktree', 'remove'];
+    if (force) rmArgs.push('--force');
+    rmArgs.push(t.worktree);
+    const rm = execGit(cwd, rmArgs);
+    if (rm.exitCode !== 0) {
+      kept.push({ worktree: t.worktree, branch: t.branch, reason: `worktree remove refused: ${rm.stderr.trim()} — pass --force to discard uncommitted changes` });
+      if (t.branch) handledBranches.add(t.branch);
+      continue;
+    }
+    removedWorktrees.push(t.worktree);
+    if (t.branch) {
+      handledBranches.add(t.branch);
+      deleteBranch(t.branch, true);
+    }
+  }
+
+  // 2. Drop stale registrations (a manually deleted directory leaves one).
+  const pruned = execGit(cwd, ['worktree', 'prune']).exitCode === 0;
+
+  // 3. Orphaned army/ branches — a worktree removed without its branch.
+  const stillAttached = new Set(listArmyWorktrees(cwd).map(t => t.branch));
+  const ls = execGit(cwd, ['branch', '--list', `${ARMY_BRANCH_PREFIX}*`, '--format=%(refname:short)']);
+  if (ls.exitCode === 0) {
+    for (const branch of ls.stdout.split(/\r?\n/).map(s => s.trim()).filter(Boolean)) {
+      if (!stillAttached.has(branch) && !handledBranches.has(branch)) deleteBranch(branch, false);
+    }
+  }
+
+  return {
+    removed_worktrees: removedWorktrees,
+    deleted_branches: deletedBranches,
+    kept,
+    pruned,
+    clean: kept.length === 0,
+  };
+}
+
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 
 function cmdWorktreeList(cwd, raw) {
@@ -112,12 +197,25 @@ function cmdWorktreeRemove(cwd, worktreePath, branch, raw, opts) {
   output(r, raw, r.warnings.length ? r.warnings.join('\n') : 'removed');
 }
 
+function cmdWorktreeCleanup(cwd, raw, opts) {
+  const r = cleanupArmyWorktrees(cwd, opts);
+  if (r.error) return error(r.error);
+  const lines = [
+    ...r.removed_worktrees.map(w => `removed worktree ${w}`),
+    ...r.deleted_branches.map(b => `deleted branch ${b}`),
+    ...r.kept.map(k => `KEPT ${k.worktree || k.branch}: ${k.reason}`),
+  ];
+  output(r, raw, lines.length ? lines.join('\n') : 'nothing to clean');
+}
+
 module.exports = {
   ARMY_BRANCH_PREFIX,
   createTaskWorktree,
   removeTaskWorktree,
   listArmyWorktrees,
+  cleanupArmyWorktrees,
   cmdWorktreeList,
   cmdWorktreeCreate,
   cmdWorktreeRemove,
+  cmdWorktreeCleanup,
 };

package/pan-wizard-core/bin/pan-tools.cjs

@@ -1191,8 +1191,10 @@ async function main() {
         worktree.cmdWorktreeCreate(cwd, args[2], raw, { base: getArgValue(args, '--base') });
       } else if (subcommand === 'remove') {
         worktree.cmdWorktreeRemove(cwd, args[2], getArgValue(args, '--branch'), raw, { force: args.includes('--force') });
+      } else if (subcommand === 'cleanup') {
+        worktree.cmdWorktreeCleanup(cwd, raw, { force: args.includes('--force') });
       } else {
-        error('Unknown worktree subcommand. Available: list, create, remove');
+        error('Unknown worktree subcommand. Available: list, create, remove, cleanup');
       }
       break;
     }