@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

package/framework/evals/rubrics/code-quality.md

@@ -11,7 +11,7 @@ Avalia naming, ausência de code smells e aderência aos padrões do stack do pr
 - **Nada do que foi criado aqui já existia no projeto**: os conceitos novos batem com o veredito do `reuse-map.md`, e cada `CRIAR` tem justificativa que se sustenta.
 - Segue os padrões do stack conforme os standards do projeto (ex: Result pattern para .NET, hooks pattern para React).
 - Sem "dead code" — sem variáveis não usadas, sem blocos comentados, sem imports desnecessários.
-- Comentário só com o porquê que o código não mostra (`architecture-code-comments`): nenhum conta história de task, UC, ADR, Gate ou avaliador.
+- Quase nenhum comentário: nome, tipo e teste explicam o código. O que sobra é só o porquê que o código não mostra (`architecture-code-comments`), sem `///`/JSDoc que repete a assinatura, banner de seção nem história de task, UC, ADR, Gate ou avaliador.
 
 ## Score 7-8 — Bom
 
@@ -21,7 +21,7 @@ Avalia naming, ausência de code smells e aderência aos padrões do stack do pr
 - No máximo um conceito recriado que já existia no codebase, com impacto pequeno e localizado.
 - Segue padrões do stack com desvios isolados e justificáveis.
 - Sem dead code significativo.
-- Um ou outro comentário que repete o código; nenhum narra o processo.
+- Um ou outro comentário que repete o código ou doc-comment dispensável; nenhum narra o processo.
 
 ## Score 5-6 — Aceitável com ressalvas
 
@@ -31,7 +31,7 @@ Avalia naming, ausência de code smells e aderência aos padrões do stack do pr
 - Um ou dois tipos/componentes recriados que já existiam em outro arquivo do projeto.
 - Desvios dos padrões do stack sem justificativa.
 - Dead code pontual.
-- Comentário de processo (UC, ADR, `T{n}`, Gate, `spec.md`, mockup) ou comentário afirmando comportamento que nenhum teste cobra.
+- Comentário de processo (UC, ADR, `T{n}`, Gate, `spec.md`, mockup), comentário afirmando comportamento que nenhum teste cobra, ou `///`/JSDoc em todo membro de aplicação repetindo a assinatura.
 
 ## Score 3-4 — Problemático
 
@@ -95,4 +95,4 @@ chave `obs` no `**Proof-Scores:**`, também não há teto a aplicar.
 3b. **O que foi criado aqui já existia no projeto?** Confira os tipos, componentes, hooks e serviços novos contra o `reuse-map.md` e contra o grafo — e diga no relatório o que você conferiu.
 4. O código segue os padrões definidos nos standards do projeto?
 5. Há variáveis não usadas, imports desnecessários ou blocos comentados?
-6. Algum comentário conta história de processo, repete o código ou passa de ~3 linhas sem justificar? O validador `code-budget` do nó `validators` já conta, nas linhas adicionadas, os comentários que citam processo; leia os citados antes de pontuar.
+6. Algum comentário existe onde um nome, uma função extraída, um tipo ou um teste bastaria? Algum conta história de processo, repete o código ou a assinatura, ou passa de ~3 linhas sem justificar? O validador `code-budget` do nó `validators` já conta, nas linhas adicionadas, os comentários que citam processo e a densidade de comentário sobre código; leia os arquivos citados antes de pontuar.

package/framework/evals/rubrics/condensed.md

@@ -30,7 +30,7 @@ Se o diff toca endpoint minimal API ou fetch cross-camada, independente do resto
 |---|---|---|---|---|
 | **Arquitetura** | Ignora a arquitetura do spec.md; sem feature folder; deps circulares; ou violação mecânica acima | Pastas corretas, responsabilidades se misturam; deps cross-feature sem justificativa; domain acoplado a infra | Desvios menores justificados; deps cross-feature via abstração; impurezas de infra pontuais | Feature folder rigoroso; zero deps cross-feature diretas; domain isolado; DI onde exige |
 | **Contratos** | Sem tipos ou `any` generalizado; zero validação; sem tratamento de erro; naming arbitrário | `any`/genérico visível; validação parcial; mix exceptions/Result; naming inconsistente | Tipos bem definidos, `any` raro e justificado; validação na maioria; erro consistente | Zero `any`; validação em todos endpoints; Result pattern/discriminated union; naming consistente |
