@polymorphism-tech/morph-spec 8.22.0 → 8.23.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.22.0  
+**Version:** 8.23.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -368,4 +368,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.22.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.23.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -42,6 +42,7 @@ import { retypeCommand } from '../src/commands/state/retype.js';
 import { handoffCommand } from '../src/commands/state/handoff.js';
 import { listCommand } from '../src/commands/state/list.js';
 import { deleteCommand } from '../src/commands/state/delete.js';
+import { usecaseReserveCommand } from '../src/commands/state/usecase.js';
 
 // === Tasks ===
 import { dagCommand } from '../src/commands/tasks/dag.js';
@@ -258,6 +259,19 @@ program
   .option('--json', 'Output as JSON')
   .action((feature, options) => handoffCommand(feature, options));
 
+// ─── Use cases ────────────────────────────────────────────────────────────
+const usecaseCommand = program
+  .command('usecase')
+  .description('Project-wide UC-{nn} numbering (acervo + every worktree of this repo)');
+
+usecaseCommand
+  .command('reserve')
+  .description('Atomically reserve the next N UC-{nn} numbers, shared across every worktree of this repo — replaces the old max+1 disk scan, which collides across worktrees')
+  .option('--count <n>', 'How many numbers to reserve', '1')
+  .option('--feature <name>', 'Feature to record as the reservation owner (defaults to the sole active feature, if unambiguous) — also what the promotion collision guard compares against')
+  .option('--json', 'Output as JSON')
+  .action((options) => usecaseReserveCommand(options));
+
 // ─── Tasks ────────────────────────────────────────────────────────────────
 program
   .command('dag <feature>')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.22.0",
+  "version": "8.23.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.22.0 by Polymorphism Tech*
+*morph-spec v8.23.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

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

package/framework/MORPH.md

@@ -122,7 +122,7 @@ Features independentes podem ser desenvolvidas **em paralelo, cada uma no seu gi
 - **Ambiente separado (portas):** o setup aloca um **bloco de portas determinístico** por feature em `.morph/worktree.env` (`PORT`, `MORPH_PORT_RANGE`; `ASPNETCORE_URLS` se dotnet). **Suba dev servers SEMPRE nas portas do bloco** — as portas padrão (3000/5000) pertencem à raiz. Arquivo local, git-invisível; SessionStart injeta as portas. Overrides em `config.json → fleet.basePort/blockSize`.
 - **Banco de dados:** compartilhado por padrão. Isolamento real (Neon MCP): branch de DB `morph/{f}` + connection string no `.morph/worktree.env`; sem Neon, prefixe schema/DB local pelo nome da feature. Migration destrutiva compartilhando banco → integre antes de abrir worktrees irmãos.
 - **Limitação conhecida:** `node_modules` compartilhado (junction) — mudança de dependência afeta os irmãos. Mudou dependência: conclua e integre (`finish`) antes de seguir em paralelo.
-- **Handoff entre sessões:** `.morph/features/{f}/handoff.md` — documento de retomada comprimido, regenerável (`morph-spec handoff <f>`), **aponta** para os artefatos em vez de copiá-los. Regenerado em `worktree setup`/`create --worktree`/`advance`. **Leia-o antes de re-derivar contexto à mão.** Nunca edite manualmente.
+- **Handoff entre sessões:** `.morph/features/{f}/handoff.md` — documento de retomada comprimido, regenerável (`morph-spec handoff <f>`), **aponta** para os artefatos em vez de copiá-los. Regenerado em `worktree setup`/`create --worktree`/`advance`/`approve`. **Leia-o antes de re-derivar contexto à mão.** Nunca edite manualmente.
 - **Visão da frota:** `morph-spec fleet` agrega raiz + worktrees (fase, gates, tasks, portas, handoff, último commit, sujeira). `morph-spec worktree list` é a visão enxuta por worktree.
 - **Ownership de arquivos:** sem lock em runtime — colisão se resolve **em plan-time** (`morph-spec dag` detecta overlap de `outputs`, recomenda `isolation: "worktree"`) e **por construção** (uma feature = um worktree = um escritor). Arquivos compartilhados convergem no merge do `finish`; conflito ali é escopo sobreposto, não bug.
 - **Fechamento:** aprove o Gate 3, depois **`morph-spec finish <f> --pr|--merge`** — encerramento único e simétrico. **Arquiva** commitando `features/{f} → archive/{f}` **dentro de `morph/{f}`** e integra: `--merge` faz `--no-ff` **local** (sem push; recusa se sujo; aborta em conflito); `--pr` faz `push` + `gh pr create` (exige `origin`+`gh`, checados **antes** de arquivar). Worktree desmontado (PROVE-or-DECLINE), portas liberadas; no `--pr` a branch é **preservada**. `morph-spec archive` fica para arquivar-sem-integrar (features legadas, faxina).

