@polymorphism-tech/morph-spec 8.4.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.4.0  
+**Version:** 8.6.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -140,7 +140,7 @@ These commands are available inside Claude Code after init.
 | `/morph-apply {feature}`       | Autonomous execution + review (Gate 3)                        |
 | `/morph-hotfix {feature}`      | Surgical hotfix ADW — scout → fix → human Gate 3 → ship         |
 | `/morph-status [feature]`      | Status of the active (or specified) feature                      |
-| `/morph-archive {feature}`     | Archive a completed feature (after Gate 3)                          |
+| `/morph-archive {feature}`     | Archive **without integrating** (legacy feature / cleanup); normal close is `morph-spec finish --pr\|--merge` |
 | `/morph-preflight`             | Pre-deploy validation (specs, contracts, tests, infra)                |
 | `/morph-troubleshoot [error]`  | Root-cause diagnosis for .NET/Next.js errors                            |
 
@@ -167,9 +167,12 @@ morph-spec status {feature}                    # Feature status dashboard
 morph-spec approve {feature} {gate}            # Approve a phase gate (proposal, plan, review)
 morph-spec advance {feature}                   # Approve the current gate and scaffold the next phase folder
 morph-spec approval-status {feature}           # Show approval status for all gates
-morph-spec archive {feature}                   # Archive a completed feature (after Gate 3)
+morph-spec finish {feature} --pr|--merge       # Close a feature: archive + integrate (PR or local merge) + teardown
+morph-spec archive {feature}                   # Archive WITHOUT integrating (legacy feature / cleanup)
 ```
 
+`finish` is the normal close for both flows: it archives (committing the move inside `morph/{feature}`), then integrates — `--merge` merges `--no-ff` into the default branch locally; `--pr` pushes the branch and runs `gh pr create` (needs `origin` + authenticated `gh`) — and tears down the worktree if there is one. Plain `archive` is reserved for legacy features (born before every feature had a `morph/{feature}` branch) and cleanup.
+
 Task progress within a feature is tracked with the native `TaskCreate`/`TaskUpdate` tools, persisted to `tasks.json` — there is no separate CLI command for starting or completing a task.
 
 ### Validation
@@ -196,8 +199,8 @@ morph-spec dag {feature} [--mermaid]                            # DAG dispatch d
 morph-spec create {feature} --description "<what/why>" --worktree   # Birth the feature already isolated in its own worktree
 morph-spec worktree setup {feature}      # Create .worktrees/{feature}/ on branch morph/{feature}
 morph-spec worktree link [--all]         # Relink shared infra (node_modules, .claude, .morph/framework)
-morph-spec worktree finish {feature}     # Merge --no-ff back to the primary root, clean up (requires Gate 3)
 morph-spec worktree list [--json]        # List active feature worktrees with phase/gate status
+# Close a worktree feature with `morph-spec finish {feature} --pr|--merge` (see Feature workflow) — it absorbed `worktree finish`.
 ```
 
 ---
@@ -365,4 +368,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.4.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.6.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -23,13 +23,14 @@ import { installPluginCommand } from '../src/commands/project/install-plugin-cmd
 import { updateCommand } from '../src/commands/project/update.js';
 import { doctorCommand } from '../src/commands/project/doctor.js';
 import { statusCommand } from '../src/commands/project/status.js';
-import { worktreeSetupCommand, worktreeLinkCommand, worktreeFinishCommand, worktreeListCommand } from '../src/commands/project/worktree.js';
+import { worktreeSetupCommand, worktreeLinkCommand, worktreeListCommand } from '../src/commands/project/worktree.js';
 import { fleetCommand } from '../src/commands/project/fleet.js';
 
 // === Approval gates (human-only) ===
 import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/commands/state/approve.js';
 import { advanceCommand } from '../src/commands/state/advance.js';
 import { archiveCommand } from '../src/commands/state/archive.js';
+import { finishCommand } from '../src/commands/state/finish.js';
 import { scoreCommand } from '../src/commands/state/score.js';
 import { gateDecisionCommand } from '../src/commands/state/gate-decision.js';
 import { createCommand } from '../src/commands/state/create.js';
@@ -158,11 +159,21 @@ program
 
 program
   .command('archive <feature>')
