@polymorphism-tech/morph-spec 8.22.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.22.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.22.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';
@@ -42,6 +42,7 @@ import { retypeCommand } from '../src/commands/state/retype.js';
 import { handoffCommand } from '../src/commands/state/handoff.js';
 import { listCommand } from '../src/commands/state/list.js';
 import { deleteCommand } from '../src/commands/state/delete.js';
+import { usecaseReserveCommand } from '../src/commands/state/usecase.js';
 
 // === Tasks ===
 import { dagCommand } from '../src/commands/tasks/dag.js';
@@ -258,6 +259,19 @@ program
   .option('--json', 'Output as JSON')
   .action((feature, options) => handoffCommand(feature, options));
 
+// ─── Use cases ────────────────────────────────────────────────────────────
+const usecaseCommand = program
+  .command('usecase')
+  .description('Project-wide UC-{nn} numbering (acervo + every worktree of this repo)');
+
+usecaseCommand
+  .command('reserve')
+  .description('Atomically reserve the next N UC-{nn} numbers, shared across every worktree of this repo — replaces the old max+1 disk scan, which collides across worktrees')
+  .option('--count <n>', 'How many numbers to reserve', '1')
+  .option('--feature <name>', 'Feature to record as the reservation owner (defaults to the sole active feature, if unambiguous) — also what the promotion collision guard compares against')
+  .option('--json', 'Output as JSON')
+  .action((options) => usecaseReserveCommand(options));
+
 // ─── Tasks ────────────────────────────────────────────────────────────────
 program
   .command('dag <feature>')
@@ -397,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.22.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.22.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.22.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,11 +118,11 @@ 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.
-- **Handoff entre sessões:** `.morph/features/{f}/handoff.md` — documento de retomada comprimido, regenerável (`morph-spec handoff <f>`), **aponta** para os artefatos em vez de copiá-los. Regenerado em `worktree setup`/`create --worktree`/`advance`. **Leia-o antes de re-derivar contexto à mão.** Nunca edite manualmente.
+- **Handoff entre sessões:** `.morph/features/{f}/handoff.md` — documento de retomada comprimido, regenerável (`morph-spec handoff <f>`), **aponta** para os artefatos em vez de copiá-los. Regenerado em `worktree setup`/`create --worktree`/`advance`/`approve`. **Leia-o antes de re-derivar contexto à mão.** Nunca edite manualmente.
 - **Visão da frota:** `morph-spec fleet` agrega raiz + worktrees (fase, gates, tasks, portas, handoff, último commit, sujeira). `morph-spec worktree list` é a visão enxuta por worktree.
 - **Ownership de arquivos:** sem lock em runtime — colisão se resolve **em plan-time** (`morph-spec dag` detecta overlap de `outputs`, recomenda `isolation: "worktree"`) e **por construção** (uma feature = um worktree = um escritor). Arquivos compartilhados convergem no merge do `finish`; conflito ali é escopo sobreposto, não bug.
 - **Fechamento:** aprove o Gate 3, depois **`morph-spec finish <f> --pr|--merge`** — encerramento único e simétrico. **Arquiva** commitando `features/{f} → archive/{f}` **dentro de `morph/{f}`** e integra: `--merge` faz `--no-ff` **local** (sem push; recusa se sujo; aborta em conflito); `--pr` faz `push` + `gh pr create` (exige `origin`+`gh`, checados **antes** de arquivar). Worktree desmontado (PROVE-or-DECLINE), portas liberadas; no `--pr` a branch é **preservada**. `morph-spec archive` fica para arquivar-sem-integrar (features legadas, faxina).

package/framework/agents.json

@@ -20,6 +20,7 @@
         "backend-dotnet-result-pattern",
         "backend-dotnet-vsa-handler-patterns",
         "backend-dotnet-fluent-validation-vsa",
+        "backend-dotnet-testing",
         "backend-integrations-neon-auth-neon-auth"
       ],
       "mcp": ["context7"],

package/framework/docs/CLI.md

@@ -21,10 +21,12 @@
 
 ## 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. `--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.
