@polymorphism-tech/morph-spec 8.5.0 → 8.7.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.7.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -125,7 +125,7 @@ morph-spec approval-status {feature}
 
 Not every change deserves the full pipeline. Every feature is born with a **work type** — `feature`, `bug`, `chore`, or `hotfix` — set via `morph-spec create {feature} --type <type>` or classified from free text with `--request "<text>"`. The type dimensions the pipeline: `feature` runs the full proposal → [uiux] → plan → implement → review sequence; `bug` runs a lean proposal/plan; `chore` skips straight to implement (Gates 1/2 stamped by policy at birth); `hotfix` runs scout (read-only root-cause) → surgical fix → test loop, and its Gate 3 always pauses for a human even under `trust: auto`. Change the type mid-flight with `morph-spec retype {feature} {newType}` (undoes only policy-stamped gates, preserves human approvals, blocked after Gate 3).
 
-Independent features can also be developed **in parallel, each isolated in its own git worktree** — one feature, one worktree, one Claude Code instance. `morph-spec create {feature} --worktree` (or `morph-spec worktree setup {feature}`) creates `.worktrees/{feature}/` on branch `morph/{feature}`. The authoritative `feature.json` travels committed on the branch; shared infra (`node_modules`, `.claude`, `.morph/framework`) is linked via junctions (`morph-spec worktree link --all` repairs it if missing). Close out with `morph-spec worktree finish {feature}` (merges `--no-ff` back into the clean primary root) followed by `morph-spec archive {feature}` at the root; `morph-spec worktree list` shows every active worktree with its phase and gate status.
+Independent features can also be developed **in parallel, each isolated in its own git worktree** — one feature, one worktree, one Claude Code instance. `morph-spec create {feature} --worktree` (or `morph-spec worktree setup {feature}`) creates `worktrees/{feature}/` on branch `morph/{feature}`. The authoritative `feature.json` travels committed on the branch; shared infra (`node_modules`, `.claude`, `.morph/framework`) is linked via junctions (`morph-spec worktree link --all` repairs it if missing). Close out with `morph-spec worktree finish {feature}` (merges `--no-ff` back into the clean primary root) followed by `morph-spec archive {feature}` at the root; `morph-spec worktree list` shows every active worktree with its phase and gate status.
 
 ---
 
@@ -197,7 +197,7 @@ morph-spec dag {feature} [--mermaid]                            # DAG dispatch d
 
 ```bash
 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 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 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`.
@@ -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.7.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -25,6 +25,8 @@ import { doctorCommand } from '../src/commands/project/doctor.js';
 import { statusCommand } from '../src/commands/project/status.js';
 import { worktreeSetupCommand, worktreeLinkCommand, worktreeListCommand } from '../src/commands/project/worktree.js';
 import { fleetCommand } from '../src/commands/project/fleet.js';
+import { claimCommand } from '../src/commands/project/claim.js';
+import { reportCheckCommand } from '../src/commands/state/report-check.js';
 
 // === Approval gates (human-only) ===
 import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/commands/state/approve.js';
@@ -118,6 +120,9 @@ program
   .description('Check MORPH installation health')
   .option('--full', 'Run full health check')
   .option('--mcp', 'Check MCP server configuration')
+  .option('--worktrees', "Reconcile git's worktree registry × the directories on disk × known features")
+  .option('--prune', 'With --worktrees: drop git records for worktree directories that are already gone')
+  .option('--json', 'With --worktrees: output as JSON')
   .option('--reset', 'Remove morph-managed entries from .claude/settings.local.json')
   .action(doctorCommand);
 
@@ -145,6 +150,7 @@ program
   .option('--mode <mode>', 'Approval mode: "user" or "auto" (default: detected from TTY)')
   .option('--notes <notes>', 'Approval notes')
   .option('--force', 'Approve out of order (bypass the gate-monotonicity check)')
+  .option('--self-assessed', 'Gate 3 only: approve without 4-review/evaluator-report.md, recording the degradation in feature.json')
   .action((feature, gate, options) => approveCommand(feature, gate, options));
 
 program
@@ -341,7 +347,7 @@ const worktreeCommand = program
 
 worktreeCommand
   .command('setup <feature>')
