@polymorphism-tech/morph-spec 8.5.0 → 8.7.0

package/framework/hooks/shared/state-reader.js

@@ -181,6 +181,63 @@ export function getFeature(featureName, projectPath) {
  */
 export const PHASE_INDEX = { proposal: 0, uiux: 1, plan: 2, implement: 3, review: 4 };
 
+/**
+ * The canonical artifact of each phase, descending. Exported so a caller that
+ * holds the file list from somewhere OTHER than the local filesystem (a git
+ * tree, say) can answer the same question without re-encoding the map.
+ */
+export const PHASE_ARTIFACTS = [
+  ['4-review',    'review',    'review-report.md'],
+  ['3-implement', 'implement', 'recap.md'],
+  ['2-plan',      'plan',      'spec.md'],
+  ['1-design',    'uiux',      'design-system.md'],
+  ['0-proposal',  'proposal',  'proposal.md'],
+];
+
+const gatesOf = (feature) => feature?.approvals || feature?.approvalGates;
+
+/**
+ * Gate-implied phase from an ALREADY-LOADED feature object — no disk access.
+ *
+ * Split out of `gateImpliedPhase` so callers holding a feature.json that did
+ * not come from the working tree (e.g. `git show morph/{f}:…`) can reuse the
+ * rule instead of copying it. The path-based wrapper below is unchanged.
+ *
+ * @param {Object|null} feature
+ * @returns {string} phase name
+ */
+export function gateImpliedPhaseFrom(feature) {
+  const gates = gatesOf(feature);
+  const ok = (g) => gates?.[g]?.approved === true;
+  if (ok('review')) return 'review';
+  if (ok('plan')) return 'implement';
+  if (ok('uiux')) return 'plan';
+  return 'proposal';
+}
+
+/**
+ * Phase from an already-loaded feature plus an artifact predicate — no disk
+ * access of its own, so the artifact universe can be a git tree.
+ *
+ * @param {Object|null} feature
+ * @param {(relPath: string) => boolean} hasArtifact - receives POSIX-style
+ *   paths relative to the feature dir, e.g. `2-plan/spec.md`
+ * @returns {string} phase name
+ */
+export function derivePhaseFrom(feature, hasArtifact) {
+  let artifactPhase = 'proposal';
+  for (const [folder, phase, canonical] of PHASE_ARTIFACTS) {
+    if (hasArtifact(`${folder}/${canonical}`)) { artifactPhase = phase; break; }
+  }
+
+  // Gate-aware: an approved gate advances the phase even before the next
+  // phase's first canonical artifact exists. This breaks the chicken-and-egg
+  // where that first artifact could never be written because the phase never
+  // advanced to permit it. Take whichever of (artifact, gate-implied) is later.
+  const implied = gateImpliedPhaseFrom(feature);
+  return PHASE_INDEX[implied] > PHASE_INDEX[artifactPhase] ? implied : artifactPhase;
+}
+
 /**
  * The phase implied purely by approved gates, independent of which artifacts
  * exist on disk. An approved gate authorizes the NEXT phase, so:
@@ -192,32 +249,15 @@ export const PHASE_INDEX = { proposal: 0, uiux: 1, plan: 2, implement: 3, review
  * @returns {string} phase name
  */
 export function gateImpliedPhase(featureName, projectPath) {
-  if (isGateApproved(featureName, 'review', projectPath)) return 'review';
-  if (isGateApproved(featureName, 'plan', projectPath)) return 'implement';
-  if (isGateApproved(featureName, 'uiux', projectPath)) return 'plan';
-  return 'proposal';
+  return gateImpliedPhaseFrom(getFeature(featureName, projectPath));
 }
 
 export function derivePhaseForFeature(featureName, projectPath) {
   const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
-  const phaseMap = [
-    ['4-review',    'review',    'review-report.md'],
-    ['3-implement', 'implement', 'recap.md'],
-    ['2-plan',      'plan',      'spec.md'],
-    ['1-design',    'uiux',      'design-system.md'],
-    ['0-proposal',  'proposal',  'proposal.md'],
-  ];
-  let artifactPhase = 'proposal';
-  for (const [folder, phase, canonical] of phaseMap) {
-    if (existsSync(join(basePath, folder, canonical))) { artifactPhase = phase; break; }
-  }
-
-  // Gate-aware: an approved gate advances the phase even before the next
-  // phase's first canonical artifact exists. This breaks the chicken-and-egg
-  // where that first artifact could never be written because the phase never
-  // advanced to permit it. Take whichever of (artifact, gate-implied) is later.
-  const implied = gateImpliedPhase(featureName, projectPath);
-  return PHASE_INDEX[implied] > PHASE_INDEX[artifactPhase] ? implied : artifactPhase;
+  return derivePhaseFrom(
+    getFeature(featureName, projectPath),
+    (rel) => existsSync(join(basePath, rel)),
+  );
 }
 
 /**
@@ -253,10 +293,9 @@ export function isGateApproved(featureName, gate, projectPath) {
  * @param {string} [projectPath]
  * @returns {string[]} List of gate names that are not yet approved
  */
-export function getPendingGates(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
+export function pendingGatesFrom(feature) {
   // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
-  const gates = feature?.approvals || feature?.approvalGates;
+  const gates = gatesOf(feature);
   if (!gates) return [];
 
   return Object.entries(gates)
@@ -264,6 +303,10 @@ export function getPendingGates(featureName, projectPath) {
     .map(([name]) => name);
 }
 
+export function getPendingGates(featureName, projectPath) {
+  return pendingGatesFrom(getFeature(featureName, projectPath));
+}
+
 /**
  * Get feature outputs status.
  * @param {string} featureName

package/framework/rules/morph-task-tracking.md

@@ -33,11 +33,18 @@ TaskUpdate(taskId, subject="Round 3 — score 82/100")
 
 ## Persisting Progress to `tasks.json`
 
+> **Dois sistemas, dois vocabulários.** Tudo acima desta linha é sobre as *session
+> tasks* nativas do Claude Code (`TaskCreate`/`TaskUpdate`), cujo status terminal é
+> `completed`. Tudo abaixo é sobre o `tasks.json` do morph-spec, governado por
+> `.morph/framework/schemas/tasks.schema.json`, cujo status terminal é `done` —
+> **`completed` não existe nesse enum** e o hook `protect-spec-files` rejeita a
+> gravação. Não misture os dois.
+
 Native session tasks (`TaskCreate`/`TaskUpdate`) track your live work. To persist
 task progress for the feature, write `.morph/features/{feature}/2-plan/tasks.json`,
 touching ONLY the mutable fields:
 
-- `status` — `pending` → `in_progress` → `completed`
+- `status` — `pending` → `in_progress` → `done` (também: `skipped`, `blocked`)
 - `outputs` — the files the task produced
 - `notes` — free-text record (deviations, context, resolved blockers)
 
@@ -53,17 +60,16 @@ output.
 ## Deviation Tracking
 
 When completing a task differently than originally planned, record the reason in the
-task's `notes` field. Use the `notes` array to capture deviations, added context, or
-resolved blockers — for example:
+task's `notes` field. `notes` is **uma única string** (o schema declara
+`"notes": { "type": "string" }`) — para registrar mais de um desvio, separe-os com
+`;` ou `\n` dentro da mesma string. Um array é **rejeitado** pelo validador, com a
+mensagem `'notes' must be a string`.
 
 ```json
 {
   "id": "T3",
-  "status": "completed",
+  "status": "done",
   "outputs": ["Features/User/Update/Handler.cs"],
-  "notes": [
-    "deviation: split validation into a separate validator for testability",
-    "blocker-resolved: EF migration conflict fixed by regenerating the snapshot"
-  ]
+  "notes": "deviation: split validation into a separate validator for testability; blocker-resolved: EF migration conflict fixed by regenerating the snapshot"
 }
 ```

package/framework/rules/morph-workflow.md

@@ -13,9 +13,9 @@ stacks:
 
 **NEVER skip to code without a specification.** Every feature must progress through phases:
 
-1. **Proposal** — Problem statement + acceptance criteria (`0-proposal/proposal.md`)
+1. **Proposal** — Problem statement + scope + risks (`0-proposal/proposal.md`). No acceptance criteria: verifiable behaviour lives in the use cases.
 2. **Design** (optional, UI-heavy) — Design system + mockups + flows (`1-design/`)
-3. **Plan** — Technical spec + mandate + tasks (`2-plan/spec.md`, `mandate.md`, `tasks.json`)
+3. **Plan** — Use cases first, then technical spec + mandate + tasks (`2-plan/usecases/UC-{nn}-{slug}.md`, `spec.md`, `mandate.md`, `tasks.json`). Each use case post-condition must be observable in a test and reaches the task's `doneCriteria` verbatim.
 4. **Implement** — Code + recap (`3-implement/recap.md`)
 5. **Review** — Review report + Gate 3 (`4-review/review-report.md`)
 
@@ -72,6 +72,39 @@ All outputs go in `.morph/features/{feature}/`:
 
 ---
 
+## Formato obrigatório do `3-implement/recap.md`
+
+> Esta exigência é **cobrada por hook** (`validate-completion`, no Stop). Ela está aqui, na regra
+> sempre-ativa, e não só na skill `morph-implement`: descobrir o formato quando o hook dispara
+> significa reescrever o recap depois de a fase já estar dada por encerrada.
+
+**Para CADA task com `status: "done"` em `tasks.json`**, o recap precisa de um bloco próprio:
+
+1. um heading `## T{N}` (o hook casa `^## T\d+` — uma linha de tabela `| T1 | … | done |` conta
+   como menção, **não** como bloco);
+2. uma linha `**Standard:** {standard-id}` **dentro de 12 linhas** do heading. Sem standard que
+   cubra o caso, registre a decisão em `decisions.md` e cite
+   `**Standard:** ad-hoc (see decisions.md ADR-{N})`.
+
+```markdown
+## T{N} — {title}
+
+**Standard:** {standard-id} (`.morph/framework/standards/{path}.md`)
+**Persona:** {mecanismo real usado}
+**Files:**
+- `{path}`
+
+{2-3 frases sobre o que foi feito}
+
+**Issues encontrados:** {breve descrição ou "nenhum"}
+```
+
+O `validate-completion` também acusa **drift**: uma task que aparece como concluída no recap mas
+ainda está `pending`/`in_progress` no `tasks.json`. Template completo e regras de exceção em
+`morph-implement` §6.
+
+---
+
 ## Checkpoints
 
 Run a checkpoint every 3 completed tasks:
@@ -158,7 +191,7 @@ During implementation, these skills MUST be invoked at the specified triggers:
 | Trigger | Skill | When |
 |---------|-------|------|
 | Before each task | `superpowers:test-driven-development` | Invoke BEFORE writing any code for a task |
-| Before marking a task complete | `morph-verification-before-completion` | Invoke BEFORE setting a task's `status` to `completed` in `tasks.json` |
+| Before marking a task complete | `morph-verification-before-completion` | Invoke BEFORE setting a task's `status` to `done` in `tasks.json` |
 | On bug/unexpected | `superpowers:systematic-debugging` | Invoke IF a bug or unexpected behavior is encountered |
 | After all tasks | `morph-post-implementation` | Invoke AFTER all tasks completed |
 | Before PR | `morph-checklist` | Invoke BEFORE creating pull request |

package/framework/schemas/feature.schema.json

@@ -222,7 +222,8 @@
       "properties": {
         "approved": { "type": "boolean" },
         "timestamp": { "type": ["string", "null"], "description": "ISO timestamp of the approval/revocation, null while never evaluated." },
-        "approvedBy": { "type": ["string", "null"], "description": "\"auto\" (approve/advance --mode auto), \"manual\" (human in the loop), \"policy:{workType}\" (gate stamped at birth by `morph-spec create` per the work type's skippedGates — see src/core/work-types.js; the gate-guard hook only special-cases \"auto\", so policy-stamped gates stay silent to it), a --approver name, or null while never evaluated." }
+        "approvedBy": { "type": ["string", "null"], "description": "\"auto\" (approve/advance --mode auto), \"manual\" (human in the loop), \"policy:{workType}\" (gate stamped at birth by `morph-spec create` per the work type's skippedGates — see src/core/work-types.js; the gate-guard hook only special-cases \"auto\", so policy-stamped gates stay silent to it), a --approver name, or null while never evaluated." },
+        "selfAssessed": { "type": "boolean", "description": "Gate `review` SOMENTE. `true` quando o Gate 3 foi aprovado sem `4-review/evaluator-report.md`, via `morph-spec approve <f> review --self-assessed`. O score composto deveria vir do avaliador independente; esta flag registra a degradação em vez de deixá-la silenciosa, e aparece no `morph-spec list`." }
       },
       "additionalProperties": true
     }

package/framework/schemas/tasks.schema.json

@@ -25,7 +25,12 @@
           "status": { "type": "string", "enum": ["pending", "in_progress", "done", "skipped", "blocked"] },
           "outputs": { "type": "array", "items": { "type": "string" } },
           "notes": { "type": "string" },
-          "group": { "type": "string", "enum": ["backend", "frontend", "tests", "infra", "docs"] }
+          "group": { "type": "string", "enum": ["backend", "frontend", "tests", "infra", "docs"] },
+          "usecase": {
+            "type": "string",
+            "pattern": "^UC-\\d+$",
+            "description": "ID of the use case this task realizes (2-plan/usecases/UC-{nn}-{slug}.md). Optional: technical tasks with no observable behaviour have none."
+          }
         },
         "additionalProperties": false
       }

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.5.0"
+cliVersion: "8.7.0"
 ---
 
 # create-umbraco-lp

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.5.0"
+cliVersion: "8.7.0"
 ---
 
 # migrate-lp-to-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.5.0"
+cliVersion: "8.7.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.5.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-brainstorming
@@ -72,12 +72,13 @@ Para `workType: feature` (ou features sem `workType` — compat, ver MORPH.md §
    - **Problema:** o que está sendo resolvido e para quem (máx. 2 parágrafos)
    - **Escopo:** o que está incluído e o que está explicitamente excluído
    - **Usuários e fluxos críticos:** quem usa e qual é o caminho principal
-   - **Critérios de aceite:** condições verificáveis que indicam que a feature está pronta
    - **Stack:** confirme o stack padrão ou documente desvios aprovados
    - **Riscos e dependências:** o que pode dar errado, o que esta feature depende
    - **Compliance de stack:** "Em compliance" ou lista de desvios detectados e plano de resolução
 
-   **Se `workType: bug`** (modo bug-lean, ver nota no início da skill), substitua a lista acima pela estrutura enxuta: **Repro** (passos para reproduzir), **Diagnóstico** (o que foi observado/investigado), **Root cause provável**, **Escopo do fix** (o que muda, o que fica de fora) e **Critérios de aceite** (condição verificável de que o bug foi corrigido) — sem as seções de negócio completas do fluxo `feature`.
+   **Não escreva critérios de aceite aqui.** O comportamento verificável mora nos **use cases**, destilados pela `morph-plan` na fase seguinte (`2-plan/usecases/UC-{nn}-{slug}.md`), onde cada pós-condição precisa ser observável em teste e chega literal ao `doneCriteria` das tasks. O `proposal.md` responde **o quê e por quê**; os use cases respondem **como o sistema se comporta**. Duplicar aqui produz duas fontes que divergem no primeiro ajuste.
+
+   **Se `workType: bug`** (modo bug-lean, ver nota no início da skill), substitua a lista acima pela estrutura enxuta: **Repro** (passos para reproduzir), **Diagnóstico** (o que foi observado/investigado), **Root cause provável** e **Escopo do fix** (o que muda, o que fica de fora) — sem as seções de negócio completas do fluxo `feature`. A condição verificável de que o bug foi corrigido vira a **pós-condição** que faltava no use case do acervo (`.morph/specs/usecases/`), corrigida ou acrescentada na fase plan.
 
    Um bom proposal.md tem no máximo 2 páginas. Se está crescendo além disso, o escopo precisa ser cortado.
 

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.5.0"
+cliVersion: "8.7.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.5.0"
+cliVersion: "8.7.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.5.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-implement

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.5.0"
+cliVersion: "8.7.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.5.0"
+cliVersion: "8.7.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.5.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-review
@@ -74,6 +74,12 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    - **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.
 
 5. Produza `review-report.md` em `.morph/features/{feature}/4-review/` com:
+   - **`**Reviewed-SHA:** {git rev-parse HEAD}`** — o commit que você revisou, **obrigatório**.
+     Um review revisa uma ÁRVORE, e a árvore anda: sem esse carimbo, um relatório escrito antes
+     da última task fica no repo afirmando números e cobertura que já não valem. O
+     `morph-spec approve {feature} review` compara o carimbo com o HEAD e **recusa** se divergirem
+     (aconteceu de verdade: relatório de `b30ac6e` sobrevivendo à T3, que inverteu o default de
+     uma regra de negócio, e ainda dizendo `976/976` quando eram 982).
    - Scores por dimensão (arquitetura, contratos, qualidade, cobertura)
    - Score composto final
    - Lista de itens bloqueantes (se houver) — com descrição e critério de resolução

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.5.0"
+cliVersion: "8.7.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.5.0"
+cliVersion: "8.7.0"
 ---
 
 # morph-standards

package/package.json

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