@polymorphism-tech/morph-spec 9.7.0 → 10.0.0

package/framework/schemas/config.schema.json

@@ -57,7 +57,7 @@
               "expectedCount": {
                 "type": "integer",
                 "minimum": 0,
-                "description": "Recorded baseline. Written ONLY by `morph-spec verify --record-baseline`, from a green run — never typed by hand."
+                "description": "Recorded baseline, kept only for `node-test` and `evals` (ignored, and removed by --record-baseline, on the other runners). Written ONLY by `morph-spec verify --record-baseline`, from a green run — never typed by hand."
               },
               "timeoutMs": {
                 "type": "integer",
@@ -122,11 +122,16 @@
     "e2e": {
       "type": "object",
       "additionalProperties": true,
-      "description": "The verification stack of `e2e up` and of the verify e2e node. Only hostServices is described here; the other keys (auth, command, portEnvNames, ...) stay open.",
+      "description": "The verification stack of `e2e up` and of the verify e2e node. Only hostServices and resetCommand are described here; the other keys (auth, command, portEnvNames, ...) stay open.",
       "properties": {
+        "resetCommand": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Run by `e2e reset` to put the running stack's data back in a known state between verification flows, with the stack env (port block + e2e.auth.envFile), before the auth seed. Unset: `e2e reset` recreates, empty, the compose services without a build section that mount a named, non-external volume (rm -sfv, volume rm, up -d --wait). App services and hostServices are never restarted."
+        },
         "hostServices": {
           "type": "array",
-          "description": "Apps that run as host processes next to the compose stack, when building them inside the Docker VM is expensive: compose keeps only the dependencies. Order on `e2e up` and on the verify e2e node: compose up --wait, then each service in array order (build, start detached, health), then the auth seed. They stay up until `e2e down`, `finish`, `delete` or `worktree remove`. Reused while the code stamp (HEAD + status + diff) matches and health is green; a divergent stamp or --fresh/--fresh-e2e kills, rebuilds and restarts them. A failure (build exit != 0, timeout, health never green) fails `e2e up` (exit 1) and the e2e node with the service name and its log tail, kills what this run started and skips the seed. The authority at runtime is validateServices() in framework/hooks/shared/host-services.js.",
+          "description": "Apps that run as host processes, in the feature's port block: next to the compose stack when building them inside the Docker VM is expensive (compose keeps only the dependencies), or alone when the app has no dependency to containerize (no database, no queue). Without a compose file and without a configured e2e.composeFile, a non-empty hostServices IS the stack (host-only): no compose lint, no Docker check, `e2e reset` runs resetCommand or only the seed. Order on `e2e up` and on the verify e2e node: compose up --wait (skipped host-only), then each service in array order (build, start detached, health), then the auth seed. They stay up until `e2e down`, `finish`, `delete` or `worktree remove`. Reused while the code stamp (HEAD + status + diff) matches and health is green; a divergent stamp or --fresh/--fresh-e2e kills, rebuilds and restarts them. A failure (build exit != 0, timeout, health never green) fails `e2e up` (exit 1) and the e2e node with the service name and its log tail, kills what this run started and skips the seed. The authority at runtime is validateServices() in framework/hooks/shared/host-services.js.",
           "items": {
             "type": "object",
             "additionalProperties": false,
@@ -237,7 +242,7 @@
           "type": "object",
           "additionalProperties": false,
           "default": { "unit": 1.5, "build": 4, "e2e": 4 },
-          "description": "Free-RAM floor per kind of heavy command. unit = vitest/jest, npm|pnpm|yarn test, the verify tests node; e2e = playwright, docker compose up, the verify e2e node, e2e up; build = everything else (dotnet build|test|publish, next build, docker build, mutate, unknown commands). A verify admitted at a lighter node waits again, holding its slot, before a heavier one. A kind left out takes an explicit heavy.minFreeMemGb, else its default.",
+          "description": "Free-RAM floor per kind of heavy command. unit = vitest/jest, npm|pnpm|yarn test, the verify tests node; e2e = playwright, docker compose up, the verify e2e node, e2e up; build = everything else (dotnet build|test|publish, next build, docker build, unknown commands). A verify admitted at a lighter node waits again, holding its slot, before a heavier one. A kind left out takes an explicit heavy.minFreeMemGb, else its default.",
           "properties": {
             "unit": { "type": "number", "minimum": 0 },
             "build": { "type": "number", "minimum": 0 },
@@ -268,15 +273,15 @@
         },
         "gateBash": {
           "type": "boolean",
-          "default": false,
-          "description": "Opt-in. A PreToolUse hook takes a slot before a raw heavy Bash command (dotnet build|test|publish|pack, npm|pnpm|yarn test|build, vitest, jest, docker compose up|build, ...) runs and the matching Post hook gives it back. Waits up to heavy.waitTimeoutSec (capped below the hook timeout), then refuses the call with a busy message instead of running it. Foreground Bash only: a run_in_background call is not gated, and a call denied or interrupted after the hook keeps its slot until its timeout lapses, and that timeout starts before the permission prompt."
+          "default": true,
+          "description": "On by default: the session runs builds and tests itself, so a raw heavy command queues like the verify does. A PreToolUse hook takes a slot before a raw heavy Bash command (dotnet build|test|publish|pack, npm|pnpm|yarn test|build, vitest, jest, docker compose up|build, ...) runs and the matching Post hook gives it back. Waits up to heavy.waitTimeoutSec (capped below the hook timeout), then refuses the call with a busy message instead of running it. Foreground Bash only: a run_in_background call is not gated, and a call denied or interrupted after the hook keeps its slot until its timeout lapses, and that timeout starts before the permission prompt."
         }
       }
     },
     "worktree": {
       "type": "object",
       "additionalProperties": true,
-      "description": "Worktree behaviour of this project. Other keys are left open; the readers are src/lib/worktree/vscode-settings.js and src/lib/worktree/agent-reaper.js.",
+      "description": "Worktree behaviour of this project. Other keys are left open; the reader is src/lib/worktree/vscode-settings.js.",
       "properties": {
         "root": {
           "type": "string",
@@ -287,18 +292,6 @@
           "type": "boolean",
           "default": true,
           "description": "false stops `init`, `update`, `worktree setup|provision` and `doctor --worktrees --prune` from adding the worktree/node_modules (and, on .NET, bin/obj) excludes to .vscode/settings.json. `MORPH_EDITOR_SETTINGS=0` does the same for one run."
-        },
-        "reap": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "graceMinutes": {
-              "type": "number",
-              "minimum": 0,
-              "default": 30,
-              "description": "How long a sub-agent's events.jsonl must stay quiet after its AgentUsage before `worktree reap` removes the tree: a stopped agent can still be resumed by SendMessage. An invalid value falls back to 30."
-            }
-          }
         }
       }
     }