+- **`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 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`.
+- **`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.22.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.22.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.22.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.22.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.22.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.22.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.22.0"
+cliVersion: "8.24.1"
 ---
 
 # morph-implement
@@ -129,9 +129,21 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    - **`outputs` contém apenas paths realmente produzidos.** Deleções, remoções
      e anotações (ex.: `"pasta/ (removido: a, b)"`) se registram em `notes`,
      nunca em `outputs`. E `notes` é **uma string única** — não um array.
+   - **`outputs` DEVE listar TODO arquivo criado ou modificado pela task — sem exceção.**
+     Isso inclui artefato auxiliar que não estava no plano original (ex.: uma
+     factory de design-time, um seed, um arquivo de config gerado a reboque de
+     outro output) — se a task o produziu, ele entra em `outputs` junto com o
+     resto. Arquivo shipped sem dono em `outputs` de task alguma é falha de
+     protocolo: o Gate 3 (avaliador independente da `morph-review`) aponta como
+     achado de rastreabilidade, mesmo que o arquivo em si esteja correto — quem
+     lê `tasks.json`/`recap.md` depois precisa achar todo arquivo em produção
+     citado em algum lugar, e é essa a lacuna que este parágrafo fecha.
    - **Se os `outputs` reais divergirem dos planejados**, registre o porquê em
      `notes` na mesma edição — o hook exige a note quando há divergência (e a
-     mensagem de violação aponta o campo/valor exato do problema).
+     mensagem de violação aponta o campo/valor exato do problema). Isto é o
+     caso mais comum em que a regra acima se aplica: todo arquivo extra na lista
+     de "realmente produzidos" acima do planejado é, por definição, uma
+     divergência real vs. planejado — a note explica o porquê.
    - `tasks.json` é protegido após o Gate 2: o hook `protect-spec-files` faz diff
      semântico e libera Write ou Edit desde que nenhum campo de contrato do plano
      (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`)

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.22.0"
+cliVersion: "8.24.1"
 ---
 
 # morph-plan
@@ -56,7 +56,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
    **A regra que sustenta a camada inteira: pós-condição precisa ser observável em teste.** "O sistema fica consistente" não passa. "A resposta contém todos os veterinários não arquivados" passa. Antes de escrever cada pós-condição, pergunte: *que asserção eu escreveria para verificar isto?* Se não há resposta, a pós-condição está mal formulada — reescreva ou descarte. Sem esse filtro a camada vira prosa e não chega ao `doneCriteria`.
 
-   **Identificador sequencial no projeto, não na feature.** Antes de numerar, leia o acervo `.morph/specs/usecases/` (se existir) mais os use cases das features ativas em `.morph/features/*/2-plan/usecases/`; tome o maior `UC-{nn}` e some um. Numerar por feature garante colisão no momento da promoção.
+   **Identificador sequencial, reservado — nunca leia o disco à mão.** Rode `morph-spec usecase reserve --count {n} --feature {feature}` (`n` = quantos UCs esta feature vai criar; pode reservar de novo se descobrir mais no meio do plano). Um scan manual do maior `UC-{nn}` só enxerga a ÁRVORE CORRENTE — cada worktree tem a própria cópia de `.morph/features/`, então dois worktrees planejando ao mesmo tempo calculam o mesmo maior número e mintam o MESMO `UC-{nn}` sem saber um do outro; na promoção do `finish`, o segundo a fechar sobrescreve por ID e **apaga o use case do primeiro** — já causou perda de dados em produção. `usecase reserve` aloca atomicamente a partir de um contador compartilhado em `<git-common-dir>/morph-spec/uc-registry.json` (visível a todo worktree do repo, mesmo mecanismo do `claim`/fleet), semeado do maior número já visto no acervo + nas features da árvore corrente + no próprio contador — nunca regride. Fora de um repositório git, cai para o scan local antigo e avisa que o paralelismo entre worktrees não está protegido.
 
    **Seções obrigatórias:** `Pré-condições` (o que já é verdade antes), `Cenário principal` (o caminho feliz, numerado, **curto** — não é o lugar para exaustão de casos) e `Pós-condições` (**P1**, **P2**… — o que passa a ser verdade, cada uma testável; é a seção que viaja **literal** ao `doneCriteria`, ver abaixo).
 
