@polymorphism-tech/morph-spec 8.31.0 → 8.32.0

package/src/commands/project/branch.js

@@ -0,0 +1,170 @@
+/**
+ * branch.js — `morph-spec branch prune`.
+ *
+ * The gap this closes: after a few features close by squash-merge, the local
+ * repo accumulates branches git considers unmerged. `git branch --merged` lists
+ * none of them, `git branch -d` refuses each one, and the only command left is
+ * `git branch -D` — which is EXACTLY the command for throwing away real work.
+ * Once a user has typed `-D` on five safe branches, the sixth (an actual
+ * unintegrated feature) gets the same keystroke.
+ *
+ * So this command never asks the user to make that distinction: it makes it
+ * itself, prints the evidence for each branch, and deletes only what it PROVED
+ * is already integrated (see branch-classifier.js for the five classes and
+ * their order). Everything else is listed with the reason it survives.
+ *
+ * The remote is a separate decision: `--remote` is required to touch
+ * `origin/<branch>`, because a local branch is a local artifact while the remote
+ * one may be what someone else, or an open review, is looking at.
+ */
+
+import { execFileSync } from 'child_process';
+import chalk from 'chalk';
+import { isGitRepo, resolvePrimaryRoot } from './worktree.js';
+import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+import { buildPrIndex } from '../../lib/git/pr-index.js';
+import { classifyBranches } from '../../lib/git/branch-classifier.js';
+
+/**
+ * Delete one local branch.
+ *
+ * `-D`, not `-d`, and that is the whole point of the classifier: `-d` refuses
+ * every squash-merged branch, so a command that used it would be unable to do
+ * its one job. The safety does not come from git's own check (which cannot see
+ * a squash-merge) — it comes from only ever reaching this function with a
+ * branch whose integration was positively proven.
+ */
+function deleteLocal(name, cwd) {
+  try {
+    execFileSync('git', ['branch', '-D', name], { cwd, stdio: 'pipe' });
+    return { deleted: true };
+  } catch (err) {
+    return { deleted: false, error: (err.stderr?.toString() || err.message || 'unknown').trim().slice(0, 200) };
+  }
+}
+
+function deleteRemote(name, cwd) {
+  try {
+    execFileSync('git', ['push', 'origin', '--delete', name], { cwd, stdio: 'pipe', timeout: 20000 });
+    return { deleted: true };
+  } catch (err) {
+    return { deleted: false, error: (err.stderr?.toString() || err.message || 'unknown').trim().slice(0, 200) };
+  }
+}
+
+/** Does `origin/<name>` exist locally as a remote-tracking ref? */
+function remoteRefExists(name, cwd) {
+  try {
+    execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/remotes/origin/${name}`], { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Command handler for `morph-spec branch prune [--remote] [--dry-run] [--json]`.
+ *
+ * Fail-open outside a git repo (exit 0, empty result) — the same discipline the
+ * rest of the worktree suite follows: a housekeeping command must never be the
+ * reason a script dies.
+ *
+ * @param {{ remote?: boolean, dryRun?: boolean, json?: boolean, cwd?: string }} [options]
+ */
+export function branchPruneCommand(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const emit = (payload, code = 0) => {
+    if (options.json) console.log(JSON.stringify(payload, null, 2));
+    else printReport(payload, options);
+    process.exitCode = code;
+    return payload;
+  };
+
+  if (!isGitRepo(cwd)) {
+    return emit({ pruned: [], kept: [], error: 'not-a-git-repo' });
+  }
+  const root = resolvePrimaryRoot(cwd);
+  const defaultBranch = detectDefaultBranch(root);
+  // null = UNKNOWN, never "no PR" — the classifier treats a branch with no
+  // positive evidence as unmerged, so a missing `gh` costs conservatism, not
+  // safety. Reported so the user can tell "no PR" from "could not ask".
+  const prIndex = buildPrIndex(root);
+
+  const classified = classifyBranches({ cwd: root, defaultBranch, prIndex });
+  const pruned = [];
+  const kept = [];
+
+  for (const b of classified) {
+    if (!b.deletable) { kept.push(b); continue; }
+    if (options.dryRun) {
+      pruned.push({ ...b, deleted: false, dryRun: true, remoteDeleted: false });
+      continue;
+    }
+    const local = deleteLocal(b.name, root);
+    let remoteDeleted = false;
+    let remoteError;
+    if (local.deleted && options.remote && remoteRefExists(b.name, root)) {
+      const r = deleteRemote(b.name, root);
+      remoteDeleted = r.deleted;
+      if (!r.deleted) remoteError = r.error;
+    }
+    if (local.deleted) pruned.push({ ...b, deleted: true, remoteDeleted, ...(remoteError ? { remoteError } : {}) });
+    else kept.push({ ...b, kind: 'delete-failed', reason: `git branch -D falhou: ${local.error}`, deletable: false });
+  }
+
+  return emit({
+    defaultBranch,
+    prIndexAvailable: prIndex !== null,
+    dryRun: options.dryRun === true,
+    remote: options.remote === true,
+    pruned,
+    kept,
+  });
+}
+
+const KIND_LABEL = {
+  'merged-ancestral': chalk.green('merged'),
+  'merged-squash': chalk.green('squash-merged'),
+  open: chalk.yellow('PR aberto'),
+  'in-worktree': chalk.cyan('em uso'),
+  unmerged: chalk.red('não integrada'),
+  'delete-failed': chalk.red('falhou'),
+};
+
+function printReport(payload, options) {
+  if (payload.error === 'not-a-git-repo') {
+    console.log(chalk.gray('não é um repositório git — nada a fazer'));
+    return;
+  }
+  const verb = payload.dryRun ? 'seriam apagadas' : 'apagadas';
+  console.log(chalk.bold(`\nbranch prune — default: ${payload.defaultBranch || chalk.red('não resolvida')}`));
+  if (!payload.prIndexAvailable) {
+    // Load-bearing caveat, not noise: without `gh` a squash-merge is only
+    // detectable by the tree comparison, so branches that WERE merged may
+    // legitimately show up as unmerged here.
+    console.log(chalk.gray('  (sem `gh`/GitHub: squash-merge só é detectado por árvore idêntica)'));
+  }
+
+  if (payload.pruned.length) {
+    console.log(chalk.bold(`\n  ${payload.pruned.length} ${verb}:`));
+    for (const b of payload.pruned) {
+      const remote = b.remoteDeleted ? chalk.gray(' + origin') : '';
+      console.log(`    ${KIND_LABEL[b.kind] || b.kind}  ${chalk.bold(b.name)}${remote}`);
+      console.log(chalk.gray(`      ${b.reason}`));
+      if (b.remoteError) console.log(chalk.yellow(`      origin não apagada: ${b.remoteError}`));
+    }
+  } else {
+    console.log(chalk.gray('\n  nada a apagar'));
+  }
+
+  if (payload.kept.length) {
+    console.log(chalk.bold(`\n  ${payload.kept.length} mantida(s):`));
+    for (const b of payload.kept) {
+      console.log(`    ${KIND_LABEL[b.kind] || b.kind}  ${chalk.bold(b.name)}${b.ahead ? chalk.gray(` (+${b.ahead})`) : ''}`);
+      console.log(chalk.gray(`      ${b.reason}`));
+    }
+  }
+  if (payload.dryRun) console.log(chalk.gray('\n  --dry-run: nada foi apagado'));
+  if (!options.remote && payload.pruned.length) console.log(chalk.gray('  branches remotas intactas (use --remote para apagá-las também)'));
+  console.log();
+}

package/src/commands/project/doctor.js

@@ -1,11 +1,14 @@
 import { join, relative } from 'path';
 import { execSync } from 'child_process';
+import { existsSync } from 'fs';
 import { platform, homedir } from 'os';
 import fs from 'fs-extra';
 import chalk from 'chalk';
 import { logger } from '../../utils/logger.js';
 import { pathExists, readJson } from '../../utils/file-copier.js';
 import { checkClaudeMdImport } from '../../utils/claude-md-injector.js';
+import { buildPrIndex } from '../../lib/git/pr-index.js';
+import { pendingPrFeatures, MORPH_BRANCH_RE } from '../../lib/git/pending-prs.js';
 import {
   checkCLIOutdated,
   checkProjectOutdated,
@@ -556,10 +559,12 @@ async function doctorMcpCommand(targetPath) {
  * Orphan worktrees used to accumulate invisibly: `fleet` only reports worktrees
  * on a `morph/*` branch, so anything else never showed up anywhere.
  *
- * `--prune` runs the one safe repair (`git worktree prune`: admin records for
- * directories that are already gone). Deleting a directory that still exists is
- * reported with the exact command, never performed — same PROVE-or-DECLINE
- * discipline as the finish teardown.
+ * `--prune` runs the safe repairs: `git worktree prune` (admin records for
+ * directories that are already gone) and the removal of EMPTY unregistered
+ * residue directories, which by definition hold nothing that can be lost.
+ * Deleting a directory that still HOLDS something is reported with the exact
+ * command, never performed — same PROVE-or-DECLINE discipline as the finish
+ * teardown.
  */
 export async function doctorWorktreesCommand(targetPath, options = {}) {
   const { auditWorktrees, pruneWorktrees } = await import('../../lib/worktree/worktree-audit.js');
@@ -568,19 +573,28 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
     const beforeIssues = auditWorktrees(targetPath);
     const beforeMissing = beforeIssues.filter((i) => i.type === 'registered-missing').length;
     const beforeDangling = beforeIssues.filter((i) => i.type === 'dangling-registration').length;
+    const beforeEmptyDirs = beforeIssues.filter((i) => i.type === 'unregistered-dir' && i.empty).length;
     const result = await pruneWorktrees(targetPath);
     if (result.pruned) logger.success(`git worktree prune: ${beforeMissing} registro(s) órfão(s) removido(s).`);
     else logger.warn(`prune falhou: ${result.error}`);
+    if (result.removedEmptyDirs.length) {
+      logger.success(`${result.removedEmptyDirs.length}/${beforeEmptyDirs} diretório(s) vazio(s) removido(s): ${result.removedEmptyDirs.join(', ')}`);
+    }
     if (result.clearedRegistrations.length) {
       logger.success(`registro de worktree limpo em ${result.clearedRegistrations.length}/${beforeDangling} feature(s): ${result.clearedRegistrations.map((r) => r.feature).join(', ')}`);
     }
   }
 
   const issues = auditWorktrees(targetPath);
+  // `severity: 'info'` entries (a worktree carrying unintegrated work) are
+  // REPORTED but are not failures — a `doctor --worktrees || ...` in CI must not
+  // go red because somebody has an open PR. The human path below splits the same
+  // way; both surfaces must agree on what counts as broken.
+  const isProblem = (i) => i.severity !== 'info';
 
   if (options.json) {
     console.log(JSON.stringify({ issues }, null, 2));
-    return issues.length === 0;
+    return !issues.some(isProblem);
   }
 
   logger.header('MORPH-SPEC Worktrees');
@@ -589,18 +603,90 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
     return true;
   }
 
-  logger.warn(`${issues.length} inconsistência(s):`);
-  for (const i of issues) {
+  // `unintegrated-work` is NOT an inconsistency — it is a worktree doing its
+  // job, reported so the reader knows why no cleanup is offered for it. Counting
+  // it as a problem is how a diagnostic starts nagging people into destroying
+  // things to make the warning go away.
+  const informational = issues.filter((i) => !isProblem(i));
+  const problems = issues.filter(isProblem);
+
+  if (problems.length) logger.warn(`${problems.length} inconsistência(s):`);
+  for (const i of problems) {
     console.log(`  ⚠ ${i.type}`);
     console.log(`     ${i.detail}`);
     console.log(`     → ${i.fix}`);
   }
-  if (issues.some((i) => i.type === 'registered-missing' || i.type === 'dangling-registration') && !options.prune) {
-    logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos.');
+  for (const i of informational) {
+    console.log(`  ℹ ${i.type}`);
+    console.log(`     ${i.detail}`);
+    console.log(`     → ${i.fix}`);
+  }
+  // An EMPTY unregistered directory is prunable too — it holds nothing that can
+  // be lost — so the hint must mention it, or the one issue `--prune` now fixes
+  // automatically would still read as a manual chore.
+  const prunable = (i) => i.type === 'registered-missing'
+    || i.type === 'dangling-registration'
+    || (i.type === 'unregistered-dir' && i.empty);
+  if (problems.some(prunable) && !options.prune) {
+    logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos e os diretórios vazios.');
+  }
+  if (!problems.length) {
+    logger.success('Nenhuma inconsistência — os itens acima são informativos.');
+    return true;
   }
   return false;
 }
 
+/** Dias a partir dos quais um PR aberto vira aviso. */
+const PR_STALE_DAYS = 7;
+
+/**
+ * As inconsistências de PR desta árvore.
+ *
+ *   pr-awaiting-merge   — PR aberto há muito, sem cópia local: trabalho em
+ *                         revisão que nenhuma superfície local reivindica.
+ *   pr-merged-not-landed — o PR mergeou mas `archive/{f}` não está aqui. O
+ *                         archive viaja no diff do PR, então ou falta um
+ *                         `git pull`, ou ele não estava no diff.
+ *
+ * Offline-safe: índice `null` devolve `null`, NUNCA lista vazia — lista vazia
+ * afirmaria "perguntei e não achei nada", que é diferente de "não pude
+ * perguntar". Achado #3: um `[]` disfarçado de "sem problema" é o que fazia
+ * `doctor` imprimir `✓ pull requests` mesmo sem conseguir consultar o `gh`.
+ *
+ * @returns {Array<{feature:string,type:string,detail:string}>|null}
+ *   null = DESCONHECIDO (índice não pôde ser construído); nunca "sem PRs".
+ */
+function auditPullRequests(root) {
+  const index = buildPrIndex(root);
+  if (!index) return null;
+  const issues = [];
+
+  for (const p of pendingPrFeatures(root, { index }) || []) {
+    if (p.ageDays != null && p.ageDays >= PR_STALE_DAYS) {
+      issues.push({
+        feature: p.feature,
+        type: 'pr-awaiting-merge',
+        detail: `PR #${p.number} aberto há ${p.ageDays}d e sem cópia local — mergeie ou feche`,
+      });
+    }
+  }
+
+  for (const [branch, pr] of index) {
+    const m = branch.match(MORPH_BRANCH_RE);
+    if (!m || pr.state !== 'MERGED') continue;
+    const feature = m[1];
+    if (existsSync(join(root, '.morph', 'archive', feature))) continue;
+    issues.push({
+      feature,
+      type: 'pr-merged-not-landed',
+      detail: `PR #${pr.number} foi mergeado mas .morph/archive/${feature} não está aqui — falta \`git pull\`?`,
+    });
+  }
+
+  return issues;
+}
+
 export async function doctorCommand(options = {}) {
   // `--json` and `--prune` only mean something under `--worktrees`. Falling
   // through to the human health check would hand a script a banner and a table
@@ -1075,6 +1161,32 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
+  // Pull requests — o pendurado (aberto há dias sem cópia local) e o mergeado
+  // que não pousou (archive não chegou nesta árvore). Offline-safe: sem `gh`,
+  // sem origin no GitHub, ou qualquer falha, `auditPullRequests` nunca lança
+  // (achado #7 — mesma guarda fail-open que `fleet-scanner.js` já usa para a
+  // síntese idêntica) e devolve `null` — achado #3: um índice desconhecido
+  // renderiza como "não verificado", nunca como `✓ ok`, porque `[]` e
+  // "não pude perguntar" não são a mesma coisa.
+  let prIssues;
+  try {
+    prIssues = auditPullRequests(targetPath);
+  } catch {
+    prIssues = null; // fail-open — um doctor não pode ficar mais ruidoso porque o gh sumiu
+  }
+  if (prIssues === null) {
+    checks.push({ name: 'pull requests', status: 'skip', msg: 'gh indisponível — não verificado' });
+  } else if (prIssues.length === 0) {
+    checks.push({ name: 'pull requests', status: 'ok' });
+  } else {
+    checks.push({
+      name: 'pull requests',
+      status: 'warn',
+      msg: `${prIssues.length} pendência${prIssues.length === 1 ? '' : 's'} (veja abaixo)`,
+    });
+    hasWarnings = true;
+  }
+
   // Codebase graph — opcional (ADR-002). Nunca 'missing': um projeto que não
   // usa o grafo tem de continuar com o doctor verde.
   const graphAudit = auditGraph(targetPath);
@@ -1130,6 +1242,11 @@ export async function doctorCommand(options = {}) {
       console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(' (missing)'));
     } else if (check.status === 'error') {
       console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(` (${check.msg})`));
+    } else if (check.status === 'skip') {
+      // "Não verificado" — nem ok nem falha. Nunca soma em hasWarnings/hasErrors:
+      // um `gh` indisponível não pode deixar o doctor mais barulhento nem mudar
+      // o exit code (achado #3).
+      console.log(chalk.gray(`  ○ ${check.name}`) + chalk.gray(check.msg ? ` (${check.msg})` : ''));
     }
   }
 
