@polymorphism-tech/morph-spec 8.20.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.20.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.20.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')
@@ -428,7 +456,8 @@ program
 program
   .command('cost [feature]')
   .description('Cost-facing view over .morph/logs/events.jsonl: task duration, bytes re-ingested by kind (proxy, not tokens), dispatch counts')
-  .option('--by <mode>', 'Group by: task|phase (default: feature-wide summary)')
+  .option('--by <mode>', 'Group by: task|phase (default: feature-wide summary; with --all-trees, applies to the combined aggregate)')
+  .option('--all-trees', 'Aggregate .morph/logs/events.jsonl across every git worktree that has one, not just the current tree — per-tree breakdown + combined total')
   .option('--json', 'Output the aggregate as JSON')
   .action((feature, options) => costCommand(feature, options));
 

package/claude-plugin.json

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

@@ -102,7 +102,7 @@
         "design", "ui", "ux", "design system", "tokens", "wcag",
         "accessibility", "mockup", "flow", "shadcn", "tailwind"
       ],
-      "stack": ["nextjs"],
+      "stack": ["*"],
       "standards": [
         "frontend-design-system-naming",
         "frontend-design-system-animations",
@@ -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

@@ -9,7 +9,7 @@
 - **`morph-spec approve <feature> <gate> --mode auto`** — aprova um gate (`proposal`/`uiux`/`plan`/`review`) em `trust: auto`. **`uiux`** é o único gate cujo `AskUserQuestion` o hook `state-sync.js` não reconhece por texto (só casa "Gate 1/2/3") — aprove-o sempre explicitamente por este comando ou por `advance`, nunca contando com o hook. **O Gate 3 exige `4-review/evaluator-report.md`**: sem o relatório do avaliador independente o comando recusa (exit 1). Se o dispatch do avaliador for impossível nesta sessão, aprove com `--self-assessed` — a degradação é gravada em `approvalGates.review.selfAssessed` e aparece marcada no `morph-spec list`. `--force` **não** dispensa esta regra (é só para ordem de gate). **Exceção `hotfix`:** esse tipo nunca despacha o avaliador (`morph-hotfix` §7); o Gate 3 exige `4-review/review-report.md` no lugar do `evaluator-report.md`, e a assinatura humana continua obrigatória via `--approver` (o backstop de `--mode auto` acima permanece recusando).
 - **`morph-spec advance <feature>`** — aprova o gate da fase corrente **e** cria a pasta da próxima fase num passo só (`--design` toma o ramo opcional de uiux a partir da proposta).
 - **`morph-spec score <feature> <task> <score> [--dims a,c,q,t]`** — grava `taskScores` no feature.json com timestamp server-side; **nunca edite taskScores à mão**. Em PowerShell, cite o valor de `--dims` entre aspas (`--dims "9.5,9,9,9"`) — sem aspas, a lista pode chegar como tokens separados; o parser aceita ambas as formas, mas citar evita qualquer ambiguidade.
-- **`morph-spec gate-check <feature> <gate> [--signals <json>] [--trust <mode>] [--json]`** — o caminho **default**: coleta do disco os sinais que `shouldPauseGate` (risk-detector.js) já sabe avaliar (`workType`, `taskCount`, verificação, sha/diffstat), decide a pausa e persiste `gateDecisions.{gate}`. `--signals` aceita só as chaves que o disco genuinamente não expõe sozinho — `designSystemDivergence`, `standardsViolations`, `evalScore` — qualquer outra chave é ignorada com aviso. No **review**, o `evalScore` real vem do token `**Composite-Score:** {n.n}` do `evaluator-report.md` (o avaliador o grava por contrato); sem o token, cai no proxy (média das `taskScores`); `--signals` vence ambos. Um stamp de `verification` com status `fail` (último `morph-spec verify` vermelho) **força pausa** em qualquer gate.
+- **`morph-spec gate-check <feature> <gate> [--signals <json>] [--trust <mode>] [--json]`** — o caminho **default**: coleta do disco os sinais que `shouldPauseGate` (risk-detector.js) já sabe avaliar (`workType`, `taskCount`, verificação, sha/diffstat), decide a pausa e persiste `gateDecisions.{gate}`. `--signals` aceita só as chaves que o disco genuinamente não expõe sozinho — `designSystemDivergence`, `standardsViolations`, `evalScore` — qualquer outra chave é ignorada com aviso. No **review**, o `evalScore` real vem do token `**Composite-Score:** {n.n}` do `evaluator-report.md` (o avaliador o grava por contrato); sem o token, cai no proxy (média das `taskScores`); `--signals` vence ambos. Um stamp de `verification` com status `fail` (último `morph-spec verify` vermelho) **força pausa** em qualquer gate. Um stamp `pass` mas **stale** (sha diferente do HEAD atual — código mudou depois do último verify) força pausa **só no ship** (`review`); em `plan`/`uiux`/`proposal` a staleness é computada e reportada em `signals`, mas não pausa nada — é regra de ship, não de gate genérico. Stamp **ausente** nunca pausa por isso (features legadas sem stamp).
 - **`morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]`** — o **escape manual**: registra uma decisão já tomada pela sessão (ex.: `discoveryMode: "interview"`, sinal que `shouldPauseGate` nem representa). Mesmo write path do `gate-check` — grava `gateDecisions` no feature.json com timestamp server-side (shape em `framework/schemas/feature.schema.json`); **nunca edite gateDecisions à mão** — o Edit manual colide com o hook state-sync.
 
 ## Features
@@ -31,11 +31,12 @@
 ## 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.
 
 ## Observabilidade
 
 - **`morph-spec telemetry [--json] [--feature <f>] [--limit <n>]`** — reconstrói o caminho de execução da sessão a partir de `.morph/logs/events.jsonl` (skills invocadas, personas despachadas + prompts, standards/base de conhecimento lidos, mix de tools, prompts do usuário). Capturado silenciosamente pelo hook `telemetry-log` em todo tool call e todo UserPromptSubmit.
-- **`morph-spec cost [feature] [--by task|phase] [--json]`** — custo da execução a partir do mesmo `events.jsonl`: duração por task (TaskStart→TaskEnd), bytes de contexto re-ingerido por tipo (`rubric`/`standard`/`skill`/`agents`/`plan-artifact`/`code`), dispatches + tamanho de prompt e mix de tools. Bytes re-ingeridos são **proxy determinística** de custo de token (tokens reais não são observáveis por hook). Use antes/depois de mudar skill ou fluxo para medir o efeito.
+- **`morph-spec cost [feature] [--by task|phase] [--all-trees] [--json]`** — custo da execução a partir do mesmo `events.jsonl`: duração por task (TaskStart→TaskEnd), bytes de contexto re-ingerido por tipo (`rubric`/`standard`/`skill`/`agents`/`plan-artifact`/`code`), dispatches + tamanho de prompt e mix de tools. Bytes re-ingeridos são **proxy determinística** de custo de token (tokens reais não eram observáveis por hook até o evento `SessionUsage` — quando presente no stream, `inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheCreationTokens` são somados e exibidos à parte como "tokens reais", nunca misturados com a proxy de bytes). `--all-trees` agrega `.morph/logs/events.jsonl` de **toda árvore git** que tiver um (não só a corrente) — reusa a mesma enumeração de worktree do `doctor --worktrees`/`fleet`; mostra um resumo por árvore + o total combinado (`--by` aplica ao agregado combinado). Use antes/depois de mudar skill ou fluxo para medir o efeito.

package/framework/hooks/claude-code/core/enforce-phase-writes.js

@@ -102,8 +102,29 @@ export async function run(payload) {
       // advances once that file exists) — the deadlock this hook used to create.
       const entryGate = PHASE_DIR_ENTRY_GATE[targetDir];
       if (entryGate && isGateApproved(featureName, entryGate, root)) {
-        logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
-        return null;
+        // uiux is OPTIONAL — proposal approval alone is enough to enter
+        // 2-plan/ for a feature that never took the design branch (no
+        // 1-design/ dir), exactly as before this check. But once a feature
+        // HAS opted into uiux (1-design/ exists), that gate is not
+        // decorative: 2-plan/ must wait for it too, or a feature can skip
+        // straight from an approved proposal into planning with its design
+        // gate silently left pending.
+        const tookDesignBranch = targetDir === '2-plan'
+          && existsSync(resolveTargetPath(`.morph/features/${featureName}/1-design`, root));
+
+        if (!tookDesignBranch || isGateApproved(featureName, 'uiux', root)) {
+          logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+          return null;
+        }
+
+        logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
+        return blockResult(
+          `MORPH-SPEC: Writing to '2-plan/' is not allowed yet.\n` +
+          `This feature entered the uiux branch (1-design/ exists) and the 'uiux' gate is still pending.\n\n` +
+          `Approve the design gate first, then re-enter plan:\n` +
+          `  morph-spec approve ${featureName} uiux\n` +
+          `  morph-spec advance ${featureName}`
+        );
       }
 
       const phaseLabel = phase.toUpperCase();

package/framework/hooks/claude-code/core/state-sync.js

@@ -94,6 +94,11 @@ function isApprovalAnswer(answer) {
 
 function gateFromQuestion(question) {
   if (typeof question !== 'string') return null;
+  // Checked BEFORE the generic patterns below: the pinned uiux template is
+  // "Gate uiux — Design de {feature} aprovado?" (morph-uiux/SKILL.md) — it
+  // must never fall through to 'plan' via a stray "plan"/"plano" substring in
+  // the feature name. `/gate\s+uiux/i` alone is unambiguous either way.
+  if (/gate\s+uiux/i.test(question)) return 'uiux';
   const lower = question.toLowerCase();
   if (lower.includes('gate 1') || lower.includes('proposta')) return 'proposal';
   if (lower.includes('gate 2') || lower.includes('plano') || lower.includes('plan')) return 'plan';

package/framework/hooks/claude-code/core/telemetry-log.js

@@ -41,6 +41,32 @@ function normalize(p) {
   return (p || '').replace(/\\/g, '/');
 }
 
+// events.jsonl grows forever across a project's lifetime (R2 rotation caps
+// the FILE, not any single line) — a multi-KB sub-agent prompt or a long
+// Bash command written verbatim on every dispatch/call is the dominant per-
+// line cost. Capped AT THE WRITE SITE (not in the shared logger, so every
+// OTHER event type stays exactly as-is) to `MAX_FIELD_CHARS`, with the
+// ORIGINAL length preserved in a sibling `<field>Chars` key — `morph-spec
+// cost` sums prompt chars for its dispatch-cost view, and must prefer that
+// field over `prompt.length` once it's present (a truncated string's own
+// length would silently undercount every dispatch over the cap). This shape
+// is a CONTRACT with the telemetry reader — do not rename either half.
+const MAX_FIELD_CHARS = 2000;
+const TRUNCATE_SUFFIX = '…[truncado]';
+
+/**
+ * Cap a free-text field (prompt/command) at MAX_FIELD_CHARS, always
+ * reporting the field's true original length alongside it.
+ *
+ * @param {string} value
+ * @returns {{ value: string, chars: number }}
+ */
+function capField(value) {
+  const str = typeof value === 'string' ? value : '';
+  if (str.length <= MAX_FIELD_CHARS) return { value: str, chars: str.length };
+  return { value: str.slice(0, MAX_FIELD_CHARS) + TRUNCATE_SUFFIX, chars: str.length };
+}
+
 /**
  * Classify a Read target into the telemetry `kind` taxonomy — a contract with
  * the observability side (src/lib/telemetry/telemetry-reader.js), so these
@@ -144,7 +170,8 @@ export async function run(payload) {
 
     // UserPromptSubmit carries the user's prompt and no tool_name.
     if (payload.hook_event_name === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string')) {
-      event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: payload.prompt || '' };
+      const userPrompt = capField(payload.prompt || '');
+      event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: userPrompt.value, promptChars: userPrompt.chars };
     } else {
       const tool = payload.tool_name;
       if (!tool) return null;
@@ -156,7 +183,9 @@ export async function run(payload) {
       } else if (tool === 'Agent' || tool === 'Task') {
         event.persona = input.subagent_type || '';
         if (input.description) event.desc = input.description;
-        event.prompt = input.prompt || '';
+        const dispatchPrompt = capField(input.prompt || '');
+        event.prompt = dispatchPrompt.value;
+        event.promptChars = dispatchPrompt.chars;
       } else if (tool === 'Read') {
         event.target = targetFilePath || normalize(input.file_path || input.path);
         event.kind = classifyReadKind(event.target);
@@ -169,7 +198,9 @@ export async function run(payload) {
           // omit bytes
         }
       } else if (tool === 'Bash') {
-        event.command = input.command || '';
+        const bashCommand = capField(input.command || '');
+        event.command = bashCommand.value;
+        event.commandChars = bashCommand.chars;
       } else if (tool === 'Write' || tool === 'Edit') {
         event.target = normalize(input.file_path || input.path);
       } else {

package/framework/hooks/claude-code/core/validate-completion.js

@@ -21,7 +21,7 @@
  * Fail-open: exits 0 on any error.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
 import { runBuildCheck } from '../../shared/build-check.js';
@@ -30,6 +30,7 @@ import {
 } from '../../shared/state-reader.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
+import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
 
 /**
  * Audit recap.md against tasks.json + standard-citation rule.
@@ -121,6 +122,80 @@ function auditRecapAndTasks(featurePath) {
   return warnings;
 }
 
+// Safety valve for a pathological outlier transcript — NOT needed for the
+// normal case: a real 45 MB / ~16k-line transcript (inspected directly while
+// building this) parses+sums in ~350ms locally, well inside a Stop hook's
+// budget. Above this, skip rather than risk an unbounded read.
+const MAX_TRANSCRIPT_BYTES = 50 * 1024 * 1024; // 50 MB
+
+/**
+ * Sum real token usage from a Claude Code session transcript (JSONL, the
+ * `transcript_path` the Stop payload carries).
+ *
+ * Each assistant TURN is written to the transcript as MULTIPLE JSONL lines —
+ * one per content block (thinking/text/tool_use) — every one of them
+ * repeating the exact SAME turn-level `message.usage` object under the same
+ * `message.id`. Verified against a real transcript: 5982 assistant lines but
+ * only 3315 unique message ids, with byte-identical usage across duplicates
+ * of the same id — summing every line naively double/triple-counts (measured
+ * ~2x on output_tokens on that file). This is why a per-line sum is wrong and
+ * a dedup-by-id sum is required; there is no running/cumulative total field
+ * to lean on instead — each turn's `usage` is that turn's own cost.
+ *
+ * Tolerant to shape: any missing usage field reads as 0. A corrupt/truncated
+ * line is skipped, not fatal — same discipline as telemetry-logger's reader.
+ *
+ * @param {string} [transcriptPath]
+ * @returns {{inputTokens:number,outputTokens:number,cacheReadTokens:number,cacheCreationTokens:number}|null}
+ *   null when there is nothing to report (no path, missing/oversized/
+ *   unreadable file, or zero assistant messages carrying usage).
+ */
+function computeSessionUsage(transcriptPath) {
+  if (!transcriptPath || typeof transcriptPath !== 'string') return null;
+  try {
+    if (!existsSync(transcriptPath)) return null;
+    if (statSync(transcriptPath).size > MAX_TRANSCRIPT_BYTES) return null;
+
+    const raw = readFileSync(transcriptPath, 'utf-8');
+    let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheCreationTokens = 0;
+    const seenMessageIds = new Set();
+    let sawAny = false;
+
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let entry;
+      try {
+        entry = JSON.parse(trimmed);
+      } catch {
+        continue; // one corrupt/truncated line must not lose the whole transcript
+      }
+      if (entry?.type !== 'assistant') continue;
+      const usage = entry?.message?.usage;
+      if (!usage || typeof usage !== 'object') continue;
+
+      // Dedup by message.id (fallback to the line's own uuid when a message
+      // carries none) — first occurrence wins, duplicates carry identical
+      // values so which one wins never matters.
+      const dedupKey = entry?.message?.id || entry?.uuid;
+      if (dedupKey) {
+        if (seenMessageIds.has(dedupKey)) continue;
+        seenMessageIds.add(dedupKey);
+      }
+
+      sawAny = true;
+      inputTokens += Number(usage.input_tokens) || 0;
+      outputTokens += Number(usage.output_tokens) || 0;
+      cacheReadTokens += Number(usage.cache_read_input_tokens) || 0;
+      cacheCreationTokens += Number(usage.cache_creation_input_tokens) || 0;
+    }
+
+    return sawAny ? { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens } : null;
+  } catch {
+    return null; // fail-open
+  }
+}
+
 // Phases where compaction is strongly recommended before starting
 const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 
@@ -128,12 +203,15 @@ const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 const HEAVY_SOURCE_PHASES = new Set(['plan', 'uiux']);
 
 /**
- * @param {object} _payload - parsed Stop stdin payload (unused — this hook
- *   reads its own state from disk, not from the tool payload)
+ * @param {object} payload - parsed Stop stdin payload. Most of this hook's
+ *   logic reads its own state from disk rather than the payload, EXCEPT the
+ *   session-usage capture below, which needs `payload.transcript_path` (and
+ *   `payload.session_id` for the throttle key) — the one thing only the
+ *   payload carries.
  * @returns {Promise<object|null>} a hookSpecificOutput advisory (phase
  *   transition / build failure / recap drift), or null (pass/silent).
  */
-export async function run(_payload) {
+export async function run(payload) {
   try {
     // Prevent infinite loop
     if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') return null;
@@ -264,6 +342,40 @@ export async function run(_payload) {
     }
     // ────────────────────────────────────────────────────────────────────────
 
+    // ── Session usage (real tokens, from the transcript) ──────────────────────
+    // Silent side effect — never contributes to `warnings`/additionalContext,
+    // same as telemetry-log.js's capture. Throttled: only re-emitted when the
+    // computed totals actually changed since the last SessionUsage recorded
+    // for this session_id, so an unchanged transcript across consecutive
+    // Stops (no new assistant turn) does not re-append an identical event.
+    try {
+      const usage = computeSessionUsage(payload?.transcript_path);
+      if (usage) {
+        const usagePath = join(memDir, 'session-usage.json');
+        let stored = {};
+        try {
+          if (existsSync(usagePath)) stored = JSON.parse(readFileSync(usagePath, 'utf-8'));
+        } catch { /* corrupt file — start fresh */ }
+
+        const sessionKey = payload?.session_id || 'default';
+        const last = stored[sessionKey];
+        const unchanged = last
+          && last.inputTokens === usage.inputTokens
+          && last.outputTokens === usage.outputTokens
+          && last.cacheReadTokens === usage.cacheReadTokens
+          && last.cacheCreationTokens === usage.cacheCreationTokens;
+
+        if (!unchanged) {
+          appendTelemetryEvent({ event: 'SessionUsage', ...usage }, cwd);
+          stored[sessionKey] = usage;
+          try { writeFileSync(usagePath, JSON.stringify(stored, null, 2), 'utf-8'); } catch { /* non-blocking */ }
+        }
+      }
+    } catch {
+      // Fail-open — usage capture must never block Stop
+    }
+    // ────────────────────────────────────────────────────────────────────────
+
     if (warnings.length === 0) return null;
 
     const message = [

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

@@ -27,7 +27,10 @@
  * Also the real call site for activity-log rotation (R1.2 of the performance
  * plan): SessionStart is the only reliable "between sessions" checkpoint the
  * harness gets, so this is where `.morph/logs/activity.jsonl` gets archived
- * to `.morph/logs/sessions/` once it crosses the size threshold.
+ * to `.morph/logs/sessions/` once it crosses the size threshold. The same
+ * checkpoint now also rotates `.morph/logs/events.jsonl` (telemetry-logger.js)
+ * once IT crosses its own threshold — events.jsonl grew unbounded even after
+ * R1.2, since that rotation only ever covered activity.jsonl.
  *
  * Fail-open: any error, or nothing to report, → pass() silently. This hook
  * never blocks a session from starting.
@@ -46,6 +49,7 @@ import {
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registry.js';
 import { rotateActivityLogIfLarge } from '../../shared/activity-logger.js';
+import { rotateEventsLogIfLarge } from '../../shared/telemetry-logger.js';
 
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -223,10 +227,11 @@ export async function run(payload) {
       return null;
     }
 
-    // Rotate the activity log before anything else touches it this session.
-    // Best-effort, never fatal to session start — rotateActivityLogIfLarge()
-    // is itself fail-open (returns false on any error).
+    // Rotate the activity + events logs before anything else touches them
+    // this session. Best-effort, never fatal to session start — both rotate*
+    // helpers are themselves fail-open (return false on any error).
     try { rotateActivityLogIfLarge(dir); } catch { /* non-blocking */ }
+    try { rotateEventsLogIfLarge(dir); } catch { /* non-blocking */ }
 
     if (isSecondaryWorktree(dir)) {
       const feature = featureFromBranch(dir) || featureFromSingleDir(dir);

package/framework/hooks/shared/telemetry-logger.js

@@ -16,12 +16,22 @@
  * - Windows-safe paths via path.join
  */
 
-import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'fs';
+import {
+  appendFileSync, readFileSync, mkdirSync, existsSync, statSync, renameSync,
+} from 'fs';
 import { join, dirname } from 'path';
 
 const LOGS_DIR = '.morph/logs';
 export const EVENTS_FILE = join(LOGS_DIR, 'events.jsonl');
 
+// SessionStart (worktree-context.js) rotates events.jsonl once it crosses
+// this size, alongside the pre-existing activity.jsonl rotation — same
+// call site, same "between sessions" checkpoint. events.jsonl has no natural
+// per-turn cap (prompts/commands are truncated at the write site, but the
+// LINE COUNT itself grows unbounded across a long-lived project), so without
+// this it grows forever the way activity.jsonl used to before R1.2.
+export const ROTATE_THRESHOLD_BYTES = 5 * 1024 * 1024; // 5 MB
+
 function getEventsPath(projectPath) {
   return join(projectPath || process.cwd(), EVENTS_FILE);
 }
@@ -73,3 +83,56 @@ export function readTelemetryEvents(projectPath) {
     return [];
   }
 }
+
+/**
+ * Archive the current events.jsonl to `.morph/logs/sessions/`, mirroring
+ * activity-logger.js's `archiveSession()` — same directory, same rename-not-
+ * rewrite mechanics (O(1) even at multi-MB sizes). Named with an `events-`
+ * prefix (activity-logger's archives carry no prefix) so the two streams
+ * never collide inside the shared `sessions/` directory and stay
+ * distinguishable at a glance.
+ *
+ * Fail-silent — called only from `rotateEventsLogIfLarge` below, which has
+ * already confirmed the file exists.
+ *
+ * @param {string} [projectPath]
+ */
+function archiveEvents(projectPath) {
+  try {
+    const eventsPath = getEventsPath(projectPath);
+    if (!existsSync(eventsPath)) return;
+
+    const sessionsDir = join(projectPath || process.cwd(), LOGS_DIR, 'sessions');
+    mkdirSync(sessionsDir, { recursive: true });
+
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const archivePath = join(sessionsDir, `events-${stamp}.jsonl`);
+    renameSync(eventsPath, archivePath);
+  } catch {
+    // Fail-silent
+  }
+}
+
+/**
+ * Rotate events.jsonl when it crosses `thresholdBytes`. Called from
+ * worktree-context.js on SessionStart, right next to the existing
+ * `rotateActivityLogIfLarge()` call — the only reliable "between sessions"
+ * checkpoint the harness gets. `thresholdBytes` is injectable so a test can
+ * force rotation without writing multiple megabytes.
+ *
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ * @param {number} [thresholdBytes] - Rotate once the log is at least this large
+ * @returns {boolean} true if a rotation was performed
+ */
+export function rotateEventsLogIfLarge(projectPath, thresholdBytes = ROTATE_THRESHOLD_BYTES) {
+  try {
+    const eventsPath = getEventsPath(projectPath);
+    if (!existsSync(eventsPath)) return false;
+    const { size } = statSync(eventsPath);
+    if (size < thresholdBytes) return false;
+    archiveEvents(projectPath);
+    return true;
+  } catch {
+    return false;
+  }
+}

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"] },