@@ -67,12 +67,14 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    | Tipo | Use case |
    |---|---|
    | `feature` | Obrigatório quando há comportamento observável. Feature puramente técnica (refactor, infra, migração) dispensa — **registre a dispensa em `decisions.md`**. |
-   | `bug` | Não cria novo: **copie** o `UC-{nn}-*.md` do acervo para `2-plan/usecases/` e **corrija ou adicione a pós-condição** lá — o bug é a pós-condição que faltava. |
+   | `bug` | Não cria novo, não reserva número novo: **copie** o `UC-{nn}-*.md` do acervo para `2-plan/usecases/` **mantendo o nome do arquivo publicado** (mesmo slug) e **corrija ou adicione a pós-condição** lá — o bug é a pós-condição que faltava, não a identidade do UC. É esse mesmo nome, inalterado, que faz o `finish` reconhecer a correção como o MESMO UC (abaixo) em vez de uma colisão. |
    | `chore` | Nenhum (já pula a fase plan por política). |
    | `hotfix` | Não bloqueia. Referencia se existir; o pós-mortem pode virar pós-condição numa feature posterior. |
 
    **Nunca edite `.morph/specs/usecases/` à mão.** A única via de escrita no acervo é a promoção do `finish`, que lê **só** de `2-plan/usecases/`: é ela que carimba `status: implemented`, sobrescreve por ID (mesmo com slug novo) e leva o arquivo no commit de arquivamento. Editar o acervo direto pula os três e cria uma segunda verdade fora do mecanismo. Mudar um UC existente = copiar para o `2-plan/usecases/` da feature, corrigir lá, e deixar o `finish` sobrescrever.
 
+   **Backstop de colisão na promoção.** Se, apesar da reserva, duas features chegarem à promoção com o MESMO `UC-{nn}` e slugs diferentes — registro de reserva aponta para uma feature diferente da que já está no acervo —, o `finish`/`archive` **recusa promover esse UC específico** (nunca recusa fechar a feature: fail-open, só aquele use case fica de fora) e imprime onde o arquivo ficou e como recuperar. Se acontecer: renumere com `usecase reserve` e promova manualmente, ou — se for mesmo o caso `bug` — confira se o slug bate com o publicado.
+
    O use case fica **editável depois do Gate 2**, por design — é o que permite mudar o comportamento e re-rodar `implement`. A trilha de auditoria fica no git.
 
 3. Produza `spec.md` em `.morph/features/{feature}/2-plan/`:
@@ -223,7 +225,7 @@ Ao registrar a aprovação do Gate 2, atualize o frontmatter de cada use case de
 - `morph-spec standards --find "<query>"` — para identificar standards relevantes ao mandate (o índice inteiro só como navegação exploratória; ver `morph-standards`)
 - `.morph/framework/agents.json` — personas por domínio; lido UMA VEZ no passo 5a para carimbar `agent`/`standards` por task
 - `.morph/framework/schemas/tasks.schema.json` — schema obrigatório de tasks.json
-- `.morph/specs/usecases/` — acervo permanente de use cases do projeto (leia antes de numerar; em `bug`, é onde mora o UC a corrigir)
+- `.morph/specs/usecases/` — acervo permanente de use cases do projeto (`usecase reserve` já lê antes de numerar; em `bug`, é onde mora o UC a corrigir)
 - `.morph/features/{feature}/0-proposal/proposal.md` — escopo da feature
 - `.morph/features/{feature}/0-proposal/stack-scan.md` — contexto técnico detectado
 - `.morph/framework/schemas/tasks.schema.json` — schema e enums de tasks.json

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.22.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.22.0"
+cliVersion: "8.24.1"
 ---
 
 # morph-review
@@ -42,7 +42,23 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
      confirme que usam duas constantes de prefixo nomeadas distintas, nenhuma reusada para o
      outro propósito. Falha aqui é bloqueante — quebra silenciosa em runtime, não em build.
 
