@polymorphism-tech/morph-spec 8.23.0 → 8.24.1

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.23.0  
+**Version:** 8.24.1  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -368,4 +368,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.23.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.24.1 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -23,7 +23,7 @@ import { installPluginCommand } from '../src/commands/project/install-plugin-cmd
 import { updateCommand } from '../src/commands/project/update.js';
 import { doctorCommand } from '../src/commands/project/doctor.js';
 import { statusCommand } from '../src/commands/project/status.js';
-import { worktreeSetupCommand, worktreeLinkCommand, worktreeListCommand } from '../src/commands/project/worktree.js';
+import { worktreeSetupCommand, worktreeLinkCommand, worktreeListCommand, worktreeRemoveCommand } from '../src/commands/project/worktree.js';
 import { fleetCommand } from '../src/commands/project/fleet.js';
 import { claimCommand } from '../src/commands/project/claim.js';
 import { standardsCommand } from '../src/commands/project/standards.js';
@@ -411,6 +411,18 @@ worktreeCommand
   .option('--all', 'Link all shared dirs, not just node_modules')
   .action((options) => worktreeLinkCommand(options));
 
+// The SAFE removal — it drops the infra junctions before letting git near the
+// directory. Raw `git worktree remove` follows them out and empties the primary
+// root's .claude/ and .morph/framework/, so nothing in this repo (message, doc,
+// or skill) may point at it; they all point here.
+worktreeCommand
+  .command('remove [feature]')
+  .description('Safely tear down a worktree (drops infra junctions first, PROVE-or-DECLINE) — does NOT close the feature; that is `finish`')
+  .option('--target <path>', 'Remove the worktree at this path (for worktrees with no feature registration)')
+  .option('--discard-ignored', 'Allow removing even though it holds gitignored files that exist nowhere else (e.g. .env) — they are destroyed')
+  .option('--delete-branch', 'Also delete the branch (default: kept — unintegrated commits live there)')
+  .action((feature, options) => worktreeRemoveCommand(feature, options));
+
 worktreeCommand
   .command('list')
   .description('List active feature worktrees with their phase and gate status')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.23.0",
+  "version": "8.24.1",
   "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.23.0 by Polymorphism Tech*
+*morph-spec v8.24.1 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.23.0 by Polymorphism Tech*
+*morph-spec v8.24.1 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -60,7 +60,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 | `retype <f> <tipo>` | Muda o workType mid-flight; bloqueado após o Gate 3 |
 | `finish <f> --pr\|--merge` | Encerramento único: arquiva, promove use cases, integra, desmonta worktree |
 | `archive <f>` | Arquiva sem integrar (legadas/faxina) |
-| `worktree setup\|link\|list` | Ciclo do worktree (fechamento é `finish`, não aqui) |
+| `worktree setup\|link\|remove\|list` | Ciclo do worktree; `remove` é a única remoção segura |
 | `handoff <f>` | Regenera o documento de retomada da feature |
 | `fleet` | Visão agregada de toda feature ativa (raiz + worktrees) |
 | `claim [f] [--release] [--list]` | Posse advisory — confirme antes de `finish`/`archive`/`delete` se outra sessão tiver claim vivo |

package/framework/MORPH.md

@@ -118,7 +118,7 @@ Features independentes podem ser desenvolvidas **em paralelo, cada uma no seu gi
 - **Uma feature = um worktree = uma instância.** Nunca abra duas instâncias na mesma feature (setup recusa, exit 3).
 - `feature.json` viaja **commitado na branch** `morph/{f}`. `state.json` local do worktree é índice derivável — materializado por self-heal, nunca sincronizado à mão.
 - Infra compartilhada (`node_modules`, `.claude`, `.morph/framework`) linkada por junction; `memory/`/`logs/` são locais de cada worktree. Faltou infra (worktree aberto com `git worktree add` puro) → `morph-spec worktree link --all`.
-- **Nunca apague um worktree à mão** (`rm -rf`, `Remove-Item -Recurse -Force`, explorador/IDE). `morph-spec finish`/`worktree remove` desmonta a junction ANTES de remover (PROVE-or-DECLINE); uma remoção genérica não sabe disso e, em várias implementações (inclusive `Remove-Item -Recurse` no Windows), **atravessa a junction** e apaga o conteúdo real compartilhado (`.claude`/`node_modules`/`.morph/framework`), não só o link. Use sempre `morph-spec finish <f> --pr|--merge` (ou `git worktree remove`, sem fechar a feature).
+- **Só o morph remove worktree.** Remoção genérica — `git worktree remove` (com OU sem `--force`), `rm -rf`, `Remove-Item -Recurse`, explorador/IDE — **atravessa a junction** e apaga o conteúdo real compartilhado da raiz (`.claude`/`node_modules`/`.morph/framework`), não só o link, saindo com sucesso. Foi assim que uma raiz teve `.claude/` e `.morph/framework/` esvaziados. Só `morph-spec` desmonta a junction ANTES de remover (PROVE-or-DECLINE): **fechar a feature** = `morph-spec finish <f> --pr|--merge`; **só desmontar o worktree** (feature segue aberta) = `morph-spec worktree remove <f>` — ou `--target <path>` para worktree sem feature. O hook `block-destructive-worktree-removal` barra a versão crua, mas a regra vale antes dele.
 - **Ambiente separado (portas):** o setup aloca um **bloco de portas determinístico** por feature em `.morph/worktree.env` (`PORT`, `MORPH_PORT_RANGE`; `ASPNETCORE_URLS` se dotnet). **Suba dev servers SEMPRE nas portas do bloco** — as portas padrão (3000/5000) pertencem à raiz. Arquivo local, git-invisível; SessionStart injeta as portas. Overrides em `config.json → fleet.basePort/blockSize`.
 - **Banco de dados:** compartilhado por padrão. Isolamento real (Neon MCP): branch de DB `morph/{f}` + connection string no `.morph/worktree.env`; sem Neon, prefixe schema/DB local pelo nome da feature. Migration destrutiva compartilhando banco → integre antes de abrir worktrees irmãos.
 - **Limitação conhecida:** `node_modules` compartilhado (junction) — mudança de dependência afeta os irmãos. Mudou dependência: conclua e integre (`finish`) antes de seguir em paralelo.