@@ -1144,6 +1261,17 @@ export async function doctorCommand(options = {}) {
     console.log(chalk.gray("    Fix: 'morph-spec approve' (order), '--description' on create, or 'morph-spec delete' for dead scaffolds."));
   }
 
+  // Per-feature detail for the PR inconsistencies (item: pendurado ou merge
+  // que não pousou).
+  if (prIssues?.length) {
+    logger.blank();
+    console.log(chalk.yellow('  Pull requests pendentes:'));
+    for (const issue of prIssues) {
+      console.log(chalk.gray(`    • ${issue.feature} [${issue.type}] — ${issue.detail}`));
+    }
+    console.log(chalk.gray('    `finish --pr` abre o PR; quem encerra a feature é o merge.'));
+  }
+
   logger.blank();
 
   if (hasErrors) {

package/src/commands/project/fleet.js

@@ -55,14 +55,21 @@ export function fleetCommand(options = {}) {
   };
 
   console.log(chalk.white.bold(
-    col('FEATURE', 20) + col('TYPE', 9) + col('PHASE', 11) + col('TASKS', 8)
+    // PHASE at 18: `aguardando-merge` (the pr-pending synthesized phase, see
+    // fleet-scanner.js) is 16 chars — 1 wider than the col width `list.js`
+    // already uses (17) for the identical string. A narrower column here
+    // would misalign every column after it just for that one row.
+    col('FEATURE', 20) + col('TYPE', 9) + col('PHASE', 18) + col('TASKS', 8)
     + col('GATES PEND.', 20) + col('WHERE', 24) + col('REMOTO', 16) + col('CLAIM', 16)
     + col('PORTS', 12) + col('HANDOFF', 9) + 'ATIVIDADE',
   ));
   for (const e of fleet.entries) {
     const tasks = e.tasks ? `${e.tasks.done}/${e.tasks.total}` : '-';
     const gates = e.pendingGates.length ? e.pendingGates.join(',') : '-';
-    const where = e.location === 'worktree' ? e.branch : 'raiz';
+    // pr-pending has no worktree and isn't root-resident either — its branch
+    // is the only place it exists, so show that instead of the misleading
+    // 'raiz' a location-blind check would print.
+    const where = (e.location === 'worktree' || e.location === 'pr-pending') ? e.branch : 'raiz';
     const ports = e.env ? `${e.env.range[0]}-${e.env.range[1]}` : '-';
     const handoff = e.handoff?.exists ? 'sim' : '-';
     const activity = [
@@ -73,7 +80,7 @@ export function fleetCommand(options = {}) {
     // length and append the padding by hand.
     const claimPlain = e.claim ? `${e.claim.live ? 'sessão' : 'morta'} (${claimAge(e.claim)})` : '-';
     console.log(
-      col(e.feature, 20) + col(e.workType || '-', 9) + col(e.phase, 11) + col(tasks, 8)
+      col(e.feature, 20) + col(e.workType || '-', 9) + col(e.phase, 18) + col(tasks, 8)
       + col(gates, 20) + col(where, 24) + col(remoteCell(e.remote), 16)
       + claimCell(e.claim) + ' '.repeat(Math.max(1, 16 - claimPlain.length))
       + col(ports, 12) + col(handoff, 9) + activity,

package/src/commands/project/worktree.js

@@ -35,6 +35,7 @@ import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, append
 import { join, resolve, dirname } from 'path';
 import chalk from 'chalk';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+import { triageIgnoredPaths } from '../../lib/worktree/ignored-triage.js';
 // The reparse scan lives in hooks/shared because the PreToolUse guardrail needs
 // the SAME answer this file does, and hooks can never import from `src/`.
 import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
@@ -767,23 +768,6 @@ export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
  */
 const IGNORED_SHIELDABLE_PREFIXES = ['.morph/'];
 
-/**
- * Well-known, regenerable build artifacts — `bin/`, `obj/` (dotnet), a real
- * `node_modules` left behind outside the setup-created junction, and
- * `*.tsbuildinfo` (tsc incremental cache). These are the everyday leftovers of
- * running a build/test cycle inside a worktree, not user data: they are fully
- * reproducible from source, and requiring `--discard-ignored` for every finish
- * that ever ran a build turns the flag from "explicit consent for a real risk"
- * into a rubber stamp nobody reads anymore. Auto-discarding them (like any
- * `discarded` entry, WITHOUT a backup — see the note below) is safe precisely
- * because "regenerable" is a stronger guarantee than "backed up".
- *
- * Deliberately narrow — do NOT add speculative patterns (`dist/`, `.next/`)
- * beyond what's proven to be pure noise; anything else stays in `blocking` by
- * default, requiring the explicit `--discard-ignored` consent.
- *
- * @param {string} p - forward-slash relative path from `git status --ignored`
- */
 /**
  * Whether a dirty root-side path is EXACTLY a sibling feature's live worktree
  * registration — see the call site (primaryRootUnexplainedDirt, the root-clean
@@ -811,16 +795,9 @@ function isLiveSiblingWorktreeRegistration(relPath, root, feature) {
   }
 }
 
-function isDisposableBuildArtifact(p) {
-  if (/\.tsbuildinfo$/.test(p)) return true;
-  const segments = p.split('/').filter(Boolean);
-  return segments.some((s) => s === 'bin' || s === 'obj' || s === 'node_modules');
-}
-
 /**
- * Split the worktree's GITIGNORED leftovers into what this command may remove
- * (morph's own, after a backup, or a known disposable build artifact, without
- * one) and what it must refuse to destroy.
+ * Split the worktree's GITIGNORED leftovers into what this command may delete
+ * outright, what it must COPY OUT first, and what it cannot even enumerate.
  *
  * Why this exists: `git worktree remove` deletes gitignored files outright, and
  * the clean-check that gates it uses `git status --porcelain`, which omits them
@@ -829,14 +806,33 @@ function isDisposableBuildArtifact(p) {
  * disposable; morph must not, because "not in git" is exactly the property that
  * makes a file unrecoverable.
  *
- * Fail-CLOSED: if the status call fails we cannot enumerate what is at stake, so
- * everything is reported as blocking.
+ * The buckets, and why refusing is no longer one of them: the earlier version
+ * blocked on ANY unrecognised gitignored path, which in practice meant blocking
+ * on `.env` files that were byte-identical to the primary root's — nothing was
+ * at stake, and the only escape offered (`--discard-ignored`) also destroyed the
+ * genuinely unique `keys/` next to them. `triageIgnoredPaths` answers the
+ * question that actually decides whether bytes are lost (see ignored-triage.js),
+ * so the command can PROCEED in every case, backing up only what exists nowhere
+ * else. A refusal survives for exactly one reason now: the backup FAILED.
+ *
+ *   shieldable — morph's own bookkeeping + anything EXCLUSIVE to this worktree.
+ *                Copied to `finish-backup` before the removal; a failed copy is
+ *                what declines the removal.
+ *   discarded  — build artifacts (regenerable) and REPLICABLE files (the root
+ *                holds the same path with the same SHA-256). Deleted without a
+ *                backup because neither loses bytes.
+ *   blocking   — the fail-CLOSED sentinel only: `git status --ignored` itself
+ *                failed, so we cannot enumerate what is at stake.
+ *
+ * `--discard-ignored` no longer means "destroy the unique ones too, blind"; it
+ * means SKIP THE BACKUP — the same removal, without the copy.
  *
  * @param {string} worktreePath
+ * @param {string} rootPath - the primary root, for the replica comparison
  * @param {{ discardIgnored?: boolean }} options
- * @returns {{ shieldable: string[], blocking: string[], discarded: string[] }}
+ * @returns {{ shieldable: string[], blocking: string[], discarded: string[], replicable: string[] }}
  */
-function classifyIgnoredLeftovers(worktreePath, options = {}) {
+function classifyIgnoredLeftovers(worktreePath, rootPath, options = {}) {
   let out;
   try {
     // `-z` + execFile: NUL-delimited, no shell, no C-style quoting to undo —
@@ -850,30 +846,30 @@ function classifyIgnoredLeftovers(worktreePath, options = {}) {
     // empirically, not assumed.
     out = execFileSync('git', ['status', '--porcelain', '--ignored=matching', '-z'], { cwd: worktreePath, stdio: 'pipe' }).toString();
   } catch {
-    return { shieldable: [], blocking: ['<git status --ignored falhou — não foi possível enumerar o que seria destruído>'], discarded: [] };
+    return { shieldable: [], blocking: ['<git status --ignored falhou — não foi possível enumerar o que seria destruído>'], discarded: [], replicable: [] };
   }
 
-  const shieldable = [];
-  const blockingRest = [];
-  const disposable = [];
+  const morphOwned = [];
+  const rest = [];
   for (const record of out.split('\0')) {
     if (!record || record.length < 4) continue;
     if (record.slice(0, 2) !== '!!') continue; // only ignored entries; the rest is the clean-check's job
     const p = record.slice(3).replace(/\\/g, '/');
-    if (IGNORED_SHIELDABLE_PREFIXES.some((prefix) => p.startsWith(prefix))) shieldable.push(p);
-    else if (isDisposableBuildArtifact(p)) disposable.push(p);
-    else blockingRest.push(p);
+    if (IGNORED_SHIELDABLE_PREFIXES.some((prefix) => p.startsWith(prefix))) morphOwned.push(p);
+    else rest.push(p);
+  }
+
+  const { replicable, disposable, exclusive } = triageIgnoredPaths({ worktreePath, rootPath, paths: rest });
+  const shieldable = [...morphOwned, ...exclusive];
+
+  // Explicit consent = SKIP THE BACKUP, not "widen what dies". The same paths
+  // are removed either way; the flag only decides whether a copy is made first.
+  // The list is never thrown away — these are the bytes that exist nowhere
+  // else, and reporting them is the least this can do.
+  if (options.discardIgnored) {
+    return { shieldable: [], blocking: [], discarded: [...disposable, ...replicable, ...shieldable], replicable };
   }
-  // Explicit consent clears the rest of the block too — but the list is NOT
-  // thrown away. These are the files that exist nowhere else, and they are the
-  // ones about to die; reporting them is the least this can do. (Backing them
-  // up instead is not an option: this bucket is where arbitrarily large
-  // leftovers land, so a copy is unbounded. The user declared them
-  // disposable — they still get told.)
-  if (options.discardIgnored) return { shieldable, blocking: [], discarded: [...disposable, ...blockingRest] };
-  // Known build artifacts are discarded by default, no flag required — they
-  // are reproducible from source, unlike anything else in `blockingRest`.
-  return { shieldable, blocking: blockingRest, discarded: disposable };
+  return { shieldable, blocking: [], discarded: [...disposable, ...replicable], replicable };
 }
 
 /**
@@ -1177,7 +1173,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   const unlinked = unlinkWorktreeInfraLinks(worktreePath, root);
 
   const scan = findReparsePoints(worktreePath);
-  const ignored = classifyIgnoredLeftovers(worktreePath, options);
+  const ignored = classifyIgnoredLeftovers(worktreePath, root, options);
   const blockers = [...scan.points, ...scan.unprovable];
 
   // Back up ONLY once the removal is otherwise cleared: nothing is destroyed on
@@ -1257,14 +1253,22 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   const removeCmd = (addressByTarget || !isValidFeatureName(feature))
     ? `morph-spec worktree remove --target "${worktreePath}"`
     : `morph-spec worktree remove ${feature}`;
+  const backupDir = join(root, '.git', 'morph-spec', 'finish-backup');
+  const sample = (list) => `${list.slice(0, 5).join(', ')}${list.length > 5 ? `, +${list.length - 5}` : ''}`;
   const declineReason = worktreeRemoved
     ? null
     : ignored.blocking.length
-      ? `worktree NÃO removido: contém arquivo(s) gitignored que existem só ali e a remoção apagaria (${ignored.blocking.slice(0, 5).join(', ')}${ignored.blocking.length > 5 ? `, +${ignored.blocking.length - 5}` : ''}). Salve o que importa e rode \`${removeCmd}\`, ou \`${removeCmd} --discard-ignored\` para descartá-los deliberadamente`
+      ? `worktree NÃO removido: não foi possível enumerar os arquivos gitignored (${sample(ignored.blocking)}), então não dá para provar que a remoção não destrói nada. Rode \`git status --ignored\` dentro do worktree para ver o que está travando e tente de novo com \`${removeCmd}\``
       : blockers.length
         ? `worktree NÃO removido: ainda contém link(s)/caminho(s) não verificáveis (${blockers.join(', ')}) que a remoção seguiria para fora, apagando o alvo na raiz. Remova-os e rode \`${removeCmd}\``
         : ignored.shieldable.length && ignoredBackup === null
-          ? `worktree NÃO removido: o backup do gitignored do worktree falhou, e sem ele a remoção seria destrutiva. Libere espaço/permissão em \`.git/morph-spec/\` e rode \`${removeCmd}\`, ou \`${removeCmd} --discard-ignored\` se não precisar desse conteúdo`
+          // The ONLY gitignored refusal left. The old hint was circular — it
+          // said "salve o que importa e rode <the command that just failed>".
+          // This one names WHAT is exclusive, what was replicable (so the
+          // reader stops worrying about those), and WHERE the copy was going.
+          ? `worktree NÃO removido: o backup falhou. Estes arquivos existem só neste worktree e a remoção os apagaria: ${sample(ignored.shieldable)}. `
+            + (ignored.replicable.length ? `(${sample(ignored.replicable)} são idênticos aos da raiz — esses não são o problema.) ` : '')
+            + `O backup iria para \`${backupDir}\`; libere espaço/permissão ali e rode \`${removeCmd}\`, ou copie os arquivos você mesmo e rode \`${removeCmd} --discard-ignored\` para pular o backup`
           : removalFailure?.kind === 'in-use'
             ? `worktree NÃO removido: o diretório está EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd em "${worktreePath}"). A infra compartilhada ficou DESMONTADA de propósito — feche o que está usando o diretório e rode \`${removeCmd}\`. Se preferir continuar trabalhando nele, restaure a infra com \`morph-spec worktree link --all\``
             : `worktree NÃO removido: a remoção falhou${removalFailure?.detail ? ` (${removalFailure.detail})` : ''}. A infra compartilhada ficou DESMONTADA de propósito — rode \`${removeCmd}\` para tentar de novo, ou \`morph-spec worktree link --all\` para voltar a trabalhar nele`;
@@ -1273,6 +1277,14 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     worktreeRemoved,
     ignoredBackup,
     discarded: ignored.discarded,
+    replicable: ignored.replicable,
+    // The infra reparse points this teardown dropped BEFORE letting git near
+    // the directory. Reported because it is the load-bearing safety step of the
+    // whole operation and was previously invisible: the user had no way to see
+    // that `.claude` was a junction into the primary root, nor that it was
+    // unlinked rather than followed. On a removal it is the proof the root's
+    // real `.claude/` was never at risk.
+    unlinked,
     blockers,
     ignoredBlocking: ignored.blocking,
     shieldable: ignored.shieldable,
@@ -1405,13 +1417,24 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     ...(branch ? { branch } : {}),
     ...(feature ? { feature } : {}),
   };
+  // Reported on BOTH paths: on a removal it is the proof the primary root's
+  // real `.claude/`/`.morph/framework/` were unlinked rather than followed; on
+  // a refusal it is what `relinked` did or did not put back.
+  if (teardown.unlinked.length) out.unlinked = teardown.unlinked;
   if (teardown.worktreeRemoved) {
     if (teardown.discarded.length) out.discardedIgnored = teardown.discarded;
+    // Broken out of `discardedIgnored` on purpose: "deleted" and "deleted
+    // because the identical bytes are still in the root" are not the same
+    // report, and the second is the one that needs no follow-up from the user.
+    if (teardown.replicable.length) out.replicatedInRoot = teardown.replicable;
     if (teardown.ignoredBackup) out.ignoredBackup = teardown.ignoredBackup;
+    if (teardown.shieldable.length) out.backedUp = teardown.shieldable;
   } else {
     out.refused = teardown.refused;
     if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
     if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
+    if (teardown.shieldable.length) out.exclusiveIgnored = teardown.shieldable;
+    if (teardown.replicable.length) out.replicatedInRoot = teardown.replicable;
     if (teardown.infraLeftUnlinked.length) out.infraLeftUnlinked = teardown.infraLeftUnlinked;
     out.hint = teardown.declineReason;
   }