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

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.5.0",
+  "version": "8.6.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.5.0 by Polymorphism Tech*
+*morph-spec v8.6.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.5.0 by Polymorphism Tech*
+*morph-spec v8.6.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -15,7 +15,9 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 **NUNCA:**
 - Pular para código sem proposal aprovado (Gate 1) e plano aprovado (Gate 2).
-- Modificar o contrato do plano depois do Gate 2: `spec.md`, `mandate.md`, e os campos de plano de `tasks.json` (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) estão congelados.
+- Modificar o contrato do plano depois do Gate 2: `spec.md`, `mandate.md`, e os campos de plano de `tasks.json` (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) estão congelados. **Os use cases (`2-plan/usecases/UC-*.md`) NÃO estão** — são editáveis por design, é assim que se muda o comportamento e se re-roda `implement`; a auditoria fica no git.
+- Escrever critérios de aceite no `proposal.md`. O comportamento verificável mora nos use cases, cuja pós-condição precisa ser **observável em teste** e chega **literal** ao `doneCriteria` da task.
+- Editar `.morph/specs/usecases/` à mão. O acervo só se escreve pela promoção do `finish`, que lê de `2-plan/usecases/` — é ela que carimba `status: implemented` e sobrescreve por ID. Para mudar um UC existente (o caso `bug`), copie-o para o `2-plan/usecases/` da feature e corrija lá.
 - Tocar os campos de contrato do plano em `tasks.json` após o Gate 2 (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) — o hook `protect-spec-files` faz diff semântico e bloqueia mudanças neles, seja via `Write` ou `Edit`. (Os campos mutáveis `status`/`outputs`/`notes` continuam graváveis por `Write` ou `Edit` — ver SEMPRE.)
 - Listar perguntas em texto simples — sempre use a tool `AskUserQuestion` (1-4 perguntas por chamada).
 - Usar `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), ou SQL cru sem justificativa.
@@ -44,8 +46,8 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - `morph-spec approve <feature> <gate> --mode auto` — aprova um gate (`proposal`/`plan`/`review`) em `trust: auto`.
 - `morph-spec advance <feature>` — aprova o gate da fase corrente **e** cria a pasta da próxima fase num passo só (`--design` toma o ramo opcional de uiux a partir da proposta).
 - `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 finish <feature> --pr|--merge` — o **encerramento único** da feature (worktree ou comum): **arquiva** commitando `features/{f} → archive/{f}` dentro de `morph/{f}`, 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 dag <feature>` — análise do DAG de tasks.json com decisão sequencial vs paralelo **ponderada por effort** (raízes S vão inline, nunca ganham agente próprio).
+- `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 dag <feature>` — análise do DAG de tasks.json com decisão sequencial vs paralelo **ponderada por effort** (raízes S vão inline, nunca ganham agente próprio). Também cruza `tasks.json` com os use cases: `usecase` apontando para um `UC-{nn}` inexistente é **erro** (exit 1, não despacha); pós-condição órfã e `doneCriteria` que parafraseou em vez de copiar são avisos. `--mermaid` nunca é bloqueado.
 - `morph-spec score <feature> <task> <score> [--dims a,c,q,t]` — grava `taskScores` no feature.json com timestamp server-side; **nunca edite taskScores à mão**. Em PowerShell, cite o valor de `--dims` entre aspas (`--dims "9.5,9,9,9"`) — sem aspas, a lista pode chegar como tokens separados; o parser aceita ambas as formas, mas citar evita qualquer ambiguidade.
 - `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]` — grava `gateDecisions` no feature.json com timestamp server-side (shape em `framework/schemas/feature.schema.json`); **nunca edite gateDecisions à mão** — o Edit manual colide com o hook state-sync.
 - `morph-spec create <feature> --description "<o quê/porquê>" --type <feature|bug|chore|hotfix> [--request "<txt>"] [--name "<nome>"] [--worktree]` — cria a estrutura da feature + `feature.json` canônico explicitamente (nascimento explícito no início da proposal; o hook state-sync continua cobrindo o caminho implícito como fallback). **Identidade no nascimento:** `name` (default = slug) e `description` são carimbados; a `--description` é **obrigatória** numa feature nova (ou `--request`, que a semeia) — sem nenhuma das duas o `create` recusa (fim dos scaffolds anônimos). `--type` classifica direto; `--request "<pedido>"` roda o detector determinístico (empate/sem sinal sai com exit 2 e candidatos — a LLM decide e re-roda com `--type` + `--request`/`--description`); `--worktree` já nasce a feature no seu worktree próprio. **Toda feature nasce numa branch `morph/{f}`** (ramificada da default) mesmo sem `--worktree` — por isso o fechamento por `morph-spec finish` é idêntico nos dois fluxos.
@@ -64,7 +66,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 |-------|-------------|
 | `morph-brainstorming` | Entender negócio, escanear stack, produzir proposal.md |
 | `morph-stack-scan` | Detectar desvios de stack em projeto brownfield |
-| `morph-plan` | Produzir spec.md + mandate.md + tasks.json |
+| `morph-plan` | Destilar os use cases (comportamento) e então produzir spec.md + mandate.md + tasks.json |
 | `morph-implement` | Executar uma tarefa com auto-advance entre tasks |
 | `morph-eval` | Aplicar rubricas e produzir score 0-10 |
 | `morph-review` | Produzir review-report.md (Gate 3) |

package/framework/MORPH.md

@@ -138,15 +138,21 @@ Não invente caminhos alternativos.
 
 ### Proposal (`0-proposal/`)
 
-- `proposal.md` — descrição da feature, problema que resolve, escopo, critérios de aceite, riscos. Um bom proposal.md tem no máximo 2 páginas: se está crescendo além disso, o escopo provavelmente precisa ser cortado antes de avançar.
+- `proposal.md` — descrição da feature, problema que resolve, escopo, riscos. **Sem critérios de aceite:** o comportamento verificável mora nos use cases (`2-plan/usecases/`), destilados na fase plan. Duplicar aqui produz duas fontes que divergem no primeiro ajuste. Um bom proposal.md tem no máximo 2 páginas: se está crescendo além disso, o escopo provavelmente precisa ser cortado antes de avançar.
 
 ### Plan (`2-plan/`)
 
