@polymorphism-tech/morph-spec 8.17.0 → 8.19.0

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: morph-stack-scan
-description: Varre o codebase existente, detecta stack atual, compara com o stack padrão e gera migration-plan.md se houver desvios
+description: Varre o codebase existente, detecta stack atual, compara com o stack padrão e registra desvios em stack-scan.md
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.17.0"
+cliVersion: "8.19.0"
 ---
 
 # morph-stack-scan
@@ -17,19 +17,7 @@ Quando o projeto já tem código existente e você precisa entender o estado atu
 
 ## Stack padrão de referência
 
-| Camada | Esperado |
-|--------|----------|
-| Runtime | .NET 10 |
-| Arquitetura | VSA — feature-folder: `{Feature}/` com Handler, Validator, Endpoint, Errors, Tests |
-| ORM | EF Core + Neon (Postgres) |
-| IDs | `Guid.CreateVersion7()` |
-| Classes | `sealed` por padrão |
-| Erros | Result pattern (`result.Match()`), não exceptions não tratadas |
-| IA | Microsoft Agent Framework (MAF) |
-| Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
-| Jobs | Hangfire (apenas quando necessário) |
-
-**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), SQL cru sem justificativa. Acesso a dados em VSA: `ApplicationDbContext` direto no slice (`DbSet<T>` já é repository, `DbContext` já é unit of work); para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
+O "Esperado" da comparação do passo 2 é o stack baked-in (runtime .NET 10 + VSA, EF Core/Neon, `Guid.CreateVersion7()`, `sealed`, result pattern, MAF, Next.js/Tailwind/Shadcn, Hangfire) e a lista de padrões proibidos (`Guid.NewGuid()`, classes não-sealed, Service/Manager layer, repository genérico, SQL cru sem justificativa) — regra canônica em `MORPH.md` § "Stack baked-in". Os templates de `stack-scan.md` abaixo (greenfield e brownfield) escrevem essa lista por extenso no artefato da feature, para que quem ler o `stack-scan.md` depois não precise reabrir o `MORPH.md`.
 
 ## Greenfield short-circuit
 
@@ -120,29 +108,25 @@ Antes de despachar Explore, verifique se o projeto é greenfield:
    | Runtime | .NET X | .NET 10 | ✓ / ✗ |
    ...
 
-   ## Desvios
+   ## Desvios (ordenados por severidade)
    ### Bloqueantes
-   - {desvio}: {onde foi encontrado} — impacto: {o que quebra se não migrar}
+   - {desvio}: {onde foi encontrado} — impacto: {o que quebra se não migrar} — esforço: {estimativa}
 
    ### Não bloqueantes
-   - {desvio}: {onde foi encontrado} — migração: {como resolver}
+   - {desvio}: {onde foi encontrado} — migração: {como resolver} — esforço: {estimativa}
 
    ## Recomendação
    {Em compliance — prosseguir para morph-brainstorming}
