@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

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

@@ -1,189 +1,20 @@
 #!/usr/bin/env node
 
-/**
- * PreToolUse Hook: Protect Approved Spec Files
- *
- * Event: PreToolUse | Matcher: Write|Edit
- *
- * Blocks Write/Edit to spec artifacts after their approval gate has passed:
- *   - 2-plan/spec.md, etc. → blocked if 'plan' gate approved
- *   - 1-design/design-system.md, etc. → blocked if 'uiux' gate approved
- *
- * Semantic exception for files in MUTABLE_SPEC_FIELDS (e.g. tasks.json):
- * the plan contract is frozen, but per-task progress fields (status, outputs,
- * notes) may still change during the implement phase. For those files BOTH a
- * full Write and a targeted Edit are allowed — but only when the semantic diff
- * touches solely the mutable fields. The Edit is simulated (old_string →
- * new_string applied to the current file) and diffed exactly like a Write, so a
- * one-field status flip via Edit is permitted while any change to the frozen
- * plan contract (titles, dependencies, doneCriteria, the task set) is blocked.
- * This is the sanctioned progress path — the agent never has to rewrite the
- * whole file nor reach for a Node script to record task status.
- *
- * A gate freezes the APPROVED ARTIFACT, so a protected file that does not yet
- * exist on disk is a CREATION and passes — the criterion is the file's
- * existence, never who signed the gate (see the carve-out in run()).
- *
- * Fail-open: exits 0 on any error.
- */
-
 import { existsSync, readFileSync } from 'fs';
 import { stateExists, isGateApproved } from '../../shared/state-reader.js';
 import {
   isFeaturePath,
   extractFeatureName,
   getBasename,
-  PROTECTED_SPEC_FILES,
-  MUTABLE_SPEC_FIELDS
+  PROTECTED_SPEC_FILES
 } from '../../shared/phase-utils.js';
 import { blockResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { getFilePath, getToolName, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
-import { validateTasksDoc, outputsDivergenceViolations } from '../../shared/tasks-validator.js';
-
-/**
- * Compare two tasks.json structures and return the list of plan-contract
- * violations — changes that touch anything other than the mutable fields.
- *
- * Frozen-by-default, not an enumerated frozen list: the loop below walks the
- * UNION of old/new task keys and flags any key not in `mutableFields`. A new
- * plan-contract field (e.g. `agent`/`standards`, stamped by morph-plan — R2
- * token-cut) needs NO entry added here to become protected; it is frozen the
- * moment it exists on a task, simply by never being added to
- * MUTABLE_SPEC_FIELDS (output-schema.js → `npm run generate` →
- * framework/hooks/shared/phase-utils.js). Only fields that must stay
- * EDITABLE post-Gate-2 (today: status, outputs, notes) belong in that list.
- *
- * @param {object} oldDoc - parsed previous file content
- * @param {object} newDoc - parsed proposed file content
- * @param {string[]} mutableFields - field names allowed to change
- * @returns {string[]} human-readable violation messages (empty = OK)
- */
-function diffPlanContract(oldDoc, newDoc, mutableFields) {
-  const violations = [];
-  const mutable = new Set(mutableFields);
-
-  // Backfilling a previously-absent `version` (undefined → any value) is a
-  // benign schema-tooling update, not a plan-contract change — it's what
-  // lets legacy tasks.json adopt the field so `morph-spec dag` can analyze
-  // it without a lenient fallback. An actual change between two SET
-  // versions is still a real contract change and stays blocked.
-  const versionBackfilled = oldDoc.version === undefined && newDoc.version !== undefined;
-  if (!versionBackfilled && oldDoc.version !== newDoc.version) {
-    violations.push(`'version' changed (${oldDoc.version} → ${newDoc.version})`);
-  }
-  if (oldDoc.feature !== newDoc.feature) {
-    violations.push(`'feature' changed (${oldDoc.feature} → ${newDoc.feature})`);
-  }
-
-  const oldTasks = Array.isArray(oldDoc.tasks) ? oldDoc.tasks : [];
-  const newTasks = Array.isArray(newDoc.tasks) ? newDoc.tasks : [];
-
-  if (oldTasks.length !== newTasks.length) {
-    violations.push(`task count changed (${oldTasks.length} → ${newTasks.length}) — tasks cannot be added or removed`);
-  }
-
-  const oldById = new Map(oldTasks.map(t => [t.id, t]));
-  const newById = new Map(newTasks.map(t => [t.id, t]));
-
-  // A task present before must still exist (no removals / id renames).
-  for (const id of oldById.keys()) {
-    if (!newById.has(id)) violations.push(`task '${id}' was removed`);
-  }
-  for (const id of newById.keys()) {
-    if (!oldById.has(id)) violations.push(`task '${id}' was added`);
-  }
+import { ERRATA_HEADING, errataViolation } from '../../shared/errata.js';
 
-  // For tasks present on both sides, only mutable fields may differ.
-  for (const [id, newTask] of newById) {
-    const oldTask = oldById.get(id);
-    if (!oldTask) continue;
-    const keys = new Set([...Object.keys(oldTask), ...Object.keys(newTask)]);
-    for (const key of keys) {
-      if (mutable.has(key)) continue;
-      if (JSON.stringify(oldTask[key]) !== JSON.stringify(newTask[key])) {
-        violations.push(`task '${id}': immutable field '${key}' changed`);
-      }
-    }
-  }
-
-  return violations;
-}
-
-/**
- * O heading que abre o bloco de errata, no fim de um arquivo congelado.
- *
- * Congelar o CONTRATO não é a mesma coisa que congelar um ERRO DE FATO. Caso
- * real: a spec afirmava, entre parênteses, que certos registros também eram
- * escritos por humanos; o código mostrava que os três escritores eram do
- * próprio motor. A afirmação era falsa sobre o código, não uma mudança de
- * escopo — mas a trava cega não distingue as duas coisas, então a mentira
- * ficava na spec e a correção morava em outro arquivo. Quem abrisse a spec
- * primeiro lia a versão errada.
- *
- * A errata resolve isso SEM abrir o contrato: o corpo continua byte-idêntico e
- * só se acrescenta texto ao fim, num bloco identificado. Escopo negociado ⇒
- * revogar o gate. Fato errado sobre o código ⇒ errata.
- */
-const ERRATA_HEADING = '## Errata';
-
-/** Índice onde começa o bloco de errata (-1 se não há). Só reconhece o heading em início de linha. */
-function errataIndex(text) {
-  if (text.startsWith(ERRATA_HEADING)) return 0;
-  const at = text.indexOf(`\n${ERRATA_HEADING}`);
-  return at === -1 ? -1 : at + 1;
-}
-
-/**
- * Corpo congelado = tudo ANTES do bloco de errata (ou o texto inteiro, se não
- * há bloco), sem o branco final.
- *
- * O `trimEnd` não é frouxidão: separar o bloco por uma linha em branco é o
- * formato markdown natural, e sem isso a primeira errata de todas seria
- * recusada por "mudou o corpo" — quando o que mudou foi um `\n` de formatação.
- * A garantia que importa (nenhum caractere SIGNIFICATIVO do texto aprovado
- * muda) fica intacta, porque só espaço em branco terminal é ignorado.
- */
-function frozenBody(text) {
-  const at = errataIndex(text);
-  return (at === -1 ? text : text.slice(0, at)).trimEnd();
-}
-
-/**
- * A mudança proposta é uma errata legítima?
- *
- * Três condições, todas necessárias — frouxo em qualquer uma delas e a trava
- * cega vira uma trava que uma edição criativa atravessa:
- *   1. o corpo congelado permanece BYTE-IDÊNTICO;
- *   2. o resultado de fato tem um bloco `## Errata` (senão é edição do corpo);
- *   3. a errata só CRESCE — o que já estava escrito nela não é reescrito.
- *
- * A (3) existe porque uma errata reescrita perde a serventia: o valor dela é
- * ser trilha acumulada, não um segundo lugar editável.
- *
- * @returns {{ok: true} | {ok: false, why: string}}
- */
-function errataViolation(original, proposed) {
-  if (frozenBody(proposed) !== frozenBody(original)) {
-    return { ok: false, why: 'o corpo da spec mudou — errata só ACRESCENTA ao fim, nunca altera o texto aprovado' };
-  }
-  if (errataIndex(proposed) === -1) {
-    return { ok: false, why: `o conteúdo novo precisa estar sob um bloco \`${ERRATA_HEADING}\` no fim do arquivo` };
-  }
-  const oldAt = errataIndex(original);
-  if (oldAt !== -1) {
-    const oldErrata = original.slice(oldAt);
-    if (!proposed.slice(errataIndex(proposed)).startsWith(oldErrata)) {
-      return { ok: false, why: 'a errata existente foi reescrita — ela é append-only, entradas anteriores não se apagam' };
-    }
-  }
-  return { ok: true };
-}
+const CHECKS_FILE = 'checks.json';
 
-/**
- * Texto proposto para um arquivo totalmente travado, a partir de Write ou Edit.
- * @returns {string|null} null quando o payload não permite reconstruir (fail-open).
- */
 function proposedText(payload, toolName, original) {
   if (toolName === 'Edit') {
     const oldStr = payload?.tool_input?.old_string;
@@ -197,14 +28,8 @@ function proposedText(payload, toolName, original) {
   return typeof content === 'string' ? content : null;
 }
 
-/**
- * @param {object} payload - parsed PreToolUse stdin payload
- * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
- *   Never prints, never exits — see runStandalone()/chain.js at the bottom.
- */
 export async function run(payload) {
   try {
-    // Amend mode: bypass spec protection for legitimate in-implementation corrections
     if (process.env.MORPH_AMEND_PHASE) {
       console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
       return null;
@@ -215,14 +40,9 @@ export async function run(payload) {
     const filePath = getFilePath(payload);
     if (!filePath) return null;
 
-    // Only check files inside .morph/features/
     if (!isFeaturePath(filePath)) return null;
 
-    // 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.
+    // The gate lives in the feature.json of the tree that OWNS the file: asking the session's tree left this guard dark in a worktree.
     const root = resolveMorphRoot(filePath, process.cwd());
     if (!stateExists(root)) return null;
 
@@ -232,133 +52,42 @@ export async function run(payload) {
     const filename = getBasename(filePath);
     const requiredGate = PROTECTED_SPEC_FILES[filename];
 
-    // Not a protected file
     if (!requiredGate) return null;
 
-    // Gate not yet approved — allow editing
+    // Generated only by the CLI: a hand-written one would carry checks the parser never judged.
+    // Decided before the creation carve-out, since chore/hotfix are born with the plan gate stamped.
+    if (filename === CHECKS_FILE) {
+      logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
+      return blockResult(
+        `MORPH-SPEC: '${CHECKS_FILE}' is generated — never written by hand.\n` +
+        `Edit 2-plan/plan.md and run \`morph-spec plan-check ${featureName}\`: it parses the plan and writes ${CHECKS_FILE}.\n` +
+        `After the plan gate the plan is frozen: a wrong fact goes in \`${ERRATA_HEADING}\` (append-only, ${CHECKS_FILE} unchanged);\n` +
+        `a real scope change needs \`morph-spec unapprove ${featureName} plan\`, then plan-check and the gate again.`
+      );
+    }
+
     if (!isGateApproved(featureName, requiredGate, root)) {
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
       return null;
     }
 
-    // ── Gate approved — file is locked ──────────────────────────────────────
     const absPath = resolveTargetPath(filePath, root);
 
-    // Um gate aprovado congela o ARTEFATO APROVADO. Se o arquivo ainda não
-    // existe no disco, não há artefato aprovado a proteger: isto é a CRIAÇÃO
-    // inicial, não a edição de uma spec fechada. O caso é real e não é raro —
-    // `chore`/`hotfix` nascem com `proposal`+`plan` carimbados `policy:{tipo}`
-    // (create.js → work-types.js skippedGates), então o primeiro `Write` de
-    // `2-plan/spec.md` já chega aqui com o gate "aprovado" sem que humano
-    // nenhum tenha aprovado coisa alguma — e era barrado com uma mensagem
-    // mandando revogar o gate de um arquivo inexistente.
-    //
-    // O critério é a EXISTÊNCIA, nunca o `approvedBy`. Liberar por assinatura
-    // (`policy:` passa, `lucas` não) transformaria este carve-out em licença
-    // para reescrever qualquer spec aprovada: bastaria apagá-la antes. Por ser
-    // sobre o disco, a janela fecha sozinha no instante em que o arquivo
-    // existe — os contra-canários de test/hooks/protect-spec-files.test.js
-    // pinam exatamente isso.
-    //
-    // A decisão é explícita e vale para as DUAS metades do hook. Antes, o ramo
-    // de campos mutáveis (tasks.json) já deixava a primeira criação passar, mas
-    // por acidente — o ENOENT caía no catch fail-open da leitura — enquanto o
-    // ramo travado bloqueava. Duas metades respondendo à mesma pergunta em
-    // direções opostas; agora respondem aqui, uma vez só. O `result` distinto
-    // no log é o que torna essa unificação observável.
+    // A file not yet on disk is its CREATION (chore/hotfix are born with `plan` stamped), not an edit of a frozen spec.
+    // The criterion is existence, never `approvedBy`: by signature, deleting a spec first would license rewriting it.
     if (!existsSync(absPath)) {
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok:absent');
       return null;
     }
 
-    const mutableFields = MUTABLE_SPEC_FIELDS[filename];
-
-    // Files with mutable progress fields (e.g. tasks.json): allow a full Write
-    // that touches only those fields. Anything else stays blocked.
-    if (mutableFields) {
-      const toolName = getToolName(payload);
-
-      // 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. O arquivo
-      // EXISTE aqui (a inexistência já foi decidida acima), então este catch
-      // volta a significar só o que dizia originalmente: não deu para diffar.
-      let oldDoc, newDoc;
-      try {
-        const original = readFileSync(absPath, 'utf-8');
-        oldDoc = JSON.parse(original);
-
-        if (toolName === 'Edit') {
-          // Simulate the edit: apply old_string → new_string to the current file.
-          const oldStr = payload?.tool_input?.old_string;
-          const newStr = payload?.tool_input?.new_string;
-          if (typeof oldStr !== 'string' || typeof newStr !== 'string') throw new Error('no edit strings');
-          const edited = payload?.tool_input?.replace_all
-            ? original.split(oldStr).join(newStr)
-            : original.replace(oldStr, newStr);
-          newDoc = JSON.parse(edited);
-        } else {
-          const newContent = payload?.tool_input?.content;
-          if (typeof newContent !== 'string') throw new Error('no content');
-          newDoc = JSON.parse(newContent);
-        }
-      } catch {
-        logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
-        return null;
-      }
-
-      const violations = diffPlanContract(oldDoc, newDoc, mutableFields);
-
-      // Schema check on the proposed doc: even mutable-field writes must keep a
-      // valid status enum (a leaf agent writing status:"completed" was the
-      // production failure this closes). Only NEWLY introduced schema errors
-      // block — a pre-existing violation must not deadlock progress writes.
-      const preExisting = new Set(validateTasksDoc(oldDoc).errors);
-      violations.push(...validateTasksDoc(newDoc).errors.filter(e => !preExisting.has(e)));
-
-      // Planned-vs-real outputs diff: changing `outputs` is allowed, but the
-      // divergence must be explained in `notes` in the same edit.
-      violations.push(...outputsDivergenceViolations(oldDoc, newDoc));
-
-      if (violations.length === 0) {
-        // Only mutable progress fields changed — a legitimate implement-phase
-        // update via Write OR Edit.
-        logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
-        return null;
-      }
-
-      logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
-      return blockResult(
-        `MORPH-SPEC: '${filename}' write rejected — the '${requiredGate}' gate has been approved.\n` +
-        `This ${toolName} violates the plan contract or the tasks schema:\n` +
-        violations.map(v => `  • ${v}`).join('\n') + '\n\n' +
-        `During the implement phase only these fields may change: ${mutableFields.join(', ')}\n` +
-        `(status must stay in the schema enum, and outputs that diverge from the plan\n` +
-        `require an explanatory 'notes' in the same edit).\n` +
-        `To change the plan itself, ask the user to revoke the '${requiredGate}' gate,\n` +
-        `then re-present it for approval.`
-      );
-    }
-
-    // ── Arquivo totalmente travado (spec.md, design) ────────────
-    // O corpo continua congelado. A ÚNICA passagem é a errata append-only:
-    // corpo byte-idêntico + texto novo sob `## Errata` no fim. Qualquer falha
-    // de leitura/reconstrução cai no bloqueio (o conservador aqui é BLOQUEAR —
-    // ao contrário do ramo do tasks.json, onde não conseguir diffar significa
-    // não ter como provar violação; aqui a regra base é "não se edita").
-    //
-    // O arquivo EXISTE neste ponto — a inexistência foi decidida lá em cima, e
-    // é a única coisa que este catch NÃO significa mais. ENOENT tratado como
-    // "ilegível" era o defeito F14; "ilegível de verdade" continua bloqueando.
+    // The only way through is the append-only errata; any read or rebuild failure falls into the block.
     const toolName = getToolName(payload);
     let errataCheck = null;
     try {
       const original = readFileSync(absPath, 'utf-8');
       const proposed = proposedText(payload, toolName, original);
       if (proposed !== null) errataCheck = errataViolation(original, proposed);
-    } catch {
-      // arquivo ilegível → sem errata possível, segue para o bloqueio
-    }
+    } catch {}
 
     if (errataCheck?.ok) {
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
@@ -368,16 +97,15 @@ export async function run(payload) {
     logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
     return blockResult(
       `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
-      `Editing approved specs breaks the spec contract.\n\n` +
+      `Editing an approved artifact breaks its contract.\n\n` +
       (errataCheck ? `Esta mudança não é uma errata válida: ${errataCheck.why}.\n\n` : '') +
-      `Corrigir um FATO ERRADO sobre o código (a spec afirma algo que o código\n` +
-      `desmente) não exige revogar o gate: acrescente um bloco \`${ERRATA_HEADING}\` no\n` +
+      `Corrigir um FATO ERRADO sobre o código (o texto aprovado afirma algo que o\n` +
+      `código desmente) não exige revogar o gate: acrescente sob \`${ERRATA_HEADING}\` no\n` +
       `FIM do arquivo, deixando o corpo intacto — é append-only e fica na trilha.\n\n` +
-      `Mudar o ESCOPO acordado é outra coisa: peça ao usuário para revogar o gate\n` +
-      `'${requiredGate}', edite, e re-apresente o gate para aprovação.`
+      `Mudar o ESCOPO acordado é outra coisa: \`morph-spec unapprove ${featureName} ${requiredGate}\`,\n` +
+      `edite, rode plan-check quando for o plan.md, e re-apresente o gate para aprovação.`
     );
   } catch {
-    // Fail-open
     return null;
   }
 }

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

@@ -1,15 +1,4 @@
 #!/usr/bin/env node
-/**
- * state-sync.js — PostToolUse hook
- *
- * Keeps .morph/state.json in sync with the agent's actions, without requiring
- * the agent to think about state. Fail-open: any error returns {} silently.
- *
- * Triggers:
- *  - Write/Edit of .morph/features/{feature}/0-proposal/proposal.md  → register feature
- *  - Write/Edit of .morph/features/{feature}/{phase}/{output}        → mark output created
- *  - AskUserQuestion answered with option starting "aprovado"        → advance gate
- */
 
 import { existsSync } from 'fs';
 import { join } from 'path';
@@ -17,6 +6,7 @@ import { loadState, stateExists } from '../../shared/state-reader.js';
 import { persistFeature, setGateApproved, createDefaultFeature, readFeatureFile } from '../../shared/state-writer.js';
 import { resolveMorphRoot } from '../../shared/payload-utils.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
+import { gateFromQuestion } from '../../shared/gate-question.js';
 import {
   locateFeatureForQuestion,
   allWorkTrees,
@@ -25,9 +15,8 @@ import {
 } from '../../shared/feature-locator.js';
 
 const PHASE_FOLDERS = {
-  '0-proposal': 'proposal',
   '1-design': 'design',
-  '1-ui': 'uiux', // legacy alias — still recognized during folder transition
+  '1-ui': 'uiux', // legacy alias
   '2-plan': 'plan',
   '3-implement': 'implement',
   '4-review': 'review',
@@ -62,8 +51,6 @@ function registerFeatureIfMissing(state, featureName) {
   if (!state.features) state.features = {};
   if (state.features[featureName]) return false;
 
-  // Canonical object-form gates (incl. optional uiux) + stamped identity
-  // (name=slug, workType, createdAt) — no anonymous shell, no boolean drift.
   state.features[featureName] = createDefaultFeature(featureName);
   return true;
 }
@@ -94,24 +81,8 @@ function isApprovalAnswer(answer) {
   );
 }
 
-function gateFromQuestion(question) {
-  if (typeof question !== 'string') return null;
-  // Checked BEFORE the generic patterns below: the pinned uiux template is
-  // "Gate uiux — Design de {feature} aprovado?" (morph-uiux/SKILL.md) — it
-  // must never fall through to 'plan' via a stray "plan"/"plano" substring in
-  // the feature name. `/gate\s+uiux/i` alone is unambiguous either way.
-  if (/gate\s+uiux/i.test(question)) return 'uiux';
-  const lower = question.toLowerCase();
-  if (lower.includes('gate 1') || lower.includes('proposta')) return 'proposal';
-  if (lower.includes('gate 2') || lower.includes('plano') || lower.includes('plan')) return 'plan';
-  if (lower.includes('gate 3') || lower.includes('review')) return 'review';
-  return null;
-}
-
-// Gate monotonicity — mirror of src/core/state/gate-order.js (hooks are
-// installed standalone and cannot import from src/). Keep in sync:
-// proposal → plan → review; uiux requires proposal.
-const GATE_PREREQ = { proposal: [], uiux: ['proposal'], plan: ['proposal'], review: ['plan'] };
+// Mirror of src/core/state/gate-order.js: hooks are installed standalone and cannot import src/.
+const GATE_PREREQ = { plan: [], uiux: ['plan'], review: ['plan'] };
 function unmetGatePrereqs(gate, gates) {
   const isApproved = (g) => gates?.[g]?.approved === true || gates?.[g] === true;
   return (GATE_PREREQ[gate] || []).filter((p) => !isApproved(p));
@@ -122,9 +93,7 @@ function handleWriteEdit(input, sessionRoot) {
   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.
+  // Sync the tree that OWNS the written file: a root session also writes into worktrees.
   const cwd = resolveMorphRoot(filePath, sessionRoot);
   if (!stateExists(cwd)) return false;
 
@@ -139,8 +108,6 @@ function handleWriteEdit(input, sessionRoot) {
   }
 
   if (changed) {
-    // Persist the touched feature to its authoritative feature.json and refresh
-    // the thin root index. The feature's state thus travels in its own folder.
     persistFeature(featureName, state.features[featureName], cwd);
   }
   return true;
@@ -156,22 +123,11 @@ function handleAskUserQuestion(input, sessionRoot) {
     const gate = gateFromQuestion(question);
     if (!gate) continue;
 
-    // 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.
+    // The feature the QUESTION names, in the tree that owns it — never the session tree's first in-progress feature.
     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.
+      // Refuse to guess: a gate on the wrong feature inverts gate order. For an unregistered slug
+      // `approve` is a dead end ("Feature not found"), so the remediation names `create`.
       const allNames = allWorkTrees(sessionRoot).flatMap((r) => featureNamesIn(r));
       const candidate = unrecognizedSlugLike(question, allNames);
       const remediation = candidate
@@ -190,20 +146,14 @@ function handleAskUserQuestion(input, sessionRoot) {
     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).
+    // Fallback to the merged view: a feature only in the thin index would read every predecessor as unapproved.
     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;
 
-    // Gate monotonicity: fail-open. The human said "aprovado", so we DO approve
-    // (never block a human in the loop), but if a predecessor gate is still
-    // pending we surface a non-blocking warning — the CLI `morph-spec approve`
-    // hard-refuses the same shape; here we alert so the operator can reconcile.
+    // Out of order still approves (never block a human in the loop); `morph-spec approve` refuses the same shape.
     const unmet = unmetGatePrereqs(gate, gates);
     if (unmet.length) {
       warnings.push(
@@ -213,18 +163,12 @@ function handleAskUserQuestion(input, sessionRoot) {
       );
     }
 
-    // An "aprovado" answer to AskUserQuestion is a human approving in the loop.
-    // Route through the shared canonical gate writer so the hook and the CLI
-    // (`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.
-    // Same contract as `approve`'s --self-assessed: a human may ship Gate 3 without the
-    // independent evaluator, but the degradation is stamped, never silent.
+    // Same contract as `approve --self-assessed`: approving review without its reports is stamped, never silent.
     const selfAssessed = gate === 'review' && feature?.workType !== 'hotfix'
-      && !existsSync(join(root, '.morph', 'features', featureName, '4-review', 'evaluator-report.md'));
+      && ['verifier.md', 'reviewer.md'].some((f) => !existsSync(join(root, '.morph', 'features', featureName, '4-review', f)));
     if (selfAssessed) {
       warnings.push(
-        `⚠️ [morph-spec] Gate 3 de "${featureName}" aprovado SEM avaliador independente — ` +
+        `⚠️ [morph-spec] Gate 3 de "${featureName}" aprovado SEM os relatórios de review independentes (verifier.md, reviewer.md) — ` +
         `registrado como selfAssessed (aparece no list/fleet).`
       );
     }
@@ -233,19 +177,9 @@ function handleAskUserQuestion(input, sessionRoot) {
   return warnings.length ? warnings.join('\n') : null;
 }
 
-/**
- * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit|AskUserQuestion)
- * @returns {Promise<object|null>} a hookSpecificOutput warning on a gate
- *   order/attribution violation, or null (pass/silent).
- */
 export async function run(payload) {
   try {
-    // 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).
+    // Only a starting point: each handler resolves the tree it reads and writes, so the stateExists gate lives there.
     const sessionRoot = projectDir();
 
     const input = payload || {};
@@ -258,12 +192,8 @@ export async function run(payload) {
       } else if (toolName === 'AskUserQuestion') {
         warning = handleAskUserQuestion(input, sessionRoot);
       }
-    } catch {
-      // fail-open
-    }
+    } catch {}
 
-    // A non-blocking order-violation warning is surfaced as injected context
-    // (hookSpecificOutput.additionalContext); everything else stays silent.
     return warning ? contextResult(warning, 'PostToolUse') : null;
   } catch {
     return null;