@polymorphism-tech/morph-spec 8.37.1 → 8.38.0

package/src/commands/project/worktree.js

@@ -35,14 +35,24 @@
  */
 
 import { execSync, execFileSync } from 'child_process';
-import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, cpSync } from 'fs';
+import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, lstatSync, unlinkSync, rmdirSync, cpSync } from 'fs';
 import { join, resolve, dirname, basename } from 'path';
 import chalk from 'chalk';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
 import { triageIgnoredPaths } from '../../lib/worktree/ignored-triage.js';
+import {
+  finishBackupDir,
+  writeFeatureScopeBackup,
+  writeWorktreeIgnoredBackup,
+  enforceBackupRetention,
+  newBackupStamp,
+} from '../../lib/worktree/finish-backup.js';
 // The reparse scan lives in hooks/shared because the PreToolUse guardrail needs
 // the SAME answer this file does, and hooks can never import from `src/`.
 import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
+import { ensureCommonExclude } from '../../../framework/hooks/shared/git-exclude.js';
+import { seedGraphFromRoot } from '../../../framework/hooks/shared/graph-refresh.js';
+import { dropLeftoverIgnore, withoutLeftoverIgnore } from '../../../framework/hooks/shared/graph-freshness.js';
 
 // The container name lives in lib/worktree/dirs.js (single source, C1
 // rationale documented there); re-exported here so existing importers and the
