@polymorphism-tech/morph-spec 8.42.0 → 8.44.0

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.42.0"
+cliVersion: "8.44.0"
 ---
 
 # morph-review
@@ -63,7 +63,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
      rodada.
 
    **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+e2e que você anexa ao prompt do avaliador independente (`morph-evaluator`). **Sem `--filter`, sempre:** o `--filter` é do loop por task, onde o relógio de uma task não paga a suíte inteira; a prova que o avaliador lê tem de cobrir **todos** os nós de `nodes.tests.runs[]` (uma suíte filtrada aparece como `skip` nomeando o filtro — Gate 3 aberto sobre isso é verde sobre código não testado). Se a suíte inteira não couber numa chamada, rode-a em background; não a encolha com `--filter`. `verify {feature}` (sem task) **nunca recorta** — o recorte automático é só do escopo de task —, e um `verify {feature} --filter …` nem persiste o stamp (`persisted: false`, `reason: 'filtered'`) — o mesmo vale para `--skip-tests`/`--skip-build` no escopo de feature. Rode-o **depois** da última task: o `gate-check {feature} review` pausa quando o último stamp `verification` é de escopo `task:{id}`, porque aquela rodada cobriu só a task. Uma rodada por árvore: se o JSON vier com `repeatOf`, nada mudou fora de `.morph/` desde o verify de feature anterior — use aquele resultado em vez de rodar de novo; depois de uma correção a árvore mudou, e a nova rodada é a prova.
+   - Rode `morph-spec verify {feature} --json` (escopo feature; exit 3 / `status: "busy"` é fila de slot pesado cheia, não vermelho: repita a chamada) e capture o JSON — é a saída real de build+testes+validadores+e2e que você anexa ao prompt do avaliador independente (`morph-evaluator`). **Sem `--filter`, sempre:** o `--filter` é do loop por task, onde o relógio de uma task não paga a suíte inteira; a prova que o avaliador lê tem de cobrir **todos** os nós de `nodes.tests.runs[]` (uma suíte filtrada aparece como `skip` nomeando o filtro — Gate 3 aberto sobre isso é verde sobre código não testado). Se a suíte inteira não couber numa chamada, rode-a em background; não a encolha com `--filter`. `verify {feature}` (sem task) **nunca recorta** — o recorte automático é só do escopo de task —, e um `verify {feature} --filter …` nem persiste o stamp (`persisted: false`, `reason: 'filtered'`) — o mesmo vale para `--skip-tests`/`--skip-build` no escopo de feature. Rode-o **depois** da última task: o `gate-check {feature} review` pausa quando o último stamp `verification` é de escopo `task:{id}`, porque aquela rodada cobriu só a task. Uma rodada por árvore: se o JSON vier com `repeatOf`, nada mudou fora de `.morph/` desde o verify de feature anterior — use aquele resultado em vez de rodar de novo; depois de uma correção a árvore mudou, e a nova rodada é a prova.
    - **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
@@ -174,21 +174,48 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
          MUTAÇÃO — o método, e a ordem dele importa:
            - COMMITE O FIX ANTES DE MUTAR. Se a sessão morrer no meio, o
              que sobrevive é a mutação, não a correção.