package/framework/docs/CLI.md

@@ -24,7 +24,8 @@
 - **`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 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|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). O fechamento saiu daqui — use `morph-spec finish` (acima).
+- **`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).
+- **`morph-spec worktree remove [feature] [--target <path>] [--discard-ignored] [--delete-branch]`** — a remoção **segura** de um worktree, sem fechar a feature. Desmonta as junctions de infra ANTES de deixar o git chegar no diretório e recusa se não conseguir **provar** que é seguro (PROVE-or-DECLINE) — `git worktree remove` cru, com ou sem `--force`, atravessa a junction e apaga o `.claude/`/`.morph/framework/`/`node_modules/` **reais da raiz**, saindo com sucesso. Use `--target` para worktree sem feature registrada (os que o `isolation: "worktree"` cria). A branch **sobrevive** por padrão: remover o worktree não é descartar o trabalho.
 - **`morph-spec handoff <feature>`** — regenera o documento de retomada (`.morph/features/{f}/handoff.md`): comprimido, derivado, aponta para os artefatos em vez de copiá-los. Gerado automaticamente em `setup`/`create --worktree`/`advance`/`approve`.
 - **`morph-spec fleet`** — visão da frota: toda feature ativa (raiz + worktrees) com fase, gates pendentes, tasks, **remoto** (`local`/`pushed`/`PR #N`), **claim** (que sessão está na feature), portas, handoff e atividade. Use entre sessões para decidir onde atuar.
 - **`morph-spec claim [feature] [--release] [--list] [--json]`** — posse **advisory** de feature. Cada sessão reclama sua feature ativa automaticamente (hook SessionStart) e renova o heartbeat a cada tool call; o registro vive em `<git-common-dir>/morph-spec/claims.json`, compartilhado por todos os worktrees. **`morph-spec claim <feature>` (sem flags) ADQUIRE** — se esta árvore já tinha claim vivo em outra feature, ele é liberado no mesmo passo (o CLI reporta "movido de X para Y"); é o jeito de trocar de feature no meio da tarefa sem a dança de dois passos `--release` + reclamar. `--list` força a leitura sem adquirir mesmo passando uma feature. **Claims avisam, nunca bloqueiam** — mas se o SessionStart avisar que outra sessão tem claim vivo, **confirme antes de `finish`/`archive`/`delete`**: duas sessões na mesma feature já custaram um recap.md inteiro e um sub-agent (o worktree sumiu debaixo dele). Claim órfão de sessão morta: `morph-spec claim <f> --release`.

package/framework/hooks/claude-code/core/block-destructive-worktree-removal.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { existsSync } from 'fs';
+import { resolve, isAbsolute } from 'path';
+import { blockResult, runStandalone } from '../../shared/hook-response.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { scanForBlockers } from '../../shared/reparse-scan.js';
+
+/**
+ * block-destructive-worktree-removal — the only defense that does not depend on
+ * someone reading documentation.
+ *
+ * A morph worktree carries JUNCTIONS to the primary root's shared infra
+ * (`node_modules`, `.claude`, `.morph/framework`). Every generic recursive
+ * removal — `git worktree remove` (plain AND `--force`), `rm -rf`,
+ * `Remove-Item -Recurse`, `rmdir /s` — FOLLOWS those links out of the worktree
+ * and deletes what they point at, leaving the primary root's `.claude/` and
+ * `.morph/framework/` as empty directories. That is the incident this hook
+ * exists for, and it is not hypothetical: it happened, and the command was
+ * copied from a message the CLI itself printed.
+ *
+ * `morph-spec worktree remove` is safe because it drops the junctions BEFORE
+ * letting git near the directory. This hook is what stops the unsafe path from
+ * being reachable by accident.
+ *
+ * DELIBERATELY NARROW — an inert or over-eager guardrail is worse than none:
+ *   - only recursive-removal shapes, only when a target path can be extracted;
+ *   - only when that path exists AND the scan finds reparse points under it
+ *     (an already-unlinked worktree, or one that never had junctions, passes);
+ *   - anything unparseable passes.
+ * The scan is the authority, not the path shape: a worktree kept outside
+ * `worktrees/` is protected just the same, and a `worktrees/` directory with
+ * nothing to traverse is not blocked for looking dangerous.
+ */
+
+/** Split a shell-ish command into tokens, honoring single and double quotes. */
+function tokenize(command) {
+  const tokens = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(command)) !== null) tokens.push(m[1] ?? m[2] ?? m[3]);
+  return tokens;
+}
+
+/**
+ * The path a recursive-removal command would destroy, or null when this is not
+ * such a command (or the target cannot be read off it).
+ *
+ * @param {string} command
+ * @returns {string|null}
+ */
+export function extractRemovalTarget(command) {
+  const tokens = tokenize(command);
+  if (!tokens.length) return null;
+  const lower = tokens.map((t) => t.toLowerCase());
+
+  // `git worktree remove [--force] <path>` — the path is always the last
+  // non-flag token; git has no form of this command without one.
+  const gi = lower.indexOf('git');
+  if (gi !== -1 && lower[gi + 1] === 'worktree' && lower[gi + 2] === 'remove') {
+    const rest = tokens.slice(gi + 3).filter((t) => !t.startsWith('-'));
+    return rest.length ? rest[rest.length - 1] : null;
+  }
+
+  // Generic recursive deletes. Each needs BOTH its command word and a recursive
+  // flag — a plain `rm file` or `Remove-Item file` cannot traverse a junction's
+  // contents and is none of this hook's business.
+  const recursive = tokens.some((t) => /^(-[a-z]*r[a-z]*|--recursive|\/s)$/i.test(t));
+  const removalCmd = lower.find((t) => /^(rm|remove-item|ri|rd|rmdir|del)$/.test(t));
+  if (!removalCmd || !recursive) return null;
+
+  const idx = lower.indexOf(removalCmd);
+  // A cmd.exe switch is a slash plus a letter or two (`rmdir /s /q`). Anything
+  // longer that starts with `/` is a POSIX ABSOLUTE PATH — filtering on the
+  // bare `/` made every Linux target look like a flag, so `rm -rf /tmp/wt`
+  // extracted nothing and the hook passed exactly where it had to block.
+  const isCmdSwitch = (t) => /^\/[a-z]{1,2}$/i.test(t);
+  const operands = tokens.slice(idx + 1).filter((t) => !t.startsWith('-') && !isCmdSwitch(t));
+  // Named-parameter form: `Remove-Item -Path <p> -Recurse`.
+  const pathFlag = lower.findIndex((t) => t === '-path' || t === '-literalpath');
+  if (pathFlag !== -1 && tokens[pathFlag + 1]) return tokens[pathFlag + 1];
+  return operands.length ? operands[0] : null;
+}
+
+/**
+ * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
+ * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
+ */
+export async function run(payload) {
+  try {
+    if (!stateExists()) return null;
+
+    const command = payload?.tool_input?.command || '';
+    if (!command) return null;
+
+    const raw = extractRemovalTarget(command);
+    if (!raw) return null;
+
+    const cwd = payload?.cwd || process.cwd();
+    const target = isAbsolute(raw) ? resolve(raw) : resolve(cwd, raw);
+    if (!existsSync(target)) return null;
+
+    const { safe, blockers } = scanForBlockers(target);
+    if (safe) return null;
+
+    const shown = blockers.slice(0, 5).join(', ');
+    const more = blockers.length > 5 ? `, +${blockers.length - 5}` : '';
+    return blockResult(
+      `Remoção bloqueada: "${target}" contém link(s) que este comando SEGUIRIA para fora, apagando o alvo real na raiz do projeto (${shown}${more}).\n\n` +
+      `Isto é o que esvazia o \`.claude/\` e o \`.morph/framework/\` da raiz.\n\n` +
+      `Use: \`morph-spec worktree remove --target "${target}"\` — ele desmonta as junctions ANTES de remover, e recusa se não conseguir provar que é seguro.\n` +
+      `Para fechar a feature de vez: \`morph-spec finish <feature> --pr|--merge\`.`
+    );
+  } catch {
+    return null;
+  }
+}
+
+await runStandalone(run);