-- `spec.md` — especificação técnica detalhada: arquitetura, componentes, integrações, fluxos de dados, edge cases identificados. Um bom spec.md permite que qualquer desenvolvedor comece a implementar sem fazer perguntas básicas. Um spec.md fraco lista tecnologias mas não explica como os componentes se conectam.
+- `usecases/UC-{nn}-{slug}.md` — **um arquivo por use case**, o artefato de comportamento da feature. Frontmatter (`id`, `title`, `actor`, `status`, `entities`) mais as seções `Pré-condições`, `Cenário principal`, `Fluxos alternativos` (A1, A2… — cada alternativa aproxima uma user story), `Pós-condições` (P1, P2…) e `Delta de domínio` (**só o que muda** no modelo; o domínio completo continua sendo o código EF Core mais as migrations).
+
+  **Pós-condição precisa ser observável em teste** — esta é a regra que sustenta a camada. "O sistema fica consistente" não passa; "a resposta contém todos os veterinários não arquivados" passa. A pós-condição chega **literal** ao `doneCriteria` da task que a realiza: é a tradução manual nesse ponto que hoje perde o requisito.
+
+  O `id` é sequencial **no projeto**, não na feature — atribuído lendo o acervo `.morph/specs/usecases/` mais os use cases das features ativas, tomando o maior mais um. Ciclo de status: `draft` (nasce) → `approved` (Gate 2) → `implemented` (promoção no `finish`); é descritivo, quem trava fase é o gate. O use case fica **editável depois do Gate 2**, por design — é o que permite mudar o comportamento e re-rodar `implement`, com a auditoria no git. Obrigatoriedade por tipo de trabalho: ver `morph-plan`.
+
+- `spec.md` — especificação técnica detalhada: arquitetura, componentes, integrações, fluxos de dados, edge cases **técnicos**. Responde **como** os use cases serão realizados — não repete o comportamento. Um bom spec.md permite que qualquer desenvolvedor comece a implementar sem fazer perguntas básicas. Um spec.md fraco lista tecnologias mas não explica como os componentes se conectam.
 
 - `mandate.md` — contrato de implementação: stack exata, standards obrigatórios (com links), patterns explicitamente proibidos, checklist de done com critérios verificáveis. O mandate.md é lido no início de cada tarefa de implementação — deve ser específico o suficiente para resolver ambiguidades sem consultar o Orchestrator.
 
-- `tasks.json` — task list estruturada validada contra `framework/schemas/tasks.schema.json`. Cada task tem `id` (T1, T2...), `title`, `description`, `dependencies` (array de IDs), `effort` (S/M/L/XL), `doneCriteria`, `status` (pending/in_progress/done/skipped/blocked) e `outputs` (paths esperados). Cada entrada no recap.md deve referenciar um ID do tasks.json.
+- `tasks.json` — task list estruturada validada contra `framework/schemas/tasks.schema.json`. Cada task tem `id` (T1, T2...), `title`, `description`, `dependencies` (array de IDs), `effort` (S/M/L/XL), `doneCriteria`, `status` (pending/in_progress/done/skipped/blocked), `outputs` (paths esperados) e `usecase` (opcional — o **ID** do use case que a task realiza, `UC-07`, nunca o nome do arquivo). O `doneCriteria` de uma task com `usecase` carrega a **pós-condição literal**, com o rótulo (`"P2 — cada veterinário traz..."`). Cada entrada no recap.md deve referenciar um ID do tasks.json.
 
 - `decisions.md` — log de decisões técnicas: qual era a alternativa, por que foi descartada, quem decidiu. Criado quando surgir a primeira decisão não trivial. Não é obrigatório — só existe se houver decisões que precisam de rastreabilidade.
 
@@ -158,6 +164,18 @@ Não invente caminhos alternativos.
 
 - `review-report.md` — relatório de revisão: scores por dimensão (arquitetura, contratos, qualidade, cobertura), feedback priorizado (bloqueantes primeiro, melhorias depois), aprovação ou rejeição com critérios explícitos. Um review-report.md que só diz "aprovado" sem scores não satisfaz o gate.
 
+### Acervo de use cases (`.morph/specs/usecases/`)
+
+O acervo permanente do projeto: `UC-{nn}-{slug}.md`, **commitado** (nenhuma regra do `.gitignore` o cobre). É a descrição viva do comportamento do sistema e sobrevive ao arquivamento das features — diferente dos traces, ele **faz parte da entrega**.
+
+- **Quem escreve:** `morph-spec finish` promove os use cases da feature para cá **dentro do commit de arquivamento**, na branch `morph/{f}`, com `status: implemented`. O acervo viaja na própria integração, como o estado arquivado (§2.2) — não é um passo pós-merge.
+- **O que é cobrado mecanicamente:** `morph-spec dag {feature}` cruza `tasks.json` com os use cases — referência a um `UC-{nn}` inexistente é **erro** (não despacha), pós-condição órfã e `doneCriteria` parafraseado são avisos. Isso cobre o *encanamento*. Se a pós-condição é **observável em teste** nenhum checker decide: continua sendo critério do Gate 2 e da rubrica `test-coverage`.
+- **Via única de escrita:** a promoção lê **só** de `{feature}/2-plan/usecases/`. Nunca edite `.morph/specs/usecases/` à mão — a edição direta pula o `status: implemented`, a sobrescrita por ID e o commit escopado, e o acervo passa a ter duas verdades. Para mudar um UC existente (o caso `bug`), copie-o para o `2-plan/usecases/` da feature, corrija lá, e deixe o `finish` sobrescrever.
+- **Quando chega na default:** em `--merge`, no merge `--no-ff`; em `--pr`, só quando o PR for mergeado. Correto por construção: o acervo descreve o que foi **integrado**, não o que foi proposto.
+- **Sobrescrita por ID:** um `UC-07` que já existe é substituído pela versão que está sendo integrada, mesmo que o slug tenha mudado. Exatamente um arquivo por ID.
+- **Fail-open:** feature sem `2-plan/usecases/` promove nada, em silêncio. A promoção nunca pode impedir o fechamento de uma feature.
+- **Colisão entre features paralelas:** dois worktrees podem alocar `UC-08` sem se enxergar, porque cada `feature.json` viaja na sua branch. A colisão é **aceita e resolvida no merge**, como conflito de arquivo — coerente com o ownership de §2.2 ("conflito ali é o sinal honesto de escopo sobreposto"). Renumere o UC perdedor e atualize as referências `usecase` no `tasks.json` arquivado daquela feature. Não há alocador central, e não deve haver: um lock global de id reintroduziria entre worktrees a coordenação que a arquitetura evita de propósito.
+
 ### Traces (`.morph/traces/`)
 
 Cada fase de implementação produz um trace JSON em `.morph/traces/YYYY-MM-DD-{feature}-{phase}.json`.

