@polymorphism-tech/morph-spec 8.31.0 → 8.32.0

package/src/commands/state/finish.js

@@ -13,6 +13,7 @@ import {
   cwdIsInsideWorktree,
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
+import { resolveGh } from '../../lib/git/gh.js';
 import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
 import {
   composeProjectName,
@@ -326,7 +327,7 @@ export async function finishCommand(feature, options = {}) {
           branch: expectedBranch,
           base: target,
           archived: archivePath.replace(/\\/g, '/'),
-          ...(typeof openPr === 'string' ? { pr: openPr } : {}),
+          ...(typeof openPr === 'string' ? { pr: { number: prNumberFromUrl(openPr), url: openPr } } : {}),
           hint: `'${feature}' já foi arquivada e ${expectedBranch} já tem PR aberto — o finish anterior concluiu. Falta apenas mergear o PR.`,
         });
         process.exit(1);
@@ -487,7 +488,7 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
       // VALID (it still names a live directory), so nothing to clean up here —
       // only report where it lives and how to close it later.
       emit({
-        finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false,
+        finished: true, integrated: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false,
         worktree: { path: worktreePath, branch: expectedBranch },
         hint: `worktree preservado em ${worktreePath} — feche depois com \`morph-spec worktree remove ${feature}\`.`,
         ...backupNote, ...ucNote,
@@ -526,10 +527,26 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
   }
   tryGit(['branch', '-d', expectedBranch], root);
   // The root index (gitignored) was already updated by the archive (same cwd).
-  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: MERGE_NEXT_STEP, ...ucNote });
+  emit({ finished: true, integrated: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: MERGE_NEXT_STEP, ...ucNote });
   process.exit(0);
 }
 
