@polymorphism-tech/morph-spec 8.31.0 → 8.33.0

package/src/lib/worktree/worktree-audit.js

@@ -15,14 +15,16 @@
  *
  * Read-only and fail-open: anything unresolvable yields no issue rather than a
  * throw. A diagnostic that invents problems is worse than one that misses some.
- * The one mutation lives in `pruneWorktrees`, and it is deliberately the safest
- * possible: `git worktree prune` drops ADMIN RECORDS for directories that are
- * already gone. Deleting a directory that still exists stays a human decision —
- * the same PROVE-or-DECLINE discipline `teardownWorktree` follows.
+ * The mutations all live in `pruneWorktrees`, and each is deliberately the
+ * safest possible: `git worktree prune` drops ADMIN RECORDS for directories
+ * that are already gone, and the empty-residue sweep removes only directories
+ * with zero entries inside — nothing that can hold work. Deleting a directory
+ * that still HOLDS something stays a human decision, the same PROVE-or-DECLINE
+ * discipline `teardownWorktree` follows.
  */
 
 import { execFileSync } from 'child_process';
-import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, rmdirSync, statSync } from 'fs';
 import { join, resolve } from 'path';
 import {
   isGitRepo,
@@ -31,6 +33,9 @@ import {
   WORKTREE_DIR_NAMES,
   clearDanglingWorktreeRegistration,
 } from '../../commands/project/worktree.js';
+import { detectDefaultBranch } from '../git/default-branch.js';
+import { buildPrIndex } from '../git/pr-index.js';
+import { classifyBranch, commitsAhead, resolveBaseRef } from '../git/branch-classifier.js';
 
 const norm = (p) => resolve(p).replace(/\\/g, '/');
 
@@ -66,6 +71,54 @@ function featureCommittedOnBranch(root, feature) {
   }
 }
 