package/framework/evals/rubrics/test-coverage.md

@@ -4,7 +4,9 @@ Avalia se os testes cobrem os comportamentos esperados, são isolados e têm nom
 
 ## Score 9-10 — Exemplar
 
-- Happy path coberto para todos os casos de uso relevantes.
+- **Cada pós-condição do use case referenciado tem teste correspondente.** Se a task traz `usecase: "UC-07"`, abra `2-plan/usecases/UC-07-*.md` e percorra as pós-condições (P1, P2…): cada uma precisa de ao menos um teste que a verifique. Pós-condição sem teste **impede a faixa 9-10**, por mais completa que a suíte pareça no resto.
+- Happy path coberto para todos os casos de uso relevantes — "relevantes" são os use cases referenciados pelas tasks da feature, não uma lista implícita.
+- Fluxos alternativos do use case (A1, A2…) cobertos: são os edge cases de **comportamento** e foram declarados justamente para serem testados.
 - Edge cases críticos cobertos: null/undefined, string vazia, boundary values, coleção vazia.
 - Casos de erro cobertos: o que acontece quando a operação falha, quando a dependência retorna erro.
 - Testes completamente isolados — cada teste pode rodar sozinho em qualquer ordem.
@@ -43,6 +45,7 @@ Avalia se os testes cobrem os comportamentos esperados, são isolados e têm nom
 
 ## Perguntas de avaliação
 
+0. A task referencia um `usecase`? Se sim: **toda** pós-condição daquele use case tem teste correspondente? (Sem isso, o teto é 8.)
 1. O happy path está coberto para todos os casos de uso da tarefa?
 2. Os edge cases críticos (null, vazio, boundary) estão cobertos?
 3. O que acontece quando uma dependência falha — isso está testado?

package/framework/hooks/shared/phase-utils.js

