@polymorphism-tech/morph-spec 8.21.0 → 8.22.0

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 8.21.0  
+**Version:** 8.22.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -368,4 +368,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.21.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.22.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -50,6 +50,7 @@ import { dagCommand } from '../src/commands/tasks/dag.js';
 import { validateCommand } from './validate.js';
 import { validateFeatureCommand } from '../src/commands/validation/validate-feature.js';
 import { verifyCommand } from '../src/commands/validation/verify.js';
+import { e2eUpCommand, e2eStatusCommand, e2eDownCommand } from '../src/commands/e2e/e2e.js';
 
 // === Scaffolding ===
 import { scaffoldDotnetCommand, scaffoldNextjsCommand } from '../src/commands/scaffold/scaffold.js';
@@ -293,12 +294,14 @@ program
 
 program
   .command('verify <feature> [task]')
-  .description('Run the deterministic verification chain (build + tests + validators) — code before the LLM judge')
+  .description('Run the deterministic verification chain (build + tests + validators + e2e) — code before the LLM judge')
   .option('--json', 'Output as JSON')
   .option('--rubric <id>', 'Force a rubric (default: by task group → config → default)')
   .option('--timeout <ms>', 'Build timeout in ms (default 120000)', (v) => parseInt(v, 10))
   .option('--skip-tests', 'Skip the test node')
   .option('--skip-build', 'Skip the build node')
+  .option('--skip-e2e', 'Skip the e2e node (Docker bring-up + Playwright)')
+  .option('--fresh-e2e', 'Rebuild the e2e stack instead of reusing a warm one')
   .option('--no-persist', 'Do not persist the result to feature.json')
   .action((feature, task, options) =>
     verifyCommand(feature, task, { ...options, noPersist: options.persist === false })
@@ -351,6 +354,31 @@ contextCommand
   .option('--json', 'Output scan result as JSON')
   .action((options) => contextRefreshCommand(options));
 
+// ─── E2E stack (Docker bring-up for runtime verification) ─────────────────
+const e2eCommand = program
+  .command('e2e')
+  .description("Lifecycle of the feature's verification stack (docker compose)");
+
+e2eCommand
+  .command('up <feature>')
+  .description('Bring the stack up (reusing a warm one when it still matches the working tree)')
+  .option('--fresh', 'Rebuild instead of reusing a warm stack')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => e2eUpCommand(feature, options));
+
+e2eCommand
+  .command('status <feature>')
+  .description('Is the stack up, healthy, and built from the current source? Exit 0 only if all three')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => e2eStatusCommand(feature, options));
+
+e2eCommand
+  .command('down <feature>')
+  .description('Tear the stack down (best-effort — never blocks)')
+  .option('--volumes', 'Also remove named volumes')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => e2eDownCommand(feature, options));
+
 // ─── Worktree (optional, isolation) ───────────────────────────────────────
 const worktreeCommand = program
   .command('worktree')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.21.0",
+  "version": "8.22.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

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

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.21.0 by Polymorphism Tech*
+*morph-spec v8.22.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -65,7 +65,8 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 | `fleet` | Visão agregada de toda feature ativa (raiz + worktrees) |
 | `claim [f] [--release] [--list]` | Posse advisory — confirme antes de `finish`/`archive`/`delete` se outra sessão tiver claim vivo |
 | `dag <f>` | DAG de `tasks.json`: sequencial/paralelo, recomenda isolamento |
-| `verify <f> [task] [--json]` | Build+testes+validadores, antes do juiz LLM |
+| `verify <f> [task] [--json]` | Build+testes+validadores+e2e, antes do juiz LLM |
+| `e2e up\|status\|down <f>` | Stack de verificação (docker compose) |
 | `doctor --worktrees [--prune]` | Reconcilia git × disco × features; só `--prune` remove algo |
 | `report-check <f> [task] [--json]` | Audita relatório de sub-agent vs. trabalho entregue |
 | `telemetry [--feature] [--limit]` | Caminho de execução da sessão a partir de `events.jsonl` |

package/framework/MORPH.md

@@ -148,7 +148,7 @@ Não invente caminhos alternativos.
 
 - `spec.md` — especificação técnica: arquitetura, componentes, integrações, fluxos de dados, edge cases **técnicos**. Responde **como** os use cases serão realizados — não repete o comportamento. Deve bastar para implementar sem perguntas básicas: tecnologia listada sem explicar como os componentes se conectam é um spec.md fraco.
 
-- `mandate.md` — contrato de implementação: stack exata, standards obrigatórios (com links), patterns proibidos, checklist de done verificável. Lido no início de cada task — específico o bastante para resolver ambiguidades sem consultar o Orchestrator.
+- `mandate.md` — contrato de implementação: stack exata, standards obrigatórios (com links), patterns proibidos, **verificação de runtime** (como o stack sobe, que fluxos são exercitados, quais viram spec Playwright, setup de auth) e checklist de done verificável. Lido no início de cada task — específico o bastante para resolver ambiguidades sem consultar o Orchestrator.
 
 - `tasks.json` — validada contra `framework/schemas/tasks.schema.json`. Cada task: `id` (T1, T2...), `title`, `description`, `dependencies` (IDs), `effort` (S/M/L/XL), `doneCriteria`, `status` (pending/in_progress/done/skipped/blocked), `outputs` (paths esperados), `usecase` (opcional — **ID** do use case, `UC-07`, nunca o nome do arquivo). `doneCriteria` de task com `usecase` carrega a **pós-condição literal**, com rótulo (`"P2 — cada veterinário traz..."`). Toda entrada do recap.md referencia um ID do tasks.json.
 
@@ -218,6 +218,8 @@ Gates são pontos de **pausa potencial**. Em `trust: "auto"` (default), auto-pas
 | `designSystemDivergence` | true | Brainstorming detecta fontes conflitantes (spec antigo vs bundle local) |
 | `standardsViolations` | array.length > 0 | Mandate ou implementation viola padrões proibidos |
 | `evalScore` | < 9 | score composto da feature (via morph-review) abaixo do mínimo |
+| `verificationStatus` | === 'fail' | `morph-spec verify` vermelho — build, testes, validadores **ou e2e** (a app não sobe / as specs não passam). Vale em **qualquer** gate |
+| `verificationStale` | true | Stamp do `verify` com sha != HEAD: o verde não cobre mais o código. Só no **ship** (Gate 3) |
 | `taskCount` | > 20 | Escopo grande — provavelmente vale revisar antes de implementar |
 | `workType` | === 'hotfix' | Gate 3 pausa SEMPRE (detalhe abaixo, "Gates por tipo de trabalho") |
 
@@ -225,7 +227,9 @@ Gates são pontos de **pausa potencial**. Em `trust: "auto"` (default), auto-pas
 | ------ | -------- | -------------------- |
 | 1 — Proposta | `designSystemDivergence`, `standardsViolations` (improvável) | `morph-brainstorming` |
 | 2 — Plano | Gate 1 + `taskCount`, `standardsViolations` em mandate | `morph-plan` |
