@polymorphism-tech/morph-spec 8.6.0 → 8.8.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.8.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.8.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.8.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.8.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.8.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();
   }