@polymorphism-tech/morph-spec 8.5.0 → 8.7.0

package/src/commands/project/claim.js

@@ -0,0 +1,91 @@
+/**
+ * `morph-spec claim [feature] [--release] [--list]` — the manual half of
+ * advisory feature ownership (B1).
+ *
+ * Claims are acquired and heartbeaten AUTOMATICALLY (SessionStart hook +
+ * telemetry hook), so the operator never has to remember anything. This command
+ * exists for the case automation cannot cover: a session that died without
+ * releasing, leaving a claim that keeps warning everyone until its TTL expires.
+ *
+ * Read-only by default (`--list`); the only mutation is `--release`.
+ * Always exits 0 except on a genuine misuse — the claim system is advisory and
+ * must never become a source of hard failures.
+ */
+
+import chalk from 'chalk';
+import { execSync } from 'child_process';
+import { resolve } from 'path';
+import { isGitRepo, resolvePrimaryRoot } from './worktree.js';
+import { listClaims, releaseClaim, claimAge } from '../../../framework/hooks/shared/claim-registry.js';
+
+/** Resolve the repo's shared git common dir — where claims live. */
+function gitCommonDirOf(cwd) {
+  const root = resolvePrimaryRoot(cwd);
+  const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
+  return common ? resolve(root, common) : null;
+}
+
+/**
+ * @param {string|undefined} feature
+ * @param {{ release?: boolean, list?: boolean, json?: boolean, cwd?: string }} [options]
+ */
+export function claimCommand(feature, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  if (!isGitRepo(cwd)) {
+    console.log(chalk.gray('Fora de um repositório git — não há registro de claims.'));
+    process.exit(0);
+  }
+
+  let gitCommonDir = null;
+  try {
+    gitCommonDir = gitCommonDirOf(cwd);
+  } catch { gitCommonDir = null; }
+  if (!gitCommonDir) {
+    console.log(chalk.gray('Não foi possível resolver o git common dir — nenhum claim a mostrar.'));
+    process.exit(0);
+  }
+
+  if (options.release) {
+    if (!feature) {
+      console.error(chalk.red('\n❌ --release exige o nome da feature: morph-spec claim <feature> --release\n'));
+      process.exit(1);
+    }
+    const released = releaseClaim(feature, { gitCommonDir });
+    if (options.json) {
+      console.log(JSON.stringify({ feature, released }));
+      process.exit(0);
+    }
+    console.log(released
+      ? chalk.green(`\n✅ Claim de "${feature}" liberado.\n`)
+      : chalk.yellow(`\n⚠️  Nenhum claim registrado para "${feature}" — nada a liberar.\n`));
+    process.exit(0);
+  }
+
+  // Default and --list are the same read: the whole board, or one feature.
+  const all = listClaims(gitCommonDir);
+  const rows = feature ? all.filter((c) => c.feature === feature) : all;
+
+  if (options.json) {
+    console.log(JSON.stringify(rows));
+    process.exit(0);
+  }
+
+  if (!rows.length) {
+    console.log(chalk.gray(feature
+      ? `Nenhum claim para "${feature}".`
+      : 'Nenhuma feature reclamada — nenhuma sessão registrada.'));
+    process.exit(0);
+  }
+
+  const col = (s, w) => String(s ?? '-').padEnd(w);
+  console.log(chalk.white.bold(col('FEATURE', 24) + col('ESTADO', 10) + col('VISTO HÁ', 12) + col('PID', 9) + 'ONDE'));
+  for (const c of rows) {
+    const state = c.live ? chalk.yellow('viva') : chalk.gray('morta');
+    console.log(
+      col(c.feature, 24) + state + ' '.repeat(Math.max(1, 10 - (c.live ? 4 : 5)))
+      + col(claimAge(c), 12) + col(c.pid, 9) + (c.path || '-'),
+    );
+  }
+  console.log(chalk.gray('\nClaims são AVISOS, nunca bloqueios. Claim órfão: `morph-spec claim <f> --release`'));
+  process.exit(0);
+}

package/src/commands/project/doctor.js

@@ -428,7 +428,67 @@ async function doctorMcpCommand(targetPath) {
   logger.blank();
 }
 
