@polymorphism-tech/morph-spec 8.6.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.6.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.6.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.6.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.6.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.6.0 by Polymorphism Tech*
+*morph-spec v8.7.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -43,7 +43,7 @@ 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}` — 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.
@@ -55,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/`)

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.
@@ -307,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/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/state-reader.js

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