package/framework/agents.json

@@ -20,6 +20,7 @@
         "backend-dotnet-result-pattern",
         "backend-dotnet-vsa-handler-patterns",
         "backend-dotnet-fluent-validation-vsa",
+        "backend-dotnet-testing",
         "backend-integrations-neon-auth-neon-auth"
       ],
       "mcp": ["context7"],

package/framework/docs/CLI.md

@@ -21,10 +21,11 @@
 
 ## Worktree / Fleet
 
-- **`morph-spec finish <feature> --pr|--merge`** — o **encerramento único** da feature (worktree ou comum): **arquiva** commitando `features/{f} → archive/{f}` dentro de `morph/{f}` — promovendo junto, no mesmo commit, os use cases da feature para o acervo permanente `.morph/specs/usecases/` com `status: implemented` (fail-open: sem `2-plan/usecases/`, no-op silencioso) — depois integra. `--merge` faz merge `--no-ff` **local** na default (sem push); `--pr` faz `push` + `gh pr create` (exige `origin` + `gh`, checados **antes** de arquivar — um `--pr` recusado não deixa meio-estado). Desmonta o worktree (PROVE-or-DECLINE) e libera o bloco de portas; no `--pr` **preserva** a branch (o PR precisa dela) e fica em `morph/{f}`. Flags: `--keep` mantém o worktree, `--force` dispensa o Gate 3, `--discard-ignored` consente descartar gitignored no teardown. Substitui o antigo `worktree finish` + `archive` separados.
+- **`morph-spec finish <feature> --pr|--merge`** — o **encerramento único** da feature (worktree ou comum): **arquiva** commitando `features/{f} → archive/{f}` dentro de `morph/{f}` — promovendo junto, no mesmo commit, os use cases da feature para o acervo permanente `.morph/specs/usecases/` com `status: implemented` (fail-open: sem `2-plan/usecases/`, no-op silencioso) — depois integra. Um `UC-{nn}` cuja promoção colide com outra feature já publicada sob o mesmo número (`ucCollisions` no output; ver `usecase reserve` abaixo) **não é promovido**, mas isso nunca recusa o `finish` — só aquele use case fica de fora, com a mensagem apontando onde o arquivo ficou e como recuperar. `--merge` faz merge `--no-ff` **local** na default (sem push); `--pr` faz `push` + `gh pr create` (exige `origin` + `gh`, checados **antes** de arquivar — um `--pr` recusado não deixa meio-estado). Desmonta o worktree (PROVE-or-DECLINE) e libera o bloco de portas; no `--pr` **preserva** a branch (o PR precisa dela) e fica em `morph/{f}`. Flags: `--keep` mantém o worktree, `--force` dispensa o Gate 3, `--discard-ignored` consente descartar gitignored no teardown. Substitui o antigo `worktree finish` + `archive` separados.
+- **`morph-spec usecase reserve [--count <n>] [--feature <name>] [--json]`** — reserva atomicamente os próximos N números `UC-{nn}`, compartilhado por **todo worktree** deste repo (`<git-common-dir>/morph-spec/uc-registry.json`, mesmo mecanismo do `claim`/env-registry do fleet). Substitui o scan manual "leia o acervo + as features da árvore e some 1": um scan só enxerga a ÁRVORE CORRENTE, então dois worktrees planejando ao mesmo tempo mintavam o MESMO número — colisão que a promoção do `finish` resolvia sobrescrevendo por ID, apagando o use case do primeiro a chegar (já custou perda de dados em produção). O contador nunca regride (semeado do maior número já visto no acervo + nas features da árvore + no próprio registro). `--feature` é mais que auditoria: é o sinal que o guarda de colisão do `finish`/`archive` usa para distinguir uma correção legítima (`bug`, nunca reserva — reaproveita um número publicado) de uma colisão real (a feature reservou o número e o acervo já tem outra dona nele); sem `--feature`, infere a única feature ativa se for inequívoco. Fora de um repositório git: cai para o scan local (avisa no output, `shared: false`) — ainda evita autocolisão dentro da mesma árvore, mas sem a garantia entre worktrees.
 - **`morph-spec archive <feature>`** — arquiva-**sem-integrar** (atômico, git-aware, commita o move escopado por pathspec): reservado a features legadas (sem branch `morph/{f}`) e faxina. O fechamento normal (arquiva **e** integra num passo) é `morph-spec finish`. É o que `/morph-archive` chama.
 - **`morph-spec worktree setup|link|list`** — gerencia o ciclo do worktree por feature (`setup` cria `worktrees/{f}/` na branch `morph/{f}`, aloca o bloco de portas e escreve `.morph/worktree.env`; `link` religa infra compartilhada; `list` mostra fase/gate de cada worktree ativo). O fechamento saiu daqui — use `morph-spec finish` (acima).
