@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/src/commands/state/approve.js

@@ -7,6 +7,7 @@ import { getFeature, setApprovalGate, getApprovalGate, getApprovalHistory, deriv
 import { unmetPrereqs } from '../../core/state/gate-order.js';
 import { evaluatorReportState, COMPOSITE_SCORE_TOKEN } from '../../lib/evaluator-report.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
+import { uiuxAutoApprovalBlock } from '../../lib/specs/screen-checklist.js';
 
 /**
  * The literal token `review-report.md` carries to declare which tree it
@@ -308,6 +309,20 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
+    // The same backstop when no gate-check ran: the pause it WOULD record for
+    // the screen checklist, by the predicate advance.js reads too. `--force`
+    // does not bypass it, for the reason above.
+    if (gateName === 'uiux' && approvedBy === 'auto') {
+      const block = uiuxAutoApprovalBlock(process.cwd(), featureName, feature);
+      if (block) {
+        console.error(chalk.red(`\n❌ O Gate "uiux" não pode ser auto-aprovado — ${block}.`));
+        console.error(chalk.gray('   Complete o checklist (ver a skill morph-uiux) e rode de novo, aprove com'));
+        console.error(chalk.gray('   --approver <nome>, ou, se a pausa já foi decidida, grave a decisão:'));
+        console.error(chalk.gray(`   morph-spec gate-decision ${featureName} uiux --pause false --reason "<motivo>"\n`));
+        process.exit(1);
+      }
+    }
+
     let selfAssessed = false;
     if (gateName === 'review') {
       if (feature.workType === 'hotfix') {

package/src/commands/state/archive.js

@@ -3,6 +3,8 @@ import { existsSync, renameSync, mkdirSync, readFileSync, writeFileSync } from '
 import { join, resolve, sep } from 'path';
 import { execFileSync } from 'child_process';
 import { promoteUseCases, SPECS_USECASES_PATHSPEC } from '../../lib/specs/usecase-promoter.js';
+import { applySpecRevocations } from '../../lib/specs/acervo-lifecycle.js';
+import { ADR_INDEX_PATHSPEC } from '../../lib/specs/adr-index.js';
 import { isValidFeatureName } from '../project/worktree.js';
 
 /** Refuse a move whose resolved target escapes `scopeDir`. */
@@ -64,7 +66,11 @@ function readReviewApproved(fjPath) {
  * @param {{ cwd?: string, force?: boolean, git?: boolean }} [opts]
  * @returns {{ ok: boolean, error?: string, archived?: boolean, alreadyArchived?: boolean,
  *   committed?: boolean, staged?: boolean, archivePath?: string, promotedUseCases?: string[],
- *   refusedUseCases?: Array<{id: string, incoming: string, existing: string, existingFeature: string, message: string}> }}
+ *   refusedUseCases?: Array<{id: string, incoming: string, existing: string, existingFeature: string, message: string}>,
+ *   keptSuperseded?: Array<{id: string, file: string, supersededBy: string|null, scope?: string}>,
+ *   supersededUseCases?: Array<{id: string, file: string, supersededBy: string, scope?: string}>,
+ *   revocationProblems?: Array<{id: string|null, reason: string, message: string}>,
+ *   adrIndex?: {added: string[], revoked: string[], narrowed: string[]}|null }}
  */
 export function runArchive(feature, opts = {}) {
   const cwd = opts.cwd || process.cwd();
@@ -158,10 +164,12 @@ export function runArchive(feature, opts = {}) {
   //    never to a refused close.
   let promotedUseCases = [];
   let refusedUseCases = [];
+  let keptSuperseded = [];
   try {
-    const { promoted, refused } = promoteUseCases(cwd, archivePath);
+    const { promoted, refused, keptSuperseded: kept } = promoteUseCases(cwd, archivePath);
     promotedUseCases = promoted;
     refusedUseCases = refused;
+    keptSuperseded = kept;
     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
@@ -173,17 +181,39 @@ export function runArchive(feature, opts = {}) {
     }
   } catch { /* promotion must never block archiving */ }
 
+  // 3b) Apply what the feature's spec.md declared it revokes: acervo use cases
+  //     turn `superseded`, and the ADR index gains/loses files. After the
+  //     promotion, so a substitute promoted just now is already in place (and
+  //     one it refused is known not to be); same commit, same fail-open contract.
+  let lifecycle = { superseded: [], adrIndex: null, problems: [] };
+  try {
+    lifecycle = applySpecRevocations(cwd, archivePath, { refused: refusedUseCases });
+  } catch { /* revocation must never block archiving */ }
+  const acervoChanged = promotedUseCases.length > 0 || lifecycle.superseded.length > 0;
+  const adrIndexChanged = lifecycle.adrIndex?.changed === true;
+  if (useGit && staged) {
+    if (lifecycle.superseded.length) {
+      try { execFileSync('git', ['add', '-A', '--', SPECS_USECASES_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
+    }
+    if (adrIndexChanged) {
+      try { execFileSync('git', ['add', '-A', '--', ADR_INDEX_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
+    }
+  }
+
   // 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.
+  //    The acervo pathspecs join only when something under them changed: 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];
+    const pathspecs = [
+      featPathspec,
+      archivePathspec,
+      ...(acervoChanged ? [SPECS_USECASES_PATHSPEC] : []),
+      ...(adrIndexChanged ? [ADR_INDEX_PATHSPEC] : []),
+    ];
     try {
       execFileSync('git', ['commit', '-m', `morph-spec archive: ${feature}`, '--', ...pathspecs], { cwd, stdio: 'pipe' });
       committed = true;
@@ -206,7 +236,14 @@ export function runArchive(feature, opts = {}) {
     } catch { /* index is derivable — non-fatal */ }
   }
 
-  return { ok: true, archived: true, committed, staged, archivePath, promotedUseCases, refusedUseCases };
+  const adr = lifecycle.adrIndex;
+  return {
+    ok: true, archived: true, committed, staged, archivePath, promotedUseCases, refusedUseCases,
+    keptSuperseded,
+    supersededUseCases: lifecycle.superseded,
+    revocationProblems: lifecycle.problems,
+    adrIndex: adrIndexChanged ? { added: adr.added, revoked: adr.revoked, narrowed: adr.narrowed } : null,
+  };
 }
 
 /**
@@ -253,6 +290,22 @@ export async function archiveCommand(featureName, options = {}) {
         console.log(chalk.yellow(`   ${r.message}`));
       }
     }
+    for (const k of result.keptSuperseded ?? []) {
+      console.log(chalk.yellow(`   ${k.id} continua superseded (superseded_by: ${k.supersededBy ?? '?'}) — a cópia promovida não trazia o status, e o acervo o manteve.`));
+    }
+    for (const s of result.supersededUseCases ?? []) {
+      console.log(chalk.gray(`   ${s.id} → status: superseded (superseded_by: ${s.supersededBy}${s.scope ? `; ainda vale em: ${s.scope}` : ''}).`));
+    }
+    if (result.adrIndex) {
+      const { added, revoked, narrowed } = result.adrIndex;
+      console.log(chalk.gray(`   ADR index (.morph/specs/adrs/): +${added.length} −${revoked.length} ~${narrowed.length}.`));
+    }
+    if (result.revocationProblems?.length) {
+      console.log(chalk.yellow(`\n⚠️  ${result.revocationProblems.length} revogação(ões) do spec.md NÃO aplicada(s):`));
+      for (const p of result.revocationProblems) {
+        console.log(chalk.yellow(`   ${p.message}`));
+      }
+    }
     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/finish.js

@@ -21,6 +21,8 @@ import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js'
 import { tearDownFeatureStack } from '../../lib/e2e/stack-teardown.js';
 import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
 import { runArchive } from './archive.js';
+import { dropLeftoverIgnore, withoutLeftoverIgnore } from '../../../framework/hooks/shared/graph-freshness.js';
+import { newBackupStamp, enforceBackupRetention, inspectFinishBackups } from '../../lib/worktree/finish-backup.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' };
@@ -119,6 +121,14 @@ export async function finishCommand(feature, options = {}) {
   // would otherwise get a silent merge they never asked for.
   let resumed = false;
 
+  // ONE stamp for every backup this run writes: the shed's and the teardown's
+  // folders then count as a single backup under the retention.
+  const backupStamp = newBackupStamp();
+
+  // The backup retention rides the same single point, AFTER this run's own
+  // backups exist (the shed and the teardown both precede every success emit).
+  // This run's stamp is protected: the prune never takes the backup it just
+  // made room for, even when backups stamped by a clock running ahead outrank it.
   const emit = (obj) => {
     if (resumed) obj = { ...obj, resumed: true };
     if (obj?.finished === true) {
@@ -126,6 +136,8 @@ export async function finishCommand(feature, options = {}) {
         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 */ }
+      const retention = enforceBackupRetention(root, { protectStamps: [backupStamp] });
+      if (retention) obj = { ...obj, backupRetention: retention };
     }
     console.log(JSON.stringify(obj));
   };
@@ -413,7 +425,7 @@ export async function finishCommand(feature, options = {}) {
     emit({ finished: false, error: 'status-failed', feature });
     process.exit(1);
   }
-  if (dirty.trim() !== '') {
+  if (withoutLeftoverIgnore(cleanCwd, dirty.split(/\r?\n/).filter((l) => l.trim())).length) {
     emit({ finished: false, error: isWorktreeFlow ? 'worktree-dirty' : 'working-dir-dirty', hint: 'commit seu trabalho na branch antes do finish', feature });
     process.exit(1);
   }
@@ -475,6 +487,9 @@ export async function finishCommand(feature, options = {}) {
   }
 
   // ── ARCHIVE (inside morph/{f}) ────────────────────────────────────────────
+  // Every refusal is behind us: the leftover of a killed `graph refresh` goes now,
+  // before the archive — never before a precondition that could still refuse.
+  dropLeftoverIgnore(cleanCwd);
   const arch = runArchive(feature, { cwd: featureCwd, force: options.force, git: true });
   if (!arch.ok) {
     emit({ finished: false, error: `archive-${arch.error}`, feature });
@@ -489,9 +504,9 @@ export async function finishCommand(feature, options = {}) {
 
   // ── INTEGRATE ─────────────────────────────────────────────────────────────
   if (mode === 'merge') {
-    return integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch });
+    return integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch, backupStamp });
   }
-  return integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch });
+  return integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch, backupStamp });
 }
 
 /**
@@ -582,6 +597,30 @@ export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch
 
   if (defaultBranch) out.defaultBranch = defaultBranch;
 
+  // A retenção dos backups também é mutação do finish real — a AUTOMÁTICA, que
+  // não toca backup sem manifesto (esses só o `doctor --worktrees --prune`
+  // poda). A contagem é a de AGORA: o backup que este finish gravar ainda pode
+  // empurrar mais um para fora.
+  try {
+    const retention = inspectFinishBackups(root);
+    if (retention.policy.skipped) {
+      out.backupRetention = { skipped: retention.policy.skipped };
+      warnings.push(`a retenção dos backups do finish será PULADA: ${retention.policy.skipped}`);
+    } else if (retention.outsideRetention || retention.overdueSecrets.length || retention.legacy) {
+      out.backupRetention = {
+        outsideRetention: retention.outsideRetention,
+        overdueSecrets: retention.overdueSecrets.length,
+        ...(retention.legacy ? { legacyPending: retention.legacy } : {}),
+      };
+      if (retention.outsideRetention || retention.overdueSecrets.length) {
+        out.wouldDo.push(
+          `aplicar a retenção de .git/morph-spec/finish-backup: apagar ${retention.outsideRetention} backup(s) fora da política`
+          + ` e ${retention.overdueSecrets.length} arquivo(s) .env* além de ${retention.policy.secretMaxAgeDays} dias`,
+        );
+      }
+    }
+  } catch { /* o pré-voo nunca lança */ }
+
   // ── Seções de worktree — omitidas quando não há worktree (UC-16 A1) ───────
   if (worktreePath) {
     out.worktreePath = worktreePath.replace(/\\/g, '/');
@@ -664,14 +703,14 @@ export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch
 
 // ── merge integration (local, no push) ───────────────────────────────────────
 
-async function integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch }) {
+async function integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch, backupStamp }) {
   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,
     // then guard the whole root before landing the merge commit.
-    const { shedBackup } = shedRootFeatureScope(root, feature);
+    const { shedBackup } = shedRootFeatureScope(root, feature, { stamp: backupStamp });
     const backupNote = shedBackup ? { shedBackup } : {};
 
     // Final gate before the merge commit lands. The pre-archive check above
@@ -721,7 +760,7 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
     const deferred = sessionAnchoredInWorktree(worktreePath);
     const teardown = deferred
       ? null
-      : await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: true });
+      : await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: true, stamp: backupStamp });
     dropFromRootIndex(root, feature);
     emit({ ...mergeOutput({ feature, branch: expectedBranch, defaultBranch, publish, worktreePath, teardown, shedBackup, deferred }), ...ucNote, e2e });
     process.exit(0);
