@polymorphism-tech/morph-spec 8.24.2 → 8.25.0

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 8.24.2  
+**Version:** 8.25.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -368,4 +368,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.24.2 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.25.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.24.2",
+  "version": "8.25.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -185,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.24.2 by Polymorphism Tech*
+*morph-spec v8.25.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.24.2 by Polymorphism Tech*
+*morph-spec v8.25.0 by Polymorphism Tech*

package/framework/docs/CLI.md

@@ -21,7 +21,7 @@
 
 ## Worktree / Fleet
 
-- **`morph-spec finish <feature> --pr|--merge`** — o **encerramento único** da feature (worktree ou comum): **arquiva** commitando `features/{f} → archive/{f}` dentro de `morph/{f}` — promovendo junto, no mesmo commit, os use cases da feature para o acervo permanente `.morph/specs/usecases/` com `status: implemented` (fail-open: sem `2-plan/usecases/`, no-op silencioso) — depois integra. Um `UC-{nn}` cuja promoção colide com outra feature já publicada sob o mesmo número (`ucCollisions` no output; ver `usecase reserve` abaixo) **não é promovido**, mas isso nunca recusa o `finish` — só aquele use case fica de fora, com a mensagem apontando onde o arquivo ficou e como recuperar. `--merge` faz merge `--no-ff` **local** na default (sem push); `--pr` faz `push` + `gh pr create` (exige `origin` + `gh`, checados **antes** de arquivar — um `--pr` recusado não deixa meio-estado). Desmonta o worktree (PROVE-or-DECLINE) e libera o bloco de portas; no `--pr` **preserva** a branch (o PR precisa dela) e fica em `morph/{f}`. Flags: `--keep` mantém o worktree, `--force` dispensa o Gate 3, `--discard-ignored` consente descartar gitignored no teardown. Substitui o antigo `worktree finish` + `archive` separados.
+- **`morph-spec finish <feature> --pr|--merge`** — o **encerramento único** da feature (worktree ou comum): **arquiva** commitando `features/{f} → archive/{f}` dentro de `morph/{f}` — promovendo junto, no mesmo commit, os use cases da feature para o acervo permanente `.morph/specs/usecases/` com `status: implemented` (fail-open: sem `2-plan/usecases/`, no-op silencioso) — depois integra. Um `UC-{nn}` cuja promoção colide com outra feature já publicada sob o mesmo número (`ucCollisions` no output; ver `usecase reserve` abaixo) **não é promovido**, mas isso nunca recusa o `finish` — só aquele use case fica de fora, com a mensagem apontando onde o arquivo ficou e como recuperar. `--merge` faz merge `--no-ff` **local** na default (sem push); `--pr` faz `push` + `gh pr create` (exige `origin` + `gh`, checados **antes** de arquivar — um `--pr` recusado não deixa meio-estado). Desmonta o worktree (PROVE-or-DECLINE) e libera o bloco de portas; no `--pr` **preserva** a branch (o PR precisa dela) e fica em `morph/{f}`. Flags: `--keep` mantém o worktree, `--force` dispensa o Gate 3, `--discard-ignored` consente descartar gitignored no teardown. Substitui o antigo `worktree finish` + `archive` separados. **Retomável:** conflito de merge, checkout ou push falham *depois* do archive (é o commit do archive que viaja com a branch) — re-executar o `finish` retoma na integração e sai com `resumed: true`, em vez de recusar por feature ausente. Se a integração já tiver acontecido, recusa com `already-finished` — e o que conta como "já integrada" depende do modo: no `--merge`, branch contida na default; no `--pr`, PR aberto para `morph/{f}` (a branch de um `--pr` concluído fica não-mergeada de propósito, então só o teste de ancestralidade deixaria passar um segundo `gh pr create`). Sem conseguir provar nem uma coisa nem outra, recusa com `resume-undecidable` em vez de retomar às cegas.
 - **`morph-spec usecase reserve [--count <n>] [--feature <name>] [--json]`** — reserva atomicamente os próximos N números `UC-{nn}`, compartilhado por **todo worktree** deste repo (`<git-common-dir>/morph-spec/uc-registry.json`, mesmo mecanismo do `claim`/env-registry do fleet). Substitui o scan manual "leia o acervo + as features da árvore e some 1": um scan só enxerga a ÁRVORE CORRENTE, então dois worktrees planejando ao mesmo tempo mintavam o MESMO número — colisão que a promoção do `finish` resolvia sobrescrevendo por ID, apagando o use case do primeiro a chegar (já custou perda de dados em produção). O contador nunca regride (semeado do maior número já visto no acervo + nas features da árvore + no próprio registro). `--feature` é mais que auditoria: é o sinal que o guarda de colisão do `finish`/`archive` usa para distinguir uma correção legítima (`bug`, nunca reserva — reaproveita um número publicado) de uma colisão real (a feature reservou o número e o acervo já tem outra dona nele); sem `--feature`, infere a única feature ativa se for inequívoco. Fora de um repositório git: cai para o scan local (avisa no output, `shared: false`) — ainda evita autocolisão dentro da mesma árvore, mas sem a garantia entre worktrees.
 - **`morph-spec archive <feature>`** — arquiva-**sem-integrar** (atômico, git-aware, commita o move escopado por pathspec): reservado a features legadas (sem branch `morph/{f}`) e faxina. O fechamento normal (arquiva **e** integra num passo) é `morph-spec finish`. É o que `/morph-archive` chama.
 - **`morph-spec worktree setup|link|remove|list`** — gerencia o ciclo do worktree por feature (`setup` cria `worktrees/{f}/` na branch `morph/{f}`, aloca o bloco de portas e escreve `.morph/worktree.env`; `link` religa infra compartilhada; `list` mostra fase/gate de cada worktree ativo). **Fechar a feature** continua sendo `morph-spec finish` (acima).

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-apply

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-brainstorming

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-implement

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-plan

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-proposal