-| **Qualidade** | Nomes arbitrários; god objects; duplicação massiva; recria o que o `reuse-map` mandou REUSAR; fora do padrão do stack | Nomes genéricos (`data`,`temp`); funções >30 linhas; duplicação perceptível; conceito da MESMA feature redeclarado; comentário que narra task/UC/ADR | Nomes claros, raras exceções; bem dimensionado; duplicação mínima; no máximo um conceito recriado | Nomes comunicam intenção; funções ≤20-25 linhas, 1 responsabilidade; zero duplicação/dead code; nada criado que já existia no projeto; comentário só com o porquê |
+| **Qualidade** | Nomes arbitrários; god objects; duplicação massiva; recria o que o `reuse-map` mandou REUSAR; fora do padrão do stack | Nomes genéricos (`data`,`temp`); funções >30 linhas; duplicação perceptível; conceito da MESMA feature redeclarado; comentário que narra task/UC/ADR ou `///`/JSDoc repetindo a assinatura | Nomes claros, raras exceções; bem dimensionado; duplicação mínima; no máximo um conceito recriado | Nomes comunicam intenção; funções ≤20-25 linhas, 1 responsabilidade; zero duplicação/dead code; nada criado que já existia no projeto; quase nenhum comentário, só o porquê que o código não mostra |
 | **Testes** | Sem testes ou sem asserts reais; zero edge case; nomes genéricos | Happy path OK, edge cases parciais; erros só óbvios; testes interdependentes; teste de texto de arquivo sem substituto em runtime; cópias em vez de tabela ou excesso sem justificativa | Happy path completo; maioria dos edge cases; erros nos fluxos principais | Toda pós-condição do `usecase` tem teste; A1/A2 cobertos; edge+erro cobertos, em tabela; isolados; dentro do orçamento |
 
 > **Qualidade olha o CODEBASE, não só o diff.** Símbolo novo cujo nome já existe no projeto não aparece no diff — é preciso perguntar de fora dele. O nó `validators` do `morph-spec verify` já traz os achados do validador `reuse`; o `2-plan/reuse-map.md` diz o que o plano decidiu por conceito.
@@ -39,7 +39,7 @@ Se o diff toca endpoint minimal API ou fetch cross-camada, independente do resto
 
 > Teste que só lê texto de arquivo não cobre pós-condição de comportamento: sem substituto em runtime, ela conta como sem teste (herdado de `test-coverage.md`, pergunta 7).
 
-> Orçamento por task: um teste por pós-condição + um de regressão por bug, cenários do mesmo comportamento numa tabela; teste que só fixa copy é achado (herdado de `test-coverage.md`, pergunta 8). O validador `code-budget` do nó `validators` avisa sobre teste acima de 1,5× a produção e sobre comentário que cita processo.
+> Orçamento por task: um teste por pós-condição + um de regressão por bug, cenários do mesmo comportamento numa tabela; teste que só fixa copy é achado (herdado de `test-coverage.md`, pergunta 8). O validador `code-budget` do nó `validators` avisa sobre teste acima de 1,5× a produção, sobre comentário que cita processo e sobre densidade de comentário acima de 1 linha a cada 10 de código.
 
 > Task de UI cuja tela tem `### Checklist de tela` no `1-design/mockups.md`: item divergente sem justificativa em `decisions.md` → teto 8 em Contratos; paginação, ordenação ou filtro que o checklist põe no servidor entregue em memória (ou ausente), ou estado vazio/carregando/erro decidido e ausente → teto 6 (herdado de `contracts.md`, "Contrato de tela").
 

package/framework/mcp/registry.json