-  .description('Archive a completed feature (atomic, git-aware): move folder + update state')
+  .description('Archive a completed feature (atomic, git-aware): move folder + update state. Archive WITHOUT integrating (legacy features, cleanup) — the close path is `finish`')
   .option('--no-git', 'Skip git staging of the move')
   .option('--force', 'Archive even if Gate 3 (review) is not approved')
   .action((feature, options) => archiveCommand(feature, options));
 
+program
+  .command('finish <feature>')
+  .description('Close a feature: archive → integrate. --merge merges morph/{f} into the default (local); --pr pushes it + opens a PR. Works with and without a worktree')
+  .option('--pr', 'Push morph/{feature} and open a PR against the default branch (no local merge)')
+  .option('--merge', 'Merge morph/{feature} into the default branch locally (no push)')
+  .option('--keep', 'Keep the worktree/branch after integrating (worktree flow only)')
+  .option('--force', 'Skip the Gate-3-approved precondition')
+  .option('--discard-ignored', 'Allow removing the worktree even though it holds gitignored files that exist nowhere else (e.g. .env) — they are destroyed')
+  .action((feature, options) => finishCommand(feature, options));
+
 program
   .command('delete <feature>')
   .description('Delete a feature (hard by default; --archive marks it abandoned). Refuses if a gate is approved unless --force')
@@ -341,14 +352,6 @@ worktreeCommand
   .option('--all', 'Link all shared dirs, not just node_modules')
   .action((options) => worktreeLinkCommand(options));
 
-worktreeCommand
-  .command('finish <feature>')
-  .description('Merge the feature branch back into the primary root and clean up the worktree (requires Gate 3 approved)')
-  .option('--keep', 'Keep the worktree and branch after merging')
-  .option('--force', 'Skip the Gate-3-approved precondition')
-  .option('--discard-ignored', 'Allow removing the worktree even though it holds gitignored files that exist nowhere else (e.g. .env) — they are destroyed')
-  .action((feature, options) => worktreeFinishCommand(feature, options));
-
 worktreeCommand
   .command('list')
   .description('List active feature worktrees with their phase and gate status')

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.4.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

@@ -46,7 +46,7 @@ proposal → [uiux] → plan → implement → review
 | `/morph-hotfix {feature}` | Surgical hotfix ADW (scout → fix → human gate → ship) |
 | `/morph-apply {feature}` | Autonomous execution + review (Gate 3) |
 | `/morph-status [feature]` | Status of the active (or specified) feature |
-| `/morph-archive {feature}` | Archive a completed feature (after Gate 3) |
+| `/morph-archive {feature}` | Archive **without integrating** (legacy feature / cleanup) — normal close is `morph-spec finish --pr\|--merge` |
 | `/morph-preflight` | Pre-deploy validation (specs, contracts, tests, infra) |
 | `/morph-troubleshoot [error]` | Root-cause diagnosis for .NET/Next.js errors |
 