+/**
+ * O número do PR a partir da url que o `gh pr create` imprime.
+ *
+ * Existe porque o número é o que um humano usa para falar do PR ("mergeia o
+ * #51"), e a url é a única coisa que o `gh` devolve. Um formato inesperado
+ * devolve `null` em vez de um palpite: o payload prefere admitir que não sabe
+ * o número a afirmar um errado.
+ *
+ * @param {string|null} url
+ * @returns {number|null}
+ */
+export function prNumberFromUrl(url) {
+  const m = typeof url === 'string' ? url.match(/\/pull\/(\d+)(?:[/?#]|$)/) : null;
+  return m ? Number(m[1]) : null;
+}
+
 // ── PR integration (push + gh, no local merge) ───────────────────────────────
 
 async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch }) {
@@ -571,13 +588,23 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     dropFromRootIndex(root, feature);
   }
 
+  const prNumber = prNumberFromUrl(prUrl);
+  const prLabel = prNumber ? `#${prNumber}` : 'o PR';
+
   const out = {
     finished: true,
+    // O comando terminou; a INTEGRAÇÃO não aconteceu. Eram a mesma coisa no
+    // payload antigo, e é dessa colisão que sai o "shipped" para uma feature
+    // cujo PR seguia aberto: quem lê `finished: true` sem mais nada conclui
+    // que acabou. A default só recebe archive/{f} quando o PR mergear.
+    integrated: false,
+    awaiting: 'merge',
     mode: 'pr',
     feature,
     pushed: expectedBranch,
     base: defaultBranch,
-    pr: prUrl,
+    pr: { number: prNumber, url: prUrl },
+    nextStep: `mergeie ${prLabel} — a feature só estará encerrada quando ${defaultBranch} receber o archive pelo merge`,
     ...promotedNote(arch),
     ...(shedBackup ? { shedBackup } : {}),
     ...(teardown
@@ -626,6 +653,7 @@ const MERGE_NEXT_STEP = 'integração LOCAL — nada foi publicado. Rode `git pu
 function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
   return {
     finished: true,
+    integrated: true,
     mode: 'merge',
     feature,
     merged: branch,
@@ -641,6 +669,15 @@ function teardownExtras(teardown, worktreePath, branch, deleteBranch) {
   const out = {};
   if (teardown.ignoredBackup) out.worktreeIgnoredBackup = teardown.ignoredBackup;
   if (teardown.worktreeRemoved && teardown.discarded.length) out.discardedIgnored = teardown.discarded;
+  // WHAT was copied out, and what needed no copy because the primary root holds
+  // the identical bytes. Reported on both paths: after a removal these two lists
+  // are the whole answer to "did I just lose something?", and the user should
+  // not have to open the backup directory to find out.
+  if (teardown.shieldable?.length) out.worktreeIgnoredBackedUp = teardown.shieldable;
+  if (teardown.replicable?.length) out.replicatedInRoot = teardown.replicable;
+  // The infra reparse points dropped BEFORE git touched the directory — the
+  // proof the primary root's real `.claude/` was unlinked, never followed.
+  if (teardown.unlinked?.length) out.unlinked = teardown.unlinked;
   if (!teardown.worktreeRemoved) {
     out.path = worktreePath;
     out.branch = branch;
@@ -688,28 +725,6 @@ function gitStatusPorcelain(cwd) {
   }
 }
 
-/**
- * Resolve the `gh` invocation. Defaults to the `gh` binary on PATH. Overridable
- * via MORPH_GH_BIN: a plain string names a different binary (a corporate wrapper,
- * `hub`, …); a JSON array is a full argv prefix — e.g.
- * `["/path/to/node","/path/to/gh-shim.js"]` — which is how the tests inject a
- * cross-platform stub that execFileSync can actually spawn (Node ≥20 refuses to
- * run `.cmd`/`.bat` shims without `shell:true`, and shell:true would reopen the
- * arg-injection hole the whole file avoids).
- *
- * @returns {{ bin: string, prefix: string[] }}
- */
-function resolveGh() {
-  const raw = process.env.MORPH_GH_BIN;
-  if (raw && raw.trim().startsWith('[')) {
-    try {
-      const arr = JSON.parse(raw);
-      if (Array.isArray(arr) && arr.length) return { bin: String(arr[0]), prefix: arr.slice(1).map(String) };
-    } catch { /* not JSON — treat as a plain binary name below */ }
-  }
-  return { bin: raw && raw.trim() ? raw.trim() : 'gh', prefix: [] };
-}
-
 function ghAuthOk() {
   const { bin, prefix } = resolveGh();
   try {

package/src/commands/state/list.js

@@ -7,6 +7,8 @@ import { missingIdentity } from '../../core/state/feature-identity.js';
 import { derivePhaseFrom } from '../../../framework/hooks/shared/state-reader.js';
 import { isGitRepo } from '../project/worktree.js';
 import { morphBranches, currentBranch, branchView } from '../../lib/worktree/feature-truth.js';
+import { buildPrIndex } from '../../lib/git/pr-index.js';
+import { pendingPrFeatures, prForFeature } from '../../lib/git/pending-prs.js';
 
 /**
  * `morph-spec list [--all] [--json] [--no-branch]` — the feature audit board.
@@ -176,16 +178,51 @@ function flagArchivedElsewhere(cwd, rows) {
   }
 }
 
+/**
+ * A linha de uma feature que existe SÓ como PR aberto — sem pasta ativa nem
+ * arquivada nesta árvore. É o estado que o `finish --pr` deixa: o scaffold do
+ * root foi apagado pelo shed e o archive viaja no diff do PR, chegando na
+ * default apenas no merge. Sem esta linha o trabalho fica sem dono no quadro,
+ * e uma branch sem dono é candidata a poda.
+ */
+function pendingRow(p) {
+  return {
+    feature: p.feature,
+    name: null,
+    description: null,
+    workType: null,
+    status: 'in_progress',
+    phase: 'aguardando-merge',
+    gates: { proposal: false, uiux: false, plan: false, review: false },
+    selfAssessed: false,
+    flags: ['pr-pending'],
+    location: 'pr-pending',
+    createdAt: p.createdAt,
+    updatedAt: null,
+    source: 'pr',
+    branch: p.branch,
+    worktree: null,
+    pr: { number: p.number, state: p.state, url: p.url, ageDays: p.ageDays },
+  };
+}
+
 const mark = (on) => (on ? chalk.green('✓') : chalk.gray('·'));
 const truncate = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
 
 function whereLabel(row) {
+  if (row.location === 'pr-pending') return `branch ${row.branch}`;
   if (row.location === 'archived') return '-';
   if (row.worktree) return row.worktree.exists ? `worktree ${basename(row.worktree.path)}` : '⚠ worktree ausente';
   if (row.source === 'branch') return `branch ${row.branch}`;
   return 'raiz';
 }
 
+const prCell = (pr) => {
+  if (!pr) return '-';
+  const state = String(pr.state || '').toLowerCase();
+  return `#${pr.number} ${state}`;
+};
+
 export function listCommand(options = {}) {
   const cwd = options.cwd || process.cwd();
   const rows = readFeaturesIn(cwd, 'features', 'active');
@@ -195,6 +232,32 @@ export function listCommand(options = {}) {
   // Commander's `--no-branch` sets options.branch = false; anything else (undefined/true) reads the branch.
   if (options.branch !== false) resolveBranchTruth(cwd, rows);
 
+  // Estado do PR — uma consulta ao `gh` por invocação, compartilhada pela
+  // coluna e pela síntese. `--no-branch` (o modo offline rápido) pula as duas.
+  //
+  // `prIndex` continua `null` quando a pergunta não pôde ser feita (sem `gh`,
+  // sem auth, remoto não-GitHub, ou `--no-branch`). É o mesmo sinal que
+  // `--json` já expõe como `pr: null` por linha — a tabela texto usa o mesmo
+  // fato para decidir se a coluna PR sequer aparece (achado #2): índice `null`
+  // degrada para o comportamento de antes, sem coluna e sem `-` que afirme
+  // ausência.
+  let prIndex = null;
+  if (options.branch !== false) {
+    prIndex = buildPrIndex(cwd);
+    for (const row of rows) {
+      const pr = prForFeature(prIndex, row.feature);
+      row.pr = pr ? { number: pr.number, state: pr.state, url: pr.url, ageDays: null } : null;
+    }
+    const known = new Set(rows.map((r) => r.feature));
+    // `null` propaga desconhecido: nenhuma linha sintetizada, e nenhuma
+    // afirmação de que não há pendência.
+    for (const p of pendingPrFeatures(cwd, { index: prIndex }) || []) {
+      if (!known.has(p.feature)) rows.push(pendingRow(p));
+    }
+  } else {
+    for (const row of rows) row.pr = null;
+  }
+
   rows.sort((a, b) => a.feature.localeCompare(b.feature));
 
   if (options.json) {
@@ -208,22 +271,32 @@ export function listCommand(options = {}) {
   }
 
   const col = (s, w) => String(s ?? '-').padEnd(w);
+  // A coluna PR só aparece quando o índice foi construído com sucesso (achado
+  // #2) — um índice `null` não vira uma coluna cheia de `-`, que afirmaria
+  // "sem PR" para algo que na verdade é "não sabemos".
+  const showPr = Boolean(prIndex);
+  // `pr-pending` é estado normal de trabalho em voo, não inconsistência —
+  // não deve marcar `⚠` nem contar no rodapé (achado #6). Continua em
+  // `flags` no `--json`: é metadado real, só não é anomalia.
+  const warnFlags = (r) => r.flags.filter((f) => f !== 'pr-pending');
   console.log(chalk.white.bold(
-    col('FEATURE', 22) + col('TYPE', 9) + col('STATUS', 13) + col('PHASE', 11) + col('WHERE', 22)
+    col('FEATURE', 22) + col('TYPE', 9) + col('STATUS', 13) + col('PHASE', 17) + col('WHERE', 22) + (showPr ? col('PR', 12) : '')
     + col('G1', 4) + col('G2', 4) + col('G3', 4) + col('', 3) + 'DESCRIPTION',
   ));
   for (const r of rows) {
-    const flag = r.flags.length ? chalk.yellow('⚠') : ' ';
-    const desc = (r.selfAssessed ? chalk.yellow('[G3 self-assessed] ') : '')
-      + (r.description ? truncate(r.description, 34) : chalk.yellow('(sem descrição)'));
+    const flag = warnFlags(r).length ? chalk.yellow('⚠') : ' ';
+    const desc = r.location === 'pr-pending'
+      ? chalk.yellow(`aguardando merge${r.pr?.ageDays != null ? ` há ${r.pr.ageDays}d` : ''} — sem cópia local`)
+      : (r.selfAssessed ? chalk.yellow('[G3 self-assessed] ') : '')
+        + (r.description ? truncate(r.description, 34) : chalk.yellow('(sem descrição)'));
     // padEnd counts the invisible color codes; pad the plain marks manually.
     console.log(
-      col(r.feature, 22) + col(r.workType, 9) + col(r.status, 13) + col(r.phase, 11) + col(whereLabel(r), 22)
+      col(r.feature, 22) + col(r.workType, 9) + col(r.status, 13) + col(r.phase, 17) + col(whereLabel(r), 22) + (showPr ? col(prCell(r.pr), 12) : '')
       + mark(r.gates.proposal) + '   ' + mark(r.gates.plan) + '   ' + mark(r.gates.review) + '   '
       + flag + ' ' + desc,
     );
   }
-  const flagged = rows.filter((r) => r.flags.length);
+  const flagged = rows.filter((r) => warnFlags(r).length);
   if (flagged.length) {
     console.log(chalk.gray(`\n⚠ ${flagged.length} com inconsistência — rode 'morph-spec doctor' para detalhes.`));
   }

package/src/core/state/lifecycle-audit.js

@@ -12,6 +12,9 @@
  *                     the next loadState, but surfaced so it's not a mystery)
  *   • branch-drift  — the root's copy of a feature.json disagrees with the copy
  *                     committed on `morph/{f}` (B5 — the root's view lags)
+ *   • abandoned-scaffold — an `in_progress` feature that never produced
+ *                     anything: no artifacts, no approved gate, and a branch
+ *                     with no commit of its own (see abandonedScaffold)
  *   • corrupt       — a feature.json that won't parse
  */
 
@@ -20,6 +23,8 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
 import { gateOrderViolations } from './gate-order.js';
 import { missingIdentity } from './feature-identity.js';
+import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+import { commitsAhead, resolveBaseRef } from '../../lib/git/branch-classifier.js';
 
 /** The operational truth of a feature.json: its status and which gates are approved. */
 function operationalShape(fj) {
@@ -72,6 +77,125 @@ function branchDrift(baseDir, feature, rootFj) {
   }
 }
 
+/**
+ * How long a scaffold has to sit untouched before it counts as abandoned.
+ *
+ * A dead scaffold and a feature born five minutes ago have the SAME shape:
+ * `create` forks `morph/{f}` off the default branch without committing, so at
+ * birth the branch has no commit of its own and the folder holds nothing but
+ * `feature.json`. Only elapsed time separates the two — and a check that fires
+ * on every fresh `create` is one people learn to scroll past.
+ */
+const ABANDONED_SCAFFOLD_MIN_AGE_MS = 24 * 60 * 60 * 1000;
+
+/** Newest timestamp the feature carries, in ms; falls back to the folder's mtime. */
+function lastTouched(fdir, fj) {
+  let newest = 0;
+  for (const ts of [fj?.updatedAt, fj?.createdAt]) {
+    const t = ts ? Date.parse(ts) : NaN;
+    if (!Number.isNaN(t)) newest = Math.max(newest, t);
+  }
+  if (newest) return newest;
+  try { return statSync(fdir).mtimeMs; } catch { return 0; }
+}
+
+/**
+ * Does the feature dir hold any FILE other than its own `feature.json`?
+ *
+ * Files, not entries: `create` scaffolds the phase folders empty, so an empty
+ * `0-proposal/` is the absence of work, not evidence of it.
+ */
+function hasArtifacts(fdir) {
+  let entries;
+  try { entries = readdirSync(fdir, { withFileTypes: true }); } catch { return false; }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (hasArtifacts(join(fdir, e.name))) return true;
+      continue;
+    }
+    if (e.name === 'feature.json') continue;
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Commits on the feature's branch that the base does not already contain, or
+ * `null` when git cannot answer (no repo, no resolvable base, no branch, no
+ * rev-list). "Cannot prove" must never read as "proved zero" — the predicate
+ * below hinges on this number, so an unanswerable repo has to stay silent.
+ *
+ * The counting itself is `branch-classifier.js`'s `commitsAhead` against its
+ * `resolveBaseRef`, NOT a second copy: `origin/{default}` is the authority on
+ * what actually landed, and two drifting answers to "does this branch carry
+ * anything of its own?" is exactly what the `doctor`/`branch prune` split was
+ * unified to avoid.
+ *
+ * Note the field evidence this exists for: the branch pointed at the merge
+ * commit of somebody else's PR. That is the base's own tip — reachable from
+ * the base, and therefore zero commits of its own.
+ */
+function ownCommitCount(baseDir, branch) {
+  try {
+    execFileSync('git', ['rev-parse', '--git-dir'], { cwd: baseDir, stdio: 'pipe' });
+  } catch {
+    return null;
+  }
+  const baseRef = resolveBaseRef(detectDefaultBranch(baseDir), baseDir);
+  if (!baseRef) return null;
+  try {
+    execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: baseDir, stdio: 'pipe' });
+  } catch {
+    return 0; // the branch never existed — nothing was ever committed for it
+  }
+  return commitsAhead(baseRef, branch, baseDir);
+}
+
+/**
+ * The orphan skeleton `create --worktree` can leave behind: a feature.json on
+ * its own, `status: in_progress`, no tasks, no gates, and a branch parked on
+ * somebody else's commit. Every one of those alone is normal at some point in
+ * a feature's life; together, and only after the feature has gone stale, they
+ * mean nobody ever came back to it.
+ *
+ * The artifact test is deliberately broader than the "0 tasks" the report
+ * named: a proposal drafted and waiting on Gate 1 also has zero tasks and is
+ * very much alive. What a dead scaffold has is NOTHING — checked in the root
+ * and, if the feature registered one, in its worktree, where uncommitted work
+ * would otherwise be invisible to both the disk scan and `rev-list`.
+ *
+ * @returns {string|null} the issue detail, or null when the feature is alive
+ */
+function abandonedScaffold(baseDir, feature, fdir, fj) {
+  if (fj?.status !== 'in_progress') return null;
+
+  // "0 gates": a gate stamped `policy:{workType}` at birth (chore/hotfix) was
+  // never a decision anyone took, so it must not read as progress.
+  const decided = Object.values(fj.approvalGates || {}).some(
+    (g) => g?.approved === true && !String(g?.approvedBy ?? '').startsWith('policy:'),
+  );
+  if (decided) return null;
+
+  if (hasArtifacts(fdir)) return null;
+  const wtFeatureDir = fj.worktree?.path
+    ? join(fj.worktree.path, '.morph', 'features', feature)
+    : null;
+  if (wtFeatureDir && existsSync(wtFeatureDir) && hasArtifacts(wtFeatureDir)) return null;
+
+  const age = Date.now() - lastTouched(fdir, fj);
+  if (age < ABANDONED_SCAFFOLD_MIN_AGE_MS) return null;
+
+  // The registered branch when the feature has one, `morph/{f}` otherwise —
+  // same name `branchDrift` above assumes.
+  const branch = fj.worktree?.branch || `morph/${feature}`;
+  if (ownCommitCount(baseDir, branch) !== 0) return null;
+
+  const days = Math.floor(age / (24 * 60 * 60 * 1000));
+  return `in_progress há ${days}d sem nada produzido: 0 artefatos, 0 gates aprovados `
+    + `e \`${branch}\` sem commit próprio — rode \`morph-spec delete ${feature} --archive\` `
+    + 'ou retome a feature';
+}
+
 /**
  * @param {string} [baseDir] - project root (defaults to cwd)
  * @returns {Array<{ feature: string, type: string, detail: string }>} issues
@@ -106,6 +230,9 @@ export function auditFeatureLifecycle(baseDir = process.cwd()) {
       const drift = branchDrift(baseDir, name, fj);
       if (drift) issues.push({ feature: name, type: 'branch-drift', detail: drift });
 
+      const dead = abandonedScaffold(baseDir, name, fdir, fj);
+      if (dead) issues.push({ feature: name, type: 'abandoned-scaffold', detail: dead });
+
       const miss = missingIdentity(fj);
       if (miss.length) {
         issues.push({ feature: name, type: 'identity', detail: `missing ${miss.join(', ')}` });

package/src/lib/git/branch-classifier.js

@@ -0,0 +1,177 @@
+/**
+ * branch-classifier.js — answer "is this branch's work already in the default
+ * branch?" for a repository that squash-merges.
+ *
+ * WHY THIS EXISTS: a squash-merge puts the WORK in `origin/master` while
+ * leaving none of the branch's own commits reachable from it. So
+ * `git branch --merged origin/master` does not list the branch, and
+ * `git branch -d` refuses it as unmerged. The only remaining command is
+ * `git branch -D`, which is byte-identical to the command that discards real,
+ * never-integrated work — the tool gives the user no way to tell the two apart,
+ * and after enough of these the habit becomes "just -D it", which is how work
+ * gets lost.
+ *
+ * Every branch lands in exactly one class, and only the two MERGED ones are
+ * ever deletable:
+ *
+ *   merged-ancestral — git itself proves it: the branch tip is an ancestor of
+ *                      the default. A plain merge, or a fast-forward.
+ *   merged-squash    — git cannot see it, but the evidence is positive: either
+ *                      GitHub reports the PR as MERGED, or the branch's tree is
+ *                      IDENTICAL to the default's (every change it carries is
+ *                      already there under a different commit).
+ *   open             — a PR is OPEN for it. Never deleted: the PR is the whole
+ *                      reason the branch must survive.
+ *   in-worktree      — checked out by a live worktree. Never deleted.
+ *   unmerged         — none of the above could be PROVEN. This is the fail-safe
+ *                      default and covers "no `gh`", "no origin", and "genuinely
+ *                      unintegrated work" alike, because from here they are the
+ *                      same thing: not proven integrated.
+ *
+ * Nothing here mutates. `pruneBranches` in commands/project/branch.js does the
+ * deleting, and it deletes ONLY what this file classified as merged.
+ */
+
+import { execFileSync } from 'child_process';
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, stdio: 'pipe' }).toString();
+}
+
+/**
+ * Local branches with their tips. Excludes nothing — the caller decides.
+ *
+ * @returns {Array<{ name: string, sha: string, current: boolean, worktreePath: string|null }>}
+ */
+export function listLocalBranches(cwd) {
+  try {
+    const out = git(['for-each-ref', '--format=%(refname:short)%09%(objectname)%09%(HEAD)%09%(worktreepath)', 'refs/heads/'], cwd);
+    return out.split('\n').filter(Boolean).map((line) => {
+      const [name, sha, head, worktreePath] = line.split('\t');
+      return { name, sha, current: head === '*', worktreePath: worktreePath || null };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/** Is `ancestor` reachable from `descendant`? False on any git error. */
+function isAncestor(ancestor, descendant, cwd) {
+  try {
+    git(['merge-base', '--is-ancestor', ancestor, descendant], cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Does the branch introduce NOTHING the base does not already have?
+ *
+ * `git diff --quiet <base> <branch>` compares the two TREES: an empty diff
+ * means every file the branch touched already reads exactly as the branch left
+ * it in the base. That is precisely the state a squash-merge produces, and it
+ * is a positive proof rather than an inference from history shape.
+ *
+ * Deliberately NOT `base...branch` (the three-dot form diffs against the merge
+ * base, which for a squash-merged branch still shows the branch's own changes).
+ *
+ * Fail-CLOSED: any git error reads as "introduces something", never as merged.
+ */
+function treeIsIdentical(base, branch, cwd) {
+  try {
+    execFileSync('git', ['diff', '--quiet', base, branch], { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * How many commits the branch carries that the base does not. Used only for
+ * REPORTING — the classification never turns on it, because a squash-merged
+ * branch legitimately has commits ahead while carrying no unintegrated work.
+ *
+ * @returns {number|null} null when it cannot be computed
+ */
+export function commitsAhead(base, branch, cwd) {
+  try {
+    const out = git(['rev-list', '--count', `${base}..${branch}`], cwd).trim();
+    const n = Number(out);
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the ref to compare against: `origin/<default>` when the remote-tracking
+ * ref exists (the authority on what has actually landed), else the local branch.
+ *
+ * @returns {string|null} null when neither resolves — the caller must then
+ *   classify everything as `unmerged`, because there is no baseline to prove
+ *   integration against.
+ */
+export function resolveBaseRef(defaultBranch, cwd) {
+  if (!defaultBranch) return null;
+  for (const ref of [`refs/remotes/origin/${defaultBranch}`, `refs/heads/${defaultBranch}`]) {
+    try {
+      git(['show-ref', '--verify', '--quiet', ref], cwd);
+      return ref.replace(/^refs\/(remotes|heads)\//, '');
+    } catch { /* try the next */ }
+  }
+  return null;
+}
+
+/**
+ * Classify one branch. Pure decision logic over already-gathered facts, so the
+ * table above is testable without a GitHub account.
+ *
+ * ORDER IS THE POLICY, and the two protective classes come FIRST: a branch that
+ * is checked out, or that carries an OPEN PR, is never deleted even if its tree
+ * happens to match the base — a PR being open means a human still has business
+ * with it.
+ *
+ * @param {object} b - from listLocalBranches
+ * @param {{ baseRef: string|null, cwd: string, pr: {number:number,state:string}|null|undefined }} ctx
+ * @returns {{ name: string, kind: string, reason: string, pr: number|null, ahead: number|null, deletable: boolean }}
+ */
+export function classifyBranch(b, { baseRef, cwd, pr }) {
+  const prNum = pr?.number ?? null;
+  const mk = (kind, reason, deletable) => ({
+    name: b.name, kind, reason, pr: prNum, ahead: baseRef ? commitsAhead(baseRef, b.name, cwd) : null, deletable,
+  });
+
+  if (b.current || b.worktreePath) {
+    return mk('in-worktree', b.current ? 'é a branch atual (HEAD)' : `está em uso pelo worktree ${b.worktreePath}`, false);
+  }
+  if (pr?.state === 'OPEN') {
+    return mk('open', `PR #${prNum} está OPEN — a branch é o que o PR aponta`, false);
+  }
+  if (!baseRef) {
+    return mk('unmerged', 'não há branch default resolvível (origin/HEAD, main ou master) para comparar', false);
+  }
+  if (isAncestor(b.name, baseRef, cwd)) {
+    return mk('merged-ancestral', `já é ancestral de ${baseRef}`, true);
+  }
+  if (pr?.state === 'MERGED') {
+    return mk('merged-squash', `PR #${prNum} está MERGED (squash-merge: os commits não entram em ${baseRef}, o trabalho sim)`, true);
+  }
+  if (treeIsIdentical(baseRef, b.name, cwd)) {
+    return mk('merged-squash', `a árvore é idêntica à de ${baseRef} — tudo que a branch muda já está lá`, true);
+  }
+  return mk('unmerged', `carrega mudanças que não estão em ${baseRef} e nenhum PR MERGED comprova o contrário`, false);
+}
+
+/**
+ * Classify every local branch except the default itself.
+ *
+ * @param {{ cwd: string, defaultBranch: string|null, prIndex: Map|null }} ctx
+ * @returns {Array} one entry per branch, in `for-each-ref` order
+ */
+export function classifyBranches({ cwd, defaultBranch, prIndex }) {
+  const baseRef = resolveBaseRef(defaultBranch, cwd);
+  return listLocalBranches(cwd)
+    .filter((b) => b.name !== defaultBranch)
+    .map((b) => classifyBranch(b, { baseRef, cwd, pr: prIndex?.get(b.name) ?? null }));
+}

package/src/lib/git/gh.js

@@ -0,0 +1,30 @@
+/**
+ * gh.js — como o `gh` é invocado, num lugar só.
+ *
+ * Extraído de `finish.js`, onde nasceu, porque o `pr-index.js` chamava `'gh'`
+ * cru: o caminho de SUCESSO do índice era intestável, já que não havia por
+ * onde injetar um stub. Duas formas de chamar o mesmo binário também são duas
+ * formas de discordar sobre qual binário é.
+ */
+
+/**
+ * Resolve a invocação do `gh`. Por padrão, o `gh` do PATH. Sobrescrevível via
+ * MORPH_GH_BIN: uma string simples nomeia outro binário (um wrapper corporativo,
+ * `hub`, …); um array JSON é um prefixo de argv COMPLETO — por exemplo
+ * `["/path/to/node","/path/to/gh-shim.js"]` — que é como os testes injetam um
+ * stub cross-platform que o execFileSync consegue spawnar (Node ≥20 recusa
+ * rodar shims `.cmd`/`.bat` sem `shell:true`, e `shell:true` reabriria o buraco
+ * de injeção de argumento que estes caminhos evitam).
+ *
+ * @returns {{ bin: string, prefix: string[] }}
+ */
+export function resolveGh() {
+  const raw = process.env.MORPH_GH_BIN;
+  if (raw && raw.trim().startsWith('[')) {
+    try {
+      const arr = JSON.parse(raw);
+      if (Array.isArray(arr) && arr.length) return { bin: String(arr[0]), prefix: arr.slice(1).map(String) };
+    } catch { /* não é JSON — trata como nome de binário abaixo */ }
+  }
+  return { bin: raw && raw.trim() ? raw.trim() : 'gh', prefix: [] };
+}