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

package/bin/morph-spec.js

@@ -374,9 +374,9 @@ program
 // ─── 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')
+  .description('claim [feature] acquires it (moves this tree\'s previous claim in the same step); no args shows the board (claims are advisory warnings, never locks)')
   .option('--release', 'Release the claim on <feature> (recovery: the owning session died)')
-  .option('--list', 'List every claim on record (the default)')
+  .option('--list', 'Read-only: show claims without acquiring (default when no feature is given)')
   .option('--json', 'Output as JSON')
   .action((feature, options) => claimCommand(feature, options));
 

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.12.0",
+  "version": "8.14.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -185,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.12.0 by Polymorphism Tech*
+*morph-spec v8.14.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.12.0 by Polymorphism Tech*
+*morph-spec v8.14.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -26,7 +26,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - Auto-advance entre tarefas durante a fase implement — não pause sem ambiguidade bloqueante.
 - Abrir toda feature `feature`/`bug` com a escolha de **modo de descoberta** (entrevista ou automático), depois de varrer o ambiente e montar a árvore de decisões abertas. **No modo entrevista, uma pergunta por chamada de `AskUserQuestion`** — o "1-4 perguntas por chamada" do bloco NUNCA é o teto da tool, não licença para agrupar a entrevista. O Gate 1 pausa sempre nesse modo.
 - Atualizar o progresso em `tasks.json` ao concluir cada task gravando apenas os campos mutáveis `status`, `outputs` e `notes` — via `Write` OU `Edit` (o hook `protect-spec-files` faz diff semântico e permite qualquer um dos dois desde que o contrato do plano permaneça congelado).
-- Apresentar gates com o template fixo definido em MORPH.md / morph-plan.
+- Apresentar gates com o template fixo definido em MORPH.md / morph-plan. **A pergunta PRECISA nomear a feature** ("Gate 2 — Plano de {feature} aprovado?"): é por esse nome que o hook `state-sync` atribui a aprovação ao `feature.json` certo, na árvore certa. Sem nome, e havendo mais de uma feature na árvore, ele **recusa a gravar** e avisa — adivinhar já carimbou um Gate 2 na feature errada. Nesse caso aprove com `morph-spec approve <feature> <gate>`.
 - Registrar decisões não triviais em `decisions.md`.
 - Aplicar `morph-eval` após cada tarefa; silêncio em score ≥ 9 é o sinal correto. Score < 9 dispara o loop de correção autônomo (re-implementa, sem pausa), não escala ao humano entre tarefas. No Gate 3, o score composto da feature vem do **avaliador independente** despachado pela `morph-review` (persona `evaluator`, contexto fresco) — nunca de auto-avaliação de quem implementou.
 - Incluir as 3 cláusulas do contrato do relatório final em todo dispatch de sub-agent (**o sub-agent GRAVA o relatório em arquivo canônico ANTES de encerrar — `.morph/features/{f}/3-implement/reports/{taskId}.md`, ou `4-review/evaluator-report.md` para o avaliador — com os 4 itens obrigatórios (o quê / arquivos / problemas / auto-score 0-10); esse arquivo é o valor de retorno autoritativo, a última mensagem de texto é cortesia best-effort e pode não chegar inteira; ainda assim não chamar `SendMessage`, que gera um evento a mais e custa um turno inútil**; não tocar tasks.json/feature.json/board; sem build/test da suíte compartilhada em batch paralelo) — templates em `morph-implement` §4 e `morph-apply` §3b. **O orquestrador lê o arquivo ao retomar controle** — nunca confia só na mensagem de retorno da tool.
@@ -61,7 +61,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - `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, **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 claim [feature] [--release] [--list] [--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. **`morph-spec claim <feature>` (sem flags) ADQUIRE** — se esta árvore já tinha claim vivo em outra feature, ele é liberado no mesmo passo (o CLI reporta "movido de X para Y"); é o jeito de trocar de feature no meio da tarefa sem o dança de dois passos `--release` + reclamar. `--list` força a leitura sem adquirir mesmo passando uma feature. **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

@@ -251,7 +251,7 @@ Para alterar o modo: editar `.morph/config/config.json → trust` (`"auto"` ou `
 
 **Comportamento padrão fora de gate:** trabalhe com autonomia total. Gates só existem nestes três pontos. Não pause para confirmação no meio de implementação a menos que encontre uma ambiguidade de escopo que o mandate não cobre — nesse caso, registre a ambiguidade no decisions.md, resolva da forma mais conservadora possível, e sinalize na entrega da task.
 
-**A aprovação de gate é unificada nos comandos da CLI — a LLM nunca edita o estado à mão para aprovar um gate.** Em `trust: "auto"` (sem `AskUserQuestion`), a skill aprova o gate via `morph-spec approve <feature> <gate> --mode auto`; para aprovar o gate da fase corrente **e** já criar a pasta da próxima fase num passo só, use `morph-spec advance <feature>` (adicione `--design` para tomar o ramo opcional de uiux a partir da proposta) — isso substitui o Edit manual de state.json + `mkdir` da pasta de fase. Os scores por task também têm comando dedicado: `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. **O hook state-sync.js** cobre o caminho manual: quando uma `AskUserQuestion` é respondida com label começando em "aprovado", ele registra o gate correspondente no `feature.json` autoritativo da feature com `approvedBy: "manual"` (um humano aprovou no loop), na forma canônica. Nos dois caminhos o gate acaba gravado em `.morph/features/{feature}/feature.json` — nunca via Edit à mão de `state.json`.
+**A aprovação de gate é unificada nos comandos da CLI — a LLM nunca edita o estado à mão para aprovar um gate.** Em `trust: "auto"` (sem `AskUserQuestion`), a skill aprova o gate via `morph-spec approve <feature> <gate> --mode auto`; para aprovar o gate da fase corrente **e** já criar a pasta da próxima fase num passo só, use `morph-spec advance <feature>` (adicione `--design` para tomar o ramo opcional de uiux a partir da proposta) — isso substitui o Edit manual de state.json + `mkdir` da pasta de fase. Os scores por task também têm comando dedicado: `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. **O hook state-sync.js** cobre o caminho manual: quando uma `AskUserQuestion` é respondida com label começando em "aprovado", ele registra o gate correspondente no `feature.json` autoritativo da feature com `approvedBy: "manual"` (um humano aprovou no loop), na forma canônica. **A feature é identificada pelo nome que a pergunta cita** — e o `feature.json` gravado é o da árvore que possui essa feature (raiz ou worktree), nunca o da "feature ativa" de quem por acaso rodou a sessão. Por isso os templates de gate nomeiam a feature: uma pergunta sem nome, numa árvore com mais de uma feature, faz o hook **recusar a gravar** e avisar — aprove então por `morph-spec approve <feature> <gate>`. Nos dois caminhos o gate acaba gravado em `.morph/features/{feature}/feature.json` — nunca via Edit à mão de `state.json`.
 
 **Registre quem aprovou cada gate (`approvedBy`):** o gate é um objeto `{ approved, timestamp, approvedBy }`.
 - `approvedBy: "auto"` — gate avançado por política `trust: auto` sem decisão humana.

package/framework/hooks/claude-code/core/enforce-phase-writes.js