@@ -5,6 +5,7 @@
     "context7": {
       "phases": ["proposal", "plan", "implement"],
       "tools": ["resolve-library-id", "query-docs"],
+      "serverNames": ["context7", "plugin_context7_context7"],
       "detection": "enabledPlugins includes context7 or mcpServers includes context7",
       "fallback": "WebSearch + WebFetch for library documentation",
       "usage": "Library documentation lookups, API reference, implementation patterns",
@@ -33,7 +34,8 @@
     "playwright": {
       "phases": ["uiux", "implement"],
       "tools": ["browser_navigate", "browser_snapshot", "browser_take_screenshot", "browser_console_messages", "browser_click", "browser_resize"],
-      "detection": "mcpServers includes playwright",
+      "serverNames": ["playwright", "plugin_playwright_playwright"],
+      "detection": "mcpServers includes playwright or enabledPlugins includes playwright",
       "fallback": "WebFetch for read-only page content, manual testing",
       "usage": "UI preview, smoke testing, page inspection, responsive testing, screenshot capture",
       "healthCheck": {
@@ -168,6 +170,7 @@
     "gemini-image": {
       "phases": ["uiux", "implement"],
       "tools": ["generate_image", "edit_image", "continue_editing", "list_images", "get_image_info", "get_configuration_status"],
+      "serverNames": ["gemini-image", "gemini-image-mcp"],
       "detection": "mcpServers includes gemini-image-mcp",
       "fallback": "Manual image creation, stock photos, or placeholder divs",
       "usage": "AI image generation for project assets (heroes, illustrations, brand images) using Gemini models",
@@ -285,9 +288,37 @@
         ],
         "setupGuide": null
       }
+    },
+    "neon": {
+      "phases": ["plan", "implement"],
+      "tools": ["list_projects", "describe_table_schema", "get_database_tables", "run_sql", "explain_sql_statement", "prepare_database_migration", "complete_database_migration", "compare_database_schema", "create_branch", "list_branches", "get_connection_string"],
+      "serverNames": ["neon", "Neon"],
+      "detection": "mcpServers includes neon (case-insensitive)",
+      "fallback": "SQL via the connection string (psql / dotnet ef) and the neonctl CLI for branches",
+      "usage": "Schema inspection, migration dry-run on a throwaway branch (prepare_database_migration → complete_database_migration), query tuning. The server exposes DESTRUCTIVE tools (delete_branch, delete_project, reset_from_parent): never call one without explicit human confirmation",
+      "healthCheck": {
+        "toolPattern": "neon",
+        "testCall": "Call list_projects with limit 1",
+        "testParams": { "limit": 1 },
+        "successIndicator": "Returns the project list (possibly empty)",
+        "failureHint": "Neon MCP not responding. Re-run the OAuth flow: claude mcp add --transport http neon https://mcp.neon.tech/mcp"
+      },
+      "install": {
+        "autoInstall": false,
+        "transport": "http",
+        "config": {
+          "type": "http",
+          "url": "https://mcp.neon.tech/mcp"
+        },
+        "credentials": [],
+        "prerequisites": [],
+        "stackRelevance": ["neon"],
+        "warnings": ["OAuth against your Neon account on first use. The server can delete branches and projects: keep destructive calls behind a human."],
+        "setupGuide": "Run: claude mcp add --transport http neon https://mcp.neon.tech/mcp"
+      }
     }
   },