+/**
+ * `morph-spec doctor --worktrees [--prune]` — reconcile git's worktree registry
+ * with the directories on disk and the features morph knows (C2).
+ *
+ * Orphan worktrees used to accumulate invisibly: `fleet` only reports worktrees
+ * on a `morph/*` branch, so anything else never showed up anywhere.
+ *
+ * `--prune` runs the one safe repair (`git worktree prune`: admin records for
+ * directories that are already gone). Deleting a directory that still exists is
+ * reported with the exact command, never performed — same PROVE-or-DECLINE
+ * discipline as the finish teardown.
+ */
+export async function doctorWorktreesCommand(targetPath, options = {}) {
+  const { auditWorktrees, pruneWorktrees } = await import('../../lib/worktree/worktree-audit.js');
+
+  if (options.prune) {
+    const before = auditWorktrees(targetPath).filter((i) => i.type === 'registered-missing').length;
+    const result = pruneWorktrees(targetPath);
+    if (result.pruned) logger.success(`git worktree prune: ${before} registro(s) órfão(s) removido(s).`);
+    else logger.warn(`prune falhou: ${result.error}`);
+  }
+
+  const issues = auditWorktrees(targetPath);
+
+  if (options.json) {
+    console.log(JSON.stringify({ issues }, null, 2));
+    return issues.length === 0;
+  }
+
+  logger.header('MORPH-SPEC Worktrees');
+  if (issues.length === 0) {
+    logger.success('Worktrees reconciliados — git, disco e features batem.');
+    return true;
+  }
+
+  logger.warn(`${issues.length} inconsistência(s):`);
+  for (const i of issues) {
+    console.log(`  ⚠ ${i.type}`);
+    console.log(`     ${i.detail}`);
+    console.log(`     → ${i.fix}`);
+  }
+  if (issues.some((i) => i.type === 'registered-missing') && !options.prune) {
+    logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos.');
+  }
+  return false;
+}
+
 export async function doctorCommand(options = {}) {
+  // `--json` and `--prune` only mean something under `--worktrees`. Falling
+  // through to the human health check would hand a script a banner and a table
+  // where it asked for JSON — a caller has no way to notice a flag that was
+  // dropped in silence, so refuse instead of pretending.
+  const scoped = ['json', 'prune'].filter((f) => options[f]);
+  if (scoped.length && !options.worktrees) {
+    const flags = scoped.map((f) => `--${f}`).join(' e ');
+    logger.error(`${flags} só se aplica${scoped.length > 1 ? 'm' : ''} a \`morph-spec doctor --worktrees\`.`);
+    logger.dim(`  Rode: morph-spec doctor --worktrees ${scoped.map((f) => `--${f}`).join(' ')}`);
+    process.exitCode = 1;
+    return false;
+  }
+
   // Reset mode: remove morph-managed settings entries
   if (options.reset) {
     const targetPath = process.cwd();
@@ -465,6 +525,11 @@ export async function doctorCommand(options = {}) {
     return doctorMcpCommand(process.cwd());
   }
 
+  // Worktree reconciliation mode (C2)
+  if (options.worktrees) {
+    return doctorWorktreesCommand(process.cwd(), options);
+  }
+
   const targetPath = process.cwd();
 
   logger.header('MORPH-SPEC Health Check');

package/src/commands/project/fleet.js

@@ -12,6 +12,7 @@
 
 import chalk from 'chalk';
 import { scanFleet } from '../../lib/worktree/fleet-scanner.js';
+import { claimAge } from '../../../framework/hooks/shared/claim-registry.js';
 
 /**
  * @param {{ json?: boolean, cwd?: string }} [options]
@@ -30,9 +31,33 @@ export function fleetCommand(options = {}) {
   }
 
   const col = (s, w) => String(s ?? '-').padEnd(w);
+
+  /**
+   * The REMOTO cell. `-` means "unknown" (no origin, or the probe failed) —
+   * deliberately the same glyph as "nothing there", because both mean "do not
+   * trust the local view alone". `local` is the confident negative.
+   */
+  const remoteCell = (r) => {
+    if (!r) return '-';
+    if (r.pr) return `PR #${r.pr.number}${r.pr.state && r.pr.state !== 'OPEN' ? ` (${r.pr.state.toLowerCase()})` : ''}`;
+    return r.pushed ? 'pushed' : 'local';
+  };
+
+  /**
+   * The CLAIM cell — who is on this feature right now (B1). A stale claim is
+   * shown as stale, not hidden: "nobody here" and "somebody died here" are
+   * different facts for the operator.
+   */
+  const claimCell = (c) => {
+    if (!c) return '-';
+    const age = claimAge(c);
+    return c.live ? chalk.yellow(`sessão (${age})`) : chalk.gray(`morta (${age})`);
+  };
+
   console.log(chalk.white.bold(
     col('FEATURE', 20) + col('TYPE', 9) + col('PHASE', 11) + col('TASKS', 8)
-    + col('GATES PEND.', 20) + col('WHERE', 24) + col('PORTS', 12) + col('HANDOFF', 9) + 'ATIVIDADE',
+    + col('GATES PEND.', 20) + col('WHERE', 24) + col('REMOTO', 16) + col('CLAIM', 16)
+    + col('PORTS', 12) + col('HANDOFF', 9) + 'ATIVIDADE',
   ));
   for (const e of fleet.entries) {
     const tasks = e.tasks ? `${e.tasks.done}/${e.tasks.total}` : '-';
@@ -44,11 +69,21 @@ export function fleetCommand(options = {}) {
       e.lastCommit ? `commit ${e.lastCommit}` : null,
       Number.isInteger(e.dirty) && e.dirty > 0 ? chalk.yellow(`${e.dirty} dirty`) : null,
     ].filter(Boolean).join(' · ') || '-';
+    // padEnd counts invisible color codes, so pad the claim cell on its plain
+    // length and append the padding by hand.
+    const claimPlain = e.claim ? `${e.claim.live ? 'sessão' : 'morta'} (${claimAge(e.claim)})` : '-';
     console.log(
       col(e.feature, 20) + col(e.workType || '-', 9) + col(e.phase, 11) + col(tasks, 8)
-      + col(gates, 20) + col(where, 24) + col(ports, 12) + col(handoff, 9) + activity,
+      + col(gates, 20) + col(where, 24) + col(remoteCell(e.remote), 16)
+      + claimCell(e.claim) + ' '.repeat(Math.max(1, 16 - claimPlain.length))
+      + col(ports, 12) + col(handoff, 9) + activity,
     );
   }
+  const claimed = fleet.entries.filter((e) => e.claim?.live);
+  if (claimed.length) {
+    console.log(chalk.yellow(`\n⚠ ${claimed.length} feature(s) com sessão ativa — confirme antes de finish/archive/delete.`));
+    console.log(chalk.gray("   Claim órfão de sessão morta: `morph-spec claim <f> --release`"));
+  }
   console.log(chalk.gray(`\nRaiz primária: ${fleet.root}`));
   process.exit(0);
 }

package/src/commands/project/worktree.js

@@ -1,7 +1,7 @@
 /**
  * MORPH-SPEC Worktree Command Suite
  *
- * Isolates feature work into per-feature git worktrees at .worktrees/{feature}/
+ * Isolates feature work into per-feature git worktrees at worktrees/{feature}/
  * on branch morph/{feature}, so each feature can run its own Claude Code
  * instance (v8 multi-instance, parallel-feature-development flow).
  *
@@ -34,6 +34,31 @@ import { execSync, execFileSync } from 'child_process';
 import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, readdirSync, cpSync } from 'fs';
 import { join, resolve, dirname, relative } from 'path';
 import chalk from 'chalk';
+import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+
+/**
+ * The directory new worktrees are created under, relative to the primary root.
+ *
+ * NO leading dot, deliberately (C1). Jest escapes the `.` when it interpolates
+ * an absolute `rootDir` into the `testMatch` glob, so `<root>/.worktrees/...`
+ * stops matching and an entire frontend suite reports **0 tests without an
+ * error** — the suite "passes" having tested nothing. The dot bought nothing:
+ * the directory is gitignored either way.
+ */
+export const WORKTREES_DIR = 'worktrees';
+
+/**
+ * The pre-C1 directory name. New worktrees never land here, but every reader
+ * that resolves worktrees BY CONVENTION must still accept it, so a machine
+ * that already had `.worktrees/{f}` keeps working with no manual migration.
+ *
+ * Readers that go through `git worktree list` (fleet, finish, worktree list)
+ * were never affected — git records absolute paths, not this convention.
+ */
+export const LEGACY_WORKTREES_DIR = '.worktrees';
+
+/** Both names, new first — the read order for convention-based lookups. */
+export const WORKTREE_DIR_NAMES = [WORKTREES_DIR, LEGACY_WORKTREES_DIR];
 
 // ── Pure helpers (exported for tests) ──────────────────────────────────────
 
@@ -47,7 +72,7 @@ import chalk from 'chalk';
  *
  * Mirrors the validation `morph-spec create` applies, and every worktree
  * subcommand enforces it for the same reason plus a sharper one: a feature name
- * flows into `.worktrees/{name}`, the branch `morph/{name}`, and from there into
+ * flows into `worktrees/{name}`, the branch `morph/{name}`, and from there into
  * git invocations. Characters like `& | ; > ^` are legal in a git refname but
  * are cmd.exe metacharacters — on Windows an unvalidated name turns any
  * string-interpolated git call into command injection, and makes a `finish`
@@ -121,7 +146,7 @@ export function worktreeExists(worktreePath, cwd = process.cwd()) {
 export function buildWorktreePath(feature, cwd = process.cwd(), options = {}) {
   const suffix = options.fresh ? `-${getDateSuffix()}` : '';
   const normalizedCwd = cwd.replace(/\\/g, '/');
-  return `${normalizedCwd}/.worktrees/${feature}${suffix}`;
+  return `${normalizedCwd}/${WORKTREES_DIR}/${feature}${suffix}`;
 }
 
 /**
@@ -421,14 +446,29 @@ export async function runWorktreeSetup(feature, options = {}) {
     }
   } catch { /* fail-open — malformed feature.json must never block setup */ }
 
+  let branchedFrom = null;
   try {
-    // Create branch if needed (based off current HEAD)
+    // Create branch if needed — off the DEFAULT branch, never the current HEAD.
+    // Branching from HEAD meant a root parked on some other `morph/{other}`
+    // gave the new feature that feature's commits, and every PR opened from
+    // this worktree carried the sibling's diff (A1). Symmetric with the common
+    // flow in create.js → branchCommonFlow.
+    //
+    // Fail-open, same as create: with no resolvable default (a repo whose
+    // default is neither `main`/`master` nor declared via origin/HEAD) the
+    // branch is still created — off HEAD — and `branchedFrom: null` reports it.
     if (!branchExists(branch, cwd)) {
-      execSync(`git branch ${branch}`, { cwd, stdio: 'pipe' });
+      const defaultBranch = detectDefaultBranch(cwd);
+      if (defaultBranch) {
+        execFileSync('git', ['branch', branch, defaultBranch], { cwd, stdio: 'pipe' });
+        branchedFrom = defaultBranch;
+      } else {
+        execFileSync('git', ['branch', branch], { cwd, stdio: 'pipe' });
+      }
     }
 
     // Create worktree directory parent if needed
-    const parentDir = join(cwd, '.worktrees');
+    const parentDir = join(cwd, WORKTREES_DIR);
     if (!existsSync(parentDir)) {
       mkdirSync(parentDir, { recursive: true });
     }
@@ -500,6 +540,7 @@ export async function runWorktreeSetup(feature, options = {}) {
       created: true,
       path: worktreePath,
       branch,
+      branchedFrom,
       feature,
       materialized: materialized.materialized,
       ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
@@ -1065,7 +1106,13 @@ async function clearRootWorktreeRegistration(root, feature) {
 export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true }) {
   // Drop the infra junctions FIRST, without following them — this is what makes
   // a removal survivable (see unlinkWorktreeInfraLinks). Runs unconditionally.
-  unlinkWorktreeInfraLinks(worktreePath, root);
+  //
+  // The ORDER IS LOAD-BEARING and must not be flipped: `git worktree remove`
+  // (and its --force fallback) follows reparse points OUT of the worktree and
+  // deletes the primary root's real `.claude/` and `.morph/framework/`.
+  // Whatever this unlink costs on a declined path is repaired by the rollback
+  // below — the reverse ordering has no repair, it destroys the installation.
+  const unlinked = unlinkWorktreeInfraLinks(worktreePath, root);
 
   const scan = findReparsePoints(worktreePath);
   const ignored = classifyIgnoredLeftovers(worktreePath, options);
@@ -1114,6 +1161,21 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     await clearRootWorktreeRegistration(root, feature);
   }
 
+  // Rollback (A4): the removal was refused or failed, so the worktree is still
+  // there — but without the junctions this function dropped up front, which is
+  // strictly worse than never having tried (the observed complaint: "um estado
+  // pior que não ter tentado"). Put them back so the worktree stays usable and
+  // the user can just re-run finish from the primary root. Fail-open: a failed
+  // re-link reports `relinked: false` and the caller falls back to telling the
+  // user to run `morph-spec worktree link --all`.
+  let relinked = false;
+  if (!worktreeRemoved && unlinked.length && existsSync(worktreePath)) {
+    try {
+      setupInfraLinks(worktreePath, root);
+      relinked = true;
+    } catch { relinked = false; }
+  }
+
   const declineReason = worktreeRemoved
     ? null
     : ignored.blocking.length
@@ -1132,6 +1194,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     ignoredBlocking: ignored.blocking,
     shieldable: ignored.shieldable,
     declineReason,
+    relinked,
   };
 }
 

