@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/lib/e2e/stack-teardown.js

@@ -1,27 +1,6 @@
-/**
- * Reclaim a feature's verification stack — containers, ports, named volumes
- * and the freshness stamp — from the tree that owns the feature.
- *
- * `morph-spec verify` leaves the stack UP on purpose (cold-starting a
- * container per task is what makes the loop unusable), so something has to be
- * the one place that brings it down when the feature closes. That place is
- * this module, shared by `finish` and `delete --with-worktree`.
- *
- * Three things the old root-side teardown got wrong, each pinned by a test:
- *   1. It ran from the ROOT. A compose that exists only in the worktree was
- *      never found, and a bind mount resolved to the wrong checkout.
- *   2. It passed a bare `COMPOSE_PROJECT_NAME`. Without the port block
- *      (`PORT`, `POSTGRES_PORT`, …) compose resolves a different config than
- *      the one that came up, and `down` misses the containers.
- *   3. It never removed volumes or the stamp. Postgres data and a stamp saying
- *      "source unchanged since build" outlived the feature.
- *
- * Entirely fail-open: no compose, no docker, or a stubborn container are all
- * non-events for the caller — a stack that refuses to come down must never
- * fail a finish that already merged.
- *
- * @module lib/e2e/stack-teardown
- */
+// `verify` leaves the stack up on purpose, so this is the one place that brings it down. Runs from the
+// owning tree with the full port block, or compose resolves a different config and `down` misses it.
+// Fail-open: a stack that refuses to come down must never fail a finish that already merged.
 
 import { execFileSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
@@ -36,15 +15,6 @@ import {
 } from '../../../framework/hooks/shared/e2e-check.js';
 import { buildComposeEnv } from './compose-env.js';
 
-/**
- * @param {string} feature
- * @param {object} params
- * @param {string} params.root - primary root (absolute)
- * @param {string|null} [params.worktreePath] - the feature's live worktree, if any
- * @param {boolean} [params.volumes=true] - also remove named volumes (`down -v`)
- * @param {Function} [params._exec] - injectable executor (testing)
- * @returns {{ attempted: boolean, cwd: string, status: 'pass'|'fail'|'skip', stampDeleted: boolean, output?: string }}
- */
 export function tearDownFeatureStack(feature, { root, worktreePath = null, volumes = true, _exec = defaultExec } = {}) {
   const cwd = worktreePath && existsSync(worktreePath) ? worktreePath : root;
   const projectName = composeProjectName(feature);
@@ -53,8 +23,7 @@ export function tearDownFeatureStack(feature, { root, worktreePath = null, volum
   try {
     const config = readConfig(cwd) ?? readConfig(root);
 
-    // The owning tree's compose first; the root's copy is the fallback for a
-    // worktree already half torn down (versioned file, so equivalent).
+    // The owning tree's compose first; the root's copy is the fallback for a worktree already half torn down.
     let composeCwd = cwd;
     let composeFile = resolveComposeFile(cwd, config);
     if (!composeFile && cwd !== root) {
@@ -63,8 +32,7 @@ export function tearDownFeatureStack(feature, { root, worktreePath = null, volum
     }
 
     if (!composeFile) {
-      // Nothing to bring down — but a stamp left behind would tell the next
-      // `up` that a stack it cannot see is still fresh.
+      // Nothing to bring down, but a stamp left behind would tell the next `up` a stack it cannot see is fresh.
       return { attempted: false, cwd, status: 'skip', stampDeleted: deleteStamp(gitCommonDir, projectName) };
     }
 
@@ -82,13 +50,11 @@ export function tearDownFeatureStack(feature, { root, worktreePath = null, volum
       ...(result.status === 'fail' && result.output ? { output: result.output } : {}),
     };
   } catch {
-    // Unconditional even when the teardown itself blew up: the stamp must not
-    // outlive the stack it described.
+    // The stamp must not outlive the stack it described, even when the teardown itself blew up.
     return { attempted: false, cwd, status: 'fail', stampDeleted: deleteStamp(gitCommonDir, projectName) };
   }
 }
 
-/** BOM-tolerant config read; null when absent or malformed. */
 function readConfig(dir) {
   try {
     const path = join(dir, '.morph', 'config', 'config.json');

package/src/lib/generators/architecture-scanner.js

@@ -1,19 +1,3 @@
-/**
- * Architecture Scanner - Generates rich architectural context from project filesystem.
- *
- * Performs fast (<5s) glob-based scanning to produce a snapshot of:
- * - .NET entities (sealed class/record)
- * - API endpoints (IApiEndpoint implementations)
- * - Next.js pages and components
- * - Integrations (from appsettings.json)
- * - Database schema (from EF migrations)
- * - Stack dependencies (.csproj + package.json)
- *
- * All scanning is regex-based (no AST parsing) for speed.
- *
- * @module architecture-scanner
- */
-
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -25,16 +9,6 @@ import { WORKTREE_DIR_NAMES } from '../worktree/dirs.js';
 export const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', '.git', '.morph', '.next', 'dist', 'out', ...WORKTREE_DIR_NAMES]);
 const MAX_FILES_PER_SCANNER = 200;
 
-/**
- * Recursively walk a directory, returning files matching a filter.
- * Skips known heavy directories for performance.
- *
- * @param {string} dir - Directory to walk
- * @param {function} filter - (relativePath) => boolean
- * @param {string} [base] - Base path for relative calculation
- * @param {number} [limit] - Max files to return
- * @returns {Promise<Array<{abs: string, rel: string}>>}
- */
 async function walkDir(dir, filter, base = dir, limit = MAX_FILES_PER_SCANNER) {
   const results = [];
 
@@ -68,12 +42,6 @@ async function walkDir(dir, filter, base = dir, limit = MAX_FILES_PER_SCANNER) {
   return results;
 }
 
-/**
- * Scan .NET entities from Entities/ or Features/ directories.
- *
- * @param {string} projectPath
- * @returns {Promise<Array<{name: string, type: string, path: string}>>}
- */
 export async function scanEntities(projectPath) {
   try {
     const files = await walkDir(
@@ -91,7 +59,6 @@ export async function scanEntities(projectPath) {
         entityRegex.lastIndex = 0;
         while ((match = entityRegex.exec(content)) !== null) {
           const line = content.slice(Math.max(0, match.index - 80), match.index + match[0].length);
-          // Only capture sealed/record types or classes in entity-like directories
           if (/sealed|record/.test(line) || file.rel.includes('Entities/')) {
             entities.push({
               name: match[2],
@@ -100,7 +67,7 @@ export async function scanEntities(projectPath) {
             });
           }
         }
-      } catch { /* skip unreadable files */ }
+      } catch {}
     }
 
     return entities;
@@ -109,12 +76,6 @@ export async function scanEntities(projectPath) {
   }
 }
 
-/**
- * Scan API endpoints implementing IApiEndpoint.
- *
- * @param {string} projectPath
- * @returns {Promise<Array<{name: string, route: string, method: string, path: string}>>}
- */
 export async function scanEndpoints(projectPath) {
   try {
     const files = await walkDir(
@@ -142,7 +103,7 @@ export async function scanEndpoints(projectPath) {
           method: methodMatch ? (methodMatch[1] || methodMatch[2] || '').toUpperCase() : '',
           path: file.rel
         });
-      } catch { /* skip */ }
+      } catch {}
     }
 
     return endpoints;
@@ -151,17 +112,10 @@ export async function scanEndpoints(projectPath) {
   }
 }
 
-/**
- * Scan Next.js pages and components.
- *
- * @param {string} projectPath
- * @returns {Promise<{pages: Array<{route: string, path: string}>, layouts: Array<{path: string}>, components: Array<{name: string, path: string}>}>}
- */
 export async function scanNextjsComponents(projectPath) {
   try {
     const result = { pages: [], layouts: [], components: [] };
 
-    // Scan pages and layouts from app directory
     const appFiles = await walkDir(
       projectPath,
       (rel, name) =>
@@ -181,7 +135,6 @@ export async function scanNextjsComponents(projectPath) {
       }
     }
 
-    // Scan components
     const componentFiles = await walkDir(
       projectPath,
       (rel, name) =>
@@ -191,7 +144,6 @@ export async function scanNextjsComponents(projectPath) {
 
     for (const file of componentFiles) {
       const name = path.basename(file.rel, path.extname(file.rel));
-      // Skip index files and test files
       if (name === 'index' || name.includes('.test') || name.includes('.spec')) continue;
       result.components.push({ name, path: file.rel });
     }
@@ -202,12 +154,6 @@ export async function scanNextjsComponents(projectPath) {
   }
 }
 
-/**
- * Scan integrations from appsettings*.json files.
- *
- * @param {string} projectPath
- * @returns {Promise<Array<{name: string, type: string, configured: boolean}>>}
- */
 export async function scanIntegrations(projectPath) {
   try {
     const files = await walkDir(
@@ -217,7 +163,6 @@ export async function scanIntegrations(projectPath) {
       20
     );
 
-    // Also check .env files for common integrations
     const envFiles = await walkDir(
       projectPath,
       (rel, name) => name === '.env' || name === '.env.local' || name === '.env.production',
@@ -242,7 +187,6 @@ export async function scanIntegrations(projectPath) {
 
     const detected = new Map();
 
-    // Scan appsettings files
     for (const file of files) {
       try {
         const content = JSON.parse(await fs.readFile(file.abs, 'utf8'));
@@ -256,7 +200,6 @@ export async function scanIntegrations(projectPath) {
             }
           }
         }
-        // Check ConnectionStrings specifically
         if (content.ConnectionStrings) {
           for (const [key, val] of Object.entries(content.ConnectionStrings)) {
             if (val && !String(val).startsWith('{{')) {
@@ -264,10 +207,9 @@ export async function scanIntegrations(projectPath) {
             }
           }
         }
-      } catch { /* skip invalid JSON */ }
+      } catch {}
     }
 
-    // Scan .env files for known prefixes
     const envPrefixes = {
       'NEON_AUTH_': 'NeonAuth',
       'DATABASE_URL': 'Neon',
@@ -289,7 +231,7 @@ export async function scanIntegrations(projectPath) {
             }
           }
         }
-      } catch { /* skip */ }
+      } catch {}
     }
 
     return Array.from(detected.values());
@@ -298,12 +240,6 @@ export async function scanIntegrations(projectPath) {
   }
 }
 
-/**
- * Scan database schema from EF Core migrations.
- *
- * @param {string} projectPath
- * @returns {Promise<Array<{table: string, migration: string}>>}
- */
 export async function scanDatabaseSchema(projectPath) {
   try {
     const files = await walkDir(
@@ -331,10 +267,9 @@ export async function scanDatabaseSchema(projectPath) {
             }
           }
         }
-      } catch { /* skip */ }
+      } catch {}
     }
 
-    // Also scan database migrations (SQL)
     const sqlFiles = await walkDir(
       projectPath,
       (rel, name) => name.endsWith('.sql') && rel.includes('migrations/'),
@@ -355,7 +290,7 @@ export async function scanDatabaseSchema(projectPath) {
             tables.set(match[1], { table: match[1], migration: migrationName });
           }
         }
-      } catch { /* skip */ }
+      } catch {}
     }
 
     return Array.from(tables.values());
@@ -364,17 +299,10 @@ export async function scanDatabaseSchema(projectPath) {
   }
 }
 
-/**
- * Detect stack from .csproj PackageReference and package.json dependencies.
- *
- * @param {string} projectPath
- * @returns {Promise<{dotnet: Array<{name: string, version: string}>, npm: Array<{name: string, version: string}>}>}
- */
 export async function scanStackDependencies(projectPath) {
   try {
     const result = { dotnet: [], npm: [] };
 
-    // Scan .csproj files
     const csprojFiles = await walkDir(
       projectPath,
       (rel, name) => name.endsWith('.csproj'),
@@ -392,10 +320,9 @@ export async function scanStackDependencies(projectPath) {
         while ((match = packageRefRegex.exec(content)) !== null) {
           result.dotnet.push({ name: match[1], version: match[2] });
         }
-      } catch { /* skip */ }
+      } catch {}
     }
 
-    // Scan package.json (root only)
     const pkgPath = path.join(projectPath, 'package.json');
     if (existsSync(pkgPath)) {
       try {
@@ -404,10 +331,9 @@ export async function scanStackDependencies(projectPath) {
         for (const [name, version] of Object.entries(allDeps)) {
           result.npm.push({ name, version: String(version) });
         }
-      } catch { /* skip */ }
+      } catch {}
     }
 
-    // Also check web/ or frontend/ subdirectory package.json
     for (const subdir of ['web', 'frontend', 'client', 'src']) {
       const subPkgPath = path.join(projectPath, subdir, 'package.json');
       if (existsSync(subPkgPath)) {
@@ -415,12 +341,11 @@ export async function scanStackDependencies(projectPath) {
           const pkg = JSON.parse(await fs.readFile(subPkgPath, 'utf8'));
           const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
           for (const [name, version] of Object.entries(allDeps)) {
-            // Avoid duplicates
             if (!result.npm.some(d => d.name === name)) {
               result.npm.push({ name, version: String(version) });
             }
           }
-        } catch { /* skip */ }
+        } catch {}
       }
     }
 
@@ -430,12 +355,6 @@ export async function scanStackDependencies(projectPath) {
   }
 }
 
-/**
- * Master scan — runs all scanners in parallel.
- *
- * @param {string} projectPath
- * @returns {Promise<Object>} ArchitectureScanResult
- */
 export async function scanArchitecture(projectPath) {
   const [entities, endpoints, nextjs, integrations, database, stack, graph] = await Promise.all([
     scanEntities(projectPath),
@@ -444,9 +363,7 @@ export async function scanArchitecture(projectPath) {
     scanIntegrations(projectPath),
     scanDatabaseSchema(projectPath),
     scanStackDependencies(projectPath),
-    // Aditivo: sem grafo devolve listas vazias e nada muda no README. O
-    // inventário acima continua sendo a espinha do arquivo — ele tem
-    // exaustividade que o grafo não tem.
+    // Aditivo: sem grafo devolve listas vazias; o inventário acima tem a exaustividade que o grafo não tem.
     scanGraph(projectPath)
   ]);
 
@@ -462,20 +379,11 @@ export async function scanArchitecture(projectPath) {
   };
 }
 
-/**
- * Resolve a template path: check .morph/framework/templates/ first, then framework/templates/,
- * then fall back to the CLI package's own framework/templates/.
- *
- * @param {string} projectPath
- * @param {string} templateRelPath
- * @returns {string|null}
- */
+// Project-local `.morph/framework/templates/` override first, then the CLI package's own.
 function resolveTemplatePath(projectPath, templateRelPath) {
-  // 1. Project-local override
   const projectLocal = path.join(projectPath, '.morph/framework/templates', templateRelPath);
   if (existsSync(projectLocal)) return projectLocal;
 
-  // 2. CLI package framework/ (for running from source or during init)
   const cliFramework = path.join(
     cliRootDir(), 'framework', 'templates', templateRelPath
   );
@@ -484,103 +392,64 @@ function resolveTemplatePath(projectPath, templateRelPath) {
   return null;
 }
 
-/**
- * The CLI package root, as a real filesystem path.
- *
- * fileURLToPath, not `new URL(...).pathname`: the latter leaves the path
- * percent-encoded, so an install under a directory with a space resolved to
- * ".../Program%20Files/..." — a path that never exists. `resolveTemplatePath`
- * then returned null and the caller fell through to its plain-text fallback
- * WITHOUT any warning. The first lines of that fallback are identical to the
- * template's, which is why nobody noticed the tables were gone. On Windows a
- * global npm install lives under a spaced path by default, so this was the
- * common case, not the edge one.
- */
+// fileURLToPath, not `new URL(...).pathname`: the latter stays percent-encoded, so a path with a space
+// (the default global npm install on Windows) never resolves and the template is silently dropped.
 function cliRootDir() {
   return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 }
 
-/**
- * Render architecture context to .morph/context/README.md
- *
- * QUEM LÊ ESTE ARQUIVO, E QUANDO: o passo 1c da skill `morph-plan` (mapa de
- * reuso), antes de decidir REUSAR/ESTENDER/CRIAR cada conceito da feature. É a
- * granularidade de CONCEITO — entidades, endpoints com rota, componentes com
- * path — que o grafo de codebase, que casa por símbolo, não dá; e é o único
- * inventário legível num projeto sem grafo (sem Python), antes do grep.
- *
- * Até 2026-08-27 este arquivo era gerado e NUNCA lido por skill nenhuma
- * (docs/specs/code-reuse-gap/analysis.md §2.5). Se um dia o consumidor acima
- * desaparecer do `morph-plan`, este gerador volta a queimar tempo por nada —
- * a decisão então é remover os dois, não deixar o arquivo órfão de novo.
- *
- * @param {string} projectPath
- * @param {Object} scanResult - Result from scanArchitecture()
- * @param {Object} [options]
- * @param {string} [options.projectName] - Override project name
- * @returns {Promise<string>} Path to written file
- */
+// Read by `morph-plan` for the concept-level inventory the graph doesn't give. If that reader goes away,
+// remove this generator too.
 export async function renderArchitectureContext(projectPath, scanResult, options = {}) {
   const templatePath = resolveTemplatePath(projectPath, 'context/ARCHITECTURE.md');
 
-  // Determine project name
   let projectName = options.projectName;
   if (!projectName) {
-    // Try config.json
     const configPath = path.join(projectPath, '.morph/config/config.json');
     if (existsSync(configPath)) {
       try {
         const config = JSON.parse(readFileSync(configPath, 'utf8'));
         projectName = config.project?.name;
-      } catch { /* ignore */ }
+      } catch {}
     }
-    // Fallback to directory name
     if (!projectName) {
       projectName = path.basename(projectPath);
     }
   }
 
-  // Get morph-spec version
   let morphVersion = 'unknown';
   try {
     const pkgPath = path.join(cliRootDir(), 'package.json');
     if (existsSync(pkgPath)) {
       morphVersion = JSON.parse(readFileSync(pkgPath, 'utf8')).version;
     }
-  } catch { /* ignore */ }
+  } catch {}
 
   const variables = {
     projectName,
     timestamp: new Date().toISOString().replace('T', ' ').split('.')[0],
     morphVersion,
-    // Entities
     hasDotnet: scanResult.entities.length > 0 || scanResult.endpoints.length > 0,
     entities: scanResult.entities,
     entityCount: scanResult.entities.length,
     endpoints: scanResult.endpoints,
     endpointCount: scanResult.endpoints.length,
-    // Next.js
     hasNextjs: scanResult.nextjs.pages.length > 0 || scanResult.nextjs.components.length > 0,
     pages: scanResult.nextjs.pages,
     pageCount: scanResult.nextjs.pages.length,
     layouts: scanResult.nextjs.layouts,
     components: scanResult.nextjs.components,
     componentCount: scanResult.nextjs.components.length,
-    // Integrations
     hasIntegrations: scanResult.integrations.length > 0,
     integrations: scanResult.integrations,
-    // Database
     hasTables: scanResult.database.length > 0,
     tables: scanResult.database,
     tableCount: scanResult.database.length,
-    // Stack
     hasDotnetPackages: scanResult.stack.dotnet.length > 0,
     dotnetPackages: scanResult.stack.dotnet,
     hasNpmPackages: scanResult.stack.npm.length > 0,
     npmPackages: scanResult.stack.npm,
-    // Centralidade (grafo de codebase) — ACRESCENTA, nunca substitui.
-    // Comunidade ainda com rótulo Community_N fica de fora: sem
-    // `graphify label` ela é ruído puro (441 páginas assim no eval).
+    // Comunidade ainda rotulada Community_N fica de fora: sem `graphify label` é ruído puro.
     hasGraph: scanResult.graph?.available === true && (scanResult.graph.godNodes?.length ?? 0) > 0,
     godNodes: scanResult.graph?.godNodes ?? [],
     communities: (scanResult.graph?.communities ?? []).filter((c) => c.labeled),
@@ -591,11 +460,9 @@ export async function renderArchitectureContext(projectPath, scanResult, options
   if (templatePath) {
     content = renderTemplate(templatePath, variables);
   } else {
-    // Fallback: generate minimal markdown without template
     content = generateFallbackMarkdown(variables);
   }
 
-  // Write to .morph/context/README.md
   const contextDir = path.join(projectPath, '.morph/context');
   await fs.mkdir(contextDir, { recursive: true });
   const outputPath = path.join(contextDir, 'README.md');
@@ -604,11 +471,6 @@ export async function renderArchitectureContext(projectPath, scanResult, options
   return outputPath;
 }
 
-/**
- * Generate minimal markdown when template is not available.
- * @param {Object} vars
- * @returns {string}
- */
 function generateFallbackMarkdown(vars) {
   const lines = [`# ${vars.projectName} — Architecture Context\n`];
   lines.push(`> Auto-generated by morph-spec context refresh`);

package/src/lib/generators/handoff-generator.js

@@ -1,20 +1,5 @@
-/**
- * handoff-generator.js — compressed session-handoff document (fleet).
- *
- * A fleet runs one Claude Code instance per feature worktree. What travels
- * between sessions must be a HANDOFF, not an export: a compact document that
- * points at the feature's own files instead of copying their contents, so a
- * fresh instance starts focused instead of inheriting a wall of stale context.
- *
- * Deterministic by construction — everything here is derived from feature.json,
- * the extracted plan checks, the slice reports and the worktree env manifest. The document is
- * therefore REGENERABLE (never hand-edited, never merged): `morph-spec handoff`
- * rebuilds it, and setup/create/advance/approve regenerate it at the moments a
- * new session is most likely to pick the feature up.
- *
- * Every section is fail-open: missing or corrupt plan checks degrade that
- * section, never the document.
- */
+// Derived only from committed sources, so it is regenerated, never hand-edited or merged.
+// Every section is fail-open.
 
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
@@ -22,7 +7,6 @@ import { ensureCommonExclude } from '../../../framework/hooks/shared/git-exclude
 import { derivePhaseForFeature, getPendingGates } from '../../../framework/hooks/shared/state-reader.js';
 import { sliceProgress, readySlices } from '../../../framework/hooks/shared/slice-progress.js';
 
-/** Ordered pointer candidates — only existing paths make it into the doc. */
 const POINTER_CANDIDATES = [
   ['2-plan/plan.md', 'plano: problema, cenários com prova, decisões e fatias'],
   ['2-plan/checks.json', 'cenários e fatias extraídos pelo plan-check'],
@@ -68,7 +52,7 @@ function nextAction(feature, phase, slices, featureName) {
 
   switch (phase) {
     case 'plan':
-      return `Escreva \`2-plan/plan.md\`, rode \`morph-spec plan-check ${featureName}\` até zero erro e aprove o gate do plano (\`morph-spec advance ${featureName}\`). Skill: /morph-proposal ${featureName}.`;
+      return `Escreva \`2-plan/plan.md\`, rode \`morph-spec plan-check ${featureName}\` até zero erro e aprove o gate do plano (\`morph-spec advance ${featureName}\`). Skill: /morph-plan ${featureName}.`;
     case 'uiux':
       return approved('uiux')
         ? `Gate de uiux aprovado — implemente as fatias do plano via /morph-apply ${featureName}.`
@@ -88,20 +72,8 @@ function nextAction(feature, phase, slices, featureName) {
   }
 }
 
-/**
- * Build the handoff document for a feature, resolved against `cwd` (primary
- * root or worktree — wherever the feature's `.morph/features/{f}` lives).
- *
- * @param {string} featureName
- * @param {string} [cwd]
- * @param {{ worktree?: {path:string, branch:string}|null }} [opts] - override
- *   the `worktree` bookkeeping instead of reading `feature.worktree`. Needed
- *   because that field is ROOT-OWNED and stripped from every branch-local
- *   copy at birth (create.js) — a handoff built FROM the worktree's own copy
- *   would otherwise always say "no worktree registered", even while sitting
- *   inside one. Pass `undefined` (the default) to fall back to `feature.worktree`.
- * @returns {{ markdown: string, meta: { generatedAt: string, phase: string, slicesDone: number, slicesTotal: number } } | null}
- */
+// `opts.worktree` overrides `feature.worktree`: that field is root-owned and stripped from branch-local
+// copies, so a handoff built inside a worktree would otherwise say "no worktree registered".
 export function buildHandoff(featureName, cwd = process.cwd(), opts = {}) {
   const featureDir = join(cwd, '.morph', 'features', featureName);
   if (!existsSync(join(featureDir, 'feature.json'))) return null;
@@ -118,7 +90,7 @@ export function buildHandoff(featureName, cwd = process.cwd(), opts = {}) {
   try {
     phase = derivePhaseForFeature(featureName, cwd) || 'plan';
     pendingGates = getPendingGates(featureName, cwd) || [];
-  } catch { /* fail-open — plan defaults keep the doc useful */ }
+  } catch {}
 
   const generatedAt = new Date().toISOString();
   const slices = sliceProgress(featureDir);
@@ -193,29 +165,13 @@ export function buildHandoff(featureName, cwd = process.cwd(), opts = {}) {
 const HANDOFF_EXCLUDE_MARKER = '# morph-spec: derived handoff docs (managed — see handoff-generator)';
 const HANDOFF_EXCLUDE_PATTERN = '/.morph/**/handoff.md';
 
-/**
- * The handoff is DERIVED from committed sources, so it is never committed
- * itself — regenerate > synchronize, the same principle as the materialized
- * state.json. Left visible, every `worktree setup`/`advance` would drop an
- * untracked file into the very `git status` the finish gates read. The
- * common-dir `.git/info/exclude` hides it in every worktree of the repo
- * (including the primary root); `**` also covers a feature folder after
- * `archive` moves it. Idempotent and fail-open — a handoff that shows up as
- * untracked is noise, never data loss.
- */
+// Never committed: left visible it lands in the `git status` the finish gates read. The common-dir
+// exclude hides it in every worktree; `**` also covers a feature folder after `archive` moves it.
 function ensureHandoffExcluded(cwd) {
   ensureCommonExclude(cwd, [HANDOFF_EXCLUDE_PATTERN], HANDOFF_EXCLUDE_MARKER);
 }
 
-/**
- * Write `.morph/features/{f}/handoff.md`. Returns the written path, or null
- * when the feature does not exist (nothing is created).
- *
- * @param {string} featureName
- * @param {string} [cwd]
- * @param {{ worktree?: {path:string, branch:string}|null }} [opts] - see buildHandoff
- * @returns {string|null}
- */
+/** The written path, or null when the feature does not exist (nothing is created). */
 export function writeHandoff(featureName, cwd = process.cwd(), opts = {}) {
   const result = buildHandoff(featureName, cwd, opts);
   if (!result) return null;