-  .description('Create a worktree at .worktrees/{feature}/ on branch morph/{feature}')
+  .description('Create a worktree at worktrees/{feature}/ on branch morph/{feature}')
   .option('--fresh', 'Create a new dated branch even if one already exists')
   .action((feature, options) => worktreeSetupCommand(feature, options));
 
@@ -365,6 +371,22 @@ program
   .option('--json', 'Output as JSON')
   .action((options) => fleetCommand(options));
 
+// ─── Claims (advisory feature ownership) ──────────────────────────────────
+program
+  .command('claim [feature]')
+  .description('Show which session holds each feature (claims are advisory warnings, never locks). --release frees an orphan claim left by a dead session')
+  .option('--release', 'Release the claim on <feature> (recovery: the owning session died)')
+  .option('--list', 'List every claim on record (the default)')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => claimCommand(feature, options));
+
+// ─── Sub-agent report protocol ────────────────────────────────────────────
+program
+  .command('report-check <feature> [task]')
+  .description('Audit sub-agent report files against the work that actually landed. Answers "did the WORK land even though the REPORT did not" — exits 0 only when everything is intact')
+  .option('--json', 'Output as JSON')
+  .action((feature, task, options) => reportCheckCommand(feature, task, options));
+
 // ─── Dashboard ────────────────────────────────────────────────────────────
 program
   .command('dashboard')

package/claude-plugin.json

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

@@ -117,7 +117,7 @@ One feature = one git worktree = one Claude Code instance. Each worktree gets it
 
 ```bash
 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 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 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`.
@@ -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.7.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -165,7 +165,7 @@ Independent features can be developed in parallel, each isolated in its own git
 ```bash
 morph-spec create my-feature --description "what & why" --worktree   # birth the feature already isolated
 # or, for an existing feature:
-morph-spec worktree setup my-feature         # creates .worktrees/my-feature/ on branch morph/my-feature
+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 (Gate 3 approved), close it in one step:
@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.5.0 by Polymorphism Tech*
+*morph-spec v8.7.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.
@@ -41,11 +43,11 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 | `/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 approve <feature> <gate> --mode auto` — aprova um gate (`proposal`/`plan`/`review`) em `trust: auto`. **O Gate 3 exige `4-review/evaluator-report.md`**: sem o relatório do avaliador independente o comando recusa (exit 1). Se o dispatch do avaliador for impossível nesta sessão, aprove com `--self-assessed` — a degradação é gravada em `approvalGates.review.selfAssessed` e aparece marcada no `morph-spec list`. `--force` **não** dispensa esta regra (é só para ordem de gate).
 - `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.