-           - Ancore no CALL SITE que carrega a decisão, não no `if`
-             refatorado. Uma rodada POR CLÁUSULA de um predicado composto.
-           - Rode a suíte INTEIRA (sem filtro): só ela autoriza a frase
-             "derruba N de M". Filtro estreito é prova vácua.
+           - VOCÊ ESCOLHE os mutantes: ancore no CALL SITE que carrega a
+             decisão, não no `if` refatorado. Uma rodada POR CLÁUSULA de um
+             predicado composto — cada cláusula é um mutante próprio.
+           - ESCREVA `.morph/features/{feature}/4-review/mutants.json`:
+             {"mutants":[{"id":"M1","file":"src/x.cs","line":42,
+             "find":"a && b","replace":"a"}]}. `find` começa na `line` e é
+             único nela; arquivo:linha, diff e md5 saem da ferramenta.
+             Com a ferramenta Write, se você a tem; só com Bash, heredoc
+             de delimitador entre aspas simples. O transporte do Bash
+             reduz `\\` a `\` e decodifica escapes unicode, então escreva
+             cada barra invertida do código como `{{BS}}` (a ferramenta a
+             expande): atravessa qualquer transporte. `find` que deixa de
+             bater com o arquivo é recusado com o erro, nunca aplicado.
+           - RODE `morph-spec mutate {feature}` UMA vez, com o Bash. Ela
+             faz o lote inteiro: um build só (chaves por variável de
+             ambiente; o que a chave não compila cai para rebuild real),
+             subconjunto de testes primeiro — escolhido por ela, não por
+             você — e, para CADA sobrevivente, o mutante compilado de
+             verdade contra a suíte INTEIRA. Só esse caminho produz
+             "sobreviveu"; "derruba K de M" sempre diz o escopo do K
+             (≥K no subconjunto, K na suíte inteira); na suíte inteira a
+             falha tem de se repetir, senão é instabilidade e o mutante
+             sobrevive. Sem a ferramenta,
+             mute e rode a suíte INTEIRA à mão, um mutante por vez.
            - LEIA O MOTIVO da falha, não só o md5: md5 prova que ALGO
-             mudou, jamais O QUÊ.
-           - REVERTA por snapshot/restore de BYTES (cópia feita ANTES) +
-             `os.utime` para devolver o mtime, e confirme por md5. NUNCA
+             mudou, jamais O QUÊ. Falha de build não é morte, e
+             `inconclusive` não conta como nada.
+           - A REVERSÃO é da ferramenta: bytes do snapshot com md5
+             conferido, por escrita NOVA, rebuild forçado e a DLL final
+             igual (md5) à construída antes do 1º mutante. NUNCA `os.utime`
+             para devolver o mtime: o MSBuild acha o binário do último
+             mutante em dia e a rodada-base roda sobre ele. NUNCA
              `git checkout --`: ele descarta trabalho não commitado de
              outra pessoa — aconteceu de verdade num Gate 3 desta epic.
-           - TERMINE com `git status --porcelain src/` VAZIO. Mutação
-             esquecida em produção é o pior desfecho deste método.
-         Grave no relatório a seção `## Mutações`, uma linha por mutação,
-         com os CINCO campos: arquivo:linha | diff | md5 antes/depois |
-         quantos testes derrubou (sobre o total da suíte) | o MOTIVO
+             Rodada que morreu no meio: `morph-spec mutate --restore`.
+           - TERMINE com `git status --porcelain src/` VAZIO e exit 0. Exit
+             4 é inseguro (arquivo não restaurado, árvore ou binário
+             diferentes): resolva antes de pontuar.
+         Cole no relatório a seção `## Mutações` que a ferramenta imprime
+         (ela também a grava em `4-review/mutation-section.md`), uma linha
+         por mutação, com os CINCO campos: arquivo:linha | diff | md5
+         antes/depois | quantos testes derrubou (com o escopo) | o MOTIVO
          literal da falha. Feature sem código de produção declara a seção
          com a linha `não aplicável — feature sem código de produção`. A
          seção é OBRIGATÓRIA: sem ela o `morph-spec gate-check` PAUSA o
@@ -294,6 +321,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
      > diff antes). É a mesma proibição que o prompt do passo 4 já dá ao avaliador: aqui ela vale
      > para VOCÊ.
    - **Leia primeiro** `.morph/features/{feature}/4-review/evaluator-report.md` — é o valor de retorno autoritativo, não a mensagem de texto do dispatch (que é cortesia, útil só quando chega inteira). Os scores por dimensão e o composto do review-report vêm **desse arquivo**, não da sua auto-avaliação. Se o arquivo vier ausente, oco, ou sem os scores por dimensão, registre a falha de protocolo na seção de método do review-report e re-despache.
+   - Com o relatório lido, rode `morph-spec worktree reap --json`: a árvore do avaliador que parou limpa sai sozinha; a que ficou com trabalho vem listada com a razão.
    - **`PARCIAL` na 1ª linha = o avaliador parou antes do fim** (limite de turnos; o `report-check` devolve `evaluator.partial: true`). Não leia score dele — o parcial não tem `**Composite-Score:**`, e o `gate-check` pausaria de qualquer jeito — e não re-despache frio: um avaliador novo refaz a rodada inteira (probes, mutações, navegação). Retome o MESMO avaliador por `SendMessage`, como no passo 6, colando `tree.dirty` e `tree.commits` do `report-check` no recado; ele completa o relatório, e o final substitui o parcial. Só se o id não retomar, despache um novo pelo caminho normal — o parcial no disco é resíduo, não insumo, como o prompt já diz. Antes de qualquer das duas, a higiene da árvore acima continua valendo: um avaliador cortado no meio pode ter deixado mutação no disco.
 
 5. Produza `review-report.md` em `.morph/features/{feature}/4-review/` com:
@@ -318,9 +346,10 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
      | # | Arquivo:linha | Mutação (diff) | md5 antes | md5 depois | Testes derrubados | Motivo da falha |
      |---|---|---|---|---|---|---|
-     | M1 | src/lib/x.js:42 | `- if (a && b)` / `+ if (a)` | abc… | def… | 3 de 2684 | `expected 3 got 0` em x.test.js:88 |
+     | M1 | src/lib/x.js:42 | `- if (a && b)` / `+ if (a)` | abc… | def… | ≥3 de 212 (subconjunto) | `expected 3 got 0` em x.test.js:88 |
+     | M2 | src/lib/y.js:7 | `- return ok` / `+ return true` | 123… | 456… | 0 de 2684 (SOBREVIVEU, suíte inteira) | nenhum teste falhou na suíte inteira |
 