@@ -776,7 +815,7 @@ export function prNumberFromUrl(url) {
 
 // ── PR integration (push + gh, no local merge) ───────────────────────────────
 
-async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch }) {
+async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch, backupStamp }) {
   try {
     execFileSync('git', ['push', '-u', 'origin', expectedBranch], { cwd: root, stdio: 'pipe' });
   } catch (err) {
@@ -812,13 +851,13 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     // later merges (carrying features/{f} → archive/{f}), the default would hold
     // the feature in BOTH features/ and archive/ at once — active and archived.
     // The branch/PR owns the authoritative copy; the root scaffold is transient.
-    shedBackup = shedRootFeatureScope(root, feature).shedBackup;
+    shedBackup = shedRootFeatureScope(root, feature, { stamp: backupStamp }).shedBackup;
     // Same deferral as --merge: never tear down the worktree the running
     // session is anchored in (see sessionAnchoredInWorktree).
     if (sessionAnchoredInWorktree(worktreePath)) {
       teardownDeferred = true;
     } else {
-      teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: false });
+      teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: false, stamp: backupStamp });
     }
     // The shed removed the root's features/{f} scaffold from disk, but runArchive
     // dropped the feature only from the WORKTREE's index (its cwd). Drop it from
@@ -874,16 +913,25 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
 // ── output helpers ────────────────────────────────────────────────────────
 
 /**
- * Report the use cases the archive promoted into `.morph/specs/usecases/`, and
- * any that were REFUSED for a numbering collision (`ucCollisions` — see
- * `usecase-promoter.js`'s reservation-backed guard). Both absent when there is
- * nothing to report, so a feature with no use cases keeps the exact output
- * shape it had before either existed.
+ * Report what the archive did to the acervo: use cases promoted into
+ * `.morph/specs/usecases/`, any REFUSED for a numbering collision
+ * (`ucCollisions` — see `usecase-promoter.js`'s reservation-backed guard), the
+ * promoted copies that stayed superseded because the acervo said so
+ * (`keptSuperseded`), the ones the feature's spec.md revoked
+ * (`supersededUseCases`), the ADR index files it moved (`adrIndex`) and the
+ * revocations it could not apply
+ * (`revocationProblems`). Every key is absent when there is nothing to report,
+ * so a feature that touches no acervo keeps the exact output shape it had
+ * before any of them existed.
  */
 function promotedNote(arch) {
   return {
     ...(arch?.promotedUseCases?.length ? { promotedUseCases: arch.promotedUseCases } : {}),
     ...(arch?.refusedUseCases?.length ? { ucCollisions: arch.refusedUseCases } : {}),
+    ...(arch?.keptSuperseded?.length ? { keptSuperseded: arch.keptSuperseded } : {}),
+    ...(arch?.supersededUseCases?.length ? { supersededUseCases: arch.supersededUseCases } : {}),
+    ...(arch?.adrIndex ? { adrIndex: arch.adrIndex } : {}),
+    ...(arch?.revocationProblems?.length ? { revocationProblems: arch.revocationProblems } : {}),
   };
 }
 

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

