@polymorphism-tech/morph-spec 8.4.0 → 8.6.0

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

@@ -1,18 +1,20 @@
 ---
 name: morph-plan
-description: Guia a produção dos três artefatos de planejamento de uma feature (spec.md, mandate.md, tasks.json) e apresenta o Gate 2 trust-aware.
+description: Guia a produção dos artefatos de planejamento de uma feature (use cases, spec.md, mandate.md, tasks.json) e apresenta o Gate 2 trust-aware.
 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.4.0"
+cliVersion: "8.6.0"
 ---
 
 # morph-plan
 
 ## Objetivo
 
-Produzir `spec.md`, `mandate.md` e `tasks.json` com qualidade suficiente para abrir o Gate 2.
-Os três artefatos juntos definem o quê, o como e o quanto da feature.
+Produzir os **use cases**, `spec.md`, `mandate.md` e `tasks.json` com qualidade suficiente para abrir o Gate 2.
+Os use cases definem o **comportamento**; os três artefatos seguintes definem o como e o quanto da feature.
+
+A ordem importa e não é negociável: **comportamento antes de solução técnica**. Um `spec.md` escrito antes dos use cases resolve um problema que ainda não foi enunciado.
 
 ## Quando invocar
 
@@ -20,14 +22,70 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
 ## O que fazer
 