package/framework/hooks/shared/reparse-scan.js

@@ -0,0 +1,100 @@
+/**
+ * reparse-scan.js — exhaustive, fail-closed reparse-point (symlink/junction)
+ * scan of a directory tree.
+ *
+ * This lives in `framework/hooks/shared/` rather than `src/` because BOTH sides
+ * need it and the dependency direction in this repo only runs one way: `src/`
+ * imports from `framework/hooks/shared/` (see `finish.js`'s `claim-registry`
+ * and `e2e-check` imports), never the reverse — a hook shipped into a target
+ * project has the package, not this repo's `src/` layout.
+ *
+ * Two callers, one question:
+ *   - `teardownWorktree` (src/commands/project/worktree.js) — may this worktree
+ *     be handed to `git worktree remove`?
+ *   - the `block-destructive-worktree-removal` PreToolUse hook — is the command
+ *     about to run going to traverse a link out of the worktree?
+ *
+ * WHY IT MUST BE EXHAUSTIVE — both `git worktree remove` and its `--force`
+ * fallback FOLLOW reparse points out of the worktree and delete the PRIMARY
+ * ROOT's real files. The plain removal is not the safe one: it refuses only
+ * when it sees modified/untracked *tracked-scope* content, so a GITIGNORED
+ * junction (`node_modules`, `.claude`) leaves `git status` empty, the removal
+ * proceeds, exits 0 — and the target is gone.
+ *
+ * So the check cannot live in the `catch` of the plain removal (unreachable on
+ * exactly the destructive path), and it cannot be a fixed list of the links
+ * `setup` creates: a nested link inside a real `node_modules` (npm link, npm
+ * workspaces) is invisible to any top-level inventory. We scan the whole tree
+ * and NEVER recurse INTO a reparse point — descending one would walk the target
+ * we are trying to protect (and could not terminate on a cycle).
+ *
+ * FAIL-CLOSED, deliberately: an empty result is NOT the same as a safe one. A
+ * directory we could not read or an entry we could not lstat might BE (or
+ * contain) a reparse point. Those answer `unprovable`, and every caller must
+ * treat that exactly like a found link — decline. "I saw nothing" and "I proved
+ * there is nothing" are different claims, and only the second may authorize a
+ * removal. This is the one module in the shared/ directory that must NOT be
+ * fail-open; the whole point is that uncertainty blocks.
+ *
+ * `lstat` reports a POSIX symlink and a Windows junction alike as a symbolic
+ * link, so the scan behaves identically on both platforms — as does the
+ * destruction it prevents.
+ */
+
+import { readdirSync, lstatSync } from 'fs';
+import { join, relative } from 'path';
+
+/**
+ * Every reparse point anywhere under `dir`, as relative paths.
+ *
+ * @param {string} dir
+ * @param {string} [base] - root of the scan, for relative reporting
+ * @param {{points: string[], unprovable: string[]}} [acc]
+ * @returns {{points: string[], unprovable: string[]}} both empty = provably clean
+ */
+export function findReparsePoints(dir, base = dir, acc = { points: [], unprovable: [] }) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    // Unreadable (ACL, lock, EMFILE): we cannot prove what is in here.
+    acc.unprovable.push((relative(base, dir) || '.').replace(/\\/g, '/'));
+    return acc;
+  }
+  for (const entry of entries) {
+    const p = join(dir, entry.name);
+    let st;
+    try {
+      st = lstatSync(p);
+    } catch {
+      acc.unprovable.push(relative(base, p).replace(/\\/g, '/'));
+      continue;
+    }
+    if (st.isSymbolicLink()) {
+      // Forward slashes: every other path this command reports is normalized,
+      // and these end up in JSON the caller may compare or display.
+      acc.points.push(relative(base, p).replace(/\\/g, '/'));
+      continue; // do NOT descend — that is the target, not the worktree
+    }
+    if (st.isDirectory() && entry.name !== '.git') findReparsePoints(p, base, acc);
+  }
+  return acc;
+}
+
+/**
+ * The single question both callers actually ask: may this tree be handed to a
+ * command that follows links?
+ *
+ * Collapses `points` and `unprovable` into one list precisely because callers
+ * must not weigh them differently — `teardownWorktree` already concatenated
+ * them, and a hook that treated `unprovable` as "probably fine" would reopen
+ * the hole this module exists to close.
+ *
+ * @param {string} dir
+ * @returns {{ safe: boolean, blockers: string[] }}
+ */
+export function scanForBlockers(dir) {
+  const { points, unprovable } = findReparsePoints(dir);
+  const blockers = [...points, ...unprovable];
+  return { safe: blockers.length === 0, blockers };
+}

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.23.0"
+cliVersion: "8.24.1"
 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.23.0"
