@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/framework/commands/morph-apply.md

@@ -9,6 +9,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, Skil
 Atalho: invoque `Skill(morph-apply)` com o nome da feature.
 
 Pré-requisito: o gate do plano aprovado, com `.morph/features/{feature}/2-plan/plan.md` e
-`2-plan/checks.json` (gravado por `morph-spec plan-check`). Faltando, rode `/morph-proposal {feature}`.
+`2-plan/checks.json` (gravado por `morph-spec plan-check`). Faltando, rode `/morph-plan {feature}`.
 
 **Feature:** $ARGUMENTS

package/framework/commands/morph-status.md

@@ -34,7 +34,7 @@ output completion (X/N outputs), slice progress (reports in `3-implement/reports
 After running the CLI, summarize:
 - Current phase and which gate (if any) is open
 - Outstanding outputs for the current phase
-- Recommended next slash command (`/morph-proposal`, `/morph-apply`, or a gate approval)
+- Recommended next slash command (`/morph-plan`, `/morph-apply`, or a gate approval)
 
 ---
 

package/framework/docs/CLI.md

@@ -16,7 +16,7 @@
 
 **Exceção `hotfix`:** esse tipo nunca despacha (`morph-hotfix` §7); o Gate 3 exige só `4-review/verifier.md`, escrito pelo orquestrador, e a assinatura humana continua obrigatória via `--approver` (o backstop de `--mode auto` acima permanece recusando).
 
-**No `uiux`, a assinatura `auto` é recusada (exit 1) onde o `gate-check uiux` pausaria pelo checklist de tela** — o mesmo predicado do `advance` (`uiuxChecklistPause`, em `risk-detector.js`), lido mesmo sem gate-check antes. Destravam: uma decisão gravada com `pause: false` (`gate-decision {f} uiux --pause false --reason …`, ou um gate-check que não pausou) e a assinatura humana (`--approver`); `--force` não. A decisão vale para o mockup que viu: ela grava `mockupsHash` (o `mockups.md` por conteúdo), e um mockup escrito ou mudado depois dela volta a ser conferido.
+**No `uiux`, a assinatura `auto` é recusada (exit 1) onde o `gate-check uiux` pausaria pelo checklist de tela ou pelo protótipo** — o mesmo predicado do `advance` (`uiuxChecklistPause`, em `risk-detector.js`), lido mesmo sem gate-check antes. Destravam: uma decisão gravada com `pause: false` (`gate-decision {f} uiux --pause false --reason …`, ou um gate-check que não pausou) e a assinatura humana (`--approver`); `--force` não. A decisão vale para o mockup que viu: ela grava `mockupsHash` (o `mockups.md` por conteúdo), e um mockup escrito ou mudado depois dela volta a ser conferido.
 
 **O hook state-sync.js** cobre o caminho manual: `AskUserQuestion` respondida com frase de aprovação (abaixo) → registra o gate no `feature.json` autoritativo com `approvedBy: "manual"`. **A feature é identificada pelo nome que a pergunta cita** — grava na árvore dona dela, nunca na "feature ativa" da sessão. Pergunta sem nome numa árvore com mais de uma feature: o hook **recusa gravar** e avisa — aprove por `morph-spec approve`.
 
@@ -38,11 +38,11 @@ No **review**, o `gate-check` lê os relatórios de `4-review/` (`src/lib/review
 
 Um stamp de `verification` com status `fail` (último `morph-spec verify` vermelho) **força pausa** em qualquer gate. Um stamp `pass` mas **stale** (o código mudou depois do commit do stamp — só conta o que está fora de `.morph/`; o `config.json` conta exceto a troca de `expectedCount`, e um commit só de estado, como o do próprio `feature.json` do verify, não invalida) força pausa **só no ship** (`review`); em `plan`/`uiux` a staleness é computada e reportada em `signals`, mas não pausa nada — é regra de ship, não de gate genérico. Stamp **ausente** nunca pausa por isso (features legadas sem stamp).
 
-**Dispensa de e2e:** o stamp carrega `nodes.e2e` e a razão literal `e2eReason`, porque um nó e2e que **pula** não reprova o rollup — sem eles o gate lê `pass` tanto quando o e2e rodou e passou quanto quando ele nunca rodou. No **ship** (`review`), um `skip` é classificado pela razão (`classifyE2eSkip`, em `risk-detector.js` — fonte única) e o veredito fica registrado em `gateDecisions.review.signals` (`e2eStatus`, `e2eReason`, `e2eSkipClass`): `project` ("project does not containerize") é **dispensa legítima** — passa, com o motivo gravado, sem precisar de `gate-decision` manual; `environment` ("docker is not available…"), `requested` (`--skip-e2e`) e `unknown` (qualquer outra razão, **inclusive razão nenhuma**) **pausam** — a máquina ou o operador não são evidência sobre o código, e uma dispensa sem motivo é o mesmo no-op silencioso que a regra existe para eliminar. `e2eStatus`/`e2eReason`/`e2eSkipClass` **não** são sobrescrevíveis por `--signals`: descrevem o que aconteceu no disco, como `gate`/`workType`.
+**Dispensa de e2e:** o stamp carrega `nodes.e2e` e a razão literal `e2eReason`, porque um nó e2e que **pula** não reprova o rollup — sem eles o gate lê `pass` tanto quando o e2e rodou e passou quanto quando ele nunca rodou. No **ship** (`review`), um `skip` é classificado pela razão (`classifyE2eSkip`, em `risk-detector.js` — fonte única) e o veredito fica registrado em `gateDecisions.review.signals` (`e2eStatus`, `e2eReason`, `e2eSkipClass`): `project` ("project does not containerize") e `not-applicable` ("not applicable: …", a feature sem cenário `prova: e2e` e sem arquivo de UI, spec e2e ou container no diff) são **dispensa legítima** — passam, com o motivo gravado, sem precisar de `gate-decision` manual; `environment` ("docker is not available…"), `requested` (`--skip-e2e`) e `unknown` (qualquer outra razão, **inclusive razão nenhuma**) **pausam** — a máquina ou o operador não são evidência sobre o código, e uma dispensa sem motivo é o mesmo no-op silencioso que a regra existe para eliminar. `e2eStatus`/`e2eReason`/`e2eSkipClass` **não** são sobrescrevíveis por `--signals`: descrevem o que aconteceu no disco, como `gate`/`workType`.
 
 **Prova de mídia:** do MESMO relatório e pelo MESMO leitor, o `gate-check` grava `signals.mediaClaims = {section, featureGeneratesMedia}`. `featureGeneratesMedia` é determinístico do disco — existe ao menos uma fatia do `checks.json` cujo `standards` cita `ai-agents-modalities-image-gen`, `ai-agents-media-video` ou `ai-agents-media-pipeline` — pelo id de STANDARDS.json ou pelo caminho, com ou sem `framework/`/`standards/` na frente, porque uma grafia não prevista desarmaria o guardrail sem uma linha de erro (`featureGeneratesMedia`, função exportada de `gate-check.js`, é onde essa normalização mora e é testada). Nessa condição, relatório **sem** a seção `## Mídia gerada` **pausa o Gate 3**: as quatro afirmações de mídia (custo, revisão humana, marcação, hot path não bloqueado) não foram provadas (`framework/evals/review-checklist.md`, "Feature que gera mídia").
 
-**Checklist de tela:** na `uiux` e no `review`, o `gate-check` grava `signals.screenChecklist` lido do `1-design/mockups.md` (`mockups`, `legacy`, `screens`, `problems`). Na **uiux**, checklist incompleto **pausa** nomeando a tela e o item, e um mockup sem nenhuma `## Tela:` é o problema "nenhuma tela declarada". No **review**, o que se cobra é o item **devido** — decidido, nem "não se aplica" nem a superfície (`uncovered`): cada um exige uma linha na seção `## Checklist de tela` do `verifier.md`, e a linha que o verificador marca como não verificável conta. Com item devido, relatório sem a seção ou com linha faltando (`section`, `uncovered`) **pausa** o Gate 3 (`evals/review-checklist.md`, "Contrato de tela"); tela toda "não se aplica" não deve nada e não pausa. **Mockup legado** — telas no formato antigo (`## S001: …`) e nenhuma `## Tela:`, o que o template anterior gerava — é **isento nas duas fases**, com a isenção à vista: o sinal grava `exempt: "checklist dispensado: mockup no formato antigo"` e a mesma razão aparece em "risk signals present". Mockup ausente não pausa. `screenChecklist` **não** é sobrescrevível por `--signals`.
+**Checklist de tela:** na `uiux` e no `review`, o `gate-check` grava `signals.screenChecklist` lido do `1-design/mockups.md` (`mockups`, `legacy`, `screens`, `problems`). Na **uiux**, checklist incompleto **pausa** nomeando a tela e o item, e um mockup sem nenhuma `## Tela:` é o problema "nenhuma tela declarada". Com o checklist completo, cada tela ainda deve o **protótipo** (`prototypes`, só na uiux): a linha `**Protótipo:** 1-design/prototipos/<tela>.html` dentro da `## Tela:`, o HTML e os prints `<tela>-1280.png` e `<tela>-390.png` ao lado dele; faltando um, **pausa** nomeando a tela e o arquivo ("protótipo incompleto"), pelo mesmo predicado. No **review**, o que se cobra é o item **devido** — decidido, nem "não se aplica" nem a superfície (`uncovered`): cada um exige uma linha na seção `## Checklist de tela` do `verifier.md`, e a linha que o verificador marca como não verificável conta. Com item devido, relatório sem a seção ou com linha faltando (`section`, `uncovered`) **pausa** o Gate 3 (`evals/review-checklist.md`, "Contrato de tela"); tela toda "não se aplica" não deve nada e não pausa. **Mockup legado** — telas no formato antigo (`## S001: …`) e nenhuma `## Tela:`, o que o template anterior gerava — é **isento nas duas fases**, com a isenção à vista: o sinal grava `exempt: "checklist dispensado: mockup no formato antigo"` e a mesma razão aparece em "risk signals present". Mockup ausente não pausa. `screenChecklist` **não** é sobrescrevível por `--signals`.
 
 **Por quê.** Fora do review a regra não vale (pausar o Gate 1/2 numa máquina sem docker travaria planejamento legítimo). Feature que não pina standard de mídia é **isenta automaticamente** — a regra não pede cerimônia de quem não gera mídia. `mediaClaims` **não** é sobrescrevível por `--signals`, pela mesma razão anti-spoof dos demais sinais de disco.
 
@@ -58,10 +58,10 @@ A tabela é a mesma régua que `shouldPauseGate` aplica e que o `gate-check` imp
 | `verificationStatus` | === 'fail' | `verify` vermelho — build, testes, validadores **ou e2e**. Vale em **qualquer** gate |
 | `verificationStatus` | ausente, no `review` | nenhum `verify` carimbado: ship sem prova; `approve` auto aplica a mesma régua |
 | `verificationStale` | true | Stamp do `verify` com sha != HEAD: o verde é de outro código. Só no **ship** |
-| `e2eSkipClass` (derivada) | environment/requested/unknown | e2e pulou sem dispensa legítima (só `project`). Só no **ship** |
+| `e2eSkipClass` (derivada) | environment/requested/unknown | e2e pulou sem dispensa legítima (`project` e `not-applicable` passam). Só no **ship** |
 | `promptModel` | prompt/modelo tocado | Sem nó `evals` declarado, ou eval pulado neste verify. Só no **ship** |
 | `mediaClaims` | seção ausente | Feature que gera mídia, relatório sem `## Mídia gerada`. Só no **ship** |
-| `screenChecklist` | item em aberto | **uiux**: tela sem checklist completo, ou nenhuma `## Tela:`. **ship**: item decidido sem linha em `## Checklist de tela` |
+| `screenChecklist` | item em aberto | **uiux**: tela sem checklist completo, nenhuma `## Tela:`, ou tela sem protótipo e prints 1280/390. **ship**: item decidido sem linha em `## Checklist de tela` |
 | `planChecks` | ≠ `fresh` | `checks.json` ausente ou de outra versão do `plan.md`: rode `plan-check`. Só no **plano**; `approve`/`advance` automáticos recusam |
 | `sliceCount` | > 12 | Plano grande demais para uma feature |
 | `workType` | === 'hotfix' | Gate 3 pausa SEMPRE (ver "Gates por tipo de trabalho") |
@@ -268,7 +268,7 @@ Fail-open: uma poda que falha nunca derruba o comando. PROVE-or-DECLINE como o r
 
 ### claim
 
-**`morph-spec claim [feature] [--release] [--list] [--all] [--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`. **O board mostra só claims VIVOS** (dentro do TTL de 30 min): um claim morto não avisa mais nada, e deixá-lo listado transformava o quadro em ruído (features encerradas há 20h e 73h ainda aparecendo). `--all` mostra o registro inteiro; a contagem dos omitidos sai no rodapé, nunca em silêncio.
+**`morph-spec claim [feature] [--release] [--list] [--all] [--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 o trabalho de uma fatia e um sub-agent (o worktree sumiu debaixo dele). Claim órfão de sessão morta: `morph-spec claim <f> --release`. **O board mostra só claims VIVOS** (dentro do TTL de 30 min): um claim morto não avisa mais nada, e deixá-lo listado transformava o quadro em ruído (features encerradas há 20h e 73h ainda aparecendo). `--all` mostra o registro inteiro; a contagem dos omitidos sai no rodapé, nunca em silêncio.
 
 ## Validação
 
@@ -282,6 +282,8 @@ O nó `e2e` é o único que **executa** a aplicação: sobe o `docker compose` d
 
 As specs são procuradas na raiz, em `project.frontendPath` e, sem ele, nas pastas de frontend conhecidas (as mesmas do detector, mais `web`). Se o nó cai para smoke enquanto existe um `playwright.config.*` não executado em pasta de primeiro nível, o `verify` avisa nomeando a pasta e `project.frontendPath`. A contagem de specs sai em `nodes.e2e.count` do `verify --json` (`null` quando não rodou ou o sumário é ilegível, nunca 0); ela não é persistida no stamp.
 
+**O e2e só sobe quando pode provar algo:** com testes vermelhos ele não roda (`tests failed — the e2e does not run over a red suite`); sem nó de teste `e2e: true` (esses são a prova do backend contra a stack e sempre a sobem), ele também não roda quando nenhum cenário do `checks.json` é `prova: e2e` e o diff da feature contra a branch default (fora de `.morph/`) não toca UI (`.tsx`, `.css`, `.html`…), spec e2e, `playwright.config.*`, Dockerfile/compose nem pasta de frontend conhecida — `skip` com a razão `not applicable: …`, que o gate aceita. Sem git, sem base ou diff vazio: roda (só para diante de evidência).
+
 **Dispensa legítima × setup faltando:** projeto sem compose e sem a integração `docker` é `skip` com razão; projeto que **declara** `docker` e não tem compose é `fail` — é verificação que nunca foi montada, não projeto que não containeriza.
 
 **Descoberta de testes e relógio:** a varredura por `*Tests.csproj` **não enxerga worktrees** — nem os convencionais (`worktrees/`, `.worktrees/`) nem os registrados em `git worktree list` fora da convenção. O timeout do nó `tests` deixou de ser fixo: `--timeout` (que agora cobre build **e** tests) > `project.testTimeoutMs` no `config.json` > **120 s por projeto de teste encadeado** — um encadeamento nunca nasce condenado pelo tamanho. Quando o relógio estoura, o nó diz isso com nome (`timeout após N ms na execução X de Y — nenhum teste falhou`) em vez de devolver log truncado.
@@ -316,7 +318,7 @@ Nenhuma regra de gate muda: e2e pulado, escopo, evals e stale valem igual.
 
 **Sem workflow** que rode `morph-spec verify` publicando `morph-verify.json`, cria e commita `.github/workflows/morph-verify.yml` na branch da feature (gatilho `push` em `morph/**`, `.morph/` fora do gatilho exceto o `config.json`, `cancel-in-progress`, setup de .NET por `global.json`/stack, install por lockfile, browsers do Playwright onde há config, e o `morph-spec` na versão de `.morph/.morphversion`). Um run sobre um commit anterior vale quando só `.morph/` andou desde ele; run `cancelled`/`skipped`/`startup_failure` não é prova.
 
-**Sem CI cai para o verify local, com a razão** (`project.ci: false`, origin fora do GitHub, `gh` ausente ou sem login, branch que não é `morph/<feature>`, token HTTPS sem o escopo `workflow` para criar o arquivo, push recusado, workflow que não disparou nem com `gh workflow run`, run sem o artefato). **Antes de rodar local, reaproveita o stamp fresco:** último stamp `pass` com `sha`, nada fora de commit e `treeMovedSince(stamp.sha, HEAD)` falso (a mesma régua do `verificationStale`: só `.morph/` andou, ou o `config.json` mudou só `expectedCount`) → não roda nem regrava, imprime "stamp fresco reaproveitado" e o `--json` traz `reason: "stamp-reused"`, `status`, `nodes` e `reused: { sha, ts, source }`, exit 0.
+**Sem CI cai para o verify local, com a razão** (`project.ci: false`, origin fora do GitHub, `gh` ausente ou sem login, branch que não é `morph/<feature>`, token HTTPS sem o escopo `workflow` para criar o arquivo, push recusado, workflow que não disparou nem com `gh workflow run`, run sem o artefato). **Antes de tudo — com ou sem CI — reaproveita o stamp fresco:** último stamp `pass` com `sha`, nada fora de commit e `treeMovedSince(stamp.sha, HEAD)` falso (a mesma régua do `verificationStale`: só `.morph/` andou, ou o `config.json` mudou só `expectedCount`) → não empurra, não roda nem regrava, imprime "stamp verde e fresco — o CI não roda de novo" e o `--json` traz `reason: "stamp-reused"`, `status`, `nodes` e `reused: { sha, ts, source }`, exit 0.
 
 Código não commitado é **erro de uso (exit 2)**: o CI só vê commits. CI rodando depois de 50 min é **exit 3** (`status: "pending"`), sem stamp — não é vermelho. Com task, `--filter`, `--skip-*`, `--fresh-e2e`, `--linux`, `--record-baseline`, `--refresh-cache` ou `--no-persist`, erro de uso. Vermelho imprime `gh run view <id> --log-failed`.
 
@@ -328,25 +330,25 @@ Código não commitado é **erro de uso (exit 2)**: o CI só vê commits. CI rod
 
 **Validador `code-budget` (nó `validators` do `verify`)** — mede o que a árvore **adicionou** contra a branch default: `git diff -U0` a partir do merge-base com `origin/{default}` (ou `{default}` local), arquivo novo não rastreado conta inteiro e arquivo movido sem edição não conta. Lê `.cs`/`.ts`/`.tsx`/`.js`/`.jsx`/`.mjs`/`.cjs`, fora de `.d.ts`, de `node_modules`/`bin`/`obj`/`dist`/`.morph` e de código gerado (`*.Designer.cs`, `*.g.cs`, `*ModelSnapshot.cs`).
 
-Três medidas, cada uma **um aviso, nunca erro**: (a) **linhas de comentário adicionadas que citam processo** — `UC-nn`, `ADR-nn`, `FR-nn`, `C{n}`/`F{n}` (cenário/fatia — fora tecla, métrica, célula e o modelo C4), `Gate N`, `plan.md`, `checks.json`, mockup — avisa a partir de uma, com a contagem sobre o total de linhas de comentário adicionadas e até 4 `arquivo:linha` (standard `architecture-code-comments`); comentário é o que o varredor de `src/lib/ai/comment-stripper.js` separa de string, com template e regex literal de TS/JS; (b) **linhas não vazias de teste ÷ de produção** — avisa acima de **1,5×**, e só quando o teste adicionado passa de **40 linhas** (a regressão de um bug de duas linhas cabe abaixo disso); sem linha de produção, o aviso dá as duas contagens sem razão. (c) **densidade de comentário** — linhas de comentário adicionadas ÷ linhas de código adicionadas (as não vazias menos as de comentário), doc-comment (`///`, JSDoc) incluído — avisa acima de **1 a cada 10**, e só a partir de **40 linhas** de código, com até 4 arquivos mais comentados e suas contagens (o padrão do standard `architecture-code-comments` é nenhum comentário).
+Três medidas, cada uma **um aviso, nunca erro**: (a) **linhas de comentário adicionadas que citam processo** — `UC-nn`, `ADR-nn`, `FR-nn`, `C{n}`/`F{n}` (cenário/fatia — fora tecla, métrica, célula e o modelo C4), `Gate N`, `plan.md`, `checks.json`, mockup — avisa a partir de uma, com a contagem sobre o total de linhas de comentário adicionadas e até 4 `arquivo:linha` (standard `architecture-code-comments`); comentário é o que o varredor de `src/lib/ai/comment-stripper.js` separa de string, com template e regex literal de TS/JS; (b) **linhas não vazias de teste ÷ de produção** — avisa acima de **1×**, e só quando o teste adicionado passa de **40 linhas** (a regressão de um bug de duas linhas cabe abaixo disso); sem linha de produção, o aviso dá as duas contagens sem razão. (c) **densidade de comentário** — linhas de comentário adicionadas ÷ linhas de código adicionadas (as não vazias menos as de comentário), doc-comment (`///`, JSDoc) incluído — avisa acima de **1 a cada 10**, e só a partir de **40 linhas** de código, com até 4 arquivos mais comentados e suas contagens (o padrão do standard `architecture-code-comments` é nenhum comentário).
 
 Teste é o que o validador `reuse` já trata como teste: arquivo `.test.` ou `.spec.` com extensão `js`/`jsx`/`ts`/`tsx`, e tudo sob `__tests__/`, `test/`, `tests/` ou pasta terminada em `Test`/`Tests` (`Foo.Tests/`, `FooTests/`). O resto conta como produção, inclusive `a.test.mjs`, `a.test.cjs` e `*.e2e.ts` fora dessas pastas.
 
-Sem base git, ou sem linha de código adicionada, pula com razão; qualquer falha de medição também vira skip, nunca erro. Fica fora do modo `light`.
+Sem base git, ou sem linha de código adicionada, pula com razão; qualquer falha de medição também vira skip, nunca erro. 
 
 **Por quê.** Excesso justificado não silencia o aviso: a justificativa mora na task (orçamento do `morph-plan` passo 5), e é lá que o avaliador a lê.
 
 ### mutate
 
-**`morph-spec mutate [feature] [--plan <arquivo>] [--out <arquivo>] [--no-subset] [--allow-dirty] [--jobs <n>] [--timeout <ms>] [--restore] [--json]`** — mutação **dirigida** para o verificador do Gate 3: no máximo **3** mutantes, só quando o diff tem uma guarda que um cenário exige e o verificador não achou o teste que a morde.
+**`morph-spec mutate [feature] [--plan <arquivo>] [--out <arquivo>] [--allow-dirty] [--jobs <n>] [--timeout <ms>] [--restore] [--json]`** — mutação **dirigida** para o verificador do Gate 3: no máximo **3** mutantes, só quando o diff tem uma guarda que um cenário exige e o verificador não achou o teste que a morde.
 
 **Manifesto** (`--plan`, default `4-review/mutants.json`): `{"mutants":[{"id":"M1","file":"src/x.cs","line":42,"find":"a && b","replace":"a","expect":"OrdersTests.RecusaSemItens deve falhar"}]}` — `expect` é obrigatório (qual teste deve falhar e por quê, dito antes de rodar), `find` começa na `line` e é único nela; barra invertida do código vai como `{{BS}}` (o transporte do Bash a reduz). Mais de 3 mutantes ou `expect` ausente: exit 2.
 
 **O que compila (.NET):** o `build` do nó quando declarado; senão o que o comando nomeia (`.sln`/`.slnx`/`.csproj` — a solution vale pelos projetos que lista, também para o subconjunto); senão a solution única (ou o projeto único) do diretório alvo, como o próprio `dotnet test` escolhe. Só sem nada descobrível recusa (exit 2), antes de mutar, pedindo a solution no comando ou o `build`.
 
-**Método:** recusa arquivo não commitado (`--allow-dirty` assume o risco); snapshot dos bytes fora da árvore (`<git-common-dir>/morph-spec/mutation/<run>/`) com journal — rodada que morreu se desfaz por `mutate --restore`; em .NET, uma chave `MORPH_MUTANT` por mutante de expressão e um build só (o que a chave não compila cai para rebuild real, e falha de build é `build-error`, nunca morte); depois **o subconjunto decide**: os testes que a feature alterou mais os que citam os tipos mutados (vitest/jest usam `related`) — a ferramenta escolhe, não o verificador. `killed` = falha **nova** contra a rodada-base do mesmo escopo, com o motivo literal do TRX; `survived` no subconjunto é o veredito, com o `expect` ao lado; sem subconjunto utilizável, a suíte inteira roda e a morte tem de se repetir.
+**Método:** recusa arquivo não commitado (`--allow-dirty` assume o risco); snapshot dos bytes fora da árvore (`<git-common-dir>/morph-spec/mutation/<run>/`) com journal — rodada que morreu se desfaz por `mutate --restore`; em .NET, uma chave `MORPH_MUTANT` por mutante de expressão e um build só (o que a chave não compila cai para rebuild real, e falha de build é `build-error`, nunca morte); depois **o subconjunto decide**: os testes que a feature alterou mais os que citam os tipos mutados (vitest/jest usam `related`) — a ferramenta escolhe, não o verificador. `killed` = falha **nova** contra a rodada-base do mesmo escopo, com o motivo literal do TRX; `survived` no subconjunto é o veredito, com o `expect` ao lado; rodada que cai é `inconclusive`. **Nunca a suíte inteira:** sem subconjunto utilizável (nenhum teste da feature nem citando os tipos mutados) o comando recusa antes de compilar (exit 2) e manda provar o cenário por leitura; subconjunto que some em runtime (base que não seleciona teste, ou cai) deixa os mutantes `inconclusive` com a mesma razão.
 
-**Nó `e2e: true`:** arquivo coberto **só** por nó de teste `e2e: true` é recusado (exit 2, nomeando mutante, arquivo e nó): a suíte testa o container do compose e o `mutate` recompila só localmente — todo mutante sobreviveria em falso. Com outro nó dono do arquivo, ele é o escolhido — mas, havendo qualquer nó `e2e: true` no config, só se algum arquivo de teste dele (com atributo de teste) citar um tipo declarado no arquivo mutado: o dono de um `.cs` é a suíte .NET, não a referência de projeto, e a unidade que só referencia a API daria sobrevivente em falso. Sem citação, recusa (exit 2) antes do snapshot. Nas duas recusas a saída prescreve o protocolo manual com o comando pronto do nó e2e, cada passo numa linha só encadeado por `&&` (nunca `;`): base verde antes do 1º mutante (`eval "$(morph-spec env <f>)" && morph-spec e2e up <f> && morph-spec heavy run -- <comando do nó>`), a mesma cadeia depois de cada edição, e restauração conferida por `git diff --quiet` seguida de um novo `e2e up` — registrado em `4-review`. Sem nó `e2e: true`, o sobrevivente é achado real e roda como antes.
+**Nó `e2e: true`:** arquivo coberto **só** por nó de teste `e2e: true` é recusado (exit 2, nomeando mutante, arquivo e nó): a suíte testa o container do compose e o `mutate` recompila só localmente — todo mutante sobreviveria em falso. Com outro nó dono do arquivo, ele é o escolhido — mas, havendo qualquer nó `e2e: true` no config, só se algum arquivo de teste dele (com atributo de teste) citar um tipo declarado no arquivo mutado: o dono de um `.cs` é a suíte .NET, não a referência de projeto, e a unidade que só referencia a API daria sobrevivente em falso. Sem citação, recusa (exit 2) antes do snapshot. Nas duas recusas a saída prescreve o protocolo manual com o comando pronto do nó e2e, cada passo numa linha só encadeado por `&&` (nunca `;`): base verde antes do 1º mutante (`eval "$(morph-spec env <f>)" && morph-spec e2e up <f> && morph-spec heavy run -- <comando do nó>`), a mesma cadeia depois de cada edição, e restauração conferida por `git diff --quiet` seguida de um novo `e2e up` — registrado em `4-review`. Sem nó `e2e: true`, vale a regra do subconjunto acima.
 
 **Sem `<feature>`:** vale a única feature em andamento; sem ela (nenhuma, ou mais de uma), exige `--plan`, e a seção só é gravada com `--out` — sai no stdout, `section: null` no `--json`.
 
@@ -496,6 +498,10 @@ Sem fatia na linha de comando, a saída traz `reviews: { verifier, reviewer, sec
 
 **`morph-spec stack-scan [<feature>] [--json]`** — varredura determinística do código contra `config.project.stack`: só os stacks configurados são julgados (sem `project.stack`, nenhuma regra roda e o resultado é `não auditado: project.stack ausente em .morph/config/config.json`, nunca "Em compliance" — exit 0; stack sem regras de varredura sai `não auditado` pelo mesmo motivo; código de um stack não configurado é só anotado). `dotnet`: TargetFramework abaixo de net10 e ORM/banco diferente (Dapper puro, SQL Server, MySQL) são **Bloqueante**; `Guid.NewGuid()`, repository genérico (`IRepository<T>`/`IUnitOfWork` — código morto: apagar a pasta `Repository/` e as 2 linhas de DI), classe `*Service`/`*Manager` sobre `DbContext` e SQL cru (`FromSqlRaw`, `ExecuteSqlRaw`, `SqlQueryRaw`, `ExecuteQuery`) são **Alto**; classe não-sealed é **Médio**; pacote `Microsoft.EntityFrameworkCore|AspNetCore|Extensions` abaixo da major 10 é **Baixo**. `nextjs`: frontend sem Next.js é Bloqueante; Pages Router sem `app/` e biblioteca de UI diferente (MUI, antd, Chakra, Bootstrap, Mantine) são Médio. Código de teste não conta; `node_modules`, `bin`, `obj`, `.morph`, `.claude` e os contêineres de worktree ficam fora; arquivo ilegível é anotado, nunca derruba. Sem código fonte = GREENFIELD. As contagens são de texto e superestimam consumidores — o relatório aponta `graph affected <símbolo> --uses-only`. Desvio Bloqueante/Alto vira nó da árvore de decisões da `morph-plan`. Com `<feature>`, grava `.morph/features/<f>/2-plan/stack-scan.md` (exit 2 se a feature não existe, 1 fora da árvore dona); sem, imprime o markdown.
 
+### tests-audit
+
+**`morph-spec tests-audit [--json]`** — auditoria **somente leitura** dos arquivos de teste rastreados (`git ls-files` + `isTestPath`): total de casos (`[Fact]`/`[Theory]`, `it`/`test`), os maiores arquivos e quatro listas de **candidatos** — nunca vereditos, nada é apagado: teste que lê `.md`/`.txt` ou tem 3+ asserts de frase literal (fixa texto, não comportamento); constante comparada ao próprio literal; família de 4+ `[Fact]` com o mesmo prefixo de nome (candidata a `[Theory]`); o mesmo assunto em mais de uma camada (`XHandlerTests` e `XEndpointTests`/`XIntegrationTests` — fique com a mais barata que morde). Fora de git: exit 2 com a razão. É o ponto de partida de uma limpeza: apagar teste e depois rodar `verify --record-baseline` grava a contagem menor.
+
 ## Suítes de teste (`project.tests[]`) e a divisão loop × suíte
 
 O nó `tests` do `verify` é **plural**: um projeto pode declarar quantas suítes tiver em
@@ -677,7 +683,7 @@ sem `--no-build` já compila sozinho, e pré-compilar ali só dobraria o relógi
 **O ciclo da baseline, e o número que só sai à mão.** `verify --record-baseline` é a única via de
 escrita: mede cada nó numa execução real e grava `expectedCount` de volta no `config.json` (escrita
 atômica `tmp.{pid}` + rename, preservando todo o resto do arquivo). Recusa **quatro** vezes — execução
-vermelha, execução **parcial** (sob `--filter`, mesmo com o verify verde: baseline de meia frota é
+vermelha (fora o `count-drop` com exit 0, abaixo), execução **parcial** (sob `--filter`, mesmo com o verify verde: baseline de meia frota é
 afirmação sobre a outra metade que ninguém fez), contagem desconhecida, e **sem `config.json` ou sem
 `project.tests[]`** (erro de uso, exit 2; o arquivo nunca é criado implicitamente — gravar os nós que o
 fallback sintetiza exigiria inventar a declaração que o comando veio manter). Verde com gravação
@@ -685,11 +691,7 @@ recusada sai **exit 1**, com a razão em **stderr** (sobrevive ao `--json`). A g
 pelos **nós de teste**, não pelos quatro nós do verify: um `validators` vermelho não muda quantos
 testes rodaram. A execução que **gravou** a baseline (verde e inteira) persiste o stamp `verification` como qualquer verify: ela mediu a suíte toda, e rodá-la de novo só para ter prova seria pagar duas vezes pelo mesmo
 verde. Sem gravação (vermelha, parcial, contagem desconhecida) não há stamp, e o `reason` do `--json`
-nomeia o nó que impediu. **Consequência a conhecer:** um `expectedCount` digitado à
-mão **alto demais** (9 onde a suíte roda 7) deixa o verify vermelho por `count-drop`, e então
-`--record-baseline` recusa — preservando o 9. **Não há flag de regravação forçada:** rebaixe ou apague
-o número à mão e então re-meça pelo comando. O caso oposto se conserta sozinho — número baixo demais
-passa com aviso de alta, e o comando grava.
+nomeia o nó que impediu. **Apagar teste é legítimo:** a única cor vermelha que a gravação aceita é o `count-drop` de um nó que saiu com exit 0 — a suíte ficou menor de propósito. `--record-baseline` grava o número menor que mediu, o nó fica verde nessa mesma execução, o stamp persiste e o `feedback` diz `[baseline] rebaixada: <nó> (9 → 7)`; o revisor do Gate 3 vê a queda e julga se foi limpeza. Sem a flag, a queda continua reprovando (regressão silenciosa). Queda ao lado de outro nó vermelho não grava nada.
 
 **A divisão loop × suíte.** É a resposta ao "a suíte inteira não cabe numa chamada":
 
@@ -735,7 +737,7 @@ Falhas do `--show` saem 1: id inexistente (`Standard "<id>" não existe.` com at
 **`--dry-run` prevê sem tocar em nada.** Previsão e execução são o **mesmo percurso**, com os **mesmos filtros** e o **mesmo coletor de efeitos**: em modo normal cada verbo executa *e* registra, em dry apenas registra.
 
 O relatório agrupa por natureza do efeito (apagar, criar diretório, copiar, escrever, mesclar, executar, índice do git) e **nomeia separadamente três grupos que ninguém adivinha da palavra "update"**:
-- **apagados por inteiro antes da reinstalação** — `.claude/{commands,rules,skills,agents}` e `.morph/{framework/standards,framework/hooks,framework/schemas,framework/rubrics,framework/evals,config}`, com a contagem de arquivos que hoje moram em cada um (`framework/rubrics` não é mais instalado: entra na lista só para sumir de instalações antigas);
+- **apagados por inteiro antes da reinstalação** — `.claude/{commands,rules,skills,agents}` e `.morph/{framework/standards,framework/hooks,framework/schemas,framework/evals,config}`, com a contagem de arquivos que hoje moram em cada um;
 - **fora do projeto** — `~/.claude/statusline.sh`, `~/.claude/statusline.py` e a mesclagem de `~/.claude/settings.json`;
 - **dentro do pacote da CLI** — `generate-refs.js` escrevendo `framework/hooks/shared/phase-utils.js` do pacote, que num `npm link` de desenvolvimento é o próprio repositório do framework. Em dry roda a variante `--check`, que verifica e não escreve.
 
@@ -743,17 +745,6 @@ O `--dry-run` **passa por cima** da saída antecipada de "CLI desatualizada": bl
 
 **Freio de major.** Um salto de **dois majors ou mais** é recusado sem `--force`, **antes de qualquer mutação** — recusar depois de mutar é meio-estado. A versão instalada vem de `.morph/.morphversion → morphVersion`, o mesmo registro que o `update` já lê; **nunca** de `config.json → frameworkVersion`, que o `update` escreve e jamais lê para decidir (medido: os dois divergem por um major inteiro num projeto real). Quando os dois discordam, a mensagem imprime **os dois** e diz qual decidiu — escolher em silêncio é acertar metade das vezes e nunca saber qual metade. `.morphversion` ausente ou ilegível é tratado como salto grande, com motivo próprio (`versão instalada indeterminável`) distinto do salto medido: "não sei quão velho isto é" é precisamente quando sobrescrever às cegas é mais perigoso. `--force` dispensa o freio e o relatório final **registra a dispensa**. `--dry-run` combinado com uma recusa **imprime o relatório**, com a recusa como primeiro item.
 
-**Feature em voo no formato anterior.** Antes de qualquer mutação, o `update` varre `.morph/features/` da raiz e de cada worktree que o `git worktree list` conhece; uma feature não encerrada (`status` diferente de `completed`/`abandoned`) com `2-plan/tasks.json` ou `0-proposal/` e sem `2-plan/plan.md` é do formato que esta versão não conduz, e o `update` recusa (exit 1, nada escrito):
-
-```
-Recusado: N feature(s) em voo no formato anterior ao plan.md (proposal/spec/tasks.json), que esta versão não conduz:
-  - <feature> (raiz | <caminho da worktree>)
-  Termine cada uma na 8.47: `npx @polymorphism-tech/morph-spec@8.47 <comando>` (por exemplo `finish <feature> --pr`),
-  ou arquive sem integrar: `morph-spec archive <feature> --force` (o Gate 3 dela não foi aprovado). Depois rode o `update` de novo.
-```
-
-`--force` **não** dispensa esta recusa (o freio de major, sim): a CLI nova não sabe conduzir essas features. Feature em `.morph/archive/` não conta. `--dry-run` põe as mesmas linhas no topo da previsão. A mesma regra roda no `init --force` e no `setup-infra` (inclusive `--reinstall`), que sobrescrevem `.morph/` e `.claude/` sem passar pelo `update`: recusam com as mesmas linhas e saem 1. No retorno programático, `{ refused: true, reason: 'old-format-features', features }`.
-
 **Por quê.** Não há travessia paralela — o resumo de uma execução real também sai do coletor, de modo que um ponto de emissão esquecido some das duas saídas ao mesmo tempo, em vez de mentir só no `--dry-run`.
 
 ## Grafo de codebase
@@ -810,7 +801,7 @@ O servidor MCP (`graphify-mcp`, 10 tools, todas aceitando `project_path`) está
 
 ### cost
 
-**`morph-spec cost [feature] [--by phase] [--all-trees] [--json]`** — custo da execução a partir do mesmo `events.jsonl`: bytes de contexto lidos por tipo (`rubric`/`standard`/`skill`/`agents`/`plan-artifact`/`code` — a janela `offset`/`limit` que o Read trouxe, quando o evento a tem), dispatches + tamanho de prompt e mix de tools. Bytes são **proxy determinística** de custo de token; os tokens reais vêm à parte: `SessionUsage` (sessão principal) e `AgentUsage` (cada sub-agent, lido do transcript dele), somados **só pelo `delta`** de cada amostra — o total de topo é acumulado e se repete a cada Stop, e amostra antiga sem `delta` fica fora da soma e é contada como legada. `--all-trees` agrega **toda árvore git** com log, mais os logs que o `finish` guardou em `.git/morph-spec/finish-backup/` antes de desmontar a worktree, deduplicados por `eventId`.
+**`morph-spec cost [feature] [--by phase] [--all-trees] [--json]`** — custo da execução a partir do mesmo `events.jsonl`: bytes de contexto lidos por tipo (`checklist`/`standard`/`skill`/`agents`/`plan-artifact`/`code` — a janela `offset`/`limit` que o Read trouxe, quando o evento a tem), dispatches + tamanho de prompt e mix de tools. Bytes são **proxy determinística** de custo de token; os tokens reais vêm à parte: `SessionUsage` (sessão principal) e `AgentUsage` (cada sub-agent, lido do transcript dele), somados **só pelo `delta`** de cada amostra — o total de topo é acumulado e se repete a cada Stop, e amostra antiga sem `delta` fica fora da soma e é contada como legada. `--all-trees` agrega **toda árvore git** com log, mais os logs que o `finish` guardou em `.git/morph-spec/finish-backup/` antes de desmontar a worktree, deduplicados por `eventId`.
 
 ### cost --metrics
 

package/framework/evals/review-checklist.md

@@ -41,7 +41,10 @@ diferente") é nota; nota não bloqueia e não pede rodada nova. Na dúvida, sem
 ## Verificador (`4-review/verifier.md`)
 
 Missão: **provar cada cenário** do `2-plan/checks.json`. O default de todo `Cn` é NÃO PROVADO;
-critério que você não verificou nunca vira PROVADO por inferência.
+critério que você não verificou nunca vira PROVADO por inferência. A prova é a que o plano declarou
+(`prova:` do Cn): `leitura` prova-se pelo `arquivo:linha` e pela fiação, **sem teste** — Cn `leitura`
+sem teste não é NÃO PROVADO, e pedir teste para ele não é bloqueador. Só Cn com `risco:` exige teste
+que morde.
 
 ```markdown
 ## Checks
@@ -82,7 +85,9 @@ morde. Escreva `4-review/mutants.json` e rode `morph-spec mutate {feature}` **um
 
 `expect` é obrigatório: diga qual teste deve falhar e por quê **antes** de rodar — mutante cujo
 efeito você não sabe prever tende a ser equivalente. Barra invertida do código vira `{{BS}}`.
-Sobreviveu numa linha que um cenário exige → bloqueador `teste`. Sobreviveu em outra → nota. Cole a
+Sobreviveu numa linha que um cenário exige → bloqueador `teste`. Sobreviveu em outra → nota.
+Sem subconjunto (exit 2) ou `inconclusive`: a mutação não roda a suíte inteira — prove por leitura
+(`arquivo:linha` + o teste que cobre), nunca em laço. Cole a
 seção `## Mutações` que a ferramenta imprime. A reversão é da ferramenta; rodada morta no meio:
 `morph-spec mutate --restore`.
 
@@ -109,6 +114,11 @@ Read-only, sobre o commit do dispatch: `git diff {base}..{sha}`, `git show {sha}
 árvore de trabalho — o verificador pode estar com um mutante aplicado nela. Default SHIP.
 
 1. **Escopo**: o diff contra as fatias (`arquivos:`) e o `## Contrato de implementação` do plano.
+   Teste além do orçamento também é escopo: teste para Cn `prova: leitura`, mais de um teste por Cn de
+   risco sem porquê no plano, teste que só fixa texto/constante/DTO, o mesmo comportamento em duas
+   camadas — bloqueador `escopo` (apague, não acrescente). `expectedCount` menor no
+   `.morph/config/config.json` do diff sem teste apagado no mesmo diff é bloqueador `regressao`: é
+   suíte que parou de rodar, não limpeza.
 2. **Arquitetura**: padrão ou abstração nova contra o stack do projeto e os standards (camada que o
    projeto não usa, repositório sobre o DbContext, dependência nova sem decisão no plano).
 3. **Regressão**: para cada símbolo público alterado, `morph-spec graph affected <símbolo> --prod --json`.

package/framework/hooks/README.md

@@ -6,41 +6,16 @@ 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-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
-│   │   └── warn-bash-source-write.js              # PreToolUse(Bash): source written by redirect skips the Write/Edit guards
-│   ├── user-prompt/
-│   │   └── enrich-prompt.js         # Context-aware prompt enrichment
-│   ├── pre-tool-use/
-│   │   ├── protect-spec-files.js    # Block edits to approved spec artifacts
-│   │   └── enforce-phase-writes.js  # Enforce writes to correct phase dir
-│   ├── post-tool-use/
-│   │   └── dispatch.js              # Dispatch on CLI commands (auto-checkpoint)
-│   ├── stop/
-│   │   └── validate-completion.js   # Advisory: warn about incomplete work
-│   ├── pre-compact/
-│   │   └── save-morph-context.js    # Snapshot state before compaction
-├── shared/                          # Reusable utilities for all hooks
-│   ├── state-reader.js              # Read-only state.json accessor
-│   ├── phase-utils.js               # Phase constants and path utilities
-│   ├── hook-response.js             # JSON response builders
-│   └── stdin-reader.js              # Stdin JSON reader
-├── git/                             # Git hooks (Bash)
-│   ├── pre-commit/
-│   │   ├── orchestrator.sh          # Master hook dispatcher
-│   │   └── agents.sh                # Validates agents.json schema
-│   ├── commit-msg/
-│   │   └── conventional-commits.sh  # Enforces conventional commits
-│   └── pre-push/
-│       └── run-tests.sh             # Runs test suite before push
-└── README.md                        # This file
+├── claude-code/
+│   ├── core/          # every hook, plus chain.js (one process per multi-hook group)
+│   └── statusline.py  # global statusline
+├── shared/            # code hooks share (and src/ imports): state reader, guards, e2e, heavy, telemetry
+└── README.md
 ```
 
+The registered set is `MORPH_HOOKS` in `src/utils/hooks-installer.js` — the table below lists it. No hook builds,
+typechecks or runs tests: that is `morph-spec verify`.
+
 ## Hook Events
 
 | Event | Hook | Type | Purpose |
@@ -104,17 +79,6 @@ The installer writes to `.claude/settings.local.json`:
 }
 ```
 
-### Git Hooks
-
-```bash
-# In your project root
-cd .git/hooks
-ln -sf ../../framework/hooks/git/pre-commit/orchestrator.sh pre-commit
-ln -sf ../../framework/hooks/git/commit-msg/conventional-commits.sh commit-msg
-ln -sf ../../framework/hooks/git/pre-push/run-tests.sh pre-push
-chmod +x pre-commit commit-msg pre-push
-```
-
 ## Shared Utilities
 
 All Claude Code hooks import from `framework/hooks/shared/`:

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

@@ -6,70 +6,31 @@ 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
- * 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.
- */
+// Generic recursive removals FOLLOW a worktree's junctions and empty the root's `.claude/` and `.morph/framework/`.
+// The reparse scan is the authority, not the path shape; anything unparseable passes.
 
-// 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).
+// A hook never imports a sibling hook (its standalone tail would fire), so the tokenizer lives in shared/.
 export { tokenize };
 
-/**
- * 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.
+  // The path is always the last non-flag token.
   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.
+  // Needs both the command word and a recursive flag: a plain `rm file` cannot traverse a junction.
   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.
+  // A cmd.exe switch is a slash plus one or two letters; anything longer is a POSIX absolute path.
   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`.
@@ -78,10 +39,6 @@ export function extractRemovalTarget(command) {
   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;

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

@@ -5,56 +5,23 @@ import { stateExists } from '../../shared/state-reader.js';
 // 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 (GIT_GLOBAL_WITH_VALUE.has(tokens[j])) j += 2;
+      else j += 1;
     }
     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;

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

@@ -1,54 +1,6 @@
 #!/usr/bin/env node
-/**
- * chain.js — roda vários hooks core num único processo node.
- *
- * Motivação (onda de performance R2): cada hook registrado no Claude Code é
- * hoje um processo node próprio (~60ms de cold start). Um único Write/Edit
- * disparava até 9 desses processos — 2 PreToolUse + 3+2+2 PostToolUse. Este
- * script agrupa os elos de um mesmo event+matcher (a mesma entrada do
- * registry em src/utils/hooks-installer.js) num só spawn: lê stdin UMA vez,
- * importa e chama `run(payload)` de cada hook em sequência, e combina as
- * respostas — reduzindo esses 9 spawns para 4 por Write/Edit (1 PreToolUse +
- * 3 PostToolUse: Write|Edit / Write|Edit|AskUserQuestion / matcher-`*`).
- *
- * Uso: `node chain.js <hook1> <hook2> ...` — nomes de arquivo SEM `.js`,
- * resolvidos no mesmo diretório deste script (core/), na ORDEM em que devem
- * rodar. A ordem é a mesma que o registry antigo (duas entries separadas)
- * já implicava — ver o comentário de cada grupo em hooks-installer.js.
- *
- * Cada hook core exporta `run(payload)` (ver framework/hooks/shared/hook-response.js
- * `runStandalone`) — o arquivo continua executável standalone (spawnSync
- * direto, como os testes já fazem) porque a própria cauda do arquivo só lê
- * stdin/imprime/sai quando NÃO está sendo importado por esta cadeia.
- *
- * Regras de combinação:
- *  - PreToolUse (decision:'block'): o PRIMEIRO elo que retornar um bloqueio
- *    VENCE e encerra a cadeia — os elos seguintes nem chegam a rodar. Isto é
- *    uma otimização NOVA desta consolidação (antes, Claude Code podia
- *    disparar os dois processos de qualquer forma); o resultado observável
- *    pro Claude Code é idêntico (o tool call é bloqueado do mesmo jeito).
- *  - PostToolUse / outros eventos de contexto: os textos de TODOS os elos que
- *    retornarem `hookSpecificOutput.additionalContext` (ou `decision:'approve'`
- *    com additionalContext) são concatenados, na ORDEM dos argv, separados por
- *    uma linha em branco — nenhum elo é pulado por um vizinho ter respondido.
- *  - Nome do evento (hookSpecificOutput.hookEventName) no resultado final:
- *    o valor que o PRIMEIRO elo a declarar um venceu (mesma regra de
- *    "primeiro vence" do bloqueio acima — na prática todos os elos de um
- *    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
- *    try/catch; isto é a segunda rede de segurança, para o import em si.
- */
+// Usage: node chain.js <hook> ... (names without .js, run in argv order). The first block wins and ends the chain,
+// the contexts of every link concatenate, and an exception in one link never stops the next.
 
 import { dirname, join } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
@@ -56,20 +8,12 @@ import { readStdin } from '../../shared/stdin-reader.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Marca "já estou dentro de uma cadeia" para os hooks importados abaixo: a
-// cauda de execução standalone de cada hook (runStandalone() em
-// hook-response.js) só dispara quando esta flag NÃO está setada. Setada
-// ANTES do primeiro import dinâmico — cada hook importado herda o mesmo
-// process.env deste processo.
+// Set before the first import: each hook's standalone tail runs only when this is unset.
 process.env.MORPH_HOOK_CHAINED = '1';
 
-// Override só para testes da mecânica genérica desta cadeia (fixtures fora
-// de core/, sem precisar ser hooks reais nem satisfazer as convenções que
-// hook-wiring.test.js exige de todo arquivo em core/). Produção nunca seta
-// isto — resolve sempre no próprio diretório deste script.
+// Test-only override; production always resolves next to this script.
 const coreDir = process.env.MORPH_HOOK_CORE_DIR || __dirname;
 
-/** Extrai o texto de contexto de um resultado de hook, se houver. */
 function contextOf(result) {
   if (!result) return null;
   if (result.decision === 'approve' && typeof result.additionalContext === 'string') {
@@ -93,13 +37,11 @@ async function main() {
       const mod = await import(pathToFileURL(join(coreDir, `${name}.js`)).href);
       result = await mod.run(payload);
     } catch {
-      // Fail-open POR ELO — ver doc do módulo acima.
       result = null;
     }
 
     if (!result) continue;
 
-    // PreToolUse: o primeiro bloqueio vence e encerra a cadeia.
     if (result.decision === 'block') {
       // A later link blocking must not swallow what earlier links reported (a tsc error on the same edit).
       if (contexts.length) result = { ...result, reason: [...contexts, result.reason].join('\n\n') };
@@ -116,9 +58,6 @@ async function main() {
     const ctx = contextOf(result);
     if (ctx) {
       contexts.push(ctx);
-      // First link to declare a name wins (mirrors block-first-wins above) —
-      // in practice every link in a group observes the SAME real Claude Code
-      // event, so this only matters as a deterministic tie-break.
       eventName = eventName || result?.hookSpecificOutput?.hookEventName;
     }
   }

package/framework/hooks/claude-code/core/comment-guard.js

@@ -1,17 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * PostToolUse Hook: comments the edit added in a shape the
- * `architecture-code-comments` standard never allows.
- *
- * Event: PostToolUse | Matcher: Write|Edit
- *
- * `decision: block` makes the agent fix it in the same turn; the edit itself
- * already landed. Only comments absent from `tool_response.originalFile`
- * count, so editing a legacy file never reports its old comments.
- *
- * Fail-open: any error passes silently.
- */
+// `decision: block` makes the agent fix it in the same turn (the edit already landed). Only comments absent from
+// `tool_response.originalFile` count, so editing a legacy file never reports its old comments.
 
 import { readFileSync } from 'fs';
 import { isAbsolute, relative, resolve } from 'path';
@@ -78,10 +68,6 @@ function describe(file, findings) {
   ].join('\n');
 }
 
-/**
- * @param {object} payload - PostToolUse stdin payload
- * @returns {Promise<object|null>}
- */
 export async function run(payload) {
   try {
     if (!['Write', 'Edit'].includes(payload?.tool_name)) return null;