-   {ou: Migração necessária antes de prosseguir — veja migration-plan.md}
+   {ou: Migração necessária antes de prosseguir — ver Desvios acima}
    ```
 
-4. Se houver desvios bloqueantes ou altos, produza `migration-plan.md` em `.morph/features/{feature}/0-proposal/` com:
-   - Lista de desvios ordenados por severidade
-   - Para cada desvio: o que migrar, como migrar, estimativa de esforço, ordem sugerida
-   - Pergunta única via `AskUserQuestion`: "Esta migração deve ser incluída na feature atual ou tratada numa feature separada?"
+4. Se houver desvios bloqueantes ou altos, pergunte via `AskUserQuestion`: "Esta migração deve ser incluída na feature atual ou tratada numa feature separada?" A resposta é decisão humana — registre-a na seção "Compliance de stack" do `proposal.md` (produzido pela `morph-brainstorming`), não num artefato novo: a lista de desvios com impacto/esforço já vive no `stack-scan.md` acima.
 
 5. Se não houver desvios (ou apenas baixos): informe "codebase em compliance com o stack padrão" e prossiga para morph-brainstorming ou morph-plan conforme o contexto.
 
 ## Output esperado
-- `.morph/features/{feature}/0-proposal/stack-scan.md` — resultado da varredura
-- `.morph/features/{feature}/0-proposal/migration-plan.md` — apenas se houver desvios altos/bloqueantes
-- Decisão documentada: incluir migração nesta feature ou separar
+- `.morph/features/{feature}/0-proposal/stack-scan.md` — resultado da varredura, com desvios ordenados por severidade e esforço estimado
+- Decisão documentada: incluir migração nesta feature ou separar (registrada no proposal.md pela morph-brainstorming)
 
 ## Referências
 - `framework/MORPH.md` — seção 4 (Standards), seção 2 (Fases)

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.17.0"
+cliVersion: "8.19.0"
 ---
 
 # morph-standards

package/package.json

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

package/src/commands/project/doctor.js

@@ -826,13 +826,20 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check templates
+  // Check templates — as of the R3 perf plan (Task 2), setup-infra/update no
+  // longer pre-populate .morph/framework/templates/: template resolution is
+  // layered (template-registry.js / architecture-scanner.js resolveTemplatePath)
+  // and falls back to the npm package's own framework/templates/ when the
+  // project-local copy is absent, which is now the expected default rather
+  // than an error. The project-local copy remains a supported override — if
+  // present, report it as such. The "key templates" check further below
+  // verifies the package copy itself is intact, which is the check that
+  // actually matters now.
   const templatesPath = join(morphPath, 'framework', 'templates');
   if (await pathExists(templatesPath)) {
-    checks.push({ name: 'templates/', status: 'ok' });
+    checks.push({ name: 'templates/', status: 'ok', msg: 'local override present' });
   } else {
-    checks.push({ name: 'templates/', status: 'missing' });
-    hasErrors = true;
+    checks.push({ name: 'templates/', status: 'ok', msg: 'resolved from package (no local override)' });
   }
 
   // Check .claude folder

package/src/commands/project/init.js

@@ -486,7 +486,7 @@ export async function initCommand(options) {
     logger.info('Files installed:');
     logger.dim(`  ✓ CLAUDE.md`);
     logger.dim(`  ✓ .morph/config/ (config.json)`);
-    logger.dim(`  ✓ .morph/framework/ (agents.json, standards/, templates/, hooks/)`);
+    logger.dim(`  ✓ .morph/framework/ (agents.json, standards/, hooks/)`);
     logger.dim(`  ✓ .morph/context/ (project context)`);
     logger.dim(`  ✓ .morph/features/ (feature outputs)`);
     if (commandsCopied) {

package/src/commands/project/status.js

@@ -62,7 +62,7 @@ function getPhaseStatus(phaseKey, currentPhase, feature) {
  */
 function checkPhaseOutputs(phaseKey, feature) {
   const phaseOutputMap = {
-    proposal: ['proposal', 'stackScan', 'migrationPlan'],
+    proposal: ['proposal', 'stackScan'],
     uiux: ['uiDesignSystem', 'uiMockups', 'uiComponents', 'uiFlows'],
     plan: ['spec', 'mandate', 'tasks', 'decisions'],
     implement: ['recap'],
@@ -100,7 +100,7 @@ function formatPhase(phaseKey, currentPhase, feature, options = {}) {
   // Add output files if verbose
   if (options.verbose && status !== 'pending' && status !== 'skipped') {
     const phaseOutputMap = {
-      proposal: ['proposal', 'stackScan', 'migrationPlan'],
+      proposal: ['proposal', 'stackScan'],
       uiux: ['uiDesignSystem', 'uiMockups', 'uiComponents', 'uiFlows'],
       plan: ['spec', 'mandate', 'tasks', 'decisions'],
       implement: ['recap'],

package/src/commands/project/update.js

@@ -24,7 +24,8 @@ import {
   checkProjectOutdated,
   saveProjectMorphVersion,
   getUpdateInstructions,
-  detectInstallMethod
+  detectInstallMethod,
+  compareVersions
 } from '../../utils/version-checker.js';
 import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
 import { installSkills } from '../../utils/skills-installer.js';
@@ -59,7 +60,12 @@ async function backupUserConfig(morphPath) {
 async function cleanFrameworkDirs(morphPath, targetPath) {
   const claudeDir = join(targetPath, '.claude');
   const dirsToClean = [
-    join(morphPath, 'framework', 'templates'),
+    // NOTE: framework/templates is intentionally NOT in this list (R3 perf
+    // plan, Task 2). It's no longer copied/refreshed here — see
+    // reconcileLegacyTemplatesCopy() below, which decides per-run whether a
+    // pre-existing local copy is safe to remove or must be preserved as a
+    // user override. Blindly deleting it here (the old behavior) destroyed
+    // any customization on every single `update` run, override or not.
     join(morphPath, 'framework', 'standards'),
     join(morphPath, 'framework', 'hooks'),
     join(morphPath, 'framework', 'schemas'),
@@ -83,6 +89,67 @@ async function cleanFrameworkDirs(morphPath, targetPath) {
   }
 }
 
+/**
+ * Last CLI version whose `update`/`setup-infra` still wrote
+ * `.morph/framework/templates/` unconditionally, before Task 2 of the R3
+ * perf plan removed that copy. Used as the decision boundary in
+ * `reconcileLegacyTemplatesCopy` below — see its doc comment for why a
+ * version check is used instead of diffing file content.
+ */
+const LAST_VERSION_THAT_COPIED_TEMPLATES = '8.17.0';
+
+/**
+ * Reconcile a pre-existing `.morph/framework/templates/` copy now that
+ * `update` no longer writes it (Task 2, R3 perf plan — resolution falls
+ * back to the npm package's own framework/templates/, see
+ * template-registry.js / architecture-scanner.js's layered resolver).
+ *
+ * Decided from the project's PRIOR recorded CLI version (before THIS
+ * update writes a new one), not by diffing content against the package.
+ * A content diff can't tell "stale copy from an older CLI version" apart
+ * from "deliberate user override" — and staleness is the dominant case for
+ * anyone who actually runs `update`, since template content does change
+ * between releases. The version boundary is unambiguous instead:
+ *
+ *   - No local copy → nothing to do.
+ *   - Prior version is unrecorded, OR <= LAST_VERSION_THAT_COPIED_TEMPLATES
+ *     → the copy could ONLY have been put there by the OLD installer:
+ *     `.morph/framework/**` is Edit-denied to the agent (MORPH_DENY in
+ *     hooks-installer.js — "installer-managed, immutable at runtime"),
+ *     the directory is gitignored, and every `update` before this fix
+ *     unconditionally wiped + recopied it. There is no path by which a
+ *     project on an old version could have a genuine override sitting
+ *     here. Safe to delete unconditionally — it is dead weight, not data.
+ *   - Prior version > LAST_VERSION_THAT_COPIED_TEMPLATES → `update` and
+ *     `setup-infra` have never written this directory for this project.
+ *     Anything found here was placed deliberately (by the user or other
+ *     tooling) — this is the forward-looking override use case the
+ *     layered resolver exists for. Preserve untouched, unconditionally,
+ *     with no diffing.
+ *
+ * @param {string} templatesDest - .morph/framework/templates (may not exist)
+ * @param {string|null} priorProjectVersion - project's recorded morph-spec
+ *   version BEFORE this update run (checkProjectOutdated().current)
+ * @returns {'absent'|'removed-legacy'|'preserved-override'}
+ */
+export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion) {
+  if (!existsSync(templatesDest)) return 'absent';
+
+  const isLegacy = !priorProjectVersion
+    || compareVersions(priorProjectVersion, LAST_VERSION_THAT_COPIED_TEMPLATES) <= 0;
+
+  if (!isLegacy) return 'preserved-override';
+
+  try {
+    fs.removeSync(templatesDest);
+    return 'removed-legacy';
+  } catch {
+    // Couldn't remove — don't risk a half-broken state; leave it and let
+    // the layered resolver's override-first check pick it up as before.
+    return 'preserved-override';
+  }
+}
+
 /**
  * Restore user's config.json after reinstallation
  * @param {string} morphPath - Path to .morph directory
@@ -240,12 +307,14 @@ export async function updateCommand(options) {
     const updateTemplates = !options.standards || options.templates;
     const updateStandards = !options.templates || options.standards;
 
-    // Update templates
+    // Templates are no longer copied to .morph/framework/templates/ (Task 2,
+    // R3 perf plan) — see reconcileLegacyTemplatesCopy()'s doc comment for
+    // why. Only reconcile a leftover copy from a pre-R3 install.
+    let templatesReconcile = 'absent';
     if (updateTemplates) {
-      updateSpinner.text = 'Updating templates...';
-      const templatesSrc = join(contentDir, 'framework', 'templates');
+      updateSpinner.text = 'Checking for a legacy templates copy...';
       const templatesDest = join(morphPath, 'framework', 'templates');
-      await copyDirectory(templatesSrc, templatesDest);
+      templatesReconcile = reconcileLegacyTemplatesCopy(templatesDest, projectCheck.current);
     }
 
     // Update standards
@@ -289,6 +358,13 @@ export async function updateCommand(options) {
         await copyDirectory(src, join(morphPath, 'framework', dir));
       }
     }
+    // CLI.md vive em framework/docs/ na fonte mas instala achatado em
+    // .morph/framework/CLI.md (o CLAUDE.md residente aponta para lá) —
+    // por isso não entra no loop de nomes acima.
+    const cliMdSrc = join(canonicalFrameworkDir, 'docs', 'CLI.md');
+    if (await pathExists(cliMdSrc)) {
+      await copyFile(cliMdSrc, join(morphPath, 'framework', 'CLI.md'));
+    }
 
     // Regenerate derived files (phase-utils.js, skill output tables) from output-schema.js
     // Only runs when the generator script is present (framework dev installs via npm link)
@@ -415,7 +491,15 @@ export async function updateCommand(options) {
 
     logger.blank();
     logger.info('Updated files:');
-    if (updateTemplates) logger.dim('  ✓ .morph/framework/templates/');
+    if (updateTemplates) {
+      if (templatesReconcile === 'removed-legacy') {
+        logger.dim('  ✓ .morph/framework/templates/ (legacy installer copy removed — resolved from package)');
+      } else if (templatesReconcile === 'preserved-override') {
+        logger.dim('  ⚠ .morph/framework/templates/ (local override present — preserved untouched, not updated)');
+      } else {
+        logger.dim('  · .morph/framework/templates/ (not present — resolved from package, no local override)');
+      }
+    }
     if (updateStandards) logger.dim('  ✓ .morph/framework/standards/');
     logger.dim('  ✓ .morph/framework/hooks/');
     logger.dim('  ✓ .morph/framework/agents.json');

package/src/commands/state/gate-check.js

@@ -0,0 +1,223 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'fs';
+import { getFeature } from '../../core/state/state-manager.js';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+import { shouldPauseGate, getRiskSignals } from '../../lib/risk-detector.js';
+import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-decision.js';
+import { detectDefaultBranch, getHeadSha, getDiffStat } from '../../lib/git/default-branch.js';
+
+/**
+ * `--signals` on `gate-check` is NOT a general override like `gate-decision`'s
+ * — everything else here is read straight off disk (workType, taskCount, sha,
+ * diffstat, verification), and letting a caller override those would let a
+ * careless/hostile `--signals` silently defeat the policy this command exists
+ * to make deterministic (e.g. overriding `workType` away from "hotfix" would
+ * suppress risk-detector's forced Gate-3 pause). Only the signals that are
+ * genuinely NOT derivable from disk today are accepted here:
+ *   - standardsViolations / designSystemDivergence: still an LLM's
+ *     natural-language read (see the R4 report — no deterministic detector
+ *     exists in JS yet).
+ *   - evalScore: escape hatch for the TRUE Gate-3 composite score. Since R4
+ *     the evaluator-report carries a machine-readable `**Composite-Score:**`
+ *     token that this command parses by itself (see evaluatorCompositeScore),
+ *     so the override is only needed for legacy reports without the token —
+ *     there the taskScores-average proxy is the fallback.
+ */
+const OVERRIDABLE_SIGNAL_KEYS = ['standardsViolations', 'designSystemDivergence', 'evalScore'];
+
+/** Read tasks.json's task list for a feature; [] if missing/corrupt. Mirrors verify.js's readTasks(). */
+function readTasks(featureName) {
+  try {
+    const tasksPath = getAbsoluteOutputPath(process.cwd(), featureName, 'tasks');
+    if (!existsSync(tasksPath)) return [];
+    return JSON.parse(readFileSync(tasksPath, 'utf8')).tasks || [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Composite eval score PROXY: the average of `lastScore` across every task
+ * recorded in `feature.taskScores`, rounded to 1 decimal. `lastScore` (not
+ * `bestScore`) on purpose — a gate check reports current-state risk, and
+ * `bestScore` can be a stale high-water mark from an attempt the code no
+ * longer matches. "average" mirrors morph-apply's own Gate-3 risk-signal
+ * prose ("Score médio < 9 no review-report" — SKILL.md §5).
+ *
+ * This is explicitly NOT the true Gate-3 composite score (see
+ * OVERRIDABLE_SIGNAL_KEYS doc above) — undefined (key omitted) when no task
+ * has been scored yet, so shouldPauseGate's `typeof === 'number'` check
+ * naturally skips it instead of pausing on a false 0.
+ *
+ * @param {object} feature
+ * @returns {number|undefined}
+ */
+function compositeEvalScore(feature) {
+  const scores = Object.values(feature.taskScores || {})
+    .map((t) => t.lastScore)
+    .filter((n) => typeof n === 'number');
+  if (scores.length === 0) return undefined;
+  const avg = scores.reduce((a, b) => a + b, 0) / scores.length;
+  return Math.round(avg * 10) / 10;
+}
+
+/**
+ * Parse the machine-readable `**Composite-Score:** N.N` token out of
+ * evaluator-report.md — the mirror of approve.js's `**Reviewed-SHA:**`
+ * pattern. This is the TRUE Gate-3 composite (written by the independent
+ * evaluator, per morph-review's dispatch contract), preferred over the
+ * taskScores-average proxy whenever present. Returns undefined when the
+ * report or the token is absent (legacy report) — the proxy stays the
+ * fallback, `--signals evalScore` still overrides both.
+ */
+function evaluatorCompositeScore(cwd, featureName) {
+  try {
+    const p = getAbsoluteOutputPath(cwd, featureName, 'evaluatorReport');
+    if (!existsSync(p)) return undefined;
+    const m = readFileSync(p, 'utf8').match(/\*\*Composite-Score:\*\*\s*([0-9]+(?:\.[0-9]+)?)/);
+    return m ? Number(m[1]) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Collect every signal `shouldPauseGate()` (risk-detector.js) is documented
+ * to consume, straight off disk — the deterministic call site risk-detector
+ * never had (it shipped fully tested with zero callers; see the R4 report).
+ *
+ * `verificationStatus` feeds a real pause rule (verify vermelho pausa —
+ * política adicionada em risk-detector.js no fecho do R4); `verification`
+ * completo, verificationStale, diffstat e sha seguem como contexto de
+ * auditoria persistido, sem regra própria.
+ *
+ * @param {string} featureName
+ * @param {object} feature
+ * @param {string} cwd
+ * @param {string} gateName
+ * @returns {object}
+ */
+function collectSignals(featureName, feature, cwd, gateName) {
+  const tasks = readTasks(featureName);
+  const defaultBranch = detectDefaultBranch(cwd);
+  const sha = getHeadSha(cwd);
+  const verification = feature.verification || null;
+
+  const signals = {
+    workType: feature.workType || 'feature',
+    taskCount: tasks.length,
+    standardsViolations: [],
+    designSystemDivergence: false,
+  };
+
+  const evalScore = compositeEvalScore(feature);
+  if (evalScore !== undefined) {
+    signals.evalScore = evalScore;
+    signals.evalScoreSource = 'taskScores-proxy';
+  }
+
+  // No Gate 3, o score verdadeiro do avaliador independente (token
+  // Composite-Score no evaluator-report.md) tem precedência sobre o proxy.
+  if (gateName === 'review') {
+    const trueComposite = evaluatorCompositeScore(cwd, featureName);
+    if (trueComposite !== undefined) {
+      signals.evalScore = trueComposite;
+      signals.evalScoreSource = 'evaluator-report';
+    }
+  }
+
+  // verificationStatus alimenta a regra "verify vermelho pausa"; o resto do
+  // stamp é auditoria. verificationStale é fail-open na direção "not stale":
+  // stamp com sha null (checkout sem git) ou stamp ausente lê como NOT stale.
+  signals.verification = verification;
+  if (verification?.status) signals.verificationStatus = verification.status;
+  signals.verificationStale = Boolean(verification?.sha && sha && verification.sha !== sha);
+  signals.diffstat = getDiffStat(defaultBranch, cwd);
+  signals.sha = sha;
+
+  return signals;
+}
+
+/**
+ * `morph-spec gate-check <feature> <gate> [--signals <json>] [--trust <mode>]
+ * [--json]` — the deterministic, disk-derived counterpart to `gate-decision`:
+ * collects the signals `shouldPauseGate()` (risk-detector.js) already knows
+ * how to score, calls it, and persists the result through the SAME write path
+ * as `gate-decision` ({@link persistGateDecision}) so the two commands can
+ * never produce a differently-shaped `gateDecisions.{gate}` entry.
+ *
+ * Golden rule: this command does NOT change gate policy. It is a faithful
+ * caller of risk-detector.js's existing, already-tested rules — nothing here
+ * adds a new pause condition. Where the skills' natural-language risk tables
+ * (morph-brainstorming/morph-plan/morph-review/morph-apply) diverge from
+ * risk-detector.js, risk-detector.js wins (see the R4 report for the full list).
+ */
+export async function gateCheckCommand(featureName, gateName, options = {}) {
+  try {
+    if (!VALID_GATES.includes(gateName)) {
+      console.error(chalk.red(`\n❌ Invalid gate: ${gateName}`));
+      console.error(chalk.gray(`Valid gates: ${VALID_GATES.join(', ')}\n`));
+      process.exit(1);
+    }
+
+    const feature = getFeature(featureName);
+    if (!feature) {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+      process.exit(1);
+    }
+
+    let overrides = {};
+    if (options.signals !== undefined) {
+      let parsed;
+      try {
+        parsed = JSON.parse(options.signals);
+      } catch (err) {
+        console.error(chalk.red(`\n❌ Invalid --signals: not valid JSON (${err.message})\n`));
+        process.exit(1);
+      }
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        console.error(chalk.red('\n❌ Invalid --signals: expected a JSON object, e.g. \'{"evalScore":9.2}\'\n'));
+        process.exit(1);
+      }
+
+      const rejected = Object.keys(parsed).filter((k) => !OVERRIDABLE_SIGNAL_KEYS.includes(k));
+      if (rejected.length > 0) {
+        console.error(chalk.yellow(
+          `\n⚠️  --signals ignored for keys not derived from disk-facts you may safely override: ${rejected.join(', ')}\n` +
+          `   Only ${OVERRIDABLE_SIGNAL_KEYS.join(', ')} may be overridden here — everything else is read from feature.json/tasks.json/git.\n` +
+          `   Use \`morph-spec gate-decision\` directly for a fully manual decision.\n`
+        ));
+      }
+      for (const key of OVERRIDABLE_SIGNAL_KEYS) {
+        if (key in parsed) overrides[key] = parsed[key];
+      }
+    }
+
+    const cwd = process.cwd();
+    const signals = { ...collectSignals(featureName, feature, cwd, gateName), ...overrides };
+
+    const trust = options.trust || readTrustFromConfig();
+    const { pause, reason } = shouldPauseGate({ trust }, signals);
+
+    const entry = await persistGateDecision(featureName, gateName, { pause, reason, signals, trust });
+
+    if (options.json) {
+      console.log(JSON.stringify({ feature: featureName, gate: gateName, ...entry }, null, 2));
+      return;
+    }
+
+    const allSignals = getRiskSignals(signals);
+    console.log(entry.pause
+      ? chalk.yellow(`\n⏸️  Gate "${gateName}" — PAUSE (${featureName})`)
+      : chalk.green(`\n▶️  Gate "${gateName}" — auto-pass (${featureName})`));
+    console.log(chalk.gray(`   reason: ${entry.reason} | trust: ${entry.trust} | decidedAt: ${entry.decidedAt}`));
+    if (allSignals.length > 0) {
+      console.log(chalk.gray(`   risk signals present: ${allSignals.join('; ')}`));
+    }
+    console.log(chalk.gray(`   signals: ${JSON.stringify(entry.signals)}`));
+    console.log('');
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error running gate check: ${error.message}\n`));
+    process.exit(1);
+  }
+}

package/src/commands/state/gate-decision.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { getFeature, updateFeature } from '../../core/state/state-manager.js';
 
-const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
+export const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
 
 function parsePauseValue(raw) {
   const v = String(raw).toLowerCase();
@@ -13,8 +13,12 @@ function parsePauseValue(raw) {
   process.exit(1);
 }
 
-/** trust from the committed config (BOM-tolerant), defaulting to "auto". */
-function readTrustFromConfig() {
+/**
+ * trust from the committed config (BOM-tolerant), defaulting to "auto".
+ * Shared by `gate-decision` (recorded as metadata) and `gate-check`
+ * (drives shouldPauseGate's decision directly).
+ */
+export function readTrustFromConfig() {
   try {
     const path = join(process.cwd(), '.morph', 'config', 'config.json');
     if (!existsSync(path)) return 'auto';
@@ -25,6 +29,35 @@ function readTrustFromConfig() {
   }
 }
 
+/**
+ * Write the canonical `gateDecisions.{gate}` entry to a feature's
+ * authoritative feature.json — the ONE write path both `gate-decision` (a
+ * caller-supplied pause/reason/signals, e.g. an LLM's natural-language risk
+ * read, or a manual override) and `gate-check` (a `shouldPauseGate()`-derived
+ * pause/reason/signals) feed into, so the two commands can never drift into
+ * two different persisted shapes for the same field. Does NOT validate
+ * `gateName` — callers that need a friendly CLI error check `VALID_GATES`
+ * themselves before calling this.
+ *
+ * @param {string} featureName
+ * @param {string} gateName
+ * @param {{ pause: boolean, reason?: string, signals?: object, trust?: string }} decision
+ * @returns {Promise<{ pause: boolean, reason: string, signals: object, trust: string, decidedAt: string }>}
+ *   the exact entry written (decidedAt is server-side, generated here).
+ */
+export async function persistGateDecision(featureName, gateName, { pause, reason, signals = {}, trust } = {}) {
+  const entry = {
+    pause,
+    reason: reason || (pause ? 'risco detectado' : 'nenhum sinal de risco'),
+    signals,
+    trust: trust || readTrustFromConfig(),
+    decidedAt: new Date().toISOString(),
+  };
+
+  await updateFeature(featureName, `gateDecisions.${gateName}`, entry);
+  return entry;
+}
+
 /**
  * `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>]
  * [--signals <json>] [--trust <mode>]` — record the trust decision for a gate
@@ -36,6 +69,12 @@ function readTrustFromConfig() {
  * state-sync hook rewriting the file between the agent's Read and Edit
  * ("file modified since read"). The canonical shape is documented in
  * framework/schemas/feature.schema.json and consumed by gate-guard.js.
+ *
+ * The manual escape hatch: `gate-check` (src/commands/state/gate-check.js) is
+ * the default, disk-derived path via `shouldPauseGate()`; this command stays
+ * for a caller that already knows the decision (an LLM's natural-language
+ * risk read a script can't see, or a deliberate override) — both write
+ * through {@link persistGateDecision}, so the persisted shape never diverges.
  */
 export async function gateDecisionCommand(featureName, gateName, options = {}) {
   try {
@@ -71,15 +110,12 @@ export async function gateDecisionCommand(featureName, gateName, options = {}) {
       }
     }
 
-    const entry = {
+    const entry = await persistGateDecision(featureName, gateName, {
       pause,
-      reason: options.reason || (pause ? 'risco detectado' : 'nenhum sinal de risco'),
+      reason: options.reason,
       signals,
-      trust: options.trust || readTrustFromConfig(),
-      decidedAt: new Date().toISOString(),
-    };
-
-    await updateFeature(featureName, `gateDecisions.${gateName}`, entry);
+      trust: options.trust,
+    });
 
     if (options.json) {
       console.log(JSON.stringify({ feature: featureName, gate: gateName, ...entry }, null, 2));

package/src/commands/validation/verify.js

@@ -5,6 +5,7 @@ import { getFeature, updateFeature } from '../../core/state/state-manager.js';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 import { runVerify } from '../../lib/validators/verify-runner.js';
 import { resolvePrimaryRoot } from '../project/worktree.js';
+import { getHeadSha } from '../../lib/git/default-branch.js';
 
 /** ✓ pass · ✗ fail · – skip */
 function statusIcon(status) {
@@ -160,6 +161,7 @@ export async function verifyCommand(featureName, taskId, options = {}) {
   let compact = null;
   if (persist) {
     const prevEntry = taskId ? feature.taskVerifications?.[taskId] : feature.verifications?.feature;
+    const now = new Date().toISOString();
     compact = {
       status: result.status,
       nodes: {
@@ -169,9 +171,24 @@ export async function verifyCommand(featureName, taskId, options = {}) {
       },
       score: result.nodes.validators.score ?? null,
       attempts: (prevEntry?.attempts ?? 0) + 1,
-      updatedAt: new Date().toISOString(),
+      updatedAt: now,
     };
     await updateFeature(featureName, scopeKey, compact);
+
+    // Singular, scope-agnostic "latest stamp" — distinct from the
+    // verifications/taskVerifications history above. `sha` is what lets a
+    // consumer (morph-spec gate-check) correlate this pass/fail with the
+    // EXACT commit it covers, the same way review-report.md's
+    // `**Reviewed-SHA:**` token lets approve.js detect a stale review. null
+    // in a non-git checkout (or before the first commit) — fail-open, never
+    // blocks persistence.
+    const stamp = {
+      status: result.status,
+      sha: getHeadSha(process.cwd()),
+      ts: now,
+      scope: taskId ? `task:${taskId}` : 'feature',
+    };
+    await updateFeature(featureName, 'verification', stamp);
   }
 
   if (options.json) {

package/src/core/paths/output-schema.js

@@ -37,7 +37,6 @@ export const OUTPUT_SCHEMA = {
   // 0-proposal/
   proposal:       { filename: 'proposal.md',           phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
   stackScan:      { filename: 'stack-scan.md',         phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
-  migrationPlan:  { filename: 'migration-plan.md',     phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
 
   // 1-design/ (optional)
   uiDesignSystem: { filename: 'design-system.md',      phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },

package/src/lib/agents/output-collector.js

@@ -15,7 +15,6 @@ import { OUTPUT_SCHEMA, getAbsoluteOutputPath } from '../../core/paths/output-sc
 export const SOURCE_WEIGHTS = {
   proposal:       1.0,
   stackScan:      0.8,
-  migrationPlan:  0.8,
   spec:           1.5,
   mandate:        1.3,
   tasks:          1.3,