@polymorphism-tech/morph-spec 8.5.0 → 8.7.0

package/src/commands/state/archive.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { existsSync, renameSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { execFileSync } from 'child_process';
+import { promoteUseCases, SPECS_USECASES_PATHSPEC } from '../../lib/specs/usecase-promoter.js';
 
 /**
  * `morph-spec archive <feature>` — atomic, git-aware archive of a completed
@@ -52,7 +53,7 @@ function readReviewApproved(fjPath) {
  * @param {string} feature
  * @param {{ cwd?: string, force?: boolean, git?: boolean }} [opts]
  * @returns {{ ok: boolean, error?: string, archived?: boolean, alreadyArchived?: boolean,
- *   committed?: boolean, staged?: boolean, archivePath?: string }}
+ *   committed?: boolean, staged?: boolean, archivePath?: string, promotedUseCases?: string[] }}
  */
 export function runArchive(feature, opts = {}) {
   const cwd = opts.cwd || process.cwd();
@@ -64,6 +65,14 @@ export function runArchive(feature, opts = {}) {
 
   // Idempotent short-circuit: already archived here. Checked FIRST so a re-run
   // after a partial finish reports "already done", never "not found".
+  //
+  // Consequence, deliberate: this short-circuits BEFORE the use-case promotion
+  // below, so a promotion that degraded fail-open is NOT retried by re-running
+  // `finish`. That is the price of "closing a feature never fails" — an archived
+  // feature stays archived, and the only signal is an absent `promotedUseCases`
+  // in the output. Recovering means copying the UCs into `.morph/specs/usecases/`
+  // by hand; making this retry would mean re-entering the archive path for an
+  // already-closed feature, which is a worse trade.
   if (existsSync(archivePath)) {
     return { ok: true, alreadyArchived: true, archived: false, archivePath };
   }
@@ -117,18 +126,45 @@ export function runArchive(feature, opts = {}) {
     } catch { /* non-fatal — the move is what matters */ }
   }
 
-  // 3) Commit the move — SCOPED to this feature's pathspec, NEVER `commit -a`
+  // 3) Promote the feature's use cases into the project's permanent archive
+  //    (.morph/specs/usecases/). Read from the ALREADY-MOVED folder so there is
+  //    a single source path, and land inside the SAME scoped commit below — the
+  //    archive travels with the integration, exactly like the archived state
+  //    (MORPH.md §2.2). Fail-open: any failure degrades to "promoted nothing",
+  //    never to a refused close.
+  let promotedUseCases = [];
+  try {
+    const { promoted } = promoteUseCases(cwd, archivePath);
+    promotedUseCases = promoted;
+    if (promoted.length && useGit && staged) {
+      // This staging exists for the NEW files: promoted use cases are untracked,
+      // and the scoped `commit -- <pathspec>` below only knows paths git already
+      // tracks. The replaced-by-ID deletions are tracked, so that same commit
+      // would carry them even without this line (verified by mutating it away) —
+      // `-A` is belt-and-braces, but dropping the `git add` entirely would
+      // silently promote nothing on a first delivery.
+      try { execFileSync('git', ['add', '-A', '--', SPECS_USECASES_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
+    }
+  } catch { /* promotion must never block archiving */ }
+
+  // 4) Commit the move — SCOPED to this feature's pathspec, NEVER `commit -a`
   //    (same anti-sweep discipline as `finish`'s worktree teardown). This is what
   //    lets the archived state travel with the branch on `finish` (archive-before-merge).
+  //    The acervo pathspec joins only when something was promoted: git refuses a
+  //    pathspec that matches nothing, and that refusal would leave the tree dirty
+  //    and break the checkout/merge that follows.
   let committed = false;
   if (useGit && staged) {
+    const pathspecs = promotedUseCases.length
+      ? [featPathspec, archivePathspec, SPECS_USECASES_PATHSPEC]
+      : [featPathspec, archivePathspec];
     try {
-      execFileSync('git', ['commit', '-m', `morph-spec archive: ${feature}`, '--', featPathspec, archivePathspec], { cwd, stdio: 'pipe' });
+      execFileSync('git', ['commit', '-m', `morph-spec archive: ${feature}`, '--', ...pathspecs], { cwd, stdio: 'pipe' });
       committed = true;
     } catch { /* nothing to commit / no identity — not fatal, the move + stage stand */ }
   }
 
-  // 4) Drop the feature from the thin root index. Edit the index file directly
+  // 5) Drop the feature from the thin root index. Edit the index file directly
   //    rather than calling saveState — saveState would re-create
   //    .morph/features/{name}/feature.json and undo the archive.
   const rootPath = join(cwd, '.morph', 'state.json');
@@ -144,7 +180,7 @@ export function runArchive(feature, opts = {}) {
     } catch { /* index is derivable — non-fatal */ }
   }
 
-  return { ok: true, archived: true, committed, staged, archivePath };
+  return { ok: true, archived: true, committed, staged, archivePath, promotedUseCases };
 }
 
 /**
@@ -179,6 +215,9 @@ export async function archiveCommand(featureName, options = {}) {
 
     console.log(chalk.green(`\n📦 Archived "${featureName}" → .morph/archive/${featureName}/`));
     console.log(chalk.gray(`   status: completed, archivedAt stamped in feature.json.`));
+    if (result.promotedUseCases?.length) {
+      console.log(chalk.gray(`   ${result.promotedUseCases.length} use case(s) promoted → .morph/specs/usecases/ (status: implemented).`));
+    }
     if (result.committed) console.log(chalk.gray(`   Move committed on the current branch.\n`));
     else if (result.staged) console.log(chalk.gray(`   Move staged in git; commit it when ready.\n`));
     else console.log('');

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.`;
@@ -187,6 +264,7 @@ export async function finishCommand(feature, options = {}) {
 
 async function integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch }) {
   const mergeMsg = `morph-spec finish: merge ${expectedBranch}`;
+  const ucNote = promotedNote(arch);
 
   if (isWorktreeFlow) {
     // The root stays on the default; shed this feature's own root-side scaffold,
@@ -214,13 +292,13 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
 
     if (options.keep) {
       dropFromRootIndex(root, feature);
-      emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false, ...backupNote });
+      emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false, ...backupNote, ...ucNote });
       process.exit(0);
     }
 
     const teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: true });
     dropFromRootIndex(root, feature);
-    emit(mergeOutput({ feature, branch: expectedBranch, worktreePath, teardown, shedBackup }));
+    emit({ ...mergeOutput({ feature, branch: expectedBranch, worktreePath, teardown, shedBackup }), ...ucNote });
     process.exit(0);
   }
 
@@ -249,13 +327,13 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
   }
   tryGit(['branch', '-d', expectedBranch], root);
   // The root index (gitignored) was already updated by the archive (same cwd).
-  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: null });
+  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: null, ...ucNote });
   process.exit(0);
 }
 
 // ── PR integration (push + gh, no local merge) ───────────────────────────────
 
-async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody }) {
+async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch }) {
   try {
     execFileSync('git', ['push', '-u', 'origin', expectedBranch], { cwd: root, stdio: 'pipe' });
   } catch (err) {
@@ -301,6 +379,7 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     pushed: expectedBranch,
     base: defaultBranch,
     pr: prUrl,
+    ...promotedNote(arch),
     ...(shedBackup ? { shedBackup } : {}),
     ...(teardown
       ? { worktreeRemoved: teardown.worktreeRemoved, ...teardownExtras(teardown, worktreePath, expectedBranch, false) }
@@ -312,6 +391,15 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
 
 // ── output helpers ────────────────────────────────────────────────────────
 
+/**
+ * Report the use cases the archive promoted into `.morph/specs/usecases/`.
+ * Absent when nothing was promoted, so a feature with no use cases keeps the
+ * exact output shape it had before this existed.
+ */
+function promotedNote(arch) {
+  return arch?.promotedUseCases?.length ? { promotedUseCases: arch.promotedUseCases } : {};
+}
+
 function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
   return {
     finished: true,
@@ -335,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('');
+}

package/src/commands/tasks/dag.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 import { parseTasksJsonLenient } from '../../lib/tasks/tasks-json-parser.js';
 import { planDispatch } from '../../lib/tasks/dispatch-planner.js';
 import { renderMermaidFlowchart } from '../../lib/tasks/mermaid-renderer.js';
+import { checkUseCases } from '../../lib/specs/usecase-check.js';
 
 /**
  * `morph-spec dag <feature>` — analyze the tasks.json DAG and print the
@@ -17,7 +18,8 @@ import { renderMermaidFlowchart } from '../../lib/tasks/mermaid-renderer.js';
  */
 export async function dagCommand(featureName, options = {}) {
   try {
-    const tasksPath = join(process.cwd(), '.morph', 'features', featureName, '2-plan', 'tasks.json');
+    const planDir = join(process.cwd(), '.morph', 'features', featureName, '2-plan');
+    const tasksPath = join(planDir, 'tasks.json');
     if (!existsSync(tasksPath)) {
       console.error(chalk.red(`\n❌ tasks.json not found for feature "${featureName}"`));
       console.error(chalk.gray(`Expected at: .morph/features/${featureName}/2-plan/tasks.json\n`));
@@ -42,13 +44,34 @@ export async function dagCommand(featureName, options = {}) {
       return;
     }
 
+    // Use-case cross-check. Runs AFTER the --mermaid short-circuit on purpose:
+    // rendering the DAG is pure visualization and must never be blocked by the
+    // state of the spec. A broken `usecase` reference IS fatal here — the file
+    // either exists or it does not, so there is no false positive to weigh
+    // against a plan that points at a use case nobody can read.
+    const ucCheck = checkUseCases(data, join(planDir, 'usecases'));
+
     const plan = planDispatch(data);
 
     if (options.json) {
-      console.log(JSON.stringify(plan, null, 2));
+      console.log(JSON.stringify({ ...plan, useCases: ucCheck }, null, 2));
+      if (ucCheck.errors.length) process.exit(1);
       return;
     }
 
+    const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+    if (ucCheck.errors.length) {
+      console.error(chalk.red(`\n❌ Use cases — ${plural(ucCheck.errors.length, 'erro', 'erros')}\n`));
+      for (const e of ucCheck.errors) console.error(chalk.red(`  ${e}`));
+      console.error(chalk.gray('\n  Corrija a referência no tasks.json ou restaure o use case.\n'));
+      process.exit(1);
+    }
+    if (ucCheck.warnings.length) {
+      console.error(chalk.yellow(`\n⚠ Use cases — ${plural(ucCheck.warnings.length, 'aviso', 'avisos')}`));
+      for (const w of ucCheck.warnings) console.error(chalk.yellow(`  ${w}`));
+    }
+
     console.log(chalk.bold(`\n📊 DAG — ${featureName}`));
     console.log('━'.repeat(60));
 

package/src/commands/validation/validate-feature.js

@@ -36,17 +36,24 @@ import { validateTasksJson } from '../../lib/tasks/tasks-json-parser.js';
  */
 const OUTPUT_SECTIONS = {
   // morph-brainstorming emits: Problema, Escopo, Usuários e fluxos críticos,
-  // Critérios de aceite, Stack, Riscos e dependências, Compliance de stack.
+  // Stack, Riscos e dependências, Compliance de stack.
+  //
+  // "Critérios de aceite" is now OPTIONAL, not required: the behaviour layer
+  // moved to the use cases (2-plan/usecases/), whose post-conditions must be
+  // observable in a test, and morph-brainstorming no longer emits the section.
+  // `optional` — not `recommended` — precisely because the skill never emits it
+  // anymore: a warning on every new proposal would be systematic noise. Legacy
+  // proposals that DO carry the section keep validating exactly as before.
   'proposal.md': {
     required: [
       ['Problema', 'Problem'],
       ['Escopo', 'Scope'],
-      ['Critérios de aceite', 'Critério', 'Aceite', 'Acceptance Criteria', 'Acceptance', 'Success Criteria', 'Success Metrics'],
     ],
     recommended: [
       ['Riscos', 'Risks'],
     ],
     optional: [
+      ['Critérios de aceite', 'Critério', 'Aceite', 'Acceptance Criteria', 'Acceptance', 'Success Criteria', 'Success Metrics'],
       'Stack',
       ['Usuários', 'Usuarios', 'Users', 'User Journey', 'User Stories', 'Fluxos'],
       ['Dependências', 'Dependencias', 'Dependencies'],