@polymorphism-tech/morph-spec 8.33.0 → 8.34.2

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.33.0",
+  "version": "8.34.2",
   "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

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

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.33.0 by Polymorphism Tech*
+*morph-spec v8.34.2 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, desmonta worktree. Integra só no `--merge`; `--pr` abre PR e fica `aguardando-merge` até alguém mergear |
 | `archive <f>` | Arquiva sem integrar (legadas/faxina) |
-| `worktree setup\|link\|remove\|list` | Ciclo do worktree; `remove` é a única remoção segura |
+| `worktree setup\|provision\|link\|remove\|list` | Ciclo do worktree; `provision` = isolamento de task; `remove` é a única remoção segura |
 | `branch prune [--dry-run]` | Apaga branch já integrada, inclusive squash-merge; nunca a com PR aberto |
 | `handoff <f>` | Regenera o documento de retomada da feature |
 | `fleet` | Visão agregada de toda feature ativa (raiz + worktrees) |
@@ -109,6 +109,6 @@ Drift entre `agents.json` e os `.md` gerados é detectado por `morph-spec doctor
 
 ## Regra de precedência de skills
 
-Prefira `morph-*` a `superpowers:*` equivalentes (`brainstorming`→`morph-brainstorming`, `writing-plans`→`morph-plan`, `executing-plans`→`morph-apply`, `test-driven-development`→seguir `mandate.md`, TDD embutido): `morph-*` aplica Gates e paths corretos de `.morph/`; `superpowers:*` é genérico, sem esse contexto.
+Prefira `morph-*` a `superpowers:*` equivalentes (`brainstorming`→`morph-brainstorming`, `writing-plans`→`morph-plan`, `executing-plans`→`morph-apply`, `test-driven-development`→seguir `mandate.md`, TDD embutido, `using-git-worktrees`→`morph-spec worktree setup|provision`): `morph-*` aplica Gates e paths corretos de `.morph/`; `superpowers:*` é genérico, sem esse contexto.
 
 *MORPH-SPEC v5 by Polymorphism Tech*

package/framework/MORPH.md

@@ -118,11 +118,10 @@ 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}`; a cópia da raiz é esqueleto do nascimento, nunca mais atualizado — leitores (`list`/`handoff`/`fleet`) seguem a branch, mutadores recusam gravar fora da árvore dona (detalhes: CLI.md). `state.json` do worktree é índice derivável — 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`.
-- **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):** setup aloca **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 padrão (3000/5000) pertencem à raiz. Local, git-invisível; SessionStart injeta as portas. Override: `config.json → fleet.basePort/blockSize`.
-- **Banco de dados:** compartilhado por padrão; isolar via Neon MCP: branch de DB `morph/{f}` + connection string em `.morph/worktree.env` (sem Neon, prefixe schema/DB pelo nome da feature). Migration destrutiva → integre antes de abrir worktrees irmãos.
-- **Limitação conhecida:** `node_modules` compartilhado (junction) — dependência mudada afeta os irmãos; integre (`finish`) antes de seguir em paralelo.
+- **Só o morph cria worktree:** `worktree setup <f>` (feature) ou `worktree provision <n>` (isolamento de task, branch `morph-task/<n>`). `git worktree add` cru é bloqueado; `EnterWorktree`/`-w`/`isolation:"worktree"` passam pelo hook `WorktreeCreate` e caem em `worktrees/`. Fora de `worktrees/` = criado sem o morph (`doctor --worktrees` acusa). Infra (`node_modules`, `.claude`, `.morph/framework`) por junction; faltou → `worktree link --all`.
+- **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 da raiz (`.claude`/`node_modules`/`.morph/framework`), saindo com sucesso (já esvaziou uma raiz). 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** = `morph-spec worktree remove <f>` — ou `--target <path>` para worktree sem feature. O hook barra a versão crua, mas a regra vale antes dele.
+- **Ambiente dedicado:** setup escreve `.morph/worktree.env` (`PORT`, `API_PORT`/`ASPNETCORE_URLS`, `POSTGRES_PORT`, `COMPOSE_PROJECT_NAME=morph-{f}`); cada worktree sobe o **seu** compose. O hook `PreToolUse:Bash` injeta as variáveis em dev server/compose; fora do Claude, `eval "$(morph-spec env)"`. Porta fixa ou `container_name` no compose **reprova o nó e2e** em worktree. `finish` derruba o stack **com volumes** (`--keep-volumes` preserva). Neon branch opcional, credencial em `e2e.auth.envFile`, nunca em `worktree.env`. Migration destrutiva → integre antes de abrir irmãos.
+- **Limitação:** `node_modules` é junction compartilhada — dependência mudada afeta os irmãos; integre antes de seguir em paralelo.
 - **Handoff entre sessões:** `.morph/features/{f}/handoff.md` — retomada comprimida, regenerável (`morph-spec handoff <f>`, resolve a árvore dona sozinho), **aponta** para os artefatos em vez de copiá-los. Regenerado em `setup`/`create --worktree`/`advance`/`approve`. **Leia-o antes de re-derivar contexto à mão** — nunca edite manualmente.
 - **Visão da frota:** `fleet` agrega raiz + worktrees (fase, gates, tasks, portas, handoff, commit, sujeira); `worktree list` é a visão enxuta por worktree.
 - **Ownership de arquivos:** sem lock runtime — colisão resolve **em plan-time** (`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.