package/framework/schemas/feature.schema.json

@@ -29,6 +29,11 @@
       "format": "date-time",
       "description": "Stamped by `morph-spec archive`."
     },
+    "archivedFrom": {
+      "type": "object",
+      "properties": { "sha": { "type": "string", "pattern": "^[0-9a-f]{40}$" } },
+      "description": "Branch tip before `morph-spec archive` pruned the folder to feature.json + 2-plan/plan.md: the report, reviews and evidence stay readable at this sha."
+    },
     "abandonedAt": {
       "type": "string",
       "format": "date-time",
@@ -52,7 +57,8 @@
         "type": "object",
         "required": ["pause", "reason", "signals", "trust", "decidedAt"],
         "properties": {
-          "pause": { "type": "boolean", "description": "true = the gate must pause for a human (AskUserQuestion); false = auto-pass with a short summary." },
+          "pause": { "type": "boolean", "description": "true = the gate does not pass yet: `resolver` says who clears it (the session by doing the work, or a human by AskUserQuestion); false = auto-pass with a short summary." },
+          "resolver": { "type": ["string", "null"], "enum": ["session", "human", null], "description": "Who clears a pause: `session` does the work the reason names and runs gate-check again (verify, fix loop, plan-check, review dispatch); `human` answers the gate question. null when the gate does not pause. Rule: `pauseResolver` in src/lib/risk-detector.js." },
           "reason": { "type": "string", "description": "The signal that drove the decision (or 'nenhum sinal de risco')." },
           "signals": {
             "type": "object",

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

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when_to_use: Use quando for iniciar um novo projeto de LP com o template Umbraco genérico
 user-invocable: true
-cliVersion: "9.7.0"
+cliVersion: "10.0.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/create-umbraco-lp/references/umbraco-lp-patterns.md

@@ -1,6 +1,6 @@
 # Umbraco 17 / .NET 10 + Next.js: Padrões e Gotchas do Sistema de Leads (Frente 4)
 
-> **Origem:** documentado a partir do código real em `MORPH_Umbraco_LP_Template` (template canônico) e validado contra `Gardim_LP_Umbraco` (implementação de referência).
+> **Origem:** documentado a partir do código real em `MORPH_Umbraco_LP_Template` (template canônico) e validado contra uma LP em produção derivada dele.
 > **Natureza:** referência consultável para devs adaptando o template para novos clientes — não é um skill executável. A lógica vive no template repo; este doc é o mapa dos padrões e armadilhas.
 > **Convenção de citação:** cada padrão cita o **arquivo real** no `MORPH_Umbraco_LP_Template`. Símbolos (método/classe/alias) são âncoras estáveis; números de linha, quando aparecem, são auxiliares e podem deslizar entre versões.
 

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

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when_to_use: Use quando o usuário pedir "use /migrate-lp-to-umbraco {projeto}" ou descrever a necessidade de migrar uma LP para Umbraco
 user-invocable: true
-cliVersion: "9.7.0"
+cliVersion: "10.0.0"
 stacks:
   - umbraco
 ---
@@ -346,7 +346,7 @@ Copiar as variáveis de design da origem para `frontend/src/app/globals.css` no
 href="https://fonts.googleapis.com/css2?...">` no `<head>` é render-blocking (round-trip
 externo antes de qualquer paint) e, combinado com `font-display: swap`, causa CLS quando a
 fonte troca depois do primeiro paint — foi 1.680ms de render-blocking estimado e 0.221 de CLS
-medidos num caso real (Barone_LP). **Não usar `next/font/google`** aqui (diferente do passo 4
+medidos numa LP real migrada. **Não usar `next/font/google`** aqui (diferente do passo 4
 de `create-umbraco-lp`, que pode usar): o nome de família que ele gera é escopado/diferente do
 literal da origem, e o gate de paridade (passo 6b.2) compara `font-family` computado
 byte-a-byte contra a origem — `next/font` quebra esse check.

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

@@ -1,189 +1,61 @@
 ---
 name: morph-apply
-description: Executa as fatias do plano de uma feature morph-spec — dispatch por persona, em ondas paralelas do plan-check, com relatório por fatia — prova a feature com um verify sem filtro e entrega à morph-review (Gate 3).
+description: Implementa o plano aprovado de uma feature morph-spec inteiro nesta sessão, prova com um verify sem filtro, conduz o Gate 3 (verificador, revisor e segurança em contexto fresco) e fecha com finish. Também conduz hotfix e chore.
 version: core
-when_to_use: Use com o gate do plano aprovado, em "use /morph-apply {feature}" ou "implementar feature"
+when_to_use: Use com o gate do plano aprovado ("/morph-apply {feature}", "implementar feature"), em "/morph-review {feature}" (entra no §5), em "/morph-hotfix {feature}" ou incidente de produção (references/hotfix.md), ou quando `morph-spec next` mandar implement, verify, fix, review ou finish
 user-invocable: true
-cliVersion: "9.7.0"
+cliVersion: "10.0.0"
 ---
 
 # morph-apply
 
-## Objetivo
+Do plano aprovado à feature fechada, numa janela só. O progresso é `3-implement/report.md`; o próximo passo é o que `morph-spec next {feature}` disser.
 
-Toda fatia de `2-plan/checks.json` com relatório final em `3-implement/reports/F{n}.md`, o
-`verify` da feature verde, e a entrega à `morph-review`. O progresso **é** o conjunto de
-relatórios (ausente = pendente, `PARCIAL` na 1ª linha = parcial, senão feito): não há arquivo de
-status para editar.
+## 1. Contexto, uma vez
 
-## Ritmo
+Leia `2-plan/plan.md` e `2-plan/checks.json` uma vez por sessão (ou depois de um `/compact`): o plano está congelado, não releia por padrão — só o trecho que falta. Retomando, leia também `3-implement/report.md`: é a sua memória.
 
-Comando em primeiro plano; o `verify {feature}` que passa do teto de 10 min do Bash vai com
-`run_in_background` e espera a notificação de término **no mesmo turno**: nunca encerre o turno
-com o verify da feature rodando — o stamp que o Gate 3 lê é o dele. `verify` com exit 3 (`status: "busy"`) já esperou a fila pesada
-pelo timeout dela: no máximo uma chamada nova; persistiu, pare e avise o usuário — a máquina está
-saturada (skill `morph-machine`). Nunca `sleep`/`until` nem retentativa agendada.
+`.morph/config/config.json` sem `project.stack` → a stack é do usuário: `AskUserQuestion` com a stack completa do Morph recomendada (`dotnet+nextjs --with neon`, standard `architecture-stack-baseline`), depois `morph-spec stack-set <stack>`. As rules de domínio só valem numa sessão nova: peça para reabrir antes de qualquer código. Sem `project.tests` → declare-os a partir do `## Contrato de implementação` (forma em `.morph/framework/schemas/config.schema.json`) e confira com `morph-spec doctor --full`, antes de qualquer código.
 
-## 1. Contexto, uma vez
+## 2. Implementar
 
-Read em `2-plan/plan.md` e `2-plan/checks.json` uma vez por sessão (ou depois de um `/compact`):
-o plano está congelado desde o gate, então não releia por padrão — só o trecho que falta.
-Antes do primeiro dispatch: `.morph/config/config.json` sem `project.stack` ou `project.tests` →
-declare-os a partir dos comandos de baseline do `## Contrato de implementação` e commite junto com o
-`.gitignore` que o `plan-check` semeou (`bin/`/`obj/` num projeto .NET) — antes de qualquer código. Não há comando de
-CLI para isso: uma edição no `config.json` na forma de `.morph/framework/schemas/config.schema.json`
-(`project.tests[]` com `id` e `command`; `project.stack` com as tags unidas por `+`, ex. `dotnet+nextjs`;
-mais de uma solução .NET no repositório → `project.backendPath` com a pasta da que o build compila), conferida
-por `morph-spec doctor --full`.
-`morph-spec plan-check {feature}` imprime as **ondas**: fatias de uma onda não dependem uma da
-outra nem tocam o mesmo arquivo, até 4 por onda.
-
-## 2. Fatiar
-
-- Uma onda por vez, até **4 agentes ao mesmo tempo**, um por fatia, `subagent_type: "morph-{id}"` (o `persona:` da fatia).
-- Duas fatias em voo que escrevem o mesmo arquivo: a segunda vai em worktree (§4), rolling.
-- Fatias em paralelo na mesma árvore commitam pela lista explícita de arquivos (`git add <paths>`), nunca um diretório: `git add api` leva o arquivo que a fatia vizinha acabou de escrever.
-- **Inline** só para fatia pequena no domínio já carregado, com **uma linha de porquê** no relatório.
-  Antes de codar, leia os standards que a fatia fixa. Inline também grava `3-implement/reports/F{n}.md`,
-  no formato abaixo — é ele que conta o progresso.
-
-O hook `validate-completion` (no Stop) e o `report-check` cobram o relatório pela mesma régua
-(`inspectReport`); conhecer o formato antes evita reescrever o relatório depois de dar a fatia por feita:
-
-```markdown
-# F{n} — {título}
-
-{2-3 frases: o comportamento entregue, onde mora e como foi provado}
-
-**Arquivos:** `{path}`, `{path}`
-
-**Checks:** C{n} — {teste que prova, ou `arquivo:linha`}
-
-**Standards:** `{id}`, `{id}`
-```
-
-`**Arquivos:**` lista todo arquivo criado ou modificado; cada `C{n}` que a fatia `cobre` aparece pelo
-id; relatório que abre com `PARCIAL` não conta como feito. Os relatórios **são** o registro da
-implementação: o `verify` confere a união dos `**Arquivos:**` contra os
-`arquivos:` das fatias (aviso, nunca reprova). `**Standards:**` nomeia os ids que o agente de fato
-consultou (o `report-check` não o exige).
-- Persona não registrada: `general-purpose` com o campo `persona` de `agents.json` colado, e
-  `dispatch-fallback: general-purpose ({id} não registrado)` no relatório.
-
-## 3. Dispatch — só o que muda
-
-O contrato fixo (relatório, estado, teste, escopo, `wip`, processos, reuso, mutação e o formato do
-relatório) está no corpo da persona gerada e chega a todo dispatch sem ser colado. O prompt leva:
-
-```
-dispatch Agent (subagent_type: "morph-{id}") with prompt:
-Fatia F{n} — <título>
-cobre: <cada Cn com o texto literal do cenário, a `prova:` e o `risco:`>
-arquivos: <os `arquivos:` da fatia>
-standards: <por id: o digest de `morph-spec standards --find` + as 3-8 regras que ESTA fatia aplica>
-reuso: <as linhas de `## Reuso` que tocam a fatia — conceito, veredito, alvo>
-contexto: <o que você já leu: `arquivo:linhas` + o trecho; nada que o agente tenha de reler>
-relatório: .morph/features/{feature}/3-implement/reports/F{n}.md (com `**Standards:**`: os ids consultados)
-worktree: <só com isolamento>
-```
-
-## 4. Worktree rolling
-
-Com `isolation: "worktree"` o hook `WorktreeCreate` cria `worktrees/<n>` na branch `morph-task/<n>`,
-com junctions e `.morph/worktree.env` prontos (infra faltando: `morph-spec worktree link --all`).
-**Rolling, não por onda:** a cada relatório, `report-check`, `git merge --no-ff <branch>` (conflito →
-`git merge --abort` e a fatia volta a pendente com nota no relatório) e despache na hora a próxima fatia
-que ficou pronta sem colidir com as em voo. Depois de cada retorno, `morph-spec worktree reap --json`
-(`not-a-registered-worktree` no `remove --target` seguinte = o reaper já o levou); o que sobrar sai por `morph-spec worktree remove --target <path> --delete-branch` (já mergeada; o
-`git branch -d` dele recusa trabalho não integrado) — NUNCA `git worktree remove` cru,
-que atravessa as junctions.
-
-## 5. Retomar o controle
-
-`morph-spec report-check {feature} F1 F2 … --json` com as fatias que voltaram. **Leia o arquivo de
-relatório, não a mensagem** — a mensagem final pode não chegar ou vir resumida.
-
-| Veredito | Ação |
-|---|---|
-| `ok` | siga |
-| `report-stale` | **não re-despache**: o agente escreveu depois de relatar; leia `observed` e atualize o relatório |
-| `report-incomplete` + `resume` | `PARCIAL` na 1ª linha = a fatia não está pronta — o `report-check` o acusa como `report-incomplete`. Retome o MESMO agente por `SendMessage`, colando `tree.dirty`, `tree.commits` e o que falta |
-| `report-blocked` + `ask-human` | `BLOQUEADO` na 1ª linha = decisão que não é do agente; a pergunta e as opções estão no relatório. **Não re-despache.** Plano ou ADR já decide → decida e registre; senão `AskUserQuestion`. Retome o MESMO agente com a resposta |
-| `report-incomplete` + `complete-degraded` | complete a partir da mensagem, carimbe DEGRADADO e registre a falha no relatório |
-| `work-landed-report-missing` | não re-despache; grave você o relatório, DEGRADADO |
-| `no-work-no-report` / `report-missing-evidence-unknown` | re-despache uma vez; segunda ausência sem trabalho = escale |
-
-Árvore suja sem explicação ou `tree.markers` não vazio vão ao relatório da fatia.
-
-## 6. Verify da feature, uma vez
-
-Sem fatia pendente nem em voo, **primeiro o contexto** — antes do verify, para que a prova e o Gate 3
-cubram a árvore que vai ao merge. Todo `.morph/context/*.md` que descreve um fato que esta feature
-mudou tem o **corpo** reescrito para o estado novo, nunca empilhado (valor que ainda vale em algum
-lugar diz onde); o changelog do documento guarda só data e motivo. Mudança estrutural
-(`package.json`, `.csproj`, `next.config.*`, `tsconfig.json`, `docker-compose.yml`) atualiza também
-`.morph/context/README.md` (stack, arquitetura, integrações) e `.morph/config/config.json` (stack,
-arquitetura, integrações, paths). **Commite** o trabalho das fatias e essa atualização de contexto e
-config **antes** do verify: o stamp grava o HEAD, e código ou `config.json` commitado depois dele é
-árvore nova — um terceiro verify.
-
-Depois `morph-spec verify {feature} --json`, **sem filtro** — nunca recorte o
-verify da feature. `--filter` é do loop do próprio sub-agente; o Gate 3 e o CI rodam a suíte
-inteira. Nó de teste sem `expectedCount`, ou fatia que apagou teste de propósito (limpeza, `morph-spec tests-audit`): acrescente `--record-baseline` a ESTA rodada — ela mede e
-prova de uma vez; nunca um segundo verify só para gravar a baseline. Vermelho: corrija com `verify.feedback` (direto no código, ou re-despachando a fatia dona)
-e rode de novo; **3 tentativas** sem verde → `AskUserQuestion` ("Verify de {feature} vermelho após 3
-tentativas — aceitar com ressalva, continuar tentando, ou parar?"). Quem conta é o `feature.json`:
-`morph-spec next {feature}` devolve `fix` enquanto há tentativa e `escalate` na 3ª vermelha seguida.
-
-**Cenário que julga saída de LLM** (`prova: eval`): a evidência é rodar, não ler código. Com nó
-`runner: "evals"`: `morph-spec verify {feature} --filter {id-do-nó-evals} --skip-e2e --no-persist`
-(sonda, não prova de gate). Grave `3-implement/evidencias/{Cn}.md`: o cenário literal, o nó, o modelo
-efetivo, a versão ou o hash do prompt (nunca o prompt cru), entrada e saída sem dado pessoal, e o
-veredito com a razão. Não é o `reports/F{n}.md`: aquele diz o que o agente fez; este prova, rodando,
-que a saída atende ao cenário.
-
-## 7. Review
-
-Verify verde: `Skill(morph-review)`. O Gate 3 é apresentado, decidido e aprovado por ela; ao retomar o
-controle, **não re-apresente o gate** — siga para o encerramento conforme `gateDecisions.review`.
-
-## 8. Encerramento
-
-- **Contexto já foi no §6**, antes da prova. Depois do Gate 3 nada muda `config.json` nem código: a
-  árvore integrada é a revisada. Commite na branch da feature o que faltar (relatórios do review) —
-  o `finish` exige a árvore limpa.
-- **Fechar:** `morph-spec finish {feature} --pr|--merge`, modo por `AskUserQuestion` (header
-  `"Integração"`). `--pr` arquiva e abre o PR, mas só o merge integra: a feature fica
-  `aguardando-merge` em `list`/`fleet`.
-
-## Escalada de escopo
+O plano inteiro, nesta sessão, em sequência. Sem sub-agent para implementar: o que você descobre no `C1` (um formato, uma regra, um nome) é o que o `C5` precisa.
+
+- As regras de cada domínio (.NET, EF, MAF, Next.js, infra) chegam sozinhas: a rule do stack carrega quando você toca o arquivo. O texto inteiro de um standard: `morph-spec standards --find` → `--show <id>#<âncora>`.
+- Antes de criar um tipo, confira a tabela `## Reuso` e `morph-spec graph explain <nome>` (sem grafo, `grep -rn`).
+- Rode build e teste quando quiser; teste pesado fora do `verify` por `morph-spec heavy run -- <cmd>`. Exit 3 = fila cheia: uma chamada nova no máximo (`references/machine.md`).
+- Ao fechar um `Cn`, atualize a linha dele no `report.md` (`feito` + a evidência: teste, `arquivo:linha`) e commite (`wip(<f>): C2 …`). Decisão ou fato novo → uma linha em `## Notas`.
+- Mídia gerada por IA: `references/media.md`. Erro difícil: `references/debugging.md`.
+
+`Cn` que depende de uma decisão que não é sua: status `bloqueado` e a pergunta em `## Notas`; o `next` devolve `decide` → `AskUserQuestion`.
 
 | Situação | Caminho |
 |---|---|
-| Acréscimo pequeno dentro da fatia | registre no relatório da fatia — sem gate a revogar |
-| **Fato errado**: o plano afirma algo que o código desmente, sem mudar escopo | bloco `## Errata` no FIM do `plan.md`, corpo intacto, append-only |
-| **O escopo mudou** | `morph-spec unapprove {feature} plan --reason "..."`, emende, `plan-check`, re-aprove |
+| acréscimo pequeno dentro do escopo | `## Notas` do report |
+| fato errado no plano, escopo igual | `## Errata` no fim do `plan.md` (append-only) |
+| escopo mudou | `morph-spec unapprove {feature} plan --reason "…"`, emende, `plan-check`, gate de novo |
 
-Ambiguidade que o plano não cobre não é escalada: resolva pelo lado conservador, registre a decisão sob `## Errata` do `plan.md`
-e siga.
+**Cenário `prova: eval`:** a evidência é rodar. Com nó `runner: "evals"`: `morph-spec verify {feature} --filter <nó> --skip-e2e --no-persist`; grave `3-implement/evidencias/{Cn}.md` (cenário, modelo, hash do prompt, entrada e saída sem dado pessoal, veredito). `prova: manual`: passo e resultado no mesmo lugar.
 
-## Arquivo de teste
+## 3. Verify, sem filtro
 
-1. **Analise primeiro** — a IMPLEMENTAÇÃO está errada ou a ESPECIFICAÇÃO do teste está?
-2. **Corrija a implementação primeiro** — o teste é a especificação; confie nele por padrão.
-3. **Só mude um arquivo de teste se a própria expectativa estiver errada.**
-4. **Antes de mudar, explique POR QUE o teste está errado** — qual é o comportamento certo.
+Todo `Cn` `feito`: `morph-spec context refresh` (regera o inventário em `.morph/context/README.md`; `design-system.md` você atualiza só se mudou token), commite tudo e rode `morph-spec verify {feature} --json` sem filtro: a suíte inteira é a prova que o Gate 3 e o CI leem; com `--filter`, o verde mede só um nó. Passou de 10 min: `run_in_background` e espere a notificação **no mesmo turno**. Nó `node-test`/`evals` sem `expectedCount`, ou teste apagado de propósito: `--record-baseline` nesta mesma rodada.
 
-## Debugging
+Vermelho → corrija com `verify.feedback` e rode de novo. `next` conta: `fix` enquanto há tentativa, `escalate` na 3ª vermelha seguida → `AskUserQuestion` ("Verify de {feature} vermelho após 3 tentativas — aceitar com ressalva, continuar tentando, ou parar?").
 
-Causa raiz antes do conserto: reproduza e leia o erro inteiro; erro conhecido de .NET/Next.js →
-`/morph-troubleshoot <palavras>`; **uma hipótese por vez**, cada uma testada pela menor checagem que
-a refutaria; depois de três consertos falhos, nunca tente um quarto sozinho — `AskUserQuestion`
-com a pergunta de desenho que as falhas levantam; confirme com a mesma checagem que reproduziu.
+## 4. Ramo por tipo
 
-## Anti-padrões
+- **chore:** Gate 3 só com o revisor (`references/review.md`).
+- **hotfix:** `references/hotfix.md` do começo ao fim (diagnóstico, plano curto, `verifier.md` seu, Gate 3 sempre humano).
+
+## 5. Gate 3
+
+Verify verde: siga `references/review.md` — foto `--before-eval`, verificador ∥ revisor (∥ segurança) na mesma resposta, correção dos bloqueadores, confirmação, `gate-check review`. Ao retomar com o gate já decidido, não re-apresente: siga para o §6.
+
+## 6. Fechar
+
+Commite o que faltar (relatórios do review) — o `finish` exige árvore limpa. Modo por `AskUserQuestion` (header "Integração"): `morph-spec finish {feature} --pr|--merge`. `--pr` não integra: a feature fica `aguardando-merge` até o merge. O `finish` arquiva o `feature.json`, o `plan.md` e o recap; o report e a review ficam no histórico do git. Encerrado, aponte o recap ao usuário (`.morph/archive/{feature}/recap.html`, abra no navegador; `morph-spec recap {feature} --piper` narra com o Piper local).
+
+## Arquivo de teste
 
-- Mais de 4 agentes ao mesmo tempo, ou duas fatias em voo no mesmo arquivo sem worktree.
-- Sub-agente tocando `plan.md`, `checks.json` ou `feature.json`.
-- Re-despachar sobre `report-stale` ou sobre um `PARCIAL` (retome o MESMO agente).
-- Rodar teste fora do `verify` no loop do orquestrador: a prova é o verify.
+A implementação está errada ou a expectativa do teste está? Corrija a implementação primeiro — o teste é a especificação. Só mude o teste quando a expectativa estiver errada, e diga por quê nas `## Notas`.

package/framework/skills/core/morph-apply/references/debugging.md

@@ -0,0 +1,8 @@
+# Debugging
+
+Causa raiz antes do conserto.
+
+1. Reproduza e leia o erro inteiro. Erro conhecido de .NET/Next.js → `/morph-troubleshoot <palavras>`.
+2. **Uma hipótese por vez**, cada uma testada pela menor checagem que a refutaria.
+3. Confirme o conserto com a mesma checagem que reproduziu o erro.
+4. Três consertos falhos no mesmo problema: não tente um quarto sozinho — `AskUserQuestion` com a pergunta de desenho que as falhas levantaram.

package/framework/skills/core/morph-apply/references/hotfix.md

@@ -0,0 +1,42 @@
+# Hotfix
+
+Queda ou bug crítico de produção. Prioridade é velocidade, com aprovação humana obrigatória antes do ship.
+
+## 1. Nascimento
+
+`morph-spec create {feature} --type hotfix --description "<o que quebrou / sintoma>"` — nasce com o gate `plan` carimbado por política, já em `implement`. Já existe: siga.
+
+## 2. Diagnóstico
+
+Você mesmo, antes de qualquer fix: o sintoma → o caminho no código (`morph-spec graph affected <símbolo> --prod --json`; sem grafo, `grep -rn`) → causa provável → blast radius (o que mais passa pelo trecho que vai mudar). Cite `arquivo:linha` só do que você abriu: sob pressão, citação inventada vira um segundo incidente.
+
+## 3. Plano curto (uma escrita só — o arquivo congela ao nascer)
+
+`2-plan/plan.md`, ~20 linhas:
+
+- `## Problema` — sintoma, causa, blast radius.
+- `## Cenários`:
+  - **C1** — o sintoma ausente: dado o estado que quebrava, quando a ação que falhava, então o resultado certo. `prova: teste` (ou `e2e`) e `risco: regressão` — o único teste novo do hotfix.
+  - **C2** — o blast radius continua funcionando. `prova: leitura` (`arquivo:linha`) ou um teste existente que já o cobre.
+- `## Decisões` com `### Conflitos com o acervo` (`nenhum` vale).
+
+`morph-spec plan-check {feature}` até zero erro.
+
+## 4. Fix e prova
+
+A mudança mínima que tira a falha do ar — refatoração e hardening fora do sintoma ficam para outra feature. `report.md` com C1/C2. `morph-spec verify {feature} --json` sem filtro; C1 se prova com o sintoma reproduzido antes e ausente depois — cole a saída real.
+
+## 5. Gate 3 — sempre humano
+
+Escreva você `4-review/verifier.md`: `**Verdict:** SHIP|FIX`, `**Reviewed-SHA:** {git rev-parse HEAD}`, `## Checks` (`| Cn | PROVADO|NÃO PROVADO|FALHA | evidência |`, evidência = saída do verify), `## Bloqueadores` (`Nenhum.` vale). `morph-spec gate-check {feature} review` pausa sempre. `AskUserQuestion`, header "Gate 3":
+
+```
+question: "Gate 3 — Hotfix de {feature} pronto para ship?"
+options: "aprovado, ship" | "preciso ajustar" | "rollback"
+```
+
+**Nunca** `approve {feature} review --mode auto` (o CLI recusa). Headless: `morph-spec approve {feature} review --approver "<quem aprovou>"` — só com aprovação humana real; nunca invente o nome.
+
+## 6. Pós-gate
+
+Código mudou depois do verify → verify de novo. `morph-spec finish {feature} --pr|--merge`, modo escolhido pelo usuário; `--merge` integra na hora, `--pr` não — o incidente só está resolvido depois do merge.

package/framework/skills/core/morph-apply/references/machine.md

@@ -0,0 +1,29 @@
+# Máquina: RAM, fila e processos
+
+Para manter a máquina utilizável enquanto você compila e testa. Aplique quando o sintoma aparecer; o usuário não precisa pedir.
+
+## Regras que não se negociam
+
+- **Nunca** `taskkill /IM`, `pkill`, `killall` nem `Stop-Process -Name`: derrubam os MCPs de todas as sessões abertas. O único que encerra processo é `doctor --procs --prune`, e por PID.
+- **Fila cheia não é erro de código.** `⏳ … não rodou`, `slots pesados ocupados` e exit 3 querem dizer que a fila já esperou o prazo dela (`heavy.waitTimeoutSec`). Não entra no loop de correção, não conta como tentativa e não é vermelho no `verify`. No máximo uma chamada nova; persistiu, siga sem aquela rodada e avise o usuário — nunca `sleep`/`until` nem retentativa agendada.
+- **Nunca remova worktree** por `git worktree remove`, `rm -rf` ou `Remove-Item -Recurse`: atravessa a junction e apaga o conteúdo real da raiz. Só `finish` ou `worktree remove`.
+- **Destrutivo pergunta antes.** `doctor --procs --prune`: mostre a lista e use `AskUserQuestion`.
+
+## Sintoma → comando
+
+| Sintoma | Comando | Como ler e o que fazer |
+|---|---|---|
+| Máquina ou editor lento, pouca RAM | `morph-spec doctor --procs` (só lê) | Cada linha diz órfão ou protegido, com a razão. Sem órfão, a pressão vem de fora (vmmem do WSL, IDE): diga isso e passe a sugestão de `.wslconfig` que o relatório traz. Com órfão, mostre a lista e ofereça `--prune`. |
+| Comando voltou `⏳ … não rodou` ou exit 3 | `morph-spec heavy status` | Mostra quem segura cada vaga, há quanto tempo, e a RAM livre. A vaga solta sozinha (processo morto ou timeout). Vaga presa por sessão viva: diga ao usuário quem a segura. Se a causa for RAM e nenhuma vaga estiver presa, rode `doctor --procs`. |
+| Várias features abertas, uma por worktree, testando ao mesmo tempo | nada: a fila resolve | São 2 vagas por padrão; o que não couber espera. Se a espera virar recusa toda hora, `heavy.slots` sobe quando houver RAM. |
+| Worktree sobrando ou fora do contêiner | `morph-spec doctor --worktrees` | Lista cada árvore com a razão; remova só por `worktree remove`. |
+| A worktree precisa de arquivo fora do git (`.env`, segredos) | `.worktreeinclude` na raiz do repo | Um padrão por linha, sintaxe do gitignore. Copia só o que casa **e** é ignorado; nunca `node_modules`, build ou `.git`. O `setup` e o `provision` aplicam. |
+| Editor pesado por causa das worktrees | `worktree.root` em `.morph/config/config.json` | Põe as worktrees fora da árvore aberta (caminho absoluto fora do projeto). `init` e `update` já gravam as exclusões no `.vscode/settings.json`. |
+
+## A fila pega o seu build e o seu teste
+
+`heavy.gateBash` vem ligado: antes de `dotnet build|test`, `npm test`, `vitest`, `docker compose up` e afins, um hook toma uma vaga da fila e a devolve depois. Sem vaga no prazo, a chamada é recusada com a causa: rode o mesmo comando de novo uma vez, ou siga sem ele. Projeto que prefere sem a fila: `"heavy": { "gateBash": false }` em `.morph/config/config.json` (pergunte ao usuário antes).
+
+Limites: não cobre `run_in_background`, PowerShell nem comando fora da lista; uma chamada negada por regra ou interrompida segura a vaga até o timeout dela.
+
+Referências: `.morph/framework/CLI.md` — `### heavy`, `### doctor --procs` e `### worktree.root`; MORPH.md §2.2 (worktrees).

package/framework/skills/core/{morph-media/SKILL.md → morph-apply/references/media.md}

@@ -1,17 +1,4 @@
----
-name: morph-media
-description: Conduz a AUTORIA de mídia gerada por IA — escolher o modelo pelo trabalho, montar o prompt como spec versionada, encadear derivadas a partir de um herói aprovado, subir a escada de custo e conduzir o gate humano de escolha entre N candidatas. É o lado processo; o conhecimento de API, custo e conformidade vive nos standards de mídia.
-version: core
-when_to_use: Use quando a tarefa for PRODUZIR imagem ou vídeo por IA (catálogo, marketing, asset de LP) e alguém precisar decidir modelo, prompt e aprovação
-user-invocable: true
-cliVersion: "9.7.0"
-stacks:
-  - dotnet
-  - nextjs
----
-
-# morph-media
-
+# Mídia gerada por IA
 ## Objetivo
 
 Conduzir a **autoria** de mídia gerada: a sequência de decisões humanas que vai de "precisamos de
@@ -66,65 +53,17 @@ Uma pergunta decide quase tudo: **existe um produto real a preservar?**
 desligado não é preferência de estilo: é uma chamada que devolve erro depois de você ter escrito o
 código inteiro em cima dela.
 
-## Passo 2 — Montar o prompt como spec versionada
-
-Prompt de produção é **template versionado**, nunca string concatenada. A ordem importa, e as duas
-famílias de modelo concordam nela:
-
-```
-cena/fundo → sujeito → detalhes-chave → restrições
-```
-
-Seis regras que mudam o resultado mais do que qualquer outra coisa:
-
-1. **Descreva em prosa, não em lista de keywords.** "beautiful, stunning, 4k, masterpiece" adiciona
-   ruído, não qualidade. Briefe como se briefasse um fotógrafo.
-2. **Seja hiper-específico no sujeito.** "armadura de fantasia" produz genérico; "armadura élfica de
-   placas prateadas, gravada com folhas, gola alta, ombreiras em asa de falcão" produz uma imagem.
-3. **Descreva em camadas** — primeiro plano, plano médio, fundo. Descrição plana produz imagem
-   plana; camadas produzem profundidade.
-4. **Iluminação é a maior alavanca isolada de qualidade.** Sempre declare, com termos de fotografia,
-   e prefira **múltiplas fontes** com direções e temperaturas diferentes. Luz única e frontal é o
-   que faz uma imagem parecer amadora.
-5. **Enquadre positivamente.** "rua deserta, completamente parada" funciona; "rua sem carros" não —
-   o modelo lida mal com negação.
-6. **Contexto e finalidade entram no prompt.** "logo para uma marca de skincare minimalista premium"
-   decide melhor que "faça um logo".
+## Passos 2 a 4 — Prompt, edição e encadeamento
 
-**Texto na imagem:** cite literalmente entre aspas e soletre marcas. Erro de grafia é o defeito mais
-comum dessa categoria — **confira lendo a imagem gerada** e corrija com uma edição pontual ("corrija
-a grafia para 'X' exatamente; mantenha o resto"). Duas ou três iterações são normais.
+O ofício mora no standard de imagem; abra só a seção do passo (`morph-spec standards --show <id>#<âncora>`):
 
-**Aspect ratio é decisão, não default.** Escolha pelo destino final (feed, story, banner, impressão).
-
-## Passo 3 — Editar é o oposto de gerar
-
-| | Gerar | Editar |
-|---|---|---|
-| Estratégia | **Profundidade** — composição em camadas, texturas, luz dramática | **Contenção** — 1 a 2 frases, exatamente o que muda |
-| Erro típico | Prompt raso → imagem plana e genérica | Prompt longo → o modelo "re-imagina" tudo e o resultado fica artificial |
-
-Padrões de edição que funcionam:
-
-- **Acrescentar/remover:** uma frase. Não explique como integrar — o modelo faz isso bem quando você
-  não o sufoca.
-- **Trocar o fundo:** diga o fundo novo e pare. Ele casa a iluminação sozinho.
-- **Inpaint:** nomeie o que muda e o que fica. *"Troque o sofá azul por um chesterfield de couro
-  marrom. Mantenha o resto."*
-- **"Preserve list" repetida em CADA iteração.** É o que impede o drift de acumular.
-- **Uma mudança por vez.** Refinamentos em série, nunca em bloco.
-- **Ao driftar, recomece** com a descrição completa em vez de empilhar correções.
-
-## Passo 4 — Encadear a partir de um herói aprovado
-
-A consistência não vem do prompt; vem da **referência**.
-
-1. Gere e **aprove** o herói primeiro — a imagem que define paleta, luz e enquadramento.
-2. Use o herói aprovado como **referência** das derivadas. Nunca gere as derivadas em paralelo com o
-   herói: elas herdam o erro que ainda não foi visto.
-3. Indexe cada referência no prompt ("image 1 = o sofá; image 2 = o tecido") e diga como interagem.
-4. Imagens que vão virar vídeo são enquadradas **sem rosto** — rosto derruba moderação, e o contorno
-   está em `ai-video-generation.md` §Section 3.
+| Passo | Seção |
+|---|---|
+| Prompt como spec versionada: prosa, sujeito específico, camadas, luz, enquadrar no positivo, contexto | `frontend-design-system-ai-image-generation#narrative-style`, `#prompting-principles`, `#category-templates` |
+| Texto dentro da imagem e proporção pelo destino | `#text-rendering`, `#aspect-ratio-guide` |
+| Editar é o oposto de gerar (contenção, preserve list, uma mudança por vez) | `#iterative-editing-workflows` |
+| Herói aprovado primeiro, derivadas por referência, várias referências | `#chain-from-an-approved-hero`, `#multi-image-composition` |
+| Imagem que vira vídeo (sem rosto) | `#downstream-images-that-become-video` |
 
 **O que a IA nunca recria:** render arquitetônico do cliente e foto real de produto. Esses são
 animados ou editados a partir do arquivo real — recriá-los é inventar o que o cliente já tem.
@@ -210,6 +149,4 @@ trabalho de design". Tratar a saída como entregável vetorial é o erro clássi
 
 ## Referências
 
-- Os cinco standards da tabela do topo — a fonte de API, custo, prazo e conformidade.
-- Proveniência do conhecimento absorvido: `.morph/framework/standards/PROVENANCE.json`
-  (`morph-image`, `cinematic-lp`, `brand-design`).
+Os cinco standards da tabela do topo: a fonte de API, custo, prazo, conformidade e do ofício do prompt.