@@ -59,9 +59,12 @@ morph-spec approve {feature} {gate} [--mode auto] [--approver name] [--notes tex
 morph-spec advance {feature} [--design]         # approve current gate + scaffold next phase folder in one step
 morph-spec approval-status {feature} [--json]
 morph-spec unapprove {feature} {gate} [--reason text]   # recovery only
-morph-spec archive {feature} [--force] [--no-git]
+morph-spec finish {feature} --pr|--merge [--keep] [--force] [--discard-ignored]   # normal close: archive + integrate + teardown
+morph-spec archive {feature} [--force] [--no-git]        # archive WITHOUT integrating (legacy feature / cleanup)
 ```
 
+`finish` is the normal way to close a feature (both the worktree flow and the common flow): it archives (committing the move inside `morph/{feature}`), then integrates — `--merge` merges `--no-ff` into the default branch locally (no push); `--pr` pushes `morph/{feature}` + `gh pr create` (needs `origin` + authenticated `gh`). It then tears down the worktree and releases the port block. `archive` alone is reserved for legacy features (no `morph/{feature}` branch) and cleanup.
+
 ---
 
 ## CLI — feature birth & work-type routing
@@ -116,8 +119,8 @@ One feature = one git worktree = one Claude Code instance. Each worktree gets it
 morph-spec create {feature} --description "<what/why>" --worktree   # birth the feature already isolated in its own worktree
 morph-spec worktree setup {feature}        # create .worktrees/{feature}/ on branch morph/{feature}
 morph-spec worktree link [--all]           # relink shared infra (node_modules[, .claude, .morph/framework])
-morph-spec worktree finish {feature}       # merge --no-ff back to the primary root, clean up + release ports (requires Gate 3)
 morph-spec worktree list [--json]          # active feature worktrees with phase/gate status
+# Close a worktree feature with `morph-spec finish {feature} --pr|--merge` (see above) — it absorbed `worktree finish`.
 morph-spec handoff {feature} [--json]      # regenerate the compressed session-handoff doc (pointers, not copies)
 morph-spec fleet [--json]                  # every active feature (root + worktrees) with phase/gates/ports/handoff/activity
 ```
@@ -182,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.4.0 by Polymorphism Tech*
+*morph-spec v8.6.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -168,13 +168,16 @@ morph-spec create my-feature --description "what & why" --worktree   # birth the
 morph-spec worktree setup my-feature         # creates .worktrees/my-feature/ on branch morph/my-feature
 ```
 
-Open the new worktree directory in its own Claude Code instance and work normally — a SessionStart hook injects the worktree's feature identity into context automatically. When the feature is done:
+Open the new worktree directory in its own Claude Code instance and work normally — a SessionStart hook injects the worktree's feature identity into context automatically. When the feature is done (Gate 3 approved), close it in one step:
 
 ```bash
-morph-spec worktree finish my-feature        # merges --no-ff back into the primary root, then cleans up
-morph-spec archive my-feature                # run at the primary root afterward
+morph-spec finish my-feature --merge         # archive + merge --no-ff into the default branch (local), tear down the worktree
+# or, to open a PR instead of merging locally:
+morph-spec finish my-feature --pr            # archive + push morph/my-feature + gh pr create (keeps the branch the PR needs)
 ```
 
+`finish` archives the feature (committing the move inside `morph/my-feature`) *and* integrates *and* tears down the worktree in one step — it replaces the old `worktree finish` + separate `archive`. The same command closes features developed **without** a worktree (they're born on `morph/{feature}` too).
+
 List every active worktree with its phase and gate status:
 
 ```bash
@@ -246,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.4.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.
@@ -36,23 +38,24 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 | `/morph-hotfix {feature}` | ADW cirúrgico de hotfix (scout → fix → gate humano → ship) |
 | `/morph-apply {feature}` | Execução autônoma + review (Gate 3) |
 | `/morph-status [feature]` | Status da feature ativa (ou a especificada) |
-| `/morph-archive {feature}` | Arquiva feature concluída (após Gate 3) — wrapper de `morph-spec archive` (atômico, git-aware) |
+| `/morph-archive {feature}` | Arquiva-**sem-integrar** (features legadas/faxina) — wrapper de `morph-spec archive`. Fechamento normal = `morph-spec finish --pr\|--merge` |
 | `/morph-preflight` | Validação pré-deploy (specs, contratos, testes, infra) |
 | `/morph-troubleshoot [erro]` | Diagnóstico de erros .NET/Next.js com root-cause analysis |
 
 **Comandos CLI de gate e de estado** (a LLM os usa em vez de editar o estado à mão):
 - `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 a feature (atômico, git-aware); é o que `/morph-archive` chama.
-- `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 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}` — 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.
+- `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.
 - `morph-spec list [--all] [--json]` — o quadro de auditoria: uma linha por feature × workType × status × fase × gates G1/G2/G3 × descrição, com `⚠` para inconsistências (sem descrição, ordem de gate). `--all` inclui as arquivadas; `--json` para scripting. É o complemento do `delete` (enxergar o que está morto antes de remover).
 - `morph-spec delete <feature> [--archive] [--force]` — remove uma feature. Hard por padrão (pasta apagada, git-aware, + entrada podada do índice raiz para não ressuscitar); `--archive` move para `.morph/archive` com status `abandoned` em vez de apagar. Recusa se algum gate estiver aprovado, a menos que `--force`. Use para faxina de scaffolds mortos e drafts abandonados (`archive` é para trabalho concluído; `delete` é para trabalho morto).
 - `morph-spec retype <feature> <newType>` — muda o tipo de trabalho mid-flight; desfaz só os gates carimbados por política, preserva aprovações humanas; bloqueado após o Gate 3.
 - `morph-spec verify <feature> [task] [--json]` — cadeia determinística build+testes+validadores (código antes do juiz LLM); escopo de task quando informado, senão a feature inteira.
