@polymorphism-tech/morph-spec 9.8.0 → 10.0.0

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

@@ -34,7 +34,7 @@ export function autoApprovalRefusal({ cwd, featureName, feature, gate, approvedB
     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

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

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

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { getFeature } from '../../core/state/state-manager.js';
-import { shouldPauseGate, getRiskSignals, classifyE2eSkip, planChecksPause, securityReviewFor } from '../../lib/risk-detector.js';
+import { shouldPauseGate, getRiskSignals, classifyE2eSkip, planChecksPause, securityReviewFor, pausingRungs, migrationsTouched, contractsTouched, humanApprover, rungPause, planCritiquePause } from '../../lib/risk-detector.js';
+import { readPlanCritique } from '../../lib/plan/critique.js';
 import { reviewReports, reviewSignal, requiredReviewRoles, verifierMediaSection } from '../../lib/review-reports.js';
 import { collectScreenChecklist } from '../../lib/specs/screen-checklist.js';
 import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-decision.js';
@@ -9,33 +10,22 @@ import { detectDefaultBranch, getHeadSha, getDiffStat, changedPathsAgainst } fro
 import { treeMovedSince } from '../../lib/git/evidence-staleness.js';
 import { readMorphConfig } from '../../lib/tasks/test-runner.js';
 import { readPlanChecks } from '../../lib/plan/checks.js';
+import { featureGeneratesMedia } from '../../lib/plan/media.js';
+import { readFileSync, existsSync } from 'fs';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
+export { featureGeneratesMedia, MEDIA_STANDARD_IDS, standardIdOf } from '../../lib/plan/media.js';
+
 // Only signals NOT derivable from disk may be overridden: overriding a disk fact (e.g. `workType`
 // away from hotfix) would silently defeat the policy this command makes deterministic.
 const OVERRIDABLE_SIGNAL_KEYS = ['standardsViolations', 'designSystemDivergence'];
 
-export const MEDIA_STANDARD_IDS = [
-  'ai-agents-modalities-image-gen',
-  'ai-agents-media-video',
-  'ai-agents-media-pipeline',
-];
-
-// O plano escreve o standard pelo id ou pelo caminho (com ou sem `framework/`/`standards/`).
-export function standardIdOf(value) {
-  return String(value ?? '').trim().replace(/\\/g, '/')
-    .replace(/^(\.morph\/)?(framework\/)?(standards\/)?/, '')
-    .replace(/\.md$/, '')
-    .replace(/\//g, '-');
+function readPlanText(cwd, featureName) {
+  const path = getAbsoluteOutputPath(cwd, featureName, 'plan');
+  try { return existsSync(path) ? readFileSync(path, 'utf8') : ''; } catch { return ''; }
 }
 
-// Decide se um guardrail arma: um predicado que sempre devolve `false` desarma em silêncio a
-// pausa de mídia da review e a rota opus.
-export function featureGeneratesMedia(slices) {
-  if (!Array.isArray(slices)) return false;
-  return slices.some((s) => Array.isArray(s?.standards)
-    && s.standards.some((id) => MEDIA_STANDARD_IDS.includes(standardIdOf(id))));
-}
 
 // `declared: false` (nenhum caminho declarado: regra inerte) e `touched: []` (declarou, nada
 // tocado) não podem colapsar num array vazio. COLETA, NUNCA DECIDE: política no coletor cria
@@ -70,7 +60,11 @@ export function collectReviewSignal(cwd, featureName, feature, planChecks = read
 
 /** Why an automatic signature may not close the plan gate: the rule that makes gate-check pause it. */
 export function planAutoApprovalBlock(cwd, featureName) {
-  const reason = planChecksPause(readPlanChecks(cwd, featureName).status);
+  const planChecks = readPlanChecks(cwd, featureName);
+  const workType = getFeature(featureName)?.workType || 'feature';
+  const reason = planChecksPause(planChecks.status)
+    ?? planCritiquePause(readPlanCritique(cwd, featureName, { workType, planChecks }))
+    ?? rungPause({ gate: 'plan', rungs: pausingRungs(planChecks.checks) })?.reason;
   return reason ? reason.replace('{feature}', featureName) : null;
 }
 
@@ -79,7 +73,6 @@ export function planAutoApprovalBlock(cwd, featureName) {
 // waiver from missing proof.
 export function collectSignals(featureName, feature, cwd, gateName) {
   const planChecks = readPlanChecks(cwd, featureName);
-  const slices = planChecks.checks?.slices ?? null;
   const defaultBranch = detectDefaultBranch(cwd);
   const sha = getHeadSha(cwd);
   const verification = feature.verification || null;
@@ -88,12 +81,15 @@ export function collectSignals(featureName, feature, cwd, gateName) {
     // Disk-derived, never overridable: a caller cannot spoof which gate is being decided.
     gate: gateName,
     workType: feature.workType || 'feature',
-    sliceCount: slices ? slices.length : null,
     standardsViolations: [],
     designSystemDivergence: false,
   };
 
-  if (gateName === 'plan') signals.planChecks = planChecks.status;
+  if (gateName === 'plan') {
+    signals.planChecks = planChecks.status;
+    signals.planCritique = readPlanCritique(cwd, featureName, { workType: signals.workType, planChecks });
+  }
+  if (gateName === 'plan' || gateName === 'review') signals.rungs = pausingRungs(planChecks.checks);
 
   // Só onde o checklist decide algo: no fecho do design e no ship.
   if (gateName === 'uiux' || gateName === 'review') {
@@ -104,13 +100,20 @@ export function collectSignals(featureName, feature, cwd, gateName) {
     signals.reviewReports = collectReviewSignal(cwd, featureName, feature, planChecks);
     signals.mediaClaims = {
       section: verifierMediaSection(cwd, featureName),
-      featureGeneratesMedia: featureGeneratesMedia(slices),
+      featureGeneratesMedia: featureGeneratesMedia(readPlanText(cwd, featureName)),
     };
+    let changed = [];
+    try { changed = changedPathsAgainst(defaultBranch, cwd); } catch { changed = []; }
+    signals.migrationsTouched = migrationsTouched(changed);
+    signals.contractsTouched = contractsTouched(changed);
+    signals.planApprovedByHuman = feature.approvalGates?.plan?.approved === true
+      && humanApprover(feature.approvalGates.plan.approvedBy);
   }
 
   // verificationStale é fail-open: stamp sem sha (checkout sem git) ou ausente lê como NOT stale.
   signals.verification = verification;
   if (verification?.status) signals.verificationStatus = verification.status;
+  signals.failStreak = feature.verifications?.feature?.failStreak ?? 0;
   signals.verificationStale = treeMovedSince(cwd, verification?.sha, sha);
 
   // Separado do rollup: um `skip` NÃO reprova `verification.status`. `null` é DESCONHECIDO, nunca
@@ -189,10 +192,12 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
     const computed = shouldPauseGate({ trust }, signals);
     const manual = feature.gateDecisions?.[gateName];
     const manualPause = manual?.source === 'manual' && manual.pause === true;
-    const { pause, reason, signal } = manualPause ? { pause: true, reason: manual.reason, signal: 'manual' } : computed;
+    const { pause, reason, signal, resolver } = manualPause
+      ? { pause: true, reason: manual.reason, signal: 'manual', resolver: 'human' }
+      : computed;
 
     const entry = await persistGateDecision(featureName, gateName, {
-      pause, reason, signal, signals, trust, cwd, source: manualPause ? 'manual' : 'gate-check',
+      pause, reason, signal, resolver, signals, trust, cwd, source: manualPause ? 'manual' : 'gate-check',
     });
 
     if (options.json) {
@@ -201,9 +206,11 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
     }
 
     const allSignals = getRiskSignals(signals);
-    console.log(entry.pause
-      ? chalk.yellow(`\n⏸️  Gate "${gateName}" — PAUSE (${featureName})`)
-      : chalk.green(`\n▶️  Gate "${gateName}" — auto-pass (${featureName})`));
+    console.log(!entry.pause
+      ? chalk.green(`\n▶️  Gate "${gateName}" — auto-pass (${featureName})`)
+      : entry.resolver === 'session'
+        ? chalk.yellow(`\n🔧 Gate "${gateName}" — PAUSE, resolver: session (${featureName}): do what the reason says and run gate-check again`)
+        : chalk.yellow(`\n⏸️  Gate "${gateName}" — PAUSE, resolver: human (${featureName})`));
     console.log(chalk.gray(`   reason: ${entry.reason} | trust: ${entry.trust} | decidedAt: ${entry.decidedAt}`));
     if (manualPause) {
       console.log(chalk.gray(`   pausa manual mantida (sinais calculados: ${computed.reason}); só \`morph-spec gate-decision ${featureName} ${gateName} --pause false\` a libera`));

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

@@ -32,9 +32,10 @@ export function readTrustFromConfig() {
  * The ONE write path of `gateDecisions.{gate}`, shared by `gate-decision` and `gate-check`.
  * Does not validate `gateName`. A uiux decision records the `mockupsHash` it saw.
  */
-export async function persistGateDecision(featureName, gateName, { pause, reason, signal, signals = {}, trust, cwd = process.cwd(), source } = {}) {
+export async function persistGateDecision(featureName, gateName, { pause, reason, signal, resolver, signals = {}, trust, cwd = process.cwd(), source } = {}) {
   const entry = {
     pause,
+    resolver: pause ? resolver ?? 'human' : null,
     reason: reason || (pause ? 'risco detectado' : 'nenhum sinal de risco'),
     signals,
     trust: trust || readTrustFromConfig(),
@@ -44,7 +45,7 @@ export async function persistGateDecision(featureName, gateName, { pause, reason
   };
 
   await updateFeature(featureName, `gateDecisions.${gateName}`, entry);
-  recordGateEvent(cwd, { feature: featureName, gate: gateName, step: 'decision', pause, signal, source });
+  recordGateEvent(cwd, { feature: featureName, gate: gateName, step: 'decision', pause, signal, source, resolver: entry.resolver });
   return entry;
 }
 

package/src/commands/state/next.js

@@ -20,5 +20,6 @@ export function nextCommand(featureName, options = {}) {
     return;
   }
   console.log(formatNext(next));
+  for (const line of next.how ?? []) console.log(`   ${line}`);
   if (owner.tree !== process.cwd()) console.log(chalk.gray(`   árvore dona: ${owner.tree}`));
 }

package/src/commands/state/recap.js

@@ -0,0 +1,67 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { buildRecap, changeSummary, recapScenes, renderRecapHtml } from '../../lib/recap/recap.js';
+import { narrateWithPiper, resolvePiper } from '../../lib/recap/piper.js';
+
+export const RECAP_FILES = { html: 'recap.html', data: 'recap.json' };
+
+/** Writes `recap.html` + `recap.json` into `targetDir` from the live feature folder. Never throws. */
+export function writeRecap(featureDir, targetDir, feature, { cwd }) {
+  try {
+    const data = buildRecap(featureDir, feature, { changes: changeSummary(cwd) });
+    writeFileSync(join(targetDir, RECAP_FILES.data), JSON.stringify(data, null, 2));
+    writeFileSync(join(targetDir, RECAP_FILES.html), renderRecapHtml(data));
+    return { ok: true, path: join(targetDir, RECAP_FILES.html) };
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+}
+
+// Active feature: rebuilt from its folder and the branch diff. Archived: the data the finish froze,
+// since the archive keeps neither the reports nor the branch.
+export function recapCommand(feature, options = {}) {
+  const cwd = options.path || process.cwd();
+  const active = join(cwd, '.morph', 'features', feature);
+  const archived = join(cwd, '.morph', 'archive', feature);
+  let data;
+  let dir;
+  if (existsSync(active)) {
+    dir = active;
+    data = buildRecap(active, feature, { changes: changeSummary(cwd) });
+    writeFileSync(join(dir, RECAP_FILES.data), JSON.stringify(data, null, 2));
+  } else if (existsSync(join(archived, RECAP_FILES.data))) {
+    dir = archived;
+    data = JSON.parse(readFileSync(join(archived, RECAP_FILES.data), 'utf8'));
+  } else {
+    const payload = { ok: false, reason: existsSync(archived) ? 'archived-without-recap' : 'feature-not-found' };
+    if (options.json) console.log(JSON.stringify(payload));
+    else console.error(chalk.yellow(`\n○ ${payload.reason === 'feature-not-found' ? `Feature "${feature}" não existe.` : `"${feature}" foi arquivada antes do recap existir.`}\n`));
+    process.exit(1);
+  }
+
+  let narration = 'sistema';
+  let path = join(dir, RECAP_FILES.html);
+  let note = null;
+  if (options.piper) {
+    const piper = resolvePiper();
+    const audio = piper.ok ? narrateWithPiper(recapScenes(data), piper) : null;
+    if (audio) {
+      // Audio is megabytes: it goes to a temp file, never into the committed archive.
+      path = join(tmpdir(), `morph-recap-${feature}.html`);
+      writeFileSync(path, renderRecapHtml(data, { audio }));
+      narration = 'piper';
+    } else {
+      note = piper.ok ? 'o piper falhou numa cena — ficou a voz do sistema' : piper.reason;
+    }
+  }
+  if (narration === 'sistema') writeFileSync(path, renderRecapHtml(data));
+
+  if (options.json) {
+    console.log(JSON.stringify({ ok: true, path, narration, note }));
+    return;
+  }
+  console.log(chalk.green(`\n✅ Recap de ${feature}: ${path}`));
+  console.log(chalk.gray(`   narração: ${narration === 'piper' ? 'Piper (áudio embutido)' : 'voz do sistema, pelo navegador'}${note ? ` — ${note}` : ''}\n`));
+}