@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/commands/state/finish.js

@@ -24,113 +24,48 @@ import { runArchive } from './archive.js';
 import { dropLeftoverIgnore, withoutLeftoverIgnore } from '../../../framework/hooks/shared/graph-freshness.js';
 import { newBackupStamp, enforceBackupRetention, inspectFinishBackups } from '../../lib/worktree/finish-backup.js';
 
-/** workType → conventional-commit type. `hotfix` IS a fix; anything else is a chore. */
 const PR_TYPE_BY_WORK_TYPE = { feature: 'feat', bug: 'fix', hotfix: 'fix', chore: 'chore' };
 
 /** Git's soft limit for a subject line. */
 const PR_TITLE_MAX = 72;
 
-/**
- * The PR title for `finish --pr`.
- *
- * Was always `morph: {slug}` — so every PR in a repo whose hand-made ones follow
- * conventional commits (`fix(ui): coluna CRM nos dossiês…`) arrived shapeless
- * and said nothing about what changed (D4).
- *
- * Now: `{type}({slug}): {subject}` — the type from the feature's `workType`, the
- * slug kept as the scope (it is the traceability the old title at least had),
- * and the subject from the feature's own identity: `name` first (a human
- * deliberately titled it), then `description`, first line only. With neither,
- * degrade to `{type}: {slug}` rather than emit an empty subject.
- *
- * @param {string} feature
- * @param {object|null} fj - the feature.json
- * @returns {string}
- */
+// `{type}({slug}): {subject}`, the subject from `name` (unless it is the default slug), then
+// `description`, first line only; with neither, `{type}: {slug}`.
 export function buildPrTitle(feature, fj) {
   const type = PR_TYPE_BY_WORK_TYPE[fj?.workType] || 'chore';
 
   const named = typeof fj?.name === 'string' ? fj.name.trim() : '';
-  // The default `name` IS the slug (create stamps it), which as a subject would
-  // only repeat the scope — treat it as absent.
+  // The default `name` IS the slug, which as a subject would only repeat the scope.
   const described = typeof fj?.description === 'string' ? fj.description.trim() : '';
   const raw = (named && named !== feature ? named : described).split('\n')[0].trim();
   if (!raw) return `${type}: ${feature}`;
 
   const prefix = `${type}(${feature}): `;
   const room = PR_TITLE_MAX - prefix.length;
-  // A scope so long there is no room left for a subject: drop the scope rather
-  // than ship a title that is all prefix.
+  // No room left for a subject: drop the scope rather than ship a title that is all prefix.
   if (room < 12) return `${type}: ${raw}`.slice(0, PR_TITLE_MAX);
   return prefix + (raw.length <= room ? raw : `${raw.slice(0, room - 1)}…`);
 }
 
-const MEMORY_NOTE = 'o fechamento desta feature já está registrado no repositório (commit de archive, `decisions.md`, use cases promovidos, `git log`) — memória de sessão só para o que NENHUM deles guarda: decisão do usuário, pendência a observar em produção, custo medido.';
+const MEMORY_NOTE = 'o fechamento desta feature já está registrado no repositório (commit de archive, `plan.md` com as decisões, índice de ADRs, `git log`) — memória de sessão só para o que NENHUM deles guarda: decisão do usuário, pendência a observar em produção, custo medido.';
 