@@ -4,6 +4,7 @@ import { getFeature } from '../../core/state/state-manager.js';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 import { shouldPauseGate, getRiskSignals, classifyE2eSkip } from '../../lib/risk-detector.js';
 import { evaluatorCompositeScore, evaluatorProofState, minProofScore, mediaProofScore } from '../../lib/evaluator-report.js';
+import { collectScreenChecklist } from '../../lib/specs/screen-checklist.js';
 import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-decision.js';
 import { minimatch } from 'minimatch';
 import { detectDefaultBranch, getHeadSha, getDiffStat, changedPathsAgainst } from '../../lib/git/default-branch.js';
@@ -195,6 +196,12 @@ function collectSignals(featureName, feature, cwd, gateName) {
     designSystemDivergence: false,
   };
 
+  // Só onde o checklist decide algo: no fecho do design e no ship. Fato de
+  // disco, fora de OVERRIDABLE_SIGNAL_KEYS como `mutationProof`.
+  if (gateName === 'uiux' || gateName === 'review') {
+    signals.screenChecklist = collectScreenChecklist(cwd, featureName, gateName);
+  }
+
   const evalScore = compositeEvalScore(feature);
   if (evalScore !== undefined) {
     signals.evalScore = evalScore;
@@ -392,7 +399,7 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
     const trust = options.trust || readTrustFromConfig();
     const { pause, reason } = shouldPauseGate({ trust }, signals);
 
-    const entry = await persistGateDecision(featureName, gateName, { pause, reason, signals, trust });
+    const entry = await persistGateDecision(featureName, gateName, { pause, reason, signals, trust, cwd });
 
     if (options.json) {
       console.log(JSON.stringify({ feature: featureName, gate: gateName, ...entry }, null, 2));

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

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { getFeature, updateFeature } from '../../core/state/state-manager.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
+import { mockupsHash } from '../../lib/specs/screen-checklist.js';
 
 export const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
 
@@ -42,17 +43,20 @@ export function readTrustFromConfig() {
  *
  * @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).
+ * @param {{ pause: boolean, reason?: string, signals?: object, trust?: string, cwd?: string }} decision
+ * @returns {Promise<{ pause: boolean, reason: string, signals: object, trust: string, decidedAt: string, mockupsHash?: string|null }>}
+ *   the exact entry written (decidedAt is server-side, generated here). A uiux
+ *   decision also carries the hash of the mockup it saw: it answers that
+ *   mockup's pause, not the next one's.
  */
-export async function persistGateDecision(featureName, gateName, { pause, reason, signals = {}, trust } = {}) {
+export async function persistGateDecision(featureName, gateName, { pause, reason, signals = {}, trust, cwd = process.cwd() } = {}) {
   const entry = {
     pause,
     reason: reason || (pause ? 'risco detectado' : 'nenhum sinal de risco'),
     signals,
     trust: trust || readTrustFromConfig(),
     decidedAt: new Date().toISOString(),
+    ...(gateName === 'uiux' ? { mockupsHash: mockupsHash(cwd, featureName) } : {}),
   };
 
   await updateFeature(featureName, `gateDecisions.${gateName}`, entry);

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

@@ -23,12 +23,18 @@
  *
  * 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.
+ *
+ * The output also carries `tree` (see tree-state.js): the working tree the
+ * orchestrator would otherwise ask git for, call by call, right after the same
+ * dispatch. It is information only and never changes the verdict.
  */
 
 import chalk from 'chalk';
 import { existsSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
-import { readTelemetryEvents } from '../../../framework/hooks/shared/telemetry-logger.js';
+import { readTelemetryEvents, isFailedToolCall } from '../../../framework/hooks/shared/telemetry-logger.js';
+import { treeState, snapshotTree } from '../../lib/git/tree-state.js';
+import { atomicWriteJson } from '../../core/state/state-manager.js';
 
 /**
  * The four mandatory items of the report contract, as detectable markers.
@@ -51,6 +57,16 @@ const REPORT_MARKERS = [
 /** (1) "what was done" — prose beyond the structural markers. */
 const MIN_PROSE_CHARS = 80;
 
+/**
+ * The partial-report marker of the dispatch contract (clause 5, ADR-004): a
+ * sub-agent nearing its `maxTurns` ceiling writes `PARCIAL` on the FIRST line.
+ * Read on purpose, never inferred from a missing score: the score marker above
+ * is loose by design, and a partial saying "auto-score: pendente (0-10 no
+ * final)" matches it — with the other items present it would audit as `ok`.
+ * Tolerates heading/bold/quote typography (`# PARCIAL`, `**PARCIAL**`).
+ */
+const PARTIAL_MARKER = /^[\s#>*_]*PARCIAL\b/;
+
 function reportPath(cwd, feature, taskId) {
   return join(cwd, '.morph', 'features', feature, '3-implement', 'reports', `${taskId}.md`);
 }
@@ -99,7 +115,11 @@ export function inspectReport(path) {
     .trim();
   if (prose.length < MIN_PROSE_CHARS) missing.unshift('what');
 
-  return { exists: true, complete: missing.length === 0, missing };
+  const firstLine = body.split('\n').find((l) => l.trim() !== '') ?? '';
+  const partial = PARTIAL_MARKER.test(firstLine);
+  if (partial) missing.push('partial');
+
+  return { exists: true, complete: missing.length === 0, missing, partial };
 }
 
 /** How many of a task's declared outputs actually exist on disk. */
@@ -206,6 +226,7 @@ function observedEvidence(cwd, feature, task) {
   const writes = [];
   for (const e of events) {
     if (e?.tool !== 'Write' && e?.tool !== 'Edit') continue;
+    if (isFailedToolCall(e)) continue;
     const ts = Date.parse(e?.ts ?? '');
     if (!Number.isFinite(ts) || ts < startMs || ts > endMs) continue;
     const target = toRepoRelative(e.target, cwd);
@@ -249,6 +270,10 @@ function decide(report, evidence, stale) {
       ? { verdict: 'report-stale', action: 'refresh-from-evidence' }
       : { verdict: 'ok', action: 'proceed' };
   }
+  // A PARCIAL report is an agent that stopped short (turn ceiling): the work
+  // resumes from its last `wip` commit — completing it DEGRADADO would stamp
+  // unfinished work as done.
+  if (report.exists && report.partial) return { verdict: 'report-incomplete', action: 'resume' };
   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
@@ -273,13 +298,36 @@ const ACTION_HINT = {
   proceed: 'relatório íntegro — siga o fluxo normal.',
   'refresh-from-evidence': 'o relatório está COMPLETO mas VELHO: a task seguiu escrevendo arquivos depois que ele foi gravado, então ele descreve um estado já ultrapassado. NÃO re-despache e não confie no texto — confira os arquivos em `observed` (evidência real, não auto-declarada) e atualize o relatório a partir deles.',
   '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.',
+  resume: 'relatório PARCIAL: o sub-agent parou antes do fim (limite de turnos) e a task NÃO está pronta. Não carimbe DEGRADADO nem pontue — retome o MESMO agente por `SendMessage` (cole no recado `tree.dirty` e `tree.commits` desta saída e o que falta) ou re-despache só o que falta, a partir do último commit `wip`.',
   '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.',
 };
 
+function snapshotPath(cwd, feature) {
+  return join(cwd, '.morph', 'features', feature, '4-review', 'tree-before-eval.json');
+}
+
+/**
+ * The tree block, compared with the snapshot taken before the evaluator was
+ * dispatched when there is one. `beforeEval` takes a new snapshot after the
+ * comparison, so the output still shows what changed since the previous one.
+ */
+function treeFor(cwd, feature, beforeEval) {
+  const path = snapshotPath(cwd, feature);
+  let snapshot = null;
+  try { if (existsSync(path)) snapshot = JSON.parse(readFileSync(path, 'utf8')); } catch { snapshot = null; }
+  const tree = treeState(cwd, { snapshot });
+  if (!beforeEval) return { tree };
+  const next = snapshotTree(cwd);
+  if (!next) return { tree, beforeEval: null };
+  atomicWriteJson(path, next);
+  return { tree, beforeEval: { at: next.at, files: Object.keys(next.files).length } };
+}
+
 /**
  * @param {string} feature
- * @param {string|undefined} taskId
+ * @param {string|string[]|undefined} taskId - several ids audit a parallel
+ *   batch whose tasks are not `done` yet, which the whole-feature mode skips
  * @param {{ json?: boolean, cwd?: string }} [options]
  */
 export function reportCheckCommand(feature, taskId, options = {}) {
@@ -303,18 +351,26 @@ export function reportCheckCommand(feature, taskId, options = {}) {
     emit({ error: `2-plan/tasks.json de "${feature}" está corrompido`, feature }, 1);
   }
 
+  if (Array.isArray(taskId)) {
+    const unknown = taskId.filter((id) => !tasks.some((t) => t.id === id));
+    if (unknown.length) emit({ error: `task(s) ${unknown.join(', ')} não existe(m) em tasks.json`, feature }, 1);
+    const results = taskId.map((id) => checkTask(cwd, feature, tasks.find((t) => t.id === id)));
+    const clean = results.every((r) => r.verdict === 'ok');
+    emit({ feature, results, clean, ...treeFor(cwd, feature, options.beforeEval) }, clean ? 0 : 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);
+    emit({ feature, ...result, hint: ACTION_HINT[result.action], ...treeFor(cwd, feature, options.beforeEval) }, 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);
+  emit({ feature, results, evaluator, clean, ...treeFor(cwd, feature, options.beforeEval) }, clean ? 0 : 1);
 }
 
 function printHuman(obj) {
@@ -339,6 +395,7 @@ function printHuman(obj) {
   if (obj.task) {
     console.log(chalk.bold(`\n📄 report-check ${obj.feature} ${obj.task}`));
     line(obj);
+    printTree(obj.tree);
     console.log('');
     return;
   }
@@ -346,9 +403,33 @@ function printHuman(obj) {
   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'}`,
-  );
+  if (obj.evaluator) {
+    console.log(
+      `  ${obj.evaluator.exists ? chalk.green('✓') : chalk.yellow('⚠')} ${'Gate 3'.padEnd(6)} `
+      + `evaluator-report.md ${obj.evaluator.exists ? (obj.evaluator.complete ? 'íntegro' : obj.evaluator.partial ? 'PARCIAL' : 'incompleto') : 'ausente'}`,
+    );
+  }
+  printTree(obj.tree);
   console.log('');
 }
+
+function printTree(tree) {
+  if (!tree) {
+    console.log(chalk.gray('  árvore: fora de um repositório git — não conferida'));
+    return;
+  }
+  const stat = tree.diffstat ? ` (+${tree.diffstat.insertions} −${tree.diffstat.deletions})` : '';
+  console.log(`  árvore ${tree.branch ?? '-'}@${tree.head ?? '-'}: ${tree.dirtyCount} arquivo(s) não commitado(s) fora de .morph/${stat}`);
+  for (const d of tree.dirty.slice(0, 10)) console.log(chalk.gray(`      ${d.status.padEnd(2)} ${d.path}`));
+  if (tree.dirtyCount > 10) console.log(chalk.gray(`      … e mais ${tree.dirtyCount - 10}`));
+  if (tree.markers.length) {
+    console.log(chalk.yellow(`  ⚠ marcador de mutação esquecido: ${tree.markers.map((m) => `${m.file}:${m.line}`).join(', ')}`));
+  }
+  if (tree.commits?.length) console.log(chalk.gray(`  commits sobre a default: ${tree.commits.join(' · ')}`));
+  const since = tree.sinceBeforeEval;
+  if (since) {
+    console.log(since.changedCount
+      ? chalk.yellow(`  ⚠ desde a foto de ${since.at}: ${since.changedCount} arquivo(s) mudaram — ${since.changed.join(', ')}`)
+      : chalk.green(`  ✓ nada mudou fora de .morph/ desde a foto de ${since.at}`));
+  }
+}

package/src/commands/state/usecase.js

@@ -11,6 +11,8 @@
  * how `morph-plan` gets that protection; omitting it degrades to "reserved,
  * no owner recorded" — still collision-free, just unable to name the
  * conflicting feature if one ever surfaces.
+ *
+ * `morph-spec usecase check <feature>` — see `usecaseCheckCommand` below.
  */
 
 import chalk from 'chalk';
@@ -18,6 +20,11 @@ import { existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
 import { reserveUseCases } from '../../lib/specs/usecase-registry.js';
+import { checkUseCases } from '../../lib/specs/usecase-check.js';
+import { checkLifecycle } from '../../lib/specs/acervo-lifecycle.js';
+import { parseTasksJsonLenient } from '../../lib/tasks/tasks-json-parser.js';
+import { isValidFeatureName } from '../project/worktree.js';
+import { printLifecycleWarnings } from '../tasks/dag.js';
 
 /**
  * Best-effort feature-name inference when `--feature` is omitted: only when
@@ -75,3 +82,62 @@ export function usecaseReserveCommand(options = {}) {
   else console.log('');
   process.exit(0);
 }
+
+/**
+ * `morph-spec usecase check <feature> [--json]` — the use-case half of `dag`,
+ * runnable before `tasks.json` exists: the feature's use cases and the
+ * revocations its `spec.md` declares, against the acervo's lifecycle. With a
+ * `tasks.json`, also the task → use case plumbing `dag` checks.
+ *
+ * Exit 1 only for what `dag` also refuses (a task pointing at a use case that
+ * does not exist, a tasks.json that does not validate); lifecycle findings are
+ * warnings.
+ *
+ * @param {string} feature
+ * @param {{ json?: boolean, cwd?: string }} [options]
+ */
+export async function usecaseCheckCommand(feature, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const fail = (error) => {
+    if (options.json) console.log(JSON.stringify({ feature, error }));
+    else console.error(chalk.red(`\n❌ ${error}\n`));
+    process.exit(1);
+  };
+
+  if (!isValidFeatureName(feature)) fail(`nome de feature inválido: "${feature}"`);
+  const featureDir = join(cwd, '.morph', 'features', feature);
+  if (!existsSync(featureDir)) fail(`feature não encontrada: .morph/features/${feature}`);
+
+  const tasksPath = join(featureDir, '2-plan', 'tasks.json');
+  let tasksData = null;
+  if (existsSync(tasksPath)) {
+    try {
+      ({ data: tasksData } = await parseTasksJsonLenient(tasksPath));
+    } catch (error) {
+      fail(`tasks.json inválido: ${error.message}`);
+    }
+  }
+
+  const useCases = tasksData ? checkUseCases(tasksData, join(featureDir, '2-plan', 'usecases')) : null;
+  const lifecycle = checkLifecycle({ cwd, featureDir, tasksData });
+  const broken = useCases?.errors.length > 0;
+
+  if (options.json) {
+    console.log(JSON.stringify({ feature, useCases, lifecycle }, null, 2));
+    process.exit(broken ? 1 : 0);
+  }
+
+  if (broken) {
+    console.error(chalk.red(`\n❌ Use cases — ${useCases.errors.length} erro(s)\n`));
+    for (const e of useCases.errors) console.error(chalk.red(`  ${e}`));
+  }
+  if (useCases?.warnings.length) {
+    console.error(chalk.yellow(`\n⚠ Use cases — ${useCases.warnings.length} aviso(s)`));
+    for (const w of useCases.warnings) console.error(chalk.yellow(`  ${w}`));
+  }
+  printLifecycleWarnings(lifecycle);
+  if (!broken && !useCases?.warnings.length && !lifecycle.warnings.length) {
+    console.log(chalk.green(`\n✅ ${feature}: use cases e acervo sem achados\n`));
+  }
+  process.exit(broken ? 1 : 0);
+}