@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/src/commands/project/doctor.js

@@ -16,7 +16,7 @@ import {
   getInstalledCLIVersion
 } from '../../utils/version-checker.js';
 import { resetMorphSettings } from '../../utils/claude-settings-manager.js';
-import { checkMissingAgents, checkAgentsDrift } from '../../utils/agents-installer.js';
+import { checkMissingAgents, checkAgentsDrift, maxTurnsError, surfacesError } from '../../utils/agents-installer.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
 import { auditGraph } from '../../lib/graph/graph-health.js';
 import { auditFeatureLifecycle } from '../../core/state/lifecycle-audit.js';
@@ -44,10 +44,10 @@ function normCwd(root, cwd) {
 /**
  * Check which required Claude Code plugins are installed.
  * @param {Object} pluginsData - The `plugins` object from installed_plugins.json
- * @returns {{ superpowers: boolean, context7: boolean }}
+ * @returns {{ context7: boolean }}
  */
 export function checkInstalledPlugins(pluginsData) {
-  const REQUIRED = ['superpowers', 'context7'];
+  const REQUIRED = ['context7'];
   return Object.fromEntries(
     REQUIRED.map(name => [name, `${name}@claude-plugins-official` in (pluginsData || {})])
   );
@@ -191,6 +191,23 @@ export function validateAgentsJson(agentsData) {
     });
   }
 