-4. **Despache o avaliador independente** — o score do Gate 3 nunca é auto-atribuído por quem implementou:
+4. **Antes de despachar, verifique se já existe um relatório íntegro** — inclusive em sessão
+   retomada. **Esta verificação NÃO é pulada porque a sessão foi retomada** — é exatamente esse o
+   cenário que já mordeu em produção: 4 sessões retomadas re-despacharam o avaliador do Gate 3 sem
+   nunca ler o `evaluator-report.md` que já existia, íntegro, desde o 1º dispatch (`APPROVED`, score
+   9.3) — e a 4ª sessão chegou a afirmar, falsamente, que "o avaliador nunca rodou". `SessionStart:
+   resume`/`init` não reseta este passo: ele roda sempre, a cada retomada de controle, antes de
+   cogitar um dispatch.
+   - Rode `morph-spec report-check {feature} --json` (sem `task`, modo feature inteira) e leia o
+     campo `evaluator` da resposta — ou, equivalente, leia `4-review/evaluator-report.md` direto e
+     confira: scores por dimensão presentes + a linha `**Composite-Score:**` presente = **íntegro**.
+   - **Se íntegro** (`evaluator.exists && evaluator.complete`): **NÃO despache de novo.** Pule direto
+     para "**Leia primeiro**" logo abaixo — leia o arquivo e siga para o passo 5 (síntese do
+     review-report a partir dele). Re-despachar aqui joga fora um veredito de Gate 3 já válido.
+   - **Se ausente, oco, ou sem scores por dimensão:** este é exatamente o caso de falha de protocolo
+     que este passo trata — prossiga com o dispatch abaixo.
+
+   **Despache o avaliador independente** — o score do Gate 3 nunca é auto-atribuído por quem implementou:
    - Rode `morph-spec verify {feature} --json` (escopo feature) e capture o JSON — é a saída real de build+testes+validadores+e2e que você anexa ao prompt do avaliador independente (`morph-evaluator`).
    - **Confira o nó `e2e` do verify antes de despachar.** Ele carrega o estado do stack:
      - `pass` → a aplicação subiu e está saudável; o avaliador pode navegá-la. **Passe a URL no prompt**
@@ -53,6 +69,9 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
        legítimo; "docker indisponível no ambiente" numa feature de UI **não** é — registre você mesmo
        `morph-spec gate-decision {feature} review --pause true --reason "e2e não verificado: {razão}"`.
        O disco não distingue dispensa legítima de verificação que faltou; esse julgamento é seu.
+   - **Confira também `traceability.warnings`** (advisory, nunca faz `verify` falhar): cada entrada é
+     um arquivo citado no `recap.md` sem task dona em `outputs` — repasse ao avaliador como sinal de
+     rastreabilidade para a dimensão de qualidade, não como bloqueio automático do gate.
    - Gere o **diff da implementação** (`git diff` do range da feature, ou a lista de arquivos do recap.md com seus conteúdos atuais).
    - Despache o subagent registrado `morph-evaluator` (gerado de `agents.json` — a persona do avaliador é o system prompt dele, com Read/Glob/Grep + Bash somente para verificação + Playwright para navegar, sem Write/Edit), com contexto fresco:
      ```
@@ -61,7 +80,14 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
                  + nó e2e do verify (stack no ar? em qual URL?)
        instrução: |
          Você NÃO participou da implementação — avalie o que está no diff,
-         contra o mandate. Você tem Bash: use `morph-spec verify`, testes/build
+         contra o mandate. NÃO leia `4-review/evaluator-report.md` neste
+         caminho antes de escrever o seu: se esse arquivo já existir quando
+         você começar, é resíduo de uma tentativa anterior — NÃO é insumo,
+         é o SEU caminho de escrita, não de leitura. Sua nota nasce do
+         mandate + spec + diff + testes, nunca do veredito de outro
+         avaliador; ler o relatório de um antecessor antes de pontuar é
+         ancoragem — exatamente o que "contexto fresco" existe para evitar.
+         Você tem Bash: use `morph-spec verify`, testes/build
          do stack e `git log/diff/show` para conferir por conta própria o que
          foi reportado, em vez de confiar cegamente. Aplique as rubricas em
          .morph/framework/evals/rubrics/ (architecture 30%, contracts 25%,

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.22.0"
+cliVersion: "8.24.1"
 ---
 
 # morph-stack-scan