-- `morph-spec worktree setup|link|finish|list` — gerencia o ciclo do worktree por feature (`setup` cria `.worktrees/{f}/` na branch `morph/{f}`, aloca o bloco de portas e escreve `.morph/worktree.env`; `link` religa infra compartilhada; `finish` faz merge `--no-ff`, limpa e libera o bloco; `list` mostra fase/gate de cada worktree ativo).
+- `morph-spec worktree setup|link|list` — gerencia o ciclo do worktree por feature (`setup` cria `.worktrees/{f}/` na branch `morph/{f}`, aloca o bloco de portas e escreve `.morph/worktree.env`; `link` religa infra compartilhada; `list` mostra fase/gate de cada worktree ativo). O fechamento saiu daqui — use `morph-spec finish` (acima).
 - `morph-spec handoff <feature>` — regenera o documento de retomada (`.morph/features/{f}/handoff.md`): comprimido, derivado, aponta para os artefatos em vez de copiá-los. Gerado automaticamente em `setup`/`create --worktree`/`advance`.
 - `morph-spec fleet` — visão da frota: toda feature ativa (raiz + worktrees) com fase, gates pendentes, tasks, portas, handoff e atividade. Use entre sessões para decidir onde atuar.
 - `morph-spec telemetry [--json] [--feature <f>] [--limit <n>]` — reconstrói o caminho de execução da sessão a partir de `.morph/logs/events.jsonl` (skills invocadas, personas despachadas + prompts, standards/base de conhecimento lidos, mix de tools, prompts do usuário). Capturado silenciosamente pelo hook `telemetry-log` em todo tool call e todo UserPromptSubmit.
@@ -63,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) |
@@ -74,7 +77,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 Toda feature nasce com um `workType` (`morph-spec create <f> --description "<o quê/porquê>" --type <tipo>` ou classificado de `--request "<pedido>"`, que também semeia a descrição obrigatória) que dimensiona o pipeline: `feature` roda o fluxo completo (proposal → [uiux] → plan → implement → review); `bug` roda uma versão enxuta (proposal/plan lean); `chore` pula direto para implement (Gates 1/2 carimbados por política no nascimento); `hotfix` roda scout → fix cirúrgico → test loop → ship. O Gate 3 do `hotfix` **pausa sempre para um humano**, mesmo em `trust: auto` — o CLI recusa `morph-spec approve <f> review --mode auto` nesse tipo. Detalhes em `.morph/framework/MORPH.md` §2.1 e §5.
 
-Features independentes podem rodar em paralelo, cada uma isolada num git worktree (`morph-spec create <f> --description "<o quê/porquê>" --worktree` ou `morph-spec worktree setup <f>`) — uma feature por worktree, uma instância de Claude Code por worktree. Cada worktree tem seu **bloco de portas** próprio (`.morph/worktree.env` — suba dev servers SEMPRE nelas, nunca nas portas padrão) e seu **handoff.md** de retomada. `feature.json` viaja commitado na branch `morph/{f}`; ao fechar, aprove o Gate 3 dentro do worktree e rode `morph-spec worktree finish <f>` seguido de `morph-spec archive <f>` na raiz. Visão agregada: `morph-spec fleet`. Detalhes em `.morph/framework/MORPH.md` §2.2.
+Features independentes podem rodar em paralelo, cada uma isolada num git worktree (`morph-spec create <f> --description "<o quê/porquê>" --worktree` ou `morph-spec worktree setup <f>`) — uma feature por worktree, uma instância de Claude Code por worktree. Cada worktree tem seu **bloco de portas** próprio (`.morph/worktree.env` — suba dev servers SEMPRE nelas, nunca nas portas padrão) e seu **handoff.md** de retomada. `feature.json` viaja commitado na branch `morph/{f}`; ao fechar, aprove o Gate 3 e rode `morph-spec finish <f> --pr|--merge` (arquiva dentro da branch, integra e desmonta o worktree num passo só). Visão agregada: `morph-spec fleet`. Detalhes em `.morph/framework/MORPH.md` §2.2.
 
 ## Personas (em `.claude/agents/`)
 