+  // 4: maxTurns (ADR-004) — the installer's own rule, so this cannot pass a
+  // value the installer refuses. ERROR, not warn: that persona is not generated.
+  const maxTurnsErrors = agentEntries
+    .map(([id, data]) => maxTurnsError(id, data?.maxTurns))
+    .filter(Boolean);
+  checks.push(maxTurnsErrors.length > 0
+    ? { name: 'agents.json maxTurns', status: 'error', msg: maxTurnsErrors.join(' | ') }
+    : { name: 'agents.json maxTurns', status: 'ok' });
+
+  // 5: surfaces — same installer rule, same severity: the persona is not generated.
+  const surfacesErrors = agentEntries
+    .map(([id, data]) => surfacesError(id, data?.surfaces, data?.standards))
+    .filter(Boolean);
+  checks.push(surfacesErrors.length > 0
+    ? { name: 'agents.json surfaces', status: 'error', msg: surfacesErrors.join(' | ') }
+    : { name: 'agents.json surfaces', status: 'ok' });
+
   if (missingV5Fields.length > 0 && isV5) {
     const sample = missingV5Fields.slice(0, 3).join(', ');
     checks.push({
@@ -348,12 +365,23 @@ async function doctorFullCommand(frameworkRoot) {
           projectTags = getProjectTags(JSON.parse(rawCfg));
         } catch { /* no tags */ }
       }
-      const drift = checkAgentsDrift(frameworkRoot, join(frameworkRoot, '.morph/framework'), projectTags);
+      // The MCP registry comes from the package, like the installer's: the
+      // installed .morph/framework/ has no mcp/, and rendering without it
+      // flagged every persona with an `mcp` grant as stale on a clean install.
+      const drift = checkAgentsDrift(frameworkRoot, join(frameworkRoot, '.morph/framework'), projectTags,
+        { mcpRegistryDir: join(import.meta.dirname, '..', '..', '..', 'framework') });
+      if (drift.invalid.length > 0) {
+        check('Personas agents.json valid', false, false,
+          `${drift.invalid.map(i => i.reason).join(' | ')} — corrija o agents.json e rode 'morph-spec update'`);
+      }
       check(`Personas installed (${drift.expected - drift.missing.length}/${drift.expected})`,
         drift.missing.length === 0, false,
         drift.missing.length > 0 ? `missing: ${drift.missing.join(', ')} — run 'morph-spec setup-infra --reinstall'` : '');
+      // Name WHAT differs per file (frontmatter key or body): a hand-edited
+      // maxTurns and a CLI upgrade that changed the body read differently.
+      const staleList = drift.stale.map(f => `${f} (${(drift.staleFields[f] ?? []).join(', ')})`);
       check('Personas up-to-date (no drift)', drift.stale.length === 0, true,
-        drift.stale.length > 0 ? `stale/hand-edited: ${drift.stale.join(', ')} — regenerate via 'morph-spec setup-infra --reinstall'` : '');
+        drift.stale.length > 0 ? `stale/hand-edited: ${staleList.join(', ')} — regenerate via 'morph-spec setup-infra --reinstall'` : '');
       check('No orphan morph-* agents', drift.orphans.length === 0, true,
         drift.orphans.length > 0 ? `orphans: ${drift.orphans.join(', ')}` : '');
     } catch {
@@ -653,23 +681,54 @@ async function doctorMcpCommand(targetPath) {
  * Deleting a directory that still HOLDS something is reported with the exact
  * command, never performed — same PROVE-or-DECLINE discipline as the finish
  * teardown.
+ *
+ * `--prune` also applies the retention of the finish backups — the same policy
+ * every `finish` applies on its own, and the ONLY path that also applies it to
+ * the backups written before the retention existed (no manifest), counting
+ * them against the budget. Under `--json` its result rides in the JSON.
  */
 export async function doctorWorktreesCommand(targetPath, options = {}) {
   const { auditWorktrees, pruneWorktrees } = await import('../../lib/worktree/worktree-audit.js');
 
+  let backupRetention = null;
+  let prune = null;
   if (options.prune) {
     const beforeIssues = auditWorktrees(targetPath);
     const beforeMissing = beforeIssues.filter((i) => i.type === 'registered-missing').length;
     const beforeDangling = beforeIssues.filter((i) => i.type === 'dangling-registration').length;
     const beforeEmptyDirs = beforeIssues.filter((i) => i.type === 'unregistered-dir' && i.empty).length;
     const result = await pruneWorktrees(targetPath);
-    if (result.pruned) logger.success(`git worktree prune: ${beforeMissing} registro(s) órfão(s) removido(s).`);
-    else logger.warn(`prune falhou: ${result.error}`);
-    if (result.removedEmptyDirs.length) {
-      logger.success(`${result.removedEmptyDirs.length}/${beforeEmptyDirs} diretório(s) vazio(s) removido(s): ${result.removedEmptyDirs.join(', ')}`);
+    // Under --json the only thing on stdout is the JSON: a status line in front
+    // of it breaks every caller that parses the output.
+    prune = {
+      pruned: Boolean(result.pruned),
+      ...(result.pruned ? { orphanRegistrations: beforeMissing } : { error: result.error }),
+      removedEmptyDirs: result.removedEmptyDirs,
+      clearedRegistrations: result.clearedRegistrations.map((r) => r.feature),
+    };
+    if (!options.json) {
+      if (result.pruned) logger.success(`git worktree prune: ${beforeMissing} registro(s) órfão(s) removido(s).`);
+      else logger.warn(`prune falhou: ${result.error}`);
+      if (result.removedEmptyDirs.length) {
+        logger.success(`${result.removedEmptyDirs.length}/${beforeEmptyDirs} diretório(s) vazio(s) removido(s): ${result.removedEmptyDirs.join(', ')}`);
+      }
+      if (result.clearedRegistrations.length) {
+        logger.success(`registro de worktree limpo em ${result.clearedRegistrations.length}/${beforeDangling} feature(s): ${result.clearedRegistrations.map((r) => r.feature).join(', ')}`);
+      }
     }
-    if (result.clearedRegistrations.length) {
-      logger.success(`registro de worktree limpo em ${result.clearedRegistrations.length}/${beforeDangling} feature(s): ${result.clearedRegistrations.map((r) => r.feature).join(', ')}`);
+
+    const { resolvePrimaryRoot } = await import('./worktree.js');
+    const { applyBackupRetention, summarizeRetention } = await import('../../lib/worktree/finish-backup.js');
+    // The explicit prune is the one that reaches the backups written before the
+    // retention existed (no manifest): the automatic one never touches them.
+    backupRetention = summarizeRetention(applyBackupRetention(resolvePrimaryRoot(targetPath), { includeLegacy: true }));
+    if (backupRetention?.skipped && !options.json) {
+      logger.warn(`retenção dos backups do finish PULADA: ${backupRetention.skipped}`);
+    } else if (backupRetention && !options.json) {
+      const stripped = backupRetention.secretsStripped ? `, ${backupRetention.secretsStripped} arquivo(s) .env* apagado(s)` : '';
+      const adopted = backupRetention.adopted ? `, ${backupRetention.adopted} backup(s) antigo(s) mantido(s) ganharam manifesto` : '';
+      logger.success(`retenção dos backups do finish: ${backupRetention.removed ?? 0} pasta(s) removida(s)${stripped}${adopted}`);
+      for (const d of backupRetention.declined || []) logger.warn(`backup mantido: ${d.backup} (${d.reason})`);
     }
   }
 
@@ -684,7 +743,7 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
   const isProblem = (i) => !['info', 'warn'].includes(i.severity);
 
   if (options.json) {
-    console.log(JSON.stringify({ issues }, null, 2));
+    console.log(JSON.stringify({ issues, ...(prune ? { prune } : {}), ...(backupRetention ? { backupRetention } : {}) }, null, 2));
     return !issues.some(isProblem);
   }
 
@@ -1271,15 +1330,13 @@ export async function doctorCommand(options = {}) {
       } catch { /* non-fatal */ }
 
       // ── Claude Code Plugins ──────────────────────────────────────────────────
-      console.log(chalk.cyan('\n  Claude Code Plugins (required for /morph-init)'));
+      console.log(chalk.cyan('\n  Claude Code Plugins (required by morph-spec init)'));
       const pluginsFile = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
       let pluginData = { plugins: {} };
       try {
         pluginData = JSON.parse(await fs.readFile(pluginsFile, 'utf8'));
       } catch { /* file may not exist */ }
       const pluginStatus = checkInstalledPlugins(pluginData.plugins || {});
-      check('superpowers plugin', pluginStatus.superpowers, false,
-        'Run: morph-spec install-plugin superpowers');
       check('context7 plugin', pluginStatus.context7, false,
         'Run: morph-spec install-plugin context7');
     } else {
@@ -1390,6 +1447,19 @@ export async function doctorCommand(options = {}) {
     checks.push({ name: 'codebase graph', status: 'ok', msg: graphAudit.msg });
   }
 
+  // O que o morph-spec guarda dentro do `.git` (backups do finish, registros de
+  // porta e de claim) cresce sem aparecer em `git status`. Informação — `ok` ou
+  // `warn`, nunca falha —, e nenhuma linha quando não há nada guardado.
+  try {
+    const { resolvePrimaryRoot } = await import('./worktree.js');
+    const { morphStoreCheck } = await import('../../lib/worktree/finish-backup.js');
+    const storeCheck = morphStoreCheck(resolvePrimaryRoot(targetPath));
+    if (storeCheck) {
+      checks.push(storeCheck);
+      if (storeCheck.status === 'warn') hasWarnings = true;
+    }
+  } catch { /* fail-open */ }
+
   // Check key templates exist (in framework package, not project copy)
   const frameworkTemplatesRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'templates');
   const keyTemplates = [

package/src/commands/project/init.js

@@ -34,6 +34,7 @@ import { installAgents, installDomainAgents } from '../../utils/agents-installer
 import { getProjectTags } from '../../lib/stack-filter.js';
 import { updateCommand } from './update.js';
 import { resolvePrimaryRoot } from './worktree.js';
+import { registerProject } from '../../lib/projects/registry.js';
 
 /**
  * Guard against running a full `init` install from inside a secondary
@@ -135,8 +136,7 @@ export async function initCommand(options) {
     try {
       claudeConfigDetected = await detectClaudeConfig(targetPath);
       const hasIntegrations = claudeConfigDetected.plugins.length > 0
-        || claudeConfigDetected.mcpServers.length > 0
-        || claudeConfigDetected.superpowers.installed;
+        || claudeConfigDetected.mcpServers.length > 0;
 
       if (hasIntegrations) {
         spinner.stop();
@@ -287,7 +287,8 @@ export async function initCommand(options) {
       try {
         spinner.stop();
         const existingMcps = claudeConfigDetected?.mcpServers || [];
-        const orchestration = orchestrateMcpSetup(targetPath, detectedStack, existingMcps);
+        const orchestration = orchestrateMcpSetup(targetPath, detectedStack, existingMcps,
+          { integrations: config.project?.integrations ?? [] });
 
         const autoNames = Object.keys(orchestration.autoInstallable);
         const manualNames = Object.keys(orchestration.needsManualSetup);
@@ -467,6 +468,8 @@ export async function initCommand(options) {
     }
 
     spinner.succeed('MORPH-SPEC installed successfully!');
+    // The dashboard's portfolio learns about the project here (fail-open).
+    registerProject(targetPath, 'init');
 
     // Show next steps
     logger.blank();

package/src/commands/project/install-plugin-cmd.js

@@ -5,7 +5,7 @@ import { logger } from '../../utils/logger.js';
 export async function installPluginCommand(pluginName, _options) {
   if (!pluginName) {
     logger.error('Plugin name required. Usage: morph-spec install-plugin <name>');
-    logger.dim('  Available: superpowers, context7');
+    logger.dim('  Available: context7');
     process.exit(1);
   }
   try {

package/src/commands/project/update.js

@@ -33,6 +33,10 @@ import { getProjectTags } from '../../lib/stack-filter.js';
 import { updateClaudeMdAgentsBlock, installRulesForStack } from '../../scripts/setup-infra.js';
 import { reconcileLegacyTemplatesCopy } from '../../lib/installers/templates-reconcile.js';
 import { createEffects } from '../../lib/installers/effects.js';
+import { registerProject } from '../../lib/projects/registry.js';
+import {
+  writeGraphifyignore, describeOutdatedIgnore, graphifyignoreTracked,
+} from '../../lib/graph/graphifyignore.js';
 
 /**
  * Backup user's config.json before cleaning
@@ -725,6 +729,24 @@ export async function updateCommand(options = {}) {
     await updateGitignore(targetPath, fx);
     await ensureGitattributes(targetPath, fx);
 
+    // Migration: a .graphifyignore the previous version generated and nobody
+    // edited is swapped for the current one when its RULES change (test doubles
+    // and fixtures back in the graph — a header-only difference is left alone);
+    // an edited one is left alone, with the change to make. Only an existing
+    // file — the graph is opt-in, and `graph build` writes it. A tracked file
+    // reaches worktrees and teammates only once committed: each checkout reads
+    // its own.
+    let graphIgnore = null;
+    if (existsSync(join(targetPath, '.graphifyignore'))) {
+      updateSpinner.text = 'Checking .graphifyignore...';
+      graphIgnore = writeGraphifyignore(targetPath, projectTags, { fx });
+      if (graphIgnore.outdated) notices.push(describeOutdatedIgnore(graphIgnore.outdated));
+      if (graphIgnore.migrated && graphifyignoreTracked(targetPath)) {
+        notices.push('.graphifyignore é versionado: commite a migração (git add .graphifyignore) — '
+          + 'as worktrees e o resto do time leem o arquivo do próprio checkout e só recebem as regras novas depois do commit');
+      }
+    }
+
     // Migration: untrack a pre-v5 committed state.json so it stops being swept
     // into feature commits. Gitignore alone can't do this for an already-tracked file.
     const untracked = untrackCommittedStateJson(targetPath, fx);
@@ -737,6 +759,10 @@ export async function updateCommand(options = {}) {
     logger.blank();
 
     if (!dryRun) {
+      // The dashboard's portfolio learns about the project here (fail-open;
+      // outside the project, so not an effect of the update itself).
+      registerProject(targetPath, 'update');
+
       // Show version change
       if (projectCheck.current && projectCheck.current !== cliCheck.current) {
         logger.success(`Updated: ${projectCheck.current} → ${cliCheck.current}`);
@@ -769,6 +795,10 @@ export async function updateCommand(options = {}) {
       logger.dim(`  ✓ .claude/agents/ (${agentsResult?.agents?.length ?? '?'} personas — stack: ${tagsLabel})`);
       logger.dim(`  ✓ .claude/rules/ (${rulesResult?.installed ?? '?'} stack-filtered rules)`);
       if (commandsCopied) logger.dim('  ✓ .claude/commands/');
+      if (graphIgnore?.migrated) {
+        logger.dim('  ✓ .graphifyignore (dublês, fixtures e helpers de teste voltam ao grafo da raiz no próximo refresh');
+        logger.dim('    em background — início de sessão ou comando git do agente; numa worktree: morph-spec graph refresh)');
+      }
       if (untracked) {
         logger.dim('  ✓ .morph/state.json untracked (git rm --cached) — commit to finalize');
         logger.warn('Migration: .morph/state.json was removed from git tracking. The');

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) {