package/framework/agents.json

@@ -138,6 +138,7 @@
       "standards": [
         "backend-integrations-hangfire-hangfire-jobs",
         "infrastructure-docker-coolify-deploy",
+        "infrastructure-docker-local-compose-isolation",
         "backend-dotnet-scrutor",
         "ai-agents-observability-patterns"
       ],

package/framework/docs/CLI.md

@@ -25,8 +25,11 @@
 - **`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` na hora; `--pr` só abre o PR, sem integrar. **O payload distingue os dois** — `--merge` sai com `integrated: true`; `--pr` sai com `integrated: false`, `awaiting: "merge"`, `pr: {number, url}` e um `nextStep` apontando para o merge. **`finished: true` sai nos dois casos e marca só o comando ter terminado, nunca a integração** — `--pr` não encerra a feature, quem encerra é o merge do PR; até lá ela aparece em `morph-spec list`/`fleet` como `aguardando-merge`, sem cópia local (ver `list` acima e `doctor` abaixo). 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 **e** o registro dele na raiz (válido enquanto o diretório existir) — o output reporta `worktree: {path, branch}` e um `hint` lembrando `worktree remove <f>` para fechar depois; `--force` dispensa o Gate 3; `--discard-ignored` consente descartar gitignored no teardown. Substitui o antigo `worktree finish` + `archive` separados. **Retomável:** conflito de merge, checkout ou push falham *depois* do archive (é o commit do archive que viaja com a branch) — re-executar o `finish` retoma na integração e sai com `resumed: true`, em vez de recusar por feature ausente. Se a integração já tiver acontecido, recusa com `already-finished` — e o que conta como "já integrada" depende do modo: no `--merge`, branch contida na default; no `--pr`, PR aberto para `morph/{f}` (a branch de um `--pr` concluído fica não-mergeada de propósito, então só o teste de ancestralidade deixaria passar um segundo `gh pr create`). Sem conseguir provar nem uma coisa nem outra, recusa com `resume-undecidable` em vez de retomar às cegas.
 - **`morph-spec usecase reserve [--count <n>] [--feature <name>] [--json]`** — reserva atomicamente os próximos N números `UC-{nn}`, compartilhado por **todo worktree** deste repo (`<git-common-dir>/morph-spec/uc-registry.json`, mesmo mecanismo do `claim`/env-registry do fleet). Substitui o scan manual "leia o acervo + as features da árvore e some 1": um scan só enxerga a ÁRVORE CORRENTE, então dois worktrees planejando ao mesmo tempo mintavam o MESMO número — colisão que a promoção do `finish` resolvia sobrescrevendo por ID, apagando o use case do primeiro a chegar (já custou perda de dados em produção). O contador nunca regride (semeado do maior número já visto no acervo + nas features da árvore + no próprio registro). `--feature` é mais que auditoria: é o sinal que o guarda de colisão do `finish`/`archive` usa para distinguir uma correção legítima (`bug`, nunca reserva — reaproveita um número publicado) de uma colisão real (a feature reservou o número e o acervo já tem outra dona nele); sem `--feature`, infere a única feature ativa se for inequívoco. Fora de um repositório git: cai para o scan local (avisa no output, `shared: false`) — ainda evita autocolisão dentro da mesma árvore, mas sem a garantia entre worktrees.
 - **`morph-spec archive <feature>`** — arquiva-**sem-integrar** (atômico, git-aware, commita o move escopado por pathspec): reservado a features legadas (sem branch `morph/{f}`) e faxina. O fechamento normal (arquiva **e** integra num passo) é `morph-spec finish`. É o que `/morph-archive` chama.
