@polymorphism-tech/morph-spec 9.8.0 → 10.1.1

package/src/commands/project/init.js

@@ -1,5 +1,4 @@
-import { join, dirname, resolve } from 'path';
-import { fileURLToPath } from 'url';
+import { join, resolve } from 'path';
 import { homedir } from 'os';
 import fs from 'fs-extra';
 import ora from 'ora';
@@ -28,13 +27,43 @@ import {
   setupStitch,
   loadMcpRegistry
 } from '../../lib/installers/mcp-installer.js';
-import { setupInfra, installRulesForStack, installCommandsForStack } from '../../scripts/setup-infra.js';
-import { installSkills } from '../../utils/skills-installer.js';
-import { installAgents, installDomainAgents } from '../../utils/agents-installer.js';
+import { setupInfra } from '../../scripts/setup-infra.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
 import { updateCommand } from './update.js';
 import { resolvePrimaryRoot } from './worktree.js';
 import { registerProject } from '../../lib/projects/registry.js';
+import { setProjectStack } from '../../lib/installers/stack-sync.js';
+import { installStackAssets } from '../../lib/installers/stack-assets.js';
+
+const GREENFIELD_CHOICES = [
+  { name: 'dotnet+nextjs — stack do Morph: .NET 10 + EF Core/Neon + Next.js/Shadcn (recomendada)', value: { stack: 'dotnet+nextjs', integrations: ['neon'] } },
+  { name: 'dotnet — só a API .NET (EF Core/Neon)', value: { stack: 'dotnet', integrations: ['neon'] } },
+  { name: 'nextjs — só o app web Next.js', value: { stack: 'nextjs', integrations: [] } },
+  { name: 'Decidir depois (o /morph-plan pergunta)', value: null },
+];
+
+/** Empty project: `--stack` wins; a terminal is asked, the Morph stack first; no terminal leaves it to the plan. */
+export async function chooseGreenfieldStack(options = {}, { isTTY = process.stdin.isTTY, prompt = inquirer.prompt } = {}) {
+  if (options.stack) {
+    const integrations = String(options.with ?? '').split(',').map((t) => t.trim()).filter(Boolean);
+    return { stack: options.stack, integrations };
+  }
+  if (!isTTY) return null;
+  const { stackChoice } = await prompt([{
+    type: 'list',
+    name: 'stackChoice',
+    message: 'Projeto novo: qual stack?',
+    choices: GREENFIELD_CHOICES,
+  }]);
+  return stackChoice;
+}
+
+async function reinstallForStack(targetPath, stackTags, spinner) {
+  if (stackTags.length === 0) return;
+  spinner.start('Re-installing stack-filtered assets...');
+  await installStackAssets(targetPath, stackTags);
+  spinner.succeed(`Stack-filtered assets reinstalled for [${stackTags.join(', ')}]`);
+}
 
 /**
  * A linked worktree junctions `.claude/` and `.morph/framework/` but not `.morph/config`/state:
@@ -196,15 +225,17 @@ export async function initCommand(options) {
           if (structure?.uiLibrary) logger.dim(`UI Library: ${structure.uiLibrary}`);
           if (structure?.integrations?.length > 0) logger.dim(`Integrations: ${structure.integrations.join(', ')}`);
 
-          const { standardsChoice } = await inquirer.prompt([{
-            type: 'list',
-            name: 'standardsChoice',
-            message: 'How should morph-spec handle your project standards?',
-            choices: [
-              { name: 'Keep morph-spec defaults (recommended)', value: 'morph-spec' },
-              { name: 'Detect project-specific standards', value: 'detect' }
-            ]
-          }]);
+          const { standardsChoice } = process.stdin.isTTY
+            ? await inquirer.prompt([{
+              type: 'list',
+              name: 'standardsChoice',
+              message: 'How should morph-spec handle your project standards?',
+              choices: [
+                { name: 'Keep morph-spec defaults (recommended)', value: 'morph-spec' },
+                { name: 'Detect project-specific standards', value: 'detect' }
+              ]
+            }])
+            : { standardsChoice: 'morph-spec' };
 
           if (standardsChoice === 'detect') {
             spinner.start('Generating project-specific standards...');
@@ -215,30 +246,27 @@ export async function initCommand(options) {
             logger.dim('Review and edit .morph/context/standards.md as needed.');
           }
 
-          const stackTags = getProjectTags(config);
-          if (stackTags.length > 0) {
-            spinner.start('Re-installing stack-filtered assets...');
-            const frameworkDir = join(targetPath, '.morph', 'framework');
-            const fwSrcDir = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'framework');
-
-            const rulesSrc = join(fwSrcDir, 'rules');
-            const rulesDest = join(targetPath, '.claude', 'rules');
-            installRulesForStack(rulesSrc, rulesDest, stackTags);
-            installCommandsForStack(join(fwSrcDir, 'commands'), join(targetPath, '.claude', 'commands'), stackTags);
-
-            await installSkills(targetPath, { projectTags: stackTags });
-
-            await installAgents(targetPath, fwSrcDir, { projectTags: stackTags });
-            await installDomainAgents(targetPath, fwSrcDir, { projectTags: stackTags });
-
-            spinner.succeed(`Stack-filtered assets reinstalled for [${stackTags.join(', ')}]`);
-          }
-
+          await reinstallForStack(targetPath, getProjectTags(config), spinner);
           spinner.start('Continuing...');
         }
       } catch (error) {
         logger.dim(`  Stack detection skipped: ${error.message}`);
       }
+    } else {
+      const choice = await chooseGreenfieldStack(options);
+      if (choice) {
+        spinner.stop();
+        const result = setProjectStack(targetPath, choice.stack, { integrations: choice.integrations, log: (line) => logger.dim(line) });
+        if (result.error) {
+          logger.warn(`Stack não declarada: ${result.error}`);
+        } else {
+          config = await readJson(configPath);
+          await reinstallForStack(targetPath, getProjectTags(config), spinner);
+        }
+        spinner.start('Continuing...');
+      } else {
+        logger.dim('  Stack: não declarada — o /morph-plan pergunta antes de planejar (recomendada: a do Morph)');
+      }
     }
 
     let mcpSetupResult = null;
@@ -460,13 +488,12 @@ export async function initCommand(options) {
 
     const agents = infraResult?.agents;
     if (agents) {
-      const total = (agents.tier1 || 0) + (agents.tier2 || 0) + (agents.specialists || 0) + (agents.personas || 0);
-      logger.dim(`  ✓ .claude/agents/ (${total} domain personas installed)`);
+      logger.dim(`  ✓ .claude/agents/ (${agents.installed ?? 0} Gate 3 agents installed)`);
     } else {
       logger.dim('  ✓ .claude/agents/ (native subagents installed)');
     }
 
-    logger.dim('  ✓ ~/.claude/statusline.sh (global statusline installed)');
+    logger.dim('  ✓ ~/.claude/statusline.js (global statusline installed)');
 
     logger.blank();
     const globalSettingsPath = join(homedir(), '.claude', 'settings.local.json');

package/src/commands/project/stack-scan.js

@@ -1,56 +1,17 @@
-import chalk from 'chalk';
-import { existsSync, mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
-import { getFeatureDir } from '../../core/paths/output-schema.js';
 import { readMorphConfig } from '../../lib/tasks/test-runner.js';
-import { notAuditedReason, scanStack, renderStackScan } from '../../lib/stack/stack-scan.js';
-import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
+import { scanStack, renderStackScan } from '../../lib/stack/stack-scan.js';
 
-export const STACK_SCAN_FILE = 'stack-scan.md';
-
-/** Scan the tree at `cwd`; with a feature, write `2-plan/stack-scan.md`. */
+/** Scan the tree at `cwd`; prints, never writes — the plan reads stdout. */
 export function runStackScan(featureName, cwd = process.cwd()) {
   const result = scanStack(cwd, readMorphConfig(cwd));
-  const markdown = renderStackScan(result, featureName ?? 'projeto');
-  if (!featureName) return { ...result, markdown, written: null, exit: 0 };
-
-  const featureDir = join(cwd, getFeatureDir(featureName));
-  if (!existsSync(featureDir)) return { ...result, markdown, written: null, exit: 2, error: 'feature-not-found' };
-  const planDir = join(featureDir, '2-plan');
-  mkdirSync(planDir, { recursive: true });
-  const written = join(planDir, STACK_SCAN_FILE);
-  writeFileSync(written, markdown, 'utf8');
-  return { ...result, markdown, written, exit: 0 };
+  return { ...result, markdown: renderStackScan(result, featureName ?? 'projeto'), exit: 0 };
 }
 
 export function stackScanCommand(featureName, options = {}) {
-  if (featureName) {
-    const owner = assertOwnerTree(featureName, process.cwd());
-    if (owner.blocked) {
-      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec stack-scan ${featureName}`)) {
-        console.error(chalk[tone](text));
-      }
-      process.exit(1);
-    }
-  }
-
   const result = runStackScan(featureName);
   if (options.json) {
     const { markdown, ...rest } = result;
     console.log(JSON.stringify(rest, null, 2));
-    process.exit(result.exit);
-  }
-  if (result.error === 'feature-not-found') {
-    console.error(chalk.red(`stack-scan: a feature "${featureName}" não existe — rode morph-spec create ${featureName} antes`));
-    process.exit(2);
-  }
-  if (result.written) {
-    const high = result.deviations.filter((d) => d.severity === 'Bloqueante' || d.severity === 'Alto').length;
-    console.log(chalk.green(`✓ stack-scan: ${join(getFeatureDir(featureName), '2-plan', STACK_SCAN_FILE)} gravado`));
-    const summary = result.greenfield ? 'greenfield'
-      : !result.audited ? notAuditedReason(result)
-      : `${result.deviations.length} desvio(s), ${high} Bloqueante/Alto`;
-    console.log(chalk.gray(`  ${summary}`));
   } else {
     process.stdout.write(result.markdown);
   }

package/src/commands/project/stack-set.js

@@ -0,0 +1,26 @@
+import chalk from 'chalk';
+import { setProjectStack } from '../../lib/installers/stack-sync.js';
+import { installStackAssets } from '../../lib/installers/stack-assets.js';
+import { getProjectTags } from '../../lib/stack-filter.js';
+
+export async function stackSetCommand(stack, options = {}) {
+  const integrations = String(options.with ?? '').split(',').map((t) => t.trim()).filter(Boolean);
+  const result = setProjectStack(process.cwd(), stack, {
+    integrations,
+    log: options.json ? () => {} : (line) => console.log(chalk.gray(line)),
+  });
+  if (result.error) {
+    if (options.json) console.log(JSON.stringify({ error: result.error }, null, 2));
+    else console.error(chalk.red(`✗ ${result.error}`));
+    process.exit(1);
+  }
+  const { stack: declared, integrations: declaredIntegrations, sync } = result;
+  await installStackAssets(process.cwd(), getProjectTags({ project: { stack: declared, integrations: declaredIntegrations } }));
+  if (options.json) {
+    console.log(JSON.stringify({ stack: declared, integrations: declaredIntegrations, rulesAdded: sync.added, rulesUpdated: sync.updated }, null, 2));
+  } else {
+    console.log(chalk.green(`✓ stack ${declared}`) + chalk.gray(` — rules, commands e skills da stack instalados (${sync.added.length + sync.updated.length} rule(s) de domínio nova(s))`));
+    console.log(chalk.yellow('  As rules carregam no início de uma sessão do Claude Code: implemente numa sessão nova.'));
+  }
+  process.exit(0);
+}

package/src/commands/project/status.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { loadState, getFeature, derivePhase, deriveOutputs } from '../../core/state/state-manager.js';
-import { sliceProgress } from '../../../framework/hooks/shared/slice-progress.js';
+import { implementProgress } from '../../../framework/hooks/shared/report-progress.js';
 import { formatNext } from '../../../framework/hooks/shared/next-step.js';
 import { nextStepFor } from '../../lib/next-step.js';
 
@@ -20,8 +20,8 @@ const PHASE_ORDER = [
 
 const PHASE_OUTPUTS = {
   plan: ['plan', 'checks'],
-  uiux: ['uiDesignSystem', 'uiMockups', 'uiComponents', 'uiFlows'],
-  implement: [],
+  uiux: ['uiMockups'],
+  implement: ['implementReport'],
   review: ['verifierReport', 'reviewerReport']
 };
 
@@ -118,7 +118,7 @@ export async function statusCommand(featureName, options = {}) {
   if (!feature.outputs) {
     feature.outputs = deriveOutputs(featureName, process.cwd());
   }
-  const slices = sliceProgress(featurePath);
+  const scenarios = implementProgress(featurePath);
 
   if (options.json) {
     const status = {
@@ -137,7 +137,7 @@ export async function statusCommand(featureName, options = {}) {
         created: output.created,
         path: output.path
       })),
-      slices,
+      scenarios,
       approvals: feature.approvalGates || {},
       next: nextStepFor(featureName, process.cwd())
     };
@@ -177,14 +177,13 @@ export async function statusCommand(featureName, options = {}) {
   }
   console.log('');
 
-  if (slices && slices.total > 0) {
-    console.log(chalk.white.bold('Fatias:'));
-    const percentage = Math.round((slices.done / slices.total) * 100);
-    console.log(`  Total: ${slices.total}`);
-    console.log(chalk.green(`  ✓ Feitas: ${slices.done} (${percentage}%)`));
-    if (slices.partial > 0) console.log(chalk.cyan(`  ▶ Parciais: ${slices.partial}`));
-    if (slices.blocked > 0) console.log(chalk.yellow(`  ⏸ Bloqueadas (esperam decisão): ${slices.blocked}`));
-    if (slices.pending > 0) console.log(chalk.gray(`  ⬜ Pendentes: ${slices.pending}`));
+  if (scenarios && scenarios.total > 0) {
+    console.log(chalk.white.bold('Cenários (3-implement/report.md):'));
+    const percentage = Math.round((scenarios.done / scenarios.total) * 100);
+    console.log(`  Total: ${scenarios.total}`);
+    console.log(chalk.green(`  ✓ Feitos: ${scenarios.done} (${percentage}%)`));
+    if (scenarios.blocked > 0) console.log(chalk.yellow(`  ⏸ Bloqueados (esperam decisão): ${scenarios.blocked}`));
+    if (scenarios.pending > 0) console.log(chalk.gray(`  ⬜ Pendentes: ${scenarios.pending}`));
     console.log('');
   }
 

package/src/commands/project/update.js

@@ -1,7 +1,7 @@
 import { join, dirname, relative, isAbsolute } from 'path';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
-import { existsSync, readdirSync } from 'fs';
+import { existsSync, readdirSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -27,9 +27,10 @@ import {
 } from '../../utils/version-checker.js';
 import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
 import { installSkills } from '../../utils/skills-installer.js';
-import { installAgents, installDomainAgents } from '../../utils/agents-installer.js';
+import { installAgents } from '../../utils/agents-installer.js';
 import { injectMorphImport } from '../../utils/claude-md-injector.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
+import { detectStackTags, mergeDetectedTags } from '../../lib/installers/stack-sync.js';
 import { updateClaudeMdAgentsBlock, installRulesForStack, installCommandsForStack } from '../../scripts/setup-infra.js';
 import { reconcileLegacyTemplatesCopy } from '../../lib/installers/templates-reconcile.js';
 import { createEffects } from '../../lib/installers/effects.js';
@@ -145,6 +146,26 @@ export function stateJsonIsTracked(targetPath) {
   }
 }
 
+const SLICES_HEADING = /^## Fatias\s*$/m;
+
+/** Active features still planned in 9.x slices: a plan with `## Fatias` and no `3-implement/report.md` yet. */
+export function legacySliceFeatures(targetPath) {
+  const featuresDir = join(targetPath, '.morph', 'features');
+  let names;
+  try { names = readdirSync(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name); } catch { return []; }
+  return names.filter((name) => {
+    const dir = join(featuresDir, name);
+    if (existsSync(join(dir, '3-implement', 'report.md'))) return false;
+    try { return SLICES_HEADING.test(readFileSync(join(dir, '2-plan', 'plan.md'), 'utf8')); } catch { return false; }
+  }).sort();
+}
+
+export function legacySliceNotice(names) {
+  if (names.length === 0) return null;
+  return `Feature(s) planejada(s) em fatias (9.x): ${names.join(', ')}. Plano não aprovado: tire \`## Fatias\` e rode \`morph-spec plan-check <f>\`. `
+    + 'Já em implement: segue pelos `reports/F*.md`; para o formato novo, crie `3-implement/report.md` com uma linha por `Cn` (CHANGELOG 10.0.0).';
+}
+
 export function untrackCommittedStateJson(targetPath, fx = createEffects({ dryRun: false })) {
   if (!stateJsonIsTracked(targetPath)) return false;
   return fx.gitIndex('rm --cached --quiet', '.morph/state.json', { cwd: targetPath });
@@ -487,6 +508,19 @@ export async function updateCommand(options = {}) {
     try {
       if (configBackup) projectTags = getProjectTags(configBackup);
     } catch {}
+    // The same detection as `syncStackRules`, folded in before the installs: `restoreUserConfig`
+    // writes `configBackup`, and a dry run sees `.claude/rules/` before the clean, not after.
+    if (configBackup) {
+      try {
+        const detected = detectStackTags(targetPath, { config: configBackup });
+        const merged = mergeDetectedTags(configBackup, detected.persist);
+        if (merged.changed) {
+          configBackup.project = merged.config.project;
+          logger.dim(`  ✓ config.json: + ${merged.added.join(', ')} (detectado nos arquivos)`);
+        }
+        projectTags = [...new Set([...getProjectTags(configBackup), ...detected.tags])];
+      } catch {}
+    }
 
     let commandsCopied = false;
     const commandsSrc = join(frameworkDir, 'commands');
@@ -504,7 +538,6 @@ export async function updateCommand(options = {}) {
 
     updateSpinner.text = 'Syncing agents to .claude/agents/...';
     const agentsResult = await installAgents(targetPath, frameworkDir, { projectTags, fx });
-    await installDomainAgents(targetPath, frameworkDir, { projectTags, fx });
 
     updateSpinner.text = 'Syncing rules to .claude/rules/...';
     const rulesSrc = join(frameworkDir, 'rules');
@@ -566,6 +599,9 @@ export async function updateCommand(options = {}) {
       }
     }
 
+    const sliceNotice = legacySliceNotice(legacySliceFeatures(targetPath));
+    if (sliceNotice) notices.push(sliceNotice);
+
     const untracked = untrackCommittedStateJson(targetPath, fx);
 
     updateSpinner.text = 'Saving version info...';

package/src/commands/project/worktree.js

@@ -320,15 +320,6 @@ export async function runWorktreeSetup(feature, options = {}) {
 
     const graph = seedWorktreeGraph(worktreePath, cwd);
 
-    // Fail-open; a no-op under `create --worktree`, which regenerates it after its copy.
-    try {
-      if (existsSync(join(worktreePath, '.morph', 'features', feature, 'feature.json'))) {
-        const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
-        // `worktree` is root-owned and absent from this branch copy: pass it so the doc says "Local: worktree".
-        writeHandoff(feature, worktreePath, { worktree: { path: worktreePath, branch } });
-      }
-    } catch {}
-
     try {
       const { loadState, saveState } = await import('../../core/state/state-manager.js');
       const state = loadState(false);
@@ -834,9 +825,9 @@ export function pickRemovalFailure(stderrs) {
 
 /**
  * PROVE-or-DECLINE. `refused` (proved unsafe) restores the junctions; a git FAILURE leaves them down
- * (`infraLeftUnlinked`) unless `relinkOnFailure` (the reaper, whose agent may still be live).
+ * (`infraLeftUnlinked`).
  */
-export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false, relinkOnFailure = false, stamp }) {
+export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false, stamp }) {
   // ORDER IS LOAD-BEARING: unlink the junctions BEFORE git touches the dir. `git worktree remove`
   // follows them and deletes the root's installation; a declined path is repaired by the rollback below.
   const unlinked = unlinkWorktreeInfraLinks(worktreePath, root);
@@ -881,8 +872,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   // would make the next retry (or a raw `--force`) follow the junctions out.
   const refused = !canRemove;
   let relinked = false;
-  const relinkAfterFailure = relinkOnFailure && !refused && !worktreeRemoved && !removalFailure?.alreadyDeregistered;
-  if ((refused || relinkAfterFailure) && unlinked.length && existsSync(worktreePath)) {
+  if (refused && unlinked.length && existsSync(worktreePath)) {
     try {
       setupInfraLinks(worktreePath, root);
       relinked = true;
@@ -1055,7 +1045,6 @@ export async function runWorktreeRemove(featureArg, options = {}) {
     options: { discardIgnored: options.discardIgnored === true },
     // The branch is the work: deleting it would discard unintegrated commits. Opt-in only.
     deleteBranch: options.deleteBranch === true,
-    relinkOnFailure: options.relinkOnFailure === true,
     // Re-run advice must address the worktree the way it was addressable here:
     // a `--target` worktree has no feature name that would resolve.
     addressByTarget: !featureAddressable,

package/src/commands/state/advance.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { getFeature, setApprovalGate, derivePhase } from '../../core/state/state-manager.js';
@@ -8,7 +8,7 @@ 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';
 import { seedDesignArtifacts } from '../../lib/specs/design-seed.js';
-import { sliceProgress } from '../../../framework/hooks/shared/slice-progress.js';
+import { implementProgress, reportPath, reportSkeleton } from '../../../framework/hooks/shared/report-progress.js';
 import { autoApprovalRefusal, printRefusal } from './auto-approval.js';
 import { seedDotnetBuildIgnores } from '../../lib/stack/dotnet-build-ignores.js';
 
@@ -38,17 +38,25 @@ function missingPhaseArtifacts(phase, featurePath) {
       const rel = `${entry.phaseDir}/${entry.filename}`;
       if (!existsSync(join(featurePath, entry.phaseDir, entry.filename))) missing.push(rel);
     }
-    if (phase === 'implement') missing.push(...unfinishedSliceReports(featurePath));
+    if (phase === 'implement') missing.push(...unfinishedScenarios(featurePath));
     return missing;
   } catch {
     return [];
   }
 }
 
-function unfinishedSliceReports(featurePath) {
-  const progress = sliceProgress(featurePath);
+function unfinishedScenarios(featurePath) {
+  const progress = implementProgress(featurePath);
   if (!progress) return ['2-plan/checks.json'];
-  return progress.slices.filter((s) => s.status !== 'feito').map((s) => `3-implement/reports/${s.id}.md`);
+  const open = progress.checks.filter((c) => c.status !== 'feito').map((c) => c.id);
+  return open.length ? [`3-implement/report.md (${open.join(', ')} não feito)`] : [];
+}
+
+function seedReport(featurePath, featureName) {
+  const path = reportPath(featurePath);
+  if (existsSync(path)) return;
+  const progress = implementProgress(featurePath);
+  if (progress) writeFileSync(path, reportSkeleton(featureName, progress.checks.map((c) => c.id)));
 }
 
 // Message-only and fail-open: names the worktree that holds the artifacts instead of demanding
@@ -114,10 +122,6 @@ export async function advanceCommand(featureName, options = {}) {
       mkdirSync(join(featurePath, '1-design'), { recursive: true });
       reportDesignSeed(seedDesignArtifacts(featureName, process.cwd()));
       reportDotnetIgnores(seedDotnetBuildIgnores(process.cwd(), { featureName }));
-      try {
-        const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
-        writeHandoff(featureName, process.cwd());
-      } catch { /* fail-open */ }
       console.log(chalk.green(`\n✅ "${featureName}": gate plan já aprovado — ramo de design aberto (1-design/).\n`));
       return;
     }
@@ -129,7 +133,7 @@ export async function advanceCommand(featureName, options = {}) {
       return;
     }
 
-    // `implement` has no gate, so this is what keeps unfinished slice reports out of review.
+    // `implement` has no gate, so this is what keeps unfinished scenarios out of review.
     // `--force` bypasses it but still names what was skipped.
     const missingArtifacts = missingPhaseArtifacts(phase, featurePath);
     if (missingArtifacts.length && !options.force) {
@@ -166,7 +170,7 @@ export async function advanceCommand(featureName, options = {}) {
     }
 
     // `setApprovalGate` replaces the gate whole: rewriting an approved gate would turn a human
-    // signature into "auto". Skips ONLY the write, so the scaffold and handoff below still run.
+    // signature into "auto". Skips ONLY the write, so the scaffold below still runs.
     const priorGate = gate ? feature.approvalGates?.[gate] : null;
     const alreadyApproved = priorGate?.approved === true;
 
@@ -193,13 +197,9 @@ export async function advanceCommand(featureName, options = {}) {
       if (!existsSync(nextPath)) mkdirSync(nextPath, { recursive: true });
     }
     if (nextDir === '1-design') reportDesignSeed(seedDesignArtifacts(featureName, process.cwd()));
+    if (nextDir === '3-implement') seedReport(featurePath, featureName);
     if (phase === 'plan') reportDotnetIgnores(seedDotnetBuildIgnores(process.cwd(), { featureName }));
 
-    // A phase transition is when a session hands the feature over: refresh handoff.md.
-    try {
-      const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
-      writeHandoff(featureName, process.cwd());
-    } catch { /* fail-open */ }
 
     console.log(chalk.green(`\n✅ Advanced "${featureName}" past the ${phase} phase.`));
     if (missingArtifacts.length) {

package/src/commands/state/approve.js

@@ -260,12 +260,6 @@ export async function approveCommand(featureName, gateName, options = {}) {
       ...(selfAssessed ? { selfAssessed: true } : {}),
     });
 
-    // Approving is a session handoff too; a regeneration failure must never fail the approval.
-    try {
-      const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
-      writeHandoff(featureName, process.cwd());
-    } catch { /* fail-open */ }
-
     if (selfAssessed) {
       console.log(chalk.yellow('\n⚠️  Gate 3 aprovado SEM os relatórios de review independentes (--self-assessed).'));
       console.log(chalk.gray('   Registrado em feature.json → approvalGates.review.selfAssessed.'));

package/src/commands/state/archive.js

@@ -1,9 +1,10 @@
 import chalk from 'chalk';
-import { existsSync, renameSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, renameSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs';
 import { join, resolve, sep } from 'path';
 import { execFileSync } from 'child_process';
 import { ADR_INDEX_PATHSPEC, updateAdrIndex } from '../../lib/specs/adr-index.js';
 import { isValidFeatureName } from '../project/worktree.js';
+import { RECAP_FILES, writeRecap } from './recap.js';
 
 function assertContained(scopeDir, name, target) {
   const scopeAbs = resolve(scopeDir) + sep;
@@ -38,6 +39,17 @@ function readReviewApproved(fjPath) {
  * Never calls process.exit, and resolves everything from `cwd` so `finish` can archive inside a
  * worktree. Idempotent: an existing archive returns `{ ok: true, alreadyArchived: true }`.
  */
+// plan.md stays: a squash merge drops every file born and pruned inside the branch.
+function pruneArchive(dir) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'feature.json' || Object.values(RECAP_FILES).includes(entry)) continue;
+    if (entry !== '2-plan') { rmSync(join(dir, entry), { recursive: true, force: true }); continue; }
+    for (const planEntry of readdirSync(join(dir, entry))) {
+      if (planEntry !== 'plan.md') rmSync(join(dir, entry, planEntry), { recursive: true, force: true });
+    }
+  }
+}
+
 export function runArchive(feature, opts = {}) {
   const cwd = opts.cwd || process.cwd();
 
@@ -71,6 +83,10 @@ export function runArchive(feature, opts = {}) {
   }
 
   const useGit = opts.git !== false && isGitRepo(cwd);
+  let archivedFromSha = null;
+  if (useGit) {
+    try { archivedFromSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim(); } catch { /* no commit yet */ }
+  }
 
   // `git mv` keeps history and stages in one step; an untracked folder falls back to rename.
   mkdirSync(archiveDir, { recursive: true });
@@ -96,6 +112,7 @@ export function runArchive(feature, opts = {}) {
       const fj = JSON.parse(readFileSync(fjPathAfter, 'utf8'));
       fj.status = 'completed';
       fj.archivedAt = new Date().toISOString();
+      if (archivedFromSha) fj.archivedFrom = { sha: archivedFromSha };
       fj.updatedAt = fj.archivedAt;
       writeFileSync(fjPathAfter, JSON.stringify(fj, null, 2), 'utf8');
       if (useGit && staged) {
@@ -113,6 +130,13 @@ export function runArchive(feature, opts = {}) {
     try { execFileSync('git', ['add', '-A', '--', ADR_INDEX_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
   }
 
+  // Before the prune: the recap reads the Gate 3 reports the archive does not keep.
+  const recap = opts.recap === false ? null : writeRecap(archivePath, archivePath, feature, { cwd });
+  pruneArchive(archivePath);
+  if (useGit && staged) {
+    try { execFileSync('git', ['add', '-A', '--', archivePathspec], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
+  }
+
   // Scoped to this feature's pathspec, never `commit -a`. The ADR index joins only when it
   // changed: git refuses a pathspec that matches nothing, leaving the tree dirty for the merge.
   let committed = false;
@@ -144,6 +168,7 @@ export function runArchive(feature, opts = {}) {
 
   return {
     ok: true, archived: true, committed, staged, archivePath,
+    recap: recap?.ok ? recap.path : null,
     revocationProblems: adrIndex.problems,
     adrIndex: adrIndex.changed ? { added: adrIndex.added, revoked: adrIndex.revoked, narrowed: adrIndex.narrowed } : null,
   };
@@ -180,6 +205,7 @@ export async function archiveCommand(featureName, options = {}) {
 
     console.log(chalk.green(`\n📦 Archived "${featureName}" → .morph/archive/${featureName}/`));
     console.log(chalk.gray(`   status: completed, archivedAt stamped in feature.json.`));
+    if (result.recap) console.log(chalk.gray(`   recap: ${result.recap} (morph-spec recap ${featureName} --piper narra com o Piper)`));
     if (result.adrIndex) {
       const { added, revoked, narrowed } = result.adrIndex;
       console.log(chalk.gray(`   ADR index (.morph/specs/adrs/): +${added.length} −${revoked.length} ~${narrowed.length}.`));

package/src/commands/state/auto-approval.js

@@ -30,11 +30,11 @@ export function autoApprovalRefusal({ cwd, featureName, feature, gate, approvedB
   }
 
   if (gate === 'plan') {
-    const block = planAutoApprovalBlock(cwd, featureName);
+    const block = planAutoApprovalBlock(cwd, featureName, feature);
     if (block) {
       return {
         title: `O gate "plan" não pode ser auto-aprovado — ${block}.`,
-        hints: ['Com plan-check verde, rode de novo; ou aprove com --approver <nome>. O --force não dispensa o checks.json.'],
+        hints: ['Sem checks.json fresco: plan-check verde e rode de novo. Com degrau: aprove com --approver <nome> ou pela resposta humana. O --force não dispensa nenhum dos dois.'],
       };
     }
   }

package/src/commands/state/create.js

@@ -132,7 +132,7 @@ export async function createCommand(featureName, options = {}) {
     const alreadyExists = existsSync(join(process.cwd(), '.morph', 'features', featureName, 'feature.json'));
     if (!alreadyExists && (description === null || String(description).trim() === '')) {
       console.error(chalk.red(`\n❌ A feature needs a description at birth: "${featureName}"`));
-      console.error(chalk.gray('   Pass --description "<what/why>" (or --request "<pedido>", which seeds it).'));
+      console.error(chalk.gray('   Pass --description "<what/why>" (or --request '<pedido>', which seeds it).'));
       console.error(chalk.gray('   This keeps features identifiable — no more anonymous scaffolds.\n'));
       process.exit(1);
     }
@@ -185,11 +185,6 @@ export async function createCommand(featureName, options = {}) {
             // Re-materialize after the copy: the setup's earlier materialize ran with no features yet.
             const remat = await materializeState(worktreeResult.path);
             worktreeResult.materialized = remat.materialized;
-            try {
-              const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
-              // `worktree` was stripped from this copy above, so pass where it actually lives.
-              writeHandoff(featureName, worktreeResult.path, { worktree: { path: worktreeResult.path, branch: worktreeResult.branch } });
-            } catch { /* fail-open */ }
           } catch { /* fail-open — the feature already exists in root */ }
         }
       } else {