@@ -288,28 +298,9 @@ const EXCLUDE_MARKER = '# morph-spec: infra links inside worktrees (managed —
  * @param {string[]} rels - worktree-relative paths to exclude
  */
 function excludeWorktreePaths(mainCwd, rels) {
-  if (!rels.length) return;
-  try {
-    // `--git-common-dir`, never `join(mainCwd, '.git')`: the primary root may
-    // itself be a worktree (whose `.git` is a FILE), and the common dir is the
-    // only exclude every linked worktree actually reads.
-    const common = execSync('git rev-parse --git-common-dir', { cwd: mainCwd, stdio: 'pipe' }).toString().trim();
-    if (!common) return;
-    const infoDir = join(resolve(mainCwd, common), 'info');
-    const excludePath = join(infoDir, 'exclude');
-    const current = existsSync(excludePath) ? readFileSync(excludePath, 'utf8') : '';
-    const present = new Set(current.split(/\r?\n/).map((l) => l.trim()));
-    // Anchored (`/x`): these live at the top of a worktree, and an unanchored
-    // `node_modules` would also swallow nested ones the user may track.
-    const missing = rels.map((rel) => `/${rel.replace(/\\/g, '/')}`).filter((p) => !present.has(p));
-    if (!missing.length) return;
-    mkdirSync(infoDir, { recursive: true });
-    appendFileSync(excludePath, [
-      current && !current.endsWith('\n') ? '\n' : '',
-      present.has(EXCLUDE_MARKER) ? '' : `${EXCLUDE_MARKER}\n`,
-      `${missing.join('\n')}\n`,
-    ].join(''));
-  } catch { /* fail-open */ }
+  // Anchored (`/x`): these live at the top of a worktree, and an unanchored
+  // `node_modules` would also swallow nested ones the user may track.
+  ensureCommonExclude(mainCwd, rels.map((rel) => `/${rel.replace(/\\/g, '/')}`), EXCLUDE_MARKER);
 }
 
 /**
@@ -412,6 +403,28 @@ export async function materializeState(worktreePath) {
   }
 }
 
+/**
+ * Codebase graph for a new worktree. The tree is born from a root commit, so
+ * the root's graph is either this tree's HEAD graph already or one
+ * `morph-spec graph refresh` away — and the `reuse` validator reads the graph
+ * of the tree `verify` runs in, so a worktree without one skips reuse checking
+ * exactly where the new code is written. Nothing is launched in the
+ * background: the automatic refresh only ever touches the root (a detached
+ * process holding a worktree directory made `finish` fail on win32).
+ * Fail-open: no root graph, no copy.
+ *
+ * @param {string} worktreePath
+ * @param {string} root
+ * @returns {{seeded: boolean, reason?: string}}
+ */
+function seedWorktreeGraph(worktreePath, root) {
+  try {
+    return seedGraphFromRoot(worktreePath, root);
+  } catch {
+    return { seeded: false, reason: 'seed-failed' };
+  }
+}
+
 // ── Command handler ─────────────────────────────────────────────────────────
 
 /**
@@ -521,6 +534,8 @@ export async function runWorktreeSetup(feature, options = {}) {
     // committed feature.json files) so hooks work from the very first session.
     const materialized = await ensureLocalState(worktreePath);
 
+    const graph = seedWorktreeGraph(worktreePath, cwd);
+
     // Fleet handoff: the fresh instance that opens this worktree reads
     // handoff.md before anything else (SessionStart hook points at it). The doc
     // is derived and git-invisible (see handoff-generator). Fail-open — and a
@@ -560,6 +575,7 @@ export async function runWorktreeSetup(feature, options = {}) {
       feature,
       materialized: materialized.materialized,
       ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
+      ...(graph.seeded ? { graph: 'seeded' } : {}),
       nextStep: `Abra o Claude Code em ${worktreePath} para trabalhar nesta feature`,
     };
   } catch (err) {
@@ -654,6 +670,7 @@ export async function runWorktreeProvision(name, options = {}) {
     setupInfraLinks(worktreePath, root);
     const envBlock = await allocateWorktreeEnv(worktreePath, root, `task/${name}`);
     const materialized = await ensureLocalState(worktreePath);
+    const graph = seedWorktreeGraph(worktreePath, root);
 
     return {
       ok: true,
@@ -666,6 +683,7 @@ export async function runWorktreeProvision(name, options = {}) {
       name,
       materialized: materialized.materialized,
       ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
+      ...(graph.seeded ? { graph: 'seeded' } : {}),
     };
   } catch (err) {
     return { ok: true, exitCode: 0, created: false, error: (err.message || 'unknown').slice(0, 200), name };
@@ -930,7 +948,7 @@ export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
 
 /**
  * Gitignored paths a morph worktree owns and that are safe to remove — but ONLY
- * once backed up (see backupWorktreeIgnored). `.morph/state.json` is provably
+ * once backed up (see writeWorktreeIgnoredBackup). `.morph/state.json` is provably
  * derivable (loadState self-heals it from the committed feature.json files) and
  * the rest is morph's own diagnostic output, which `setupInfraLinks` documents
  * as worktree-local. They are small, so backing them up costs nothing and buys
@@ -1054,60 +1072,6 @@ export function classifyIgnoredLeftovers(worktreePath, rootPath, options = {}) {
   return { shieldable, blocking: [], discarded: [...disposable, ...replicable], replicable };
 }
 
-/**
- * Back up the worktree's morph-owned gitignored leftovers before the removal
- * deletes them. Same destination and rationale as backupFeatureScope.
- *
- * @param {string} worktreePath
- * @param {string} root
- * @param {string} feature
- * @param {string[]} rels - worktree-relative paths
- * @param {string} stamp
- * @returns {string|null} backup path, or null if ANY copy failed (caller must
- *   then decline the removal — a partial backup authorizes nothing)
- */
-function backupWorktreeIgnored(worktreePath, root, feature, rels, stamp) {
-  const dest = join(root, '.git', 'morph-spec', 'finish-backup', `${feature}-${stamp}-worktree-ignored`);
-  try {
-    for (const rel of rels) {
-      const src = join(worktreePath, rel);
-      if (!existsSync(src)) continue; // a directory entry already covered by its children
-      const target = join(dest, rel);
-      mkdirSync(dirname(target), { recursive: true });
-      cpSync(src, target, { recursive: true });
-    }
-    return existsSync(dest) ? dest : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Copy the feature's root-side scope to a backup OUTSIDE the working tree, so
- * the shed below can never be the reason something is lost.
- *
- * Lives under `.git/` on purpose: it is not a working-tree path, so it can never
- * dirty `git status` (which the very next validation reads) and is never merged,
- * committed, or cleaned by `git clean`.
- *
- * @param {string} root
- * @param {string} feature
- * @param {string} stamp - caller-supplied timestamp (keeps this pure/testable)
- * @returns {string|null} absolute backup path, or null if the copy failed
- */
-function backupFeatureScope(root, feature, stamp) {
-  const src = join(root, '.morph', 'features', feature);
-  if (!existsSync(src)) return null;
-  const dest = join(root, '.git', 'morph-spec', 'finish-backup', `${feature}-${stamp}`);
-  try {
-    mkdirSync(dirname(dest), { recursive: true });
-    cpSync(src, dest, { recursive: true });
-    return dest;
-  } catch {
-    return null; // caller MUST treat this as "do not shed"
-  }
-}
-
 // ── finish primitives (used by `morph-spec finish`) ───────────────────────
 //
 // The old `worktree finish` command dissolved here: `morph-spec finish` (see
@@ -1119,17 +1083,19 @@ function backupFeatureScope(root, feature, stamp) {
 /**
  * Shed the feature's OWN transient root-side bookkeeping so the merge can own
  * this feature's state while the whole-root clean-check keeps guarding UNRELATED
- * work. Backs up FIRST (see backupFeatureScope), then discards — the shed is
- * safe WITHOUT having to be right about what is in scope: if the classification
- * the merge implies turns out wrong, the bytes are still on disk. Worktree-flow
- * only; the common flow committed the archive on the branch, so there is no
- * untracked root-side scaffold to shed.
+ * work. Backs up FIRST (see writeFeatureScopeBackup), then discards — the shed
+ * is safe WITHOUT having to be right about what is in scope: if the
+ * classification the merge implies turns out wrong, the bytes are still on
+ * disk. Worktree-flow only; the common flow committed the archive on the
+ * branch, so there is no untracked root-side scaffold to shed.
  *
  * @param {string} root
  * @param {string} feature
+ * @param {{ stamp?: string }} [opts] - the finish's one stamp, shared with the
+ *   teardown's backup so the two folders count as one backup
  * @returns {{ shedBackup: string|null }} backup path if anything was shed
  */
-export function shedRootFeatureScope(root, feature) {
+export function shedRootFeatureScope(root, feature, { stamp } = {}) {
   const featPathspec = `.morph/features/${feature}`;
   let dirtyInScope = '';
   try {
@@ -1138,7 +1104,7 @@ export function shedRootFeatureScope(root, feature) {
 
   if (dirtyInScope.trim() === '') return { shedBackup: null };
 
-  const shedBackup = backupFeatureScope(root, feature, new Date().toISOString().replace(/[:.]/g, '-'));
+  const shedBackup = writeFeatureScopeBackup({ root, feature, stamp });
   // No backup, no shed. Falling through leaves the root dirty, so the caller's
   // clean-check refuses — the exact fail-closed behaviour from before any shed.
   if (shedBackup) {
@@ -1363,14 +1329,17 @@ export function pickRemovalFailure(stderrs) {
  * `deleteBranch` decouples `git branch -d` from removal: true for `--merge` (the
  * branch is integrated), false for `--pr` (the open PR still needs the branch).
  *
+ * `stamp` names the backup; `finish` passes the one it gave the shed, so both
+ * folders of that finish count as one backup under the retention.
+ *
  * @param {string} worktreePath
- * @param {{ root: string, feature: string, branch: string, options?: object, deleteBranch?: boolean }} ctx
+ * @param {{ root: string, feature: string, branch: string, options?: object, deleteBranch?: boolean, stamp?: string }} ctx
  * @returns {Promise<{ worktreeRemoved: boolean, ignoredBackup: string|null, discarded: string[],
  *   blockers: string[], ignoredBlocking: string[], shieldable: string[], declineReason: string|null,
  *   relinked: boolean, refused: boolean, infraLeftUnlinked: string[],
  *   removalFailure: {kind: string, detail: string}|null }>}
  */
-export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false }) {
+export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false, stamp }) {
   // Drop the infra junctions FIRST, without following them — this is what makes
   // a removal survivable (see unlinkWorktreeInfraLinks). Runs unconditionally.
   //
@@ -1392,7 +1361,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   let ignoredBackup = null;
   const clearedToRemove = blockers.length === 0 && ignored.blocking.length === 0;
   if (clearedToRemove && ignored.shieldable.length) {
-    ignoredBackup = backupWorktreeIgnored(worktreePath, root, feature, ignored.shieldable, new Date().toISOString().replace(/[:.]/g, '-'));
+    ignoredBackup = writeWorktreeIgnoredBackup({ worktreePath, root, feature, rels: ignored.shieldable, stamp });
   }
   const canRemove = clearedToRemove && (!ignored.shieldable.length || ignoredBackup !== null);
 
@@ -1462,7 +1431,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   const removeCmd = (addressByTarget || !isValidFeatureName(feature))
     ? `morph-spec worktree remove --target "${worktreePath}"`
     : `morph-spec worktree remove ${feature}`;
-  const backupDir = join(root, '.git', 'morph-spec', 'finish-backup');
+  const backupDir = finishBackupDir(root);
   const sample = (list) => `${list.slice(0, 5).join(', ')}${list.length > 5 ? `, +${list.length - 5}` : ''}`;
   const declineReason = worktreeRemoved
     ? null
@@ -1659,13 +1628,18 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
       emit({ removed: false, error: 'status-failed', path: worktreePath, root,
         hint: 'não foi possível provar que o worktree está limpo — nada foi removido' }, 1);
     }
-    const dirt = status.split(/\r?\n/).filter((l) => l.trim());
+    const dirt = withoutLeftoverIgnore(worktreePath, status.split(/\r?\n/).filter((l) => l.trim()));
     if (dirt.length) {
       emit({ removed: false, error: 'worktree-dirty', path: worktreePath, root, dirt: dirt.slice(0, 20),
         hint: `o worktree tem trabalho não commitado — commit ou descarte antes, ou rode \`morph-spec worktree remove --target "${worktreePath}"\` sem --if-clean para remover com backup` }, 1);
     }
   }
 
+  // A leftover temporary .graphifyignore (a `graph refresh` killed mid-run) is a
+  // copy of the root's rules: not a file to back up. Deleted only now, after
+  // every refusal, so a refused removal leaves the tree as it was.
+  dropLeftoverIgnore(worktreePath);
+
   // The env-registry key this tree allocated under: `<f>` for morph/<f>,
   // `task/<n>` for morph-task/<n>. Read BEFORE the teardown (the entry is gone
   // from `git worktree list` afterwards). The old `'worktree'` placeholder
@@ -1683,9 +1657,13 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     e2e = tearDownFeatureStack(envKey || feature || basename(worktreePath), { root, worktreePath, volumes: false });
   } catch { e2e = null; /* fail-open */ }
 
+  // The stamp this removal's backup is written under — protected from the
+  // retention that runs after it.
+  const stamp = newBackupStamp();
   const teardown = await teardownWorktree(worktreePath, {
     root,
     feature: feature || envKey || 'worktree',
+    stamp,
     branch,
     options: { discardIgnored: options.discardIgnored === true },
     // Removing a worktree is not closing a feature: the branch is the work, and
@@ -1724,6 +1702,11 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     if (teardown.infraLeftUnlinked.length) out.infraLeftUnlinked = teardown.infraLeftUnlinked;
     out.hint = teardown.declineReason;
   }
+  // After the new backup, never before — and never the new backup itself.
+  if (teardown.ignoredBackup) {
+    const retention = enforceBackupRetention(root, { protectStamps: [stamp] });
+    if (retention) out.backupRetention = retention;
+  }
   emit(out, teardown.worktreeRemoved ? 0 : 1);
 }
 

package/src/commands/state/advance.js

@@ -6,6 +6,7 @@ import { getFeature, setApprovalGate, derivePhase } from '../../core/state/state
 import { unmetPrereqs } from '../../core/state/gate-order.js';
 import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
+import { uiuxAutoApprovalBlock } from '../../lib/specs/screen-checklist.js';
 
 const FRAMEWORK_DIR = fileURLToPath(new URL('../../../framework/', import.meta.url));
 
@@ -169,6 +170,19 @@ export async function advanceCommand(featureName, options = {}) {
     const gate = PHASE_GATE[phase];
     const approvedBy = resolveApprovedBy(options);
 
+    // The screen checklist is part of what the uiux phase owes. The predicate
+    // is approve.js's too: an "auto" signature never closes a gate the
+    // gate-check would pause, and a recorded decision or a human signature
+    // (--approver) is the answer to that pause; --force is not, as in approve.
+    const checklistBlock = phase === 'uiux' ? uiuxAutoApprovalBlock(process.cwd(), featureName, feature) : null;
+    if (checklistBlock && approvedBy === 'auto') {
+      console.error(chalk.red(`\n❌ A fase "uiux" não pode ser encerrada com assinatura automática — ${checklistBlock}.`));
+      console.error(chalk.gray('\n   Complete o checklist (ver a skill morph-uiux) e rode de novo. Quem decidiu aprovar assim'));
+      console.error(chalk.gray(`   mesmo grava a decisão (morph-spec gate-decision ${featureName} uiux --pause false --reason "...")`));
+      console.error(chalk.gray('   ou assina com --approver <nome>. O --force não dispensa o checklist.\n'));
+      process.exit(1);
+    }
+
     // Gate monotonicity (mirrors approve.js): advance is a gate write-path too,
     // so it must not stamp gate N while a predecessor is pending. In the
     // sanctioned flow advance is always in-order (it approves G1 before the plan
@@ -242,6 +256,10 @@ export async function advanceCommand(featureName, options = {}) {
     if (missingArtifacts.length) {
       console.log(chalk.yellow(`   ⚠️  --force: avançou SEM ${missingArtifacts.join(', ')}.`));
     }
+    if (checklistBlock) {
+      const by = options.force ? '--force' : `aprovado por ${approvedBy}`;
+      console.log(chalk.yellow(`   ⚠️  ${by}: avançou com o ${checklistBlock}.`));
+    }
     // Report what actually happened: claiming "approved (auto)" when nothing
     // was written is how the destroyed signature stayed invisible.
     if (gate && alreadyApproved) {

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('');