package/framework/MORPH.md

@@ -112,6 +112,8 @@ Nem todo trabalho merece o pipeline completo. Cada feature nasce com **identidad
 
 **Compat:** uma feature sem `workType` (criada antes do v8) é tratada como `feature`. Mudança de tipo mid-flight: `morph-spec retype <f> <tipo>` (desfaz só carimbos de política, preserva aprovações humanas; bloqueado após o Gate 3).
 
+**Nascimento numa branch:** toda feature — **com ou sem `--worktree`** — nasce numa branch `morph/{f}` ramificada da default. O fluxo comum (sem worktree) desenvolve direto em `morph/{f}` na raiz; o fluxo worktree isola em `.worktrees/{f}`. Por construção o fechamento é simétrico: `morph-spec finish <f> --pr|--merge` (§2.2) fecha os dois do mesmo jeito. Features criadas **antes** deste modelo (sem branch `morph/{f}`) fecham por `morph-spec archive <f>` (arquivar-sem-integrar), não por `finish`.
+
 ### 2.2 Desenvolvimento paralelo por worktree (frota)
 
 Features independentes podem ser desenvolvidas **em paralelo, cada uma no seu git worktree**, com uma instância de Claude Code por worktree. `morph-spec create <f> --description "<o quê/porquê>" --worktree` (ou `morph-spec worktree setup <f>`) cria `.worktrees/{f}/` na branch `morph/{f}`. Contrato:
@@ -125,7 +127,7 @@ Features independentes podem ser desenvolvidas **em paralelo, cada uma no seu gi
 - **Handoff entre sessões:** `.morph/features/{f}/handoff.md` é o documento de retomada — comprimido, derivado e regenerável (`morph-spec handoff <f>`), ele **aponta** para os artefatos em vez de copiá-los. É regenerado automaticamente no `worktree setup`, `create --worktree` e `advance`; o hook de SessionStart aponta para ele. **Ao abrir uma sessão numa feature em andamento, leia o handoff antes de re-derivar contexto à mão.** Nunca o edite manualmente (é git-invisível e sobrescrito na próxima regeneração).
 - **Visão da frota:** `morph-spec fleet` agrega raiz + worktrees (fase, gates pendentes, tasks, portas, handoff, último commit, sujeira) — use entre sessões para decidir onde atuar. `morph-spec worktree list` continua sendo a visão enxuta por worktree.
 - **Ownership de arquivos:** não há lock em runtime, por design — a colisão de escrita se resolve **em plan-time** (`morph-spec dag` detecta overlap de `outputs` e recomenda `isolation: "worktree"`) e **por construção** (uma feature = um worktree = um escritor). Entre features, arquivos compartilhados convergem no merge do `finish` — conflito ali é o sinal honesto de escopo sobreposto, não um bug.
-- **Fechamento:** aprove o Gate 3 dentro do worktree, depois `morph-spec worktree finish <f>` (merge `--no-ff` da branch na raiz primária limpa; recusa se worktree ou raiz estiverem sujos; aborta em conflito; libera o bloco de portas) e por fim `morph-spec archive <f>` na raiz.
+- **Fechamento:** aprove o Gate 3, depois **`morph-spec finish <f> --pr|--merge`** — o encerramento único e simétrico (mesmo comando nos dois fluxos, worktree e comum). Ele **arquiva** a feature commitando o move `features/{f} → archive/{f}` **dentro da branch `morph/{f}`** (o estado arquivado viaja na própria integração, não num commit à parte) e então integra: `--merge` faz o merge `--no-ff` **local** na branch default (sem push; recusa se worktree/raiz estiverem sujos; aborta em conflito) e `--pr` faz `push` de `morph/{f}` + `gh pr create` (sem merge local; exige `origin` + `gh` autenticado — as pré-condições rodam **antes** de arquivar, então um `--pr` recusado não deixa meio-estado). Em ambos o worktree é desmontado (PROVE-or-DECLINE) e o bloco de portas liberado; no `--pr` a branch é **preservada** (o PR aberto precisa dela) e a sessão permanece em `morph/{f}`. Não há mais `worktree finish` nem `archive` separado no caminho feliz — `morph-spec archive` fica reservado a arquivar-sem-integrar (features legadas, faxina).
 
 ---
 