-/**
- * `morph-spec finish <feature> --pr|--merge` — the single, symmetric close of a
- * feature's lifecycle, for BOTH the worktree flow and the common flow.
- *
- * Order (see the plan's backbone): validate → ARCHIVE inside the `morph/{f}`
- * branch (committed, so the archived state travels in one integration) →
- * integrate:
- *   --merge  : merge `--no-ff` into the default branch, LOCAL (no push).
- *   --pr     : push `morph/{f}` + `gh pr create` (does NOT merge locally).
- * → teardown the worktree (PROVE-or-DECLINE) when there is one.
- *
- * Every refusal is fail-CLOSED, exit 1, and — since the `--pr` remote
- * preconditions run BEFORE the archive — a refused `--pr` leaves no side effect.
- * `finished` is the integration (the actual value); `worktreeRemoved` is the
- * best-effort teardown — two independent signals, as before.
- *
- * RESUMABLE. `merge-conflict`, `checkout-default-failed`, `push-failed` and
- * `pr-create-failed` all fail AFTER the archive, and legitimately so: the
- * archive commit is what travels with the branch. Re-running then found no
- * `features/{f}` and refused from scratch, so every mid-way failure demanded a
- * hand repair. Now a second run that finds the feature ARCHIVED on its own
- * branch, not yet merged into the default, picks up at the integration and says
- * `resumed: true` in its output — see Validation 0c.
- *
- * @param {string} feature
- * `--dry-run` desvia para {@link finishPreflight} ANTES de qualquer validação
- * que saia com exit 1 e ANTES de qualquer mutação: o pré-voo existe para
- * EXPLICAR, e um pré-voo que recusa pelos mesmos motivos do comando real não
- * explica nada.
- *
- * @param {{ pr?: boolean, merge?: boolean, keep?: boolean, keepVolumes?: boolean,
- *   push?: boolean, force?: boolean, discardIgnored?: boolean, dryRun?: boolean,
- *   cwd?: string }} [options]
- */
+// Every refusal is fail-CLOSED and happens BEFORE the archive, the first mutation. Resumable: a
+// later run that finds the feature archived on its branch but not integrated picks up there.
+// `--dry-run` diverts to finishPreflight before any exit-1 validation: a preflight explains.
 export async function finishCommand(feature, options = {}) {
   const cwd = options.cwd || process.cwd();
   const root = resolvePrimaryRoot(cwd);
   const rootNorm = resolve(root).replace(/\\/g, '/');
 
-  // A closed feature must not keep warning other sessions that someone is
-  // working on it (B1). Released on EVERY success path — hooking it into emit
-  // is the single point that covers merge/PR/--keep alike. Fail-open: a claim
-  // that outlives its feature only expires on its own TTL.
-  //
-  // The e2e stack is NOT reclaimed here: by the time a success is emitted the
-  // worktree that owns the compose file may already be gone. Each integration
-  // path calls `reclaimStack` immediately BEFORE its worktree teardown (or
-  // before its final emit in the common flow) — see stack-teardown.js.
-  //
-  // Set by Validation 0c when this run picks up an already-archived feature.
-  // Stamped onto EVERY payload emitted from that point on, success or refusal:
-  // a resume merges a branch the user did not archive in this run, and that has
-  // to be visible. Someone who mistypes a name and lands on an archived feature
-  // would otherwise get a silent merge they never asked for.
+  // The claim is released on every success through emit (fail-open: a stale claim expires on its
+  // TTL). The e2e stack is reclaimed by each path BEFORE its worktree teardown, never here.
+  // `resumed` goes on every payload, so a merge of a feature archived by an earlier run is visible.
   let resumed = false;
 
-  // ONE stamp for every backup this run writes: the shed's and the teardown's
-  // folders then count as a single backup under the retention.
+  // ONE stamp for every backup this run writes, so they count as a single backup in the retention.
   const backupStamp = newBackupStamp();
 
-  // The backup retention rides the same single point, AFTER this run's own
-  // backups exist (the shed and the teardown both precede every success emit).
-  // This run's stamp is protected: the prune never takes the backup it just
-  // made room for, even when backups stamped by a clock running ahead outrank it.
+  // Retention runs after this run's own backups exist, and never prunes this run's stamp.
   const emit = (obj) => {
     if (resumed) obj = { ...obj, resumed: true };
     if (obj?.finished === true) {
@@ -146,15 +81,12 @@ export async function finishCommand(feature, options = {}) {
     console.log(JSON.stringify(obj));
   };
 
-  // Gate 0: valid kebab name — anti command-injection (the name flows into every
-  // git/gh call below) and the same gate the worktree path always applied.
+  // Anti command-injection: the name flows into every git/gh call below.
   if (!isValidFeatureName(feature)) {
     emit({ finished: false, error: 'invalid-feature-name', feature });
     process.exit(1);
   }
 
-  // Mode: exactly one of --pr / --merge (they are alternative integrations — the
-  // finish merges OR opens a PR, never both, never neither).
   const wantPr = !!options.pr;
   const wantMerge = !!options.merge;
   if (wantPr === wantMerge) {
@@ -163,15 +95,8 @@ export async function finishCommand(feature, options = {}) {
   }
   const mode = wantPr ? 'pr' : 'merge';
 
-  // `--push` publica a DEFAULT depois de um merge local; o fluxo `--pr` não tem
-  // merge local nenhum (a default só recebe a feature quando o PR mergear), e
-  // já publica `morph/{f}` por conta própria. A combinação é um pedido que o
-  // comando não consegue honrar — e aceitar em silêncio o que não se pode
-  // honrar é exatamente o defeito que esta série de fixes existe para tirar do
-  // CLI (o `score` que gravava um zero fabricado, o `approve` que saía 0 sem
-  // aprovar nada). Recusa ALTA, e AQUI: junto do gate de modo, antes do
-  // archive — que é a primeira mutação do finish. Uma recusa depois dele
-  // deixaria a feature meio fechada, pior que o no-op que ela substitui.
+  // `--push` publica a default depois de um merge local, e o `--pr` não faz merge local: recusa
+  // AQUI, antes do archive (a primeira mutação), em vez de aceitar em silêncio o que não honra.
   if (wantPr && options.push) {
     emit({
       finished: false,
@@ -184,23 +109,16 @@ export async function finishCommand(feature, options = {}) {
 
   const expectedBranch = buildBranchName(feature);
 
-  // ── Resolve the flow ──────────────────────────────────────────────────────
-  // findWorktreeForFeature matches ANY worktree on morph/{feature} — including
-  // the PRIMARY ROOT itself when the common flow checked the branch out there.
-  // A match whose path IS the root is the common flow (no separate worktree to
-  // tear down); a match elsewhere is the worktree flow.
+  // findWorktreeForFeature also matches the PRIMARY ROOT when the common flow checked the branch
+  // out there: a match at the root is the common flow.
   const found = findWorktreeForFeature(feature, root);
   const isWorktreeFlow = !!found && found.path.replace(/\\/g, '/') !== rootNorm;
 
   let worktreePath = null;
-  let featureCwd = root; // where the feature's own tree (and Gate 3) lives
-
-  // ── PRÉ-VOO ───────────────────────────────────────────────────────────────
-  // AQUI, e não mais abaixo: as validações seguintes saem com exit 1 (branch
-  // divergente, cwd dentro do worktree, feature ausente), e o pré-voo existe
-  // justamente para ser rodado ANTES de o estado estar bom. Ele reporta o que
-  // encontrar — inclusive o cwd dentro do worktree, como AVISO — e sai 0 sem
-  // ter tocado em nada.
+  let featureCwd = root; // where the feature's own tree (and its review) lives
+
+  // Pré-voo AQUI, antes das validações que saem com exit 1: ele existe para rodar antes de o estado
+  // estar bom, reporta o que encontrar e sai 0 sem tocar em nada.
   if (options.dryRun) {
     emit(finishPreflight({
       feature,
@@ -209,17 +127,14 @@ export async function finishCommand(feature, options = {}) {
       cwd,
       mode,
       branch: expectedBranch,
-      // `options` INTEIRO, e não um subconjunto escolhido a dedo: `--discard-ignored`
-      // INVERTE a classificação (o exclusivo deixa de ser copiado e passa a ser
-      // destruído), então um pré-voo que não recebe as flags do comando prevê
-      // outro comando. Ver B1 na errata E4.
+      // `options` INTEIRO: `--discard-ignored` inverte a classificação, e um pré-voo sem as flags do
+      // comando prevê outro comando.
       options,
     }));
     return;
   }
 
   if (isWorktreeFlow) {
-    // Validation 0: the worktree must actually be ON the branch we will merge.
     if (found.branch !== found.expectedBranch) {
       emit({
         finished: false,
@@ -235,14 +150,8 @@ export async function finishCommand(feature, options = {}) {
     worktreePath = found.path;
     featureCwd = worktreePath;
 
-    // Validation 0b: the session's cwd must not be INSIDE the worktree we are
-    // about to tear down (A4). Windows holds a lock on the process's working
-    // directory, so `git worktree remove` fails — and by then the archive is
-    // committed, the branch merged, and the infra junctions already dropped.
-    // The result is a worse state than never having tried: an orphan directory,
-    // a de-registered worktree, and a `relinkHint` telling the user to repair
-    // by hand. Refuse HERE, before the first mutation — the cost is one
-    // `cd`, and it is the exact failure observed in the ProspectPRO session.
+    // Windows locks the process cwd, so `git worktree remove` would fail AFTER the archive and the
+    // merge, leaving an orphan directory. Refuse here, before the first mutation.
     if (cwdIsInsideWorktree(cwd, worktreePath)) {
       emit({
         finished: false,
@@ -255,15 +164,9 @@ export async function finishCommand(feature, options = {}) {
       process.exit(1);
     }
   } else {
-    // COMMON flow: the feature branch must exist and be the ROOT's current
-    // branch (so the archive commits on it and we can checkout the default to
-    // merge). A feature with NO morph/{f} branch was born before this flow —
-    // route it explicitly to archive-without-integrate, never a generic refusal.
+    // A feature with no morph/{f} branch predates this flow: route it to archive-without-integrate.
     if (!branchExists(expectedBranch, root)) {
-      // No branch AND no feature on disk is not a legacy feature — it is a
-      // feature that is not here at all (wrong name, wrong tree, or already
-      // archived). Routing that to `archive legacy` would tell the user to
-      // archive something that does not exist.
+      // No branch AND no folder is not a legacy feature: it is not here at all.
       if (!existsSync(join(root, '.morph', 'features', feature))) {
         emit({ finished: false, error: 'feature-not-found', feature, ...featureElsewhereHint(root, root, feature) });
         process.exit(1);
@@ -291,19 +194,8 @@ export async function finishCommand(feature, options = {}) {
     featureCwd = root;
   }
 
-  // Validation 0c: the feature must still be in `features/` — or, if it is not,
-  // this run has to decide which of three states it is in before doing anything:
-  // gone entirely, already ARCHIVED and awaiting integration (resume), or
-  // already integrated (nothing to do).
-  //
-  // Originally all three arrived as `review-not-approved`, because a missing
-  // feature.json parses to null and the optional chaining below fell straight
-  // through — being told "Gate 3 not approved" about an approved gate is what
-  // sent the user looking in the wrong place after an interrupted finish.
-  //
-  // Keyed on the DIRECTORY, not on the parse: readFeatureJson also returns null
-  // for malformed JSON, and a legacy feature with a folder but no (or broken)
-  // feature.json is a real thing that `--force` is expected to push through.
+  // Not in `features/`: gone, archived awaiting integration (resume), or already integrated. Keyed
+  // on the DIRECTORY, not the parse: a legacy folder with a broken feature.json is --force's case.
   if (!existsSync(join(featureCwd, '.morph', 'features', feature))) {
     const archivePath = join(featureCwd, '.morph', 'archive', feature);
     if (!existsSync(archivePath)) {
@@ -311,19 +203,8 @@ export async function finishCommand(feature, options = {}) {
       process.exit(1);
     }
 
-    // ── RESUME ──────────────────────────────────────────────────────────────
-    // Archived HERE, on the branch this finish would merge — every path that
-    // reaches this line has already proved we are standing on `morph/{f}`
-    // (worktree flow: found.branch === expectedBranch; common flow: branchExists
-    // + currentBranch === expectedBranch). So the archive step is done and only
-    // the integration is missing. Which is exactly what a failed merge/push
-    // leaves behind, and what used to require repairing by hand.
-    //
-    // The one thing still to establish is whether the integration ALSO
-    // happened. A branch already contained in the default is a finish that
-    // COMPLETED (`--keep`, or a `--pr` whose PR was merged) — re-merging it is
-    // the hazard this check exists to stop, and it is why resume is keyed on
-    // the branch's relationship to the default rather than on the archive alone.
+    // Every path here already stands on `morph/{f}`, so only the integration is missing. A branch
+    // already contained in the default COMPLETED: re-merging it is the hazard this check stops.
     const target = detectDefaultBranch(root);
     if (!target) {
       emit({ finished: false, error: 'no-default-branch', hint: 'não foi possível resolver a branch default (origin/HEAD, main ou master)', feature });
@@ -331,9 +212,7 @@ export async function finishCommand(feature, options = {}) {
     }
     const merged = branchMergedInto(expectedBranch, target, root);
     if (merged === null) {
-      // PROVE-or-DECLINE, same discipline as the worktree teardown: we could not
-      // establish the branch's state, so we do not act on a guess. Refusing is
-      // recoverable; a duplicate merge is not.
+      // PROVE-or-DECLINE: refusing is recoverable, a duplicate merge is not.
       emit({
         finished: false,
         error: 'resume-undecidable',
@@ -358,17 +237,8 @@ export async function finishCommand(feature, options = {}) {
       process.exit(1);
     }
 
-    // "Already integrated" is MODE-SPECIFIC, and the ancestor test above only
-    // answers it for `--merge`. A `--pr` that completed leaves its branch
-    // deliberately UNMERGED (that is what the open PR is for), so the ancestor
-    // test says "not merged" and would wave the resume through — straight into
-    // a second `gh pr create` on a head that already has one. The common flow
-    // makes that trivially reachable: integratePr never leaves `morph/{f}`, so
-    // simply re-running the command lands here.
-    //
-    // `gh pr create` refuses a duplicate, so the damage was never two PRs — it
-    // was `pr-create-failed` standing in for "this already finished", which is
-    // the same collapsed diagnosis the `feature-not-found` split removed.
+    // "Already integrated" is per mode: a completed `--pr` leaves its branch unmerged on purpose, so
+    // the ancestor test alone would wave a second `gh pr create` through.
     if (mode === 'pr') {
       const openPr = openPrFor(expectedBranch, root);
       if (openPr === null) {
@@ -400,17 +270,8 @@ export async function finishCommand(feature, options = {}) {
     resumed = true;
   }
 
-  // Validation 1: Gate 3 (review) approved on the feature's own feature.json —
-  // which on a resume lives in `archive/{f}`, where runArchive moved it.
-  //
-  // NOT re-checked on a resume, deliberately. The archive IS the gate's receipt:
-  // runArchive refuses `review-not-approved` itself, so a feature that reached
-  // `archive/` either passed Gate 3 or was explicitly forced past it. Re-reading
-  // it here would only add a way to fail — an archive whose feature.json is
-  // absent or unparseable (legacy shapes, a forced close) parses to null and
-  // falls straight through to `review-not-approved`, which is the exact
-  // collapsed diagnosis the `feature-not-found` fix removed. Resume integrates
-  // what was already archived; it does not re-litigate why.
+  // Not re-checked on a resume: the archive IS the gate's receipt (runArchive refuses without
+  // the review gate), and an archive with no readable feature.json would only fail here wrongly.
   const fj = readFeatureJson(featureCwd, feature, resumed ? 'archive' : 'features');
   if (!resumed && !options.force && !(fj?.approvalGates?.review?.approved === true || fj?.approvals?.review?.approved === true)) {
     emit({ finished: false, error: 'review-not-approved', feature });
@@ -421,8 +282,7 @@ export async function finishCommand(feature, options = {}) {
     ? String(fj.description).trim()
     : `Feature ${feature} — integrada via morph-spec finish --pr.`;
 
-  // Validation 2: the tree that will carry the archive commit must be clean
-  // (work committed), so the scoped archive commit contains only the move.
+  // Clean, so the scoped archive commit contains only the move.
   const cleanCwd = isWorktreeFlow ? worktreePath : root;
   const dirty = gitStatusPorcelain(cleanCwd);
   if (dirty === null) {
@@ -434,8 +294,7 @@ export async function finishCommand(feature, options = {}) {
     process.exit(1);
   }
 
-  // Default branch — needed as the merge target and the PR base. Never assume
-  // "master"; refuse clearly when it cannot be resolved.
+  // Never assume "master".
   const defaultBranch = detectDefaultBranch(root);
   if (!defaultBranch) {
     emit({ finished: false, error: 'no-default-branch', hint: 'não foi possível resolver a branch default (origin/HEAD, main ou master)', feature });
@@ -446,20 +305,8 @@ export async function finishCommand(feature, options = {}) {
     process.exit(1);
   }
 
-  // ── MERGE precondition, BEFORE the archive ────────────────────────────────
-  // `--merge` lands its merge commit in the PRIMARY ROOT, so the root has to be
-  // clean. That check used to live inside integrateMerge — i.e. AFTER
-  // runArchive had already moved the feature to .morph/archive/, promoted its
-  // use cases and COMMITTED. A root dirtied by unrelated work therefore got a
-  // refusal on a half-finished feature, and the retry then failed for a
-  // different reason entirely (the feature was no longer in features/).
-  //
-  // `exemptOwnScope` because shedRootFeatureScope has not run yet: this
-  // feature's own root-side scaffold is still on disk and is not a reason to
-  // refuse — the shed backs it up and discards it moments later.
-  //
-  // `--pr` is exempt by design: integratePr pushes from the root but never
-  // checks out or merges there, so root dirt cannot corrupt it.
+  // BEFORE the archive: a dirty root refused after it left a half-finished feature. The own scope
+  // is exempt (the shed discards it next), and `--pr` never checks out or merges in the root.
   if (mode === 'merge' && isWorktreeFlow) {
     const rootPre = primaryRootUnexplainedDirt(root, feature, { exemptOwnScope: true });
     if (!rootPre.ok) {
@@ -477,8 +324,7 @@ export async function finishCommand(feature, options = {}) {
     }
   }
 
-  // ── PR preconditions run BEFORE the archive, so a refused --pr has NO side
-  //    effect (nothing archived, nothing committed). ─────────────────────────
+  // BEFORE the archive, so a refused --pr has no side effect.
   if (mode === 'pr') {
     if (!hasOriginRemote(root)) {
       emit({ finished: false, error: 'no-origin-remote', hint: 'não há remoto `origin` para abrir PR — configure um ou use --merge', feature });
@@ -490,9 +336,7 @@ export async function finishCommand(feature, options = {}) {
     }
   }
 
-  // ── ARCHIVE (inside morph/{f}) ────────────────────────────────────────────
-  // Every refusal is behind us: the leftover of a killed `graph refresh` goes now,
-  // before the archive — never before a precondition that could still refuse.
+  // Every refusal is behind us: the leftover of a killed `graph refresh` goes now, never before.
   dropLeftoverIgnore(cleanCwd);
   const arch = runArchive(feature, { cwd: featureCwd, force: options.force, git: true });
   if (!arch.ok) {
@@ -506,66 +350,26 @@ export async function finishCommand(feature, options = {}) {
     process.exit(1);
   }
 
-  // ── INTEGRATE ─────────────────────────────────────────────────────────────
   if (mode === 'merge') {
     return integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch, backupStamp });
   }
   return integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch, backupStamp });
 }
 
-/**
- * O aviso que acompanha CADA reparse point listado pelo pré-voo.
- *
- * Exportado porque é a frase que carrega o fato: uma junction/symlink dentro do
- * worktree aponta para conteúdo que vive na RAIZ, e `rm -rf` / `git worktree
- * remove --force` atravessam o link. Já aconteceu: um `worktree remove --force`
- * atravessou a junction e apagou o `node_modules` da raiz.
- */
+// A junction/symlink in the worktree points at content in the ROOT, and `rm -rf` or
+// `git worktree remove --force` traverse it.
 export const REPARSE_WARNING =
   'estes são junctions/symlinks: apagá-los fora do morph-spec apaga o conteúdo REAL na raiz';
 
-/**
- * `morph-spec finish <feature> --pr|--merge --dry-run` — o PRÉ-VOO.
- *
- * NÃO MUTA NADA. Nenhum commit, nenhum archive, nenhum worktree removido,
- * nenhum `gh` que crie coisa alguma, nenhum `git fetch`. Ele responde, ANTES,
- * as três perguntas que hoje só se respondem depois do estrago:
- *
- *   1. O que este `finish` vai COPIAR para o backup e o que vai DESCARTAR?
- *      (`classifyIgnoredLeftovers` — a MESMA função que o teardown consulta;
- *      um segundo enumerador aqui faria o pré-voo prometer o que o comando não
- *      cumpre, e um dry-run que mente é pior que nenhum.)
- *   2. Que reparse points existem, e o que significa apagá-los por fora?
- *      (`findReparsePoints`, exaustivo e fail-closed.)
- *   3. A base andou? — a pergunta INVERSA da de #89. Lá se mede "quantos
- *      commits EU tenho que o upstream não tem"; aqui, "quantos commits
- *      `origin/{default}` tem que a MINHA base não tem", que é o que decide se
- *      este merge vai ser trivial ou uma surpresa. Mesma função
- *      (`commitsAhead`), argumentos invertidos.
- *
- * `cwd` dentro do worktree é AVISO, não recusa: o caminho real continua
- * recusando antes da primeira mutação (Validation 0b), e recusar aqui negaria
- * ao usuário justamente a explicação que ele veio buscar — do lugar mais
- * provável de estar quando a pede.
- *
- * SEM `git fetch` implícito: um fetch dentro de um comando que promete não
- * mexer em nada é efeito colateral de rede. O pré-voo AVISA que o dado pode
- * estar velho e sugere o fetch.
- *
- * @param {{ feature: string, root: string, worktreePath: string|null,
- *   cwd: string, mode: 'pr'|'merge', branch: string,
- *   options?: { discardIgnored?: boolean, keep?: boolean } }} args
- * @returns {object} o payload emitido — nunca lança
- */
+// NÃO MUTA NADA: nenhum commit, archive, remoção, `gh` que crie algo nem `git fetch` (efeito de
+// rede). Usa as MESMAS funções do comando real, senão o pré-voo promete o que o comando não
+// cumpre. `cwd` dentro do worktree é AVISO, não recusa. Nunca lança.
 export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch, options = {} }) {
   const warnings = [];
 
-  // ── A base andou? (vale COM e SEM worktree — UC-16 A1) ────────────────────
   const defaultBranch = detectDefaultBranch(root);
   const baseRef = defaultBranch ? resolveBaseRef(defaultBranch, root) : null;
-  // `commitsAhead(base, branch)` conta `base..branch`. Passando a branch da
-  // feature como BASE e o baseRef como BRANCH, contamos o que a default tem e a
-  // feature não — exatamente a pergunta inversa.
+  // `commitsAhead` conta `base..branch`: invertidos, contam o que a default tem e a feature não.
   const commits = baseRef && branchExists(branch, root)
     ? commitsAhead(branch, baseRef, root)
     : null;
@@ -577,9 +381,7 @@ export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch
     mode,
     branch,
     baseAdvanced: { ref: baseRef, commits },
-    // `null` é DESCONHECIDO e nunca é renderizado como 0 (UC-16 P6): "não deu
-    // para perguntar" e "a default não andou" são fatos opostos, e confundi-los
-    // é como um `--dry-run` passa confiança que não tem.
+    // `null` é DESCONHECIDO, nunca 0: "não deu para perguntar" e "não andou" são fatos opostos.
     baseAdvancedNote: commits === null
       ? (baseRef === null
         ? 'sem contraparte remota nem branch default resolvível — a contagem é DESCONHECIDA, não zero'
@@ -601,10 +403,8 @@ export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch
 
   if (defaultBranch) out.defaultBranch = defaultBranch;
 
-  // A retenção dos backups também é mutação do finish real — a AUTOMÁTICA, que
-  // não toca backup sem manifesto (esses só o `doctor --worktrees --prune`
-  // poda). A contagem é a de AGORA: o backup que este finish gravar ainda pode
-  // empurrar mais um para fora.
+  // A retenção automática também é mutação do finish real; a contagem é a de AGORA, antes do
+  // backup que este finish gravar.
   try {
     const retention = inspectFinishBackups(root);
     if (retention.policy.skipped) {
@@ -625,7 +425,6 @@ export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch
     }
   } catch { /* o pré-voo nunca lança */ }
 
-  // ── Seções de worktree — omitidas quando não há worktree (UC-16 A1) ───────
   if (worktreePath) {
     out.worktreePath = worktreePath.replace(/\\/g, '/');
 
@@ -647,24 +446,17 @@ export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch
       );
     }
 
-    // AS MESMAS FLAGS do comando real. `--discard-ignored` INVERTE a
-    // classificação — o exclusivo deixa de ser copiado e entra no lote
-    // destruído sem backup — então prever com `options` vazio é prever OUTRO
-    // comando. Medido antes do conserto: o pré-voo prometia salvar caminhos que
-    // o `--discard-ignored` destruía. Normalizado com `=== true` para que
-    // `undefined` e `false` sejam a mesma coisa, como no `worktree remove`.
+    // As MESMAS flags do comando real: `--discard-ignored` inverte a classificação, então prever com
+    // `options` vazio é prever outro comando.
     const discardIgnored = options.discardIgnored === true;
     const ignored = classifyIgnoredLeftovers(worktreePath, root, { discardIgnored });
     out.discardIgnored = discardIgnored;
     out.ignored = {
-      // COPIADO para .git/morph-spec/finish-backup antes da remoção: existe só
-      // aqui, ou difere do que está na raiz. Com `--discard-ignored` esta lista
-      // sai VAZIA por construção — a flag significa "pule o backup".
+      // Copiado para o backup; vazio por construção sob `--discard-ignored`.
       shieldable: ignored.shieldable,
       // Idêntico byte a byte ao da raiz (SHA-256): apagar não perde nada.
       replicable: ignored.replicable,
-      // Artefato regenerável + os replicáveis (+ o exclusivo, sob a flag):
-      // descartado sem backup.
+      // Descartado sem backup.
       discardable: ignored.discarded,
     };
     if (ignored.blocking.length) {
@@ -673,12 +465,8 @@ export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch
     }
 
     if (discardIgnored) {
-      // SEGUNDA leitura, deliberada e só aqui: sob a flag, `shieldable` sai
-      // vazia e a informação mais valiosa do pré-voo — QUAIS destes existem só
-      // aqui — desapareceria justamente no modo destrutivo. Perguntar à MESMA
-      // função, sem a flag, é a única forma de nomeá-los sem recriar a regra
-      // (uma segunda cópia da triagem é o defeito que o export de
-      // `classifyIgnoredLeftovers` existe para evitar).
+      // Sob a flag `shieldable` sai vazia: perguntar à MESMA função sem a flag nomeia o que existe só
+      // aqui, sem recriar a regra.
       const semFlag = classifyIgnoredLeftovers(worktreePath, root);
       out.ignored.discardableExclusive = semFlag.shieldable;
       if (semFlag.shieldable.length) {
@@ -705,23 +493,17 @@ export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch
   return out;
 }
 
-// ── merge integration (local, no push) ───────────────────────────────────────
-
 async function integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch, backupStamp }) {
   const mergeMsg = `morph-spec finish: merge ${expectedBranch}`;
-  const ucNote = promotedNote(arch);
+  const adrNote = adrIndexNote(arch);
 
   if (isWorktreeFlow) {
-    // The root stays on the default; shed this feature's own root-side scaffold,
-    // then guard the whole root before landing the merge commit.
+    // Shed this feature's root-side scaffold, then guard the whole root before the merge commit.
     const { shedBackup } = shedRootFeatureScope(root, feature, { stamp: backupStamp });
     const backupNote = shedBackup ? { shedBackup } : {};
 
-    // Final gate before the merge commit lands. The pre-archive check above
-    // already refused an unrelated-dirt root WITHOUT side effects, so reaching
-    // a refusal HERE means the shed itself dirtied the root — a bug signal, not
-    // user error. Kept because this is the last moment before we mutate the
-    // default branch, and it is nearly free.
+    // The pre-archive check already refused unrelated dirt, so a refusal here means the shed
+    // dirtied the root: a bug signal. Last moment before mutating the default branch.
     const rootClean = primaryRootUnexplainedDirt(root, feature);
     if (!rootClean.ok) {
       emit({ finished: false, error: 'primary-root-status-failed', feature, ...backupNote });
@@ -748,30 +530,24 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
       dropFromRootIndex(root, feature);
       emit({
         ...mergeOutput({ feature, branch: expectedBranch, defaultBranch, publish, worktreePath, shedBackup, kept: true }),
-        ...ucNote,
+        ...adrNote,
       });
       process.exit(0);
     }
 
-    // The stack comes down BEFORE the worktree: the compose file, the bind
-    // mount and the port block all belong to that tree, and once it is gone
-    // there is nothing left to address the containers by.
+    // The stack comes down BEFORE the worktree, which holds its compose file, bind mount and ports.
     const e2e = reclaimStack(feature, { root, worktreePath, options });
-    // The session that ran this finish may be ANCHORED in the worktree (its
-    // hooks resolve `.morph/framework` through it): tearing it down now would
-    // kill every hook of that session. The integration is done; only the
-    // teardown waits (see sessionAnchoredInWorktree).
+    // A session ANCHORED in the worktree resolves its hooks through it: tearing it down now would
+    // kill every hook of that session, so only the teardown waits.
     const deferred = sessionAnchoredInWorktree(worktreePath);
     const teardown = deferred
       ? null
       : await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: true, stamp: backupStamp });
     dropFromRootIndex(root, feature);
-    emit({ ...mergeOutput({ feature, branch: expectedBranch, defaultBranch, publish, worktreePath, teardown, shedBackup, deferred }), ...ucNote, e2e });
+    emit({ ...mergeOutput({ feature, branch: expectedBranch, defaultBranch, publish, worktreePath, teardown, shedBackup, deferred }), ...adrNote, e2e });
     process.exit(0);
   }
 
-  // COMMON flow: we are on morph/{f} in the root, archive committed. Move to the
-  // default and merge the feature branch in.
   try {
     execFileSync('git', ['checkout', defaultBranch], { cwd: root, stdio: 'pipe' });
   } catch (err) {
@@ -786,8 +562,6 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
       finished: false,
       error: 'merge-conflict',
       output: gitErr(err),
-      // The abort left the working dir on the default WITHOUT the feature — say
-      // where the intact work is so the user can recover it.
       hint: `conflito ao mergear ${expectedBranch} em ${defaultBranch}. Seu trabalho está intacto em ${expectedBranch} — rode \`git checkout ${expectedBranch}\` para voltar a ele`,
       feature,
     });
@@ -796,29 +570,16 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
   tryGit(['branch', '-d', expectedBranch], root);
   const publish = publicationState({ root, defaultBranch, push: options.push });
   const e2e = reclaimStack(feature, { root, worktreePath: null, options });
-  // The root index (gitignored) was already updated by the archive (same cwd).
-  emit({ ...mergeOutput({ feature, branch: expectedBranch, defaultBranch, publish }), ...ucNote, e2e });
+  emit({ ...mergeOutput({ feature, branch: expectedBranch, defaultBranch, publish }), ...adrNote, e2e });
   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}
- */
+// `null` for an unexpected format: better to admit not knowing the number than state a wrong one.
 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, backupStamp }) {
   try {
     execFileSync('git', ['push', '-u', 'origin', expectedBranch], { cwd: root, stdio: 'pipe' });
@@ -836,37 +597,27 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     process.exit(1);
   }
 
-  // Worktree flow: remove the worktree but KEEP the branch (the open PR needs it).
-  // Common flow: nothing to tear down; stay on morph/{f} (the default has no
-  // feature yet — honest until the PR merges).
+  // The worktree flow keeps the branch (the open PR needs it); the common flow stays on morph/{f},
+  // since the default has no feature until the PR merges.
   let teardown = null;
   let shedBackup = null;
-  // Reclaimed from the owning tree, before that tree goes away; skipped on
-  // --keep, where the worktree (and its stack) stays alive on purpose.
+  // Skipped on --keep, where the worktree and its stack stay alive on purpose.
   const e2e = isWorktreeFlow
     ? (options.keep ? null : reclaimStack(feature, { root, worktreePath, options }))
     : reclaimStack(feature, { root, worktreePath: null, options });
   let teardownDeferred = false;
   if (isWorktreeFlow && !options.keep) {
-    // Shed the transient root-side scaffold BEFORE teardown — exactly as --merge
-    // does. The real `create --worktree` leaves the root's .morph/features/{f}
-    // UNTRACKED; without this, teardown's clearRootWorktreeRegistration would
-    // `git add` + commit that scaffold onto the default branch. Then when the PR
-    // later merges (carrying features/{f} → archive/{f}), the default would hold
-    // the feature in BOTH features/ and archive/ at once — active and archived.
-    // The branch/PR owns the authoritative copy; the root scaffold is transient.
+    // Shed BEFORE teardown: otherwise clearRootWorktreeRegistration commits the untracked root
+    // scaffold to the default, and the merged PR leaves the feature in both features/ and archive/.
     shedBackup = shedRootFeatureScope(root, feature, { stamp: backupStamp }).shedBackup;
-    // Same deferral as --merge: never tear down the worktree the running
-    // session is anchored in (see sessionAnchoredInWorktree).
+    // Same deferral as --merge (sessionAnchoredInWorktree).
     if (sessionAnchoredInWorktree(worktreePath)) {
       teardownDeferred = true;
     } else {
       teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: false, stamp: backupStamp });
     }
-    // The shed removed the root's features/{f} scaffold from disk, but runArchive
-    // dropped the feature only from the WORKTREE's index (its cwd). Drop it from
-    // the ROOT index too — exactly as --merge does — or `doctor`'s lifecycle audit
-    // flags a `stale-index` phantom (index lists {f}, no folder on disk).
+    // runArchive dropped the feature only from the WORKTREE index: drop it from the root's too, or
+    // `doctor` flags a `stale-index` phantom.
     dropFromRootIndex(root, feature);
   }
 
@@ -875,10 +626,7 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
 
   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.
+    // O comando terminou, a INTEGRAÇÃO não: a default só recebe archive/{f} quando o PR mergear.
     integrated: false,
     awaiting: 'merge',
     mode: 'pr',
@@ -887,15 +635,14 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     base: defaultBranch,
     pr: { number: prNumber, url: prUrl },
     nextStep: `mergeie ${prLabel} — a feature só estará encerrada quando ${defaultBranch} receber o archive pelo merge`,
-    ...promotedNote(arch),
+    ...adrIndexNote(arch),
     ...(shedBackup ? { shedBackup } : {}),
     ...(e2e ? { e2e } : {}),
     ...(teardown
       ? { worktreeRemoved: teardown.worktreeRemoved, ...teardownExtras(teardown, worktreePath, expectedBranch, false) }
       : {
         worktreeRemoved: false,
-        // isWorktreeFlow && options.keep is the only way `teardown` stays null
-        // with a worktree still alive — the common flow has none to report.
+        // Only --keep leaves `teardown` null with a worktree still alive.
         ...(isWorktreeFlow && options.keep
           ? {
             worktree: { path: worktreePath, branch: expectedBranch },
@@ -914,59 +661,20 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
   process.exit(0);
 }
 
-// ── output helpers ────────────────────────────────────────────────────────
-
-/**
- * Report what the archive did to the acervo: use cases promoted into
- * `.morph/specs/usecases/`, any REFUSED for a numbering collision
- * (`ucCollisions` — see `usecase-promoter.js`'s reservation-backed guard), the
- * promoted copies that stayed superseded because the acervo said so
- * (`keptSuperseded`), the ones the feature's spec.md revoked
- * (`supersededUseCases`), the ADR index files it moved (`adrIndex`) and the
- * revocations it could not apply
- * (`revocationProblems`). Every key is absent when there is nothing to report,
- * so a feature that touches no acervo keeps the exact output shape it had
- * before any of them existed.
- */
-function promotedNote(arch) {
+function adrIndexNote(arch) {
   return {
-    ...(arch?.promotedUseCases?.length ? { promotedUseCases: arch.promotedUseCases } : {}),
-    ...(arch?.refusedUseCases?.length ? { ucCollisions: arch.refusedUseCases } : {}),
-    ...(arch?.keptSuperseded?.length ? { keptSuperseded: arch.keptSuperseded } : {}),
-    ...(arch?.supersededUseCases?.length ? { supersededUseCases: arch.supersededUseCases } : {}),
     ...(arch?.adrIndex ? { adrIndex: arch.adrIndex } : {}),
     ...(arch?.revocationProblems?.length ? { revocationProblems: arch.revocationProblems } : {}),
   };
 }
 
-/**
- * O único remoto com que o `finish` conversa — o mesmo que `hasOriginRemote` e
- * o `resolveBaseRef` do branch-classifier assumem. Um nome só, aqui, para que o
- * comando que a saída IMPRIME e o push que o `--push` EXECUTA jamais possam
- * nomear remotos diferentes.
- */
+// Um nome só, para que o comando que a saída IMPRIME e o push que o `--push` EXECUTA jamais
+// nomeiem remotos diferentes.
 const PUSH_REMOTE = 'origin';
 
-/**
- * O que sobrou por publicar depois que o merge local aterrissou — e, com
- * `--push`, o resultado da publicação.
- *
- * A contagem REUSA `resolveBaseRef` + `commitsAhead` (branch-classifier), em vez
- * de uma terceira cópia de `rev-list --count`. Detalhe que decide o P4:
- * `resolveBaseRef` degrada para a branch LOCAL quando não existe ref de
- * rastreamento remoto — comparar a branch consigo mesma devolveria um `0` de
- * aparência honesta para um repo que nunca deu push. Por isso a comparação só
- * vale quando o ref resolvido é diferente do nome da branch; caso contrário
- * `ahead` fica `null` ("incomparável"), nunca zero.
- *
- * Fail-open por desenho: o merge JÁ aconteceu quando esta função roda, então
- * nenhum resultado daqui — nem um push que falhou — pode transformar um sucesso
- * em exit 1. A falha vira `pushError` no payload.
- *
- * @param {{ root: string, defaultBranch: string, push?: boolean }} ctx
- * @returns {{ remote: string, branch: string, ahead: number|null, pushed: boolean,
- *   published?: number|null, pushError?: string }}
- */
+// `resolveBaseRef` degrada para a branch LOCAL sem ref remoto: comparada consigo mesma daria um
+// `0` falso, então `ahead` fica `null`. Fail-open: o merge JÁ aconteceu, e um push que falha
+// vira `pushError`, nunca exit 1.
 function publicationState({ root, defaultBranch, push }) {
   const baseRef = resolveBaseRef(defaultBranch, root);
   const tracked = !!baseRef && baseRef !== defaultBranch;
@@ -990,19 +698,8 @@ function publicationState({ root, defaultBranch, push }) {
   return { ...state, published: ahead, ahead: remaining, pushed: true };
 }
 
-/**
- * A frase do próximo passo — PRODUTOR ÚNICO.
- *
- * O comando se chama `finish`, e no modo `--merge` ele NÃO publica nada por
- * conta própria: o merge é local, o remoto continua sem a feature. Quem lê
- * "finished: true" conclui o contrário — foi pegadinha repetida em sessões
- * diferentes. Três saídas de `--merge` montavam esse aviso por conta própria, e
- * uma delas (o `--keep`) simplesmente esquecia dele; um produtor único é o que
- * impede a divergência de voltar.
- *
- * @param {ReturnType<typeof publicationState>} publish
- * @returns {string}
- */
+// PRODUTOR ÚNICO: no `--merge` o merge é local e o remoto continua sem a feature; cada saída
+// que montava o aviso por conta própria podia esquecê-lo.
 function mergeNextStep(publish) {
   const { remote, branch, ahead, pushed, published, pushError } = publish;
   const pushCmd = `\`git push ${remote} ${branch}\``;
@@ -1017,25 +714,15 @@ function mergeNextStep(publish) {
   if (pushError) {
     return `integração LOCAL — o push pedido por --push FALHOU e nada foi publicado. Rode ${pushCmd} manualmente.`;
   }
-  // Sem contraparte remota não se inventa contagem (P4): fica a frase estática.
+  // Sem contraparte remota não se inventa contagem: fica a frase estática.
   if (ahead === null) {
     return 'integração LOCAL — nada foi publicado. Rode `git push` para levar ao remoto.';
   }
   return `integração LOCAL — nada foi publicado: ${branch} está ${ahead} commit(s) à frente de ${remote}/${branch}. Rode ${pushCmd} para levar ao remoto (ou re-execute o finish com --push).`;
 }
 
-/**
- * CONSTRUTOR ÚNICO da saída de sucesso do `--merge`. As três emissões (worktree
- * normal, worktree `--keep` e fluxo comum) passam por aqui — era a terceira
- * cópia, montada à mão no `--keep`, que saía sem `nextStep` nenhum.
- *
- * `teardown === null` cobre os dois casos sem desmonte: o `--keep` (worktree
- * vivo de propósito) e o fluxo comum (não há worktree algum).
- *
- * @param {{ feature: string, branch: string, defaultBranch: string,
- *   publish: ReturnType<typeof publicationState>, worktreePath?: string|null,
- *   teardown?: object|null, shedBackup?: string|null, kept?: boolean }} args
- */
+// CONSTRUTOR ÚNICO das três saídas de sucesso do `--merge`. `teardown === null` cobre o `--keep`
+// e o fluxo comum.
 function mergeOutput({ feature, branch, defaultBranch, publish, worktreePath = null, teardown = null, shedBackup = null, kept = false, deferred = false }) {
   return {
     finished: true,
@@ -1052,9 +739,7 @@ function mergeOutput({ feature, branch, defaultBranch, publish, worktreePath = n
     ...(shedBackup ? { shedBackup } : {}),
     ...(kept
       ? {
-        // Worktree preserved on purpose: the root's `worktree` registration stays
-        // VALID (it still names a live directory), so nothing to clean up here —
-        // only report where it lives and how to close it later.
+        // The root registration stays VALID (it names a live directory): nothing to clean up.
         worktree: { path: worktreePath, branch },
         hint: `worktree preservado em ${worktreePath} — feche depois com \`morph-spec worktree remove ${feature}\`.`,
       }
@@ -1063,12 +748,7 @@ function mergeOutput({ feature, branch, defaultBranch, publish, worktreePath = n
   };
 }
 
-/**
- * Hint for a teardown deferred because the session is anchored in the worktree
- * (both modes). Names the safe command, never `git worktree remove`. `--merge`
- * would have deleted the (now integrated) branch, so its hint carries
- * `--delete-branch`; `--pr` keeps the branch — the PR needs it.
- */
+// Names the safe command, never `git worktree remove`. `--pr` keeps the branch: the PR needs it.
 function deferredTeardownHint(feature, worktreePath, { deleteBranch = false } = {}) {
   return `worktree mantido em ${worktreePath}: a sessão do Claude Code que rodou o finish está ancorada nele, `
     + 'e desmontá-lo agora quebraria todos os hooks dela (eles resolvem `.morph/framework` por ele) — '
@@ -1076,19 +756,14 @@ function deferredTeardownHint(feature, worktreePath, { deleteBranch = false } =
     + 'de uma sessão aberta na raiz do repo.';
 }
 
-/** Shared teardown reporting for both modes (kept identical to the old finish). */
 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.
+  // After a removal these two lists answer "did I just lose something?".
   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.
+  // 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;
@@ -1096,16 +771,8 @@ function teardownExtras(teardown, worktreePath, branch, deleteBranch) {
     if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
     if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
     out.cleanupHint = teardown.declineReason;
-    // The unlink runs before the removal by design (it is what keeps the removal
-    // from following the junctions out into the primary root), so every
-    // non-removal passes through a moment with the infra loose. What happens
-    // next depends on WHY, and the two must not be reported alike:
-    //   REFUSED — we proved removal unsafe, the user keeps working here, so the
-    //     teardown re-links (A4).
-    //   FAILED  — removal was the intent and a lock got in the way. The infra
-    //     stays down ON PURPOSE, so the retry (or anything pasted from an old
-    //     transcript) has nothing to traverse. Say so explicitly, or the user
-    //     reads a bare "failed" and reaches for the destructive command.
+    // REFUSED re-links (the user keeps working here); FAILED leaves the infra down ON PURPOSE so a
+    // retry has nothing to traverse. Say which, or a bare "failed" invites the destructive command.
     out.relinked = teardown.relinked === true;
     if (!teardown.refused) {
       if (teardown.infraLeftUnlinked?.length) out.infraLeftUnlinked = teardown.infraLeftUnlinked;
@@ -1119,8 +786,6 @@ function teardownExtras(teardown, worktreePath, branch, deleteBranch) {
   return out;
 }
 
-// ── small git helpers ────────────────────────────────────────────────────────
-
 function currentBranch(cwd) {
   try {
     return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
@@ -1155,27 +820,8 @@ function gitErr(err) {
   return (((err.stdout && err.stdout.toString()) || '') + ((err.stderr && err.stderr.toString()) || '')).slice(0, 2000) || (err.message || '').slice(0, 500);
 }
 
-/**
- * Where a feature that is NOT in `features/` actually went, as extra fields on
- * the `feature-not-found` payload.
- *
- * Exists because "not found" is the least useful thing we can say about a
- * feature the user just worked on. The two real cases:
- *
- *  - ARCHIVED: an earlier finish archived it and then failed to integrate.
- *    What is missing is the merge, not the whole finish — say so, because the
- *    user's instinct is to re-run `finish` and get refused again.
- *  - ON ITS BRANCH: the feature was created on `morph/{f}` and the command is
- *    running from the default branch, where `.morph/features/{f}` does not
- *    exist yet. Naming the branch turns a dead end into one checkout.
- *
- * Fail-open in every direction: a hint that cannot be computed is simply absent.
- *
- * @param {string} featureCwd - the tree we looked in
- * @param {string} root - the primary root
- * @param {string} feature
- * @returns {{ archived?: string, hint?: string, onBranch?: string }}
- */
+// Where a feature not in `features/` went: ARCHIVED (only the merge is missing) or on its
+// `morph/{f}` branch. Fail-open: a hint that cannot be computed is absent.
 function featureElsewhereHint(featureCwd, root, feature) {
   try {
     const archived = join(featureCwd, '.morph', 'archive', feature);
@@ -1201,12 +847,6 @@ function featureElsewhereHint(featureCwd, root, feature) {
   return { hint: `'${feature}' não existe em .morph/features/ nesta árvore. Confira o nome com \`morph-spec list --all\`.` };
 }
 
-/**
- * @param {string} cwd
- * @param {string} feature
- * @param {'features'|'archive'} [bucket] - `archive` on a resume, where the
- *   feature.json has already been moved (and stamped `completed`).
- */
 function readFeatureJson(cwd, feature, bucket = 'features') {
   try {
     return JSON.parse(readFileSync(join(cwd, '.morph', bucket, feature, 'feature.json'), 'utf8'));
@@ -1216,19 +856,8 @@ function readFeatureJson(cwd, feature, bucket = 'features') {
 }
 
 /**
- * Is `branch` already contained in `target` — i.e. did an earlier finish get its
- * merge in?
- *
- * Three-valued ON PURPOSE. `git merge-base --is-ancestor` answers by exit code,
- * and the two failure modes mean opposite things: **1** is a real "no, not
- * merged", while **128** is "one of these refs does not resolve" and proves
- * nothing at all. Collapsing them to a boolean would read an unresolvable ref as
- * "not merged" and let a resume re-merge a completed feature.
- *
- * @param {string} branch
- * @param {string} target
- * @param {string} cwd
- * @returns {boolean|null} null when the comparison could not be made
+ * Three-valued ON PURPOSE: `merge-base --is-ancestor` exit 1 is "not merged", 128 is "a ref does
+ * not resolve". `null` when the comparison could not be made.
  */
 export function branchMergedInto(branch, target, cwd) {
   try {
@@ -1239,20 +868,8 @@ export function branchMergedInto(branch, target, cwd) {
   }
 }
 
-/**
- * Does `branch` already have an OPEN pull request? The `--pr` half of
- * "already integrated" — a completed `--pr` leaves the branch unmerged on
- * purpose, so `branchMergedInto` cannot see it.
- *
- * Three-valued for the same reason: an unanswerable query (no `gh`, no auth, no
- * network) is not evidence of "no PR", and treating it as such would resume
- * into a duplicate `gh pr create`.
- *
- * @param {string} branch
- * @param {string} cwd
- * @returns {string|boolean|null} the PR url, `true` (open PR, url unavailable),
- *   `false` (none open), or `null` when the question could not be asked
- */
+// Three-valued: an unanswerable query (no `gh`, auth or network) is not evidence of "no PR".
+// Returns the PR url, `true` (open, url unknown), `false` (none) or `null`.
 function openPrFor(branch, cwd) {
   const { bin, prefix } = resolveGh();
   try {
@@ -1267,13 +884,7 @@ function openPrFor(branch, cwd) {
   }
 }
 
-/**
- * Reclaim the feature's verification stack (containers, ports, named volumes,
- * freshness stamp) from the tree that owns it. `--keep-volumes` keeps the
- * named volumes (e.g. a seeded database) for the next feature. Best-effort by
- * contract — a stack that refuses to come down must never fail a finish that
- * already merged, so this never throws.
- */
+// Never throws: a stack that refuses to come down must not fail a finish that already merged.
 function reclaimStack(feature, { root, worktreePath, options }) {
   try {
     return tearDownFeatureStack(feature, { root, worktreePath, volumes: !options.keepVolumes });
@@ -1282,7 +893,7 @@ function reclaimStack(feature, { root, worktreePath, options }) {
   }
 }
 
-/** Drop a feature from the thin, gitignored root index (never via saveState). */
+// Never via saveState, which would re-materialize the feature folder.
 function dropFromRootIndex(root, feature) {
   const rootPath = join(root, '.morph', 'state.json');
   if (!existsSync(rootPath)) return;