+/**
+ * Does this worktree's branch still hold work that is NOT in the default
+ * branch, or an OPEN PR?
+ *
+ * This is the predicate that separates "an orphan directory to clean up" from
+ * "the only copy of somebody's work". Two independent pieces of evidence, and
+ * ANY of them is enough to protect the worktree:
+ *
+ *   1. commits the default branch does not have (`git rev-list base..branch`)
+ *   2. an OPEN pull request on that branch
+ *
+ * Fail-CLOSED, and that asymmetry is the whole design: whenever the answer
+ * cannot be established — no default branch, no origin, git errored — the
+ * worktree counts as UNINTEGRATED. The cost of being wrong that way is a
+ * diagnostic that stays quiet; the cost of the opposite is a suggestion to
+ * delete work that exists nowhere else.
+ *
+ * A squash-merged branch legitimately reports commits ahead, so the tree
+ * comparison (`branch-classifier.js`) is consulted for the same reason
+ * `branch prune` needs it — the two must not disagree about "is this in".
+ *
+ * @returns {{ unintegrated: boolean, evidence: string, pr: number|null }}
+ */
+function unintegratedWork(root, branchRef, prIndex) {
+  const branch = (branchRef || '').replace(/^refs\/heads\//, '');
+  if (!branch) return { unintegrated: true, evidence: 'não foi possível resolver a branch do worktree', pr: null };
+
+  const pr = prIndex?.get(branch) ?? null;
+  if (pr?.state === 'OPEN') return { unintegrated: true, evidence: `PR #${pr.number} OPEN`, pr: pr.number };
+
+  const defaultBranch = detectDefaultBranch(root);
+  const baseRef = resolveBaseRef(defaultBranch, root);
+  if (!baseRef) return { unintegrated: true, evidence: 'sem branch default resolvível para comparar', pr: null };
+
+  const ahead = commitsAhead(baseRef, branch, root);
+  if (ahead === null) return { unintegrated: true, evidence: `não foi possível comparar com ${baseRef}`, pr: null };
+  if (ahead === 0) return { unintegrated: false, evidence: `nenhum commit fora de ${baseRef}`, pr: pr?.number ?? null };
+
+  // Commits ahead, but the work may still be IN: a squash-merge leaves exactly
+  // that shape. Reuse the classifier so `doctor` and `branch prune` cannot
+  // reach opposite conclusions about the same branch.
+  const verdict = classifyBranch({ name: branch, sha: '', current: false, worktreePath: null }, { baseRef, cwd: root, pr });
+  if (verdict.kind === 'merged-ancestral' || verdict.kind === 'merged-squash') {
+    return { unintegrated: false, evidence: verdict.reason, pr: pr?.number ?? null };
+  }
+  return { unintegrated: true, evidence: `${ahead} commit(s) fora de ${baseRef}`, pr: pr?.number ?? null };
+}
+
 /**
  * Every feature's `worktree` registration in the primary root — the OTHER
  * direction from `knownFeatures`/`dirsOnDisk`: not "does git/disk know about
@@ -96,6 +149,22 @@ function featureRegistrations(root) {
   return out;
 }
 
+/**
+ * Is this directory literally empty — zero entries, dotfiles included?
+ *
+ * The whole point of the distinction: an empty residue holds nothing that can
+ * be lost, so it can be removed without a human looking at it. Anything else —
+ * including a directory we cannot read — is reported as NON-empty, because the
+ * safe answer to "might there be work in here?" is yes.
+ */
+function isEmptyDir(path) {
+  try {
+    return readdirSync(path).length === 0;
+  } catch {
+    return false; // unreadable → treat as occupied
+  }
+}
+
 /** Directories physically present under either worktree root. */
 function dirsOnDisk(root) {
   const found = [];
@@ -106,7 +175,9 @@ function dirsOnDisk(root) {
       for (const name of readdirSync(base)) {
         const full = join(base, name);
         try {
-          if (statSync(full).isDirectory()) found.push({ name, path: norm(full), container: dirName });
+          if (statSync(full).isDirectory()) {
+            found.push({ name, path: norm(full), container: dirName, empty: isEmptyDir(full) });
+          }
         } catch { /* unreadable entry — skip */ }
       }
     } catch { /* fail-open */ }
@@ -125,7 +196,13 @@ function dirsOnDisk(root) {
  *   • unregistered-dir          — a directory under worktrees/ git never
  *                                 registered
  *   • no-feature                — a `morph/{f}` worktree for a feature morph
- *                                 does not know
+ *                                 does not know AND whose branch carries
+ *                                 nothing that is not already integrated
+ *   • unintegrated-work (info)  — the same shape, except the branch still holds
+ *                                 commits the default does not, or an OPEN PR.
+ *                                 Reported so the reader knows why no removal
+ *                                 is suggested — this worktree may be the ONLY
+ *                                 copy of the work
  *   • dangling-registration     — a feature's ROOT feature.json still points
  *                                 at a `worktree.path` that no longer exists
  *                                 (the symmetric OTHER direction from
@@ -144,6 +221,11 @@ export function auditWorktrees(cwd = process.cwd()) {
   const rootNorm = norm(root);
   const issues = [];
 
+  // ONE `gh pr list` for the whole audit — null means UNKNOWN (no gh, not
+  // GitHub, not authenticated), never "no PRs"; `unintegratedWork` treats the
+  // two differently on purpose.
+  const prIndex = buildPrIndex(root);
+
   const registered = parseWorktreeList(root);
   const registeredPaths = new Set();
   const features = knownFeatures(root);
@@ -169,27 +251,65 @@ export function auditWorktrees(cwd = process.cwd()) {
       // a worktree the user keeps elsewhere is none of morph's business.
       const inContainer = WORKTREE_DIR_NAMES.some((d) => path.startsWith(`${rootNorm}/${d}/`));
       if (inContainer) {
-        issues.push({
-          type: 'non-morph-branch',
-          path,
-          detail: `${path} está em ${entry.branch || 'HEAD destacado'}, não numa branch morph/* — o \`fleet\` não o enxerga`,
-          // NEVER raw `git worktree remove` here: it follows the infra junctions
-          // out and empties the primary root's .claude/ and .morph/framework/.
-          // `worktree remove` drops them first (PROVE-or-DECLINE) and takes
-          // --target precisely for worktrees like this one, with no feature.
-          fix: `morph-spec worktree remove --target "${path}"  (se já não serve)`,
-        });
+        // Same hazard as `no-feature` below, and it needs the same guard:
+        // "invisible to fleet" says nothing about whether the WORK is safe
+        // elsewhere. A worktree on a `feat/*` branch with an open PR is the
+        // most normal thing in the world, and suggesting its removal is a
+        // suggestion to destroy the only copy.
+        const work = unintegratedWork(root, entry.branch, prIndex);
+        issues.push(work.unintegrated
+          ? {
+            type: 'unintegrated-work',
+            severity: 'info',
+            path,
+            detail: `${path} está em ${entry.branch || 'HEAD destacado'} (o \`fleet\` não o enxerga) e carrega trabalho NÃO integrado (${work.evidence})`,
+            fix: work.pr
+              ? `nada a fazer enquanto o PR #${work.pr} estiver aberto`
+              : `integre a branch antes de remover o worktree — ele é o único exemplar`,
+          }
+          : {
+            type: 'non-morph-branch',
+            path,
+            detail: `${path} está em ${entry.branch || 'HEAD destacado'}, não numa branch morph/* — o \`fleet\` não o enxerga (e não há trabalho pendente: ${work.evidence})`,
+            // NEVER raw `git worktree remove` here: it follows the infra junctions
+            // out and empties the primary root's .claude/ and .morph/framework/.
+            // `worktree remove` drops them first (PROVE-or-DECLINE) and takes
+            // --target precisely for worktrees like this one, with no feature.
+            fix: `morph-spec worktree remove --target "${path}"  (se já não serve)`,
+          });
       }
       continue;
     }
 
     if (!features.has(feature) && !featureCommittedOnBranch(root, feature)) {
-      issues.push({
-        type: 'no-feature',
-        path,
-        detail: `worktree de "${feature}" sem feature conhecida (nem em .morph/features/, nem na branch)`,
-        fix: `morph-spec worktree remove --target "${path}"`,
-      });
+      // "sem feature conhecida" is a bookkeeping fact, NOT a verdict on the
+      // work: a `finish` that archived the feature leaves exactly this shape,
+      // and so does a worktree whose PR is still open. In the observed session
+      // this branch recommended `worktree remove --target` for a worktree
+      // holding the ONLY copy of an open PR with 12 tasks and a 9.5 at Gate 3.
+      // So the diagnosis now depends on whether the WORK is integrated, and the
+      // suggestion to destroy appears only when it provably is.
+      const work = unintegratedWork(root, entry.branch, prIndex);
+      if (work.unintegrated) {
+        issues.push({
+          type: 'unintegrated-work',
+          severity: 'info',
+          path,
+          feature,
+          detail: `worktree com trabalho NÃO integrado (${work.evidence}) — a feature foi arquivada, o trabalho não`,
+          fix: work.pr
+            ? `nada a fazer enquanto o PR #${work.pr} estiver aberto; depois de mergeado, \`morph-spec worktree remove --target "${path}"\``
+            : `integre a branch (\`morph-spec finish\` ou um PR) antes de remover o worktree — ele é o único exemplar`,
+        });
+      } else {
+        issues.push({
+          type: 'no-feature',
+          path,
+          feature,
+          detail: `worktree de "${feature}" sem feature conhecida (nem em .morph/features/, nem na branch) e sem trabalho pendente (${work.evidence})`,
+          fix: `morph-spec worktree remove --target "${path}"`,
+        });
+      }
     }
   }
 
@@ -198,8 +318,16 @@ export function auditWorktrees(cwd = process.cwd()) {
     issues.push({
       type: 'unregistered-dir',
       path: d.path,
-      detail: `${d.container}/${d.name} existe no disco mas o git não o registra — resíduo de um finish anterior`,
-      fix: `apague o diretório à mão depois de conferir que nada importante ficou nele`,
+      empty: d.empty,
+      detail: d.empty
+        ? `${d.container}/${d.name} existe no disco, está VAZIO e o git não o registra — resíduo de um finish anterior`
+        : `${d.container}/${d.name} existe no disco mas o git não o registra — resíduo de um finish anterior`,
+      // An empty folder has nothing to lose, so it gets the automatic repair.
+      // One with content keeps the manual chore: there may be work in there,
+      // and the whole PROVE-or-DECLINE discipline exists for exactly that.
+      fix: d.empty
+        ? `morph-spec doctor --worktrees --prune`
+        : `apague o diretório à mão depois de conferir que nada importante ficou nele`,
     });
   }
 
@@ -232,24 +360,59 @@ export function auditWorktrees(cwd = process.cwd()) {
 }
 
 /**
- * Drop git's admin records for worktrees whose directory is already gone, AND
- * clear any feature's `worktree` registration that names one of those same
- * gone directories.
+ * Remove the EMPTY directories under `worktrees/`/`.worktrees/` that git does
+ * not register — the residue a finish leaves behind.
+ *
+ * "Empty" is the whole licence to act: a folder with zero entries cannot be
+ * hiding uncommitted work, so asking a human about it is pure ceremony, and
+ * the audit that only warns leaves it there forever. A directory with anything
+ * in it keeps the manual path.
+ *
+ * Two guards beyond the emptiness check:
+ *   • only directories directly inside morph's own worktree containers, never
+ *     the containers themselves and never a path git registers;
+ *   • `rmdirSync`, not `rm -rf` — it REFUSES a non-empty directory, so a file
+ *     that appears between the check and the call is a failure, not a loss.
+ *
+ * @param {string} root
+ * @returns {string[]} paths actually removed
+ */
+function removeEmptyUnregisteredDirs(root) {
+  const registeredPaths = new Set(parseWorktreeList(root).map((e) => norm(e.path)));
+  const removed = [];
+  for (const d of dirsOnDisk(root)) {
+    if (!d.empty || registeredPaths.has(d.path)) continue;
+    try {
+      rmdirSync(d.path);
+      removed.push(d.path);
+    } catch { /* raced, locked or no longer empty — leave it to the next audit */ }
+  }
+  return removed;
+}
+
+/**
+ * Drop git's admin records for worktrees whose directory is already gone,
+ * remove the EMPTY unregistered residue directories, AND clear any feature's
+ * `worktree` registration that names a directory that is now gone.
+ *
+ * These three are the ONLY prune offered, on purpose: none can destroy
+ * anything, because everything they touch is either already absent from disk
+ * or provably empty. Removing a directory that still HOLDS something is
+ * exactly the operation that needs a human looking at it.
  *
- * Both halves are the ONLY prune offered, on purpose: neither can destroy
- * anything, because everything they touch is already absent from disk.
- * Removing a directory that still exists is exactly the operation that needs
- * a human looking at it.
+ * Order is load-bearing: the empty directories go first, so a root pointer
+ * naming one of them becomes dangling in time for the registration sweep below
+ * to clear it — one command, not two runs.
  *
  * `clearDanglingWorktreeRegistration` re-checks the dangling predicate itself
  * (path unset, or still exists → no-op) rather than trusting a pre-computed
  * list, so this stays correct even called against a stale audit snapshot.
  *
  * @param {string} [cwd]
- * @returns {Promise<{ pruned: boolean, error?: string, clearedRegistrations: Array<{feature: string, cleared: boolean}> }>}
+ * @returns {Promise<{ pruned: boolean, error?: string, removedEmptyDirs: string[], clearedRegistrations: Array<{feature: string, cleared: boolean}> }>}
  */
 export async function pruneWorktrees(cwd = process.cwd()) {
-  if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo', clearedRegistrations: [] };
+  if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo', removedEmptyDirs: [], clearedRegistrations: [] };
   const root = resolvePrimaryRoot(cwd);
 
   let pruned = false;
@@ -261,11 +424,13 @@ export async function pruneWorktrees(cwd = process.cwd()) {
     error = (err.message || 'unknown').slice(0, 200);
   }
 
+  const removedEmptyDirs = removeEmptyUnregisteredDirs(root);
+
   const clearedRegistrations = [];
   for (const reg of featureRegistrations(root)) {
     const { cleared } = await clearDanglingWorktreeRegistration(root, reg.feature);
     if (cleared) clearedRegistrations.push({ feature: reg.feature, cleared: true });
   }
 
-  return { pruned, ...(error ? { error } : {}), clearedRegistrations };
+  return { pruned, ...(error ? { error } : {}), removedEmptyDirs, clearedRegistrations };
 }