@@ -136,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.
 
@@ -156,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/commands/morph-archive.md

@@ -6,12 +6,18 @@ allowed-tools: Read, Bash
 
 # Archive MORPH Feature
 
-Archive a feature that has cleared Gate 3 (review). Use when the work is shipped and you want the
-feature out of the active set in `.morph/features/`.
+Archive-**without-integrate**: move a feature out of the active set in `.morph/features/` without
+merging or opening a PR. This is the **reserved** path — for **legacy** features (born before the
+"every feature is born on a `morph/{f}` branch" model, so there's no branch to integrate) and for
+**cleanup**. The **normal close** of a feature is `morph-spec finish {feature} --pr|--merge`, which
+archives *and* integrates *and* tears down the worktree in one step (see `MORPH.md` §2.2 and
+`morph-apply` §6). Reach for `/morph-archive` only when integration is not wanted.
 
 This is a thin wrapper over the atomic, git-aware CLI command — do **not** move folders or edit state
 by hand. The command moves the folder, stamps the feature `completed` + `archivedAt` in its
-`feature.json`, stages the move in git, and cleans the derivable root index, all-or-nothing.
+`feature.json`, **commits the move scoped to the feature's own pathspec** (`.morph/features/{f}` +
+`.morph/archive/{f}`, never `commit -a`), and cleans the derivable root index, all-or-nothing. Re-running
+is idempotent: an already-archived feature is reported, not re-moved.
 
 ## Workflow
 
@@ -28,7 +34,8 @@ by hand. The command moves the folder, stamps the feature `completed` + `archive
    ```
    The command refuses if Gate 3 isn't approved (override with `--force` only when the user asks).
    It moves `.morph/features/{feature}/` → `.morph/archive/{feature}/` (via `git mv` when possible),