+cliVersion: "8.24.1"
 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # morph-apply
@@ -196,7 +196,7 @@ Quando o `morph-spec dag {feature}` reporta `isolation.recommended: "worktree"`
 1. **Dispatch:** mesmo `subagent_type: "morph-{id}"` e standards de §3b, mais `isolation: "worktree"`. Se a stack for Node e faltar `node_modules` no worktree, o agente roda `morph-spec worktree link` (fail-open) antes de testar; se ainda impossível, reporta "verificação: não executada" (o verify pós-merge cobre). Se o agente precisar subir um dev server e existir `.morph/worktree.env` no seu cwd, usa as portas de lá (nunca as padrão — MORPH.md §2.2). O agente commita na branch do worktree e reporta a branch.
 2. **Integração (orquestrador, após todos os relatórios):** faça o merge de cada branch reportada, uma por vez, na ordem de chegada — `git merge --no-ff <branch>`. Conflito → `git merge --abort`, marque a task de volta a `pending` com nota "merge conflict — reexecutar sequencial", siga para a próxima branch. Os paths em conflito são exatamente os de `isolation.collisions` do dag.
 3. **Pós-merge:** rode `morph-spec verify {feature} --json` UMA vez (o merge é o novo ponto de integração — verificação compartilhada obrigatória), depois `morph-eval` + `morph-spec score` por relatório, como em §3b.
-4. **Cleanup:** `git worktree remove` + `git branch -d` das branches integradas + `git worktree prune` (fail-open). Branches não integradas ficam e são registradas no recap com o motivo.
+4. **Cleanup:** `morph-spec worktree remove --target <path>` por worktree (NUNCA `git worktree remove` cru — o passo 1 pode ter criado junction de `node_modules`, e a remoção crua a atravessa e apaga o `node_modules` da raiz) + `git branch -d` das branches integradas + `git worktree prune` (fail-open). Branches não integradas ficam e são registradas no recap com o motivo.
 5. **Agente morto no meio:** se commitou, a branch sobrevive (retomável); senão, a task volta a `pending` na lane sequencial. Registre a falha de protocolo no recap.
 
 > Anti-padrões: não misture unidades isoladas e não-isoladas no mesmo batch; o subagent nunca faz merge (integração é exclusiva do orquestrador).

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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # 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.23.0"
+cliVersion: "8.24.1"
 ---
 
 # morph-uiux

package/package.json

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

package/src/commands/project/worktree.js

@@ -31,10 +31,13 @@
  */
 
 import { execSync, execFileSync } from 'child_process';
-import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, readdirSync, cpSync } from 'fs';
-import { join, resolve, dirname, relative } from 'path';
+import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, cpSync } from 'fs';
+import { join, resolve, dirname } from 'path';
 import chalk from 'chalk';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+// The reparse scan lives in hooks/shared because the PreToolUse guardrail needs
+// the SAME answer this file does, and hooks can never import from `src/`.
+import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
 
 /**
  * The directory new worktrees are created under, relative to the primary root.
@@ -740,64 +743,6 @@ export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
   return removed;
 }
 
-/**
- * Every reparse point anywhere under `worktreePath`, as relative paths.
- *
- * CRITICAL — this is the gate that keeps `morph-spec finish` (worktree teardown)
- * from destroying the project, and it must be exhaustive. BOTH `git worktree remove` and its
- * `--force` fallback FOLLOW reparse points out of the worktree and delete the
- * PRIMARY ROOT's real files. The plain removal is not the safe one: it refuses
- * only when it sees modified/untracked *tracked-scope* content, so a GITIGNORED
- * junction (`node_modules`, `.claude`) leaves `git status` empty, the removal
- * proceeds, exits 0 — and the target is gone.
- *
- * So the check cannot live in the `catch` of the plain removal (unreachable on
- * exactly the destructive path), and it cannot be a fixed list of the links
- * `setup` creates: a nested link inside a real `node_modules` (npm link, npm
- * workspaces) is invisible to any top-level inventory. We scan the whole tree
- * and NEVER recurse INTO a reparse point — descending one would walk the target
- * we are trying to protect (and could not terminate on a cycle).
- *
- * An empty result is NOT the same as a safe one: a directory we could not read
- * or an entry we could not lstat might BE (or contain) a reparse point. Those
- * answer `unprovable: true`, and the caller must treat that exactly like a found
- * link — decline. "I saw nothing" and "I proved there is nothing" are different
- * claims, and only the second one may authorize a removal.
- *
- * @param {string} dir
- * @param {string} [base] - root of the scan, for relative reporting
- * @param {{points: string[], unprovable: string[]}} [acc]
- * @returns {{points: string[], unprovable: string[]}} both empty = provably clean
- */
-function findReparsePoints(dir, base = dir, acc = { points: [], unprovable: [] }) {
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    // Unreadable (ACL, lock, EMFILE): we cannot prove what is in here.
-    acc.unprovable.push((relative(base, dir) || '.').replace(/\\/g, '/'));
-    return acc;
-  }
-  for (const entry of entries) {
-    const p = join(dir, entry.name);
-    let st;
-    try {
-      st = lstatSync(p);
-    } catch {
-      acc.unprovable.push(relative(base, p).replace(/\\/g, '/'));
-      continue;
-    }
-    if (st.isSymbolicLink()) {
-      // Forward slashes: every other path this command reports is normalized,
-      // and these end up in JSON the caller may compare or display.
-      acc.points.push(relative(base, p).replace(/\\/g, '/'));
-      continue; // do NOT descend — that is the target, not the worktree
-    }
-    if (st.isDirectory() && entry.name !== '.git') findReparsePoints(p, base, acc);
-  }
-  return acc;
-}
-
 /**
  * Gitignored paths a morph worktree owns and that are safe to remove — but ONLY
  * once backed up (see backupWorktreeIgnored). `.morph/state.json` is provably
@@ -1085,6 +1030,60 @@ async function clearRootWorktreeRegistration(root, feature) {
   } catch { /* fail-open — a dirty root is a nuisance, not a reason to fail */ }
 }
 