@@ -33,6 +33,7 @@ export const OUTPUT_PHASE_MAP = {
   mandate: 'plan',
   tasks: 'plan',
   decisions: 'plan',
+  usecases: 'plan',
   recap: 'implement',
   reviewReport: 'review',
   evaluatorReport: 'review',

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`)
 

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.6.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.6.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.6.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.6.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.6.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.6.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.6.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.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.5.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.5.0"
+cliVersion: "8.6.0"
 ---
 
 # morph-review

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.5.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.5.0"
+cliVersion: "8.6.0"
 ---
 
 # morph-standards

package/package.json

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

package/src/commands/state/archive.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { existsSync, renameSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { execFileSync } from 'child_process';
+import { promoteUseCases, SPECS_USECASES_PATHSPEC } from '../../lib/specs/usecase-promoter.js';
 
 /**
  * `morph-spec archive <feature>` — atomic, git-aware archive of a completed
@@ -52,7 +53,7 @@ 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 }}
+ *   committed?: boolean, staged?: boolean, archivePath?: string, promotedUseCases?: string[] }}
  */
 export function runArchive(feature, opts = {}) {
   const cwd = opts.cwd || process.cwd();
@@ -64,6 +65,14 @@ export function runArchive(feature, opts = {}) {
 
   // Idempotent short-circuit: already archived here. Checked FIRST so a re-run
   // after a partial finish reports "already done", never "not found".
+  //
+  // Consequence, deliberate: this short-circuits BEFORE the use-case promotion
+  // below, so a promotion that degraded fail-open is NOT retried by re-running
+  // `finish`. That is the price of "closing a feature never fails" — an archived
+  // feature stays archived, and the only signal is an absent `promotedUseCases`
+  // in the output. Recovering means copying the UCs into `.morph/specs/usecases/`
+  // by hand; making this retry would mean re-entering the archive path for an
+  // already-closed feature, which is a worse trade.
   if (existsSync(archivePath)) {
     return { ok: true, alreadyArchived: true, archived: false, archivePath };
   }
@@ -117,18 +126,45 @@ export function runArchive(feature, opts = {}) {
     } catch { /* non-fatal — the move is what matters */ }
   }
 
-  // 3) Commit the move — SCOPED to this feature's pathspec, NEVER `commit -a`
+  // 3) Promote the feature's use cases into the project's permanent archive
+  //    (.morph/specs/usecases/). Read from the ALREADY-MOVED folder so there is
+  //    a single source path, and land inside the SAME scoped commit below — the
+  //    archive travels with the integration, exactly like the archived state
+  //    (MORPH.md §2.2). Fail-open: any failure degrades to "promoted nothing",
+  //    never to a refused close.
+  let promotedUseCases = [];
+  try {
+    const { promoted } = promoteUseCases(cwd, archivePath);
+    promotedUseCases = promoted;
+    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
+      // tracks. The replaced-by-ID deletions are tracked, so that same commit
+      // would carry them even without this line (verified by mutating it away) —
+      // `-A` is belt-and-braces, but dropping the `git add` entirely would
+      // silently promote nothing on a first delivery.
+      try { execFileSync('git', ['add', '-A', '--', SPECS_USECASES_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
+    }
+  } catch { /* promotion must never block archiving */ }
+
+  // 4) Commit the move — SCOPED to this feature's pathspec, NEVER `commit -a`
   //    (same anti-sweep discipline as `finish`'s worktree teardown). This is what
   //    lets the archived state travel with the branch on `finish` (archive-before-merge).
+  //    The acervo pathspec joins only when something was promoted: git refuses a
+  //    pathspec that matches nothing, and that refusal would leave the tree dirty
+  //    and break the checkout/merge that follows.
   let committed = false;
   if (useGit && staged) {
+    const pathspecs = promotedUseCases.length
+      ? [featPathspec, archivePathspec, SPECS_USECASES_PATHSPEC]
+      : [featPathspec, archivePathspec];
     try {
-      execFileSync('git', ['commit', '-m', `morph-spec archive: ${feature}`, '--', featPathspec, archivePathspec], { cwd, stdio: 'pipe' });
+      execFileSync('git', ['commit', '-m', `morph-spec archive: ${feature}`, '--', ...pathspecs], { cwd, stdio: 'pipe' });
       committed = true;
     } catch { /* nothing to commit / no identity — not fatal, the move + stage stand */ }
   }
 
-  // 4) Drop the feature from the thin root index. Edit the index file directly
+  // 5) Drop the feature from the thin root index. Edit the index file directly
   //    rather than calling saveState — saveState would re-create
   //    .morph/features/{name}/feature.json and undo the archive.
   const rootPath = join(cwd, '.morph', 'state.json');
@@ -144,7 +180,7 @@ export function runArchive(feature, opts = {}) {
     } catch { /* index is derivable — non-fatal */ }
   }
 
-  return { ok: true, archived: true, committed, staged, archivePath };
+  return { ok: true, archived: true, committed, staged, archivePath, promotedUseCases };
 }
 
 /**
@@ -179,6 +215,9 @@ export async function archiveCommand(featureName, options = {}) {
 
     console.log(chalk.green(`\n📦 Archived "${featureName}" → .morph/archive/${featureName}/`));
     console.log(chalk.gray(`   status: completed, archivedAt stamped in feature.json.`));
+    if (result.promotedUseCases?.length) {
+      console.log(chalk.gray(`   ${result.promotedUseCases.length} use case(s) promoted → .morph/specs/usecases/ (status: implemented).`));
+    }
     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('');

package/src/commands/state/finish.js

@@ -187,6 +187,7 @@ export async function finishCommand(feature, options = {}) {
 
 async function integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch }) {
   const mergeMsg = `morph-spec finish: merge ${expectedBranch}`;
+  const ucNote = promotedNote(arch);
 
   if (isWorktreeFlow) {
     // The root stays on the default; shed this feature's own root-side scaffold,
@@ -214,13 +215,13 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
 
     if (options.keep) {
       dropFromRootIndex(root, feature);
-      emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false, ...backupNote });
+      emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false, ...backupNote, ...ucNote });
       process.exit(0);
     }
 
     const teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: true });
     dropFromRootIndex(root, feature);
-    emit(mergeOutput({ feature, branch: expectedBranch, worktreePath, teardown, shedBackup }));
+    emit({ ...mergeOutput({ feature, branch: expectedBranch, worktreePath, teardown, shedBackup }), ...ucNote });
     process.exit(0);
   }
 
@@ -249,13 +250,13 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
   }
   tryGit(['branch', '-d', expectedBranch], root);
   // The root index (gitignored) was already updated by the archive (same cwd).
-  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: null });
+  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: null, ...ucNote });
   process.exit(0);
 }
 
 // ── PR integration (push + gh, no local merge) ───────────────────────────────
 
-async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody }) {
+async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch }) {
   try {
     execFileSync('git', ['push', '-u', 'origin', expectedBranch], { cwd: root, stdio: 'pipe' });
   } catch (err) {
@@ -301,6 +302,7 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     pushed: expectedBranch,
     base: defaultBranch,
     pr: prUrl,
+    ...promotedNote(arch),
     ...(shedBackup ? { shedBackup } : {}),
     ...(teardown
       ? { worktreeRemoved: teardown.worktreeRemoved, ...teardownExtras(teardown, worktreePath, expectedBranch, false) }
@@ -312,6 +314,15 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
 
 // ── output helpers ────────────────────────────────────────────────────────
 
+/**
+ * Report the use cases the archive promoted into `.morph/specs/usecases/`.
+ * Absent when nothing was promoted, so a feature with no use cases keeps the
+ * exact output shape it had before this existed.
+ */
+function promotedNote(arch) {
+  return arch?.promotedUseCases?.length ? { promotedUseCases: arch.promotedUseCases } : {};
+}
+
 function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
   return {
     finished: true,

package/src/commands/tasks/dag.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 import { parseTasksJsonLenient } from '../../lib/tasks/tasks-json-parser.js';
 import { planDispatch } from '../../lib/tasks/dispatch-planner.js';
 import { renderMermaidFlowchart } from '../../lib/tasks/mermaid-renderer.js';
+import { checkUseCases } from '../../lib/specs/usecase-check.js';
 
 /**
  * `morph-spec dag <feature>` — analyze the tasks.json DAG and print the
@@ -17,7 +18,8 @@ import { renderMermaidFlowchart } from '../../lib/tasks/mermaid-renderer.js';
  */
 export async function dagCommand(featureName, options = {}) {
   try {
-    const tasksPath = join(process.cwd(), '.morph', 'features', featureName, '2-plan', 'tasks.json');
+    const planDir = join(process.cwd(), '.morph', 'features', featureName, '2-plan');
+    const tasksPath = join(planDir, 'tasks.json');
     if (!existsSync(tasksPath)) {
       console.error(chalk.red(`\n❌ tasks.json not found for feature "${featureName}"`));
       console.error(chalk.gray(`Expected at: .morph/features/${featureName}/2-plan/tasks.json\n`));
@@ -42,13 +44,34 @@ export async function dagCommand(featureName, options = {}) {
       return;
     }
 
+    // Use-case cross-check. Runs AFTER the --mermaid short-circuit on purpose:
+    // rendering the DAG is pure visualization and must never be blocked by the
+    // state of the spec. A broken `usecase` reference IS fatal here — the file
+    // either exists or it does not, so there is no false positive to weigh
+    // against a plan that points at a use case nobody can read.
+    const ucCheck = checkUseCases(data, join(planDir, 'usecases'));
+
     const plan = planDispatch(data);
 
     if (options.json) {
-      console.log(JSON.stringify(plan, null, 2));
+      console.log(JSON.stringify({ ...plan, useCases: ucCheck }, null, 2));
+      if (ucCheck.errors.length) process.exit(1);
       return;
     }
 
+    const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+    if (ucCheck.errors.length) {
+      console.error(chalk.red(`\n❌ Use cases — ${plural(ucCheck.errors.length, 'erro', 'erros')}\n`));
+      for (const e of ucCheck.errors) console.error(chalk.red(`  ${e}`));
+      console.error(chalk.gray('\n  Corrija a referência no tasks.json ou restaure o use case.\n'));
+      process.exit(1);
+    }
+    if (ucCheck.warnings.length) {
+      console.error(chalk.yellow(`\n⚠ Use cases — ${plural(ucCheck.warnings.length, 'aviso', 'avisos')}`));
+      for (const w of ucCheck.warnings) console.error(chalk.yellow(`  ${w}`));
+    }
+
     console.log(chalk.bold(`\n📊 DAG — ${featureName}`));
     console.log('━'.repeat(60));
 

package/src/commands/validation/validate-feature.js

@@ -36,17 +36,24 @@ import { validateTasksJson } from '../../lib/tasks/tasks-json-parser.js';
  */
 const OUTPUT_SECTIONS = {
   // morph-brainstorming emits: Problema, Escopo, Usuários e fluxos críticos,
-  // Critérios de aceite, Stack, Riscos e dependências, Compliance de stack.
+  // Stack, Riscos e dependências, Compliance de stack.
+  //
+  // "Critérios de aceite" is now OPTIONAL, not required: the behaviour layer
+  // moved to the use cases (2-plan/usecases/), whose post-conditions must be
+  // observable in a test, and morph-brainstorming no longer emits the section.
+  // `optional` — not `recommended` — precisely because the skill never emits it
+  // anymore: a warning on every new proposal would be systematic noise. Legacy
+  // proposals that DO carry the section keep validating exactly as before.
   'proposal.md': {
     required: [
       ['Problema', 'Problem'],
       ['Escopo', 'Scope'],
-      ['Critérios de aceite', 'Critério', 'Aceite', 'Acceptance Criteria', 'Acceptance', 'Success Criteria', 'Success Metrics'],
     ],
     recommended: [
       ['Riscos', 'Risks'],
     ],
     optional: [
+      ['Critérios de aceite', 'Critério', 'Aceite', 'Acceptance Criteria', 'Acceptance', 'Success Criteria', 'Success Metrics'],
       'Stack',
       ['Usuários', 'Usuarios', 'Users', 'User Journey', 'User Stories', 'Fluxos'],
       ['Dependências', 'Dependencias', 'Dependencies'],

package/src/core/paths/output-schema.js

@@ -15,7 +15,7 @@ import { join } from 'path';
  * Schema for output types produced by morph-spec NLH phases.
  *
  * Fields:
- *   filename     - The file's basename (e.g. 'spec.md')
+ *   filename     - The file's basename (e.g. 'spec.md'). Single-file types only.
  *   phaseDir     - Subdirectory within .morph/features/{feature}/
  *   phase        - The morph-spec phase that produces this output
  *   protected    - Whether the file requires an approval gate before editing
@@ -25,6 +25,13 @@ import { join } from 'path';
  *                  Lets the implement phase update task progress without
  *                  unfreezing the plan contract. When present, the protect
  *                  hook does a semantic diff instead of a blanket block.
+ *
+ * Multi-file types (`multi: true`) hold N files in a directory instead of one
+ * fixed basename. They carry `dirname` + `filenamePattern` + `displayFilename`
+ * INSTEAD of `filename`, and every derivation keyed by basename
+ * (FILENAME_TO_OUTPUT, PROTECTED_SPEC_FILES, MUTABLE_SPEC_FIELDS) skips them —
+ * there is no single basename to key on. `getOutputPath` returns the DIRECTORY
+ * for these types.
  */
 export const OUTPUT_SCHEMA = {
   // 0-proposal/
@@ -43,6 +50,19 @@ export const OUTPUT_SCHEMA = {
   mandate:        { filename: 'mandate.md',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan', mutableFields: ['status', 'outputs', 'notes'] },
   decisions:      { filename: 'decisions.md',          phaseDir: '2-plan',      phase: 'plan',      protected: false },
+  // N files, one per system use case — the behaviour layer the plan distils
+  // BEFORE spec.md/tasks.json. Deliberately NOT protected: editing a use case
+  // after Gate 2 is the supported way to change behaviour and re-run implement;
+  // the audit trail lives in git.
+  usecases:       {
+    dirname: 'usecases',
+    filenamePattern: '^UC-\\d+-[a-z0-9-]+\\.md$',
+    displayFilename: 'UC-{nn}-{slug}.md',
+    phaseDir: '2-plan',
+    phase: 'plan',
+    protected: false,
+    multi: true,
+  },
 
   // 3-implement/
   recap:          { filename: 'recap.md',              phaseDir: '3-implement', phase: 'implement', protected: false },
@@ -60,9 +80,21 @@ export const OUTPUT_SCHEMA = {
 // Builder Functions (Windows-safe via path.join)
 // ============================================================================
 
+/**
+ * Leaf segment of a schema entry: the basename for single-file types, the
+ * directory name for multi-file ones. Keeps every path builder from having to
+ * know about `multi` on its own.
+ */
+function leafSegment(entry) {
+  return entry.multi ? entry.dirname : entry.filename;
+}
+
 /**
  * Get the morph-relative path for a specific output type of a feature.
  *
+ * For `multi` types this is the DIRECTORY holding the N files
+ * (".morph/features/my-feature/2-plan/usecases"), not a single file.
+ *
  * @param {string} featureName
  * @param {string} outputType  - camelCase output type key from OUTPUT_SCHEMA
  * @returns {string} e.g. ".morph/features/my-feature/2-plan/spec.md"
@@ -72,19 +104,38 @@ export function getOutputPath(featureName, outputType) {
   if (!entry) {
     throw new Error(`Unknown output type: "${outputType}". Valid types: ${Object.keys(OUTPUT_SCHEMA).join(', ')}`);
   }
-  return join('.morph', 'features', featureName, entry.phaseDir, entry.filename)
+  return join('.morph', 'features', featureName, entry.phaseDir, leafSegment(entry))
     .replace(/\\/g, '/');
 }
 
 /**
  * Get the absolute filesystem path for a specific output type.
+ * For `multi` types this is the directory — see {@link getOutputPath}.
  */
 export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
   const entry = OUTPUT_SCHEMA[outputType];
   if (!entry) {
     throw new Error(`Unknown output type: "${outputType}". Valid types: ${Object.keys(OUTPUT_SCHEMA).join(', ')}`);
   }
-  return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, entry.filename);
+  return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, leafSegment(entry));
+}
+
+/**
+ * Human-readable path of a schema entry, relative to the feature directory.
+ *
+ * SINGLE source for the `morph-outputs` tables: `scripts/generate-refs.js`
+ * writes them and `test/framework/refs.test.js` verifies them, and if the two
+ * rebuilt the string independently they would drift apart the first time the
+ * schema grew a new shape. Multi-file types render the filename PATTERN, so a
+ * reader sees it's a folder of N files.
+ *
+ * @param {Object} entry - an OUTPUT_SCHEMA value
+ * @returns {string} e.g. "2-plan/spec.md" or "2-plan/usecases/UC-{nn}-{slug}.md"
+ */
+export function getSchemaDisplayPath(entry) {
+  return entry.multi
+    ? `${entry.phaseDir}/${entry.dirname}/${entry.displayFilename}`
+    : `${entry.phaseDir}/${entry.filename}`;
 }
 
 /**
@@ -119,6 +170,9 @@ export function getAbsoluteTaskReportPath(projectRoot, featureName, taskId) {
 
 /**
  * Get all output paths for a feature, ready for state.json `outputs` block.
+ *
+ * Multi-file types contribute their DIRECTORY, so `created` for them means
+ * "the folder exists" — the state index tracks presence, not file count.
  */
 export function getAllOutputPaths(featureName) {
   const outputs = {};
@@ -135,8 +189,14 @@ export function getAllOutputPaths(featureName) {
 // Derived Constants
 // ============================================================================
 
+/**
+ * filename → output type. Multi-file types are absent by construction: they
+ * have N basenames, so there is nothing to key on.
+ */
 export const FILENAME_TO_OUTPUT = Object.fromEntries(
-  Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [entry.filename, key])
+  Object.entries(OUTPUT_SCHEMA)
+    .filter(([, entry]) => !entry.multi)
+    .map(([key, entry]) => [entry.filename, key])
 );
 
 export const OUTPUT_PHASE_MAP = Object.fromEntries(
@@ -148,7 +208,7 @@ export const OUTPUT_PHASE_MAP = Object.fromEntries(
  */
 export const PROTECTED_SPEC_FILES = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA)
-    .filter(([, entry]) => entry.protected && entry.approvalGate)
+    .filter(([, entry]) => entry.protected && entry.approvalGate && !entry.multi)
     .map(([, entry]) => [entry.filename, entry.approvalGate])
 );
 
@@ -160,7 +220,7 @@ export const PROTECTED_SPEC_FILES = Object.fromEntries(
  */
 export const MUTABLE_SPEC_FIELDS = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA)
-    .filter(([, entry]) => entry.protected && entry.approvalGate && entry.mutableFields)
+    .filter(([, entry]) => entry.protected && entry.approvalGate && entry.mutableFields && !entry.multi)
     .map(([, entry]) => [entry.filename, entry.mutableFields])
 );
 

package/src/lib/agents/output-collector.js

@@ -42,6 +42,11 @@ export function collectPhaseOutputs(projectRoot, featureName) {
   const results = [];
 
   for (const [key, entry] of Object.entries(OUTPUT_SCHEMA)) {
+    // Multi-file types resolve to a DIRECTORY — there is no single document to
+    // weigh as one source. Skipped explicitly rather than left to fail as an
+    // EISDIR swallowed by the catch below.
+    if (entry.multi) continue;
+
     const absPath = getAbsoluteOutputPath(projectRoot, featureName, key);
     if (!existsSync(absPath)) continue;
 

package/src/lib/generators/handoff-generator.js

@@ -29,9 +29,11 @@ const PHASE_DIRS = {
   review: '4-review',
 };
 
-/** Ordered pointer candidates — only existing files make it into the doc. */
+/** Ordered pointer candidates — only existing paths make it into the doc. */
 const POINTER_CANDIDATES = [
-  ['0-proposal/proposal.md', 'proposta e critérios de aceite'],
+  ['0-proposal/proposal.md', 'proposta: problema, escopo e riscos'],
+  // Behaviour before solution — the same order morph-plan writes them in.
+  ['2-plan/usecases', 'use cases: comportamento e pós-condições testáveis (pasta)'],
   ['2-plan/spec.md', 'especificação técnica'],
   ['2-plan/mandate.md', 'contrato de implementação (leia antes de cada task)'],
   ['2-plan/tasks.json', 'DAG de tasks (status vivo)'],

package/src/lib/specs/usecase-check.js

@@ -0,0 +1,173 @@
+/**
+ * Cross-check between a feature's use cases and its `tasks.json`.
+ *
+ * This is the mechanical half of the use-case layer. Whether a post-condition is
+ * *observable in a test* is semantic and stays with Gate 2 and the evaluator —
+ * no checker can decide it. What IS decidable is the plumbing, and the plumbing
+ * is where the requirement actually leaked before:
+ *
+ *   - a task pointing at a use case that does not exist  → ERROR (a broken plan)
+ *   - a post-condition no task ever mentions            → warning (orphan)
+ *   - a task on a use case whose `doneCriteria` carries → warning (paraphrased
+ *     none of its post-conditions verbatim                instead of copied)
+ *
+ * Two deliberate asymmetries:
+ *
+ *   **Coverage is computed from the post-condition's side, never the task's.**
+ *   `usecase` is optional by design — a technical task with no observable
+ *   behaviour has none — so "task without a use case" is never a finding.
+ *
+ *   **Matching normalizes case and whitespace.** The rule is "copy the text
+ *   verbatim", but a plan that prefixes the label (`"P2 — cada veterinário…"`)
+ *   naturally lowercases the first letter. A raw `includes()` would reject the
+ *   very example the `morph-plan` skill teaches. Accents and wording still have
+ *   to match: that is the part worth being strict about.
+ *
+ * Fail-open like the promoter: no `usecases/` folder means nothing to check.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { useCaseId } from './usecase-promoter.js';
+
+/**
+ * A post-condition line: `- **P2** — Cada veterinário traz suas especialidades`.
+ * The separator is tolerant (em dash, en dash or hyphen) because the character
+ * is a typing accident, not a decision.
+ */
+const POSTCONDITION_RE = /^[ \t]*[-*][ \t]*\*\*(P\d+)\*\*[ \t]*[—–-][ \t]*(.+?)[ \t]*$/gm;
+
+/** Case-folded, whitespace-collapsed form used for containment tests. */
+function normalize(text) {
+  return String(text).toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Parse one use-case document into its post-conditions.
+ *
+ * @param {string} content
+ * @returns {Array<{ label: string, text: string }>}
+ */
+export function parsePostConditions(content) {
+  const out = [];
+  const seen = new Set();
+  for (const m of String(content).matchAll(POSTCONDITION_RE)) {
+    const [, label, text] = m;
+    if (seen.has(label)) continue; // first wins — a repeated label is one post-condition
+    seen.add(label);
+    out.push({ label, text: text.trim() });
+  }
+  return out;
+}
+
+/**
+ * Read every use case of a feature, keyed by ID.
+ *
+ * @param {string} usecasesDir - absolute path to `2-plan/usecases`
+ * @returns {Map<string, { id: string, file: string, postConditions: Array<{label: string, text: string}> }>}
+ */
+export function loadUseCases(usecasesDir) {
+  const byId = new Map();
+  if (!existsSync(usecasesDir)) return byId;
+
+  let names;
+  try {
+    names = readdirSync(usecasesDir).sort();
+  } catch {
+    return byId; // unreadable folder is "no use cases", never a crash
+  }
+
+  for (const file of names) {
+    const id = useCaseId(file);
+    if (!id || !file.endsWith('.md')) continue;
+    try {
+      const content = readFileSync(join(usecasesDir, file), 'utf8');
+      byId.set(id, { id, file, postConditions: parsePostConditions(content) });
+    } catch { /* one unreadable use case must not sink the rest */ }
+  }
+  return byId;
+}
+
+/**
+ * Cross-check `tasks.json` against the feature's use cases.
+ *
+ * @param {Object} tasksData - parsed tasks.json (already schema-valid)
+ * @param {string} usecasesDir - absolute path to `2-plan/usecases`
+ * @returns {{ errors: string[], warnings: string[], checked: boolean }}
+ *   `checked: false` means there were no use cases to check against.
+ */
+export function checkUseCases(tasksData, usecasesDir) {
+  const errors = [];
+  const warnings = [];
+  const byId = loadUseCases(usecasesDir);
+  const tasks = Array.isArray(tasksData?.tasks) ? tasksData.tasks : [];
+
+  // A task referencing a use case that does not exist is a broken plan, and the
+  // check is exact: the file is there or it is not. This is the only finding
+  // that earns an error — everything below is advisory by construction.
+  for (const task of tasks) {
+    if (!task?.usecase) continue;
+    if (!byId.has(task.usecase)) {
+      const known = [...byId.keys()].sort().join(', ') || 'nenhum';
+      errors.push(
+        `${task.id}.usecase → ${task.usecase} não existe em 2-plan/usecases/ (encontrados: ${known})`
+      );
+    }
+  }
+
+  if (byId.size === 0) return { errors, warnings, checked: false };
+
+  // Pre-normalize every doneCriteria once: this is O(tasks × postConditions)
+  // and both are small, but the normalization itself is not free.
+  const criteria = tasks.map((t) => ({ id: t?.id, text: normalize(t?.doneCriteria || ''), usecase: t?.usecase }));
+
+  // Orphan post-conditions — computed from the post-condition's side, so a task
+  // without a `usecase` never counts against anyone.
+  //
+  // A use case NOBODY touches collapses into a single aggregated warning. The
+  // per-post-condition list is the useful shape while a plan is being closed
+  // (three of four covered → fix the fourth), but `dag` also runs on every
+  // implement cycle, where an untouched use case would repeat N identical lines
+  // forever. Losing the finding entirely would be worse: a use case written and
+  // then ignored by the whole plan is the failure this layer exists to catch.
+  for (const uc of byId.values()) {
+    const withText = uc.postConditions.filter((pc) => normalize(pc.text));
+    if (withText.length === 0) continue;
+
+    const orphans = withText.filter((pc) => !criteria.some((c) => c.text.includes(normalize(pc.text))));
+    if (orphans.length === 0) continue;
+
+    const untouched = orphans.length === withText.length && !criteria.some((c) => c.usecase === uc.id);
+    if (untouched) {
+      warnings.push(
+        `${uc.id} não é referenciado por nenhuma task — ${withText.length} pós-condição(ões) sem cobertura ` +
+        `(${withText.map((p) => p.label).join('/')})`
+      );
+      continue;
+    }
+    for (const pc of orphans) {
+      warnings.push(
+        `${uc.id} ${pc.label} não é coberta por nenhuma task — nenhum doneCriteria carrega "${pc.text}"`
+      );
+    }
+  }
+
+  // Tasks that claim a use case but paraphrased it instead of copying it.
+  for (const c of criteria) {
+    if (!c.usecase) continue;
+    const uc = byId.get(c.usecase);
+    if (!uc || uc.postConditions.length === 0) continue;
+    const carries = uc.postConditions.some((pc) => {
+      const needle = normalize(pc.text);
+      return needle && c.text.includes(needle);
+    });
+    if (!carries) {
+      warnings.push(
+        `${c.id}.doneCriteria não carrega nenhuma pós-condição de ${c.usecase} literalmente ` +
+        `(esperado o texto de ${uc.postConditions.map((p) => p.label).join('/')})`
+      );
+    }
+  }
+
+  return { errors, warnings, checked: true };
+}

package/src/lib/specs/usecase-promoter.js

@@ -0,0 +1,120 @@
+/**
+ * Promotion of a feature's use cases into the project's permanent archive.
+ *
+ * A use case is born inside a feature (`2-plan/usecases/UC-{nn}-{slug}.md`) and
+ * is promoted, at archive time, into `.morph/specs/usecases/` — the living
+ * description of the system's behaviour, which outlives the feature that
+ * introduced it. The archive is COMMITTED (no gitignore rule covers it).
+ *
+ * Contract, in the order it matters:
+ *   - **Fail-open.** Every failure degrades to "nothing promoted". Promotion may
+ *     never block the close of a feature — that is why the caller treats a throw
+ *     as a no-op rather than an error.
+ *   - **No-op without the folder.** A feature with no use cases promotes nothing.
+ *   - **Idempotent.** Re-promoting the same use case rewrites the same content.
+ *   - **Overwrite by ID, not by filename.** `UC-07-old-slug.md` in the archive is
+ *     REPLACED by an incoming `UC-07-new-slug.md`. Keying on the filename would
+ *     leave two files claiming UC-07 the first time a slug is reworded — and the
+ *     `bug` work type exists precisely to correct an existing use case.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+
+const UC = OUTPUT_SCHEMA.usecases;
+const UC_FILENAME_RE = new RegExp(UC.filenamePattern);
+
+/** Project-relative path of the permanent use-case archive (git pathspec-ready). */
+export const SPECS_USECASES_PATHSPEC = join('.morph', 'specs', 'usecases');
+
+/** `UC-07-listar-veterinarios.md` → `UC-07`. Null when the name isn't a use case. */
+export function useCaseId(filename) {
+  const m = /^(UC-\d+)-/.exec(filename);
+  return m ? m[1] : null;
+}
+
+/**
+ * Rewrite the frontmatter `status:` to `implemented`.
+ *
+ * A file with no frontmatter is copied verbatim: the use case belongs to the
+ * author, and inventing a header would be a silent edit of their document.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function stampImplemented(content) {
+  const m = /^(?---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(content);
+  if (!m || m.index !== 0) return content;
+
+  const [full, open, body, close] = m;
+  const eol = full.includes('\r\n') ? '\r\n' : '\n';
+  const statusLine = /^status:[ \t]*.*$/m;
+  const next = statusLine.test(body)
+    ? body.replace(statusLine, 'status: implemented')
+    : `${body}${eol}status: implemented`;
+
+  return open + next + close + content.slice(full.length);
+}
+
+/**
+ * Copy every use case of a feature into the project's permanent archive.
+ *
+ * @param {string} cwd        - project root that owns `.morph/specs/`
+ * @param {string} featureDir - the feature folder holding `2-plan/usecases/`
+ * @returns {{ promoted: string[], replaced: string[] }} filenames, always arrays
+ */
+export function promoteUseCases(cwd, featureDir) {
+  const empty = { promoted: [], replaced: [] };
+  const srcDir = join(featureDir, UC.phaseDir, UC.dirname);
+
+  let names;
+  try {
+    if (!existsSync(srcDir)) return empty;
+    names = readdirSync(srcDir).filter((n) => UC_FILENAME_RE.test(n)).sort();
+  } catch {
+    return empty;
+  }
+  if (!names.length) return empty;
+
+  const destDir = join(cwd, '.morph', 'specs', 'usecases');
+  const promoted = [];
+  const replaced = [];
+
+  try {
+    mkdirSync(destDir, { recursive: true });
+  } catch {
+    return empty;
+  }
+
+  // Existing archive entries, indexed by use-case ID — the key the overwrite
+  // rule is written against.
+  const existingById = new Map();
+  try {
+    for (const name of readdirSync(destDir)) {
+      const id = UC_FILENAME_RE.test(name) ? useCaseId(name) : null;
+      if (id) existingById.set(id, name);
+    }
+  } catch { /* unreadable archive — treat as empty, never fatal */ }
+
+  for (const name of names) {
+    try {
+      const content = stampImplemented(readFileSync(join(srcDir, name), 'utf8'));
+      const id = useCaseId(name);
+      const stale = id ? existingById.get(id) : null;
+
+      // Same ID under a different filename: drop the old file, or the archive
+      // would end up with two documents claiming the same UC number.
+      if (stale && stale !== name) {
+        rmSync(join(destDir, stale), { force: true });
+        replaced.push(stale);
+      }
+
+      writeFileSync(join(destDir, name), content, 'utf8');
+      promoted.push(name);
+      if (id) existingById.set(id, name);
+    } catch { /* one unreadable use case must not sink the rest */ }
+  }
+
+  return { promoted, replaced };
+}

package/src/lib/tasks/tasks-json-parser.js

@@ -26,6 +26,8 @@ export function getSchema() {
 const VALID_STATUS = ['pending', 'in_progress', 'done', 'skipped', 'blocked'];
 const VALID_EFFORT = ['S', 'M', 'L', 'XL'];
 const VALID_GROUP = ['backend', 'frontend', 'tests', 'infra', 'docs'];
+/** Use-case reference: the ID only (`UC-07`), never the filename. */
+const USECASE_RE = /^UC-\d+$/;
 
 /**
  * Validate a tasks.json structure.
@@ -79,6 +81,12 @@ export function validateTasksJson(data) {
     if (task.group !== undefined && !VALID_GROUP.includes(task.group)) {
       errors.push(`${ctx}.group must be one of ${VALID_GROUP.join(', ')}`);
     }
+    // Optional: a task with no observable behaviour references no use case.
+    // When present it must be the bare ID — `morph-spec dag` is the gate that
+    // catches "UC-07-listar.md" or "UC7" before the plan reaches Gate 2.
+    if (task.usecase !== undefined && (typeof task.usecase !== 'string' || !USECASE_RE.test(task.usecase))) {
+      errors.push(`${ctx}.usecase must match /^UC-\\d+$/ (the ID alone, e.g. "UC-07")`);
+    }
   }
 
   return { valid: errors.length === 0, errors };