-   sets `status: "completed"` + `archivedAt`, and drops the feature from the thin index.
+   sets `status: "completed"` + `archivedAt`, commits that move scoped to the feature's pathspec, and
+   drops the feature from the thin index.
 
 3. **Report** the new path (`.morph/archive/{feature}/`). Do not invent metrics not recorded in
    `feature.json` or `recap.md`.

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/feature.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "MORPH-SPEC feature.json",
-  "description": "Canonical shape of the authoritative, committed per-feature state at .morph/features/{feature}/feature.json (v5 per-feature state model). Born via `morph-spec create` (explicit) or the state-sync hook (implicit fallback). Server-side writers: `morph-spec approve/advance` (approvalGates), `morph-spec score` (taskScores), `morph-spec gate-decision` (gateDecisions), `morph-spec archive` (status/archivedAt). Never hand-edit the CLI-owned fields — manual Edits collide with the state-sync hook. This schema is documentational: additionalProperties stays true so older/newer CLIs interoperate.",
+  "description": "Canonical shape of the authoritative, committed per-feature state at .morph/features/{feature}/feature.json (v5 per-feature state model). Born via `morph-spec create` (explicit) or the state-sync hook (implicit fallback). Server-side writers: `morph-spec approve/advance` (approvalGates), `morph-spec score` (taskScores), `morph-spec gate-decision` (gateDecisions), `morph-spec archive`/`finish` (status/archivedAt — `finish` archives internally before integrating). Never hand-edit the CLI-owned fields — manual Edits collide with the state-sync hook. This schema is documentational: additionalProperties stays true so older/newer CLIs interoperate.",
   "type": "object",
   "required": ["status", "approvalGates"],
   "properties": {
@@ -200,7 +200,7 @@
     },
     "worktree": {
       "type": "object",
-      "description": "Bookkeeping do worktree ativo desta feature no ROOT feature.json, gravado por `morph-spec worktree setup` (via `create --worktree` ou standalone). Removido por `worktree finish`.",
+      "description": "Bookkeeping do worktree ativo desta feature no ROOT feature.json, gravado por `morph-spec worktree setup` (via `create --worktree` ou standalone). Removido no fechamento por `morph-spec finish` (que absorveu o antigo `worktree finish`).",
       "properties": {
         "path": { "type": "string" },
         "branch": { "type": "string" },

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.4.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.4.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.4.0"
+cliVersion: "8.6.0"
 ---
 
 # morph-apply
@@ -218,11 +218,14 @@ O comando grava `gateDecisions.review = { pause, reason, signals, trust, decided
 - Pause: `AskUserQuestion` com options `["aprovado, fechar feature", "preciso ajustar", "rollback"]`.
 - Auto: exibir summary do review-report, aprovar via `morph-spec approve {feature} review --mode auto`, e prosseguir.
 
-### 6. Pós Gate 3
+### 6. Pós Gate 3 — encerramento
 
 - Aprovar o Gate 3: em auto, `morph-spec approve {feature} review --mode auto`; em manual, o hook state-sync registra a resposta "aprovado" em AskUserQuestion. O gate fica gravado no `feature.json` autoritativo da feature — nunca via Edit à mão de `state.json`.
-- Sinalizar: "Feature {nome} concluída. Rode `/morph-archive {feature}` para arquivar."
-- Não arquivar automaticamente.
+- **Fechar a feature** com `morph-spec finish {feature} --pr|--merge` — um passo só: arquiva commitando `features/{f} → archive/{f}` dentro de `morph/{f}`, integra e desmonta o worktree (se houver). Escolha o modo com `AskUserQuestion` (header `"Integração"`):
+  - **Abrir PR** (`--pr`): faz `push` de `morph/{f}` + `gh pr create` com base na default — para review por outro humano/CI antes do merge. Exige `origin` + `gh` autenticado (checados **antes** de arquivar; se faltarem, `finish` recusa sem efeito colateral — caia para `--merge`). A branch é preservada e a sessão fica em `morph/{f}`.
+  - **Merge local** (`--merge`): merge `--no-ff` na default **localmente**, sem push — para o fluxo single-user direto. Remove a branch e o worktree.
+- Não integre automaticamente sem a escolha do modo: `finish` toca o remoto (`--pr`) ou a branch default (`--merge`) — é uma ação de saída que pede confirmação.
+- Feature **legada** (criada antes do modelo "nasce numa branch", sem `morph/{f}`): `finish` recusa e roteia para `morph-spec archive {feature}` (arquivar-sem-integrar); nesse caso, arquive.
 
 ## Anti-padrões
 
@@ -240,7 +243,7 @@ O comando grava `gateDecisions.review = { pause, reason, signals, trust, decided
 - `.morph/features/{feature}/3-implement/recap.md` produzido por morph-implement.
 - `.morph/features/{feature}/4-review/review-report.md` produzido por morph-review.
 - Gate 3 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo) — via `morph-spec approve` em auto, ou pelo hook state-sync no caminho manual.
-- Feature com Gate 3 aprovado e pronta para `morph-spec archive` (que carimba `status: "completed"` + `archivedAt`).
+- Feature com Gate 3 aprovado e **fechada** por `morph-spec finish --pr|--merge` (arquiva carimbando `status: "completed"` + `archivedAt`, integra e desmonta num passo) — ou, se legada, por `morph-spec archive`.
 
 ## Referências
 

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.4.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.4.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.4.0"
+cliVersion: "8.6.0"
 ---
 
 # morph-hotfix
@@ -103,8 +103,8 @@ options:
 ### 8. Pós-gate (o "test loop → ship" de `MORPH.md` §2.1)
 
 - Rode a suíte completa uma vez: `morph-spec verify {feature}` (sem escopo de task — cobertura da feature inteira, agora que o Gate 3 está aprovado).
-- Sinalize ao usuário: commit do fix e `morph-spec archive {feature}` (ou `morph-spec worktree finish {feature}` se a feature nasceu em worktree — ver `MORPH.md` §2.2) estão prontos.
-- Não arquive automaticamente — usuário decide quando.
+- Feche com `morph-spec finish {feature} --pr|--merge` — o mesmo encerramento único das demais features (arquiva commitando dentro de `morph/{f}`, integra, desmonta). Num hotfix urgente o `--merge` (local, direto na default) costuma ser o caminho; use `--pr` quando o fix precisa passar por CI/review antes do merge. Ver `MORPH.md` §2.2.
+- Não integre automaticamente — o usuário decide quando e por qual modo (`finish` toca a default ou o remoto). Feature legada sem `morph/{f}`: `finish` roteia para `morph-spec archive {feature}`.
 
 ## Anti-padrões
 

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