+/**
+ * Why `git worktree remove` failed, from its stderr.
+ *
+ * The distinction that matters is `in-use` — on Windows a process whose cwd is
+ * inside the worktree (another Claude Code instance, VS Code, a dev server, a
+ * stray terminal) pins the directory and the removal cannot proceed. That is a
+ * human-actionable cause with a specific fix ("close it"), and printing it is
+ * the difference between a message the user can act on and one that just says
+ * "failed" — which is what made a raw `git worktree remove --force` look like
+ * the only way forward.
+ *
+ * @param {string} stderr
+ * @returns {{ kind: 'in-use'|'unknown', detail: string }}
+ */
+function classifyRemovalError(stderr) {
+  const text = String(stderr || '').trim();
+  const inUse = /permission denied|EPERM|EBUSY|being used by another process|resource busy|access is denied|is locked/i.test(text);
+  // First stderr line only: the rest is git's usual advice block, and this lands
+  // in a JSON field a human reads.
+  const detail = text.split(/\r?\n/).find((l) => l.trim()) || '';
+  return { kind: inUse ? 'in-use' : 'unknown', detail: detail.slice(0, 200) };
+}
+
+/**
+ * Run the removal, with one retry round after a short pause.
+ *
+ * The retry exists for the transient Windows handle (antivirus/indexer touching
+ * a file mid-removal) — the same class the repo already retries in
+ * `atomicWriteJson`. It deliberately does NOT help the `in-use` case: a held
+ * directory stays held, and that one needs the human, not another attempt.
+ *
+ * `--force` is safe HERE and only here: the caller proved `blockers.length ===
+ * 0` before calling, so there is nothing left for it to traverse out of.
+ *
+ * @param {string} worktreePath
+ * @param {string} root
+ * @returns {Promise<{ removed: boolean, failure: {kind: string, detail: string}|null }>}
+ */
+async function attemptWorktreeRemoval(worktreePath, root) {
+  let lastStderr = '';
+  for (let round = 0; round < 2; round++) {
+    for (const args of [['worktree', 'remove', worktreePath], ['worktree', 'remove', '--force', worktreePath]]) {
+      try {
+        execFileSync('git', args, { cwd: root, stdio: 'pipe' });
+        return { removed: true, failure: null };
+      } catch (err) {
+        lastStderr = err?.stderr ? String(err.stderr) : (err?.message || '');
+      }
+    }
+    if (round === 0) await new Promise((r) => setTimeout(r, 200));
+  }
+  return { removed: false, failure: classifyRemovalError(lastStderr) };
+}
+
 /**
  * Remove a feature's worktree after its branch is integrated — PROVE-or-DECLINE.
  * The single most dangerous step in the lifecycle, so it declines whenever it
@@ -1095,15 +1094,22 @@ async function clearRootWorktreeRegistration(root, feature) {
  *   2. it deletes GITIGNORED files outright — a user's `.env` is not disposable,
  *      and the clean-check cannot see them.
  *
+ * A non-removal comes in two flavours the caller must not conflate — see the
+ * rollback comment below. `refused` (we proved it unsafe) restores the infra
+ * junctions; a FAILURE (git errored) deliberately leaves them down, reported in
+ * `infraLeftUnlinked`.
+ *
  * `deleteBranch` decouples `git branch -d` from removal: true for `--merge` (the
  * branch is integrated), false for `--pr` (the open PR still needs the branch).
  *
  * @param {string} worktreePath
  * @param {{ root: string, feature: string, branch: string, options?: object, deleteBranch?: boolean }} ctx
  * @returns {Promise<{ worktreeRemoved: boolean, ignoredBackup: string|null, discarded: string[],
- *   blockers: string[], ignoredBlocking: string[], shieldable: string[], declineReason: string|null }>}
+ *   blockers: string[], ignoredBlocking: string[], shieldable: string[], declineReason: string|null,
+ *   relinked: boolean, refused: boolean, infraLeftUnlinked: string[],
+ *   removalFailure: {kind: string, detail: string}|null }>}
  */
-export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true }) {
+export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false }) {
   // Drop the infra junctions FIRST, without following them — this is what makes
   // a removal survivable (see unlinkWorktreeInfraLinks). Runs unconditionally.
   //
@@ -1130,18 +1136,11 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   const canRemove = clearedToRemove && (!ignored.shieldable.length || ignoredBackup !== null);
 
   let worktreeRemoved = false;
+  let removalFailure = null;
   if (canRemove) {
-    try {
-      execFileSync('git', ['worktree', 'remove', worktreePath], { cwd: root, stdio: 'pipe' });
-      worktreeRemoved = true;
-    } catch {
-      // Nothing is left to traverse (proven above), so --force can only act
-      // inside the worktree.
-      try {
-        execFileSync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: root, stdio: 'pipe' });
-        worktreeRemoved = true;
-      } catch { /* fail-open — cleanup is best-effort once integration landed */ }
-    }
+    const attempt = await attemptWorktreeRemoval(worktreePath, root);
+    worktreeRemoved = attempt.removed;
+    removalFailure = attempt.failure; // null once removed
   }
 
   if (worktreeRemoved) {
@@ -1161,30 +1160,58 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     await clearRootWorktreeRegistration(root, feature);
   }
 
