@polymorphism-tech/morph-spec 8.31.0 → 8.33.0

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: [] };
+}

package/src/lib/git/pending-prs.js

@@ -0,0 +1,89 @@
+/**
+ * pending-prs.js — as features que existem SÓ como PR aberto.
+ *
+ * `finish --pr` deixa o root primário sem vestígio da feature: o
+ * `shedRootFeatureScope` apaga `.morph/features/{f}` e o archive foi commitado
+ * na branch `morph/{f}`, chegando na default apenas no merge. Entre abrir e
+ * mergear, portanto, nenhuma superfície local sabe que aquela branch tem dono —
+ * foi assim que uma branch com PR #51 aberto quase foi varrida.
+ *
+ * Este módulo devolve o dono. Não há estado persistido a consultar, e é de
+ * propósito: o PR aberto no GitHub É o registro, a branch é sempre
+ * `morph/{feature}`, e o `pr-index.js` já é o leitor único desse fato. Lembrar
+ * o número numa segunda cópia só criaria como divergir dele.
+ *
+ * `null` (do índice ou daqui) significa DESCONHECIDO e jamais "não há
+ * pendência" — a mesma regra que torna seguros os caminhos destrutivos que
+ * leem o índice.
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { buildPrIndex } from './pr-index.js';
+
+/** As branches que o framework cria por feature. */
+export const MORPH_BRANCH_RE = /^morph\/(.+)$/;
+
+const DAY_MS = 86400000;
+
+/**
+ * O PR da branch canônica de uma feature.
+ *
+ * @param {Map<string,object>|null} index - de buildPrIndex
+ * @param {string} feature
+ * @returns {{number:number,state:string,mergedAt:string|null,url:string|null,createdAt:string|null}|null}
+ *   null = desconhecido OU sem PR; quem precisa distinguir os dois olha o índice.
+ */
+export function prForFeature(index, feature) {
+  if (!index) return null;
+  return index.get(`morph/${feature}`) || null;
+}
+
+/** A feature tem pasta (ativa ou arquivada) nesta árvore? */
+function hasLocalFolder(root, feature) {
+  return existsSync(join(root, '.morph', 'features', feature))
+    || existsSync(join(root, '.morph', 'archive', feature));
+}
+
+/**
+ * As features aguardando merge: PR OPEN numa branch `morph/*` cujo slug não
+ * tem pasta nesta árvore.
+ *
+ * @param {string} root - a raiz a inspecionar (e de onde o `gh` roda)
+ * @param {{ index?: Map<string,object>|null, now?: Date }} [opts]
+ *   `index` injeta um índice já construído (o `list`/`fleet` constroem um por
+ *   processo e reaproveitam; os testes passam um sintético). Ausente = constrói.
+ * @returns {Array<{feature:string,branch:string,number:number,state:string,url:string|null,createdAt:string|null,ageDays:number|null}>|null}
+ *   null = DESCONHECIDO. Nunca lista vazia por falta de informação.
+ */
+export function pendingPrFeatures(root, opts = {}) {
+  const index = opts.index !== undefined ? opts.index : buildPrIndex(root);
+  if (!index) return null;
+
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const out = [];
+  for (const [branch, pr] of index) {
+    const m = branch.match(MORPH_BRANCH_RE);
+    if (!m) continue;
+    if (pr.state !== 'OPEN') continue;
+    const feature = m[1];
+    if (hasLocalFolder(root, feature)) continue;
+
+    let ageDays = null;
+    if (pr.createdAt) {
+      const t = Date.parse(pr.createdAt);
+      if (!Number.isNaN(t)) ageDays = Math.floor((now.getTime() - t) / DAY_MS);
+    }
+    out.push({
+      feature,
+      branch,
+      number: pr.number,
+      state: pr.state,
+      url: pr.url ?? null,
+      createdAt: pr.createdAt ?? null,
+      ageDays,
+    });
+  }
+  out.sort((a, b) => a.feature.localeCompare(b.feature));
+  return out;
+}

package/src/lib/git/pr-index.js

@@ -0,0 +1,70 @@
+/**
+ * pr-index.js — one `gh pr list` per process, shared by every caller that needs
+ * to answer "does a branch have a PR, and in what state".
+ *
+ * Extracted from `fleet-scanner.js` because three independent leaders now ask
+ * the SAME question and must get the SAME answer:
+ *
+ *   • `morph-spec fleet`        — the PR column
+ *   • `morph-spec branch prune` — a branch with an OPEN PR is never deleted,
+ *                                 and a MERGED one is deletable even when git
+ *                                 cannot see the merge (squash-merge)
+ *   • `morph-spec doctor --worktrees` — a worktree whose branch carries an open
+ *                                 PR must NOT be offered up for removal
+ *
+ * Fail-open by construction: no `gh`, not authenticated, not GitHub, or a
+ * timeout all yield `null`. `null` means "unknown", NEVER "no PR" — every
+ * caller must treat the two differently, because the destructive paths
+ * (prune, remove) are only safe when the answer is a positive fact.
+ */
+
+import { execFileSync } from 'child_process';
+import { resolveGh } from './gh.js';
+
+/**
+ * Build the branch → PR index for a repository.
+ *
+ * Gated on the origin URL actually pointing at github.com: `gh` against any
+ * other host is a guaranteed error, and paying its start-up cost to learn that
+ * on every call is pure latency.
+ *
+ * `--state all` on purpose: a MERGED PR is exactly the evidence a squash-merge
+ * erases from git history, and it is the whole reason `branch prune` exists.
+ * First wins — `gh` lists newest-first, so an OPEN PR shadows an older closed
+ * one on the same branch.
+ *
+ * @param {string} root - repository root to run `gh` from
+ * @param {{ limit?: number, timeout?: number }} [opts]
+ * @returns {Map<string,{number:number,state:string,mergedAt:string|null,url:string|null,createdAt:string|null}>|null}
+ *   null = DESCONHECIDO (sem gh / não é GitHub / falhou), não "sem PRs"
+ */
+export function buildPrIndex(root, opts = {}) {
+  const limit = String(opts.limit ?? 200);
+  const timeout = opts.timeout ?? 8000;
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: root, stdio: 'pipe' }).toString();
+    if (!/github\.com/i.test(url)) return null;
+    const { bin, prefix } = resolveGh();
+    const out = execFileSync(
+      bin,
+      [...prefix, 'pr', 'list', '--state', 'all', '--limit', limit,
+        '--json', 'number,state,headRefName,mergedAt,url,createdAt'],
+      { cwd: root, stdio: 'pipe', timeout },
+    ).toString();
+    const map = new Map();
+    for (const pr of JSON.parse(out)) {
+      if (pr?.headRefName && !map.has(pr.headRefName)) {
+        map.set(pr.headRefName, {
+          number: pr.number,
+          state: pr.state,
+          mergedAt: pr.mergedAt ?? null,
+          url: pr.url ?? null,
+          createdAt: pr.createdAt ?? null,
+        });
+      }
+    }
+    return map;
+  } catch {
+    return null;
+  }
+}