@@ -18,7 +18,6 @@
  */
 
 import { existsSync } from 'fs';
-import { resolve } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists, getFeaturePhase, isGateApproved } from '../../shared/state-reader.js';
 import {
@@ -43,7 +42,7 @@ const PHASE_DIR_ENTRY_GATE = {
 };
 import { block, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
-import { getFilePath } from '../../shared/payload-utils.js';
+import { getFilePath, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 
 try {
   // Amend mode: bypass phase write enforcement for legitimate corrections
@@ -52,8 +51,6 @@ try {
     pass();
   }
 
-  if (!stateExists()) pass();
-
   const payload = await readStdin();
   if (!payload) pass();
 
@@ -63,10 +60,19 @@ try {
   // Only check files inside .morph/features/
   if (!isFeaturePath(filePath)) pass();
 
+  // Resolve the tree that OWNS this file, NOT the tree the session sits in.
+  // A session rooted in the primary repo may legitimately write to a feature
+  // living in a secondary worktree; reading the session's `.morph/` there
+  // reported the ROOT's phase for the WORKTREE's file, and blocked a legal
+  // `2-plan/` write with "not allowed during PROPOSAL phase". `stateExists`
+  // must be asked of that same tree — a worktree carries its own state.
+  const root = resolveMorphRoot(filePath, process.cwd());
+  if (!stateExists(root)) pass();
+
   const featureName = extractFeatureName(filePath);
   if (!featureName) pass();
 
-  const phase = getFeaturePhase(featureName);
+  const phase = getFeaturePhase(featureName, root);
   if (!phase) pass();
 
   // During implement phase, all writes are allowed (source code is unrestricted)
@@ -80,7 +86,7 @@ try {
 
   if (targetDir !== allowedDir) {
     // Allow editing already-existing files from previous phases
-    const absolutePath = resolve(process.cwd(), filePath);
+    const absolutePath = resolveTargetPath(filePath, root);
     if (existsSync(absolutePath)) {
       logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
       pass(); // editing existing file — allow
@@ -91,19 +97,25 @@ try {
     // this, the first file of a new phase can never be written (the phase only
     // advances once that file exists) — the deadlock this hook used to create.
     const entryGate = PHASE_DIR_ENTRY_GATE[targetDir];
-    if (entryGate && isGateApproved(featureName, entryGate)) {
+    if (entryGate && isGateApproved(featureName, entryGate, root)) {
       logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
       pass();
     }
 
     const phaseLabel = phase.toUpperCase();
+    // Name the tree the verdict came from whenever it is NOT the session's own.
+    // The phase read is per-tree, so "which .morph/ said proposal?" is the first
+    // question anyone debugging this asks.
+    const treeNote = root !== process.cwd().replace(/\\/g, '/')
+      ? `\n(phase read from the tree that owns the file: ${root})`
+      : '';
     logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
     block(
       `MORPH-SPEC: Writing to '${targetDir}/' is not allowed during ${phaseLabel} phase.\n` +
-      `Current phase '${phase}' only permits writes to '${allowedDir}/'.\n\n` +
+      `Current phase '${phase}' only permits writes to '${allowedDir}/'.${treeNote}\n\n` +
       `To move forward, approve the current gate and scaffold the next phase in\n` +
       `one step:  morph-spec advance ${featureName}\n` +
-      `(this approves the gate that unlocks the next phase folder).`
+      `(run it in that tree — the gate is recorded in its own feature.json).`
     );
   }
 

package/framework/hooks/claude-code/core/gate-guard.js

@@ -25,9 +25,11 @@
  */
 
 import { readFileSync } from 'fs';
-import { loadState, stateExists } from '../../shared/state-reader.js';
+import { loadState, stateExists, getActiveFeature } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
+import { locateFeatureForQuestion } from '../../shared/feature-locator.js';
 
 function readStdin() {
   try {
@@ -41,12 +43,38 @@ function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
 
-function findActiveFeature(state) {
-  if (!state.features) return null;
-  const entries = Object.entries(state.features);
-  const active = entries.find(([, f]) => f.status === 'in_progress');
-  if (active) return active[0];
-  return entries[0]?.[0] ?? null;
+/** Feature slug from a `.morph/features/{name}/feature.json` path. */
+function featureFromStatePath(filePath) {
+  const fp = String(filePath ?? '').replace(/\\/g, '/');
+  return (fp.match(/\.morph\/features\/([^/]+)\/feature\.json$/) ?? [])[1] ?? null;
+}
+
+/**
+ * The tree owning an edited gate-state file. `resolveMorphRoot` covers the v5
+ * per-feature `feature.json`; the legacy `.morph/state.json` has no feature
+ * segment to anchor on, so strip its own suffix instead.
+ */
+function rootOfGateStateFile(filePath, fallback) {
+  const abs = resolveTargetPath(filePath, fallback);
+  const suffix = '/.morph/state.json';
+  if (abs.endsWith(suffix)) return abs.slice(0, -suffix.length) || fallback;
+  return resolveMorphRoot(abs, fallback);
+}
+
+/** Every question/header text this AskUserQuestion call surfaced. */
+function askedTexts(input) {
+  const texts = [];
+  const questions = input.tool_input?.questions;
+  if (Array.isArray(questions)) {
+    for (const q of questions) {
+      if (typeof q?.question === 'string') texts.push(q.question);
+      if (typeof q?.header === 'string') texts.push(q.header);
+    }
+  }
+  // Fallback: some payloads only surface answered question keys.
+  const answers = input.tool_response?.answers ?? input.tool_response?.responses;
+  if (answers && typeof answers === 'object') texts.push(...Object.keys(answers));
+  return texts;
 }
 
 /** Map a gate question's text to a gate id. Mirrors state-sync.js. */
@@ -69,25 +97,23 @@ function getDecision(state, feature, gate) {
  * The LLM just asked a gate question. If the persisted decision said this
  * gate should auto-pass (pause:false), the human was interrupted needlessly.
  */
-function checkAskUserQuestion(input, state, feature, cwd) {
-  // Questions live in tool_input.questions[]; answers in tool_response.
-  const questions = input.tool_input?.questions;
-  const askedTexts = [];
-  if (Array.isArray(questions)) {
-    for (const q of questions) {
-      if (typeof q?.question === 'string') askedTexts.push(q.question);
-      if (typeof q?.header === 'string') askedTexts.push(q.header);
-    }
-  }
-  // Fallback: some payloads only surface answered question keys.
-  const answers = input.tool_response?.answers ?? input.tool_response?.responses;
-  if (answers && typeof answers === 'object') {
-    askedTexts.push(...Object.keys(answers));
-  }
-
-  for (const text of askedTexts) {
+function checkAskUserQuestion(input, sessionRoot) {
+  for (const text of askedTexts(input)) {
     const gate = gateFromQuestion(text);
     if (!gate) continue;
+
+    // Check the decision of the feature the question NAMES, in its own tree.
+    // Reading the session tree's first in_progress feature made this guard
+    // compare a gate against an unrelated feature's gateDecisions — a warning
+    // about the wrong thing is worse than silence, so an unattributable
+    // question is skipped rather than guessed at (state-sync already tells the
+    // operator when a gate answer could not be attributed).
+    const located = locateFeatureForQuestion(text, sessionRoot);
+    if (!located) continue;
+    const { name: feature, root: cwd } = located;
+    if (!stateExists(cwd)) continue; // fail-open
+
+    const state = loadState(cwd);
     const decision = getDecision(state, feature, gate);
     if (!decision) continue; // no persisted decision → nothing to verify
     if (decision.pause === false) {
@@ -121,8 +147,19 @@ function isGateStateFile(filePath) {
  * feature.json in v5). If a gate flipped to approvedBy:"auto" but the
  * persisted decision said pause:true, a required human pause was skipped.
  */
-function checkStateEdit(input, state, feature, cwd) {
-  if (!isGateStateFile(input.tool_input?.file_path)) return pass();
+function checkStateEdit(input, sessionRoot) {
+  const filePath = input.tool_input?.file_path;
+  if (!isGateStateFile(filePath)) return pass();
+
+  // The edited file names its own tree — and, for the v5 per-feature
+  // feature.json, its own feature. Only the legacy `.morph/state.json` shape
+  // still needs a most-recently-updated fallback within that tree.
+  const cwd = rootOfGateStateFile(filePath, sessionRoot);
+  if (!stateExists(cwd)) return pass(); // fail-open
+  const state = loadState(cwd);
+  if (!state) return pass();
+  const feature = featureFromStatePath(filePath) || getActiveFeature(cwd)?.name;
+  if (!feature) return pass();
 
   let checked = false;
   const gates = state.features?.[feature]?.approvalGates ?? {};
@@ -150,8 +187,9 @@ function checkStateEdit(input, state, feature, cwd) {
 }
 
 function main() {
-  const cwd = projectDir();
-  if (!stateExists(cwd)) return pass();
+  // Starting point only — each branch resolves the tree it actually inspects
+  // (from the edited path, or from the feature the question names).
+  const sessionRoot = projectDir();
 
   const input = readStdin();
   const toolName = input.tool_name;
@@ -166,13 +204,8 @@ function main() {
   }
 
   try {
-    const state = loadState(cwd);
-    if (!state) return pass();
-    const feature = findActiveFeature(state);
-    if (!feature) return pass();
-
-    if (toolName === 'AskUserQuestion') return checkAskUserQuestion(input, state, feature, cwd);
-    if (toolName === 'Edit' || toolName === 'Write') return checkStateEdit(input, state, feature, cwd);
+    if (toolName === 'AskUserQuestion') return checkAskUserQuestion(input, sessionRoot);
+    return checkStateEdit(input, sessionRoot);
   } catch {
     // fail-open
   }

package/framework/hooks/claude-code/core/protect-spec-files.js

@@ -24,7 +24,6 @@
  */
 
 import { readFileSync } from 'fs';
-import { isAbsolute, join } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists, isGateApproved } from '../../shared/state-reader.js';
 import {
@@ -36,7 +35,7 @@ import {
 } from '../../shared/phase-utils.js';
 import { block, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
-import { getFilePath, getToolName } from '../../shared/payload-utils.js';
+import { getFilePath, getToolName, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 import { validateTasksDoc, outputsDivergenceViolations } from '../../shared/tasks-validator.js';
 
 /**
@@ -106,8 +105,6 @@ try {
     pass();
   }
 
-  if (!stateExists()) pass();
-
   const payload = await readStdin();
   if (!payload) pass();
 
@@ -117,6 +114,14 @@ try {
   // Only check files inside .morph/features/
   if (!isFeaturePath(filePath)) pass();
 
+  // The gate that locks this file is recorded in the feature.json of the tree
+  // that OWNS it. Asking the session's tree instead made this guard go DARK in
+  // a secondary worktree: the root had no approved gate, so a post-Gate-2
+  // spec.md rewrite sailed through. Same defect as enforce-phase-writes,
+  // opposite direction — there it over-blocked, here it under-protected.
+  const root = resolveMorphRoot(filePath, process.cwd());
+  if (!stateExists(root)) pass();
+
   const featureName = extractFeatureName(filePath);
   if (!featureName) pass();
 
@@ -127,7 +132,7 @@ try {
   if (!requiredGate) pass();
 
   // Gate not yet approved — allow editing
-  if (!isGateApproved(featureName, requiredGate)) {
+  if (!isGateApproved(featureName, requiredGate, root)) {
     logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
     pass();
   }
@@ -143,7 +148,7 @@ try {
     // Build the proposed document from either a full Write or a targeted Edit,
     // then semantic-diff it against the current file on disk. Any failure to
     // read / parse / apply → fail-open (pass), never a false block.
-    const absPath = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
+    const absPath = resolveTargetPath(filePath, root);
     let oldDoc, newDoc;
     try {
       const original = readFileSync(absPath, 'utf-8');

package/framework/hooks/claude-code/core/state-sync.js

@@ -13,7 +13,14 @@
 
 import { readFileSync } from 'fs';
 import { loadState, stateExists } from '../../shared/state-reader.js';
-import { persistFeature, setGateApproved, createDefaultFeature } from '../../shared/state-writer.js';
+import { persistFeature, setGateApproved, createDefaultFeature, readFeatureFile } from '../../shared/state-writer.js';
+import { resolveMorphRoot } from '../../shared/payload-utils.js';
+import {
+  locateFeatureForQuestion,
+  allWorkTrees,
+  featureNamesIn,
+  unrecognizedSlugLike,
+} from '../../shared/feature-locator.js';
 
 const PHASE_FOLDERS = {
   '0-proposal': 'proposal',
@@ -87,14 +94,6 @@ function trackOutput(state, featureName, filePath) {
   return wasMissing;
 }
 
-function findActiveFeature(state) {
-  if (!state.features) return null;
-  const entries = Object.entries(state.features);
-  const active = entries.find(([, f]) => f.status === 'in_progress');
-  if (active) return active[0];
-  return entries[0]?.[0] ?? null;
-}
-
 function isApprovalAnswer(answer) {
   if (typeof answer !== 'string') return false;
   const lower = answer.toLowerCase();
@@ -124,11 +123,17 @@ function unmetGatePrereqs(gate, gates) {
   return (GATE_PREREQ[gate] || []).filter((p) => !isApproved(p));
 }
 
-function handleWriteEdit(input, cwd) {
+function handleWriteEdit(input, sessionRoot) {
   const filePath = input.tool_input?.file_path;
   const featureName = extractFeatureName(filePath);
   if (!featureName) return false;
 
+  // Sync the tree that OWNS the written file. Syncing the session's tree
+  // instead registered the feature (and its outputs) in the wrong `.morph/`
+  // whenever a root-rooted session wrote into a secondary worktree.
+  const cwd = resolveMorphRoot(filePath, sessionRoot);
+  if (!stateExists(cwd)) return false;
+
   const state = loadState(cwd);
   if (!state) return false;
 
@@ -147,23 +152,56 @@ function handleWriteEdit(input, cwd) {
   return true;
 }
 
-function handleAskUserQuestion(input, cwd) {
+function handleAskUserQuestion(input, sessionRoot) {
   const answers = input.tool_response?.answers ?? input.tool_response?.responses ?? {};
   if (typeof answers !== 'object' || answers === null) return null;
 
-  const state = loadState(cwd);
-  if (!state) return null;
-
-  const featureName = findActiveFeature(state);
-  if (!featureName) return null;
-
   const warnings = [];
   for (const [question, answer] of Object.entries(answers)) {
     if (!isApprovalAnswer(answer)) continue;
     const gate = gateFromQuestion(question);
     if (!gate) continue;
 
-    const gates = state.features[featureName].approvalGates;
+    // Attribute the approval to the feature the QUESTION names, in the tree
+    // that owns it — never to "the first in_progress feature of whatever tree
+    // the session sits in", which is how a Gate 2 for one feature was stamped
+    // onto `export-hub`, leaving it with G2 approved and G1 never asked.
+    const located = locateFeatureForQuestion(question, sessionRoot);
+    if (!located) {
+      // Refuse to guess. A gate on the wrong feature inverts gate order and
+      // invites a second stamp on the real owner; writing nothing costs one
+      // explicit remediation step.
+      //
+      // The remediation differs by WHY it refused. When the question names a
+      // specific slug that no known tree has registered (a hotfix gate asked
+      // before `create` ran — the case that used to fall through to "the
+      // tree's one feature"), `morph-spec approve <that-name> <gate>` is a
+      // dead end: approve.js does `getFeature()` and hard-refuses "Feature
+      // not found". Name the real fix instead of the wrong command.
+      const allNames = allWorkTrees(sessionRoot).flatMap((r) => featureNamesIn(r));
+      const candidate = unrecognizedSlugLike(question, allNames);
+      const remediation = candidate
+        ? `"${candidate}" não está registrada em nenhuma árvore conhecida. Se é uma feature nova, crie-a primeiro: ` +
+          `morph-spec create ${candidate} --description "<o quê/porquê>" --type <feature|bug|chore|hotfix> — ` +
+          `depois aprove com: morph-spec approve ${candidate} ${gate}`
+        : `Aprove explicitamente: morph-spec approve <feature> ${gate}`;
+      warnings.push(
+        `⚠️ [morph-spec] APROVAÇÃO NÃO ATRIBUÍDA — a resposta "aprovado" ao Gate "${gate}" NÃO foi gravada: ` +
+        `a pergunta não nomeia nenhuma feature conhecida ("${question}"). ` +
+        `Gravar por palpite carimbaria o gate na feature errada. ${remediation}`
+      );
+      continue;
+    }
+
+    const { name: featureName, root } = located;
+    if (!stateExists(root)) continue;
+
+    // Prefer the authoritative feature.json; fall back to loadState's merged
+    // view so a feature carried only by the thin index still reports its real
+    // gates (otherwise every predecessor reads as unapproved and the
+    // out-of-order warning below fires on a perfectly ordered approval).
+    const feature = readFeatureFile(featureName, root) || loadState(root)?.features?.[featureName];
+    const gates = feature?.approvalGates;
     const existing = gates?.[gate];
     const alreadyApproved = existing === true || existing?.approved === true;
     if (alreadyApproved) continue;
@@ -186,17 +224,19 @@ function handleAskUserQuestion(input, cwd) {
     // (`morph-spec approve`) produce one consistent shape
     // ({ approved, timestamp, approvedBy }) in the authoritative feature.json —
     // and a manual approval stays distinguishable from a policy auto-approval.
-    setGateApproved(featureName, gate, { approvedBy: 'manual' }, cwd);
+    setGateApproved(featureName, gate, { approvedBy: 'manual' }, root);
   }
   return warnings.length ? warnings.join('\n') : null;
 }
 
 async function main() {
-  const cwd = projectDir();
-  if (!stateExists(cwd)) {
-    exit();
-    return;
-  }
+  // The SESSION's root. It is only a starting point: which `.morph/` actually
+  // gets read and written is decided per event — by the target path for
+  // Write/Edit, by the feature the question names for AskUserQuestion. The
+  // `stateExists` gate therefore moved into each handler, against the tree that
+  // handler resolved; gating on the session's tree up here would skip work that
+  // belongs to a worktree (and, worse, silently pass it to the wrong one).
+  const sessionRoot = projectDir();
 
   const input = readStdin();
   const toolName = input.tool_name;
@@ -204,9 +244,9 @@ async function main() {
   let warning = null;
   try {
     if (toolName === 'Write' || toolName === 'Edit') {
-      handleWriteEdit(input, cwd);
+      handleWriteEdit(input, sessionRoot);
     } else if (toolName === 'AskUserQuestion') {
-      warning = handleAskUserQuestion(input, cwd);
+      warning = handleAskUserQuestion(input, sessionRoot);
     }
   } catch {
     // fail-open

package/framework/hooks/claude-code/core/trace-autogen.js

@@ -30,7 +30,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from
 import { join } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists } from '../../shared/state-reader.js';
-import { getFilePath } from '../../shared/payload-utils.js';
+import { getFilePath, resolveMorphRoot } from '../../shared/payload-utils.js';
 
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -69,9 +69,6 @@ function sessionId(d) {
 const STATUS_MAP = { done: 'completed', skipped: 'skipped', blocked: 'failed' };
 
 async function main() {
-  const cwd = projectDir();
-  if (!stateExists(cwd)) return;
-
   const payload = await readStdin();
   if (!payload) return;
 
@@ -79,6 +76,14 @@ async function main() {
   const feature = filePath ? extractFeature(filePath) : null;
   if (!feature) return;
 
+  // Read the sources — and write the trace — in the tree that owns the written
+  // tasks.json. Resolving from the session instead made this hook INERT for
+  // every worktree feature: the root's copy of the feature has no
+  // `2-plan/tasks.json`, so the `existsSync` guard below returned silently and
+  // no trace was ever produced for work done in a worktree.
+  const cwd = resolveMorphRoot(filePath, projectDir());
+  if (!stateExists(cwd)) return;
+
   const featureDir = join(cwd, '.morph', 'features', feature);
   const tasksPath = join(featureDir, '2-plan', 'tasks.json');
   if (!existsSync(tasksPath)) return;

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

@@ -146,9 +146,18 @@ function buildWorktreeContext(dir, feature) {
   const handoffLine = buildHandoffLine(dir, feature);
   if (handoffLine) text += `\n${handoffLine}`;
 
-  const missingJunctions = !existsSync(join(dir, 'node_modules')) || !existsSync(join(dir, '.claude'));
-  if (missingJunctions) {
-    text += `\n⚠ Infra compartilhada ausente (node_modules/.claude). Rode: morph-spec worktree link --all`;
+  // `.morph/framework` is checked alongside the other two because the hook
+  // commands resolve to `$CLAUDE_PROJECT_DIR/.morph/framework/hooks/...`: if
+  // that junction is missing, `node` finds no file and EVERY guardrail in this
+  // worktree is silently dark — the worst failure mode of the lot, and the one
+  // the old two-item check could not see.
+  const missing = ['node_modules', '.claude', join('.morph', 'framework')]
+    .filter((rel) => !existsSync(join(dir, rel)));
+  if (missing.length) {
+    text += `\n⚠ Infra compartilhada ausente (${missing.join(', ').replace(/\\/g, '/')}). Rode: morph-spec worktree link --all`;
+    if (missing.includes(join('.morph', 'framework'))) {
+      text += `\n   Sem .morph/framework os hooks do morph-spec NÃO executam neste worktree (nenhum guardrail ativo).`;
+    }
   }
 
   return text;

package/framework/hooks/shared/feature-locator.js

@@ -0,0 +1,164 @@
+/**
+ * Locate which tree owns a feature, and which feature a gate question is about.
+ *
+ * `resolveMorphRoot` (payload-utils) answers this from a file path. Some hook
+ * events carry no path at all — an `AskUserQuestion` gate approval is the one
+ * that matters — and those were resolved by "the first in_progress feature of
+ * whatever tree the session happens to sit in". That is how a Gate 2 approval
+ * for one feature landed on `export-hub`, an unrelated feature that merely
+ * happened to be active in the primary root.
+ *
+ * The honest signal for a pathless event is the question text itself: every
+ * gate template in the core skills names its feature — "Gate 1 — Proposta de
+ * {feature} aprovada?", "Gate 2 — Plano de {feature} aprovado?", "Gate 3 —
+ * Review de {feature} aprovado?", "Gate 3 — Hotfix de {feature} pronto para
+ * ship?". Rather than parse those sentences (which would break the moment a
+ * template is reworded), match the question against the set of feature slugs
+ * that actually exist on disk.
+ *
+ * When the text names no known feature, the caller must REFUSE TO GUESS.
+ * Stamping a gate onto the wrong feature is close to unrecoverable — it inverts
+ * gate order and invites a second stamp on the real owner; writing nothing
+ * costs one `morph-spec approve`.
+ *
+ * Fail-open by contract: every function swallows errors and returns an empty
+ * result rather than throwing.
+ */
+
+import { execSync } from 'child_process';
+import { loadState } from './state-reader.js';
+
+/**
+ * Feature slugs known to `root`.
+ *
+ * Deliberately `loadState` and not a `readdirSync` of `.morph/features/`: state
+ * lives in BOTH shapes — the thin `.morph/state.json` index and the per-feature
+ * `feature.json` — and `loadState` is the one place that already merges them.
+ * Listing directories alone misses every feature carried only by the index.
+ */
+export function featureNamesIn(root) {
+  try {
+    const state = loadState(root);
+    return state?.features ? Object.keys(state.features) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Every working tree of this repo — the primary root plus every registered
+ * secondary worktree. Fail-open to `[sessionRoot]` when git is unavailable or
+ * the directory is not a repo.
+ */
+export function allWorkTrees(sessionRoot) {
+  const roots = [sessionRoot];
+  try {
+    const out = execSync('git worktree list --porcelain', {
+      cwd: sessionRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 2000,
+    }).toString();
+    for (const line of out.split('\n')) {
+      if (!line.startsWith('worktree ')) continue;
+      const path = line.slice('worktree '.length).trim();
+      if (path && !roots.includes(path)) roots.push(path);
+    }
+  } catch {
+    /* fail-open — the session root alone */
+  }
+  return roots;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * The single feature slug named in `text`, or null.
+ *
+ * Slug boundaries are `[^a-z0-9-]` so a longer name never matches inside a
+ * shorter one (`export` must not match the text "export-hub"). Zero matches
+ * means the text named nothing; two or more means it named two features and is
+ * ambiguous. Both are null — "I don't know" and "it's ambiguous" must lead to
+ * the same refusal, not to a coin flip.
+ *
+ * @param {string} text
+ * @param {string[]} names - candidate slugs
+ * @returns {string|null}
+ */
+export function featureNamedIn(text, names) {
+  if (typeof text !== 'string' || !Array.isArray(names) || names.length === 0) return null;
+  const haystack = text.toLowerCase();
+  const hits = names.filter((name) =>
+    new RegExp(`(^|[^a-z0-9-])${escapeRe(String(name).toLowerCase())}([^a-z0-9-]|$)`).test(haystack)
+  );
+  return hits.length === 1 ? hits[0] : null;
+}
+
+/**
+ * A token in `text` shaped like a feature slug (kebab-case, at least one
+ * hyphen — `morph-spec create`'s naming convention) that names none of
+ * `names`. Signals "the text is talking about a specific feature I don't
+ * know" as opposed to "the text names nothing in particular".
+ *
+ * This is what the single-feature fallback below was missing: a gate question
+ * for a feature not yet registered (no `create`, no `proposal.md` written
+ * yet — a fresh hotfix, say) names NO known feature either, and used to fall
+ * through to "the tree's one feature must be it". That is exactly how a Gate 3
+ * for `backfill-bool-filter` landed on `export-hub`, the tree's only
+ * registered feature at the time.
+ *
+ * Deliberately narrow (requires a hyphen) to match real feature slugs
+ * (`export-hub`, `backfill-bool-filter`) without flagging ordinary prose —
+ * the fixed portions of every gate template ("Proposta", "aprovado", "Sinal",
+ * "pronto para ship"...) are single words with no internal hyphen.
+ *
+ * @param {string} text
+ * @param {string[]} names - every feature slug known across all trees
+ * @returns {string|null}
+ */
+export function unrecognizedSlugLike(text, names) {
+  if (typeof text !== 'string') return null;
+  const known = new Set((names || []).map((n) => String(n).toLowerCase()));
+  const tokens = text.toLowerCase().match(/[a-z0-9]+(?:-[a-z0-9]+)+/g) || [];
+  return tokens.find((t) => !known.has(t)) ?? null;
+}
+
+/**
+ * Resolve a gate question to `{ name, root }`.
+ *
+ * The session root is consulted first so the common case costs no git call, and
+ * so a feature present in BOTH trees resolves to the tree the session is
+ * actually in — the same tree `morph-spec approve` would write from that cwd.
+ * Only when the session root knows no such feature do we pay for enumerating
+ * the worktrees.
+ *
+ * @returns {{name: string, root: string}|null} null ⇒ caller must not guess
+ */
+export function locateFeatureForQuestion(text, sessionRoot) {
+  const trees = allWorkTrees(sessionRoot);
+  const localNames = featureNamesIn(sessionRoot);
+
+  const local = featureNamedIn(text, localNames);
+  if (local) return { name: local, root: sessionRoot };
+
+  for (const root of trees) {
+    if (root === sessionRoot) continue;
+    const found = featureNamedIn(text, featureNamesIn(root));
+    if (found) return { name: found, root };
+  }
+
+  // The text names a specific feature none of the trees know — refuse rather
+  // than guess it meant the tree's one registered feature (see
+  // `unrecognizedSlugLike` above).
+  const allNames = trees.flatMap(featureNamesIn);
+  if (unrecognizedSlugLike(text, allNames)) return null;
+
+  // Unambiguous fallback: the session's tree holds exactly ONE feature, so
+  // there is no other feature the answer could have been about. This is the
+  // single-feature project — the common case — and refusing there would break
+  // gate questions phrased without a name ("Gate 1 — Proposta aprovada?").
+  // With two or more features the fallback is exactly the guess that put a
+  // Gate 2 on `export-hub`, so it stops here.
+  if (localNames.length === 1) return { name: localNames[0], root: sessionRoot };
+
+  return null;
+}

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

@@ -47,6 +47,77 @@ export function resolveRootForFile(filePath, fallbackCwd, markers = ['package.js
   }
 }
 
+/**
+ * Resolve the project root that OWNS a `.morph/features/...` path — the tree
+ * whose `.morph/` the hook must read and write for that file.
+ *
+ * A hook process knows only where the SESSION lives (`process.cwd()` /
+ * `CLAUDE_PROJECT_DIR`). That is not the same thing as where the FILE lives: a
+ * session rooted in the primary repo can legitimately write to a feature that
+ * lives in a secondary git worktree. Resolving state from the process instead
+ * of the path is what made `enforce-phase-writes` block a legal `2-plan/` write
+ * (the root still had the feature at `proposal`) while `protect-spec-files`
+ * simultaneously went DARK there (the root had no approved gate to enforce) —
+ * one defect, opposite directions.
+ *
+ * The anchor is exact, so no marker walk is needed: everything before the
+ * file's own `.morph/features/` segment IS the owning root. `lastIndexOf` picks
+ * the CLOSEST enclosing `.morph/` — the worktree's, not the root it nests under.
+ *
+ * Note this cannot be solved by locating the hook file itself: `worktree setup`
+ * junctions `.morph/framework/` back to the primary root, so every worktree
+ * executes the very same hook file. Only the target path identifies the tree.
+ *
+ * Fail-open: never throws — returns `fallbackCwd` for any non-feature path.
+ *
+ * @param {string} filePath - target file path (absolute or relative)
+ * @param {string} fallbackCwd - root to use when the path owns no `.morph/`
+ * @returns {string} the resolved project root
+ */
+export function resolveMorphRoot(filePath, fallbackCwd) {
+  try {
+    if (!filePath) return fallbackCwd;
+    const p = toAbsolutePosix(filePath, fallbackCwd);
+
+    const idx = p.lastIndexOf('/.morph/features/');
+    if (idx <= 0) return fallbackCwd;
+    return p.slice(0, idx);
+  } catch {
+    return fallbackCwd;
+  }
+}
+
+/**
+ * Is this an already-absolute path, on EITHER convention?
+ *
+ * `path.isAbsolute` is platform-bound: `C:/x` is absolute on win32 and relative
+ * on posix. That asymmetry is a real defect here, not a theoretical one — a
+ * Windows-shaped path reaching a posix `join()` produces `/cwd/C:/x`, silently
+ * resolving state against a directory that cannot exist. Recognizing the drive
+ * letter explicitly makes the answer the same everywhere (and is a no-op on
+ * win32, where `isAbsolute` already accepts it).
+ */
+const isAbsolutePath = (p) => isAbsolute(p) || /^[a-zA-Z]:\//.test(p);
+
+/** Normalize to forward slashes and make absolute against `fallbackCwd`. */
+function toAbsolutePosix(filePath, fallbackCwd) {
+  const p = String(filePath).replace(/\\/g, '/');
+  return isAbsolutePath(p) ? p : join(fallbackCwd, p).replace(/\\/g, '/');
+}
+
+/**
+ * Absolute path of a hook's target file, resolved against the root that owns
+ * it. Pairs with `resolveMorphRoot` so a hook never mixes "the tree I read
+ * state from" with "the file I read content from".
+ *
+ * @param {string} filePath
+ * @param {string} fallbackCwd
+ * @returns {string}
+ */
+export function resolveTargetPath(filePath, fallbackCwd) {
+  return toAbsolutePosix(filePath || '', fallbackCwd);
+}
+
 /**
  * Get the file path from a hook payload, normalizing backslashes.
  * @param {Object} payload - Hook payload from stdin

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # create-umbraco-lp

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # migrate-lp-to-umbraco

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-apply
@@ -220,7 +220,7 @@ O comando grava `gateDecisions.review = { pause, reason, signals, trust, decided
 
 ### 6. Pós Gate 3 — encerramento
 
-- Aprovar o Gate 3: em auto, `morph-spec approve {feature} review --mode auto`; em manual, o hook state-sync registra a resposta "aprovado" em AskUserQuestion. O gate fica gravado no `feature.json` autoritativo da feature — nunca via Edit à mão de `state.json`.
+- Aprovar o Gate 3: em auto, `morph-spec approve {feature} review --mode auto`; em manual, o hook state-sync registra a resposta "aprovado" em AskUserQuestion — **desde que a pergunta nomeie a feature** (o template acima nomeia; se você improvisar sem o nome e houver mais de uma feature na árvore, o hook recusa a gravar e avisa, e você aprova por `morph-spec approve`). O gate fica gravado no `feature.json` autoritativo da feature — nunca via Edit à mão de `state.json`.
 - **Fechar a feature** com `morph-spec finish {feature} --pr|--merge` — um passo só: arquiva commitando `features/{f} → archive/{f}` dentro de `morph/{f}`, integra e desmonta o worktree (se houver). Escolha o modo com `AskUserQuestion` (header `"Integração"`):
   - **Abrir PR** (`--pr`): faz `push` de `morph/{f}` + `gh pr create` com base na default — para review por outro humano/CI antes do merge. Exige `origin` + `gh` autenticado (checados **antes** de arquivar; se faltarem, `finish` recusa sem efeito colateral — caia para `--merge`). A branch é preservada e a sessão fica em `morph/{f}`.
   - **Merge local** (`--merge`): merge `--no-ff` na default **localmente**, sem push — para o fluxo single-user direto. Remove a branch e o worktree.

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-brainstorming
@@ -159,7 +159,7 @@ options:
    **Riscos:** {principal} (sinais detectados: nenhum)
    ```
 
-   No caminho manual, o hook state-sync.js detecta a aprovação automaticamente (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`). Em modo auto sem AskUserQuestion, aprove via `morph-spec approve {feature} proposal --mode auto` (ou `morph-spec advance {feature}` para já criar a pasta 2-plan/) — nunca via Edit à mão de state.json.
+   No caminho manual, o hook state-sync.js detecta a aprovação automaticamente (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`) — **atribuindo pela feature nomeada na pergunta**; sem o nome, e com mais de uma feature na árvore, ele recusa a gravar e avisa (aprove então por `morph-spec approve {feature} proposal`). Em modo auto sem AskUserQuestion, aprove via `morph-spec approve {feature} proposal --mode auto` (ou `morph-spec advance {feature}` para já criar a pasta 2-plan/) — nunca via Edit à mão de state.json.
 
 ## Output esperado
 - `.morph/features/{feature}/0-proposal/proposal.md` — proposta aprovada

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-hotfix
@@ -98,7 +98,13 @@ options:
   - { label: "rollback", description: "Desfazer o fix — voltar ao estado anterior" }
 ```
 
-**NUNCA `morph-spec approve {feature} review --mode auto`** — o CLI recusa explicitamente essa combinação (`src/commands/state/approve.js`: `gateName === 'review' && feature.workType === 'hotfix' && approvedBy === 'auto'` é bloqueado) porque `forcedPauseGates` sobrepõe qualquer trust mode. Em contexto headless (sem `AskUserQuestion` disponível), a resposta textual "aprovado" do usuário é registrada pelo hook `state-sync` como `approvedBy: "manual"` — nunca `"auto"`.
+**NUNCA `morph-spec approve {feature} review --mode auto`** — o CLI recusa explicitamente essa combinação (`src/commands/state/approve.js`: `gateName === 'review' && feature.workType === 'hotfix' && approvedBy === 'auto'` é bloqueado) porque `forcedPauseGates` sobrepõe qualquer trust mode. Em contexto headless (sem `AskUserQuestion` disponível), **o `state-sync` NÃO cobre este caso**: ele é um hook `PostToolUse` com matcher `Write|Edit|AskUserQuestion`, e uma resposta em texto puro do usuário não é tool call — não gera evento e não grava gate nenhum. Esperar por ele deixa o Gate 3 por aprovar em silêncio. O caminho é registrar a aprovação humana explicitamente:
+
+```
+morph-spec approve {feature} review --approver "<nome de quem aprovou>"
+```
+
+`--approver` é a única assinatura que passa pelo backstop em headless — as outras rotas de `resolveApprovedBy` (`--mode auto`, e "sem TTY") resolvem para `"auto"` e são recusadas. Ela é **auto-declarada**: o CLI não consegue verificar que houve um humano, só recusa as assinaturas definitivamente não-humanas. Por isso: **nunca invente o nome** — use `--approver` só quando o humano de fato aprovou, senão o backstop do hotfix vira teatro.
 
 ### 8. Pós-gate (o "test loop → ship" de `MORPH.md` §2.1)
 
@@ -119,7 +125,7 @@ options:
 - `.morph/features/{feature}/2-plan/tasks.json` — T1 (fix) + T2 (verify/regressão)
 - `.morph/features/{feature}/3-implement/recap.md` — evidência real de teste
 - `.morph/features/{feature}/4-review/review-report.md` — diff + evidência, Gate 3 sempre humano
-- Gates `proposal`/`plan` carimbados `approvedBy: "policy:hotfix"`; Gate 3 registrado `approvedBy: "manual"` em `feature.json` (autoritativo) — nunca `"auto"`
+- Gates `proposal`/`plan` carimbados `approvedBy: "policy:hotfix"`; Gate 3 registrado em `feature.json` (autoritativo) com uma **assinatura humana** — `"manual"` pelo `state-sync` (resposta ao `AskUserQuestion`), o nome passado em `--approver`, ou `$USER` num terminal interativo. **Nunca `"auto"`** — é o que o backstop recusa.
 
 ## Referências
 

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-implement

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-plan
@@ -186,7 +186,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    **Tasks:** {N} | Esforço total: {soma} | Caminho crítico: {IDs sem deps paralelas}
    ```
 
-   No caminho manual, o hook state-sync registra a aprovação automaticamente em answers de AskUserQuestion (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`). Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} plan --mode auto` (ou `morph-spec advance {feature}` para já criar a pasta da próxima fase) — nunca via Edit à mão de state.json.
+   No caminho manual, o hook state-sync registra a aprovação automaticamente em answers de AskUserQuestion (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`) — **atribuindo pela feature nomeada na pergunta**; sem o nome, e com mais de uma feature na árvore, ele recusa a gravar e avisa (aprove então por `morph-spec approve {feature} plan`). Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} plan --mode auto` (ou `morph-spec advance {feature}` para já criar a pasta da próxima fase) — nunca via Edit à mão de state.json.
 
 ## Output esperado
 

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-proposal
@@ -96,7 +96,7 @@ Escopo: {incluído} | Excluído: {exclusões}
 Stack: {compliance}
 ```
 
-No caminho manual, o hook `state-sync.js` registra a aprovação automaticamente via PostToolUse quando a `AskUserQuestion` é respondida com "aprovado" (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`). Em `trust: auto` (sem AskUserQuestion), **aprove via CLI — nunca via Edit à mão de state.json**:
+No caminho manual, o hook `state-sync.js` registra a aprovação automaticamente via PostToolUse quando a `AskUserQuestion` é respondida com "aprovado" (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`) — **atribuindo pela feature nomeada na pergunta**; sem o nome, e com mais de uma feature na árvore, ele recusa a gravar e avisa (aprove então por `morph-spec approve {feature} <gate>`). Em `trust: auto` (sem AskUserQuestion), **aprove via CLI — nunca via Edit à mão de state.json**:
 
 ```
 morph-spec approve {feature} proposal --mode auto

package/framework/skills/core/morph-review/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-review
@@ -124,7 +124,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    **Recomendação:** Aprovado
    ```
 
-   No caminho manual, o hook state-sync detecta a aprovação em answers de AskUserQuestion e grava `approvalGates.review = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo da feature. Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} review --mode auto` — nunca via Edit à mão de state.json.
+   No caminho manual, o hook state-sync detecta a aprovação em answers de AskUserQuestion e grava `approvalGates.review = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo da feature — **a atribuição vem do nome da feature na pergunta** (o template acima o carrega). Pergunta sem nome, com mais de uma feature na árvore: o hook recusa a gravar e avisa; aprove então por `morph-spec approve {feature} review`. Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} review --mode auto` — nunca via Edit à mão de state.json.
 
    **Próximo passo (não é desta skill):** com o Gate 3 aprovado, a feature fecha por `morph-spec finish {feature} --pr|--merge` — a `morph-apply` §6 conduz a escolha PR vs merge. Não arquive nem integre aqui.
 

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

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-stack-scan

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.12.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-standards

package/package.json

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

package/src/commands/project/claim.js

@@ -4,19 +4,32 @@
  *
  * Claims are acquired and heartbeaten AUTOMATICALLY (SessionStart hook +
  * telemetry hook), so the operator never has to remember anything. This command
- * exists for the case automation cannot cover: a session that died without
- * releasing, leaving a claim that keeps warning everyone until its TTL expires.
+ * exists for the two cases automation cannot cover:
+ *   - a session that died without releasing, leaving a claim that keeps
+ *     warning everyone until its TTL expires (`--release`);
+ *   - an operator switching this SAME session/tree to a different feature
+ *     mid-task. `morph-spec claim <feature>` (no flags) ACQUIRES it, moving
+ *     the tree's previous claim in the same step — a manual release-then-
+ *     reclaim was observed to just not happen mid-task, and the silent no-op
+ *     this used to be (any unclaimed feature name printed "nothing here" and
+ *     changed nothing) was worse: it looked like a query, not a skipped write.
  *
- * Read-only by default (`--list`); the only mutation is `--release`.
- * Always exits 0 except on a genuine misuse — the claim system is advisory and
- * must never become a source of hard failures.
+ * `--list` forces the read-only view even when a feature is named. `--release`
+ * is the only other mutation. Always exits 0 except on a genuine misuse — the
+ * claim system is advisory and must never become a source of hard failures.
  */
 
 import chalk from 'chalk';
 import { execSync } from 'child_process';
 import { resolve } from 'path';
 import { isGitRepo, resolvePrimaryRoot } from './worktree.js';
-import { listClaims, releaseClaim, claimAge } from '../../../framework/hooks/shared/claim-registry.js';
+import {
+  acquireClaim,
+  foreignClaim,
+  listClaims,
+  releaseClaim,
+  claimAge,
+} from '../../../framework/hooks/shared/claim-registry.js';
 
 /** Resolve the repo's shared git common dir — where claims live. */
 function gitCommonDirOf(cwd) {
@@ -25,6 +38,52 @@ function gitCommonDirOf(cwd) {
   return common ? resolve(root, common) : null;
 }
 
+const norm = (p) => String(p ?? '').replace(/\\/g, '/');
+
+/**
+ * Acquire `feature`'s claim, moving it in the same step if this tree already
+ * holds a live claim on a different feature.
+ *
+ * "This tree's own claim" is identified by PATH, not session id: the CLI has
+ * no access to the Claude Code session id SessionStart stamps (that only
+ * reaches hooks, via stdin JSON) — path is the one honest signal a manual
+ * invocation shares with the automatic claim it may be replacing. Re-using
+ * that claim's session id when re-acquiring keeps the move from reading as a
+ * takeover of a stranger.
+ */
+function acquireOrMove(feature, { cwd, gitCommonDir, json }) {
+  const here = norm(cwd);
+  const previousHere = listClaims(gitCommonDir)
+    .find((c) => c.live && c.feature !== feature && norm(c.path) === here);
+  const takenFrom = foreignClaim(feature, { gitCommonDir, sessionId: previousHere?.sessionId });
+
+  if (previousHere) releaseClaim(previousHere.feature, { gitCommonDir });
+  const identity = previousHere?.sessionId || `cli-${process.pid}`;
+  acquireClaim(feature, { gitCommonDir, sessionId: identity, pid: process.pid, path: cwd });
+
+  if (json) {
+    console.log(JSON.stringify({
+      feature,
+      claimed: true,
+      movedFrom: previousHere?.feature ?? null,
+      tookOverFrom: takenFrom ? { pid: takenFrom.pid, path: takenFrom.path } : null,
+    }));
+    process.exit(0);
+  }
+
+  console.log(previousHere
+    ? chalk.green(`\n✅ Claim movido de "${previousHere.feature}" para "${feature}".\n`)
+    : chalk.green(`\n✅ Claim de "${feature}" adquirido.\n`));
+  if (takenFrom) {
+    console.log(chalk.yellow(
+      `⚠️  "${feature}" tinha claim VIVO de outra sessão (pid ${takenFrom.pid}` +
+      `${takenFrom.path ? ` · ${takenFrom.path}` : ''}, visto há ${claimAge(takenFrom)}) — assumido agora. ` +
+      'Confirme com a outra sessão antes de finish/archive/delete.\n'
+    ));
+  }
+  process.exit(0);
+}
+
 /**
  * @param {string|undefined} feature
  * @param {{ release?: boolean, list?: boolean, json?: boolean, cwd?: string }} [options]
@@ -61,7 +120,17 @@ export function claimCommand(feature, options = {}) {
     process.exit(0);
   }
 
-  // Default and --list are the same read: the whole board, or one feature.
+  // `morph-spec claim <feature>` (no --release, no --list) is the manual
+  // acquire/move half of B1 — automation (SessionStart + heartbeat) covers the
+  // common case; this covers switching this session to a different feature
+  // mid-task without a release-then-reclaim dance. `--list` forces the
+  // read-only view below even when a feature is named.
+  if (feature && !options.list) {
+    acquireOrMove(feature, { cwd, gitCommonDir, json: options.json });
+    return;
+  }
+
+  // No feature (or explicit --list): the read-only board, whole or filtered.
   const all = listClaims(gitCommonDir);
   const rows = feature ? all.filter((c) => c.feature === feature) : all;
 

package/src/commands/state/advance.js

@@ -67,6 +67,34 @@ function missingPhaseArtifacts(phase, featurePath) {
   }
 }
 
+/**
+ * When a required artifact is absent HERE, check whether it exists in the
+ * worktree that owns this feature. `feature.json` travels committed on
+ * `morph/{feature}`, so a feature developed in a worktree has its artifacts
+ * there and only a scaffold in the primary root — running `advance` from the
+ * root then demanded a file that already exists, one directory over.
+ *
+ * Message-only: this never reads state for a decision and never writes across
+ * trees. It replaces a misleading error with an accurate one.
+ *
+ * Fail-open — no git, no worktree, or any error yields null (today's message).
+ *
+ * @returns {Promise<{path: string, branch: string|null, present: string[]}|null>}
+ */
+async function artifactsLiveInWorktree(featureName, missing) {
+  try {
+    const { findWorktreeForFeature } = await import('../project/worktree.js');
+    const wt = findWorktreeForFeature(featureName, process.cwd());
+    if (!wt?.path) return null;
+
+    const base = join(wt.path, '.morph', 'features', featureName);
+    const present = missing.filter((rel) => existsSync(join(base, rel)));
+    return present.length ? { path: wt.path, branch: wt.branch, present } : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Resolve who approved, honestly (mirrors approve.js — no fake human signatures). */
 function resolveApprovedBy(options) {
   if (options.approver) return options.approver;
@@ -104,6 +132,21 @@ export async function advanceCommand(featureName, options = {}) {
     // the defect again.
     const missingArtifacts = missingPhaseArtifacts(phase, featurePath);
     if (missingArtifacts.length && !options.force) {
+      // Divergence, not absence: name the tree that actually holds the work
+      // instead of asking for a file that exists in it.
+      const elsewhere = await artifactsLiveInWorktree(featureName, missingArtifacts);
+      if (elsewhere) {
+        console.error(chalk.red(`\n❌ A fase "${phase}" de "${featureName}" não pode ser encerrada A PARTIR DESTA ÁRVORE.`));
+        console.error(chalk.gray('   Os artefatos não estão ausentes — eles vivem no worktree dono desta feature:'));
+        for (const rel of elsewhere.present) console.error(chalk.gray(`   • ${rel}`));
+        console.error(chalk.gray(`\n   Worktree: ${elsewhere.path}${elsewhere.branch ? ` (branch ${elsewhere.branch})` : ''}`));
+        console.error(chalk.gray('   Rode o comando LÁ — o gate é gravado no feature.json daquela árvore:'));
+        console.error(chalk.cyan(`     cd "${elsewhere.path}" && morph-spec advance ${featureName}`));
+        console.error(chalk.yellow('\n   NÃO use --force aqui: ele carimbaria o gate na cópia da raiz, duplicando'));
+        console.error(chalk.yellow('   uma aprovação que a outra árvore já tem e invertendo a ordem dos gates.\n'));
+        process.exit(1);
+      }
+
       console.error(chalk.red(`\n❌ A fase "${phase}" não pode ser encerrada — artefato(s) obrigatório(s) ausente(s):`));
       for (const rel of missingArtifacts) console.error(chalk.gray(`   • ${rel}`));
       console.error(chalk.gray('\n   Produza o artefato e rode de novo, ou passe --force para avançar assim mesmo.\n'));

package/src/utils/hooks-installer.js

@@ -14,8 +14,16 @@ import { existsSync, chmodSync, readdirSync } from 'fs';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
 
-/** Current hooks schema version — bump when hook definitions change */
-const HOOKS_VERSION = '3.4.0';
+/**
+ * Current hooks schema version — bump when hook definitions change.
+ *
+ * 3.5.0 keeps the same registry entries but changes what the installed hooks
+ * DO: state is now resolved from the target path's working tree instead of the
+ * session's. The hook files are re-copied unconditionally (`copyDirectory`
+ * defaults to `overwrite: true`), so the bump does not gate delivery — it makes
+ * `morph-spec update` report the change honestly instead of "already current".
+ */
+const HOOKS_VERSION = '3.5.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';