-     **Reversão:** snapshot/restore de bytes + `os.utime`; `git status --porcelain src/` vazio.
+     **Reversão:** snapshot/restore de bytes por escrita nova; DLL final igual (md5); `git status --porcelain src/` vazio.
      **Proof-Scores:** mutation=9 verde=8 fiacao=9 guard=7
      ```
 

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.42.0"
+cliVersion: "8.44.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.42.0"
+cliVersion: "8.44.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.42.0"
+cliVersion: "8.44.0"
 ---
 
 # morph-uiux

package/framework/standards/PROVENANCE.json

@@ -8,15 +8,15 @@
       "path": "skills/morph-lp-cinematic",
       "envVar": "MORPH_HUB",
       "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
-      "sourceTree": "e43114d4b28ff55680a5355cce27d31ffa74f22f",
-      "sourceCommit": "465c9b0",
+      "sourceTree": "2987b44241cae479b1aedc63f689cdcd6ef6fb94",
+      "sourceCommit": "c4c9164",
       "distilledOn": "2026-08-21",
       "distilledFrom": [
         "references/build-stack.md",
         "references/component-recipes.md",
         "references/premium-finish.md",
         "references/seo-and-qa.md",
-        "references/gemini-image-prompt.md",
+        "references/image-prompt.md",
         "references/seedance-scrub-prompt.md",
         "references/seedance-loop-prompt.md"
       ],
@@ -25,7 +25,7 @@
         "references/copy-and-messaging.md",
         "references/section-blueprint.md"
       ],
-      "notDistilledReason": "Deliberate split: a standard carries knowledge, a skill carries process. Deploy and copy strategy stay with the skill. `references/gates.md` LEFT this list on 2026-09-09: the reason that kept it out was \"a skill carries process\", and the destination is now a skill — see the \"cinematic-lp\" source below, which distils it into morph-media.",
+      "notDistilledReason": "Deliberate split: a standard carries knowledge, a skill carries process. Deploy and copy strategy stay with the skill. `references/gates.md` LEFT this list on 2026-09-09: the reason that kept it out was \"a skill carries process\", and the destination is now a skill — see the \"cinematic-lp\" source below, which distils it into morph-media. Review of 2026-09-29 (source c4c9164): only tool-independent facts were ported (the scrub_frames manifest contract for frame-scrub, chained clips for ai-video-generation); the rest was already in the standards or stays with the skill (ffmpeg-to-media_tool swaps, model prices, SKILL.md, gates.md, assets/).",
       "standards": [
         "frontend-scroll-driven-frame-scrub",
         "frontend-scroll-driven-smooth-scroll",
@@ -65,8 +65,8 @@
       "path": "skills/cinematic-lp/references",
       "envVar": "MORPH_HUB",
       "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
-      "sourceTree": "57a1734bc17651a6fed381a6e817c8b0c0a89edd",
-      "sourceCommit": "b6bbfff",
+      "sourceTree": "3c557425d649ed477bf6645b9297b6d1d72ae4a3",
+      "sourceCommit": "c4c9164",
       "distilledOn": "2026-09-09",
       "distilledFrom": [
         "gates.md"
@@ -85,7 +85,7 @@
         "video-loop-prompt.md",
         "video-scrub-prompt.md"
       ],
-      "notDistilledReason": "Only the HITL gate mechanics were distilled: the N-option picker, \"rejection goes back to the same step\", and \"show MOVEMENT, never a still\". The rest is either already a standard (the frame-scrub / smooth-scroll / premium-finish family, from the morph-lp-cinematic source above) or build/deploy strategy that belongs to the calling workflow.",
+      "notDistilledReason": "Only the HITL gate mechanics were distilled: the N-option picker, \"rejection goes back to the same step\", and \"show MOVEMENT, never a still\". The rest is either already a standard (the frame-scrub / smooth-scroll / premium-finish family, from the morph-lp-cinematic source above) or build/deploy strategy that belongs to the calling workflow. Review of 2026-09-29 (source c4c9164): gates.md did not change; the changes were in image-prompt.md and mcp-setup.md, both not distilled. Re-pinned only.",
       "standards": [],
       "skills": [
         "morph-media"
@@ -97,8 +97,8 @@
       "path": "skills/brand-design/references",
       "envVar": "MORPH_HUB",
       "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
-      "sourceTree": "d8801b8c277f63b06e1a22f57563ec468e7d4d9a",
-      "sourceCommit": "b6bbfff",
+      "sourceTree": "7b637a08e931d8b7ba5be7fc75b851d89cd6e6f4",
+      "sourceCommit": "c4c9164",
       "distilledOn": "2026-09-09",
       "distilledFrom": [
         "image-generation.md"
@@ -109,7 +109,7 @@
         "example-identidade-visual.md",
         "phases.md"
       ],
-      "notDistilledReason": "Only the image-per-phase map and the \"concept, never the final vector\" rule were distilled. The narrative prompt recipes were NOT copied verbatim: they are bound to one brand pipeline, and morph-media carries the prompt STRUCTURE instead, which survives the model changing. Brand book, checklist and phases are the process of another skill.",
+      "notDistilledReason": "Only the image-per-phase map and the \"concept, never the final vector\" rule were distilled. The narrative prompt recipes were NOT copied verbatim: they are bound to one brand pipeline, and morph-media carries the prompt STRUCTURE instead, which survives the model changing. Brand book, checklist and phases are the process of another skill. Review of 2026-09-29 (source c4c9164): the image-per-phase table and the \"concept, never the final vector\" rule are unchanged (the text now says \"image model\" instead of Gemini); what was added is morph-assets call mechanics (project_set, @brand, outputPath, models, variants, dryRun), tool-bound and kept out on purpose. Re-pinned only.",
       "standards": [],
       "skills": [
         "morph-media"

package/framework/standards/STANDARDS.json

@@ -2566,15 +2566,18 @@
         "POSTGRES_PORT",
         "COMPOSE_PROJECT_NAME",
         "port block",
+        "PG_PORT",
+        "portEnvNames",
         "local docker compose"
       ],
       "anchors": {
         "layout": "#port-layout-one-contract-everywhere",
+        "portNames": "#project-named-port-variables",
         "rules": "#core-rules",
         "enforcement": "#what-the-harness-enforces",
         "skeleton": "#minimal-compose-skeleton"
       },
-      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish tears down with volumes (--keep-volumes opts out). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env.",
+      "digest": "Every worktree runs its OWN compose stack (project morph-{feature}, own postgres, own volumes). Ports come from the worktree block: PORT +0, API_PORT +1 (ASPNETCORE_URLS on .NET), POSTGRES_PORT +2, REDIS_PORT +3 — publish via ${VAR:-default}:container, never a fixed host port, never container_name (not prefixed by the project → collides). Stable POSTGRES_DB, healthcheck on every service, DATABASE_URL with an in-network default, playwright.config reads PLAYWRIGHT_BASE_URL. A non-isolable compose fails the verify e2e node inside a worktree. finish tears down with volumes (--keep-volumes opts out). Cloud DB credentials go in e2e.auth.envFile, never in .morph/worktree.env. A compose that reads a port by ANOTHER name (PG_PORT) is not fed by the block: declare it in config.json e2e.portEnvNames ({\"postgres\": \"PG_PORT\"}) and the harness exports it with the same value in worktree.env, the compose env and the hook.",
       "verifiedAgainst": "Docker Compose v2 + morph-spec 8.34 (dedicated stack per worktree).",
       "provedBy": []
     },
@@ -2851,6 +2854,47 @@
       "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; in a test the link to the postcondition goes in the test NAME), 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. A heavily commented neighbour file is not a model. The comment-guard hook blocks an edit that ADDS process history, a banner/#region, a block over 3 lines or a doc-comment outside a published package; 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": []
+    },
+    {
+      "id": "ai-agents-tool-adapters",
+      "name": "tool adapters",
+      "path": "ai-agents/tool-adapters.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "tools",
+        "testing"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "tool fina",
+        "adaptador de tool",
+        "Ops",
+        "Desfecho",
+        "Render",
+        "regra de negocio em tool",
+        "descricao da tool",
+        "golden de tool",
+        "refactor neutro",
+        "migracao de teste"
+      ],
+      "anchors": {
+        "fronteira": "#fronteira-com-os-outros-standards",
+        "problema": "#o-problema",
+        "padrao": "#o-padrão",
+        "exemplo": "#exemplo-c-completo",
+        "testes": "#os-testes-das-duas-camadas",
+        "migracao": "#migrar-uma-tool-que-já-tem-a-regra-no-adaptador",
+        "reais": "#exemplos-reais",
+        "regras": "#regras"
+      },
+      "digest": "A tool that carries business rule keeps apart three things that change for different reasons: the RULE (sealed class XOps(...), primary constructor, explicit AddScoped; never *Service, which the mandate bans as a layer between handler and data), the sentence the MODEL reads, and the EFFECT a human sees. Each Ops method returns a typed outcome (abstract record XDesfecho, one sealed record per case); the model-facing text (description, refusal, self-correction, success, the ToolUnavailable decision) lives in the adapter, in public static object Render(XDesfecho), while human text delivered by code (task body, note, ack) stays in Ops because it is an effect. Checkable by grep: Ops names no tool and instructs no model. The adapter (AIFunctionFactory.Create) only builds the typed request, calls Ops and returns Render: zero rule, not a line count, and a long dynamic description stays byte for byte. Two test layers: Ops tests assert outcome, calls and order on the fake, never text; contract tests assert Render's exact literal and .Description, with a golden of name, description and schema per real tenant. A neutral refactor is proven before any test moves: a proof commit with the old suite untouched and green (offline evals included), then the migration, with mutation run only against the new tests. \"Already covered\" needs proof assertion by assertion (11 of 22 such claims had lost one); the tests left at the origin must be identical to the base; mutation on the new tests found rules the old suite never protected. The C# blocks were compiled against the pin and the three xunit tests run.",
+      "verifiedAgainst": "Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); os dois blocos C# abaixo foram extraídos com `scripts/extract-doc-csharp.mjs` e compilados contra o pin com `TreatWarningsAsErrors`, e os três testes do segundo bloco foram executados e passam. **A separação em si e a migração de teste são verificação documental:** vêm da feature `tools-finas` do MORPH_GHLBrain e o ai-kit não as traz.",
+      "provedBy": []
     }
   ],
   "sharedAliases": {

package/framework/standards/ai-agents/tool-adapters.md

@@ -0,0 +1,226 @@
+# Tool Adapters — a regra em `*Ops`, o texto do modelo no adaptador
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** tool, AIFunctionFactory, adaptador de tool, tool fina, Ops, Desfecho, Render, regra de negócio em tool, descrição da tool, golden de tool, refactor neutro, migração de teste
+> **Read by Claude in:** implement (ao escrever ou migrar uma tool de agente que carrega regra de negócio)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 (ai-pin 2026-09-08); os dois blocos C# abaixo foram extraídos com `scripts/extract-doc-csharp.mjs` e compilados contra o pin com `TreatWarningsAsErrors`, e os três testes do segundo bloco foram executados e passam. **A separação em si e a migração de teste são verificação documental:** vêm da feature `tools-finas` do MORPH_GHLBrain e o ai-kit não as traz. Last-verified: 2026-09-08.
+
+---
+
+## Fronteira com os outros standards
+
+`ai-agents-mcp-tools` cobre **consumir** tools de um MCP server. `ai-agents-testing-ai` cobre **testar** um agente sem rede. `backend-dotnet-testing` é dono de xUnit, relógio falso e orçamento de teste. **Nada disso se repete aqui.**
+
+Este standard cobre uma coisa só: a tool que o agente chama **e que carrega regra**. Onde mora a regra, onde mora a frase que o modelo lê, e como se testa cada uma sem que uma mascare a outra.
+
+## O problema
+
+Uma tool nasce como uma lambda dentro do `AIFunctionFactory.Create`. Enquanto é só "chame a API e devolva", serve. Quando ganha regra, a lambda passa a misturar três coisas que mudam por motivos diferentes:
+
+| O que é | Muda quando | Quem lê |
+|---|---|---|
+| a **regra** (validar, decidir, gravar) | o negócio muda | o código e o teste |
+| a **frase para o modelo** (descrição, recusa, instrução de correção) | o prompt é ajustado | o modelo |
+| o **efeito** (task, nota, mensagem entregue por código) | o processo muda | um humano |
+
+Misturadas, o único teste possível é por string: qualquer ajuste de redação quebra o teste da regra, e qualquer refactor da regra arrisca mudar, sem ninguém ver, o que o modelo lê.
+
+## O padrão
+
+```
+   o modelo chama                                          o modelo lê
+ ┌──────────────┐    pedido tipado    ┌───────────┐  desfecho  ┌────────────────┐
+ │  Adaptador   │ ──────────────────► │   *Ops    │ ─────────► │ Render(desfecho)│
+ │ (tool fina)  │                     │ (a regra) │  tipado    │ (frase p/ modelo)│
+ └──────────────┘ ◄───────────────────────────────────────────└────────────────┘
+```
+
+1. **`Ops`, não `Service`.** Regra determinística com dependências injetadas vira `sealed class XOps(...)`, com construtor primário e um `AddScoped` explícito. `*Service` colide com a proibição de camada de Service/Manager entre handler e dados; `*Ops` é outra coisa: a regra de uma tool, não um intermediário de persistência.
+2. **Desfecho tipado, e a fronteira é quem lê o texto.** Cada método de `Ops` devolve um `abstract record XDesfecho` com um `sealed record` por caso. A frase para o **modelo** (descrição, recusa, instrução de autocorreção, sucesso, a decisão de "tool indisponível") mora no adaptador, em `public static object Render(XDesfecho)`. O texto para **humano** entregue por código (corpo de task, nota, ack) mora na `Ops`, porque é efeito. É verificável por `grep`: a `Ops` não cita o nome da tool nem dá instrução ao modelo.
+3. **Adaptador fino.** `AIFunctionFactory.Create` com a lambda montando o pedido tipado, chamando a `Ops` e devolvendo `Render(desfecho)`. A régua é **zero regra no adaptador**, não um número de linhas: uma descrição dinâmica pode ser longa e tem de continuar byte a byte.
+4. **Testes em duas camadas.** O teste da `Ops` asserta desfecho, chamadas e ordem no fake, **nunca texto**. O teste de contrato asserta o `Render` com o literal exato e a `.Description`. Um golden de nome, descrição e schema, por tenant real, protege a superfície que o modelo lê.
+5. **Refactor neutro se prova antes de migrar teste.** Primeiro um commit de prova, com a suíte antiga intocada e verde (inclusive os evals offline); só depois a migração dos testes, com mutação rodando **só** contra os testes novos.
+
+## Exemplo C# completo
+
+A regra, o desfecho, o adaptador e o registro. O pedido é tipado, então a lambda não decide nada: monta, chama, renderiza.
+
+```csharp
+using System.ComponentModel;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Exemplo.Tools;
+
+public interface IAgendaExterna
+{
+    Task<int> CapacidadeAsync(string salaId, CancellationToken ct);
+    Task<string> GravarAsync(ReservaPedido pedido, CancellationToken ct);
+}
+
+public sealed record ReservaPedido(string SalaId, DateOnly Dia, int Pessoas);
+
+public abstract record ReservaDesfecho
+{
+    public sealed record Reservada(string ConfirmacaoId) : ReservaDesfecho;
+    public sealed record SalaCheia(int Capacidade) : ReservaDesfecho;
+    public sealed record DiaSemExpediente(DateOnly Dia) : ReservaDesfecho;
+}
+
+public sealed class ReservaOps(IAgendaExterna agenda)
+{
+    public async Task<ReservaDesfecho> ReservarAsync(ReservaPedido pedido, CancellationToken ct)
+    {
+        if (pedido.Dia.DayOfWeek is DayOfWeek.Saturday or DayOfWeek.Sunday)
+            return new ReservaDesfecho.DiaSemExpediente(pedido.Dia);
+
+        var capacidade = await agenda.CapacidadeAsync(pedido.SalaId, ct);
+        if (pedido.Pessoas > capacidade)
+            return new ReservaDesfecho.SalaCheia(capacidade);
+
+        return new ReservaDesfecho.Reservada(await agenda.GravarAsync(pedido, ct));
+    }
+}
+
+public static class ReservarSalaTool
+{
+    public const string Name = "reservar_sala";
+
+    public static AIFunction Create(ReservaOps ops) =>
+        AIFunctionFactory.Create(
+            async (
+                [Description("Identificador da sala, como listado por consultar_salas")] string salaId,
+                [Description("Dia da reserva, AAAA-MM-DD")] DateOnly dia,
+                [Description("Quantidade de pessoas")] int pessoas,
+                CancellationToken ct) =>
+                Render(await ops.ReservarAsync(new ReservaPedido(salaId, dia, pessoas), ct)),
+            Name,
+            "Reserva uma sala para um dia. Só chame depois de confirmar sala, dia e número de pessoas com o cliente.");
+
+    public static object Render(ReservaDesfecho desfecho) => desfecho switch
+    {
+        ReservaDesfecho.Reservada r => new { ok = true, confirmacao = r.ConfirmacaoId },
+        ReservaDesfecho.SalaCheia c => new { ok = false, erro = $"A sala comporta no máximo {c.Capacidade} pessoas. Ofereça outra sala ou reduza o grupo." },
+        ReservaDesfecho.DiaSemExpediente d => new { ok = false, erro = $"{d.Dia:yyyy-MM-dd} não tem expediente. Peça outro dia." },
+        _ => throw new ArgumentOutOfRangeException(nameof(desfecho)),
+    };
+}
+
+public static class ReservaToolsRegistration
+{
+    public static IServiceCollection AddReservaTools(this IServiceCollection services) =>
+        services.AddScoped<ReservaOps>();
+}
+```
+
+A checagem de fronteira é um `grep`, e tem de sair vazio: a `Ops` não conhece a tool nem fala com o modelo.
+
+```bash
+grep -rnE "reservar_sala|Ofereça|Peça|AIFunction" Features/Reservas/Ops/
+```
+
+## Os testes das duas camadas
+
+O teste da `Ops` compara **tipos e chamadas**; o de contrato compara **o texto que o modelo lê**. Trocar a redação de uma recusa quebra só o segundo.
+
+```csharp
+using System.Text.Encodings.Web;
+using System.Text.Json;
+using Exemplo.Tools;
+using Xunit;
+
+namespace Exemplo.Tools.Tests;
+
+internal sealed class AgendaFake(int capacidade) : IAgendaExterna
+{
+    public List<string> Chamadas { get; } = [];
+
+    public Task<int> CapacidadeAsync(string salaId, CancellationToken ct)
+    {
+        Chamadas.Add($"capacidade:{salaId}");
+        return Task.FromResult(capacidade);
+    }
+
+    public Task<string> GravarAsync(ReservaPedido pedido, CancellationToken ct)
+    {
+        Chamadas.Add($"gravar:{pedido.SalaId}");
+        return Task.FromResult("R-1");
+    }
+}
+
+public sealed class ReservaOpsTests
+{
+    [Fact]
+    public async Task Sala_cheia_nao_grava_e_devolve_a_capacidade()
+    {
+        var agenda = new AgendaFake(capacidade: 4);
+        var ops = new ReservaOps(agenda);
+
+        var desfecho = await ops.ReservarAsync(new ReservaPedido("s1", new DateOnly(2026, 10, 5), 6), CancellationToken.None);
+
+        Assert.Equal(new ReservaDesfecho.SalaCheia(4), desfecho);
+        Assert.Equal(["capacidade:s1"], agenda.Chamadas);
+    }
+}
+
+public sealed class ReservarSalaToolTests
+{
+    private static readonly JsonSerializerOptions Literal = new() { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
+
+    [Fact]
+    public void Render_da_sala_cheia_diz_ao_modelo_o_que_fazer()
+    {
+        var json = JsonSerializer.Serialize(ReservarSalaTool.Render(new ReservaDesfecho.SalaCheia(4)), Literal);
+
+        Assert.Equal("{\"ok\":false,\"erro\":\"A sala comporta no máximo 4 pessoas. Ofereça outra sala ou reduza o grupo.\"}", json);
+    }
+
+    [Fact]
+    public void A_superficie_que_o_modelo_le_nao_mudou()
+    {
+        var tool = ReservarSalaTool.Create(new ReservaOps(new AgendaFake(capacidade: 10)));
+
+        Assert.Equal("reservar_sala", tool.Name);
+        Assert.StartsWith("Reserva uma sala para um dia.", tool.Description);
+        Assert.Contains("\"salaId\"", tool.JsonSchema.GetRawText());
+    }
+}
+```
+
+## Migrar uma tool que já tem a regra no adaptador
+
+A migração é um refactor que **não pode mudar o que o modelo lê**. Por isso ela tem ordem:
+
+1. **Commit de prova.** Extraia a `Ops` e o `Render` sem tocar nenhum teste. A suíte antiga tem de continuar verde, inclusive os evals offline. Esse commit é a âncora: prova que o refactor é neutro.
+2. **Migre os testes**, e só depois de o commit de prova estar verde.
+3. **Matriz de migração.** Liste cada asserção antiga e a asserção nova que a cobre. "Já está coberto pelo teste X" precisa de prova **asserção por asserção**: na migração que originou este standard, 11 de 22 alegações desse tipo tinham perdido alguma asserção do teste antigo.
+4. **Os testes que ficam na origem têm de ser idênticos à base.** A migração só apaga. Uma checagem byte a byte dos métodos restantes contra o commit de prova pegou (e provou corrigidos) `Edit`s que casaram no método errado.
+5. **Mutação só contra os testes novos.** Ela acha lacunas que a suíte antiga nunca protegeu: em duas das três `Ops` migradas apareceram regras sem teste algum (valor digitado pelo comercial sobrescrito pelo catálogo, campos reafirmados sumindo da falha do `PUT`, corpo de update reenviando valor igual).
+
+## Exemplos reais
+
+MORPH_GHLBrain, `src/Morph.GHLBrain/Features/Conversation/Operator/`:
+
+| Tool | Adaptador | `Ops` | Desfecho |
+|---|---|---|---|
+| `finalizar_handoff` | `Tools/FinalizarHandoffTool.cs` | `Ops/HandoffOps.cs` | `HandoffDesfecho` |
+| `atualizar_dossie` | `Tools/AtualizarDossieTool.cs` | `Ops/DossieOps.cs` | `DossieDesfecho` |
+| `set_lead_fields` | `Tools/SetLeadFieldsTool.cs` | `Ops/DossieOps.cs` | `CamposDesfecho` |
+| `route_lead` | `Tools/RouteLeadTool.cs` | `Ops/TriagemOps.cs` | `TriagemDesfecho` |
+
+As decisões estão em `.morph/features/tools-finas/2-plan/decisions.md` (ADR-1 e ADR-2) daquele repositório.
+
+## Regras
+
+- **ALWAYS** a regra de uma tool vai numa `sealed class XOps(...)` com construtor primário e `AddScoped` explícito
+- **NEVER** chame essa classe de `*Service` ou `*Manager`: o mandate proíbe essa camada entre handler e dados, e `*Ops` é a forma da casa
+- **ALWAYS** cada método de `Ops` devolve um `abstract record XDesfecho`, com um `sealed record` por caso que a regra distingue
+- **NEVER** ponha na `Ops` uma frase para o modelo, o nome da tool ou uma instrução de autocorreção. Verifique por `grep`
+- **ALWAYS** o texto para humano entregue por código (task, nota, ack) fica na `Ops`: é efeito
+- **ALWAYS** o adaptador só monta o pedido tipado, chama a `Ops` e devolve `Render(desfecho)`. Zero regra ali; descrição dinâmica longa é permitida e segue byte a byte
+- **ALWAYS** o teste da `Ops` asserta desfecho, chamadas e ordem no fake, nunca texto
+- **ALWAYS** o teste de contrato asserta o `Render` com o literal exato e a `.Description`, e há um golden de nome, descrição e schema por tenant real
+- **NEVER** declare "já coberto" sem a asserção nova que cobre cada asserção antiga
+- **NEVER** migre o teste antes do commit de prova verde, nem deixe na origem um teste diferente da base

package/framework/standards/frontend/design-system/ai-video-generation.md

@@ -55,6 +55,8 @@ Give a start image and an end image, and let the model interpolate a camera trav
 
 **Avoid for scrub:** full orbits and any movement that returns to its origin. They become loops and kill the sense of progress.
 
+**Long continuous sequence (hero → reveal → product).** Generate each next clip with `chainFrom: "<id of the previous clip>"` and its own `endImage`: the previous clip's real last frame becomes the start, so the seam matches (SSIM about 0.94 in the upstream skill's test). Join the clips with `media_tool { op: "concat" }` before `scrub_frames`. Source: the upstream `morph-lp-cinematic` skill; not re-measured here.
+
 ---
 
 ## Section 3: Faces Trip Moderation

package/framework/standards/frontend/scroll-driven/frame-scrub.md

@@ -41,6 +41,16 @@ ffmpeg -i source.mp4 -vf "fps=30,scale=1280:-1" -q:v 5 frames/frame_%03d.jpg
 | Numbering | `%03d` (frame_001) matches the 1-based `framePath` contract in Section 4. |
 | Format | JPG is the safe default (fast decode, universal). If the sequence gets heavy (tens of MB), also try WebP via `-c:v libwebp -q:v 70`, which usually cuts total weight at similar quality. |
 
+**Frames from `media_tool scrub_frames` (morph-assets) do not follow the table above.** The tool writes `v{N}/frame_0001.webp …` (4-digit, 1-based, WebP by default) and a `frames.json` manifest (`version`, `count`, `format`, `width`, `height`, `fps`, `pattern`, `totalBytes`). Build `frameCount` and `framePath` from the manifest; a `%03d`/`.jpg` path from this section will not resolve against them. A new `v{N}` folder per extraction changes the URL by construction, so it is the cache-bust of Section 3:
+
+```js
+import manifest from './hero-frames/frames.json'
+const frameCount = manifest.count
+const framePath = (i) => `/hero-frames/v${manifest.version}/frame_${String(i).padStart(4, '0')}.${manifest.format}`
+```
+
+Source: the upstream `morph-lp-cinematic` skill (build-stack reference); not re-measured here.
+
 **Treat total sequence weight as a performance budget.** It shows up directly in Lighthouse. If it is too heavy, cut frame count (120 instead of 145) or resolution before cutting quality.
 
 **Mirror the footage when the subject collides with the copy.** If the subject sits on the side where text goes, flip it during extraction:
@@ -57,7 +67,7 @@ ffmpeg -i source.mp4 -vf "hflip,fps=30,scale=1664:-1" -q:v 5 frames/frame_%03d.j
 
 Re-extracting frames (for example going from 480p to 1080p) while keeping the same filenames means the browser serves the stale ones and nothing appears to change.
 
-Always version the frame URL and bump `N` on every re-extraction:
+Always version the frame URL and bump `N` on every re-extraction (a `v{N}` folder per extraction, as `scrub_frames` writes, does it by construction):
 
 ```js
 const framePath = (i) => `/hero-frames/frame_${String(i).padStart(3, '0')}.jpg?v=2`

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

@@ -27,6 +27,16 @@ The harness gives each worktree a **block of 10 ports** (`.morph/worktree.env`,
 
 Also exported: `COMPOSE_PROJECT_NAME=morph-{feature}` (isolates container, network and volume names), `MORPH_PORT_BASE`, `MORPH_PORT_RANGE`, `PLAYWRIGHT_BASE_URL=http://localhost:<+0>`.
 
+## Project-named port variables
+
+The harness exports only the four names above. A compose file that reads a port by another name (`"${PG_PORT:-5433}:5432"`) is **not** fed by the block: it publishes its own default, or whatever a `.env.e2e` copied from a sibling worktree carries, while `worktree.env` announces a different port. Hand-run specs then hit a closed port, or worse, seed one postgres and read another. Declare the name the project reads:
+
+```json
+{ "e2e": { "portEnvNames": { "postgres": "PG_PORT" } } }
+```
+
+Keys are `web`, `api`, `postgres` and `redis`. Each declared name carries the **same value** as the standard variable, everywhere the layout goes: `worktree.env`, the compose env of `verify`/`e2e up`/`morph-spec env`, and the `PreToolUse:Bash` hook. Being layout, it is ignored (and named on stderr) if the credentials file carries it. An entry the harness cannot honour — unknown port, invalid or reserved name, a name used twice — is dropped and named on stderr.
+
 ## Core Rules
 
 - NEVER set `container_name` — Compose already names containers `<project>-<service>-1`, and an explicit name is shared by every worktree
@@ -36,7 +46,7 @@ Also exported: `COMPOSE_PROJECT_NAME=morph-{feature}` (isolates container, netwo
 - ALWAYS give `DATABASE_URL` an in-network default so the stack comes up with no `.env`: `postgresql://postgres:postgres@postgres:5432/${POSTGRES_DB:-app}`
 - ALWAYS read the base URL from the environment in `playwright.config.ts`: `process.env.PLAYWRIGHT_BASE_URL ?? \`http://localhost:${process.env.PORT ?? 3000}\``
 - NEVER put a cloud connection string (Neon branch etc.) in `.morph/worktree.env` — it is regenerated; credentials go in the gitignored file named by `config.json → e2e.auth.envFile`
-- NEVER put a variable from the port layout table above (nor `PLAYWRIGHT_BASE_URL`) in that credentials file — the harness **ignores** it and says which key it ignored on stderr. Ports come from the allocated block; the file carries credentials. A `.env.e2e` copied from a sibling worktree carries THAT worktree's block, and before the filter existed it silently repointed this stack at the neighbour's postgres
+- NEVER put a variable from the port layout table above (nor `PLAYWRIGHT_BASE_URL`, nor a name declared in `e2e.portEnvNames`) in that credentials file — the harness **ignores** it and says which key it ignored on stderr. Ports come from the allocated block; the file carries credentials. A `.env.e2e` copied from a sibling worktree carries THAT worktree's block, and before the filter existed it silently repointed this stack at the neighbour's postgres
 
 ## What the harness enforces
 

package/package.json

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