-| 3 — Review | `evalScore` composite, `standardsViolations` em implementation | `morph-review` |
+| 3 — Review | `evalScore` composite, `standardsViolations` em implementation, `verificationStale` | `morph-review` |
+
+`verificationStatus` não está numa linha só porque vale em todas — verify vermelho pausa qualquer gate.
 
 **Gates por tipo de trabalho:** `chore`/`hotfix` pulam Gates 1 e 2 — carimbados por política no nascimento (`approvedBy: "policy:{tipo}"`, nunca `"auto"`, para não colidir com o gate-guard); a barra do morph-eval e o Gate 3 valem para todos os tipos. `hotfix`: Gate 3 **sempre humano** (mesmo em `trust: auto` — `morph-hotfix` pausa via `AskUserQuestion`, o `risk-detector` força, o backstop server-side recusa `approve ... review --mode auto`) e exige `4-review/review-report.md` em vez de `evaluator-report.md`. Demais tipos exigem `evaluator-report.md`, **enforced server-side** (`morph-spec approve {feature} review` recusa exit 1 sem ele; `--force` não dispensa) — ou `--self-assessed` registrado (`approvalGates.review.selfAssessed`, marcado no `morph-spec list`).
 

package/framework/agents.json

@@ -144,8 +144,9 @@
       "stack": ["*"],
       "standards": [],
       "tools": "Read, Glob, Grep, Bash",
+      "mcp": ["playwright"],
       "model": "opus",
-      "persona": "Você aplica as rubricas em .morph/framework/evals/rubrics/. Você não participou da implementação — avalia o mandate, o diff e a saída real dos testes, com contexto fresco. O orquestrador anexa o resultado do `morph-spec verify`, mas você tem Bash para conferir por conta própria: rode `morph-spec verify {feature} [task]`, testes/build do stack, `git log/diff/show` — nunca confie cegamente no que foi reportado. Bash é só para verificação: NUNCA para modificar código-fonte, tasks.json, feature.json ou o board de sessão — quem faz isso é o loop de correção, não você. Não reescreve código — produz scores 0-10 por dimensão (architecture, contracts, code-quality, test-coverage), feedback priorizado acionável, e ação clara (aprovado em >=9 / feedback para o loop de correção em <9). Silêncio em scores ≥ 9 é o sinal correto."
+      "persona": "Você aplica as rubricas em .morph/framework/evals/rubrics/. Você não participou da implementação — avalia o mandate, o diff e a saída real dos testes, com contexto fresco. O orquestrador anexa o resultado do `morph-spec verify`, mas você tem Bash para conferir por conta própria: rode `morph-spec verify {feature} [task]`, testes/build do stack, `git log/diff/show` — nunca confie cegamente no que foi reportado. Bash é só para verificação: NUNCA para modificar código-fonte, tasks.json, feature.json ou o board de sessão — quem faz isso é o loop de correção, não você. Você também tem Playwright: quando o nó `e2e` do verify subiu o stack, NAVEGUE a aplicação como um usuário faria e percorra os fluxos da feature — ler o diff prova que o código existe, usar a aplicação prova que ela funciona. Confira console e network atrás de erro que nenhum teste cobre. Quem sobe e derruba o stack é o `morph-spec verify`/`morph-spec e2e`, não você: se ele não subiu, isso é um achado de infra a reportar, não um defeito de implementação a pontuar. Se um fluxo que você exercitou merece virar regressão, recomende a spec Playwright no relatório — recomendar é seu papel, escrever não. Não reescreve código — produz scores 0-10 por dimensão (architecture, contracts, code-quality, test-coverage), feedback priorizado acionável, e ação clara (aprovado em >=9 / feedback para o loop de correção em <9). Silêncio em scores ≥ 9 é o sinal correto."
     },
     "scout": {
       "title": "Codebase Scout",

package/framework/docs/CLI.md

@@ -31,7 +31,8 @@
 ## Validação
 
 - **`morph-spec dag <feature>`** — análise do DAG de tasks.json com decisão sequencial vs paralelo **ponderada por effort** (raízes S vão inline, nunca ganham agente próprio). Também cruza `tasks.json` com os use cases: `usecase` apontando para um `UC-{nn}` inexistente é **erro** (exit 1, não despacha); pós-condição órfã e `doneCriteria` que parafraseou em vez de copiar são avisos. `--mermaid` nunca é bloqueado.
-- **`morph-spec verify <feature> [task] [--json]`** — cadeia determinística build+testes+validadores (código antes do juiz LLM); escopo de task quando informado, senão a feature inteira.
+- **`morph-spec verify <feature> [task] [--json] [--skip-e2e] [--fresh-e2e]`** — cadeia determinística build+testes+validadores+**e2e** (código antes do juiz LLM); escopo de task quando informado, senão a feature inteira. O nó `e2e` é o único que **executa** a aplicação: sobe o `docker compose` do projeto, espera todo serviço ficar saudável e roda as specs Playwright quando existem (sem specs, ainda vale como smoke — "a app sobe" já pega o serviço não registrado que derruba o startup e passa batido no build). Aplicabilidade: escopo de feature (Gate 3) **sempre** roda; escopo de task roda para `group` `frontend`/`backend`/`infra` e dispensa `tests`/`docs`. **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.
+- **`morph-spec e2e up|status|down <feature>`** — ciclo de vida do stack de verificação, compartilhando toda a lógica com o nó `e2e` do verify. `up [--fresh]` reusa um stack quente **só** quando ele provadamente serve o código atual: o carimbo compara `HEAD` + `git status --porcelain` + `git diff HEAD`, então qualquer edição, commitada ou não, invalida o reuso (a exceção é o serviço com bind mount do código, que serve o disco por construção). Na dúvida, rebuild — o layer cache do Docker faz disso barato. `status [--json]` responde a pergunta que decide se um verde vale alguma coisa (no ar? saudável? construído do código atual?) e sai 0 só com os três; o `baseUrl` do payload é o endereço real da app — é dele que a `morph-review` tira a URL que vai no prompt do avaliador, em vez de deixá-lo adivinhar `localhost:3000`. `down [--volumes]` é best-effort e nunca bloqueia. Isolamento entre worktrees: `COMPOSE_PROJECT_NAME=morph-{feature}` separa os containers e o bloco de portas do fleet (`env-allocator`) separa as portas — um compose com porta fixa não pode ser isolado, e isso é avisado. O bloco vale nos **dois** caminhos (este comando e o nó do `verify`): `PORT`, `MORPH_PORT_BASE`, `ASPNETCORE_URLS` em dotnet, mais `PLAYWRIGHT_BASE_URL` apontando para a porta alocada. Por isso o `playwright.config.ts` precisa ler a base URL do ambiente em vez de cravá-la — com a URL cravada, a suíte bate numa porta vazia e o `ECONNREFUSED` se disfarça de app quebrada.
 - **`morph-spec doctor --worktrees [--prune] [--json]`** — reconcilia o registro do git × as pastas em disco × as features conhecidas. Worktrees órfãos acumulavam **invisíveis**: o `fleet` só reporta worktrees em branch `morph/*`, então um worktree em outra branch (resíduo de finish anterior) não aparecia em lugar nenhum. `--prune` roda o único reparo seguro (`git worktree prune` — registros de pastas que já sumiram); apagar pasta que ainda existe é reportado com o comando exato, nunca executado.
 - **`morph-spec report-check <feature> [task] [--json]`** — audita os relatórios de sub-agent contra o trabalho que realmente entrou. **Relatório ausente NÃO quer dizer que o agente falhou** — ele pode ter feito tudo e perdido o meio de gravar. O comando responde a pergunta certa (`work-landed-report-missing` → aceite degradado, NÃO re-despache; `no-work-no-report` → re-despache uma vez). Protocolo completo em MORPH.md §6.
 

package/framework/schemas/feature.schema.json

@@ -106,7 +106,8 @@
             "properties": {
               "build": { "type": "string", "enum": ["pass", "fail", "skip"] },
               "tests": { "type": "string", "enum": ["pass", "fail", "skip"] },
-              "validators": { "type": "string", "enum": ["pass", "fail", "skip"] }
+              "validators": { "type": "string", "enum": ["pass", "fail", "skip"] },
+              "e2e": { "type": "string", "enum": ["pass", "fail", "skip"], "description": "Docker bring-up + Playwright specs against the running stack. Absent on entries written before the node existed — which is why it is NOT in `required`." }
             },
             "additionalProperties": false
           },
