@polymorphism-tech/morph-spec 8.11.0 → 8.14.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.11.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.11.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.11.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

@@ -1,10 +1,10 @@
 ---
 name: morph-brainstorming
-description: Entende o negócio, os usuários e a arquitetura antes de qualquer planejamento técnico. Para projetos existentes, detecta desvios de stack e propõe plano de compliance.
+description: Entende o negócio, os usuários e a arquitetura antes de qualquer planejamento técnico. Varre o ambiente primeiro, monta a árvore de decisões abertas e abre com a escolha de modo de descoberta (entrevista uma-pergunta-por-vez ou automático). Para projetos existentes, detecta desvios de stack e propõe plano de compliance.
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "8.11.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-brainstorming
@@ -31,44 +31,72 @@ O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos qu
 
 ## Modo bug-lean (`workType: bug`)
 
-Quando a feature tem `workType: bug` (roteada pela `morph-proposal` — ver MORPH.md §2.1 "Roteamento por tipo de trabalho"), o brainstorming é enxuto: pule as 4 perguntas de negócio da Parte 1 e faça **no máximo 1 pergunta de repro** via `AskUserQuestion` (como reproduzir, em qual ambiente) — só se isso não estiver claro no pedido original. O `stack-scan` (Parte 2) continua rodando normalmente, o diagnóstico precisa do contexto técnico. O `proposal.md` (Parte 3) foca em **Repro / Diagnóstico / Root cause provável / Escopo do fix / Critérios de aceite**, sem as perguntas de negócio completas.
+Quando a feature tem `workType: bug` (roteada pela `morph-proposal` — ver MORPH.md §2.1 "Roteamento por tipo de trabalho"), o brainstorming é enxuto. A varredura (Parte 0) continua rodando normalmente — o diagnóstico precisa do contexto técnico —, mas a árvore da Parte 1 é de **repro, diagnóstico e comportamento do sistema**, não de negócio; em modo automático (Parte 3) isso significa no máximo 1 pergunta de repro, e só se o pedido original não deixar claro. O `proposal.md` (Parte 4) foca em **Repro / Diagnóstico / Root cause provável / Escopo do fix**, sem as seções de negócio completas.
 
 Para `workType: feature` (ou features sem `workType` — compat, ver MORPH.md §2.1), o fluxo completo abaixo permanece integral.
 
 ## O que fazer
 
-### Parte 1 — Entendimento de negócio
+### Parte 0 — Varredura (antes de qualquer pergunta)
 
-1. Faça até 4 perguntas ao usuário via `AskUserQuestion` para entender:
-   - Qual problema de negócio esta feature resolve?
-   - Quem são os usuários afetados e quais são os fluxos críticos deles?
-   - Qual é o critério de sucesso — como saberemos que a feature está pronta?
-   - Há integrações externas, dependências de outras features ou restrições de prazo?
+Fato não se pergunta. Antes de levar a primeira pergunta ao usuário, levante o que o ambiente já responde:
 
-   Se as respostas forem claras e suficientes, siga para a Parte 2 sem perguntas adicionais.
-
-### Parte 2 — Detecção de contexto (greenfield vs brownfield)
-
-2. Invoque `Skill(morph-stack-scan)` para detectar contexto. A skill:
+1. Invoque `Skill(morph-stack-scan)`. A skill:
    - Curto-circuita em projetos greenfield (sem source files) — retorna relatório vazio.
    - Em brownfield, varre stack atual (.csproj, package.json, migrations), padrões (Guid.NewGuid vs Guid.CreateVersion7, sealed, result pattern), features existentes.
    - Produz `.morph/features/{feature}/0-proposal/stack-scan.md`.
 