@@ -53,9 +55,12 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - `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|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 doctor --worktrees [--prune] [--json]` — reconcilia o registro do git × as pastas em disco × as features conhecidas. Worktrees órfãos acumulavam **invisíveis**: o `fleet` só reporta worktrees em branch `morph/*`, então um worktree em outra branch (resíduo de finish anterior) não aparecia em lugar nenhum. `--prune` roda o único reparo seguro (`git worktree prune` — registros de pastas que já sumiram); apagar pasta que ainda existe é reportado com o comando exato, nunca executado.
+- `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 fleet` — visão da frota: toda feature ativa (raiz + worktrees) com fase, gates pendentes, tasks, **remoto** (`local`/`pushed`/`PR #N`), **claim** (que sessão está na feature), portas, handoff e atividade. Use entre sessões para decidir onde atuar.
+- `morph-spec report-check <feature> [task] [--json]` — audita os relatórios de sub-agent contra o trabalho que realmente entrou. **Relatório ausente NÃO quer dizer que o agente falhou** — ele pode ter feito tudo e perdido o meio de gravar. O comando responde a pergunta certa (`work-landed-report-missing` → aceite degradado, NÃO re-despache; `no-work-no-report` → re-despache uma vez). Protocolo completo em MORPH.md §6.
+- `morph-spec claim [feature] [--release] [--json]` — posse **advisory** de feature. Cada sessão reclama sua feature ativa automaticamente (hook SessionStart) e renova o heartbeat a cada tool call; o registro vive em `<git-common-dir>/morph-spec/claims.json`, compartilhado por todos os worktrees. **Claims avisam, nunca bloqueiam** — mas se o SessionStart avisar que outra sessão tem claim vivo, **confirme antes de `finish`/`archive`/`delete`**: duas sessões na mesma feature já custaram um recap.md inteiro e um sub-agent (o worktree sumiu debaixo dele). Claim órfão de sessão morta: `morph-spec claim <f> --release`.
 - `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.
 
 ## Skills core (em `.claude/skills/`)
@@ -64,7 +69,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

@@ -73,7 +73,7 @@ Anti-padrão: o Specialist não cria novas tarefas. Descobertas de escopo durant
 
 **Evaluator** — ativo após uma tarefa ou fase ser concluída.
 Responsabilidades: aplicar as rubricas em `.morph/framework/evals/rubrics/`, produzir score 0-10, emitir feedback priorizado quando score < 9 (que alimenta o loop de correção autônomo do morph-apply), escalar para revisão humana apenas quando o loop de correção se esgotar (3 tentativas sem atingir 9).
-No **Gate 3** o Evaluator é obrigatoriamente um sub-agent independente: a `morph-review` despacha o subagent registrado `morph-evaluator` (gerado de `agents.json`, tools read-only) com contexto fresco — mandate + diff da implementação + saída real dos testes — e o score composto da feature vem desse retorno, nunca de auto-avaliação de quem implementou.
+No **Gate 3** o Evaluator é obrigatoriamente um sub-agent independente: a `morph-review` despacha o subagent registrado `morph-evaluator` (gerado de `agents.json`, tools read-only) com contexto fresco — mandate + diff da implementação + saída real dos testes — e o score composto da feature vem desse retorno, nunca de auto-avaliação de quem implementou. **A regra é enforced server-side:** `morph-spec approve {feature} review` recusa (exit 1) enquanto `4-review/evaluator-report.md` não existir. Se o dispatch for genuinamente impossível nesta sessão, aprove com `--self-assessed` — a degradação é gravada em `approvalGates.review.selfAssessed` e aparece marcada no `morph-spec list`. `--force` não dispensa a regra (é só para ordem de gate).
 Anti-padrão: o Evaluator não reescreve o código que avaliou. Se o score está abaixo de 6, o relatório vai para o humano — não para uma segunda rodada de tentativa automática.
 
 Os papéis não são exclusivos — numa sessão longa você transita entre Orchestrator e Specialist conforme as tarefas avançam. A transição deve ser explícita: antes de mudar de papel, conclua o que estava fazendo ou registre o estado corrente no recap.md.
@@ -112,11 +112,11 @@ 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`.
+**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:
+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:
 
 - **Uma feature = um worktree = uma instância.** Nunca abra duas instâncias na mesma feature (o setup recusa com exit 3).
 - O estado autoritativo (`feature.json`) viaja **commitado na branch** `morph/{f}`. O `state.json` local do worktree é um índice derivável — materializado por self-heal, nunca sincronizado à mão.