-  // Rollback (A4): the removal was refused or failed, so the worktree is still
-  // there — but without the junctions this function dropped up front, which is
-  // strictly worse than never having tried (the observed complaint: "um estado
-  // pior que não ter tentado"). Put them back so the worktree stays usable and
-  // the user can just re-run finish from the primary root. Fail-open: a failed
-  // re-link reports `relinked: false` and the caller falls back to telling the
-  // user to run `morph-spec worktree link --all`.
+  // Rollback (A4) — ONLY on a REFUSAL, never on a FAILURE. The two look alike
+  // (worktree still there, junctions dropped) and must be treated as opposites:
+  //
+  //   REFUSED (`!canRemove`): we proved removal unsafe, so the user keeps
+  //     working in this worktree. Leaving the junctions down is "um estado pior
+  //     que não ter tentado" — put them back.
+  //   FAILED (`canRemove` but git errored): removal WAS the user's intent and
+  //     the only obstacle is a lock. Re-linking here would restore the exact
+  //     hazard that destroyed installations — the retry (ours, theirs, or a raw
+  //     `git worktree remove --force` pasted from an old transcript) would then
+  //     follow the junctions out. Leaving them down makes EVERY subsequent
+  //     attempt safe, because there is nothing left to traverse.
+  //
+  // Fail-open on the refusal path: a failed re-link reports `relinked: false`
+  // and the caller falls back to telling the user to run `worktree link --all`.
+  const refused = !canRemove;
   let relinked = false;
-  if (!worktreeRemoved && unlinked.length && existsSync(worktreePath)) {
+  if (refused && unlinked.length && existsSync(worktreePath)) {
     try {
       setupInfraLinks(worktreePath, root);
       relinked = true;
     } catch { relinked = false; }
   }
-
+  // What the caller must tell the user about on the FAILURE path: the worktree
+  // survived without its shared infra, on purpose.
+  const infraLeftUnlinked = (!worktreeRemoved && !refused) ? unlinked : [];
+
+  // Every branch names `morph-spec worktree remove` and NEVER `git worktree
+  // remove`. The raw command follows the junctions this function manages, and a
+  // decline is exactly the moment a frustrated reader copies whatever command
+  // the tool just printed — that copy is what emptied a primary root's
+  // `.claude/` and `.morph/framework/`. `worktree remove` re-runs this same
+  // PROVE-or-DECLINE path and accepts the same `--discard-ignored` consent, so
+  // there is no decline left where the raw command would be the right answer.
+  // A worktree with no feature identity (the ones `isolation: "worktree"`
+  // creates) can only be re-addressed by path — naming a feature that does not
+  // resolve would hand the reader a command that FAILS, and a failing safe
+  // command is exactly how people end up back at the raw one.
+  const removeCmd = (addressByTarget || !isValidFeatureName(feature))
+    ? `morph-spec worktree remove --target "${worktreePath}"`
+    : `morph-spec worktree remove ${feature}`;
   const declineReason = worktreeRemoved
     ? null
     : ignored.blocking.length
-      ? `worktree NÃO removido: contém arquivo(s) gitignored que existem só ali e o \`git worktree remove\` apagaria (${ignored.blocking.slice(0, 5).join(', ')}${ignored.blocking.length > 5 ? `, +${ignored.blocking.length - 5}` : ''}). Salve o que importa e rode \`git worktree remove --force "${worktreePath}"\`${deleteBranch ? ` + \`git branch -d ${branch}\`` : ''}, ou re-execute o finish com \`--discard-ignored\` para descartá-los deliberadamente`
+      ? `worktree NÃO removido: contém arquivo(s) gitignored que existem só ali e a remoção apagaria (${ignored.blocking.slice(0, 5).join(', ')}${ignored.blocking.length > 5 ? `, +${ignored.blocking.length - 5}` : ''}). Salve o que importa e rode \`${removeCmd}\`, ou \`${removeCmd} --discard-ignored\` para descartá-los deliberadamente`
       : blockers.length
-        ? `worktree NÃO removido: ainda contém link(s)/caminho(s) não verificáveis (${blockers.join(', ')}) que o \`git worktree remove\` seguiria para fora, apagando o alvo na raiz. Remova-os e rode \`git worktree remove "${worktreePath}"\`${deleteBranch ? ` + \`git branch -d ${branch}\`` : ''}`
+        ? `worktree NÃO removido: ainda contém link(s)/caminho(s) não verificáveis (${blockers.join(', ')}) que a remoção seguiria para fora, apagando o alvo na raiz. Remova-os e rode \`${removeCmd}\``
         : ignored.shieldable.length && ignoredBackup === null