package/framework/skills/core/morph-review/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-review

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-stack-scan

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza um standard específico via busca server-side (morph-spec
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-standards

package/framework/skills/core/morph-uiux/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX — design system, mockups, compone
 version: core
 when-to-invoke: ao tomar o ramo uiux (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
 user-invokable: true
-cliVersion: "8.24.2"
+cliVersion: "8.25.0"
 ---
 
 # morph-uiux

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.24.2",
+  "version": "8.25.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/project/worktree.js

@@ -968,11 +968,23 @@ export function shedRootFeatureScope(root, feature) {
  * from blocking every other feature's finish). `ok:false` means the status call
  * itself failed; an empty `dirt` means clean enough to merge into.
  *
+ * `exemptOwnScope` additionally forgives everything under
+ * `.morph/features/{feature}/` — the EXACT pathspec `shedRootFeatureScope`
+ * backs up and discards. It exists so `finish` can ask "is the root clean
+ * enough to merge into?" BEFORE archiving anything, where the shed has not run
+ * yet and the feature's own scaffold is still on disk. Without it that early
+ * question answers "dirty" for a root that the shed would have cleaned, and a
+ * finish that works today would start being refused.
+ *
+ * Callers must keep the post-shed check: this one is an early refusal so the
+ * archive never happens, not the authoritative gate.
+ *
  * @param {string} root
  * @param {string} feature - the feature THIS finish acts on (its own scope is the shed's job)
+ * @param {{ exemptOwnScope?: boolean }} [opts]
  * @returns {{ ok: boolean, dirt: string[] }}
  */
-export function primaryRootUnexplainedDirt(root, feature) {
+export function primaryRootUnexplainedDirt(root, feature, opts = {}) {
   let rootStatusRaw;
   try {
     // `--untracked-files=all`, not the default: the default collapses an
@@ -982,9 +994,11 @@ export function primaryRootUnexplainedDirt(root, feature) {
   } catch {
     return { ok: false, dirt: [] };
   }
+  const ownScope = `.morph/features/${feature}/`;
   const dirt = rootStatusRaw.split('\0').filter((record) => {
     if (!record || record.length < 4) return false;
     const p = record.slice(3).replace(/\\/g, '/');
+    if (opts.exemptOwnScope && p.startsWith(ownScope)) return false;
     return !isLiveSiblingWorktreeRegistration(p, root, feature);
   });
   return { ok: true, dirt };

package/src/commands/state/finish.js

@@ -78,6 +78,14 @@ export function buildPrTitle(feature, fj) {
  * `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
  * @param {{ pr?: boolean, merge?: boolean, keep?: boolean, force?: boolean,
  *   discardIgnored?: boolean, cwd?: string }} [options]
@@ -98,7 +106,15 @@ export async function finishCommand(feature, options = {}) {
   // containers and their ports when the feature closes. Best-effort by
   // contract — a stack that refuses to come down must never fail a finish that
   // already merged.
+  // 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.
+  let resumed = false;
+
   const emit = (obj) => {
+    if (resumed) obj = { ...obj, resumed: true };
     if (obj?.finished === true) {
       try {
         const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
@@ -180,6 +196,14 @@ export async function finishCommand(feature, options = {}) {
     // merge). A feature with NO morph/{f} branch was born before this flow —
     // route it explicitly to archive-without-integrate, never a generic refusal.
     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.
+      if (!existsSync(join(root, '.morph', 'features', feature))) {
+        emit({ finished: false, error: 'feature-not-found', feature, ...featureElsewhereHint(root, root, feature) });
+        process.exit(1);
+      }
       emit({
         finished: false,
         error: 'no-feature-branch',
@@ -203,9 +227,128 @@ export async function finishCommand(feature, options = {}) {
     featureCwd = root;
   }
 
-  // Validation 1: Gate 3 (review) approved on the feature's own feature.json.
-  const fj = readFeatureJson(featureCwd, feature);
-  if (!options.force && !(fj?.approvalGates?.review?.approved === true || fj?.approvals?.review?.approved === true)) {
+  // 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.
+  if (!existsSync(join(featureCwd, '.morph', 'features', feature))) {
+    const archivePath = join(featureCwd, '.morph', 'archive', feature);
+    if (!existsSync(archivePath)) {
+      emit({ finished: false, error: 'feature-not-found', feature, ...featureElsewhereHint(featureCwd, root, feature) });
+      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.
+    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 });
+      process.exit(1);
+    }
+    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.
+      emit({
+        finished: false,
+        error: 'resume-undecidable',
+        feature,
+        branch: expectedBranch,
+        base: target,
+        archived: archivePath.replace(/\\/g, '/'),
+        hint: `'${feature}' está arquivada, mas não foi possível comparar ${expectedBranch} com ${target} (ref ausente?) — sem saber se o merge já aconteceu, retomar arriscaria mergear duas vezes. Verifique o estado do git antes de integrar à mão`,
+      });
+      process.exit(1);
+    }
+    if (merged) {
+      emit({
+        finished: false,
+        error: 'already-finished',
+        feature,
+        branch: expectedBranch,
+        base: target,
+        archived: archivePath.replace(/\\/g, '/'),
+        hint: `'${feature}' já foi arquivada E ${expectedBranch} já está contida em ${target} — o finish anterior concluiu. Nada a integrar.`,
+      });
+      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.
+    if (mode === 'pr') {
+      const openPr = openPrFor(expectedBranch, root);
+      if (openPr === null) {
+        emit({
+          finished: false,
+          error: 'resume-undecidable',
+          feature,
+          branch: expectedBranch,
+          archived: archivePath.replace(/\\/g, '/'),
+          hint: `'${feature}' está arquivada e ${expectedBranch} não foi mergeada, mas não foi possível consultar PRs abertos com \`gh\` — retomar às cegas abriria um PR duplicado. Verifique com \`gh pr list --head ${expectedBranch}\``,
+        });
+        process.exit(1);
+      }
+      if (openPr) {
+        emit({
+          finished: false,
+          error: 'already-finished',
+          feature,
+          branch: expectedBranch,
+          base: target,
+          archived: archivePath.replace(/\\/g, '/'),
+          ...(typeof openPr === 'string' ? { pr: openPr } : {}),
+          hint: `'${feature}' já foi arquivada e ${expectedBranch} já tem PR aberto — o finish anterior concluiu. Falta apenas mergear o PR.`,
+        });
+        process.exit(1);
+      }
+    }
+
+    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.
+  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 });
     process.exit(1);
   }
@@ -239,6 +382,37 @@ 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.
+  if (mode === 'merge' && isWorktreeFlow) {
+    const rootPre = primaryRootUnexplainedDirt(root, feature, { exemptOwnScope: true });
+    if (!rootPre.ok) {
+      emit({ finished: false, error: 'primary-root-status-failed', feature });
+      process.exit(1);
+    }
+    if (rootPre.dirt.length) {
+      emit({
+        finished: false,
+        error: 'primary-root-dirty',
+        hint: 'a raiz primária tem trabalho não commitado — o merge acontece nela; commite ou faça stash antes do finish',
+        feature,
+      });
+      process.exit(1);
+    }
+  }
+
   // ── PR preconditions run BEFORE the archive, so a refused --pr has NO side
   //    effect (nothing archived, nothing committed). ─────────────────────────
   if (mode === 'pr') {
@@ -284,6 +458,11 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
     const { shedBackup } = shedRootFeatureScope(root, feature);
     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.
     const rootClean = primaryRootUnexplainedDirt(root, feature);
     if (!rootClean.ok) {
       emit({ finished: false, error: 'primary-root-status-failed', feature, ...backupNote });
@@ -521,9 +700,113 @@ function gitErr(err) {
   return (((err.stdout && err.stdout.toString()) || '') + ((err.stderr && err.stderr.toString()) || '')).slice(0, 2000) || (err.message || '').slice(0, 500);
 }
 
-function readFeatureJson(cwd, feature) {
+/**
+ * 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 }}
+ */
+function featureElsewhereHint(featureCwd, root, feature) {
+  try {
+    const archived = join(featureCwd, '.morph', 'archive', feature);
+    if (existsSync(archived)) {
+      return {
+        archived: archived.replace(/\\/g, '/'),
+        hint: `'${feature}' já foi arquivada por um finish anterior — o que faltou foi a integração. Verifique se o merge/PR já aconteceu antes de refazer o trabalho à mão.`,
+      };
+    }
+  } catch { /* fail-open */ }
+
+  try {
+    const branch = `morph/${feature}`;
+    const listed = execFileSync('git', ['branch', '--list', branch], { cwd: root, stdio: 'pipe' }).toString().trim();
+    if (listed) {
+      return {
+        onBranch: branch,
+        hint: `'${feature}' não está nesta árvore, mas a branch ${branch} existe — rode o finish de lá (\`git checkout ${branch}\`) ou do worktree da feature.`,
+      };
+    }
+  } catch { /* fail-open — sem git, sem hint */ }
+
+  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'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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
+ */
+export function branchMergedInto(branch, target, cwd) {
+  try {
+    execFileSync('git', ['merge-base', '--is-ancestor', branch, target], { cwd, stdio: 'pipe' });
+    return true;
+  } catch (err) {
+    return err?.status === 1 ? false : null;
+  }
+}
+
+/**
+ * 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
+ */
+function openPrFor(branch, cwd) {
+  const { bin, prefix } = resolveGh();
   try {
-    return JSON.parse(readFileSync(join(cwd, '.morph', 'features', feature, 'feature.json'), 'utf8'));
+    const out = execFileSync(bin, [...prefix, 'pr', 'list', '--head', branch, '--state', 'open', '--json', 'url'], { cwd, stdio: 'pipe' })
+      .toString()
+      .trim();
+    const arr = JSON.parse(out || '[]');
+    if (!Array.isArray(arr) || !arr.length) return false;
+    return typeof arr[0]?.url === 'string' ? arr[0].url : true;
   } catch {
     return null;
   }