-3. Reconciliação de design-system (se aplicável):
-   - Comparar `.morph/context/design-system.md` (se existir) com o que foi detectado no stack-scan e com bundles/mocks recentes do usuário.
-   - Se houver **divergência** (tokens diferentes, framework version mismatch, fonte aprovada distinta):
-     - Marcar `signals.designSystemDivergence = true` no contexto da feature.
-     - Perguntar ao usuário via `AskUserQuestion` qual fonte usar, listando as fontes detectadas como options.
-     - Atualizar `.morph/context/design-system.md` com a fonte escolhida + entrada de changelog (data, motivo).
+2. Leia o contexto que já existe no projeto: `.morph/context/` (se existir), `.morph/config/config.json` (stack, integrations, trust), as features ativas em `.morph/features/` e o **acervo de use cases** em `.morph/specs/usecases/`. O comportamento já implementado é o contexto mais barato que existe — e é ele que evita perguntar o que o sistema já responde.
+
+3. Reconciliação de design-system (se aplicável): comparar `.morph/context/design-system.md` (se existir) com o que foi detectado no stack-scan e com bundles/mocks recentes do usuário. Se houver **divergência** (tokens diferentes, framework version mismatch, fonte aprovada distinta), marque `signals.designSystemDivergence = true` — a escolha da fonte vira uma **decisão da árvore** (Parte 1), não uma pergunta solta. Resolvida, atualize `.morph/context/design-system.md` com a fonte escolhida + entrada de changelog (data, motivo).
+
+4. Desvio de stack detectado: gere `migration-plan.md` em `.morph/features/{feature}/0-proposal/`. "A migração entra nesta feature ou vira feature separada?" também é decisão da árvore.
+
+### Parte 1 — Árvore de decisões abertas
+
+Enumere **só o que a varredura não respondeu**. Uma decisão entra na árvore quando (a) muda o escopo, o comportamento ou a arquitetura da feature, e (b) o ambiente não a resolve.
+
+Ordene por dependência: decisão que **poda** outras vem primeiro. "O fluxo é síncrono ou assíncrono?" antecede "qual é a política de retry" — a primeira resposta pode eliminar a segunda inteira.
+
+Publique a **árvore de decisões** ao usuário antes de perguntar qualquer coisa. Ela é o sinal de progresso da entrevista e a base da recomendação de modo na Parte 2.
+
+### Parte 2 — Pergunta de abertura (modo de descoberta)
+
+Aplica-se a `workType: feature` e `bug`. **`chore` e `hotfix` não passam por aqui** — nascem com os Gates 1 e 2 carimbados `policy:{tipo}` e começam direto em `implement`.
 
-4. Com base no relatório:
-   - **Greenfield:** seguir para a Parte 3.
-   - **Stack padrão:** seguir para a Parte 3.
-   - **Desvio de stack:** gerar `migration-plan.md` em `.morph/features/{feature}/0-proposal/`. Perguntar via `AskUserQuestion`: "A migração de stack deve ser incluída nesta feature ou tratada numa feature separada?" Registrar decisão e seguir.
+Faça **uma** `AskUserQuestion` apresentando a árvore e recomendando um modo. A recomendação sai do tamanho e do acoplamento da árvore: muitas decisões abertas, ou decisões que dependem umas das outras → recomende **entrevista**; árvore rasa ou já respondida pela varredura → recomende **automático**. A opção recomendada vai em primeiro lugar, com o sufixo `(Recomendado)` no label.
 
-### Parte 3 — Produção do proposal.md
+```
+question: "Antes de começar {feature}: entrevista ou automático? Encontrei {n} decisões abertas: {resumo da árvore}"
+header: "Descoberta"
+options:
+  - { label: "{modo recomendado} (Recomendado)", description: "{por que a árvore recomenda este modo}" }
+  - { label: "{o outro modo}", description: "{o que muda na prática}" }
+```
 
-4. Produza `proposal.md` em `.morph/features/{feature}/0-proposal/` com:
+### Parte 3 — Entendimento
+
+**Modo entrevista.** Percorra a árvore, **uma pergunta por chamada** de `AskUserQuestion` — perguntas em lote desorientam e impedem que uma resposta pode ramos. Regras:
+
+- Toda pergunta traz **resposta recomendada**, como primeira opção, marcada `(Recomendado)`.
+- Cada resposta risca, poda ou abre ramos; mostre a árvore atualizada quando ela mudar de forma.
+- Fato descoberto no ambiente nunca vira pergunta. As **decisões** são do usuário; os **fatos** são seus.
+- Termina quando a árvore zera. Então apresente o **entendimento compartilhado** (problema, escopo com exclusões, usuários e fluxos, riscos) — a confirmação dele é o Gate 1, que **pausa sempre** neste modo.
+- O usuário pode encerrar a entrevista a qualquer momento; o que ficou aberto vira exclusão explícita de escopo no `proposal.md`.
+
+**Modo automático.** Até 4 perguntas via `AskUserQuestion` cobrindo o que a árvore deixou aberto:
+   - Qual problema de negócio esta feature resolve?
+   - Quem são os usuários afetados e quais são os fluxos críticos deles?
+   - Qual é o critério de sucesso — como saberemos que a feature está pronta?
+   - Há integrações externas, dependências de outras features ou restrições de prazo?
+
+   Árvore vazia → nenhuma pergunta. O Gate 1 segue trust-aware (regras do MORPH.md §5).
+
+**Em `workType: bug`**, a árvore é de **repro, diagnóstico e comportamento do sistema** — não de negócio. Em modo automático vale o bug-lean: no máximo 1 pergunta de repro, e só se o pedido original não deixar claro.
+
+### Parte 4 — Produção do proposal.md
+
+1. Produza `proposal.md` em `.morph/features/{feature}/0-proposal/` com:
    - **Problema:** o que está sendo resolvido e para quem (máx. 2 parágrafos)
    - **Escopo:** o que está incluído e o que está explicitamente excluído
    - **Usuários e fluxos críticos:** quem usa e qual é o caminho principal