-  "_phaseMatrixNote": "Keys must be the v5 phases from framework/phases.json. The v4 keys 'design' and 'tasks' both collapsed into 'plan'; 'review' was absent entirely, so a project in review resolved to undefined. Stack-scoped MCPs (asaas) stay out of this matrix on purpose — only universal ones are listed.",
+  "_phaseMatrixNote": "Keys must be the v5 phases from framework/phases.json. The v4 keys 'design' and 'tasks' both collapsed into 'plan'; 'review' was absent entirely, so a project in review resolved to undefined. Stack-scoped MCPs (asaas, neon) stay out of this matrix on purpose — only universal ones are listed.",
   "phaseMatrix": {
     "proposal": ["context7", "graphify"],
     "uiux": ["playwright", "context7", "stitch", "gemini-image", "seedance"],

package/framework/rules/infrastructure-standards.md

@@ -12,7 +12,6 @@ stacks:
 
 @.morph/framework/standards/infrastructure/docker/coolify-deploy.md
 @.morph/framework/standards/infrastructure/docker/local-compose-isolation.md
-@.morph/framework/standards/infrastructure/docker/local-compose-isolation.md
 
 ## Infrastructure Templates
 

package/framework/rules/morph-workflow.md

@@ -192,16 +192,21 @@ Every task in `tasks.json` MUST reference its FR(s) in the `description` field s
 
 ## Debugging
 
-When a bug or unexpected behavior shows up mid-task, invoke `superpowers:systematic-debugging`
-with the `Skill()` tool **before proposing a fix** — root cause first, never a patch on the
-symptom. This is MANDATORY; do NOT skip it.
+When a bug or unexpected behavior shows up mid-task, find the **root cause before proposing a
+fix** — never a patch on the symptom. This is MANDATORY:
+
+1. Reproduce it and read the full error, not the first line.
+2. For a known .NET/Next.js error, run `/morph-troubleshoot <keywords>` first.
+3. One hypothesis at a time, each tested by the smallest check that could refute it.
+4. After three failed fixes, stop and question the design instead of trying a fourth.
+5. Confirm the fix with the same check that reproduced the bug; add a test only when no existing one covers that behavior.
 
 Everything else that a rule like this might list is owned by the flow itself, and duplicating it
 here would put a second, staler copy in permanent context:
 
 | Concern | Where it actually lives |
 |---------|-------------------------|
-| TDD before writing code | The feature's `mandate.md` (TDD is built in) — the resident `.claude/CLAUDE.md` says to prefer `morph-*` over the generic `superpowers:*` equivalents |
+| How many tests to write | The test budget copied into the feature's `mandate.md`: one test per postcondition, same-behavior cases in one table, no test that only pins text |
 | Verifying a task before `status: "done"` | `morph-spec verify {feature} [task]` (build + tests + validators + e2e), then the `morph-eval` skill for the 0-10 score |
 | Parallel dispatch | `morph-spec dag {feature}` decides sequential vs parallel; execution and isolation rules are in `morph-apply` §2/§3b |
 | Closing the phase / opening the PR | `morph-review` for Gate 3, then `morph-spec finish {feature} --pr\|--merge` |

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.38.0"
+cliVersion: "8.40.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.38.0"
+cliVersion: "8.40.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.38.0"
+cliVersion: "8.40.0"
 ---
 
 # morph-apply
@@ -176,6 +176,10 @@ dispatch Agent (subagent_type: "morph-{id}") with prompt:
     Leitura: não releia o que este prompt já traz. Em arquivo grande, `Grep`
     acha a linha e `Read` com `offset`/`limit` lê só o trecho; leituras que não
     dependem uma da outra vão no mesmo turno, em paralelo.
+    Comentário: o padrão é nenhum. Nome, tipo e teste explicam o código; sem
+    `///`/JSDoc em membro de aplicação, cabeçalho, banner de seção ou história
+    da task. Só o porquê que o código não mostra, em uma linha
+    (`architecture-code-comments`).
     Não modifique spec.md, mandate.md.
 
     Contrato do relatório final:

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.38.0"
+cliVersion: "8.40.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.38.0"
+cliVersion: "8.40.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.38.0"
+cliVersion: "8.40.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.38.0"
+cliVersion: "8.40.0"
 ---
 
 # morph-implement
@@ -78,6 +78,11 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    acha a linha e `Read` com `offset`/`limit` lê só o trecho; leituras que não
    dependem uma da outra vão no mesmo turno, em paralelo.
 
+   Comentário: o padrão é nenhum. Nome, tipo e teste explicam o código; sem
+   `///`/JSDoc em membro de aplicação, cabeçalho, banner de seção ou história
+   da task. Só o porquê que o código não mostra, em uma linha
+   (`architecture-code-comments`).
+
    Contrato do relatório final:
    1. GRAVE `.morph/features/{feature}/3-implement/reports/[ID].md` ANTES de
       encerrar — é o retorno autoritativo, não a sua mensagem final (que é

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

@@ -4,7 +4,7 @@ description: Conduz a AUTORIA de mídia gerada por IA — escolher o modelo pelo
 version: core
 when-to-invoke: quando a tarefa é PRODUZIR imagem ou vídeo por IA (catálogo, marketing, asset de LP) e alguém precisa decidir modelo, prompt e aprovação
 user-invokable: true
-cliVersion: "8.38.0"
+cliVersion: "8.40.0"
 stacks:
   - dotnet
   - nextjs

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.38.0"
+cliVersion: "8.40.0"
 ---
 
 # morph-plan
@@ -220,8 +220,9 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
      proibidos: o orçamento por task do passo 5 (um teste por pós-condição + um de regressão por
      bug, justificativa acima disso, tabela antes de cópia, nenhum teste que só fixa texto);
      fixture compartilhada antes de helper novo; TDD onde paga (bug: regressão primeiro; lógica
-     pura), teste depois aceito em UI e integração; comentário só com o porquê que o código não
-     mostra, nunca história de task/UC/ADR. Nos standards obrigatórios, liste
+     pura), teste depois aceito em UI e integração; comentário: o padrão é nenhum (nome, tipo e teste
+     explicam), só o porquê que o código não mostra, nunca `///`/JSDoc que repete a assinatura
+     nem história de task/UC/ADR. Nos standards obrigatórios, liste
      `architecture-code-comments` e o standard de teste do stack (seção *Test budget*).
    - **Baseline é um COMANDO, nunca um número.** O mandate congela no Gate 2 e é lido por
      implementadores durante dias — todo número cravado nele (`Suíte: 2366 passando`, cobertura,

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.38.0"
+cliVersion: "8.40.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.38.0"
+cliVersion: "8.40.0"
 ---
 
 # morph-review

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.38.0"
+cliVersion: "8.40.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.38.0"
+cliVersion: "8.40.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.38.0"
+cliVersion: "8.40.0"
 ---
 
 # morph-uiux
@@ -32,11 +32,11 @@ Ao tomar o ramo opcional uiux: feature/bug cuja mudança cria ou altera superfí
    - **Sistemas, não telas isoladas** — mesmo critério da persona `ui-designer`: componentes reutilizáveis antes de composições de uso único.
    - **Toda tela sai com o checklist de tela preenchido** (template no passo 3) — a superfície, o volume esperado de dados, paginação, ordenação, filtro, os três estados (vazio, carregando, erro), o comportamento no mobile e abas × página longa. "Não se aplica" vale, **desde que escrito**. É o checklist que faz a lista de 2 000 linhas paginar: o que o design não decide não vira `doneCriteria` (`morph-plan` §5d), e o que não é critério ninguém entrega. Tela de dados segue os standards de `admin-app` (lista/tabela, formulário, feedback, estrutura de página), que a persona cita na superfície `admin-app`.
 
-3. **Despache `morph-ui-designer`** para o trabalho visual — dispatch é o default aqui (domínio diferente do Orchestrator, MORPH.md §6). `morph-ui-designer` tem `Read/Write/Edit/Glob/Grep` + MCPs `stitch`/`gemini-image`/`playwright`/`context7`, mas **não tem Bash** — não peça build, testes nem `morph-spec` a ele; isso é do orquestrador.
+3. **Despache `morph-ui-designer`** para o trabalho visual — dispatch é o default aqui (domínio diferente do Orchestrator, MORPH.md §6). `morph-ui-designer` tem o escopo das implementadoras (com Bash) + `Skill` + MCPs `stitch`/`gemini-image`/`playwright`/`context7`/`seedance`/`graphify`. Bash serve para `morph-spec standards --find`, `npx`, screenshot e leitura de `git`; build/test da suíte, `verify` e aprovação de gate continuam do orquestrador (cláusula 3, como nas outras personas).
 
    **Persona universal** (`ui-designer.stack = ["*"]` em `agents.json`, mesmo mecanismo de `evaluator`/`scout`): UI/UX importa sempre que há superfície de UI, então o subagent está registrado em **todo** projeto — .NET/Blazor incluído, não só Next.js. **Fallback** (caso raro: instalação anterior a essa mudança, `.claude/agents/morph-ui-designer.md` ainda não regenerado): `general-purpose` colando o campo `persona` (Read em `.morph/framework/agents.json`) no prompt, registrando o fallback no relatório — resolvido rodando `morph-spec setup-infra --reinstall`.
 
-   Template do prompt (contrato do relatório em forma curta — copia o padrão de `morph-implement` §4, sem a cláusula de build/isolamento, que não se aplica a um agente sem Bash):
+   Template do prompt (contrato do relatório em forma curta — copia o padrão de `morph-implement` §4; a cláusula de build/isolamento vira "sem build/test da suíte", porque o design não entrega código a verificar):
    ```
    Produzir os artefatos de UI/UX de [feature] em `.morph/features/{feature}/1-design/`.
 
@@ -82,8 +82,9 @@ Ao tomar o ramo opcional uiux: feature/bug cuja mudança cria ou altera superfí
       `1-design/reports/[artefato]-report.md` (ex.: `1-design/reports/design-system-report.md`)
       ANTES de encerrar — é o retorno autoritativo, não a sua mensagem final (cortesia
       best-effort, pode não chegar inteira). NÃO chame SendMessage.
-   2. Você não tem Bash — não rode `morph-spec`, build nem testes; a aprovação do Gate uiux
-      e qualquer comando CLI são do orquestrador.
+   2. Bash só para consulta (`morph-spec standards --find`, `npx`, screenshot, `git log/diff`):
+      NÃO rode build, testes nem `morph-spec verify`/`approve`/`advance` — a verificação e a
+      aprovação do Gate uiux são do orquestrador.
    3. NÃO toque em tasks.json, feature.json, state.json nem no board de sessão.
 
    Cada relatório contém: (1) o que foi feito em 2-3 frases, (2) o artefato produzido,

package/framework/standards/STANDARDS.json

@@ -2689,8 +2689,8 @@
         "tools": "#mcp-providers-by-phase",
         "setup": "#mcp-availability-detection"
       },
-      "digest": "MCP tools extend Claude with external data and actions. Tools are synchronous request-response with typed inputSchema. Resources provide read-only data access. Prompts are reusable templates. Register MCP servers in .claude/settings.json. Prefer @context7 for live library docs. Test tools with MCP Inspector before integrating.",
-      "verifiedAgainst": "Claude Code MCP tooling — context7, Playwright; GitHub via `gh` CLI; Neon via `neonctl`.",
+      "digest": "MCP tools extend Claude with external data and actions. Tools are synchronous request-response with typed inputSchema. Resources provide read-only data access. Prompts are reusable templates. Register MCP servers in .claude/settings.json. Prefer @context7 for live library docs. Tool names follow where the server is configured: mcp__context7__query-docs from .mcp.json, mcp__plugin_context7_context7__query-docs from the plugin; a deferred tool loads via ToolSearch. Test tools with MCP Inspector before integrating.",
+      "verifiedAgainst": "Claude Code 2.1.282 MCP tooling — context7, Playwright (as plugin and as a project MCP server); GitHub via `gh` CLI; Neon via its MCP or `neonctl`.",
       "provedBy": []
     },
     {
@@ -2848,7 +2848,7 @@
         "not-worth": "#o-que-não-merece",
         "size": "#tamanho"
       },
-      "digest": "Comment only the WHY the code cannot show: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), a public API contract. Never process history: task, UC, ADR, FR, Gate, evaluator, spec.md and mockup belong in the commit message and decisions.md. Do not restate the code (a good name replaces the comment), do not describe the world outside the file (it goes stale), and turn claims about behavior into test assertions. Ceiling ~3 lines; longer needs a reason. The verify validators node (code-budget) warns with the count of added comment lines that cite process.",
+      "digest": "Default is NO comment: code explains itself through names, types and tests. Before commenting, rename, extract a function or named constant, encode the state in the type, or write a test; comment only what none of these can express: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), or the contract of a package published for consumers outside the repo. Never process history (task, UC, ADR, FR, Gate, evaluator, spec.md, mockup: commit message and decisions.md), never restate the code, no XML doc/JSDoc on application members that repeats the signature, no file headers, section banners, #region, commented-out code or loose TODOs, no claims about behavior (make them test assertions). One line is normal, ~3 is the ceiling; more than one comment line per ten code lines means the names are not doing the work. The verify validators node (code-budget) warns on added comments that cite process and on added comment density.",
       "verifiedAgainst": "C#, TypeScript e JavaScript (convenção de linguagem, sem pacote externo).",
       "provedBy": []
     }

package/framework/standards/ai-agents/context-providers.md

@@ -30,8 +30,7 @@ Preciso que o agente saiba X.
 Plano por fase (instruções + **allow-list de tools** conforme o estado do funil) **não** é caso de provider. É C# puro, montado antes de criar a requisição:
 
 ```csharp
-// O CÓDIGO decide o modo; o LLM só classifica. A allow-list de tools é a parte
-// que um provider não consegue dar: AIContext.Tools ACRESCENTA tools, não remove.
+// A allow-list não cabe num provider: AIContext.Tools ACRESCENTA tools, não remove.
 public sealed record OperatorPlan(string Instructions, IReadOnlyList<AITool> Tools);
 
 public static OperatorPlan PlanFor(FunnelStage stage) => stage switch
@@ -92,10 +91,8 @@ Use um `AIContextProvider` quando o agente precisa de **contexto dinâmico compu
 
 **Método a sobrescrever:**
 
-```csharp
-// ProvideAIContextAsync  → chamado ANTES do LLM (before-run hook) — injeta contexto
-// StoreAIContextAsync    → chamado APÓS o LLM (after-run hook) — persiste estado se necessário
-```
+- `ProvideAIContextAsync` → chamado ANTES do LLM (before-run hook) — injeta contexto
+- `StoreAIContextAsync` → chamado APÓS o LLM (after-run hook) — persiste estado se necessário (opcional)
 
 ### A invariante de instância — a mesma de `ai-agents-agent-session`
 
@@ -122,32 +119,33 @@ Consequência prática: **compaction só faz sentido com histórico local**. Com
 
 ## Exemplo C# — context provider que injeta data atual e perfil do tenant
 
+O bloco tem três partes: o provider, o registro do agente com o provider no DI (`Program.cs`) e o uso
+normal. `ITenantContext` é implementado via `IHttpContextAccessor` ou `AsyncLocal` para resolver o
+tenant em runtime, nunca registrado como instância estática. O contexto volta como instrução
+adicional, não como mensagem do usuário, e `StoreAIContextAsync` fica vazio porque o provider é
+stateless. No uso, o provider é invocado a cada `RunAsync`: o agente já sabe a data, o nome do tenant
+e o idioma, sem código extra no caller.
+
 ```csharp
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
-// ── 1. Definir o provider ──
 public sealed class TenantContextProvider : AIContextProvider
 {
     private readonly ITenantService _tenantService;
     private readonly ITenantContext _tenantContext;
 
-    // ITenantContext deve ser implementado via IHttpContextAccessor ou AsyncLocal
-    // para resolver o tenant atual em runtime — não registre como instância estática.
-    // O AIAgent é singleton, então o provider também é singleton; o tenant corrente
-    // é lido de forma ambient (IHttpContextAccessor/AsyncLocal) a cada chamada.
+    // Singleton como o AIAgent: o tenant corrente é lido ambient a cada chamada, nunca guardado.
     public TenantContextProvider(ITenantService tenantService, ITenantContext tenantContext)
     {
         _tenantService = tenantService;
         _tenantContext = tenantContext;
     }
 
-    // Sobrescreva: injetado ANTES de cada chamada ao LLM
     protected override async ValueTask<AIContext> ProvideAIContextAsync(
         InvokingContext context,
         CancellationToken cancellationToken = default)
     {
-        // Tenant resolvido via serviço injetado (ambient context, ex: IHttpContextAccessor)
         var tenantId = _tenantContext.TenantId ?? "unknown";
         var tenant = await _tenantService.GetTenantAsync(tenantId, cancellationToken);
 
@@ -159,20 +157,16 @@ public sealed class TenantContextProvider : AIContextProvider
 
         return new AIContext
         {
-            // Injeta como instrução adicional — não como mensagem do usuário
             Instructions = instructions,
         };
     }
 
-    // Sobrescreva (opcional): chamado APÓS o LLM — use para persistir estado derivado da resposta
     protected override ValueTask StoreAIContextAsync(
         InvokedContext context,
         CancellationToken cancellationToken = default)
-        => ValueTask.CompletedTask; // stateless provider — nada a persistir
+        => ValueTask.CompletedTask;
 }
 
-// ── 2. Registrar o agente com o provider no DI ──
-// Program.cs
 builder.Services.AddSingleton<AIAgent>(sp =>
 {
     var registry      = sp.GetRequiredService<ModelRegistry>();
@@ -187,19 +181,15 @@ builder.Services.AddSingleton<AIAgent>(sp =>
         });
 });
 
-// ── Alternativa: pipeline de chat (compacta/injeta SÓ o request em voo) ──
-// using Microsoft.Extensions.AI;   // a extensão vive na assembly Microsoft.Agents.AI
-// IChatClient enriched = chatClient.AsBuilder()
-//     .UseAIContextProviders(new TenantContextProvider(tenantSvc, tenantContext))
-//     .Build();
-
-// ── 3. Uso normal — provider é invocado automaticamente a cada RunAsync ──
 AgentSession session = await agent.CreateSessionAsync();
 AgentResponse response = await agent.RunAsync("Quais são meus benefícios do plano?", session);
 Console.WriteLine(response.Text);
-// O agente já sabe a data, o nome do tenant e o idioma — sem código extra no caller
 ```
 
+**Alternativa: pipeline de chat**, que compacta/injeta **só** o request em voo: registre o provider
+com `.UseAIContextProviders(...)` no `ChatClientBuilder` (`chatClient.AsBuilder()`). O `using` é
+`Microsoft.Extensions.AI`, mas a extensão vive na assembly `Microsoft.Agents.AI`.
+
 ---
 
 ## Context Provider vs Tools vs RAG

package/framework/standards/ai-agents/durable-workflows-hitl.md

@@ -22,12 +22,11 @@ If neither applies, a plain workflow (or no workflow at all — see `ai-agents-s
 
 ## Human-in-the-Loop via `RequestPort`
 
-HITL is modeled with `RequestPort` — a special node in the workflow graph that pauses execution and waits for an external (human) response instead of processing automatically.
+HITL is modeled with `RequestPort` — a special node in the workflow graph that pauses execution and waits for an external (human) response instead of processing automatically. Its two type arguments are the request type the port sends out and the response type it expects back.
 
 ```csharp
 using Microsoft.Agents.AI.Workflows;
 
-// Request type the port sends out, response type it expects back.
 RequestPort<ApprovalRequest, bool> approvalPort =
     RequestPort.Create<ApprovalRequest, bool>("RefundApproval");
 
@@ -47,8 +46,7 @@ await foreach (WorkflowEvent evt in run.WatchStreamAsync())
     switch (evt)
     {
         case RequestInfoEvent requestEvt:
-            // Surface requestEvt.Request to a human (dashboard, email, Slack, ...).
-            // This is where execution pauses until an external answer arrives.
+            // Execution pauses here until the human's answer arrives (dashboard, email, Slack, ...).
             bool approved = await GetHumanDecisionAsync(requestEvt.Request);
             await run.SendResponseAsync(requestEvt.Request.CreateResponse(approved));
             break;
@@ -77,8 +75,14 @@ O caso do agente único é o que a casa realmente tem (MORPH_OS: billing, envio
 
 ### O ciclo, medido em `Microsoft.Extensions.AI` 10.9.0
 
+Quatro passos: (1) embrulhe a tool — `ApprovalRequiredAIFunction : DelegatingAIFunction`; (2) o run
+**termina** pedindo aprovação — não bloqueia, não espera —, e `ToolApprovalRequestContent.ToolCall` é
+um `ToolCallContent` (medido; **não** é `FunctionCallContent`, que aparece em
+`ToolAutoApprovalRuleContext`); (3) responda **na mesma sessão**, com
+`CreateResponse(bool approved, string? reason)`; (4) **repita** o passo 2 até não restar pendência —
+uma volta pode pedir **outra** tool.
+
 ```csharp
-// 1. Embrulhe a tool. ApprovalRequiredAIFunction : DelegatingAIFunction.
 AIFunction charge = AIFunctionFactory.Create(BillingTools.ChargeCustomer);
 AITool guarded = new ApprovalRequiredAIFunction(charge);
 
@@ -88,22 +92,16 @@ AIAgent agent = registry.GetChatClient("text-default")
 AgentSession session = await agent.CreateSessionAsync();
 AgentResponse response = await agent.RunAsync("Cobre o cliente 42.", session);
 
-// 2. O run TERMINA pedindo aprovação — não bloqueia, não espera.
-//    ToolApprovalRequestContent.ToolCall é um ToolCallContent (medido; NÃO é
-//    FunctionCallContent — este último aparece em ToolAutoApprovalRuleContext).
 var pending = response.Messages
     .SelectMany(m => m.Contents)
     .OfType<ToolApprovalRequestContent>()
     .ToList();
 
-// 3. Responda NA MESMA SESSÃO. CreateResponse(bool approved, string? reason).
 if (pending.Count > 0)
 {
     var approvals = pending.Select(r => (AIContent)r.CreateResponse(approved: true, reason: "aprovado por lucas@…"));
     response = await agent.RunAsync(new ChatMessage(ChatRole.User, [.. approvals]), session);
 }
-
-// 4. REPITA o passo 2 até não restar pendência. Uma volta pode pedir OUTRA tool.
 ```
 
 **Os quatro pontos que erram na primeira tentativa:**
@@ -157,10 +155,11 @@ Checkpointing is part of the **base, GA** `Microsoft.Agents.AI.Workflows` namesp
 | `CheckpointManager.CreateJson(new FileSystemJsonCheckpointStore(dir))` | Local disk, survives process restart | Single-instance VPS deployments — no Azure, no preview package |
 | Custom `ICheckpointStore` implementation | Whatever backend you implement it against | **Recommended for production** — implement against the project's own Neon Postgres table, matching the ownership model already used by `ai-agents-rag-custom-pgvector` |
 
+Local-disk durability, with no Azure dependency:
+
 ```csharp
 using Microsoft.Agents.AI.Workflows;
 
-// Local-disk durability — no Azure dependency:
 var checkpointFolder = Directory.CreateDirectory("./checkpoints");
 CheckpointManager checkpointManager = CheckpointManager.CreateJson(
     new FileSystemJsonCheckpointStore(checkpointFolder));
@@ -171,13 +170,12 @@ await foreach (WorkflowEvent evt in run.WatchStreamAsync())
     if (evt is SuperStepCompletedEvent stepEvt)
     {
         CheckpointInfo? checkpoint = stepEvt.CompletionInfo?.Checkpoint;
-        // Persist checkpoint.CheckpointId alongside the business record
-        // (e.g. the refund request row) so it can be resumed after a restart.
+        // Persist checkpoint.CheckpointId with the business record (e.g. the refund row) to resume after a restart.
     }
 }
 ```
 
-Resuming after a restart — rehydrate into a **new** run instance from the last known checkpoint:
+Resuming after a restart — rehydrate into a **new** run instance from the last known checkpoint. A pending `RequestPort` request is re-emitted as a `RequestInfoEvent`, so the paused approval survives the restart:
 
 ```csharp
 StreamingRun resumedRun = await InProcessExecution.ResumeStreamingAsync(
@@ -185,8 +183,6 @@ StreamingRun resumedRun = await InProcessExecution.ResumeStreamingAsync(
 
 await foreach (WorkflowEvent evt in resumedRun.WatchStreamAsync())
 {
-    // A pending RequestPort request is re-emitted here as a RequestInfoEvent —
-    // the paused approval survives the restart.
     if (evt is RequestInfoEvent requestEvt) { /* re-surface to the human */ }
 }
 ```
@@ -211,14 +207,12 @@ internal sealed class RefundAnalyzerExecutor() : Executor("RefundAnalyzer")
 
 ### `ICheckpointStore` — Neon/Postgres-backed (recommended production pattern)
 
-Implementing `ICheckpointStore` against the project's own Postgres database keeps checkpoint durability inside the same infrastructure the rest of the project already trusts (see `infrastructure-neon-setup`), instead of introducing a new storage dependency:
+Implementing `ICheckpointStore` against the project's own Postgres database keeps checkpoint durability inside the same infrastructure the rest of the project already trusts (see `infrastructure-neon-setup`), instead of introducing a new storage dependency. The store persists and retrieves checkpoint blobs in a `workflow_checkpoints` table (`workflow_id`, `checkpoint_id`, `payload` jsonb/bytea, `created_at`), implemented per the `ICheckpointStore` contract in the `Microsoft.Agents.AI.Workflows` docs:
 
 ```csharp
 public sealed class PostgresCheckpointStore(NpgsqlDataSource dataSource) : ICheckpointStore
 {
-    // Persist/retrieve checkpoint blobs in a workflow_checkpoints table
-    // (workflow_id, checkpoint_id, payload jsonb/bytea, created_at).
-    // Implement per the ICheckpointStore contract — see Microsoft.Agents.AI.Workflows docs.
+    // ICheckpointStore members over workflow_checkpoints — elided.
 }
 ```