-- **`morph-spec handoff <feature>`** — regenera o documento de retomada (`.morph/features/{f}/handoff.md`): comprimido, derivado, aponta para os artefatos em vez de copiá-los. Gerado automaticamente em `setup`/`create --worktree`/`advance`.
+- **`morph-spec handoff <feature>`** — regenera o documento de retomada (`.morph/features/{f}/handoff.md`): comprimido, derivado, aponta para os artefatos em vez de copiá-los. Gerado automaticamente em `setup`/`create --worktree`/`advance`/`approve`.
 - **`morph-spec fleet`** — visão da frota: toda feature ativa (raiz + worktrees) com fase, gates pendentes, tasks, **remoto** (`local`/`pushed`/`PR #N`), **claim** (que sessão está na feature), portas, handoff e atividade. Use entre sessões para decidir onde atuar.
 - **`morph-spec claim [feature] [--release] [--list] [--json]`** — posse **advisory** de feature. Cada sessão reclama sua feature ativa automaticamente (hook SessionStart) e renova o heartbeat a cada tool call; o registro vive em `<git-common-dir>/morph-spec/claims.json`, compartilhado por todos os worktrees. **`morph-spec claim <feature>` (sem flags) ADQUIRE** — se esta árvore já tinha claim vivo em outra feature, ele é liberado no mesmo passo (o CLI reporta "movido de X para Y"); é o jeito de trocar de feature no meio da tarefa sem a dança de dois passos `--release` + reclamar. `--list` força a leitura sem adquirir mesmo passando uma feature. **Claims avisam, nunca bloqueiam** — mas se o SessionStart avisar que outra sessão tem claim vivo, **confirme antes de `finish`/`archive`/`delete`**: duas sessões na mesma feature já custaram um recap.md inteiro e um sub-agent (o worktree sumiu debaixo dele). Claim órfão de sessão morta: `morph-spec claim <f> --release`.
 

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.22.0"
+cliVersion: "8.23.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.22.0"
+cliVersion: "8.23.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.22.0"
+cliVersion: "8.23.0"
 ---
 
 # morph-apply

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.22.0"
+cliVersion: "8.23.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.22.0"
+cliVersion: "8.23.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.22.0"
+cliVersion: "8.23.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.22.0"
+cliVersion: "8.23.0"
 ---
 
 # morph-implement
@@ -129,9 +129,21 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    - **`outputs` contém apenas paths realmente produzidos.** Deleções, remoções
      e anotações (ex.: `"pasta/ (removido: a, b)"`) se registram em `notes`,
      nunca em `outputs`. E `notes` é **uma string única** — não um array.