@@ -82,21 +110,28 @@ Para `workType: feature` (ou features sem `workType` — compat, ver MORPH.md §
 
    Um bom proposal.md tem no máximo 2 páginas. Se está crescendo além disso, o escopo precisa ser cortado.
 
-5. Apresente o Gate 1 segundo trust mode.
+2. Apresente o Gate 1 segundo o modo de descoberta e o trust mode.
 
    Ler `.morph/config/config.json → trust` (default `"auto"`). Calcular os sinais de risco em linguagem natural — sem scripts:
 
-   - `designSystemDivergence` = detectado no passo 3 (fontes de design conflitantes).
+   - `discoveryMode` = `"interview"` ou `"auto"`, conforme a resposta da Parte 2.
+   - `designSystemDivergence` = detectado na Parte 0 (fontes de design conflitantes).
    - `standardsViolations` = lista de violações detectadas.
 
-   **Decisão de pausa** (regras da tabela do MORPH.md §5): `trust: manual` → pausa sempre; `designSystemDivergence` → pausa; `standardsViolations` não-vazio → pausa; caso contrário → auto-passa (`pause: false`). Monte `reason` com o sinal que disparou.
+   **Decisão de pausa** (regras da tabela do MORPH.md §5): **modo entrevista → pausa sempre** ("não aja até eu confirmar" é literalmente o Gate 1: a confirmação do entendimento compartilhado é o gate); `trust: manual` → pausa sempre; `designSystemDivergence` → pausa; `standardsViolations` não-vazio → pausa; caso contrário → auto-passa (`pause: false`). Monte `reason` com o sinal que disparou.
 
    **Persista a decisão ANTES de apresentar ou auto-aprovar — via CLI, nunca editando feature.json à mão** (o Edit manual colide com o hook state-sync, que reescreve o arquivo entre o seu Read e o Edit — erro "file modified since read"):
 
    ```
-   morph-spec gate-decision {feature} proposal --pause false --reason "nenhum sinal de risco" --signals '{"designSystemDivergence":false,"standardsViolations":[]}'
+   # modo entrevista — o gate pausa sempre
+   morph-spec gate-decision {feature} proposal --pause true --reason "modo entrevista — entendimento compartilhado confirmado pelo usuário" --signals '{"discoveryMode":"interview","designSystemDivergence":false,"standardsViolations":[]}'
+
+   # modo automático, sem sinais de risco
+   morph-spec gate-decision {feature} proposal --pause false --reason "nenhum sinal de risco" --signals '{"discoveryMode":"auto","designSystemDivergence":false,"standardsViolations":[]}'
    ```
 
+   `signals` é free-form no `feature.schema.json` — `discoveryMode` não exige mudança de schema, e deixa o modo escolhido auditável no `feature.json` commitado.
+
    O comando grava `gateDecisions.proposal = { pause, reason, signals, trust, decidedAt }` no `feature.json` autoritativo com timestamp server-side (shape canônico em `.morph/framework/schemas/feature.schema.json`). O hook `gate-guard.js` confere depois se a ação (pausar vs auto-aprovar) bateu com esta decisão e avisa em divergência. Sem o registro o guard não verifica — não pule.
 
    **Se `pause === true`** (manual mode OU risco detectado em auto), use `AskUserQuestion`:
@@ -124,7 +159,7 @@ Para `workType: feature` (ou features sem `workType` — compat, ver MORPH.md §
    **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
@@ -134,5 +169,5 @@ Para `workType: feature` (ou features sem `workType` — compat, ver MORPH.md §
 ## Referências
 - `.morph/framework/MORPH.md` — seções 1 (Papéis), 2 (Fases), 5 (Gates), Trust Mode
 - `.morph/framework/standards/STANDARDS.json` — para referência de standards relevantes à stack
-- `framework/skills/core/morph-stack-scan/SKILL.md` — invocada na Parte 2
+- `framework/skills/core/morph-stack-scan/SKILL.md` — invocada na Parte 0 (varredura), antes de qualquer pergunta
 - `.morph/framework/MORPH.md` §5 — regras de pausa do Gate 1 (trust mode)

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.11.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.11.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.11.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.11.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.11.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-proposal
@@ -47,7 +47,7 @@ morph-spec create {feature-name} --request "<pedido do usuário>"
 
 - **`hotfix`** → invoque `Skill(morph-hotfix)` passando `{feature-name}` e **ENCERRE** — não siga o restante deste fluxo. A skill cuida de scout, brief, fix cirúrgico, test loop e Gate 3 (sempre humano).
 - **`chore`** → fast-track: os Gates 1 e 2 já nasceram carimbados `policy:chore` no `create`. Escreva um `2-plan/tasks.json` mínimo (1-3 tasks) e invoque `Skill(morph-apply)` diretamente — **exceção documentada** à regra do passo 7 ("não despachar `morph-apply` automaticamente"): não pausar numa mudança óbvia é exatamente o valor do fast-track.
-- **`bug`** → siga para `Skill(morph-brainstorming)` em modo **bug-lean**: produz um `proposal.md` enxuto (repro / diagnóstico / root cause / escopo / critério de aceite — não a proposta completa de uma feature nova) e depois um plano enxuto via `Skill(morph-plan)`. Gates 1 e 2 continuam trust-aware (passos 3 e 6) — só o conteúdo dos artefatos é mais curto.
+- **`bug`** → siga para `Skill(morph-brainstorming)` em modo **bug-lean**: produz um `proposal.md` enxuto (repro / diagnóstico / root cause / escopo do fix — não a proposta completa de uma feature nova; **sem critérios de aceite**, que moram na pós-condição do use case) e depois um plano enxuto via `Skill(morph-plan)`. Gates 1 e 2 continuam trust-aware (passos 3 e 6) — só o conteúdo dos artefatos é mais curto.
 - **`feature`** (default — inclui features criadas antes do v8 sem `workType`) → siga o fluxo completo abaixo (passos 1-7): brainstorming → Gate 1 → plan → Gate 2.
 
 ### 1. Determinar feature name e estado
@@ -59,20 +59,19 @@ morph-spec create {feature-name} --request "<pedido do usuário>"
 
 ### 2. Invocar `Skill(morph-brainstorming)`
 
-Passa o nome da feature. A skill:
-- Faz até 4 perguntas de negócio via `AskUserQuestion`.
-- Invoca `Skill(morph-stack-scan)` para detectar contexto (greenfield curto-circuita).
-- Detecta divergência entre fontes de design-system e marca `signals.designSystemDivergence`.
-- Produz `proposal.md` em `.morph/features/{feature}/0-proposal/`.
+Passa o nome da feature. A skill é a **dona da fase de entendimento** — não re-descreva o comportamento dela aqui. Em resumo: varre o ambiente antes de perguntar qualquer coisa (`Skill(morph-stack-scan)` + contexto do projeto + acervo de use cases), monta a **árvore de decisões abertas**, abre com a escolha de **modo de descoberta** (entrevista ou automático — só `feature` e `bug`), detecta divergência entre fontes de design-system (`signals.designSystemDivergence`) e produz `proposal.md` em `.morph/features/{feature}/0-proposal/`. Detalhes em `framework/skills/core/morph-brainstorming/SKILL.md`.
+
+No **modo entrevista** o Gate 1 pausa sempre — a confirmação do entendimento compartilhado é o gate. O modo escolhido chega ao passo 3 em `gateDecisions.proposal.signals.discoveryMode`.
 
 ### 3. Gate 1 (trust-aware)
 
 Ler `.morph/config/config.json → trust` (default `"auto"`). Calcular sinais de risco:
 
+- `discoveryMode` — `"interview"` ou `"auto"`, decidido na pergunta de abertura da morph-brainstorming.
 - `designSystemDivergence` — detectado pela morph-brainstorming.
 - `standardsViolations` — violações de mandate listadas na proposal (não deveria, mas verifica).
 
-**Decisão de pausa** (regras da tabela do MORPH.md §5, aplicadas em linguagem natural — sem scripts): `trust: manual` → `pause: true` sempre; `designSystemDivergence` → pausa; `standardsViolations` não-vazio → pausa; caso contrário → `pause: false` (auto-passa). Monte `reason` com o sinal que disparou.
+**Decisão de pausa** (regras da tabela do MORPH.md §5, aplicadas em linguagem natural — sem scripts): `discoveryMode: "interview"` → `pause: true` sempre; `trust: manual` → `pause: true` sempre; `designSystemDivergence` → pausa; `standardsViolations` não-vazio → pausa; caso contrário → `pause: false` (auto-passa). Monte `reason` com o sinal que disparou.
 
 **Se `pause === true`**, apresentar via `AskUserQuestion`:
 
@@ -97,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.11.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.11.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.11.0"
+cliVersion: "8.14.0"
 ---
 
 # morph-standards

package/package.json

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