-- **`morph-spec worktree setup|link|remove|list`** — gerencia o ciclo do worktree por feature (`setup` cria `worktrees/{f}/` na branch `morph/{f}`, aloca o bloco de portas e escreve `.morph/worktree.env`; `link` religa infra compartilhada; `list` mostra fase/gate de cada worktree ativo). **Fechar a feature** continua sendo `morph-spec finish` (acima).
-- **`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. **Os gitignored são triados um a um**, nunca com um veredito só para o conjunto: o que existe na raiz no mesmo path com o **mesmo SHA-256** é replicável e some sem cerimônia (`replicatedInRoot`); artefato de build regenerável (`bin/`, `obj/`, `node_modules/`, `__pycache__/`, `test-results/`, `.auth/`, `*.tsbuildinfo`) é descartado (`discardedIgnored`); o que existe **só ali** é copiado para `.git/morph-spec/finish-backup/` e a remoção **prossegue** (`ignoredBackup` + `backedUp`). A única recusa por gitignored que sobrou é o **backup ter falhado** — e aí o `hint` diz o que é exclusivo, o que era replicável e para onde o backup ia, em vez de mandar rodar o comando que acabou de falhar. `--discard-ignored` deixou de significar "apague o exclusivo junto": agora significa **pular o backup**. As junctions desmontadas saem em `unlinked` — a prova de que o `.claude/` da raiz foi desligado, nunca seguido.
+- **`morph-spec worktree setup|provision|link|remove|list`** — gerencia o ciclo do worktree (`setup <f>` cria `worktrees/{f}/` na branch `morph/{f}`, aloca o bloco de portas e escreve `.morph/worktree.env`; `provision <n> [--base <ref>]` cria `worktrees/{n}/` na branch `morph-task/{n}` — um worktree de **isolamento de task**, sem feature, com as mesmas junctions e um bloco próprio sob a chave `task/{n}`; `link --all` religa a infra compartilhada **e regenera o `worktree.env`** com o layout atual; `list` mostra fase/gate de cada worktree ativo). **Fechar a feature** continua sendo `morph-spec finish` (acima).
+  **Worktrees nativos do Claude Code.** `EnterWorktree`, `claude -w <n>` e `Agent` com `isolation: "worktree"` passam pelo hook `WorktreeCreate` instalado pelo morph: nome conhecido como feature → `worktree setup`; senão → `worktree provision`. O resultado cai sempre em `worktrees/`, nunca em `.claude/worktrees/`. O hook `WorktreeRemove` chama `worktree remove --target <path> --if-clean` (só remove árvore limpa; a branch sobrevive) — mas ele **não disparou** em nenhum run headless medido, então a limpeza primária continua sendo o passo 4 de `morph-apply` §3b-w e o `doctor --worktrees`. `git worktree add` cru é bloqueado pelo hook `block-raw-worktree-add` (sem junctions, sem portas, sem identidade → invisível ao `fleet`).
+  **Layout do bloco (10 portas):** `PORT` (+0), `API_PORT` (+1, `ASPNETCORE_URLS` em dotnet), `POSTGRES_PORT` (+2), `REDIS_PORT` (+3), +4..+9 livres; mais `COMPOSE_PROJECT_NAME=morph-{f}`, `MORPH_PORT_BASE/RANGE`. O mesmo layout alimenta o `worktree.env`, o `docker compose` do `verify`/`e2e` e o hook `worktree-env-inject` (que prefixa `npm run dev`/`dotnet run`/`docker compose`/`playwright test` com `export …` quando o cwd tem manifesto e o comando não escolheu porta própria).
+- **`morph-spec env [feature] [--json|--powershell]`** — imprime o bloco do worktree em forma shell-loadable (`eval "$(morph-spec env)"`; PowerShell: `morph-spec env --powershell | Invoke-Expression`). Feature vem do argumento ou da branch `morph/{f}`/`morph-task/{n}` do cwd. Deriva de `buildComposeEnv`, a mesma função do nó e2e — um shell e o stack nunca discordam. É o caminho para quem roda **fora** do Claude Code (terminal humano, CI, sub-agent sem hooks).
+- **`morph-spec worktree remove [feature] [--target <path>] [--if-clean] [--discard-ignored] [--delete-branch]`** — a remoção **segura** de um worktree, sem fechar a feature. `--if-clean` recusa (`worktree-dirty`, exit 1, junctions intactas) se a árvore tiver qualquer mudança não commitada — é o que o hook `WorktreeRemove` usa, porque um sub-agent que não commitou ainda é o único exemplar do trabalho. Derruba o stack compose da árvore **sem** apagar volumes (a feature segue aberta) e libera o bloco de portas pela chave da branch (`<f>` ou `task/<n>`). 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. **Os gitignored são triados um a um**, nunca com um veredito só para o conjunto: o que existe na raiz no mesmo path com o **mesmo SHA-256** é replicável e some sem cerimônia (`replicatedInRoot`); artefato de build regenerável (`bin/`, `obj/`, `node_modules/`, `__pycache__/`, `test-results/`, `.auth/`, `*.tsbuildinfo`) é descartado (`discardedIgnored`); o que existe **só ali** é copiado para `.git/morph-spec/finish-backup/` e a remoção **prossegue** (`ignoredBackup` + `backedUp`). A única recusa por gitignored que sobrou é o **backup ter falhado** — e aí o `hint` diz o que é exclusivo, o que era replicável e para onde o backup ia, em vez de mandar rodar o comando que acabou de falhar. `--discard-ignored` deixou de significar "apague o exclusivo junto": agora significa **pular o backup**. As junctions desmontadas saem em `unlinked` — a prova de que o `.claude/` da raiz foi desligado, nunca seguido.
 - **`morph-spec branch prune [--remote] [--dry-run] [--json]`** — apaga as branches locais cujo trabalho **já está** na default, **incluindo as squash-merged que o git não enxerga**. O problema que resolve: num repo que faz squash-merge, o commit de merge entra em `origin/master` mas os SHAs da branch não — `git branch --merged` não a lista, `git branch -d` recusa, e sobra o `-D`, indistinguível de descartar trabalho de verdade. Cada branch é classificada com evidência impressa: `merged-ancestral` (o git prova), `merged-squash` (PR `MERGED` pelo `gh`, **ou** árvore idêntica à da default), `open` (PR OPEN — nunca apagada), `in-worktree` (em uso — nunca apagada) e `unmerged` (**não foi possível provar** integração: sem `gh`, sem default resolvível ou trabalho de verdade — todas tratadas igual, de propósito). Só as duas primeiras são apagadas. Branch remota só com `--remote` explícito.
 - **`morph-spec handoff <feature> [--here]`** — regenera o documento de retomada (`.morph/features/{f}/handoff.md`): comprimido, derivado, aponta para os artefatos em vez de copiá-los. **Resolve a árvore dona** antes de gerar (mesma lógica do `list`/`fleet`) e escreve LÁ, não necessariamente no cwd — rodar da raiz com o worktree vivo é seguro: o handoff sai correto e no lugar certo, em vez do esqueleto de nascimento da raiz. Sem árvore nenhuma materializada (só existe commitado em `morph/{f}`) recusa com `feature-not-in-tree`, nomeando a branch, em vez de gerar um documento apontando para arquivos inexistentes. `--here` força construir/escrever no cwd mesmo assim. 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.

package/framework/hooks/README.md

@@ -8,7 +8,11 @@ Comprehensive hooks system for enforcing spec-driven development at the Claude C
 framework/hooks/
 ├── claude-code/                     # Claude Code native hooks
 │   ├── core/
-│   │   └── worktree-context.js      # SessionStart: worktree feature identity / active-feature summary
+│   │   ├── worktree-context.js      # SessionStart: worktree feature identity / active-feature summary
+│   │   ├── worktree-create.js       # WorktreeCreate: governed tree via `morph-spec worktree setup|provision`
+│   │   ├── worktree-remove.js       # WorktreeRemove: safe teardown via `worktree remove --if-clean`
+│   │   ├── block-destructive-worktree-removal.js  # PreToolUse(Bash): raw removal follows junctions out
+│   │   └── block-raw-worktree-add.js              # PreToolUse(Bash): raw `git worktree add` is ungoverned
 │   ├── user-prompt/
 │   │   └── enrich-prompt.js         # Context-aware prompt enrichment
 │   ├── pre-tool-use/
@@ -46,6 +50,10 @@ framework/hooks/
 | **PreToolUse** (Write\|Edit) | protect-spec-files.js | Block | Blocks edits to spec files after approval; for tasks.json validates the mutable-field diff, the status enum, and requires a `notes` when `outputs` diverge from the plan |
 | **PreToolUse** (Write\|Edit) | enforce-phase-writes.js | Block | Ensures writes go to current phase directory |
 | **PreToolUse** (Bash) | pre-bash-denylist.js | Block | Blocks `rm -rf .morph/` and direct state edits |
+| **PreToolUse** (Bash) | block-destructive-worktree-removal.js | Block | Blocks `git worktree remove` / `rm -rf` / `Remove-Item -Recurse` on a directory holding reparse points (the infra junctions a raw removal would FOLLOW out, emptying the root's `.claude/`); names `morph-spec worktree remove` |
+| **PreToolUse** (Bash) | block-raw-worktree-add.js | Block | Blocks raw `git worktree add` (a tree with no junctions → no hooks, no port block, no identity, outside `worktrees/`); names `morph-spec worktree setup <feature>` / `worktree provision <name> --base <ref>`. `list`/`prune`/`remove`/`lock`/`move`/`repair` pass |
+| **WorktreeCreate** | worktree-create.js | Replaces native | Fires for `claude -w`, EnterWorktree and `Agent isolation:"worktree"`; replaces Claude Code's bare `git worktree add`. Runs `morph-spec worktree setup <n>` (known feature) or `worktree provision <n>` (task tree, branch `morph-task/<n>`), honours `worktree.baseRef:"head"`, prints the path as its last stdout line. CLI unreachable → plain git, still under `<root>/worktrees/` |
+| **WorktreeRemove** | worktree-remove.js | Fail-open | Routes Claude Code's own cleanup through `morph-spec worktree remove --target --if-clean` (junctions dropped first; a dirty tree is left alone). Always exit 0. Secondary net — the event was observed NOT to fire headless; the Bash guard above stays the primary defense |
 | **PostToolUse** (Write\|Edit) | post-edit-typecheck.js | Advisory | Debounced `tsc --noEmit` after TS/TSX edits; silent on success. Also touches `.morph/memory/build-dirty.json` on every source-file edit — the write side of validate-completion.js's Stop-hook build-dirty gate |
 | **PostToolUse** (Write\|Edit) | tasks-json-guard.js | Advisory | Validates the written tasks.json schema (status/effort enums); warns so the LLM fixes it immediately |
 | **PostToolUse** (Write\|Edit) | trace-autogen.js | State sync | Auto-generates `.morph/traces/YYYY-MM-DD-{feature}-implement.json` from tasks.json + recap.md + taskScores on every tasks.json write — the skills never write traces by hand |
@@ -115,6 +123,8 @@ All Claude Code hooks import from `framework/hooks/shared/`:
 | `hook-response.js` | `block(reason)`, `approve(context)`, `injectContext(text)`, `pass()` |
 | `stdin-reader.js` | `readStdin()` — Promise-based stdin JSON reader |
 | `telemetry-logger.js` | `appendTelemetryEvent()`, `readTelemetryEvents()` — append-only JSONL event stream (`.morph/logs/events.jsonl`) |
+| `morph-cli.js` | `runMorphSpec(args, { cwd, timeoutMs, env })` — spawns the morph-spec CLI from a hook (`MORPH_SPEC_BIN` → `morph-spec` on PATH → `npx --no-install`); `unavailable: true` when none resolves, never a throw. Hooks may never import from `src/` |
+| `command-tokens.js` | `tokenize(command)` — quote-aware shell tokenizer shared by the Bash guards (a hook must never import a sibling hook: its standalone tail would fire) |
 
 `injectContext(text)` is how `worktree-context.js` (and any other SessionStart hook) delivers context: it emits `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": text } }` on stdout. Claude Code only honors additional context nested under `hookSpecificOutput` — a bare top-level field is ignored.
 

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