package/src/commands/state/advance.js

@@ -1,8 +1,12 @@
 import chalk from 'chalk';
-import { existsSync, mkdirSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { fileURLToPath } from 'url';
 import { getFeature, setApprovalGate, derivePhase } from '../../core/state/state-manager.js';
 import { unmetPrereqs } from '../../core/state/gate-order.js';
+import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
+
+const FRAMEWORK_DIR = fileURLToPath(new URL('../../../framework/', import.meta.url));
 
 /**
  * `morph-spec advance <feature>` — approve the current phase's gate AND scaffold
@@ -28,6 +32,41 @@ const NEXT_PHASE_DIR = {
   implement: '4-review',
 };
 
+/**
+ * The canonical artifacts the phase being CLOSED owes, per
+ * `framework/phases.json → phases[phase].requiredOutputs`, resolved to real
+ * filenames through OUTPUT_SCHEMA.
+ *
+ * Data-driven on purpose: adding an artifact to a phase must not need a code
+ * change here, and the list must never drift from the phase definition.
+ * Fail-open — an unreadable phases.json/OUTPUT_SCHEMA yields an empty list, so
+ * a broken install degrades to today's behaviour instead of blocking every
+ * advance.
+ *
+ * @param {string} phase
+ * @param {string} featurePath
+ * @returns {string[]} relative paths of the MISSING required artifacts
+ */
+function missingPhaseArtifacts(phase, featurePath) {
+  try {
+    const phasesPath = join(FRAMEWORK_DIR, 'phases.json');
+    const phases = JSON.parse(readFileSync(phasesPath, 'utf8')).phases || {};
+    const required = phases[phase]?.requiredOutputs || [];
+    const missing = [];
+    for (const outputType of required) {
+      // requiredOutputs already carries OUTPUT_SCHEMA's camelCase keys — an
+      // unknown key is skipped rather than guessed at.
+      const entry = OUTPUT_SCHEMA[outputType];
+      if (!entry?.filename || !entry?.phaseDir) continue;
+      const rel = `${entry.phaseDir}/${entry.filename}`;
+      if (!existsSync(join(featurePath, entry.phaseDir, entry.filename))) missing.push(rel);
+    }
+    return missing;
+  } catch {
+    return [];
+  }
+}
+
 /** Resolve who approved, honestly (mirrors approve.js — no fake human signatures). */
 function resolveApprovedBy(options) {
   if (options.approver) return options.approver;
@@ -54,6 +93,23 @@ export async function advanceCommand(featureName, options = {}) {
       return;
     }
 
+    // Phase-exit artifact check (D3): a phase transition must not step over the
+    // artifact the phase it is CLOSING owes. Observed: a feature reached review
+    // with NO 3-implement/recap.md — the file was written later, by hand, so
+    // the Gate 3 review had nothing to review. `implement` has no gate, which
+    // is precisely why nothing stopped it.
+    //
+    // `--force` bypasses (same deliberate-recovery role it already plays for
+    // gate order) but still names what was skipped — a silent bypass would be
+    // the defect again.
+    const missingArtifacts = missingPhaseArtifacts(phase, featurePath);
+    if (missingArtifacts.length && !options.force) {
+      console.error(chalk.red(`\n❌ A fase "${phase}" não pode ser encerrada — artefato(s) obrigatório(s) ausente(s):`));
+      for (const rel of missingArtifacts) console.error(chalk.gray(`   • ${rel}`));
+      console.error(chalk.gray('\n   Produza o artefato e rode de novo, ou passe --force para avançar assim mesmo.\n'));
+      process.exit(1);
+    }
+
     // 1) Approve the gate that completes the current phase.
     const gate = PHASE_GATE[phase];
     const approvedBy = resolveApprovedBy(options);
@@ -112,6 +168,9 @@ export async function advanceCommand(featureName, options = {}) {
     } catch { /* fail-open */ }
 
     console.log(chalk.green(`\n✅ Advanced "${featureName}" past the ${phase} phase.`));
+    if (missingArtifacts.length) {
+      console.log(chalk.yellow(`   ⚠️  --force: avançou SEM ${missingArtifacts.join(', ')}.`));
+    }
     if (gate) console.log(chalk.gray(`   Gate "${gate}" approved (${approvedBy}).`));
     if (nextDir) console.log(chalk.gray(`   Scaffolded ${nextDir}/ — ready for the next phase's first artifact.\n`));
     else console.log('');

package/src/commands/state/approve.js

@@ -1,10 +1,73 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { existsSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { getFeature, setApprovalGate, getApprovalGate, getApprovalHistory, derivePhase } from '../../core/state/state-manager.js';
 import { unmetPrereqs } from '../../core/state/gate-order.js';
 
+/**
+ * The literal token `review-report.md` carries to declare which tree it
+ * reviewed. Kept as one exported constant so the CLI parser, the warning text
+ * and the `morph-review` skill can never drift apart (the A5 lesson).
+ */
+export const REVIEWED_SHA_TOKEN = '**Reviewed-SHA:**';
+
+const REVIEWED_SHA_RE = /\*\*Reviewed-SHA:\*\*\s*([0-9a-f]{7,40})/i;
+
+/**
+ * Is the feature's `review-report.md` still describing the current tree?
+ *
+ * @param {string} featureName
+ * @returns {{ status: 'ok'|'stale'|'unstamped'|'skip', reviewed?: string, head?: string, ahead?: number }}
+ *   `skip` covers every case where the question cannot be answered honestly:
+ *   no report, no git repo, an unresolvable SHA. Never a false refusal.
+ */
+function reviewStaleness(featureName) {
+  const cwd = process.cwd();
+  const reportPath = join(cwd, '.morph', 'features', featureName, '4-review', 'review-report.md');
+  if (!existsSync(reportPath)) return { status: 'skip' };
+
+  let head;
+  try {
+    head = execFileSync('git', ['rev-parse', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
+  } catch {
+    return { status: 'skip' }; // not a git repo (or no commits) — nothing to compare
+  }
+
+  let body = '';
+  try {
+    body = readFileSync(reportPath, 'utf8');
+  } catch {
+    return { status: 'skip' };
+  }
+
+  const stamped = body.match(REVIEWED_SHA_RE)?.[1];
+  if (!stamped) return { status: 'unstamped', head };
+
+  let reviewed;
+  try {
+    reviewed = execFileSync('git', ['rev-parse', '--verify', `${stamped}^{commit}`], { cwd, stdio: 'pipe' })
+      .toString().trim();
+  } catch {
+    // A stamp git cannot resolve (rewritten history, a typo) is not evidence
+    // of staleness — say "unstamped" rather than block on a guess.
+    return { status: 'unstamped', head };
+  }
+  if (reviewed === head) return { status: 'ok', reviewed, head };
+
+  let ahead = 0;
+  try {
+    ahead = execFileSync('git', ['rev-list', '--count', `${reviewed}..${head}`], { cwd, stdio: 'pipe' })
+      .toString().trim();
+    ahead = Number(ahead) || 0;
+  } catch { ahead = 0; }
+
+  // HEAD not descending from the reviewed commit (a rebase, a different branch)
+  // is still "not the tree that was reviewed".
+  return { status: 'stale', reviewed, head, ahead };
+}
+
 /**
  * Unapprove action function - Revoke a previously approved gate
  */
@@ -155,12 +218,72 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
+    // Gate 3 evaluator backstop: the composite score of a feature comes from
+    // the INDEPENDENT evaluator (persona `evaluator`, fresh context) dispatched
+    // by morph-review — never from self-assessment by whoever implemented it.
+    // Nothing enforced that. When the dispatch was impossible (observed: a
+    // session instruction forbade sub-agents), the flow still produced a
+    // review-report.md carrying a composite score and a verdict, with a caveat
+    // in prose nobody is obliged to read. A gate that yields a grade without
+    // its evaluator is not a gate.
+    //
+    // The escape hatch is EXPLICIT and RECORDED (`--self-assessed`), never
+    // silent — the silence is the defect. `--force` deliberately does NOT
+    // bypass this: it is the out-of-order recovery flag, a different concern.
+    // Gate 3 staleness backstop (D1): a review reviews a TREE, and the tree
+    // moves. Observed: review-report.md written at b30ac6e, then T3 landed and
+    // inverted the default of a business rule; the report stayed in the repo
+    // claiming 976/976 tests (they were 982) and never mentioning T3. Nothing
+    // detected that the review artifact had fallen behind the code it reviews.
+    //
+    // The report stamps the SHA it reviewed; approval compares it with HEAD.
+    // A stamp that is BEHIND HEAD refuses. A MISSING stamp only warns — reports
+    // written before this existed must not brick a legacy feature — but the
+    // warning names the exact token to add, so it teaches instead of nagging.
+    if (gateName === 'review') {
+      const stale = reviewStaleness(featureName);
+      if (stale.status === 'stale') {
+        console.error(chalk.red('\n❌ O `4-review/review-report.md` está desatualizado em relação ao código.'));
+        console.error(chalk.gray(`   Revisado em: ${stale.reviewed.slice(0, 8)}`));
+        console.error(chalk.gray(`   HEAD atual:  ${stale.head.slice(0, 8)}${stale.ahead ? ` (${stale.ahead} commit(s) depois da revisão)` : ''}`));
+        console.error(chalk.gray('   Um review revisa uma ÁRVORE, e a árvore andou. Re-rode a `morph-review`'));
+        console.error(chalk.gray('   (incluindo o avaliador independente) e atualize o `**Reviewed-SHA:**`.\n'));
+        process.exit(1);
+      }
+      if (stale.status === 'unstamped') {
+        console.log(chalk.yellow('\n⚠️  O `review-report.md` não carrega `**Reviewed-SHA:**` — impossível saber se ele revisa o código atual.'));
+        console.log(chalk.gray(`   Adicione a linha \`**Reviewed-SHA:** ${stale.head}\` ao relatório para que o Gate 3 possa verificar.`));
+      }
+    }
+
+    let selfAssessed = false;
+    if (gateName === 'review') {
+      const evaluatorReport = join(process.cwd(), '.morph', 'features', featureName, '4-review', 'evaluator-report.md');
+      if (!existsSync(evaluatorReport)) {
+        if (!options.selfAssessed) {
+          console.error(chalk.red('\n❌ Gate 3 exige o avaliador independente — `4-review/evaluator-report.md` não existe.'));
+          console.error(chalk.gray('   O score composto da feature vem do avaliador (persona `evaluator`, contexto fresco)'));
+          console.error(chalk.gray('   despachado pela morph-review, nunca de auto-avaliação de quem implementou.'));
+          console.error(chalk.gray('   Se o dispatch for impossível nesta sessão, aprove com --self-assessed —'));
+          console.error(chalk.gray('   a degradação fica registrada no feature.json e aparece no `list`/`fleet`.\n'));
+          process.exit(1);
+        }
+        selfAssessed = true;
+      }
+    }
+
     await setApprovalGate(featureName, gateName, true, {
       approvedBy,
       approvedAt: new Date().toISOString(),
-      notes: options.notes
+      notes: options.notes,
+      ...(selfAssessed ? { selfAssessed: true } : {}),
     });
 
+    if (selfAssessed) {
+      console.log(chalk.yellow('\n⚠️  Gate 3 aprovado SEM avaliador independente (--self-assessed).'));
+      console.log(chalk.gray('   Registrado em feature.json → approvalGates.review.selfAssessed.'));
+    }
+
     console.log(chalk.green(`\n✅ Gate "${gateName}" approved for feature: ${featureName}`));
     console.log(chalk.gray(`Workflow can now proceed past ${gateName} phase\n`));