@polymorphism-tech/morph-spec 8.11.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.11.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.11.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.11.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.11.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.11.0 by Polymorphism Tech*
+*morph-spec v8.14.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -24,8 +24,9 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 **SEMPRE:**
 - 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.
@@ -60,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

@@ -28,6 +28,8 @@ Entre gates, você opera com autonomia total. O dev valida. Você executa.
 
 **Regra de ouro:** Dúvida que não bloqueia o progresso → resolver e registrar. Dúvida que bloqueia → uma pergunta, máximo.
 
+**Escopo da regra de ouro:** ela vale **entre gates** — durante plan, implement e review. Ela **não** vale na abertura de uma feature: a fase proposal pode rodar em **modo entrevista**, em que perguntar até fechar o entendimento é o comportamento desejado, escolhido pelo usuário na pergunta de abertura (`morph-brainstorming` Parte 2). Entrevistar antes de especificar é barato; descobrir o mal-entendido depois do Gate 2 não é.
+
 **Código antes do juiz:** o `morph-spec verify` é a barreira determinística e barata — build, testes e validadores estáticos rodam primeiro, sempre igual, sem custo de tokens. O juiz LLM (morph-eval) só é acionado quando o verify passa. Código é o herói não-celebrado do loop: ele pega o que pega de graça; o juiz gasta tokens só no que o código não consegue ver.
 
 ---
@@ -91,6 +93,8 @@ O fluxo padrão de uma feature tem quatro fases. Cada fase tem uma pasta dedicad
 | implement   | `3-implement/` | Nenhum                | Todas as tasks do tasks.json com status `done`  |
 | review      | `4-review/`    | Gate 3 (trust-aware)  | `review-report.md` aprovado e commitado         |
 
+A fase `proposal` tem dois **modos de descoberta**, escolhidos pelo usuário na abertura (só `workType: feature` e `bug` — `chore`/`hotfix` nascem em `implement`): **entrevista** (uma pergunta por vez até a árvore de decisões abertas zerar; Gate 1 pausa sempre, porque a confirmação do entendimento compartilhado é o gate) e **automático** (até 4 perguntas em lote; Gate 1 trust-aware). Nos dois modos a varredura do ambiente roda **antes** de qualquer pergunta — fato que o `morph-stack-scan` ou o acervo de use cases responde não vira pergunta ao usuário. Detalhes em `morph-brainstorming`.
+
 A fase `1-design/` (design system, mockups, flows) é opcional — aplica-se apenas a features com componentes de UI novos e deve ser explicitamente requisitada pelo usuário.
 
 Não avance de fase sem o gate correspondente ter sido confirmado.
@@ -247,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/commands/morph-proposal.md

@@ -21,10 +21,11 @@ Conduz a feature do request inicial até o Gate 2 (plano aprovado), sem interven
    - Se não existe: criar a estrutura e seguir o passo 2.
 
 2. **Invocar `morph-brainstorming`** (skill em `framework/skills/core/morph-brainstorming/`):
-   - Faz até 4 perguntas de negócio via AskUserQuestion.
-   - Roda Explore subagent para detectar stack e estado do codebase.
+   - Varre o ambiente **antes** de qualquer pergunta (stack, contexto do projeto, acervo de use cases).
+   - Monta a árvore de decisões abertas — só o que a varredura não respondeu.
+   - Abre com a escolha de **modo de descoberta** (entrevista ou automático), recomendando um.
    - Produz `proposal.md` em `.morph/features/{feature-name}/0-proposal/`.
-   - Apresenta o **Gate 1**.
+   - Apresenta o **Gate 1** (que pausa sempre no modo entrevista).
 
 3. **Aguardar aprovação do Gate 1.**
    - Resposta válida: "aprovado", "pode avançar", "lgtm".

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;