@polymorphism-tech/morph-spec 9.5.0 → 9.7.0

package/framework/schemas/config.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "MORPH-SPEC .morph/config/config.json",
-  "description": "Describes project.tests[] — the plural declaration of the project's test suites — and finishBackup.retention. Everything else in config.json is deliberately left open (additionalProperties: true) so that configs already in the field never break on a key this schema has not heard of. The authorities at runtime are validateTestNodes() in src/lib/tasks/test-nodes.js and resolveBackupRetention() in src/lib/worktree/finish-backup.js: a schema nothing calls is decoration.",
+  "description": "Describes project.tests[] — the plural declaration of the project's test suites —, e2e.hostServices and finishBackup.retention. Everything else in config.json is deliberately left open (additionalProperties: true) so that configs already in the field never break on a key this schema has not heard of. The authorities at runtime are validateTestNodes() in src/lib/tasks/test-nodes.js and resolveBackupRetention() in src/lib/worktree/finish-backup.js: a schema nothing calls is decoration.",
   "type": "object",
   "additionalProperties": true,
   "properties": {
@@ -119,6 +119,58 @@
         }
       }
     },
+    "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.",
+      "properties": {
+        "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.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "start"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9._-]+$",
+                "description": "Unique in the array. Names the log file (<git-common-dir>/morph-spec/e2e-host-<project>-<name>.log) and every message about the service."
+              },
+              "cwd": {
+                "type": "string",
+                "default": ".",
+                "description": "Working directory of build and start, relative to the project root. One that does not exist refuses."
+              },
+              "build": {
+                "type": "string",
+                "description": "Runs before start; a non-zero exit fails the bring-up."
+              },
+              "start": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The process, started detached; its output goes to the service log."
+              },
+              "env": {
+                "type": "object",
+                "additionalProperties": { "type": ["string", "number"] },
+                "description": "Added on top of process.env and the stack env (port block + e2e.auth.envFile). ${VAR} is resolved from the stack env, then process.env; a VAR with no value (or an empty one) refuses before any build, naming the variable and the service."
+              },
+              "health": {
+                "type": "string",
+                "description": "URL polled until it answers with an HTTP status below 500. ${VAR} interpolates like env. Without it, a process still alive 2 s after start counts as ready."
+              },
+              "timeoutMs": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 180000,
+                "description": "Ceiling for build + start + health together."
+              }
+            }
+          }
+        }
+      }
+    },
     "finishBackup": {
       "type": "object",
       "additionalProperties": true,
@@ -179,7 +231,18 @@
           "type": "number",
           "minimum": 0,
           "default": 4,
-          "description": "Free RAM (os.freemem) below which a heavy node WAITS instead of starting and dying 'killed' for memory. It waits with or without a slot holder - the pressure often comes from outside (WSL vmmem, the IDE). 0 disables the check."
+          "description": "Free RAM (os.freemem) below which a heavy node WAITS instead of starting and dying 'killed' for memory. It waits with or without a slot holder - the pressure often comes from outside (WSL vmmem, the IDE). 0 disables the check. Since the per-kind floors exist it is the fallback: set explicitly, it applies to every kind not listed in minFreeMemGbByKind (so 0 still turns the check off everywhere)."
+        },
+        "minFreeMemGbByKind": {
+          "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.",
+          "properties": {
+            "unit": { "type": "number", "minimum": 0 },
+            "build": { "type": "number", "minimum": 0 },
+            "e2e": { "type": "number", "minimum": 0 }
+          }
         },
         "waitTimeoutSec": {
           "type": "number",

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.5.0"
+cliVersion: "9.7.0"
 stacks:
   - umbraco
 ---

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

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when_to_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.5.0"
+cliVersion: "9.7.0"
 stacks:
   - umbraco
 ---

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

@@ -4,7 +4,7 @@ description: Executa as fatias do plano de uma feature morph-spec — dispatch p
 version: core
 when_to_use: Use com o gate do plano aprovado, em "use /morph-apply {feature}" ou "implementar feature"
 user-invocable: true
-cliVersion: "9.5.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-apply

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

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when_to_use: Use quando chegar "/morph-hotfix {feature}", quando a morph-plan rotear o pedido como workType hotfix, ou quando o usuário disser "produção caiu / hotfix / urgente" a respeito de um incidente
 user-invocable: true
-cliVersion: "9.5.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-hotfix

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

@@ -4,7 +4,7 @@ description: Cuida da RAM e da CPU da máquina enquanto o morph-spec trabalha
 version: core
 when_to_use: Use quando a máquina estiver lenta ou sem RAM, um comando pesado esperou ou foi recusado pela fila, sobrou worktree de sub-agent, ou vários sub-agents pesados vão rodar em paralelo
 user-invocable: false
-cliVersion: "9.5.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-machine

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

@@ -4,7 +4,7 @@ description: Conduz a AUTORIA de mídia gerada por IA — escolher o modelo pelo
 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.5.0"
+cliVersion: "9.7.0"
 stacks:
   - dotnet
   - nextjs

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

@@ -4,7 +4,7 @@ description: Leva uma feature do pedido ao plano aprovado — roteia o tipo de t
 version: core
 when_to_use: Use quando uma feature, bug ou chore começar ("/morph-plan {feature}", "vamos planejar X"), ou ao retomar uma feature cujo gate plan ainda não foi aprovado
 user-invocable: true
-cliVersion: "9.5.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-plan
@@ -71,7 +71,7 @@ O `create` já escreveu o esqueleto em `2-plan/plan.md` (leia e preencha; `chore
 - **Observável**: que asserção (ou que linha de código) prova? Sem resposta, reescreva ou descarte.
 - **Artefato não é comportamento.** Cenário que cita `grep`, "contém a string", "o binário", "nenhum arquivo", "arquivo/pasta/diretório em" ou glob `**/` descreve o repositório. Tente o efeito em runtime; se o artefato É o entregável, justifique em `> Por que artefato:` logo abaixo (nunca na mesma linha, nunca `> [!note]`).
 - **Saída de LLM** (o que o modelo responde) prova-se por `eval` de runtime, nunca pelo texto do prompt: evidência em `3-implement/evidencias/{Cn}.md`, path listado em `arquivos:` da fatia; com nó `runner: "evals"` (standard `ai-agents-evals-with-cache`) o cenário mora no dataset. No máximo 1 teste de estrutura da fonte do prompt.
-- **"O comando de teste da raiz roda de ponta a ponta"** prova-se pelo `verify {feature}` (o nó `e2e` e o nó de teste `e2e: true` já percorrem a cadeia): nomeie essa rodada como a prova, nunca uma execução avulsa. Precisando mesmo rodar fora dele, numa linha só (o Bash não guarda o env entre chamadas): `eval "$(morph-spec env {feature})" && morph-spec heavy run -- <comando>` — o `COMPOSE_PROJECT_NAME` da feature é o que o `finish` derruba com os volumes. `prova: manual` registra passo e resultado em `3-implement/evidencias/{Cn}.md`.
+- **"O comando de teste da raiz roda de ponta a ponta"** prova-se pelo `verify {feature}` (o nó `e2e` e o nó de teste `e2e: true` já percorrem a cadeia): nomeie essa rodada como a prova, nunca uma execução avulsa. Precisando mesmo rodar fora dele, numa linha só (o Bash não guarda o env entre chamadas): `eval "$(morph-spec env {feature} --with-secrets)" && morph-spec heavy run -- <comando>` — o `COMPOSE_PROJECT_NAME` da feature é o que o `finish` derruba com os volumes. `prova: manual` registra passo e resultado em `3-implement/evidencias/{Cn}.md`.
 - **Orçamento de teste**: um teste por cenário de risco — o cenário é a unidade, nunca a pós-condição nem o componente; variantes são linhas de tabela (`[Theory]`/`it.each`); acima disso, o porquê na linha do cenário. Nenhum teste que só fixa texto, prompt ou constante, nenhum de DTO/mapping, e o mesmo comportamento numa camada só (handler **ou** endpoint). Teste além do orçamento é escopo para o revisor. O `verify` avisa quando o teste passa da produção.
 
 ```markdown
@@ -105,7 +105,7 @@ O `create` já escreveu o esqueleto em `2-plan/plan.md` (leia e preencha; `chore
 - Cenário que se observa por um artefato de outra fatia (rota, endpoint, componente que ela cria) faz da fatia que o cobre um `depende:` daquela — senão as duas caem na mesma onda e o teste do cenário não tem por onde provar. O `plan-check` não vê de quem é a rota: a regra é sua.
 
 **Contrato de implementação**: o que quem implementa precisa e o código não diz.
-- **Verificação de runtime:** o stack sobe por `morph-spec e2e up {feature}` (compose do projeto; sem compose, isso é uma fatia); os fluxos que o verificador navega, nos verbos dos cenários; base URL `process.env.PLAYWRIGHT_BASE_URL ?? \`http://localhost:${process.env.PORT ?? 3000}\``, compose com `"${PORT:-3000}:3000"` e sem `container_name` (standard `infrastructure/docker/local-compose-isolation`). App com login: `e2e.auth` em `config.json` (`mode: seed|storageState|bypass|none`, `seedCommand`, `storageStatePath`, `envFile`), credenciais num `.env.e2e` gitignored — **`mode` é obrigatório sempre que houver `seedCommand`**, sem ele o seed fica inerte. Biblioteca pura: registre a dispensa e o porquê.
+- **Verificação de runtime:** o stack sobe por `morph-spec e2e up {feature}` (compose do projeto; sem compose, isso é uma fatia); os fluxos que o verificador navega, nos verbos dos cenários; base URL `process.env.PLAYWRIGHT_BASE_URL ?? \`http://localhost:${process.env.PORT ?? 3000}\``, compose com `"${PORT:-3000}:3000"` e sem `container_name` (standard `infrastructure/docker/local-compose-isolation`). App cujo build é caro dentro do Docker sobe como processo do host por `e2e.hostServices` (compose só com as dependências; campos em `morph-spec e2e --help`). App com login: `e2e.auth` em `config.json` (`mode: seed|storageState|bypass|none`, `seedCommand`, `storageStatePath`, `envFile`), credenciais num `.env.e2e` gitignored — **`mode` é obrigatório sempre que houver `seedCommand`**, sem ele o seed fica inerte. Biblioteca pura: registre a dispensa e o porquê.
 - **Baseline é um COMANDO, nunca um número.** O plano congela e é lido por dias: um número cravado está errado na primeira fatia, e quem confia nele "conserta" o que não quebrou. Registre como medir (`npm test`, `dotnet test`); o `expectedCount` sai de `morph-spec verify {feature} --record-baseline`, nunca digitado. Sem `project.stack`/`project.tests` no `config.json`, a `morph-apply` os declara a partir destes comandos antes do primeiro verify.
 - **Pré-requisito é um PREDICADO, nunca um SHA literal:** "`git merge-base --is-ancestor origin/main HEAD` sai 0" — o SHA muda no primeiro squash.
 

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

@@ -4,7 +4,7 @@ description: Conduz o Gate 3 — despacha verificador ∥ revisor (∥ seguranç
 version: core
 when_to_use: Use quando a fase review começar, com todas as fatias com relatório final e o verify da feature verde
 user-invocable: true
-cliVersion: "9.5.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-review
@@ -51,7 +51,8 @@ símbolo público do diff, `morph-spec graph affected <símbolo> --prod --json`;
 (`no-graph`/`not-found`/`ambiguous`), siga sem o blast radius — o revisor cai para `git grep` — e
 registre a ausência no recado a ele. Cada agente nasce com contexto fresco e **nunca recebe relatório anterior** (ancoragem).
 `chore` tem review leve: só o revisor (∥ segurança, quando exigida) — sem verificador, sem cobertura de
-`Cn`, sem mutação. Despache todos na mesma resposta:
+`Cn`, sem mutação. Despache todos na mesma resposta, **sem nome no dispatch**: com nome, o `agent_type` que o hook
+`test-budget` lê vira o nome, e o guard de review não reconhece o papel.
 ```
 dispatch Agent (subagent_type: "morph-verifier", model: {reviewModels.verifier.model}) with prompt:
   feature, base, sha, JSON do verify (nós, e2e, URL) se já terminou, 1-design/mockups.md e

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

@@ -4,7 +4,7 @@ description: Localiza um standard específico via busca server-side (morph-spec
 version: core
 when_to_use: Use quando precisar consultar um standard específico durante a implementação
 user-invocable: true
-cliVersion: "9.5.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-standards

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

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX de uma feature com plano aprovado
 version: core
 when_to_use: Use quando o ramo de design for tomado (morph-spec advance {feature} --design, depois do gate do plano) e antes de /morph-apply
 user-invocable: true
-cliVersion: "9.5.0"
+cliVersion: "9.7.0"
 ---
 
 # morph-uiux

package/framework/standards/STANDARDS.json

@@ -1629,9 +1629,10 @@
         "portNames": "#project-named-port-variables",
         "rules": "#core-rules",
         "enforcement": "#what-the-harness-enforces",
+        "hostServices": "#services-on-the-host",
         "skeleton": "#minimal-compose-skeleton"
       },
-      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish tears down with volumes (--keep-volumes opts out). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env. A compose that reads a port by ANOTHER name (PG_PORT) is not fed by the block: declare it in config.json e2e.portEnvNames ({\"postgres\": \"PG_PORT\"}) and the harness exports it with the same value in worktree.env, the compose env and the hook."
+      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish/delete tear down with --rmi local -v (--keep-volumes drops -v on finish); worktree remove of a morph-task/* branch with -v, of morph/{f} without. An app whose build is expensive in the Docker VM runs as a host process via e2e.hostServices (compose keeps only the dependencies; ports from the block). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env. A compose that reads a port by ANOTHER name (PG_PORT) is not fed by the block: declare it in config.json e2e.portEnvNames ({\"postgres\": \"PG_PORT\"}) and the harness exports it with the same value in worktree.env, the compose env and the hook."
     },
     {
       "id": "infrastructure-neon-pgrag",

package/framework/standards/infrastructure/docker/local-compose-isolation.md

@@ -51,10 +51,23 @@ Keys are `web`, `api`, `postgres` and `redis`. Each declared name carries the **
 ## What the harness enforces
 
 - Inside a secondary worktree, a compose with a fixed host port or a `container_name` **fails the `verify` e2e node** (`compose-not-isolable`) — Gate 3 cannot pass on a stack that cannot run beside its siblings. At the primary root the same finding is a warning.
-- `morph-spec finish` tears the stack down **with volumes** (`--keep-volumes` opts out) and deletes the freshness stamp; `morph-spec worktree remove` tears it down without volumes (the feature is still open).
+- `morph-spec finish` and `morph-spec delete` tear the stack down with `down --remove-orphans --rmi local -v` (`--keep-volumes` on `finish` drops the `-v`) and delete the freshness stamp. `--rmi local` removes only the images compose built, never a pulled one (`postgres`) that the next feature would download again; `docker builder prune` never runs, because the build cache is global to the machine. `morph-spec worktree remove` (and `worktree reap`, which goes through it) tears down a `morph/{f}` branch without volumes (the feature is still open) and a `morph-task/*` branch with `-v` (the task is disposable). Every one of these also stops the `e2e.hostServices` processes.
 - Two worktrees never share `POSTGRES_PORT`: the block is allocated first-free-index per feature and released only when the worktree is removed.
 - The credentials env file is read **after** the block but cannot outrank it. All four surfaces (`e2e up`, the `verify` e2e node, the teardown, `morph-spec env`) build their environment through the same `buildComposeEnv`, which drops the layout keys coming from that file and names them on **stderr** — stdout stays eval-safe for `eval "$(morph-spec env)"`. With no block allocated (outside a worktree) nothing is filtered: there the file is the only port source.
 
+## Services on the host
+
+When building an app inside the Docker VM is expensive (a `dotnet publish` or `next build` repeating the build the `verify` already did on the host), run it as a host process through `config.json → e2e.hostServices` and keep only the dependencies (postgres, redis) in compose. The app listens on the ports of the worktree block — `${API_PORT}` / `${PORT}` in its `env` and `health` — so two worktrees still never collide.
+
+```json
+"e2e": { "hostServices": [
+  { "name": "web", "build": "npm run build", "start": "node .next/standalone/server.js",
+    "env": { "PORT": "${PORT}" }, "health": "http://localhost:${PORT}/" }
+] }
+```
+
+`e2e up` and the `verify` e2e node run `compose up --wait`, then each host service in array order (build → start → health), then the auth seed. They stay up until `e2e down`, `finish`, `delete` or `worktree remove`. Fields, reuse and failure rules: `morph-spec e2e --help` and the `e2e` section of `.morph/framework/CLI.md`.
+
 ## Minimal compose skeleton
 
 ```yaml
@@ -96,5 +109,6 @@ volumes:
 ```bash
 # inside the worktree, outside Claude Code
 eval "$(morph-spec env)"        # PowerShell: morph-spec env --powershell | Invoke-Expression
+                                # --with-secrets also loads the e2e.auth.envFile credentials
 docker compose up -d --wait     # lands in project morph-{feature}, on the block's ports
 ```