@polymorphism-tech/morph-spec 8.12.0 → 8.15.0

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.15.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.15.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.15.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.15.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.15.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.15.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.15.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.15.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.15.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.15.0"
 ---
 
 # morph-review
@@ -45,17 +45,19 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 4. **Despache o avaliador independente** — o score do Gate 3 nunca é auto-atribuído por quem implementou:
    - Rode `morph-spec verify {feature} --json` (escopo feature) e capture o JSON — é a saída real de build+testes+validadores que você anexa ao prompt do avaliador independente (`morph-evaluator`).
    - Gere o **diff da implementação** (`git diff` do range da feature, ou a lista de arquivos do recap.md com seus conteúdos atuais).
-   - Despache o subagent registrado `morph-evaluator` (gerado de `agents.json` — a persona do avaliador é o system prompt dele, com tools read-only), com contexto fresco:
+   - Despache o subagent registrado `morph-evaluator` (gerado de `agents.json` — a persona do avaliador é o system prompt dele, com Read/Glob/Grep + Bash somente para verificação, sem Write/Edit), com contexto fresco:
      ```
      dispatch Agent (subagent_type: "morph-evaluator") with prompt:
        contexto: mandate.md + spec.md + diff da implementação + saída real dos testes
        instrução: |
-         Você NÃO participou da implementação — avalie apenas o que está no diff,
-         contra o mandate. Aplique as rubricas em .morph/framework/evals/rubrics/
-         (architecture 30%, contracts 25%, code-quality 25%, test-coverage 20%)
-         seguindo as bandas 0-10 de cada uma.
+         Você NÃO participou da implementação — avalie o que está no diff,
+         contra o mandate. Você tem Bash: use `morph-spec verify`, testes/build
+         do stack e `git log/diff/show` para conferir por conta própria o que
+         foi reportado, em vez de confiar cegamente. Aplique as rubricas em
+         .morph/framework/evals/rubrics/ (architecture 30%, contracts 25%,
+         code-quality 25%, test-coverage 20%) seguindo as bandas 0-10 de cada uma.
          NÃO reescreva código. NÃO toque em tasks.json, feature.json nem no board
-         de sessão.
+         de sessão — Bash é só para verificação, nunca para mudar estado.
          Contrato do relatório final: GRAVE seu relatório em
          `.morph/features/{feature}/4-review/evaluator-report.md` ANTES de
          encerrar — esse arquivo é o valor de retorno autoritativo desta
@@ -124,7 +126,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.15.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.15.0"
 ---
 
 # morph-standards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.12.0",
+  "version": "8.15.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'));