+   - **`outputs` DEVE listar TODO arquivo criado ou modificado pela task — sem exceção.**
+     Isso inclui artefato auxiliar que não estava no plano original (ex.: uma
+     factory de design-time, um seed, um arquivo de config gerado a reboque de
+     outro output) — se a task o produziu, ele entra em `outputs` junto com o
+     resto. Arquivo shipped sem dono em `outputs` de task alguma é falha de
+     protocolo: o Gate 3 (avaliador independente da `morph-review`) aponta como
+     achado de rastreabilidade, mesmo que o arquivo em si esteja correto — quem
+     lê `tasks.json`/`recap.md` depois precisa achar todo arquivo em produção
+     citado em algum lugar, e é essa a lacuna que este parágrafo fecha.
    - **Se os `outputs` reais divergirem dos planejados**, registre o porquê em
      `notes` na mesma edição — o hook exige a note quando há divergência (e a
-     mensagem de violação aponta o campo/valor exato do problema).
+     mensagem de violação aponta o campo/valor exato do problema). Isto é o
+     caso mais comum em que a regra acima se aplica: todo arquivo extra na lista
+     de "realmente produzidos" acima do planejado é, por definição, uma
+     divergência real vs. planejado — a note explica o porquê.
    - `tasks.json` é protegido após o Gate 2: o hook `protect-spec-files` faz diff
      semântico e libera Write ou Edit desde que nenhum campo de contrato do plano
      (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`)

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.22.0"
+cliVersion: "8.23.0"
 ---
 
 # morph-plan
@@ -56,7 +56,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
    **A regra que sustenta a camada inteira: pós-condição precisa ser observável em teste.** "O sistema fica consistente" não passa. "A resposta contém todos os veterinários não arquivados" passa. Antes de escrever cada pós-condição, pergunte: *que asserção eu escreveria para verificar isto?* Se não há resposta, a pós-condição está mal formulada — reescreva ou descarte. Sem esse filtro a camada vira prosa e não chega ao `doneCriteria`.
 
-   **Identificador sequencial no projeto, não na feature.** Antes de numerar, leia o acervo `.morph/specs/usecases/` (se existir) mais os use cases das features ativas em `.morph/features/*/2-plan/usecases/`; tome o maior `UC-{nn}` e some um. Numerar por feature garante colisão no momento da promoção.
+   **Identificador sequencial, reservado — nunca leia o disco à mão.** Rode `morph-spec usecase reserve --count {n} --feature {feature}` (`n` = quantos UCs esta feature vai criar; pode reservar de novo se descobrir mais no meio do plano). Um scan manual do maior `UC-{nn}` só enxerga a ÁRVORE CORRENTE — cada worktree tem a própria cópia de `.morph/features/`, então dois worktrees planejando ao mesmo tempo calculam o mesmo maior número e mintam o MESMO `UC-{nn}` sem saber um do outro; na promoção do `finish`, o segundo a fechar sobrescreve por ID e **apaga o use case do primeiro** — já causou perda de dados em produção. `usecase reserve` aloca atomicamente a partir de um contador compartilhado em `<git-common-dir>/morph-spec/uc-registry.json` (visível a todo worktree do repo, mesmo mecanismo do `claim`/fleet), semeado do maior número já visto no acervo + nas features da árvore corrente + no próprio contador — nunca regride. Fora de um repositório git, cai para o scan local antigo e avisa que o paralelismo entre worktrees não está protegido.
 
    **Seções obrigatórias:** `Pré-condições` (o que já é verdade antes), `Cenário principal` (o caminho feliz, numerado, **curto** — não é o lugar para exaustão de casos) e `Pós-condições` (**P1**, **P2**… — o que passa a ser verdade, cada uma testável; é a seção que viaja **literal** ao `doneCriteria`, ver abaixo).
 
@@ -67,12 +67,14 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    | Tipo | Use case |
    |---|---|
    | `feature` | Obrigatório quando há comportamento observável. Feature puramente técnica (refactor, infra, migração) dispensa — **registre a dispensa em `decisions.md`**. |
-   | `bug` | Não cria novo: **copie** o `UC-{nn}-*.md` do acervo para `2-plan/usecases/` e **corrija ou adicione a pós-condição** lá — o bug é a pós-condição que faltava. |
+   | `bug` | Não cria novo, não reserva número novo: **copie** o `UC-{nn}-*.md` do acervo para `2-plan/usecases/` **mantendo o nome do arquivo publicado** (mesmo slug) e **corrija ou adicione a pós-condição** lá — o bug é a pós-condição que faltava, não a identidade do UC. É esse mesmo nome, inalterado, que faz o `finish` reconhecer a correção como o MESMO UC (abaixo) em vez de uma colisão. |
    | `chore` | Nenhum (já pula a fase plan por política). |
    | `hotfix` | Não bloqueia. Referencia se existir; o pós-mortem pode virar pós-condição numa feature posterior. |
 
    **Nunca edite `.morph/specs/usecases/` à mão.** A única via de escrita no acervo é a promoção do `finish`, que lê **só** de `2-plan/usecases/`: é ela que carimba `status: implemented`, sobrescreve por ID (mesmo com slug novo) e leva o arquivo no commit de arquivamento. Editar o acervo direto pula os três e cria uma segunda verdade fora do mecanismo. Mudar um UC existente = copiar para o `2-plan/usecases/` da feature, corrigir lá, e deixar o `finish` sobrescrever.
 
+   **Backstop de colisão na promoção.** Se, apesar da reserva, duas features chegarem à promoção com o MESMO `UC-{nn}` e slugs diferentes — registro de reserva aponta para uma feature diferente da que já está no acervo —, o `finish`/`archive` **recusa promover esse UC específico** (nunca recusa fechar a feature: fail-open, só aquele use case fica de fora) e imprime onde o arquivo ficou e como recuperar. Se acontecer: renumere com `usecase reserve` e promova manualmente, ou — se for mesmo o caso `bug` — confira se o slug bate com o publicado.
+
    O use case fica **editável depois do Gate 2**, por design — é o que permite mudar o comportamento e re-rodar `implement`. A trilha de auditoria fica no git.
 
 3. Produza `spec.md` em `.morph/features/{feature}/2-plan/`:
@@ -223,7 +225,7 @@ Ao registrar a aprovação do Gate 2, atualize o frontmatter de cada use case de
 - `morph-spec standards --find "<query>"` — para identificar standards relevantes ao mandate (o índice inteiro só como navegação exploratória; ver `morph-standards`)
 - `.morph/framework/agents.json` — personas por domínio; lido UMA VEZ no passo 5a para carimbar `agent`/`standards` por task
 - `.morph/framework/schemas/tasks.schema.json` — schema obrigatório de tasks.json
-- `.morph/specs/usecases/` — acervo permanente de use cases do projeto (leia antes de numerar; em `bug`, é onde mora o UC a corrigir)
+- `.morph/specs/usecases/` — acervo permanente de use cases do projeto (`usecase reserve` já lê antes de numerar; em `bug`, é onde mora o UC a corrigir)
 - `.morph/features/{feature}/0-proposal/proposal.md` — escopo da feature
 - `.morph/features/{feature}/0-proposal/stack-scan.md` — contexto técnico detectado
 - `.morph/framework/schemas/tasks.schema.json` — schema e enums de tasks.json

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

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.22.0"
+cliVersion: "8.23.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.22.0"
+cliVersion: "8.23.0"
 ---
 
 # morph-review
@@ -42,7 +42,23 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
      confirme que usam duas constantes de prefixo nomeadas distintas, nenhuma reusada para o
      outro propósito. Falha aqui é bloqueante — quebra silenciosa em runtime, não em build.
 
-4. **Despache o avaliador independente** — o score do Gate 3 nunca é auto-atribuído por quem implementou:
+4. **Antes de despachar, verifique se já existe um relatório íntegro** — inclusive em sessão
+   retomada. **Esta verificação NÃO é pulada porque a sessão foi retomada** — é exatamente esse o
+   cenário que já mordeu em produção: 4 sessões retomadas re-despacharam o avaliador do Gate 3 sem
+   nunca ler o `evaluator-report.md` que já existia, íntegro, desde o 1º dispatch (`APPROVED`, score
+   9.3) — e a 4ª sessão chegou a afirmar, falsamente, que "o avaliador nunca rodou". `SessionStart:
+   resume`/`init` não reseta este passo: ele roda sempre, a cada retomada de controle, antes de
+   cogitar um dispatch.
+   - Rode `morph-spec report-check {feature} --json` (sem `task`, modo feature inteira) e leia o
+     campo `evaluator` da resposta — ou, equivalente, leia `4-review/evaluator-report.md` direto e
+     confira: scores por dimensão presentes + a linha `**Composite-Score:**` presente = **íntegro**.
+   - **Se íntegro** (`evaluator.exists && evaluator.complete`): **NÃO despache de novo.** Pule direto
+     para "**Leia primeiro**" logo abaixo — leia o arquivo e siga para o passo 5 (síntese do
+     review-report a partir dele). Re-despachar aqui joga fora um veredito de Gate 3 já válido.
+   - **Se ausente, oco, ou sem scores por dimensão:** este é exatamente o caso de falha de protocolo
+     que este passo trata — prossiga com o dispatch abaixo.
+
+   **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`).
    - **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**
@@ -53,6 +69,9 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
        legítimo; "docker indisponível no ambiente" numa feature de UI **não** é — registre você mesmo
        `morph-spec gate-decision {feature} review --pause true --reason "e2e não verificado: {razão}"`.
        O disco não distingue dispensa legítima de verificação que faltou; esse julgamento é seu.
+   - **Confira também `traceability.warnings`** (advisory, nunca faz `verify` falhar): cada entrada é
+     um arquivo citado no `recap.md` sem task dona em `outputs` — repasse ao avaliador como sinal de
+     rastreabilidade para a dimensão de qualidade, não como bloqueio automático do gate.
    - Gere o **diff da implementação** (`git diff` do range da feature, ou a lista de arquivos do recap.md com seus conteúdos atuais).
    - Despache o subagent registrado `morph-evaluator` (gerado de `agents.json` — a persona do avaliador é o system prompt dele, com Read/Glob/Grep + Bash somente para verificação + Playwright para navegar, sem Write/Edit), com contexto fresco:
      ```
@@ -61,7 +80,14 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
                  + nó e2e do verify (stack no ar? em qual URL?)
        instrução: |
          Você NÃO participou da implementação — avalie o que está no diff,
-         contra o mandate. Você tem Bash: use `morph-spec verify`, testes/build
+         contra o mandate. NÃO leia `4-review/evaluator-report.md` neste
+         caminho antes de escrever o seu: se esse arquivo já existir quando
+         você começar, é resíduo de uma tentativa anterior — NÃO é insumo,
+         é o SEU caminho de escrita, não de leitura. Sua nota nasce do
+         mandate + spec + diff + testes, nunca do veredito de outro
+         avaliador; ler o relatório de um antecessor antes de pontuar é
+         ancoragem — exatamente o que "contexto fresco" existe para evitar.
+         Você tem Bash: use `morph-spec verify`, testes/build
          do stack e `git log/diff/show` para conferir por conta própria o que
          foi reportado, em vez de confiar cegamente. Aplique as rubricas em
          .morph/framework/evals/rubrics/ (architecture 30%, contracts 25%,

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.22.0"
+cliVersion: "8.23.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.22.0"
+cliVersion: "8.23.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.22.0"
+cliVersion: "8.23.0"
 ---
 
 # morph-uiux

package/framework/standards/STANDARDS.json

@@ -1779,6 +1779,34 @@
         "data-ingestion": "#microsoftextensionsdataingestion-preview--pipeline-pattern-para-adoção-futura"
       },
       "digest": "Microsoft.Extensions.VectorData.Abstractions (GA) is the provider-agnostic vector-store abstraction; Microsoft.Extensions.DataIngestion (preview) is the companion ETL pipeline. Concrete connectors (Postgres, Qdrant, SQL Server...) ship under Microsoft.SemanticKernel.Connectors.* package names despite having nothing to do with Semantic Kernel — an explicit exception to ai-agents-setup's SK ban. Default RAG storage stays ai-agents-rag-custom-pgvector; adopt VectorData only for genuine multi-backend portability, since the Postgres connector is still prerelease."
+    },
+    {
+      "id": "backend-dotnet-testing",
+      "name": "testing",
+      "path": "backend/dotnet/testing.md",
+      "category": "backend",
+      "subcategory": "dotnet",
+      "tags": [
+        "backend",
+        "dotnet"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "xunit",
+        "TimeProvider",
+        "FakeTimeProvider",
+        "fake clock",
+        "integration test",
+        "ProblemDetails",
+        "error body assertion"
+      ],
+      "anchors": {
+        "clock": "#rule-1--inject-timeprovider-fake-it-with-faketimeprovider-in-tests",
+        "errorbody": "#rule-2--error-path-tests-assert-the-response-body-not-just-the-status-code"
+      },
+      "digest": "Inject TimeProvider (never DateTime.UtcNow / DateOnly.FromDateTime(DateTime.UtcNow) directly in a handler or validator) and fake it with FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) in integration tests — deterministic, no midnight-UTC flake, boundary dates (today vs. yesterday) become facts about the fake clock instead of when the suite happens to run. xUnit + WebApplicationFactory error-path tests (400/404/409) must assert the ProblemDetails response BODY (title/detail/violated field or error code), never just the HTTP status code — a status-only assertion lets the wrong validation rule or the wrong error branch pass silently as long as the status matches."
     }
   ],
   "sharedAliases": {

package/framework/standards/backend/dotnet/fluent-validation-vsa.md

@@ -23,7 +23,10 @@ One validator per request DTO. Lives in the same feature folder as the handler:
 // Features/BookFeature/CreateBook/CreateBookValidator.cs
 public class CreateBookValidator : AbstractValidator<CreateBookRequest>
 {
-    public CreateBookValidator()
+    // TimeProvider injected, never DateTime.UtcNow read directly — see
+    // backend-dotnet-testing (Rule 1): a validator that reads the real clock
+    // cannot be tested deterministically with FakeTimeProvider.
+    public CreateBookValidator(TimeProvider timeProvider)
     {
         RuleFor(c => c.Title)
             .NotEmpty().WithMessage("Title is required")
@@ -41,7 +44,7 @@ public class CreateBookValidator : AbstractValidator<CreateBookRequest>
 
         RuleFor(c => c.PublishedYear)
             .GreaterThan(1000).WithMessage("Published year must be a valid year")
-            .LessThanOrEqualTo(DateTime.UtcNow.Year)
+            .LessThanOrEqualTo(timeProvider.GetUtcNow().Year)
             .WithMessage("Published year cannot be in the future");
     }
 }

package/framework/standards/backend/dotnet/testing.md

@@ -0,0 +1,127 @@
+# .NET Integration Testing — VSA
+
+> **Scope:** dotnet-vsa
+> **Layer:** 0 (always load)
+> **Keywords:** testing, xunit, integration test, TimeProvider, FakeTimeProvider, WebApplicationFactory, ProblemDetails, error body assertion
+> **Load When:** writing or reviewing tests for a dotnet VSA project
+
+**Verified against:** .NET 10 + xUnit 2 + `Microsoft.Extensions.TimeProvider.Testing`. Last-verified: 2026-08-12.
+
+---
+
+## Overview
+
+Integration tests exercise the real ASP.NET Core pipeline (`WebApplicationFactory`) against
+an in-memory/test database — the pattern used across `backend-dotnet-vsa-handler-patterns`'
+handler examples. Two failure modes recur in generated test suites and each has a dedicated
+rule below: tests that read the real system clock instead of an injected, fakeable one; and
+error-path tests that assert only the HTTP status code, leaving the actual failure contract
+(the response body) unverified.
+
+---
+
+## Rule 1 — Inject `TimeProvider`, fake it with `FakeTimeProvider` in tests
+
+Any logic that compares against "now" (a past-date validation, an expiry check, a due-date
+default) MUST read the clock through an injected `TimeProvider` — never `DateTime.UtcNow` or
+`DateOnly.FromDateTime(DateTime.UtcNow)` directly in a handler or validator. A validator that
+reads the real clock makes "today" a moving target: a test asserting "today is valid, yesterday
+is rejected" flakes for real around UTC midnight, and is untestable for the "exactly at the
+boundary" case at all.
+
+```csharp
+// Features/VisitFeature/CloseVisit/CloseVisitValidator.cs
+public sealed class CloseVisitValidator : AbstractValidator<CloseVisitRequest>
+{
+    public CloseVisitValidator(TimeProvider timeProvider)
+    {
+        RuleFor(c => c.FollowUpDate)
+            .Must(date => date!.Value >= Today(timeProvider))
+            .WithErrorCode(VisitErrors.FollowUpDateInPast.Code)
+            .WithMessage(VisitErrors.FollowUpDateInPast.Description)
+            .When(c => c.FollowUpDate.HasValue);
+    }
+
+    private static DateOnly Today(TimeProvider timeProvider) =>
+        DateOnly.FromDateTime(timeProvider.GetUtcNow().UtcDateTime);
+}
+```
+
+Register the real clock once in `Program.cs`:
+
+```csharp
+builder.Services.AddSingleton(TimeProvider.System);
+```
+
+In tests, swap it for `Microsoft.Extensions.TimeProvider.Testing`'s `FakeTimeProvider` —
+deterministic, no dependency on when the suite happens to run:
+
+```csharp
+// tests/.../Infrastructure/VetClinicApiFactory.cs
+public sealed class VetClinicApiFactory : WebApplicationFactory<Program>
+{
+    public FakeTimeProvider TimeProvider { get; } = new(new DateTimeOffset(2026, 6, 15, 0, 0, 0, TimeSpan.Zero));
+
+    protected override void ConfigureWebHost(IWebHostBuilder builder) =>
+        builder.ConfigureServices(services =>
+        {
+            services.RemoveAll<TimeProvider>();
+            services.AddSingleton<TimeProvider>(TimeProvider);
+        });
+}
+```
+
+```csharp
+// The boundary case ("today is accepted, yesterday is not") becomes a fact about
+// the fake clock, not about when CI happens to run.
+DateOnly today = DateOnly.FromDateTime(factory.TimeProvider.GetUtcNow().UtcDateTime);
+DateOnly yesterday = today.AddDays(-1);
+```
+
+---
+
+## Rule 2 — Error-path tests assert the response BODY, not just the status code
+
+A test that only checks `response.StatusCode` proves the endpoint returns *a* 400/404/409 — it
+proves nothing about *why*, and lets the wrong validation rule or the wrong error code pass
+silently as long as the status happens to match. Every error-path test MUST also assert the
+`ProblemDetails` body: at minimum `title` (or `type`) and the specific field/reason that
+triggered the failure.
+
+```csharp
+// Wrong — proves only that SOMETHING was rejected, not what:
+HttpResponseMessage response = await client.PostAsJsonAsync($"visits/{id}/close", body);
+Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+```
+
+```csharp
+// Right — the body is the actual contract a client integrates against:
+HttpResponseMessage response = await client.PostAsJsonAsync($"visits/{id}/close", body);
+Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
+
+ProblemDetails? problem = await response.Content.ReadFromJsonAsync<ProblemDetails>();
+Assert.NotNull(problem);
+Assert.Contains("FollowUpDate", problem!.Extensions["errors"]!.ToString());
+Assert.Equal(VisitErrors.FollowUpDateInPast.Code, GetErrorCode(problem));
+```
+
+The same discipline applies to 404 (`NotFound` — assert the entity/id named in the problem
+detail) and 409 (`Conflict` — assert the conflict reason, e.g. `"Visit.AlreadyClosed"`, not just
+that a conflict happened). A status-only assertion is a regression magnet: swapping
+`VisitErrors.NotFound` for `VisitErrors.AlreadyClosed` in the wrong branch still returns 404/409
+respectively and the test suite stays green.
+
+---
+
+## Anti-Patterns
+
+| Do NOT | Do Instead |
+|--------|------------|
+| Read `DateTime.UtcNow` / `DateOnly.FromDateTime(DateTime.UtcNow)` directly in a handler or validator | Inject `TimeProvider`, read `timeProvider.GetUtcNow()` |
+| Leave a test's "past date" derived from the real system clock (`DateTime.UtcNow.AddDays(-1)`) | Swap `TimeProvider` for `FakeTimeProvider` in the test factory and derive dates from it |
+| Assert only `response.StatusCode` on an error path | Also deserialize and assert the `ProblemDetails` body (title/detail/violated field or error code) |
+| Treat a passing status-only test as proof the error message/code is correct | Assert the specific error code/field — a wrong branch can still return the right status |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/package.json

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

package/src/commands/state/approve.js

@@ -325,6 +325,17 @@ export async function approveCommand(featureName, gateName, options = {}) {
       ...(selfAssessed ? { selfAssessed: true } : {}),
     });
 
+    // Fleet handoff (mirrors advance.js): approving a gate is exactly when a
+    // feature hands over between sessions too — `approve` is the real path
+    // Gate 2 took in the field (`approve <f> plan --mode auto`), not just
+    // `advance`, so a handoff.md left stale after approve was the common
+    // case, not the edge case. Same helper, same fail-open contract: a
+    // regeneration failure must never fail the approval itself.
+    try {
+      const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
+      writeHandoff(featureName, process.cwd());
+    } catch { /* fail-open */ }
+
     if (selfAssessed) {
       console.log(chalk.yellow('\n⚠️  Gate 3 aprovado SEM avaliador independente (--self-assessed).'));
       console.log(chalk.gray('   Registrado em feature.json → approvalGates.review.selfAssessed.'));

package/src/commands/state/archive.js

@@ -63,7 +63,8 @@ function readReviewApproved(fjPath) {
  * @param {string} feature
  * @param {{ cwd?: string, force?: boolean, git?: boolean }} [opts]
  * @returns {{ ok: boolean, error?: string, archived?: boolean, alreadyArchived?: boolean,
- *   committed?: boolean, staged?: boolean, archivePath?: string, promotedUseCases?: string[] }}
+ *   committed?: boolean, staged?: boolean, archivePath?: string, promotedUseCases?: string[],
+ *   refusedUseCases?: Array<{id: string, incoming: string, existing: string, existingFeature: string, message: string}> }}
  */
 export function runArchive(feature, opts = {}) {
   const cwd = opts.cwd || process.cwd();
@@ -156,9 +157,11 @@ export function runArchive(feature, opts = {}) {
   //    (MORPH.md §2.2). Fail-open: any failure degrades to "promoted nothing",
   //    never to a refused close.
   let promotedUseCases = [];
+  let refusedUseCases = [];
   try {
-    const { promoted } = promoteUseCases(cwd, archivePath);
+    const { promoted, refused } = promoteUseCases(cwd, archivePath);
     promotedUseCases = promoted;
+    refusedUseCases = refused;
     if (promoted.length && useGit && staged) {
       // This staging exists for the NEW files: promoted use cases are untracked,
       // and the scoped `commit -- <pathspec>` below only knows paths git already
@@ -203,7 +206,7 @@ export function runArchive(feature, opts = {}) {
     } catch { /* index is derivable — non-fatal */ }
   }
 
-  return { ok: true, archived: true, committed, staged, archivePath, promotedUseCases };
+  return { ok: true, archived: true, committed, staged, archivePath, promotedUseCases, refusedUseCases };
 }
 
 /**
@@ -244,6 +247,12 @@ export async function archiveCommand(featureName, options = {}) {
     if (result.promotedUseCases?.length) {
       console.log(chalk.gray(`   ${result.promotedUseCases.length} use case(s) promoted → .morph/specs/usecases/ (status: implemented).`));
     }
+    if (result.refusedUseCases?.length) {
+      console.log(chalk.yellow(`\n⚠️  ${result.refusedUseCases.length} use case(s) NOT promoted — numbering collision:`));
+      for (const r of result.refusedUseCases) {
+        console.log(chalk.yellow(`   ${r.message}`));
+      }
+    }
     if (result.committed) console.log(chalk.gray(`   Move committed on the current branch.\n`));
     else if (result.staged) console.log(chalk.gray(`   Move staged in git; commit it when ready.\n`));
     else console.log('');