-          ? `worktree NÃO removido: o backup do gitignored do worktree falhou, e sem ele a remoção seria destrutiva. Rode \`git worktree remove --force "${worktreePath}"\` manualmente se não precisar desse conteúdo`
-          : `o \`git worktree remove\` falhou. Rode \`git worktree remove "${worktreePath}"\` manualmente`;
+          ? `worktree NÃO removido: o backup do gitignored do worktree falhou, e sem ele a remoção seria destrutiva. Libere espaço/permissão em \`.git/morph-spec/\` e rode \`${removeCmd}\`, ou \`${removeCmd} --discard-ignored\` se não precisar desse conteúdo`
+          : removalFailure?.kind === 'in-use'
+            ? `worktree NÃO removido: o diretório está EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd em "${worktreePath}"). A infra compartilhada ficou DESMONTADA de propósito — feche o que está usando o diretório e rode \`${removeCmd}\`. Se preferir continuar trabalhando nele, restaure a infra com \`morph-spec worktree link --all\``
+            : `worktree NÃO removido: a remoção falhou${removalFailure?.detail ? ` (${removalFailure.detail})` : ''}. A infra compartilhada ficou DESMONTADA de propósito — rode \`${removeCmd}\` para tentar de novo, ou \`morph-spec worktree link --all\` para voltar a trabalhar nele`;
 
   return {
     worktreeRemoved,
@@ -1195,7 +1222,144 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     shieldable: ignored.shieldable,
     declineReason,
     relinked,
+    refused,
+    infraLeftUnlinked,
+    removalFailure,
+  };
+}
+
+/**
+ * Is `cwd` the worktree we are about to remove, or inside it?
+ *
+ * Hoisted out of `finish` so BOTH callers share one answer. Windows holds a
+ * lock on a process's working directory, so a removal issued from inside the
+ * target fails — and in `finish`'s case it fails AFTER the archive is committed
+ * and the branch merged, leaving an orphan directory and a de-registered
+ * worktree. Refusing up front costs one `cd`.
+ *
+ * @param {string} cwd
+ * @param {string} worktreePath
+ * @returns {boolean}
+ */
+export function cwdIsInsideWorktree(cwd, worktreePath) {
+  const cwdNorm = resolve(cwd).replace(/\\/g, '/');
+  const wtNorm = resolve(worktreePath).replace(/\\/g, '/');
+  return cwdNorm === wtNorm || cwdNorm.startsWith(`${wtNorm}/`);
+}
+
+// ── remove ───────────────────────────────────────────────────────────────
+
+/**
+ * Command handler for `morph-spec worktree remove <feature>` /
+ * `morph-spec worktree remove --target <path>`.
+ *
+ * WHY THIS EXISTS: `teardownWorktree` — the only removal that drops the infra
+ * junctions before letting git near the directory — used to be reachable ONLY
+ * through `morph-spec finish`. So every message that had to tell a user how to
+ * remove a worktree pointed at raw `git worktree remove`, which follows those
+ * junctions out and empties the primary root's `.claude/` and
+ * `.morph/framework/`. This command is the safe answer those messages now give.
+ *
+ * Two ways to address the target, because there are two kinds of worktree:
+ *   <feature>       — a morph worktree, resolved through `findWorktreeForFeature`
+ *   --target <path> — any registered worktree, including the ones the Agent
+ *                     tool's `isolation: "worktree"` creates, which have no
+ *                     feature registration for the lookup to find.
+ *
+ * It removes ONLY. No archive, no merge, and the branch survives by default —
+ * closing a feature is still `morph-spec finish`.
+ *
+ * @param {string|undefined} featureArg
+ * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, cwd?: string }} [options]
+ */
+export async function worktreeRemoveCommand(featureArg, options = {}) {
+  const cwdArg = options.cwd || process.cwd();
+  const emit = (obj, code) => { console.log(JSON.stringify(obj)); process.exit(code); };
+
+  if (!isGitRepo(cwdArg)) emit({ removed: false, error: 'not-a-git-repo' }, 1);
+  const root = resolvePrimaryRoot(cwdArg);
+
+  let worktreePath = null;
+  let feature = featureArg || null;
+  let branch = null;
+  // Can a re-run be addressed as `remove <feature>`? Only when the feature name
+  // is what resolved the worktree in the first place.
+  let featureAddressable = !options.target;
+
+  if (options.target) {
+    worktreePath = resolve(options.target).replace(/\\/g, '/');
+    // The target MUST be a registered worktree. Without this the command would
+    // hand an arbitrary path to `git worktree remove` — and `--target ../..`
+    // is the same path-traversal class already fixed in delete/archive.
+    const entry = parseWorktreeList(root).find((e) => e.path === worktreePath);
+    if (!entry) {
+      emit({ removed: false, error: 'not-a-registered-worktree', target: worktreePath, root,
+        hint: 'o path precisa ser um worktree registrado neste repo — confira `morph-spec worktree list`' }, 1);
+    }
+    if (worktreePath === root) {
+      emit({ removed: false, error: 'refuses-primary-root', path: worktreePath,
+        hint: 'a raiz primária nunca é removível por este comando' }, 1);
+    }
+    branch = entry.branch ? entry.branch.replace(/^refs\/heads\//, '') : null;
+    // Best-effort feature identity — used for the backup/env-release bookkeeping
+    // inside the teardown. A `morph/{f}` branch means `remove <feature>` would
+    // resolve too, so re-run advice may name it; anything else stays --target.
+    if (!feature && branch?.startsWith('morph/')) {
+      feature = branch.slice('morph/'.length);
+      featureAddressable = isValidFeatureName(feature);
+    }
+  } else {
+    if (!isValidFeatureName(feature)) {
+      emit({ removed: false, error: 'invalid-feature-name', feature: feature ?? null,
+        hint: 'informe <feature> (kebab-case) ou use --target <path>' }, 1);
+    }
+    const found = findWorktreeForFeature(feature, root);
+    if (!found || found.path.replace(/\\/g, '/') === root) {
+      emit({ removed: false, error: 'no-worktree-for-feature', feature, root,
+        hint: `nenhum worktree separado para "${feature}" — confira \`morph-spec worktree list\`` }, 1);
+    }
+    worktreePath = found.path;
+    branch = found.branch;
+  }
+
+  // Same guard finish applies, for the same Windows reason — and this command
+  // is MORE likely to hit it: the natural moment to run it is right after
+  // working inside the worktree.
+  if (cwdIsInsideWorktree(cwdArg, worktreePath)) {
+    emit({ removed: false, error: 'cwd-inside-worktree', path: worktreePath, root,
+      hint: `saia do worktree antes de removê-lo — o processo trava o próprio diretório de trabalho. Rode de novo a partir de "${root}"` }, 1);
+  }
+
+  const teardown = await teardownWorktree(worktreePath, {
+    root,
+    feature: feature || 'worktree',
+    branch,
+    options: { discardIgnored: options.discardIgnored === true },
+    // Removing a worktree is not closing a feature: the branch is the work, and
+    // deleting it here would discard unintegrated commits. Opt-in only.
+    deleteBranch: options.deleteBranch === true,
+    // Re-run advice must address the worktree the way it was addressable here:
+    // a `--target` worktree has no feature name that would resolve.
+    addressByTarget: !featureAddressable,
+  });
+
+  const out = {
+    removed: teardown.worktreeRemoved,
+    path: worktreePath,
+    ...(branch ? { branch } : {}),
+    ...(feature ? { feature } : {}),
   };
+  if (teardown.worktreeRemoved) {
+    if (teardown.discarded.length) out.discardedIgnored = teardown.discarded;
+    if (teardown.ignoredBackup) out.ignoredBackup = teardown.ignoredBackup;
+  } else {
+    out.refused = teardown.refused;
+    if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
+    if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
+    if (teardown.infraLeftUnlinked.length) out.infraLeftUnlinked = teardown.infraLeftUnlinked;
+    out.hint = teardown.declineReason;
+  }
+  emit(out, teardown.worktreeRemoved ? 0 : 1);
 }
 
 // ── list ─────────────────────────────────────────────────────────────────

package/src/commands/state/finish.js

@@ -10,6 +10,7 @@ import {
   isValidFeatureName,
   buildBranchName,
   branchExists,
+  cwdIsInsideWorktree,
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
 import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
@@ -162,16 +163,14 @@ export async function finishCommand(feature, options = {}) {
     // 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.
-    const cwdNorm = resolve(cwd).replace(/\\/g, '/');
-    const wtNorm = resolve(worktreePath).replace(/\\/g, '/');
-    if (cwdNorm === wtNorm || cwdNorm.startsWith(`${wtNorm}/`)) {
+    if (cwdIsInsideWorktree(cwd, worktreePath)) {
       emit({
         finished: false,
         error: 'cwd-inside-worktree',
         feature,
         path: worktreePath,
         root,
-        hint: `saia do worktree antes do finish — o \`git worktree remove\` não consegue apagar o diretório de trabalho do próprio processo. Rode de novo a partir de "${root}"`,
+        hint: `saia do worktree antes do finish — a remoção não consegue apagar o diretório de trabalho do próprio processo. Rode de novo a partir de "${root}"`,
       });
       process.exit(1);
     }
@@ -441,15 +440,25 @@ 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 `git
-    // worktree remove` from following the junctions out into the primary root),
-    // so a declined removal always passes through a moment with the infra
-    // loose. The teardown now re-links on that path — report which of the two
-    // actually happened instead of always announcing the worse one (A4).
+    // 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.
     out.relinked = teardown.relinked === true;
-    out.relinkHint = teardown.relinked
-      ? 'as junctions de infra foram soltas antes da tentativa e RESTAURADAS após a recusa — o worktree segue utilizável'
-      : `as junctions de infra foram soltas antes desta recusa e não puderam ser restauradas — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+    if (!teardown.refused) {
+      if (teardown.infraLeftUnlinked?.length) out.infraLeftUnlinked = teardown.infraLeftUnlinked;
+      out.relinkHint = `a remoção falhou e as junctions de infra foram deixadas DESMONTADAS de propósito — qualquer nova tentativa é segura. Para voltar a trabalhar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+    } else {
+      out.relinkHint = teardown.relinked
+        ? 'as junctions de infra foram soltas antes da tentativa e RESTAURADAS após a recusa — o worktree segue utilizável'
+        : `as junctions de infra foram soltas antes desta recusa e não puderam ser restauradas — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+    }
   }
   return out;
 }

package/src/lib/worktree/worktree-audit.js

@@ -131,7 +131,11 @@ export function auditWorktrees(cwd = process.cwd()) {
           type: 'non-morph-branch',
           path,
           detail: `${path} está em ${entry.branch || 'HEAD destacado'}, não numa branch morph/* — o \`fleet\` não o enxerga`,
-          fix: `git worktree remove "${path}"  (se já não serve)`,
+          // NEVER raw `git worktree remove` here: it follows the infra junctions
+          // out and empties the primary root's .claude/ and .morph/framework/.
+          // `worktree remove` drops them first (PROVE-or-DECLINE) and takes
+          // --target precisely for worktrees like this one, with no feature.
+          fix: `morph-spec worktree remove --target "${path}"  (se já não serve)`,
         });
       }
       continue;
@@ -142,7 +146,7 @@ export function auditWorktrees(cwd = process.cwd()) {
         type: 'no-feature',
         path,
         detail: `worktree de "${feature}" sem feature conhecida (nem em .morph/features/, nem na branch)`,
-        fix: `git worktree remove "${path}"`,
+        fix: `morph-spec worktree remove --target "${path}"`,
       });
     }
   }

package/src/utils/hooks-installer.js

@@ -28,7 +28,7 @@ import { execSync } from 'child_process';
  * delivery — it makes `morph-spec update` report the change honestly instead
  * of "already current".
  */
-const HOOKS_VERSION = '3.6.0';
+const HOOKS_VERSION = '3.7.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -132,16 +132,20 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === PreToolUse: Bash — denylist (irreversible commands only). Solo. ===
+  // === PreToolUse: Bash — irreversible-command guards, chained (block-first-
+  // wins, one process). pre-bash-denylist (static pattern list) runs before
+  // block-destructive-worktree-removal (dynamic: scans the target for reparse
+  // points), so the cheap check short-circuits the filesystem walk. The second
+  // one is the only defense against the raw-removal vector that does not depend
+  // on someone having read MORPH.md. ===
   {
     event: 'PreToolUse',
     matcher: 'Bash',
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/pre-bash-denylist.js'
-      }
-    ]
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/chain.js',
+      args: ['pre-bash-denylist', 'block-destructive-worktree-removal']
+    }]
   },
 
   // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) +