@polymorphism-tech/morph-spec 7.2.0 → 7.4.0

package/framework/hooks/shared/state-reader.js

@@ -1,221 +1,236 @@
-/**
- * Shared read-only state accessor for Claude Code hooks.
- *
- * Wraps state.json reads with fail-open semantics:
- * - Returns null instead of throwing on missing/corrupt state
- * - Never writes to state.json (read-only)
- * - Uses synchronous reads for <100ms performance
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-const STATE_FILE = '.morph/state.json';
-
-/**
- * Load state.json from the project root.
- * Fail-open: returns null if file missing or corrupt.
- * @param {string} [projectPath] - Project root (defaults to cwd)
- * @returns {Object|null} State object or null
- */
-export function loadState(projectPath) {
-  try {
-    const statePath = join(projectPath || process.cwd(), STATE_FILE);
-    if (!existsSync(statePath)) return null;
-    return JSON.parse(readFileSync(statePath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check if state.json exists.
- * @param {string} [projectPath]
- * @returns {boolean}
- */
-export function stateExists(projectPath) {
-  return existsSync(join(projectPath || process.cwd(), STATE_FILE));
-}
-
-/**
- * Get the active feature (most recently updated in_progress feature).
- * @param {string} [projectPath]
- * @returns {{ name: string, feature: Object }|null}
- */
-export function getActiveFeature(projectPath) {
-  const state = loadState(projectPath);
-  if (!state?.features) return null;
-
-  let active = null;
-  let latestUpdate = '';
-
-  for (const [name, feature] of Object.entries(state.features)) {
-    if (feature.status === 'in_progress' || feature.status === 'draft') {
-      const updated = feature.updatedAt || feature.createdAt || '';
-      if (updated >= latestUpdate) {
-        latestUpdate = updated;
-        active = { name, feature };
-      }
-    }
-  }
-
-  return active;
-}
-
-/**
- * Get the most recently updated feature (any status).
- * Useful as a fallback when getActiveFeature returns null (all features done).
- * @param {string} [projectPath]
- * @returns {{ name: string, feature: Object }|null}
- */
-export function getMostRecentFeature(projectPath) {
-  const state = loadState(projectPath);
-  if (!state?.features) return null;
-
-  let result = null;
-  let latestUpdate = '';
-
-  for (const [name, feature] of Object.entries(state.features)) {
-    const updated = feature.updatedAt || feature.createdAt || '';
-    if (updated >= latestUpdate) {
-      latestUpdate = updated;
-      result = { name, feature };
-    }
-  }
-
-  return result;
-}
-
-/**
- * Get a specific feature by name.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Object|null}
- */
-export function getFeature(featureName, projectPath) {
-  const state = loadState(projectPath);
-  return state?.features?.[featureName] || null;
-}
-
-/**
- * Derive phase from filesystem (phase deleted from state).
- * Checks for phase folders in descending order, returns highest present.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string} Phase name
- */
-export function derivePhaseForFeature(featureName, projectPath) {
-  const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
-  const phaseMap = [
-    ['4-review', 'review'],
-    ['3-implement', 'implement'],
-    ['2-plan', 'plan'],
-    ['1-design', 'uiux'],
-    ['0-proposal', 'proposal'],
-  ];
-  for (const [folder, phase] of phaseMap) {
-    if (existsSync(join(basePath, folder))) return phase;
-  }
-  return 'proposal';
-}
-
-/**
- * Get the current phase of a feature.
- * Falls back to filesystem derivation when phase is not in state.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string|null}
- */
-export function getFeaturePhase(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  if (!feature) return null;
-  return feature.phase || derivePhaseForFeature(featureName, projectPath);
-}
-
-/**
- * Get approval status for a gate.
- * @param {string} featureName
- * @param {string} gate - 'proposal'|'uiux'|'plan'|'review'
- * @param {string} [projectPath]
- * @returns {boolean}
- */
-export function isGateApproved(featureName, gate, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
-  const gates = feature?.approvals || feature?.approvalGates;
-  return gates?.[gate]?.approved === true;
-}
-
-/**
- * Get all pending approval gates for a feature.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string[]} List of gate names that are not yet approved
- */
-export function getPendingGates(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
-  const gates = feature?.approvals || feature?.approvalGates;
-  if (!gates) return [];
-
-  return Object.entries(gates)
-    .filter(([, gate]) => !gate.approved)
-    .map(([name]) => name);
-}
-
-/**
- * Get feature outputs status.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Object|null} outputs map or null
- */
-export function getOutputs(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  return feature?.outputs || null;
-}
-
-/**
- * Get uncompleted required outputs for current phase.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Array<{type: string, path: string}>}
- */
-/**
- * Get task statistics directly from taskList (preferred over feature.tasks counters).
- * Excludes expanded tasks from counts, matching calculateProgress() behavior.
- *
- * @param {Object} feature - Feature state object
- * @returns {{ total: number, completed: number, inProgress: number, pending: number }}
- */
-export function getTaskStats(feature) {
-  const list = feature?.taskList || [];
-  if (list.length > 0) {
-    const active = list.filter(t => t.status !== 'expanded');
-    return {
-      total: active.length,
-      completed: active.filter(t => t.status === 'completed').length,
-      inProgress: active.filter(t => t.status === 'in_progress').length,
-      pending: active.filter(t => t.status === 'pending').length,
-    };
-  }
-  // Fallback: read from legacy counter object
-  const tasks = feature?.tasks;
-  if (tasks && typeof tasks === 'object' && !Array.isArray(tasks)) {
-    return {
-      total: tasks.total || 0,
-      completed: tasks.completed || 0,
-      inProgress: tasks.inProgress || 0,
-      pending: tasks.pending || 0,
-    };
-  }
-  return { total: 0, completed: 0, inProgress: 0, pending: 0 };
-}
-
-export function getMissingOutputs(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  if (!feature?.outputs) return [];
-
-  return Object.entries(feature.outputs)
-    .filter(([, output]) => !output.created)
-    .map(([type, output]) => ({ type, path: output.path }));
-}
+/**
+ * Shared read-only state accessor for Claude Code hooks.
+ *
+ * Wraps state.json reads with fail-open semantics:
+ * - Returns null instead of throwing on missing/corrupt state
+ * - Never writes to state.json (read-only)
+ * - Uses synchronous reads for <100ms performance
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const STATE_FILE = '.morph/state.json';
+
+/**
+ * Load state.json from the project root.
+ * Fail-open: returns null if file missing or corrupt.
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ * @returns {Object|null} State object or null
+ */
+export function loadState(projectPath) {
+  try {
+    const statePath = join(projectPath || process.cwd(), STATE_FILE);
+    if (!existsSync(statePath)) return null;
+    return JSON.parse(readFileSync(statePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if state.json exists.
+ * @param {string} [projectPath]
+ * @returns {boolean}
+ */
+export function stateExists(projectPath) {
+  return existsSync(join(projectPath || process.cwd(), STATE_FILE));
+}
+
+/**
+ * Get the active feature (most recently updated in_progress feature).
+ * @param {string} [projectPath]
+ * @returns {{ name: string, feature: Object }|null}
+ */
+export function getActiveFeature(projectPath) {
+  const state = loadState(projectPath);
+  if (!state?.features) return null;
+
+  let active = null;
+  let latestUpdate = '';
+
+  for (const [name, feature] of Object.entries(state.features)) {
+    if (feature.status === 'in_progress' || feature.status === 'draft') {
+      const updated = feature.updatedAt || feature.createdAt || '';
+      if (updated >= latestUpdate) {
+        latestUpdate = updated;
+        active = { name, feature };
+      }
+    }
+  }
+
+  return active;
+}
+
+/**
+ * Get the most recently updated feature (any status).
+ * Useful as a fallback when getActiveFeature returns null (all features done).
+ * @param {string} [projectPath]
+ * @returns {{ name: string, feature: Object }|null}
+ */
+export function getMostRecentFeature(projectPath) {
+  const state = loadState(projectPath);
+  if (!state?.features) return null;
+
+  let result = null;
+  let latestUpdate = '';
+
+  for (const [name, feature] of Object.entries(state.features)) {
+    const updated = feature.updatedAt || feature.createdAt || '';
+    if (updated >= latestUpdate) {
+      latestUpdate = updated;
+      result = { name, feature };
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get a specific feature by name.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {Object|null}
+ */
+export function getFeature(featureName, projectPath) {
+  const state = loadState(projectPath);
+  return state?.features?.[featureName] || null;
+}
+
+/**
+ * Derive phase from filesystem (phase deleted from state).
+ *
+ * Walks the phase map in descending order and returns the first phase whose
+ * CANONICAL ARTIFACT exists. An empty folder is not enough — this avoids the
+ * chicken-and-egg problem where `mkdir 2-plan/` (or any pre-created sibling)
+ * advances the phase before plan content is written, then
+ * `enforce-phase-writes` blocks writes back to `0-proposal/`.
+ *
+ * Canonical artifacts (one per phase) match MORPH.md §3:
+ *   - 4-review  → review-report.md
+ *   - 3-implement → recap.md
+ *   - 2-plan    → spec.md  (the first plan-phase output produced)
+ *   - 1-design  → design-system.md
+ *   - 0-proposal → proposal.md
+ *
+ * If no canonical file is found, returns `'proposal'` (the starting phase).
+ *
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string} Phase name
+ */
+export function derivePhaseForFeature(featureName, projectPath) {
+  const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
+  const phaseMap = [
+    ['4-review',    'review',    'review-report.md'],
+    ['3-implement', 'implement', 'recap.md'],
+    ['2-plan',      'plan',      'spec.md'],
+    ['1-design',    'uiux',      'design-system.md'],
+    ['0-proposal',  'proposal',  'proposal.md'],
+  ];
+  for (const [folder, phase, canonical] of phaseMap) {
+    if (existsSync(join(basePath, folder, canonical))) return phase;
+  }
+  return 'proposal';
+}
+
+/**
+ * Get the current phase of a feature.
+ * Falls back to filesystem derivation when phase is not in state.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string|null}
+ */
+export function getFeaturePhase(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  if (!feature) return null;
+  return feature.phase || derivePhaseForFeature(featureName, projectPath);
+}
+
+/**
+ * Get approval status for a gate.
+ * @param {string} featureName
+ * @param {string} gate - 'proposal'|'uiux'|'plan'|'review'
+ * @param {string} [projectPath]
+ * @returns {boolean}
+ */
+export function isGateApproved(featureName, gate, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
+  const gates = feature?.approvals || feature?.approvalGates;
+  return gates?.[gate]?.approved === true;
+}
+
+/**
+ * Get all pending approval gates for a feature.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string[]} List of gate names that are not yet approved
+ */
+export function getPendingGates(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
+  const gates = feature?.approvals || feature?.approvalGates;
+  if (!gates) return [];
+
+  return Object.entries(gates)
+    .filter(([, gate]) => !gate.approved)
+    .map(([name]) => name);
+}
+
+/**
+ * Get feature outputs status.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {Object|null} outputs map or null
+ */
+export function getOutputs(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  return feature?.outputs || null;
+}
+
+/**
+ * Get uncompleted required outputs for current phase.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {Array<{type: string, path: string}>}
+ */
+/**
+ * Get task statistics directly from taskList (preferred over feature.tasks counters).
+ * Excludes expanded tasks from counts, matching calculateProgress() behavior.
+ *
+ * @param {Object} feature - Feature state object
+ * @returns {{ total: number, completed: number, inProgress: number, pending: number }}
+ */
+export function getTaskStats(feature) {
+  const list = feature?.taskList || [];
+  if (list.length > 0) {
+    const active = list.filter(t => t.status !== 'expanded');
+    return {
+      total: active.length,
+      completed: active.filter(t => t.status === 'completed').length,
+      inProgress: active.filter(t => t.status === 'in_progress').length,
+      pending: active.filter(t => t.status === 'pending').length,
+    };
+  }
+  // Fallback: read from legacy counter object
+  const tasks = feature?.tasks;
+  if (tasks && typeof tasks === 'object' && !Array.isArray(tasks)) {
+    return {
+      total: tasks.total || 0,
+      completed: tasks.completed || 0,
+      inProgress: tasks.inProgress || 0,
+      pending: tasks.pending || 0,
+    };
+  }
+  return { total: 0, completed: 0, inProgress: 0, pending: 0 };
+}
+
+export function getMissingOutputs(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  if (!feature?.outputs) return [];
+
+  return Object.entries(feature.outputs)
+    .filter(([, output]) => !output.created)
+    .map(([type, output]) => ({ type, path: output.path }));
+}

package/framework/phases.json

@@ -43,7 +43,7 @@
       "goals": [
         "Write spec.md (technical spec)",
         "Write mandate.md (implementation contract with stack defaults + forbidden patterns)",
-        "Write tasks.md (ordered task breakdown)"
+        "Write tasks.json (ordered task breakdown)"
       ],
       "requiredOutputs": ["spec", "mandate", "tasks"],
       "optionalOutputs": ["decisions"],

package/framework/skills/README.md

@@ -14,9 +14,9 @@ These are the only skills the harness needs. MORPH.md references them by path.
 |----------------------|----------------------------------------------------------------------|----------------|
 | `morph-brainstorming` | Business understanding + brownfield scan → proposal.md (Gate 1)     | yes            |
 | `morph-stack-scan`    | Detect stack drift in existing projects, generate migration-plan.md  | yes            |
-| `morph-plan`          | Produce spec.md + mandate.md + tasks.md (Gate 2)                     | yes            |
+| `morph-plan`          | Produce spec.md + mandate.md + tasks.json (Gate 2)                   | yes            |
 | `morph-implement`     | Execute each task with standard + persona, auto-advance between tasks| no             |
-| `morph-eval`          | Score work 0-10 across 4 dimensions, silence on score >= 8           | no             |
+| `morph-eval`          | Score work 0-10 across 4 dimensions, silence on score >= 9           | no             |
 | `morph-review`        | Final review report with scores + recommendation (Gate 3)            | yes            |
 | `morph-standards`     | Locate and load a specific standard on demand                        | no             |
 

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: "7.2.0"
+cliVersion: "7.4.0"
 ---
 
 # morph-apply
@@ -41,18 +41,26 @@ Executar todas as tasks pendentes de uma feature até `done`, aplicando `morph-e
 
 ### 2. Análise de DAG — decisão sequencial vs paralelo
 
-Construir o grafo de dependências e detectar subsets independentes.
+Construir o grafo de dependências e detectar fluxos de trabalho independentes. Há duas formas de paralelismo a detectar — e a segunda é a que mais aparece na prática:
+
+```js
+const groups = groupTasks(data); // { backend: [ids], frontend: [ids], tests: [...], infra: [...], docs: [...] }
+const independentRoots = data.tasks.filter(t => t.dependencies.length === 0);
+```
 
 **Regras de decisão:**
 
 1. Se `data.tasks.length <= 3`: **sequencial** (overhead de Agent dispatch não compensa).
-2. Identificar tasks **100% independentes** (`dependencies: []`):
-   - Se `>= 3` tasks independentes existem: dispachar essas em **paralelo**, depois cair em sequencial para o resto.
-3. Caso contrário: **sequencial puro** com auto-advance.
+2. **Fluxos de domínio independentes (o caso comum — backend ‖ frontend).** Use `groupTasks(data)` para separar as tasks por `group`. Dois grupos formam fluxos paralelos quando **nenhuma task de um grupo depende de uma task de outro grupo** (as cadeias só convergem, se convergirem, numa task final de integração). Se existem **≥ 2 fluxos de domínio independentes** — ex: a cadeia `backend` `T1→…→T11` e a cadeia `frontend` `T12→T13` não se cruzam até `T14` —, dispache **um sub-agent por fluxo, em paralelo**, cada um com a persona e o standard do seu domínio (ver passo 3b). Esse é exatamente o caso que a regra antiga de "≥3 raízes independentes" deixava passar (duas cadeias contam como 2 raízes, não 3).
+3. **Raízes independentes (fan-out na largura).** Identificar tasks **100% independentes** (`dependencies: []`). Se `independentRoots.length >= 3`: dispachar essas raízes em **paralelo**, depois cair em sequencial para o resto.
+4. Caso contrário: **sequencial puro** com auto-advance.
+
+> O cap de **4 agentes simultâneos** (anti-padrão abaixo) vale para ambas as formas. Se um fluxo de domínio é uma cadeia longa, despache o **fluxo inteiro** a um sub-agent (que executa a cadeia em ordem internamente) — um agente por fluxo, não um agente por task.
 
-Logar a decisão:
+Logar a decisão (mostre qual forma disparou):
 ```
-DAG analysis: 12 tasks, 4 independent → parallel batch (T1, T3, T7, T9) + sequential remainder
+DAG analysis: 14 tasks, groups {backend:9, frontend:2, tests:2, infra:1}; backend ‖ frontend independentes até T14 → 2 fluxos paralelos (1 agente backend, 1 agente frontend) + T14 sequencial no fim
+DAG analysis: 12 tasks, 4 raízes independentes → parallel batch (T1, T3, T7, T9) + sequential remainder
 ```
 
 ### 3a. Modo Sequencial (auto-advance)
@@ -68,39 +76,69 @@ while (true):
   updateTaskStatus(data, task.id, 'in_progress')
   writeTasksJson(tasksPath, data)
 
-  invoke Skill(morph-implement) with task
-
-  result = invoke Skill(morph-eval) with implementation output
-
-  if result.score >= 8:
+  // Loop de correção autônomo — a barra de qualidade é >= 9 (ver MORPH.md §0).
+  // Entre tasks NÃO há pausa humana: score < 9 dispara re-implementação, não AskUserQuestion.
+  attempt = 0
+  best = { score: 0, output: null }
+  while attempt < 3:
+    attempt += 1
+    invoke Skill(morph-implement) with task
+      (no attempt > 1: passar o feedback priorizado do morph-eval anterior como input)
+    result = invoke Skill(morph-eval) with implementation output
+    if result.score > best.score: best = result
+    // Persista o score no state.json sob a task — torna o evalScore um signal de disco
+    // no MOMENTO da implementação (não no fim). O hook gate-guard.js e o Gate 3 leem dali.
+    // Edit em .morph/state.json é permitido. Grave:
+    //   features[feature].taskScores[task.id] = { lastScore: result.score, bestScore: best.score, attempts: attempt, updatedAt: <ISO> }
+    edit .morph/state.json com o taskScores acima
+
+    if result.score >= 9:
+      break
+
+  if best.score >= 9:
     updateTaskStatus(data, task.id, 'done')
   else:
-    // forçar pausa — qualidade é guardrail, trust não ignora aqui
-    AskUserQuestion: "Task {id} com score {score} — aceitar, reimplementar ou pular?"
-    options: [aceitar mesmo assim, reimplementar, pular task]
+    // 3 tentativas sem atingir 9 — AQUI sim escala ao humano (escape definido).
+    // Esta é a única pausa do loop de implement, e só após esgotar o loop de correção.
+    registrar em recap.md: as 3 tentativas e o melhor score (best.score) com o feedback
+    AskUserQuestion: "Task {id} não atingiu score 9 após 3 tentativas (melhor: {best.score}) — aceitar mesmo assim, continuar tentando, ou pular?"
+    options: [aceitar (marca done com ressalva no recap), continuar tentando (+3 tentativas), pular task (marca blocked)]
 
   writeTasksJson(tasksPath, data)
 ```
 
+> **Por que loop e não pausa:** MORPH.md §0 manda auto-avançar entre tasks. Score baixo numa task individual é um problema de qualidade que o modelo deve **corrigir sozinho**, não delegar ao humano no meio da implementação. A pausa só existe quando o loop de correção se esgota (3 tentativas) — o "escape" do modelo autônomo. O trust mode não muda esse loop: ele governa os **gates** (proposal/plan/review), não o ciclo de correção intra-task.
+
 ### 3b. Modo Paralelo (para o subset independente)
 
-Para cada task independente:
+**Antes de despachar, escope cada agente ao seu domínio.** Um agente genérico sem persona nem standard não "conhece" as convenções daquele domínio — produz código fora do padrão. Para cada fluxo/task a despachar, resolva:
+
+- **Persona:** em `agents.json`, encontre o agente cujo `domains` cobre o `group`/domínio da task (ex: `backend` → `dotnet-senior`, `frontend` → `nextjs-expert`/`ui-designer`, `database` → `ef-modeler`). Pegue o texto do campo `persona`.
+- **Standard(s):** do array `standards` desse mesmo agente em `agents.json` (e/ou do `mandate.md`), selecione o(s) path(s) `.md` relevante(s) à task.
+
 ```
 dispatch Agent (subagent_type: "general-purpose") with prompt:
+  persona: <texto do campo `persona` do agente de domínio em agents.json>
   contexto: spec.md, mandate.md, task description completa, doneCriteria
+  standard: <path(s) .md do(s) standard(s) do domínio — leia-o(s) antes de implementar>
   instrução: |
-    Implemente esta task isoladamente. Não modifique spec.md, mandate.md.
+    Adote a persona acima. Leia o(s) standard(s) indicado(s) antes de escrever código.
+    Implemente esta task (ou cadeia de tasks do fluxo) isoladamente.
+    Não modifique spec.md, mandate.md.
     Retorne:
       - sumário das mudanças
       - arquivos modificados (paths)
+      - standard(s) consultado(s)
       - auto-score 0-10 (rubric: completeness, correctness, mandate compliance)
 ```
 
+> Este template é deliberadamente paritário com o template sequencial em `morph-implement` §4: ambos passam **persona + standard escopados**. A única diferença é que aqui múltiplos agentes rodam ao mesmo tempo, um por fluxo independente.
+
 Aguardar todos os agentes terminarem (Promise.all equivalente). Depois, sequencialmente:
 - Para cada output retornado:
   - Aplicar `Skill(morph-eval)`.
-  - Se score >= 8: marcar `done`.
-  - Se score < 8: marcar `pending` novamente com nota — será re-executada no modo sequencial.
+  - Se score >= 9: marcar `done`.
+  - Se score < 9: marcar `pending` novamente com nota — volta ao modo sequencial, onde o loop de correção (até 3 tentativas) busca o score 9.
 
 Depois do batch paralelo, executar o restante em modo sequencial (passo 3a).
 
@@ -115,12 +153,16 @@ Quando `getPendingTasks(data).length === 0`:
 
 Sinais de risco para Gate 3:
 
-- Score médio < 8 no review-report.
+- Score médio < 9 no review-report.
 - Presença de erros não resolvidos.
 - Mudanças incidentais em standards/.morph/framework/.
 
 Mesma lógica do Gate 1/Gate 2 via `shouldPauseGate(config, signals)`:
 
+**Persista a decisão em `state.json` ANTES de apresentar ou auto-aprovar** — grave
+`features[feature].gateDecisions.review = { pause, reason, signals, trust, decidedAt: <ISO> }`
+(o `signals.evalScore` aqui é o score composto do review-report). O hook `gate-guard.js` confere depois se a ação bateu. Sem o registro o guard não verifica.
+
 - Pause: `AskUserQuestion` com options `["aprovado, fechar feature", "preciso ajustar", "rollback"]`.
 - Auto: exibir summary do review-report e prosseguir.
 
@@ -133,7 +175,7 @@ Mesma lógica do Gate 1/Gate 2 via `shouldPauseGate(config, signals)`:
 ## Anti-padrões
 
 - Não dispachar paralelo se há deps cruzadas entre as tasks selecionadas (corrompe ordem).
-- Não pular `morph-eval` — silêncio em score >= 8 é o sinal correto.
+- Não pular `morph-eval` — uma task só avança com score >= 9; abaixo disso, o loop de correção roda (não pausa).
 - Não reescrever spec.md/mandate.md durante implement (são read-only após Gate 2 — `protect-spec-files.js` hook bloqueia).
 - Não dispachar mais que 4 agentes em paralelo (sobrecarga de contexto + custo).