@@ -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`.
@@ -289,6 +307,31 @@ O orquestrador **lê o arquivo** ao retomar controle após o dispatch — nunca
 mensagem de retorno da tool. Se a mensagem de texto final chegou inteira, ótimo (economiza uma
 leitura); se não chegou, o arquivo já está lá.
 
+### Protocolo de ausência de relatório
+
+**"Relatório ausente = o agente falhou" é a leitura errada.** O sub-agent pode ter feito todo o
+trabalho e perdido o meio de gravá-lo — foi o que aconteceu quando um worktree sumiu debaixo de um
+avaliador em execução. Tratar isso como falha joga fora trabalho real.
+
+A pergunta que decide não é "o relatório chegou?", é **"o TRABALHO entrou?"** — e ela se responde
+por evidência, não pela palavra do agente:
+
+```
+morph-spec report-check <feature> [task] --json
+```
+
+| veredito | o que significa | ação |
+|---|---|---|
+| `ok` | relatório presente e com os 4 itens | siga o fluxo |
+| `report-incomplete` | relatório existe, faltam itens (ele lista quais) | complete a partir da mensagem de retorno, carimbe **DEGRADADO** |
+| `work-landed-report-missing` | sem relatório, mas os `outputs` da task estão no disco | **não re-despache** — grave você mesmo o relatório canônico a partir da mensagem de retorno, carimbado **DEGRADADO** |
+| `no-work-no-report` | sem relatório e sem output | re-despache **uma** vez com o mesmo prompt |
+| `report-missing-evidence-unknown` | sem relatório e a task não declarou `outputs` | re-despache (sem evidência, o conservador é o certo) |
+
+Sai 0 só em `ok`. Em qualquer caminho degradado a degradação é **registrada** — no recap e nas
+`notes` da task —, nunca aceita em silêncio. Segunda ausência sem trabalho entregue é falha real:
+escale ao humano.
+
 **O que receber de volta (no arquivo, e na mensagem final quando ela chega):**
 - O que foi feito (2-3 frases)
 - Arquivos modificados (lista)

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/claude-code/core/telemetry-log.js

@@ -59,6 +59,21 @@ try {
     // enrichment is best-effort — a missing feature never blocks capture
   }
 
+  // Claim heartbeat (B1): this hook already fires on EVERY tool call, so it is
+  // the natural proof-of-life for the advisory feature claim — no extra hook,
+  // no discipline asked of the operator. The registry throttles the actual
+  // write (HEARTBEAT_THROTTLE_MS), so this is a small read on most calls.
+  // Silent and fail-open, like everything else here.
+  if (feature && payload.session_id) {
+    try {
+      const { execSync } = await import('child_process');
+      const { resolve } = await import('path');
+      const { heartbeatClaim } = await import('../../shared/claim-registry.js');
+      const common = execSync('git rev-parse --git-common-dir', { cwd, stdio: 'pipe' }).toString().trim();
+      if (common) heartbeatClaim(feature, { gitCommonDir: resolve(cwd, common), sessionId: payload.session_id });
+    } catch { /* fail-open — a missed heartbeat only shortens a claim's life */ }
+  }
+
   let event;
 
   // UserPromptSubmit carries the user's prompt and no tool_name.

package/framework/hooks/claude-code/core/worktree-context.js

@@ -4,7 +4,7 @@
  *
  * Event: SessionStart
  *
- * v8 runs each feature in its own git worktree (`.worktrees/{feature}/` on
+ * v8 runs each feature in its own git worktree (`worktrees/{feature}/` on
  * branch `morph/{feature}`), each with its own Claude Code instance. When a
  * session starts inside one of those worktrees, Claude has no built-in way to
  * know which feature it belongs to — this hook injects that identity so the
@@ -29,7 +29,7 @@
  */
 
 import { readFileSync, existsSync, readdirSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { execSync } from 'child_process';
 import {
   stateExists,
@@ -39,6 +39,7 @@ import {
   getTaskStats,
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
+import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registry.js';
 
 function readStdin() {
   try {
@@ -168,10 +169,44 @@ function buildActiveFeatureSummary(dir) {
   return text;
 }
 
+/**
+ * Advisory feature ownership (B1): claim the feature this session is about to
+ * work on, and — if another session already holds a LIVE claim — say so loudly
+ * before any work starts.
+ *
+ * Never blocks: the claim is a warning, not a lock (see claim-registry.js).
+ * The claim is taken regardless, so the registry reflects reality; the operator
+ * decides what to do with the collision.
+ *
+ * Fail-open per FIELD: no git common dir, or any registry error, just means no
+ * claim line — never a failed session start.
+ *
+ * @returns {string} a block to append to the injected context ('' when quiet)
+ */
+function claimBlock(dir, feature, sessionId) {
+  try {
+    const gitCommonDir = resolve(dir, gitRevParse('--git-common-dir', dir));
+    const other = foreignClaim(feature, { gitCommonDir, sessionId });
+    acquireClaim(feature, { gitCommonDir, sessionId, pid: process.pid, path: dir });
+    if (!other) return '';
+    return `\n⚠️  ATENÇÃO — a feature ${feature} tem claim VIVO de OUTRA sessão`
+      + `\n   pid ${other.pid}${other.path ? ` · ${other.path}` : ''} · visto há ${claimAge(other)}`
+      + '\n   Duas sessões na mesma feature já custaram um recap.md inteiro e um sub-agent'
+      + '\n   (o worktree sumiu debaixo dele). Confirme com a outra sessão ANTES de agir —'
+      + '\n   principalmente antes de `finish`, `archive` ou `delete`.'
+      + `\n   Se aquela sessão morreu: morph-spec claim ${feature} --release`;
+  } catch {
+    return '';
+  }
+}
+
 async function main() {
   try {
     const dir = projectDir();
-    readStdin(); // consume the SessionStart payload (source/session_id) — unused here
+    // The SessionStart payload carries session_id — the identity the claim
+    // registry uses to tell "me" from "another session".
+    const payload = readStdin();
+    const sessionId = payload?.session_id || `pid-${process.pid}`;
 
     if (!stateExists(dir)) {
       pass();
@@ -184,7 +219,7 @@ async function main() {
         pass();
         return;
       }
-      injectContext(buildWorktreeContext(dir, feature), 'SessionStart');
+      injectContext(buildWorktreeContext(dir, feature) + claimBlock(dir, feature, sessionId), 'SessionStart');
       return;
     }
 
@@ -194,7 +229,8 @@ async function main() {
       pass();
       return;
     }
-    injectContext(summary, 'SessionStart');
+    const active = getActiveFeature(dir);
+    injectContext(summary + (active?.name ? claimBlock(dir, active.name, sessionId) : ''), 'SessionStart');
   } catch {
     pass();
   }

package/framework/hooks/shared/claim-registry.js

@@ -0,0 +1,175 @@
+/**
+ * claim-registry.js — advisory feature ownership across parallel sessions.
+ *
+ * Two Claude Code sessions worked the SAME feature at the same time without
+ * seeing each other: one finished it and removed the worktree out from under
+ * the other's running sub-agent. A complete recap.md was discarded, a sub-agent
+ * wasted, and a decision taken on state that was already obsolete. There was no
+ * lock, no claim, no heartbeat — not even a warning.
+ *
+ * DELIBERATELY ADVISORY. This is not a lock: nothing here ever blocks a
+ * command. The framework is fail-open by principle, and a strong lock left
+ * behind by a crashed session would strand a feature for no gain. Being
+ * VISIBLE is the whole fix.
+ *
+ * Location: `<git-common-dir>/morph-spec/claims.json`, beside the fleet's
+ * env-registry, for the same three reasons — it can never dirty the `git
+ * status` the finish gates read, it survives `git clean -fdx`, and the COMMON
+ * dir is the one place every linked worktree of the repo shares. That last one
+ * is decisive here: in the observed incident one session sat inside the
+ * worktree and the other in the primary root, so a claim written to the
+ * branch-local `feature.json` would have been invisible to exactly the session
+ * that needed to read it.
+ *
+ * Writes are tmp+rename (torn file impossible); a corrupt registry reads as
+ * empty — the cost is a lost warning, never a crash.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * A claim with no heartbeat for this long is considered dead. The heartbeat
+ * fires on tool activity, so this is really "how long a session may sit idle
+ * before its claim stops warning others".
+ */
+export const CLAIM_TTL_MS = 30 * 60 * 1000;
+
+/** Minimum gap between heartbeat WRITES. The heartbeat runs on every tool call. */
+export const HEARTBEAT_THROTTLE_MS = 60 * 1000;
+
+/** Claim file path for a repo's common git dir. */
+export function claimsPath(gitCommonDir) {
+  return join(gitCommonDir, 'morph-spec', 'claims.json');
+}
+
+function readRegistry(gitCommonDir) {
+  try {
+    const raw = readFileSync(claimsPath(gitCommonDir), 'utf8').replace(/^/, '');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.claims === 'object' && parsed.claims !== null) return parsed;
+  } catch { /* fail-open: absent or corrupt registry restarts empty */ }
+  return { version: 1, claims: {} };
+}
+
+function writeRegistry(gitCommonDir, registry) {
+  const path = claimsPath(gitCommonDir);
+  mkdirSync(join(gitCommonDir, 'morph-spec'), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path);
+}
+
+/** Is this claim still within its TTL? A missing/unparseable heartbeat is dead. */
+export function isLive(claim, now = Date.now()) {
+  const beat = Date.parse(claim?.heartbeatAt ?? '');
+  return Number.isFinite(beat) && now - beat < CLAIM_TTL_MS;
+}
+
+/**
+ * Claim a feature for this session, or refresh an existing claim of ours.
+ *
+ * A claim held by ANOTHER session is TAKEN OVER, not refused — advisory by
+ * design, and the caller has already been warned via `foreignClaim`. The
+ * takeover is recorded in `previousSessionId` so it is never silent.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string, sessionId: string, pid?: number, path?: string }} opts
+ * @returns {object} the stored claim
+ */
+export function acquireClaim(feature, { gitCommonDir, sessionId, pid = process.pid, path = null }) {
+  const registry = readRegistry(gitCommonDir);
+  const previous = registry.claims[feature];
+  const now = new Date().toISOString();
+  const claim = {
+    feature,
+    sessionId,
+    pid,
+    path: path ? String(path).replace(/\\/g, '/') : null,
+    claimedAt: previous?.sessionId === sessionId ? (previous.claimedAt || now) : now,
+    heartbeatAt: now,
+    ...(previous && previous.sessionId !== sessionId ? { previousSessionId: previous.sessionId } : {}),
+  };
+  registry.claims[feature] = claim;
+  writeRegistry(gitCommonDir, registry);
+  return claim;
+}
+
+/**
+ * Refresh our own claim's heartbeat. Throttled — this runs on every tool call,
+ * and a write per call would be pure I/O waste.
+ *
+ * Never touches a claim owned by another session: a heartbeat is proof of life,
+ * and forging someone else's would defeat the TTL.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string, sessionId: string }} opts
+ * @returns {boolean} true when a write actually happened
+ */
+export function heartbeatClaim(feature, { gitCommonDir, sessionId }) {
+  const registry = readRegistry(gitCommonDir);
+  const claim = registry.claims[feature];
+  if (!claim || claim.sessionId !== sessionId) return false;
+
+  const beat = Date.parse(claim.heartbeatAt ?? '');
+  if (Number.isFinite(beat) && Date.now() - beat < HEARTBEAT_THROTTLE_MS) return false;
+
+  claim.heartbeatAt = new Date().toISOString();
+  writeRegistry(gitCommonDir, registry);
+  return true;
+}
+
+/**
+ * The LIVE claim on this feature held by a session that is not us — the thing
+ * worth warning about. Returns null when the feature is unclaimed, claimed by
+ * us, or claimed by a session whose heartbeat went stale.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string, sessionId?: string }} opts
+ * @returns {object|null}
+ */
+export function foreignClaim(feature, { gitCommonDir, sessionId }) {
+  const claim = readRegistry(gitCommonDir).claims[feature];
+  if (!claim) return null;
+  if (sessionId && claim.sessionId === sessionId) return null;
+  return isLive(claim) ? claim : null;
+}
+
+/**
+ * Drop a feature's claim. Called by the manual `morph-spec claim <f> --release`
+ * (recovering from a session that died without releasing) and by `finish`.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string }} opts
+ * @returns {boolean} false when there was nothing to release
+ */
+export function releaseClaim(feature, { gitCommonDir }) {
+  const registry = readRegistry(gitCommonDir);
+  if (!registry.claims[feature]) return false;
+  delete registry.claims[feature];
+  writeRegistry(gitCommonDir, registry);
+  return true;
+}
+
+/**
+ * Every claim on record, live and stale, newest heartbeat first. `live` is
+ * computed, never stored — a stored flag would go wrong the moment nobody
+ * rewrites the file.
+ *
+ * @param {string} gitCommonDir
+ * @returns {object[]}
+ */
+export function listClaims(gitCommonDir) {
+  const now = Date.now();
+  return Object.values(readRegistry(gitCommonDir).claims)
+    .map((c) => ({ ...c, live: isLive(c, now) }))
+    .sort((a, b) => String(b.heartbeatAt).localeCompare(String(a.heartbeatAt)));
+}
+
+/** Human-readable age of a claim's last heartbeat ("3 min", "2 h", "—"). */
+export function claimAge(claim, now = Date.now()) {
+  const beat = Date.parse(claim?.heartbeatAt ?? '');
+  if (!Number.isFinite(beat)) return '—';
+  const min = Math.max(0, Math.round((now - beat) / 60000));
+  return min < 60 ? `${min} min` : `${Math.round(min / 60)} h`;
+}

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',