-1. **Garanta que `proposal.md` e `stack-scan.md` estão no seu contexto antes de planejar.** Se não tem o conteúdo atual em contexto (sessão fresca, ou conteúdo possivelmente desatualizado), **use a tool Read para carregá-los** — não confie em cache de turnos anteriores. Na dúvida, Read. `.morph/features/{feature}/0-proposal/proposal.md` (escopo, critérios de aceite, riscos) e `.morph/features/{feature}/0-proposal/stack-scan.md` (contexto técnico detectado: greenfield vs brownfield, stack atual, drift). Em brownfield, o stack-scan informa decisões de spec/mandate — não invente padrões que conflitam com o detectado.
+1. **Garanta que `proposal.md` e `stack-scan.md` estão no seu contexto antes de planejar.** Se não tem o conteúdo atual em contexto (sessão fresca, ou conteúdo possivelmente desatualizado), **use a tool Read para carregá-los** — não confie em cache de turnos anteriores. Na dúvida, Read. `.morph/features/{feature}/0-proposal/proposal.md` (problema, escopo, riscos — o comportamento é destilado aqui no passo 2, não vem pronto do proposal) e `.morph/features/{feature}/0-proposal/stack-scan.md` (contexto técnico detectado: greenfield vs brownfield, stack atual, drift). Em brownfield, o stack-scan informa decisões de spec/mandate — não invente padrões que conflitam com o detectado.
+
+2. **Destile os use cases — ANTES de escrever `spec.md` e `tasks.json`.**
+
+   Um arquivo por use case em `.morph/features/{feature}/2-plan/usecases/UC-{nn}-{slug}.md`:
+
+   ```markdown
+   ---
+   id: UC-07
+   title: Listar veterinários com suas especialidades
+   actor: Visitante
+   status: draft
+   entities: [Vet, Specialty]
+   ---
+
+   ## Pré-condições
+   - Existe ao menos um veterinário cadastrado
+
+   ## Cenário principal
+   1. Visitante acessa a listagem de veterinários
+   2. Sistema retorna os veterinários ordenados por sobrenome
+   3. Sistema exibe, para cada um, nome e especialidades
+
+   ## Fluxos alternativos
+   - **A1** — Nenhum veterinário cadastrado → sistema exibe estado vazio
+   - **A2** — Veterinário sem especialidade → sistema exibe "sem especialidade"
+
+   ## Pós-condições
+   - **P1** — A resposta contém todos os veterinários não arquivados
+   - **P2** — Cada veterinário traz suas especialidades em lista, nunca string concatenada
+   - **P3** — A ordenação por sobrenome é estável para nomes repetidos
+
+   ## Delta de domínio
+   - `Vet.archivedAt` (novo, nullable) — habilita P1
+   - Nenhuma relação nova
+   ```
+
+   **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`.
 
-2. Produza `spec.md` em `.morph/features/{feature}/2-plan/`:
+   **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.
+
+   **Seções:** `Pré-condições` (o que já é verdade antes), `Cenário principal` (o caminho feliz, numerado), `Fluxos alternativos` (**A1**, **A2**… — cada alternativa aproxima uma user story; edge case de *comportamento* mora aqui, edge case *técnico* fica no `spec.md`), `Pós-condições` (**P1**, **P2**… — o que passa a ser verdade, cada uma testável) e `Delta de domínio` (**só o que muda**: campo novo, relação nova, invariante nova — o modelo completo continua sendo o código EF Core mais as migrations; se a feature não altera o domínio, escreva "nenhum").
+
+   **Quando é obrigatório** (ver MORPH.md §2.1 para o roteamento por tipo):
+
+   | 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. |
+   | `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.
+
+   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/`:
    - Arquitetura da solução: quais componentes, como se conectam, fluxos de dados principais.
-   - Edge cases identificados e como serão tratados.
+   - Edge cases **técnicos** e como serão tratados (os de comportamento estão nos fluxos alternativos dos use cases).
    - Integrações externas e contratos esperados.
 
-3. Produza `mandate.md` em `.morph/features/{feature}/2-plan/`:
+   O `spec.md` responde **como** os use cases do passo 2 serão realizados. Não repita o comportamento aqui.
+
+4. Produza `mandate.md` em `.morph/features/{feature}/2-plan/`:
    - Stack exata do projeto (leia de `.morph/config/config.json` → `project.stack` ou do CLAUDE.md).
    - Standards obrigatórios: liste os IDs relevantes de `.morph/framework/standards/STANDARDS.json`.
    - Patterns proibidos — inclua sempre os defaults abaixo mais qualquer específico da feature:
@@ -41,7 +99,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via STANDARDS.json. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
    - Checklist de done com critérios verificáveis por tarefa.
 
-4. Produza `tasks.json` em `.morph/features/{feature}/2-plan/` seguindo o schema em `.morph/framework/schemas/tasks.schema.json`.
+5. Produza `tasks.json` em `.morph/features/{feature}/2-plan/` seguindo o schema em `.morph/framework/schemas/tasks.schema.json`.
 
    **Formato obrigatório** (schema em `.morph/framework/schemas/tasks.schema.json` — o hook `tasks-json-guard` valida cada write):
 
@@ -56,10 +114,11 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
          "description": "Detalhes — o que esta task realiza e por quê",
          "dependencies": [],
          "effort": "S",
-         "doneCriteria": "Critério verificável em 1 frase",
+         "doneCriteria": "P2 — Cada veterinário traz suas especialidades em lista, nunca string concatenada",
          "status": "pending",
          "outputs": [],
-         "group": "backend"
+         "group": "backend",
+         "usecase": "UC-07"
        }
      ]
    }
@@ -72,12 +131,19 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    - `status` inicia sempre como `pending`.
    - `group` (opcional): backend, frontend, tests, infra, docs. Default backend.
    - `outputs` (opcional): array de paths que serão criados/modificados.
+   - `usecase` (opcional): o **ID** do use case que a task realiza — `UC-07`, nunca o nome do arquivo. Task puramente técnica (build, config, migração) não tem.
+
+   **O `doneCriteria` carrega a pós-condição LITERAL.** Este é o elo que amarra a cadeia inteira: a pós-condição escrita em linguagem de negócio chega **sem tradução** ao critério que o `morph-spec verify` e o `morph-eval` cobram. Copie o texto da pós-condição, prefixado pelo seu rótulo (`"P2 — Cada veterinário traz..."`). Reescrever com outras palavras aqui é exatamente o ponto em que o requisito se perde hoje.
+
+   **`morph-spec dag {feature}` cobra o encanamento.** Ele lê os use cases junto com o `tasks.json` e reporta: referência a um `UC-{nn}` inexistente (**erro** — trava), pós-condição que nenhuma task cita (aviso) e task que referencia um UC mas parafraseou em vez de copiar (aviso). A comparação normaliza caixa e espaço, então prefixar o rótulo não quebra o casamento — mas a redação e os acentos precisam bater. O que o `dag` **não** julga é se a pós-condição é observável em teste: isso é semântico e continua sendo trabalho seu no Gate 2 e do evaluator.
+
+   Cada pós-condição de cada use case deve estar coberta por **pelo menos uma** task. Antes de fechar o `tasks.json`, percorra os `UC-*.md` e confira: sobrou pós-condição sem task? Ou o plano está incompleto, ou a pós-condição não era necessária — resolva antes do Gate 2, não depois.
 
    **Preencha `outputs` (paths planejados) em cada task** — o `morph-spec dag` usa os outputs para detectar colisão de arquivos entre fluxos paralelos e recomendar `isolation: "worktree"`. Task sem `outputs` entra como footprint desconhecido (não força isolamento, mas o dag não consegue protegê-la de colisão).
 
    Antes de retornar, valide rodando `morph-spec dag {feature}` — o comando parseia e valida o schema do tasks.json (ids únicos `T\d+`, enums de `status`/`effort`, `dependencies` válidas) e já imprime a análise de DAG que a `/morph-apply` vai usar. Erros de schema abortam com a lista do que corrigir.
 
-5. Apresente o Gate 2 segundo trust mode.
+6. Apresente o Gate 2 segundo trust mode.
 
    Você pode embutir o diagrama do DAG do plano via `morph-spec dag {feature} --mermaid` (flowchart Mermaid) para visualização no gate.
 
@@ -124,16 +190,20 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
 ## Output esperado
 
+- `.morph/features/{feature}/2-plan/usecases/UC-{nn}-{slug}.md` — um arquivo por use case, com pós-condições testáveis
 - `.morph/features/{feature}/2-plan/spec.md` — especificação técnica completa
 - `.morph/features/{feature}/2-plan/mandate.md` — contrato de implementação
-- `.morph/features/{feature}/2-plan/tasks.json` — task list estruturada válida contra schema
+- `.morph/features/{feature}/2-plan/tasks.json` — task list estruturada válida contra schema, com o `doneCriteria` carregando a pós-condição literal
 - Gate 2 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo)
 
+Ao registrar a aprovação do Gate 2, atualize o frontmatter de cada use case de `status: draft` para `status: approved`. O ciclo fecha na integração: `morph-spec finish` promove os use cases para o acervo permanente `.morph/specs/usecases/` já com `status: implemented`. O status é **descritivo** — quem trava fase é o gate, não este campo.
+
 ## Referências
 
 - `.morph/framework/MORPH.md` — seções 2 (Fases), 3 (Contratos de Output), 5 (Gates), Trust Mode
 - `.morph/framework/standards/STANDARDS.json` — para identificar standards relevantes ao mandate
 - `.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/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.4.0"