@@ -132,7 +133,8 @@
               "properties": {
                 "build": { "type": "string", "enum": ["pass", "fail", "skip"] },
                 "tests": { "type": "string", "enum": ["pass", "fail", "skip"] },
-                "validators": { "type": "string", "enum": ["pass", "fail", "skip"] }
+                "validators": { "type": "string", "enum": ["pass", "fail", "skip"] },
+                "e2e": { "type": "string", "enum": ["pass", "fail", "skip"], "description": "Docker bring-up + Playwright specs against the running stack. Absent on entries written before the node existed — which is why it is NOT in `required`." }
               },
               "additionalProperties": false
             },
@@ -147,7 +149,7 @@
     },
     "verification": {
       "type": "object",
-      "description": "The single latest deterministic verify stamp (any scope), written ONLY by `morph-spec verify`. Distinct from `verifications`/`taskVerifications` above (per-scope history with attempts/nodes): this is overwritten by every verify call regardless of scope, carrying just enough to correlate a pass/fail with the exact commit it covers. Primary consumer: `morph-spec gate-check`, which surfaces it as a signal (informational — no shouldPauseGate rule keys on it directly).",
+      "description": "The single latest deterministic verify stamp (any scope), written ONLY by `morph-spec verify`. Distinct from `verifications`/`taskVerifications` above (per-scope history with attempts/nodes): this is overwritten by every verify call regardless of scope, carrying just enough to correlate a pass/fail with the exact commit it covers. Primary consumer: `morph-spec gate-check`, which feeds `status` to shouldPauseGate as `verificationStatus` — a red verify pauses the gate (risk-detector.js). The remaining fields (sha/ts/scope, and the derived `verificationStale`) are audit context, not pause rules.",
       "required": ["status", "sha", "ts", "scope"],
       "properties": {
         "status": { "type": "string", "enum": ["pass", "fail"] },

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

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.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-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 stacks:
   - umbraco
 ---

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

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-apply
@@ -246,7 +246,7 @@ re-apresente o gate**: siga direto para o encerramento (§6) conforme a decisão
 - `framework/skills/core/morph-review/SKILL.md`
 - `framework/skills/core/morph-plan/SKILL.md` §5a — resolve e carimba `task.agent`/`task.standards` no plano; fonte primária deste §3b
 - `morph-spec dag {feature}` — análise de DAG e decisão sequencial vs paralelo (ponderada por effort), incluindo recomendação de isolamento (`isolation.recommended: "worktree"`)
-- `morph-spec verify {feature} [task] --json` — cadeia determinística build+testes+validadores (código antes do juiz)
+- `morph-spec verify {feature} [task] --json` — cadeia determinística build+testes+validadores+e2e (código antes do juiz)
 - `morph-spec score {feature} {task} {score} [--dims a,c,q,t]` — grava taskScores no feature.json com timestamp server-side
 - `morph-spec gate-check {feature} {gate} [--json]` — default: coleta sinais do disco, decide via `shouldPauseGate`, persiste `gateDecisions`
 - `morph-spec gate-decision {feature} {gate} --pause {bool} [--reason ...] [--signals ...]` — escape manual: risco que o `gate-check` não vê no disco (shape em `.morph/framework/schemas/feature.schema.json`)

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

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-brainstorming

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

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-eval

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

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-hotfix

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

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-implement

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

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-plan
@@ -88,6 +88,27 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    - Patterns proibidos — **copie por extenso no mandate.md** a lista canônica de `MORPH.md` § "Stack baked-in" (`Guid.NewGuid()`→`Guid.CreateVersion7()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico `IRepository<T>`/`IUnitOfWork`, SQL cru sem justificativa) mais qualquer proibição específica da feature. Copie o texto completo — o mandate.md é lido por implementadores em contexto fresco, sem `MORPH.md` carregado, então um ponteiro sozinho não basta aqui.
    - Política de acesso a dados (registre no mandate): `ApplicationDbContext` injetado direto no slice — para CRUD e para queries específicas (joins, projeção, paginação). Para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
    - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via `morph-spec standards --find "<tema>" --category ai-agents`. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
+   - **Verificação de runtime** — como se PROVA que a feature funciona rodando, não só compilando.
+     Compilar não é subir: um serviço injetado sem registro em `Program.cs` passa no build e derruba
+     a aplicação no startup. Registre no mandate:
+     - **Como o stack sobe:** o `docker compose` do projeto (`morph-spec e2e up {feature}`). Se o
+       projeto containeriza mas não tem compose, **isso é uma task** — sem ele o nó `e2e` do verify
+       reprova (não dispensa).
+     - **O que precisa ser exercitado:** os fluxos desta feature que o avaliador vai navegar, em
+       linguagem de comportamento — os mesmos verbos das pós-condições dos use cases.
+     - **Quais viram spec Playwright versionada:** caminho crítico e bug corrigido merecem regressão;
+       exploração pontual não. O critério vai aqui; escrever a spec é tarefa da implementação.
+     - **Base URL vinda do ambiente:** o harness dá a cada feature um bloco de portas próprio (para
+       duas worktrees não brigarem pela porta 3000), então o `playwright.config.ts` **não pode**
+       cravar a URL — leia `process.env.PLAYWRIGHT_BASE_URL ?? \`http://localhost:${process.env.PORT ?? 3000}\``
+       e faça o compose publicar `"${PORT:-3000}:3000"`. Config cravada = suíte batendo em porta
+       vazia e `ECONNREFUSED` com cara de app quebrada. Se estiver cravado, **isso é uma task**.
+     - **Setup de autenticação**, se a aplicação tem login: `e2e.auth` em `config.json`
+       (`mode: seed|storageState|bypass|none`, `seedCommand`, `storageStatePath`, `envFile`), com as
+       credenciais num `.env.e2e` **gitignored** — nunca no config commitado. **Se a app tem login e
+       isso não existe, crie a task de setup**: sem ela a navegação para na tela de login e a
+       verificação de runtime vira teatro. É gap de Gate 2, não dispensa de Gate 3.
+     - **Quando não se aplica** (biblioteca pura, chore sem runtime), registre a dispensa e o porquê.
    - Checklist de done com critérios verificáveis por tarefa.
 
 5. Produza `tasks.json` em `.morph/features/{feature}/2-plan/` seguindo o schema em `.morph/framework/schemas/tasks.schema.json`.

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

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-proposal

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

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-review
@@ -43,12 +43,22 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
      outro propósito. Falha aqui é bloqueante — quebra silenciosa em runtime, não em build.
 
 4. **Despache o avaliador independente** — o score do Gate 3 nunca é auto-atribuído por quem implementou:
-   - Rode `morph-spec verify {feature} --json` (escopo feature) e capture o JSON — é a saída real de build+testes+validadores que você anexa ao prompt do avaliador independente (`morph-evaluator`).
+   - Rode `morph-spec verify {feature} --json` (escopo feature) e capture o JSON — é a saída real de build+testes+validadores+e2e que você anexa ao prompt do avaliador independente (`morph-evaluator`).
+   - **Confira o nó `e2e` do verify antes de despachar.** Ele carrega o estado do stack:
+     - `pass` → a aplicação subiu e está saudável; o avaliador pode navegá-la. **Passe a URL no prompt**
+       — cada feature roda no seu bloco de portas, não em `localhost:3000`; pegue de
+       `morph-spec e2e status {feature} --json` (`baseUrl`) e não deixe o avaliador adivinhar.
+     - `fail` → **não abra o Gate 3.** Volte ao loop de correção: a app não sobe, ou as specs quebraram.
+     - `skip` → leia a razão e decida se a dispensa é legítima. "não containeriza" num projeto sem UI é
+       legítimo; "docker indisponível no ambiente" numa feature de UI **não** é — registre você mesmo
+       `morph-spec gate-decision {feature} review --pause true --reason "e2e não verificado: {razão}"`.
+       O disco não distingue dispensa legítima de verificação que faltou; esse julgamento é seu.
    - Gere o **diff da implementação** (`git diff` do range da feature, ou a lista de arquivos do recap.md com seus conteúdos atuais).
-   - Despache o subagent registrado `morph-evaluator` (gerado de `agents.json` — a persona do avaliador é o system prompt dele, com Read/Glob/Grep + Bash somente para verificação, sem Write/Edit), com contexto fresco:
+   - Despache o subagent registrado `morph-evaluator` (gerado de `agents.json` — a persona do avaliador é o system prompt dele, com Read/Glob/Grep + Bash somente para verificação + Playwright para navegar, sem Write/Edit), com contexto fresco:
      ```
      dispatch Agent (subagent_type: "morph-evaluator") with prompt:
        contexto: mandate.md + spec.md + diff da implementação + saída real dos testes
+                 + nó e2e do verify (stack no ar? em qual URL?)
        instrução: |
          Você NÃO participou da implementação — avalie o que está no diff,
          contra o mandate. Você tem Bash: use `morph-spec verify`, testes/build
@@ -56,6 +66,16 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
          foi reportado, em vez de confiar cegamente. Aplique as rubricas em
          .morph/framework/evals/rubrics/ (architecture 30%, contracts 25%,
          code-quality 25%, test-coverage 20%) seguindo as bandas 0-10 de cada uma.
+         Se o nó e2e subiu o stack, NAVEGUE a aplicação com Playwright e
+         percorra os fluxos desta feature como um usuário faria — ler o diff
+         prova que o código existe, usar a aplicação prova que ela funciona.
+         Confira console e network atrás de erro que teste nenhum cobriu.
+         Registre no relatório o que você navegou e o que viu. Se um fluxo que
+         você exercitou merece virar regressão, RECOMENDE a spec Playwright —
+         recomendar é seu papel, escrever a spec não é.
+         NÃO suba nem derrube o stack por conta própria (`morph-spec e2e` e o
+         nó de verify fazem isso): stack que não sobe é achado de INFRA a
+         reportar, não defeito de implementação a pontuar.
          NÃO reescreva código. NÃO toque em tasks.json, feature.json nem no board
          de sessão — Bash é só para verificação, nunca para mudar estado.
          Contrato do relatório final: GRAVE seu relatório em
@@ -71,8 +91,9 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
          contracts×0.25 + quality×0.25 + tests×0.20) gravado TAMBÉM como a
          linha literal `**Composite-Score:** {n.n}` (machine-readable — o
          `morph-spec gate-check` lê o score real daí em vez do proxy de
-         taskScores), e feedback priorizado (bloqueantes primeiro) para
-         qualquer dimensão < 9. Relatório ausente, oco, ou sem esses itens,
+         taskScores), feedback priorizado (bloqueantes primeiro) para
+         qualquer dimensão < 9, e — quando o stack estava no ar — o que você
+         navegou e o que observou. Relatório ausente, oco, ou sem esses itens,
          é falha de protocolo.
      ```
    - **Fallback (tipo não registrado):** se `morph-evaluator` não estiver na sua lista de subagent types, despache `general-purpose` colando o campo `persona` do agente `evaluator` (Read em `.morph/framework/agents.json`) no topo do prompt — e **registre o fallback no review-report** (seção de método).
@@ -87,6 +108,10 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
      uma regra de negócio, e ainda dizendo `976/976` quando eram 982).
    - Scores por dimensão (arquitetura, contratos, qualidade, cobertura)
    - Score composto final
+   - **Verificação de runtime** — o resultado do nó `e2e` (`pass`/`fail`/`skip` + razão), e o que o
+     avaliador navegou. Dispensa (`skip`) entra aqui **por extenso**: o valor de um gate está tanto
+     no que ele provou quanto no que ele deixou de provar, e uma dispensa silenciosa se lê como
+     aprovação. Se houver spec Playwright recomendada pelo avaliador, liste-a como melhoria.
    - Lista de itens bloqueantes (se houver) — com descrição e critério de resolução
    - Lista de melhorias recomendadas (não bloqueantes)
    - Recomendação final: Aprovado / Rejeitar com condições / Reprovar
@@ -130,6 +155,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
    **Composite score:** {score}/10
    **Dimensões:** arquitetura={X} contratos={Y} qualidade={Z} cobertura={W}
+   **Runtime:** e2e={pass|skip} {razão, quando skip}
    **Bloqueantes:** {N (zero esperado em auto-aprovação)}
    **Recomendação:** Aprovado
    ```
@@ -147,7 +173,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 - Gate 3 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo), na forma canônica `{ approved, timestamp, approvedBy }` — via `morph-spec approve` em auto, ou pelo hook state-sync no caminho manual
 
 ## Referências
-- `morph-spec verify {feature} [task] --json` — cadeia determinística build+testes+validadores anexada ao prompt do avaliador (passo 4)
+- `morph-spec verify {feature} [task] --json` — cadeia determinística build+testes+validadores+e2e anexada ao prompt do avaliador (passo 4)
 - `.morph/framework/MORPH.md` — seção 5 (Gate 3 + regras de pausa), seção 1 (papel Evaluator), Trust Mode
 - `.claude/agents/morph-evaluator.md` — subagent do avaliador (gerado de `.morph/framework/agents.json`), despachado no passo 4
 - `framework/skills/core/morph-eval/SKILL.md` — rubricas e bandas que o avaliador aplica

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-stack-scan

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-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-standards

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

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX — design system, mockups, compone
 version: core
 when-to-invoke: ao tomar o ramo uiux (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
 user-invokable: true
-cliVersion: "8.21.0"
+cliVersion: "8.22.0"
 ---
 
 # morph-uiux

package/framework/templates/infrastructure/docker/docker-compose.template.yml

@@ -1,7 +1,19 @@
 # Docker Compose for Local Development
 # Next.js + Neon Stack
-
-version: '3.8'
+#
+# Ports come from variables with sane defaults so `morph-spec e2e up` can hand
+# each feature worktree its own port block (see env-allocator.js). Hardcode
+# "3000:3000" here and two features running side by side collide on the host,
+# no matter what the harness injects — the container names would be distinct
+# and the ports would not.
+#
+# Healthchecks are what make `up --wait` meaningful: without them Compose
+# reports "started" the moment the process launches, and the e2e node would
+# navigate an application that is not serving yet.
+#
+# The harness also exports PLAYWRIGHT_BASE_URL for the same allocated port, so
+# `playwright.config.ts` must read it instead of hardcoding a URL:
+#   baseURL: process.env.PLAYWRIGHT_BASE_URL ?? `http://localhost:${process.env.PORT ?? 3000}`
 
 services:
   # Next.js Application
@@ -11,7 +23,7 @@ services:
       dockerfile: Dockerfile.dev
     container_name: {{kebabCase FEATURE_NAME}}-app
     ports:
-      - "3000:3000"
+      - "${PORT:-3000}:3000"
     environment:
       - NODE_ENV=development
       - DATABASE_URL=${DATABASE_URL}
@@ -20,7 +32,14 @@ services:
       - /app/node_modules
       - /app/.next
     depends_on:
-      - postgres
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "node -e \"fetch('http://localhost:3000/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
     networks:
       - app-network
 
@@ -30,7 +49,7 @@ services:
     container_name: {{kebabCase FEATURE_NAME}}-postgres
     restart: unless-stopped
     ports:
-      - "5432:5432"
+      - "${POSTGRES_PORT:-5432}:5432"
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
@@ -38,6 +57,11 @@ services:
     volumes:
       - postgres-data:/var/lib/postgresql/data
       - ./migrations:/docker-entrypoint-initdb.d
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d {{snakeCase FEATURE_NAME}}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
     networks:
       - app-network
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.21.0",
+  "version": "8.22.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/e2e/e2e.js

@@ -0,0 +1,318 @@
+/**
+ * `morph-spec e2e up|status|down` — lifecycle of the verification stack.
+ *
+ * The stack is deliberately NOT torn down between verifies: cold-starting a
+ * .NET container per task is the difference between a loop people run and one
+ * they disable. `up` brings it (or reuses it), `status` says whether what is
+ * running still matches the working tree, and `down` releases it — which
+ * `morph-spec finish` also does as part of teardown.
+ *
+ * All the real logic lives in framework/hooks/shared/e2e-check.js, shared with
+ * the `verify` e2e node so the two can never drift.
+ *
+ * @module commands/e2e
+ */
+
+import chalk from 'chalk';
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+import {
+  bringUpStack,
+  composeProjectName,
+  computeSourceStamp,
+  defaultExec,
+  getStackStatus,
+  isDockerAvailable,
+  prepareAuth,
+  readStamp,
+  resolveComposeFile,
+  resolveSpecCommand,
+  tearDownStack,
+} from '../../../framework/hooks/shared/e2e-check.js';
+import { buildComposeEnv } from '../../lib/e2e/compose-env.js';
+
+/** Exit code for a usage error, matching `verify`'s convention. */
+const EXIT_USAGE = 2;
+
+// ============================================================================
+// Shared context
+// ============================================================================
+
+/**
+ * Everything the three subcommands need, resolved once.
+ * Returns null (after printing) when the project has no compose file — that is
+ * a usage error here, unlike in the verify node where it is a graded skip.
+ */
+function resolveContext(featureName, { json = false } = {}) {
+  const cwd = process.cwd();
+  const config = readConfig(cwd);
+  const composeFile = resolveComposeFile(cwd, config);
+
+  if (!composeFile) {
+    const message =
+      'No compose file found (compose.yaml, docker-compose.yml, …). ' +
+      'Set project.e2e.composeFile in .morph/config/config.json if it lives elsewhere.';
+    if (json) console.log(JSON.stringify({ error: message }, null, 2));
+    else console.error(chalk.red(`\n❌ ${message}\n`));
+    return null;
+  }
+
+  const projectName = composeProjectName(featureName);
+  const gitCommonDir = resolveGitCommonDir(cwd);
+
+  return {
+    cwd,
+    config,
+    composeFile,
+    projectName,
+    gitCommonDir,
+    env: buildEnv({ cwd, config, featureName, projectName, gitCommonDir }),
+  };
+}
+
+/**
+ * Compose environment: the port block this feature owns, plus any credentials
+ * from the gitignored auth env file.
+ *
+ * The port block comes from `buildComposeEnv` rather than being assembled here
+ * so this command and the `e2e` node inside `verify` agree by construction —
+ * isolation that exists only in the command nobody runs is no isolation at all.
+ * `COMPOSE_PROJECT_NAME` isolates container NAMES but not host ports; a compose
+ * that hardcodes ports instead of reading `${PORT:-3000}` cannot be isolated at
+ * all, which is surfaced as a warning rather than silently accepted.
+ */
+function buildEnv({ cwd, config, featureName, projectName, gitCommonDir }) {
+  return {
+    COMPOSE_PROJECT_NAME: projectName,
+    ...buildComposeEnv({ cwd, config, featureName, gitCommonDir }),
+  };
+}
+
+/**
+ * Warn once when the compose file publishes fixed host ports: with a hardcoded
+ * `"3000:3000"` the fleet port block cannot take effect, so two features
+ * running simultaneously will collide no matter what we inject.
+ */
+function warnOnFixedPorts(cwd, composeFile) {
+  try {
+    const raw = readFileSync(join(cwd, composeFile), 'utf8');
+    const publishesFixed = /^\s*-\s*["']?\d+:\d+["']?\s*$/m.test(raw);
+    if (publishesFixed) {
+      console.log(
+        chalk.yellow(
+          '⚠️  Compose publishes fixed host ports. Parallel worktrees will collide — ' +
+            'use ${PORT:-3000}:3000 so the fleet port block applies.'
+        )
+      );
+    }
+  } catch {
+    // Unreadable compose is the caller's problem, not this warning's.
+  }
+}
+
+// ============================================================================
+// up
+// ============================================================================
+
+/**
+ * `morph-spec e2e up <feature> [--fresh]`
+ *
+ * Exit codes: 0 = stack healthy · 1 = failed to come up (or auth broke) ·
+ * 2 = usage (no compose file / no docker).
+ */
+export async function e2eUpCommand(featureName, options = {}) {
+  const ctx = resolveContext(featureName, options);
+  if (!ctx) process.exit(EXIT_USAGE);
+
+  if (!isDockerAvailable(ctx.cwd)) {
+    console.error(chalk.red('\n❌ Docker is not available in this environment.\n'));
+    process.exit(EXIT_USAGE);
+  }
+
+  if (!options.json) warnOnFixedPorts(ctx.cwd, ctx.composeFile);
+
+  const result = bringUpStack(ctx.cwd, {
+    composeFile: ctx.composeFile,
+    projectName: ctx.projectName,
+    gitCommonDir: ctx.gitCommonDir,
+    env: ctx.env,
+    forceFresh: Boolean(options.fresh),
+  });
+
+  const auth =
+    result.status === 'pass'
+      ? prepareAuth(ctx.cwd, { config: ctx.config, env: ctx.env })
+      : { status: 'skip', reason: null };
+
+  const failed = result.status === 'fail' || auth.status === 'fail';
+  const payload = {
+    feature: featureName,
+    project: ctx.projectName,
+    composeFile: ctx.composeFile,
+    status: failed ? 'fail' : 'pass',
+    reused: result.reused,
+    reason: result.reason,
+    auth: { status: auth.status, reason: auth.reason },
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else if (failed) {
+    console.error(chalk.red(`\n✗ ${result.reason || auth.reason}\n`));
+    if (result.output) console.error(result.output);
+  } else {
+    const how = result.reused ? chalk.gray(`(${result.reason})`) : chalk.gray('(built)');
+    console.log(chalk.green(`\n✓ Stack up — ${ctx.projectName} ${how}`));
+    if (auth.reason) console.log(chalk.gray(`  auth: ${auth.reason}`));
+    console.log('');
+  }
+
+  process.exit(failed ? 1 : 0);
+}
+
+// ============================================================================
+// status
+// ============================================================================
+
+/**
+ * Where the app actually landed.
+ *
+ * The reviewer hands this to the evaluator instead of letting it guess
+ * `localhost:3000` — each feature owns a port block, so the default port is the
+ * one address most likely to be wrong. Mirrors what `playwright.config.ts` is
+ * asked to do, deliberately: one rule, two readers.
+ *
+ * @param {Record<string,string>} env
+ * @returns {string}
+ */
+export function resolveBaseUrl(env = {}) {
+  return env.PLAYWRIGHT_BASE_URL ?? `http://localhost:${env.PORT ?? 3000}`;
+}
+
+/**
+ * `morph-spec e2e status <feature> [--json]`
+ *
+ * Answers the question that matters before trusting a green run: is what is
+ * running still built from the code on disk? Exit 0 when up AND fresh, 1
+ * otherwise — so it can gate a script.
+ */
+export async function e2eStatusCommand(featureName, options = {}) {
+  const ctx = resolveContext(featureName, options);
+  if (!ctx) process.exit(EXIT_USAGE);
+
+  const status = getStackStatus(ctx.cwd, {
+    composeFile: ctx.composeFile,
+    projectName: ctx.projectName,
+    env: ctx.env,
+  });
+
+  const stamp = computeSourceStamp(ctx.cwd);
+  const previous = ctx.gitCommonDir ? readStamp(ctx.gitCommonDir, ctx.projectName) : null;
+  const fresh = Boolean(stamp && previous?.stamp === stamp);
+
+  const spec = resolveSpecCommand(ctx.cwd, ctx.config, ctx.config?.project?.frontendPath);
+
+  const payload = {
+    feature: featureName,
+    project: ctx.projectName,
+    composeFile: ctx.composeFile,
+    up: status.up,
+    healthy: status.healthy,
+    fresh,
+    baseUrl: resolveBaseUrl(ctx.env),
+    builtAt: previous?.builtAt ?? null,
+    specs: spec ? `${spec.command} ${spec.args.join(' ')}` : null,
+    services: status.services.map((s) => ({
+      name: s.Service ?? s.Name ?? null,
+      state: s.State ?? null,
+      health: s.Health || null,
+    })),
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log('');
+    console.log(chalk.bold(`E2E stack — ${ctx.projectName}`));
+    console.log(chalk.gray(`compose: ${ctx.composeFile}`));
+    console.log(chalk.gray(`url:     ${payload.baseUrl}`));
+    console.log('');
+    console.log(`  up       ${status.up ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log(`  healthy  ${status.healthy ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log(
+      `  fresh    ${fresh ? chalk.green('yes') : chalk.yellow('no — source changed since build')}`
+    );
+    console.log(`  specs    ${spec ? payload.specs : chalk.gray('none (smoke only)')}`);
+    for (const s of payload.services) {
+      console.log(chalk.gray(`    · ${s.name}: ${s.state}${s.health ? ` / ${s.health}` : ''}`));
+    }
+    console.log('');
+  }
+
+  process.exit(status.up && status.healthy && fresh ? 0 : 1);
+}
+
+// ============================================================================
+// down
+// ============================================================================
+
+/**
+ * `morph-spec e2e down <feature> [--volumes]`
+ *
+ * Teardown is best-effort by design — a stack that will not come down must
+ * never block `finish`.
+ */
+export async function e2eDownCommand(featureName, options = {}) {
+  const ctx = resolveContext(featureName, options);
+  if (!ctx) process.exit(EXIT_USAGE);
+
+  const result = tearDownStack(ctx.cwd, {
+    composeFile: ctx.composeFile,
+    projectName: ctx.projectName,
+    env: ctx.env,
+    volumes: Boolean(options.volumes),
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify({ feature: featureName, project: ctx.projectName, status: result.status }, null, 2));
+  } else if (result.status === 'pass') {
+    console.log(chalk.green(`\n✓ Stack down — ${ctx.projectName}\n`));
+  } else {
+    console.log(chalk.yellow(`\n⚠️  Teardown reported a problem (not fatal):\n${result.output}\n`));
+  }
+
+  process.exit(0);
+}
+
+// ============================================================================
+// Shared helpers
+// ============================================================================
+
+function readConfig(cwd) {
+  try {
+    const path = join(cwd, '.morph', 'config', 'config.json');
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+/** Same resolution (and same fail-open) as verify-runner's. */
+function resolveGitCommonDir(cwd) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      windowsHide: true,
+    }).trim();
+    return common ? resolve(cwd, common) : null;
+  } catch {
+    return null;
+  }
+}
+
+export { defaultExec };

package/src/commands/state/finish.js

@@ -13,6 +13,11 @@ import {
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
 import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
+import {
+  composeProjectName,
+  resolveComposeFile,
+  tearDownStack,
+} from '../../../framework/hooks/shared/e2e-check.js';
 import { runArchive } from './archive.js';
 
 /** workType → conventional-commit type. `hotfix` IS a fix; anything else is a chore. */
@@ -85,12 +90,20 @@ export async function finishCommand(feature, options = {}) {
   // working on it (B1). Released on EVERY success path — hooking it into emit
   // is the single point that covers merge/PR/--keep alike. Fail-open: a claim
   // that outlives its feature only expires on its own TTL.
+  //
+  // The e2e stack rides along for the same reason: `morph-spec verify` leaves it
+  // UP on purpose (cold-starting a container per task is what makes the loop
+  // unusable), so something has to be the one place that reclaims the
+  // containers and their ports when the feature closes. Best-effort by
+  // contract — a stack that refuses to come down must never fail a finish that
+  // already merged.
   const emit = (obj) => {
     if (obj?.finished === true) {
       try {
         const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
         if (common) releaseClaim(feature, { gitCommonDir: resolve(root, common) });
       } catch { /* fail-open */ }
+      tearDownE2eStack(feature, root);
     }
     console.log(JSON.stringify(obj));
   };
@@ -502,6 +515,31 @@ function readFeatureJson(cwd, feature) {
   }
 }
 
+/**
+ * Reclaim the feature's verification stack, if the project has one.
+ *
+ * Runs from the ROOT rather than the worktree: by the time a finish emits
+ * success the worktree may already be gone, and the compose file is versioned
+ * so the root's copy is equivalent. Entirely fail-open — no compose, no docker,
+ * or a stubborn container are all non-events here.
+ */
+function tearDownE2eStack(feature, root) {
+  try {
+    const config = JSON.parse(
+      readFileSync(join(root, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, '')
+    );
+    const composeFile = resolveComposeFile(root, config);
+    if (!composeFile) return;
+
+    const projectName = composeProjectName(feature);
+    tearDownStack(root, {
+      composeFile,
+      projectName,
+      env: { COMPOSE_PROJECT_NAME: projectName },
+    });
+  } catch { /* fail-open — teardown must never fail a completed finish */ }
+}
+
 /** Drop a feature from the thin, gitignored root index (never via saveState). */
 function dropFromRootIndex(root, feature) {
   const rootPath = join(root, '.morph', 'state.json');

package/src/commands/validation/validate-feature.js

@@ -80,7 +80,7 @@ const OUTPUT_SECTIONS = {
     ],
   },
   // morph-plan (mandate.md) emits: Stack, Standards obrigatórios,
-  // Patterns proibidos, Checklist de done.
+  // Patterns proibidos, Verificação de runtime, Checklist de done.
   'mandate.md': {
     required: [
       'Stack',
@@ -89,6 +89,12 @@ const OUTPUT_SECTIONS = {
     ],
     recommended: [
       ['Patterns proibidos', 'Padrões proibidos', 'Padroes proibidos', 'Forbidden Patterns', 'Forbidden', 'Proibido'],
+      // Recommended rather than required on purpose: mandate.md freezes after
+      // Gate 2 (protect-spec-files blocks Write AND Edit), so promoting this to
+      // `required` would fail every in-flight feature with no way to fix it.
+      // New mandates get the section from morph-plan §4; the enforcement that
+      // actually matters is verify's e2e node, not this heading check.
+      ['Verificação de runtime', 'Verificacao de runtime', 'Runtime', 'E2E'],
     ],
     optional: [
       ['Riscos', 'Risks'],

package/src/commands/validation/verify.js

@@ -37,6 +37,10 @@ function formatVerifyResult(result) {
       detail = node.reason || '';
     } else if (name === 'validators' && node.score != null) {
       detail = `score ${node.score}/10`;
+    } else if (node.reason) {
+      // A green e2e still carries meaning worth showing: smoke-only vs specs,
+      // warm reuse vs rebuild. Without it, "pass" hides how much was proven.
+      detail = `${node.durationMs}ms — ${node.reason}`;
     } else {
       detail = `${node.durationMs}ms`;
     }
@@ -149,6 +153,8 @@ export async function verifyCommand(featureName, taskId, options = {}) {
     timeout: options.timeout,
     skipTests: options.skipTests,
     skipBuild: options.skipBuild,
+    skipE2e: options.skipE2e,
+    freshE2e: options.freshE2e,
   });
 
   const scopeKey = taskId ? `taskVerifications.${taskId}` : 'verifications.feature';
@@ -168,6 +174,7 @@ export async function verifyCommand(featureName, taskId, options = {}) {
         build: result.nodes.build.status,
         tests: result.nodes.tests.status,
         validators: result.nodes.validators.status,
+        e2e: result.nodes.e2e.status,
       },
       score: result.nodes.validators.score ?? null,
       attempts: (prevEntry?.attempts ?? 0) + 1,

package/src/lib/e2e/compose-env.js

@@ -0,0 +1,74 @@
+/**
+ * Compose environment for the e2e stack — the port block a feature owns, plus
+ * the credentials its auth setup needs.
+ *
+ * This lives in ONE place because it has two callers that must never disagree:
+ * `morph-spec e2e up` (manual) and the `e2e` node inside `morph-spec verify`
+ * (the one that actually runs in the loop). When only the manual path built the
+ * port block, the isolation was real in the command nobody runs and absent in
+ * the one everybody runs — two worktrees would get distinct container names via
+ * COMPOSE_PROJECT_NAME and then collide on host port 3000 anyway, surfacing as
+ * "port is already allocated" and pausing a gate over an infrastructure clash
+ * rather than a defect.
+ *
+ * It sits in src/lib rather than framework/hooks/shared because it depends on
+ * env-allocator.js: hooks are installed standalone into target projects, where
+ * `src/` does not exist, so the dependency may only point this way.
+ *
+ * @module lib/e2e/compose-env
+ */
+
+import { join } from 'path';
+
+import { loadEnvFile } from '../../../framework/hooks/shared/e2e-check.js';
+import { allocateEnvBlock, resolveFleetConfig } from '../worktree/env-allocator.js';
+
+/**
+ * Build the environment a `docker compose` invocation should carry.
+ *
+ * Port variables mirror `buildEnvFileContent()` in env-allocator.js so a
+ * compose file and a `.morph/worktree.env` describe the same world: `PORT` for
+ * the web tier, `ASPNETCORE_URLS` on base+1 for a .NET backend.
+ *
+ * `PLAYWRIGHT_BASE_URL` is derived here rather than left to the spec config —
+ * the suite has to be told where the app actually landed, otherwise a feature
+ * on port 4020 gets tested against a hardcoded localhost:3000 and fails with
+ * ECONNREFUSED that looks exactly like a broken app.
+ *
+ * Fail-open throughout: with no git dir (or a corrupt registry) the caller gets
+ * default ports, which only matters when two stacks run at once.
+ *
+ * @param {object} params
+ * @param {string} params.cwd - project root
+ * @param {object|null} [params.config] - .morph/config/config.json contents
+ * @param {string} params.featureName
+ * @param {string|null} [params.gitCommonDir]
+ * @returns {Record<string,string>}
+ */
+export function buildComposeEnv({ cwd, config, featureName, gitCommonDir }) {
+  const env = {};
+
+  if (gitCommonDir) {
+    try {
+      const { basePort, blockSize } = resolveFleetConfig(cwd);
+      const block = allocateEnvBlock(featureName, { gitCommonDir, basePort, blockSize });
+
+      env.MORPH_PORT_BASE = String(block.base);
+      env.MORPH_PORT_RANGE = `${block.range[0]}-${block.range[1]}`;
+      env.PORT = String(block.base);
+      env.PLAYWRIGHT_BASE_URL = `http://localhost:${block.base}`;
+
+      if (/\bdotnet\b/i.test(String(config?.project?.stack ?? ''))) {
+        env.ASPNETCORE_URLS = `http://localhost:${block.base + 1}`;
+      }
+    } catch {
+      // No block → default ports. Surfaces later as a port conflict, never here.
+    }
+  }
+
+  // Credentials live in a gitignored env file, never in the committed config.
+  const envFile = config?.e2e?.auth?.envFile;
+  if (envFile) Object.assign(env, loadEnvFile(join(cwd, envFile)));
+
+  return env;
+}

package/src/lib/validators/verify-runner.js

@@ -1,24 +1,33 @@
 /**
- * Verify Runner — deterministic build+tests+validators cadence.
+ * Verify Runner — deterministic build+tests+validators+e2e cadence.
  *
  * v8 adds a DETERMINISTIC verification node that runs BEFORE the LLM judge
  * in the per-task loop: build + tests + validators (code, free) first; the
  * LLM judge is only invoked once verify passes. This is a BINARY gate
  * (pass/fail per node), NOT a second "bar 9" — the bar 9 remains morph-eval's.
  *
+ * The `e2e` node closes the last gap in that chain: build proves the code
+ * COMPILES, tests prove units behave, validators read structure — none of
+ * them prove the application RUNS. See e2e-check.js for why that distinction
+ * is load-bearing rather than academic.
+ *
  * Pure orchestration — reuses (never reimplements):
  *   - runBuildCheck()  from framework/hooks/shared/build-check.js
  *   - runTestSuite()   from src/lib/tasks/test-runner.js
  *   - runValidation()  from ./validation-runner.js
+ *   - runE2eCheck()    from framework/hooks/shared/e2e-check.js
  *   - loadRubric() + aggregateScores() from ./score-aggregator.js
  *
  * @module verify-runner
  */
 
+import { execFileSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 
 import { runBuildCheck, getBuildSteps } from '../../../framework/hooks/shared/build-check.js';
+import { runE2eCheck } from '../../../framework/hooks/shared/e2e-check.js';
+import { buildComposeEnv } from '../e2e/compose-env.js';
 import { runTestSuite, resolveTestCommand } from '../tasks/test-runner.js';
 import { runValidation } from './validation-runner.js';
 import { loadRubric, aggregateScores } from './score-aggregator.js';
@@ -41,9 +50,12 @@ const OUTPUT_TAIL_LINES = 20;
  * @param {number} [options.timeout] - Build timeout in ms (default 120000)
  * @param {boolean} [options.skipTests] - Skip the tests node
  * @param {boolean} [options.skipBuild] - Skip the build node
+ * @param {boolean} [options.skipE2e] - Skip the e2e node
+ * @param {boolean} [options.freshE2e] - Force a stack rebuild instead of reusing a warm one
  * @param {Function} [options._runBuildCheck] - Injectable override for runBuildCheck (testing)
  * @param {Function} [options._runTestSuite] - Injectable override for runTestSuite (testing)
  * @param {Function} [options._runValidation] - Injectable override for runValidation (testing)
+ * @param {Function} [options._runE2eCheck] - Injectable override for runE2eCheck (testing)
  * @returns {Promise<Object>} Aggregated verify result — see module docs for shape
  */
 export async function runVerify(projectPath, featureName, taskId, options = {}) {
@@ -52,9 +64,12 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
     timeout = DEFAULT_BUILD_TIMEOUT,
     skipTests = false,
     skipBuild = false,
+    skipE2e = false,
+    freshE2e = false,
     _runBuildCheck = runBuildCheck,
     _runTestSuite = runTestSuite,
     _runValidation = runValidation,
+    _runE2eCheck = runE2eCheck,
   } = options;
 
   const stack = readStack(projectPath);
@@ -76,6 +91,20 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   nodes.validators = await runValidatorsNode({ projectPath, featureName, rubricId, _runValidation });
   appendValidatorsFeedback(feedback, nodes.validators);
 
+  // 4. e2e — the only node that runs the application. Like tests, it is not
+  // invoked at all on a red build: a stack that cannot compile cannot come up,
+  // and the docker output would bury the actual compile error.
+  nodes.e2e = await runE2eNode({
+    projectPath,
+    featureName,
+    taskId,
+    skipE2e,
+    freshE2e,
+    buildNode: nodes.build,
+    _runE2eCheck,
+  });
+  appendE2eFeedback(feedback, nodes.e2e);
+
   const status = Object.values(nodes).some((n) => n.status === 'fail') ? 'fail' : 'pass';
 
   return {
@@ -239,6 +268,63 @@ function appendValidatorsFeedback(feedback, validatorsNode) {
   }
 }
 
+// ============================================================================
+// E2E node
+// ============================================================================
+
+async function runE2eNode({ projectPath, featureName, taskId, skipE2e, freshE2e, buildNode, _runE2eCheck }) {
+  if (buildNode.status === 'fail') {
+    return {
+      status: 'skip',
+      command: null,
+      durationMs: 0,
+      reason: 'build failed — the stack could not come up anyway',
+      output: '',
+    };
+  }
+
+  const config = readConfig(projectPath);
+  const taskGroup = taskId ? readTaskGroup(projectPath, featureName, taskId) : null;
+  const gitCommonDir = resolveGitCommonDir(projectPath);
+
+  const start = Date.now();
+  const result = _runE2eCheck(projectPath, {
+    config,
+    featureName,
+    taskGroup,
+    scope: taskId ? 'task' : 'feature',
+    gitCommonDir,
+    // The port block matters MORE here than in `e2e up`: this is the path that
+    // runs in the loop, and two worktrees verifying at once would otherwise get
+    // distinct container names and then collide on host port 3000 — a red gate
+    // over an infrastructure clash instead of a defect.
+    env: buildComposeEnv({ cwd: projectPath, config, featureName, gitCommonDir }),
+    skipRequested: skipE2e,
+    forceFresh: freshE2e,
+    // The stack stays up between verifies on purpose: cold-starting a .NET
+    // container per task is the difference between a usable loop and one
+    // nobody runs. `morph-spec e2e down` (and `finish`) tear it down.
+    keepUp: true,
+  });
+  const durationMs = Date.now() - start;
+
+  return {
+    status: result.status,
+    command: result.command ?? null,
+    durationMs,
+    reason: result.reason ?? null,
+    output: result.output || '',
+  };
+}
+
+function appendE2eFeedback(feedback, e2eNode) {
+  if (e2eNode.status !== 'fail') return;
+  if (e2eNode.reason) feedback.push(`[e2e] ${e2eNode.reason}`);
+  for (const line of linesOf(e2eNode.output)) {
+    feedback.push(`[e2e] ${line}`);
+  }
+}
+
 // ============================================================================
 // Rubric selection — flag > task group > config > default
 // ============================================================================
@@ -328,6 +414,39 @@ function readProjectPaths(projectPath) {
   }
 }
 
+/** Read the whole config.json — the e2e node needs `e2e` and `project` together. */
+function readConfig(projectPath) {
+  try {
+    const configPath = join(projectPath, '.morph', 'config', 'config.json');
+    if (!existsSync(configPath)) return null;
+    return JSON.parse(readFileSync(configPath, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the shared git dir, where the e2e freshness stamp lives — the same
+ * location and rationale as the fleet env-registry (see env-allocator.js): it
+ * is the one place every linked worktree of a repo shares, and writing there
+ * can never dirty the `git status` the worktree-finish gates read.
+ *
+ * Fail-open: no git, no stamp — the cost is a rebuild, never a crash.
+ */
+function resolveGitCommonDir(projectPath) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd: projectPath,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      windowsHide: true,
+    }).trim();
+    return common ? resolve(projectPath, common) : null;
+  } catch {
+    return null;
+  }
+}
+
 function linesOf(text) {
   const trimmed = (text || '').trim();
   return trimmed ? trimmed.split('\n') : [];