@polymorphism-tech/morph-spec 8.6.0 → 8.7.0

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`));
 

package/src/commands/state/create.js

@@ -186,9 +186,9 @@ export async function createCommand(featureName, options = {}) {
         if (worktreeResult?.created && worktreeResult.path) {
           try {
             // feature.json in the root is NOT committed yet (create just
-            // wrote it), so the branch `runWorktreeSetup` checked out from
-            // HEAD does not have it — copy the freshly-scaffolded folder
-            // into the worktree and re-materialize its local state.json.
+            // wrote it), so the branch `runWorktreeSetup` forked off the
+            // DEFAULT branch cannot have it — copy the freshly-scaffolded
+            // folder into the worktree and re-materialize its local state.json.
             cpSync(featureDir, join(worktreeResult.path, '.morph', 'features', featureName), { recursive: true });
             // The `.worktree` registration is ROOT-OWNED metadata (runWorktreeSetup
             // stamped it onto the root's feature.json, which cpSync just copied in).

package/src/commands/state/finish.js

@@ -12,8 +12,50 @@ import {
   branchExists,
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
+import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
 import { runArchive } from './archive.js';
 
+/** workType → conventional-commit type. `hotfix` IS a fix; anything else is a chore. */
+const PR_TYPE_BY_WORK_TYPE = { feature: 'feat', bug: 'fix', hotfix: 'fix', chore: 'chore' };
+
+/** Git's soft limit for a subject line. */
+const PR_TITLE_MAX = 72;
+
+/**
+ * The PR title for `finish --pr`.
+ *
+ * Was always `morph: {slug}` — so every PR in a repo whose hand-made ones follow
+ * conventional commits (`fix(ui): coluna CRM nos dossiês…`) arrived shapeless
+ * and said nothing about what changed (D4).
+ *
+ * Now: `{type}({slug}): {subject}` — the type from the feature's `workType`, the
+ * slug kept as the scope (it is the traceability the old title at least had),
+ * and the subject from the feature's own identity: `name` first (a human
+ * deliberately titled it), then `description`, first line only. With neither,
+ * degrade to `{type}: {slug}` rather than emit an empty subject.
+ *
+ * @param {string} feature
+ * @param {object|null} fj - the feature.json
+ * @returns {string}
+ */
+export function buildPrTitle(feature, fj) {
+  const type = PR_TYPE_BY_WORK_TYPE[fj?.workType] || 'chore';
+
+  const named = typeof fj?.name === 'string' ? fj.name.trim() : '';
+  // The default `name` IS the slug (create stamps it), which as a subject would
+  // only repeat the scope — treat it as absent.
+  const described = typeof fj?.description === 'string' ? fj.description.trim() : '';
+  const raw = (named && named !== feature ? named : described).split('\n')[0].trim();
+  if (!raw) return `${type}: ${feature}`;
+
+  const prefix = `${type}(${feature}): `;
+  const room = PR_TITLE_MAX - prefix.length;
+  // A scope so long there is no room left for a subject: drop the scope rather
+  // than ship a title that is all prefix.
+  if (room < 12) return `${type}: ${raw}`.slice(0, PR_TITLE_MAX);
+  return prefix + (raw.length <= room ? raw : `${raw.slice(0, room - 1)}…`);
+}
+
 /**
  * `morph-spec finish <feature> --pr|--merge` — the single, symmetric close of a
  * feature's lifecycle, for BOTH the worktree flow and the common flow.
@@ -37,9 +79,22 @@ import { runArchive } from './archive.js';
 export async function finishCommand(feature, options = {}) {
   const cwd = options.cwd || process.cwd();
   const root = resolvePrimaryRoot(cwd);
-  const emit = (obj) => console.log(JSON.stringify(obj));
   const rootNorm = resolve(root).replace(/\\/g, '/');
 
+  // A closed feature must not keep warning other sessions that someone is
+  // working on it (B1). Released on EVERY success path — hooking it into emit
+  // is the single point that covers merge/PR/--keep alike. Fail-open: a claim
+  // that outlives its feature only expires on its own TTL.
+  const emit = (obj) => {
+    if (obj?.finished === true) {
+      try {
+        const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
+        if (common) releaseClaim(feature, { gitCommonDir: resolve(root, common) });
+      } catch { /* fail-open */ }
+    }
+    console.log(JSON.stringify(obj));
+  };
+
   // Gate 0: valid kebab name — anti command-injection (the name flows into every
   // git/gh call below) and the same gate the worktree path always applied.
   if (!isValidFeatureName(feature)) {
@@ -85,6 +140,28 @@ export async function finishCommand(feature, options = {}) {
     }
     worktreePath = found.path;
     featureCwd = worktreePath;
+
+    // Validation 0b: the session's cwd must not be INSIDE the worktree we are
+    // about to tear down (A4). Windows holds a lock on the process's working
+    // directory, so `git worktree remove` fails — and by then the archive is
+    // committed, the branch merged, and the infra junctions already dropped.
+    // The result is a worse state than never having tried: an orphan directory,
+    // a de-registered worktree, and a `relinkHint` telling the user to repair
+    // by hand. Refuse HERE, before the first mutation — the cost is one
+    // `cd`, and it is the exact failure observed in the ProspectPRO session.
+    const cwdNorm = resolve(cwd).replace(/\\/g, '/');
+    const wtNorm = resolve(worktreePath).replace(/\\/g, '/');
+    if (cwdNorm === wtNorm || cwdNorm.startsWith(`${wtNorm}/`)) {
+      emit({
+        finished: false,
+        error: 'cwd-inside-worktree',
+        feature,
+        path: worktreePath,
+        root,
+        hint: `saia do worktree antes do finish — o \`git worktree remove\` não consegue apagar o diretório de trabalho do próprio processo. Rode de novo a partir de "${root}"`,
+      });
+      process.exit(1);
+    }
   } else {
     // COMMON flow: the feature branch must exist and be the ROOT's current
     // branch (so the archive commits on it and we can checkout the default to
@@ -120,7 +197,7 @@ export async function finishCommand(feature, options = {}) {
     emit({ finished: false, error: 'review-not-approved', feature });
     process.exit(1);
   }
-  const prTitle = `morph: ${feature}`;
+  const prTitle = buildPrTitle(feature, fj);
   const prBody = (fj?.description && String(fj.description).trim())
     ? String(fj.description).trim()
     : `Feature ${feature} — integrada via morph-spec finish --pr.`;
@@ -346,7 +423,15 @@ function teardownExtras(teardown, worktreePath, branch, deleteBranch) {
     if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
     if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
     out.cleanupHint = teardown.declineReason;
-    out.relinkHint = `as junctions de infra foram soltas antes desta recusa — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+    // The unlink runs before the removal by design (it is what keeps `git
+    // worktree remove` from following the junctions out into the primary root),
+    // so a declined removal always passes through a moment with the infra
+    // loose. The teardown now re-links on that path — report which of the two
+    // actually happened instead of always announcing the worse one (A4).
+    out.relinked = teardown.relinked === true;
+    out.relinkHint = teardown.relinked
+      ? 'as junctions de infra foram soltas antes da tentativa e RESTAURADAS após a recusa — o worktree segue utilizável'
+      : `as junctions de infra foram soltas antes desta recusa e não puderam ser restauradas — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
   }
   return out;
 }

package/src/commands/state/list.js

@@ -44,8 +44,14 @@ function buildRow(name, fj, fdir, location) {
   const gates = {};
   for (const g of G) gates[g] = fj.approvalGates?.[g]?.approved === true;
 
+  // Gate 3 approved WITHOUT the independent evaluator (`approve --self-assessed`).
+  // A recorded degradation is only worth recording if it is visible — this is
+  // the surface that makes it so (D2).
+  const selfAssessed = fj.approvalGates?.review?.selfAssessed === true;
+
   const flags = [];
   if (fj.__corrupt) flags.push('corrupt');
+  if (selfAssessed) flags.push('self-assessed-g3');
   // Identity + gate-order anomalies come from the shared rules
   // (core/state/feature-identity.js, core/state/gate-order.js) — same source
   // doctor reports from.
@@ -60,6 +66,7 @@ function buildRow(name, fj, fdir, location) {
     status: fj.status || 'unknown',
     phase: location === 'archived' ? 'archived' : derivePhase(fdir),
     gates,
+    selfAssessed,
     flags,
     location,
     createdAt: fj.createdAt || null,
@@ -93,7 +100,8 @@ export function listCommand(options = {}) {
   ));
   for (const r of rows) {
     const flag = r.flags.length ? chalk.yellow('⚠') : ' ';
-    const desc = r.description ? truncate(r.description, 44) : chalk.yellow('(sem descrição)');
+    const desc = (r.selfAssessed ? chalk.yellow('[G3 self-assessed] ') : '')
+      + (r.description ? truncate(r.description, 44) : chalk.yellow('(sem descrição)'));
     // padEnd counts the invisible color codes; pad the plain marks manually.
     console.log(
       col(r.feature, 22) + col(r.workType, 9) + col(r.status, 13) + col(r.phase, 11)

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

@@ -0,0 +1,202 @@
+/**
+ * `morph-spec report-check <feature> [task] [--json]` — the deterministic half
+ * of the missing-report protocol (B4).
+ *
+ * MORPH.md already made the sub-agent's canonical report file the authoritative
+ * return value ("o ARQUIVO é o retorno, a última mensagem é cortesia"), but it
+ * never said what to do when the file is not there. The naive reading — "no
+ * report, so the agent failed" — is wrong and expensive: the agent may have
+ * done every bit of the work and lost the means to record it (observed: a
+ * worktree removed out from under a running sub-agent).
+ *
+ * So this command answers the question the orchestrator actually has, and
+ * answers it from evidence rather than from the agent's own word: **did the
+ * WORK land, independently of whether the REPORT did?**
+ *
+ *   verdict                          action
+ *   ─────────────────────────────    ──────────────────
+ *   ok                               proceed
+ *   report-incomplete                complete-degraded
+ *   work-landed-report-missing       accept-degraded
+ *   no-work-no-report                redispatch
+ *   report-missing-evidence-unknown  redispatch   (conservative default)
+ *
+ * Exit 0 only for `ok` — anything needing an action exits non-zero so a caller
+ * can branch on it. `--json` always prints the machine-readable verdict.
+ */
+
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * The four mandatory items of the report contract, as detectable markers.
+ *
+ * HEURISTIC BY CONSTRUCTION, and deliberately loose: the contract asks for
+ * content, not for a fixed template, and reports written before this command
+ * existed must still audit cleanly. A false "complete" is the cheap error here
+ * (the orchestrator reads the report anyway); a false "incomplete" would send
+ * it re-dispatching finished work, which is the expensive one.
+ */
+const REPORT_MARKERS = [
+  // (2) files touched — a list line carrying a path or a backticked identifier
+  { id: 'files', re: /^\s*[-*]\s+.*[`/\\].*$/m },
+  // (4) self-score 0-10
+  { id: 'score', re: /score[^\n]*?\b(10|\d)(?:[.,]\d+)?\b/i },
+  // (3) problems found (or an explicit "none")
+  { id: 'problems', re: /problema|issue|blocker|nenhum|impedimento/i },
+];
+
+/** (1) "what was done" — prose beyond the structural markers. */
+const MIN_PROSE_CHARS = 80;
+
+function reportPath(cwd, feature, taskId) {
+  return join(cwd, '.morph', 'features', feature, '3-implement', 'reports', `${taskId}.md`);
+}
+
+function evaluatorPath(cwd, feature) {
+  return join(cwd, '.morph', 'features', feature, '4-review', 'evaluator-report.md');
+}
+
+/**
+ * Inspect one report file: does it exist, and which of the four mandatory
+ * items can be found in it.
+ */
+export function inspectReport(path) {
+  if (!existsSync(path)) return { exists: false, complete: false, missing: ['what', 'files', 'problems', 'score'] };
+  let body = '';
+  try {
+    body = readFileSync(path, 'utf8');
+  } catch {
+    return { exists: true, complete: false, missing: ['what', 'files', 'problems', 'score'], unreadable: true };
+  }
+
+  const missing = REPORT_MARKERS.filter((m) => !m.re.test(body)).map((m) => m.id);
+  // Prose = the body minus headings and list lines, so a bare file list does
+  // not pass as "what was done".
+  const prose = body
+    .split('\n')
+    .filter((l) => !/^\s*(#|[-*]\s)/.test(l))
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (prose.length < MIN_PROSE_CHARS) missing.unshift('what');
+
+  return { exists: true, complete: missing.length === 0, missing };
+}
+
+/** How many of a task's declared outputs actually exist on disk. */
+function outputEvidence(cwd, taskOutputs) {
+  const expected = Array.isArray(taskOutputs) ? taskOutputs : [];
+  const present = expected.filter((rel) => {
+    try {
+      return existsSync(join(cwd, rel));
+    } catch {
+      return false;
+    }
+  }).length;
+  return { outputsExpected: expected.length, outputsPresent: present };
+}
+
+/** Combine report state + evidence into a verdict and the action it implies. */
+function decide(report, evidence) {
+  if (report.exists && report.complete) return { verdict: 'ok', action: 'proceed' };
+  if (report.exists) return { verdict: 'report-incomplete', action: 'complete-degraded' };
+  if (evidence.outputsExpected === 0) {
+    // No declared outputs means no evidence either way. Re-dispatching costs a
+    // sub-agent; silently accepting a phantom completion costs correctness.
+    return { verdict: 'report-missing-evidence-unknown', action: 'redispatch' };
+  }
+  return evidence.outputsPresent > 0
+    ? { verdict: 'work-landed-report-missing', action: 'accept-degraded' }
+    : { verdict: 'no-work-no-report', action: 'redispatch' };
+}
+
+function checkTask(cwd, feature, task) {
+  const report = inspectReport(reportPath(cwd, feature, task.id));
+  const evidence = outputEvidence(cwd, task.outputs);
+  return { task: task.id, report, evidence, ...decide(report, evidence) };
+}
+
+const ACTION_HINT = {
+  proceed: 'relatório íntegro — siga o fluxo normal.',
+  'complete-degraded': 'complete os itens faltantes a partir da mensagem de retorno do sub-agent, carimbe o relatório como DEGRADADO e registre a falha de protocolo no recap.',
+  'accept-degraded': 'o TRABALHO entrou — não re-despache. Grave você mesmo o relatório canônico a partir da mensagem de retorno, carimbado como DEGRADADO, e registre a falha de protocolo no recap e nas `notes` da task.',
+  redispatch: 're-despache a task UMA vez com o mesmo prompt. Segunda ausência sem trabalho entregue = falha real: escale ao humano.',
+};
+
+/**
+ * @param {string} feature
+ * @param {string|undefined} taskId
+ * @param {{ json?: boolean, cwd?: string }} [options]
+ */
+export function reportCheckCommand(feature, taskId, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const emit = (obj, code) => {
+    if (options.json) console.log(JSON.stringify(obj, null, 2));
+    else printHuman(obj);
+    process.exit(code);
+  };
+
+  const tasksPath = join(cwd, '.morph', 'features', feature, '2-plan', 'tasks.json');
+  if (!existsSync(tasksPath)) {
+    emit({ error: `feature "${feature}" não tem 2-plan/tasks.json — nada a auditar`, feature }, 1);
+  }
+
+  let tasks = [];
+  try {
+    const parsed = JSON.parse(readFileSync(tasksPath, 'utf8'));
+    tasks = Array.isArray(parsed.tasks) ? parsed.tasks : [];
+  } catch {
+    emit({ error: `2-plan/tasks.json de "${feature}" está corrompido`, feature }, 1);
+  }
+
+  if (taskId) {
+    const task = tasks.find((t) => t.id === taskId);
+    if (!task) emit({ error: `task "${taskId}" não existe em tasks.json`, feature }, 1);
+    const result = checkTask(cwd, feature, task);
+    emit({ feature, ...result, hint: ACTION_HINT[result.action] }, result.verdict === 'ok' ? 0 : 1);
+  }
+
+  // Whole-feature audit: every DONE task owes a report; a pending one does not.
+  const results = tasks.filter((t) => t.status === 'done').map((t) => checkTask(cwd, feature, t));
+  const evaluator = inspectReport(evaluatorPath(cwd, feature));
+  const clean = results.every((r) => r.verdict === 'ok');
+  emit({ feature, results, evaluator, clean }, clean ? 0 : 1);
+}
+
+function printHuman(obj) {
+  if (obj.error) {
+    console.error(chalk.red(`\n❌ ${obj.error}\n`));
+    return;
+  }
+  const line = (r) => {
+    const icon = r.verdict === 'ok' ? chalk.green('✓') : chalk.yellow('⚠');
+    const ev = r.evidence.outputsExpected
+      ? `outputs ${r.evidence.outputsPresent}/${r.evidence.outputsExpected}`
+      : 'outputs não declarados';
+    console.log(`  ${icon} ${String(r.task).padEnd(6)} ${r.verdict.padEnd(32)} ${ev}`);
+    if (r.verdict !== 'ok') {
+      if (r.report.exists && r.report.missing.length) {
+        console.log(chalk.gray(`      faltando no relatório: ${r.report.missing.join(', ')}`));
+      }
+      console.log(chalk.gray(`      → ${ACTION_HINT[r.action]}`));
+    }
+  };
+
+  if (obj.task) {
+    console.log(chalk.bold(`\n📄 report-check ${obj.feature} ${obj.task}`));
+    line(obj);
+    console.log('');
+    return;
+  }
+
+  console.log(chalk.bold(`\n📄 report-check ${obj.feature}`));
+  if (!obj.results.length) console.log(chalk.gray('  nenhuma task done — nada a auditar'));
+  for (const r of obj.results) line(r);
+  console.log(
+    `  ${obj.evaluator.exists ? chalk.green('✓') : chalk.yellow('⚠')} ${'Gate 3'.padEnd(6)} `
+    + `evaluator-report.md ${obj.evaluator.exists ? (obj.evaluator.complete ? 'íntegro' : 'incompleto') : 'ausente'}`,
+  );
+  console.log('');
+}