+cliVersion: "8.6.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.4.0"
+cliVersion: "8.6.0"
 ---
 
 # morph-review
@@ -102,7 +102,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    question: "Gate 3 — Review de {feature} aprovado?{ reason ? ' Sinal: ' + reason : '' }"
    header: "Gate 3"
    options:
-     - { label: "aprovado, fechar feature", description: "Marcar feature como completed, habilitar /morph-archive" }
+     - { label: "aprovado, fechar feature", description: "Marcar review aprovado; próximo passo é fechar com morph-spec finish --pr|--merge (ver morph-apply §6)" }
      - { label: "preciso ajustar", description: "Apontar correções necessárias antes de fechar" }
      - { label: "rollback", description: "Desfazer e voltar para implement" }
    ```
@@ -120,6 +120,8 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
    No caminho manual, o hook state-sync detecta a aprovação em answers de AskUserQuestion e grava `approvalGates.review = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo da feature. Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} review --mode auto` — nunca via Edit à mão de state.json.
 
+   **Próximo passo (não é desta skill):** com o Gate 3 aprovado, a feature fecha por `morph-spec finish {feature} --pr|--merge` — a `morph-apply` §6 conduz a escolha PR vs merge. Não arquive nem integre aqui.
+
 ## Output esperado
 - `.morph/features/{feature}/4-review/evaluator-report.md` — relatório bruto e autoritativo do
   `morph-evaluator` despachado no passo 4 (canal durável, ver MORPH.md §6)

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.4.0"
+cliVersion: "8.6.0"
 ---
 
 # morph-stack-scan

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

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.4.0"
+cliVersion: "8.6.0"
 ---
 
 # morph-standards

package/package.json

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