@@ -4,6 +4,7 @@ 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';
+import { tokenize } from '../../shared/command-tokens.js';
 
 /**
  * block-destructive-worktree-removal — the only defense that does not depend on
@@ -32,14 +33,10 @@ import { scanForBlockers } from '../../shared/reparse-scan.js';
  * 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 tokenizer lives in shared/command-tokens.js — block-raw-worktree-add.js
+// reads `git worktree add` off the same tokens, and a hook must never import a
+// sibling hook (its standalone tail would fire in the importer's process).
+export { tokenize };
 
 /**
  * The path a recursive-removal command would destroy, or null when this is not

package/framework/hooks/claude-code/core/block-raw-worktree-add.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { blockResult, runStandalone } from '../../shared/hook-response.js';
+import { stateExists } from '../../shared/state-reader.js';
+// From shared/, never from the sibling hook: importing a hook module fires its
+// standalone tail (stdin read + exit) inside THIS process.
+import { tokenize } from '../../shared/command-tokens.js';
+
+/**
+ * block-raw-worktree-add — PreToolUse (Bash) guard against `git worktree add`.
+ *
+ * A worktree created by raw git is a worktree morph cannot see: no infra
+ * junctions (`.claude`, `node_modules`, `.morph/framework` — so NO hooks run
+ * in there), no port block (its dev server collides with the root's), no
+ * feature/task identity (invisible to `fleet`, `doctor --worktrees`,
+ * `worktree list`), and a location git chose, not `<root>/worktrees/`. The
+ * sibling guard (block-destructive-worktree-removal) protects the way OUT;
+ * this one protects the way IN, by naming the two commands that build a
+ * governed tree:
+ *
+ *   morph-spec worktree setup <feature>                — a feature's tree
+ *   morph-spec worktree provision <name> [--base <ref>] — a task-isolation tree
+ *
+ * DELIBERATELY NARROW: only the `add` subcommand. `list`, `prune`, `remove`
+ * (the sibling's business), `lock`, `unlock`, `move`, `repair` all pass. The
+ * `git` token may be followed by global options (`-C <dir>`, `--git-dir=<d>`,
+ * `-c k=v`) before `worktree`, and may sit anywhere in a chained command
+ * (`cd a && git worktree add b`) — every `git` occurrence is checked.
+ */
+
+/** Global `git` options that take a separate value: `git -C <dir> worktree add`. */
+const GIT_GLOBAL_WITH_VALUE = new Set(['-c', '-C', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env']);
+
+/**
+ * Does this command line invoke `git worktree add` anywhere?
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function isRawWorktreeAdd(command) {
+  const tokens = tokenize(command);
+  const lower = tokens.map((t) => t.toLowerCase());
+  for (let i = 0; i < lower.length; i++) {
+    if (lower[i] !== 'git' && !/(^|[\\/])git(\.exe)?$/.test(lower[i])) continue;
+    let j = i + 1;
+    // Skip global options between `git` and the subcommand.
+    while (j < lower.length && lower[j].startsWith('-')) {
+      if (GIT_GLOBAL_WITH_VALUE.has(tokens[j])) j += 2; // `-C dir` consumes its value
+      else j += 1;                                       // `--git-dir=x`, `--no-pager`, …
+    }
+    if (lower[j] === 'worktree' && lower[j + 1] === 'add') return true;
+  }
+  return false;
+}
+
+/**
+ * @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 || !isRawWorktreeAdd(command)) return null;
+
+    return blockResult(
+      'Bloqueado: `git worktree add` cru cria um worktree que o morph-spec NÃO enxerga — sem as junctions de infra ' +
+      '(`.claude`, `node_modules`, `.morph/framework` → nenhum hook roda lá dentro), sem bloco de portas (o dev server ' +
+      'colide com o da raiz), sem identidade (invisível para `fleet`, `doctor --worktrees` e `worktree list`) e fora de `<raiz>/worktrees/`.\n\n' +
+      'Use o comando que constrói a árvore governada:\n' +
+      '  - feature:  `morph-spec worktree setup <feature>`\n' +
+      '  - tarefa isolada (sem feature):  `morph-spec worktree provision <nome> --base <ref>`\n\n' +
+      'Os dois deixam a árvore em `<raiz>/worktrees/<nome>` com a infra completa; `list`/`prune`/`remove` do git não são afetados por este guard.'
+    );
+  } catch {
+    return null;
+  }
+}
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/chain.js

@@ -37,6 +37,13 @@
  *    mesmo grupo observam o MESMO evento real do Claude Code, então isto só
  *    importa como desempate determinístico); na ausência de qualquer elo
  *    declarando, cai para `payload.hook_event_name`; por último, `'PostToolUse'`.
+ *  - updatedInput (PreToolUse): um elo pode devolver
+ *    `hookSpecificOutput.updatedInput` (ver `updatedInputResult` em
+ *    hook-response.js) para reescrever o tool_input. O ÚLTIMO elo a devolver um
+ *    vence (só um elo do grupo reescreve, por construção). `permissionDecision:
+ *    'allow'` + `updatedInput` só entram no resultado final quando algum elo
+ *    reescreveu — um `allow` incondicional pularia o prompt de permissão de
+ *    TODO Bash, que é exatamente o contrário de um guardrail.
  *  - Fail-open POR ELO: uma exceção não tratada por um hook individual (import
  *    falhou, run() não existe, etc.) não derruba a cadeia — os elos seguintes
  *    ainda rodam. Cada hook já fail-opens sozinho dentro do seu próprio
@@ -78,6 +85,7 @@ async function main() {
 
   const contexts = [];
   let eventName = null;
+  let updatedInput = null;
 
   for (const name of names) {
     let result = null;
@@ -97,6 +105,12 @@ async function main() {
       process.exit(0);
     }
 
+    const rewrite = result?.hookSpecificOutput?.updatedInput;
+    if (rewrite && typeof rewrite === 'object') {
+      updatedInput = rewrite; // last writer wins
+      eventName = eventName || result?.hookSpecificOutput?.hookEventName;
+    }
+
     const ctx = contextOf(result);
     if (ctx) {
       contexts.push(ctx);
@@ -107,16 +121,22 @@ async function main() {
     }
   }
 
-  if (contexts.length === 0) {
+  if (contexts.length === 0 && !updatedInput) {
     process.exit(0);
   }
 
-  console.log(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: eventName || payload?.hook_event_name || 'PostToolUse',
-      additionalContext: contexts.join('\n\n'),
-    },
-  }));
+  const hookSpecificOutput = {
+    hookEventName: eventName || payload?.hook_event_name || 'PostToolUse',
+  };
+  // `permissionDecision:'allow'` ONLY travels with a rewrite — an unconditional
+  // allow would skip the permission prompt for every command the chain sees.
+  if (updatedInput) {
+    hookSpecificOutput.permissionDecision = 'allow';
+    hookSpecificOutput.updatedInput = updatedInput;
+  }
+  if (contexts.length) hookSpecificOutput.additionalContext = contexts.join('\n\n');
+
+  console.log(JSON.stringify({ hookSpecificOutput }));
   process.exit(0);
 }
 

package/framework/hooks/claude-code/core/worktree-context.js

@@ -89,6 +89,59 @@ function featureFromBranch(dir) {
   }
 }
 
+/**
+ * Task-isolation worktree (`morph-task/{name}`): the tree a `WorktreeCreate`
+ * hook provisions for a parallel sub-agent batch (morph-apply §3b-w) or for a
+ * `claude -w` session with no feature behind it. Not a feature — no
+ * feature.json, no gates — but it owns a port block and the same junctions.
+ */
+function taskFromBranch(dir) {
+  try {
+    const branch = gitRevParse('--abbrev-ref HEAD', dir);
+    const match = branch.match(/^morph-task\/(.+)$/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is this secondary worktree inside the primary root's `worktrees/` (or the
+ * legacy `.worktrees/`) container? A tree kept anywhere else — `.claude/
+ * worktrees/` from a native Claude Code run before the hook existed, a
+ * sibling `../repo-x`, superpowers' `~/.config/...` — was created without
+ * morph: no junctions, no ports, invisible to `fleet`. Fail-open: any error
+ * reads as "in container" so a healthy tree is never nagged by mistake.
+ */
+function isOutsideContainer(dir) {
+  try {
+    const common = resolve(dir, gitRevParse('--git-common-dir', dir)).replace(/\\/g, '/');
+    const root = common.replace(/\/\.git$/, '');
+    const norm = resolve(dir).replace(/\\/g, '/');
+    return !['worktrees', '.worktrees'].some((d) => norm.startsWith(`${root}/${d}/`));
+  } catch {
+    return false;
+  }
+}
+
+function buildOutOfContainerWarning(dir) {
+  return '⚠ Este worktree está FORA do container do morph (worktrees/): foi criado sem o morph-spec — ' +
+    'sem junctions de infra, sem bloco de portas, invisível ao `fleet`. ' +
+    'Integre a branch e remova com `morph-spec worktree remove --target "<path>"`; ' +
+    'crie worktrees por `morph-spec worktree setup <f>` ou `worktree provision <n>` (o hook WorktreeCreate faz isso sozinho). ' +
+    'Diagnóstico: `morph-spec doctor --worktrees`.';
+}
+
+function buildTaskContext(dir, task) {
+  let text = `🧩 Worktree de isolamento de task: ${task} (branch morph-task/${task}). ` +
+    'Não é uma feature: trabalhe só na task despachada, commite na branch como último ato e NUNCA faça merge — ' +
+    'o orquestrador integra e remove este worktree.';
+  const envLine = buildEnvLine(dir);
+  if (envLine) text += `\n${envLine}`;
+  text += buildMissingInfraWarning(dir);
+  return text;
+}
+
 /** Fallback: if exactly one feature directory exists, assume that's the one. */
 function featureFromSingleDir(dir) {
   try {
@@ -114,8 +167,11 @@ function buildEnvLine(dir) {
     const port = content.match(/^PORT=(\d+)$/m)?.[1];
     if (!port) return null;
     const range = content.match(/^MORPH_PORT_RANGE=([\d-]+)$/m)?.[1];
-    return `🔌 Ambiente desta worktree: PORT=${port}${range ? ` (bloco ${range})` : ''}. ` +
-      `Suba dev servers SEMPRE nessas portas (fonte: .morph/worktree.env) — as portas padrão pertencem à raiz.`;
+    const pg = content.match(/^POSTGRES_PORT=(\d+)$/m)?.[1];
+    const project = content.match(/^COMPOSE_PROJECT_NAME=(\S+)$/m)?.[1];
+    const extras = [pg ? `POSTGRES_PORT=${pg}` : null, project ? `COMPOSE_PROJECT_NAME=${project}` : null].filter(Boolean);
+    return `🔌 Ambiente desta worktree: PORT=${port}${range ? ` (bloco ${range})` : ''}${extras.length ? `, ${extras.join(', ')}` : ''}. ` +
+      'Suba dev servers SEMPRE nessas portas (fonte: .morph/worktree.env; o hook PreToolUse injeta em npm run dev/dotnet run/docker compose) — as portas padrão pertencem à raiz.';
   } catch {
     return null;
   }
@@ -148,20 +204,25 @@ function buildWorktreeContext(dir, feature) {
   const handoffLine = buildHandoffLine(dir, feature);
   if (handoffLine) text += `\n${handoffLine}`;
 
-  // `.morph/framework` is checked alongside the other two because the hook
-  // commands resolve to `$CLAUDE_PROJECT_DIR/.morph/framework/hooks/...`: if
-  // that junction is missing, `node` finds no file and EVERY guardrail in this
-  // worktree is silently dark — the worst failure mode of the lot, and the one
-  // the old two-item check could not see.
+  text += buildMissingInfraWarning(dir);
+  return text;
+}
+
+/**
+ * `.morph/framework` is checked alongside the other two because the hook
+ * commands resolve to `$CLAUDE_PROJECT_DIR/.morph/framework/hooks/...`: if
+ * that junction is missing, `node` finds no file and EVERY guardrail in this
+ * worktree is silently dark — the worst failure mode of the lot, and the one
+ * the old two-item check could not see.
+ */
+function buildMissingInfraWarning(dir) {
   const missing = ['node_modules', '.claude', join('.morph', 'framework')]
     .filter((rel) => !existsSync(join(dir, rel)));
-  if (missing.length) {
-    text += `\n⚠ Infra compartilhada ausente (${missing.join(', ').replace(/\\/g, '/')}). Rode: morph-spec worktree link --all`;
-    if (missing.includes(join('.morph', 'framework'))) {
-      text += `\n   Sem .morph/framework os hooks do morph-spec NÃO executam neste worktree (nenhum guardrail ativo).`;
-    }
+  if (!missing.length) return '';
+  let text = `\n⚠ Infra compartilhada ausente (${missing.join(', ').replace(/\\/g, '/')}). Rode: morph-spec worktree link --all`;
+  if (missing.includes(join('.morph', 'framework'))) {
+    text += `\n   Sem .morph/framework os hooks do morph-spec NÃO executam neste worktree (nenhum guardrail ativo).`;
   }
-
   return text;
 }
 
@@ -234,9 +295,17 @@ export async function run(payload) {
     try { rotateEventsLogIfLarge(dir); } catch { /* non-blocking */ }
 
     if (isSecondaryWorktree(dir)) {
+      const task = taskFromBranch(dir);
+      if (task) {
+        return contextResult(buildTaskContext(dir, task), 'SessionStart');
+      }
       const feature = featureFromBranch(dir) || featureFromSingleDir(dir);
       if (!feature) {
-        return null;
+        // A tree with no morph identity at all: worth a warning ONLY when it
+        // also lives outside the container — that is the signature of a
+        // worktree created behind morph's back (native tool, raw git, another
+        // skill). Inside the container with no identity → stay silent.
+        return isOutsideContainer(dir) ? contextResult(buildOutOfContainerWarning(dir), 'SessionStart') : null;
       }
       return contextResult(buildWorktreeContext(dir, feature) + claimBlock(dir, feature, sessionId), 'SessionStart');
     }