@polymorphism-tech/morph-spec 8.1.2 → 8.2.0

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

@@ -0,0 +1,267 @@
+/**
+ * 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,
+ * tasks.json, decisions.md and the worktree env manifest. The document is
+ * therefore REGENERABLE (never hand-edited, never merged): `morph-spec handoff`
+ * rebuilds it, and setup/create/advance regenerate it at the moments a new
+ * session is most likely to pick the feature up.
+ *
+ * Every section is fail-open: a missing tasks.json or a corrupt decisions.md
+ * degrades that section, never the document.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { execSync } from 'child_process';
+import { derivePhaseForFeature, getPendingGates } from '../../../framework/hooks/shared/state-reader.js';
+
+const PHASE_DIRS = {
+  proposal: '0-proposal',
+  uiux: '1-design',
+  plan: '2-plan',
+  implement: '3-implement',
+  review: '4-review',
+};
+
+/** Ordered pointer candidates — only existing files make it into the doc. */
+const POINTER_CANDIDATES = [
+  ['0-proposal/proposal.md', 'proposta e critérios de aceite'],
+  ['2-plan/spec.md', 'especificação técnica'],
+  ['2-plan/mandate.md', 'contrato de implementação (leia antes de cada task)'],
+  ['2-plan/tasks.json', 'DAG de tasks (status vivo)'],
+  ['decisions.md', 'decisões registradas'],
+  ['3-implement/recap.md', 'recap da implementação'],
+  ['4-review/review-report.md', 'relatório do Gate 3'],
+];
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+}
+
+function taskSummary(featureDir) {
+  try {
+    const tasksPath = join(featureDir, '2-plan', 'tasks.json');
+    if (!existsSync(tasksPath)) return null;
+    const data = readJson(tasksPath);
+    if (!Array.isArray(data.tasks)) return null;
+    const done = data.tasks.filter((t) => t.status === 'done').length;
+    const doneIds = new Set(data.tasks.filter((t) => t.status === 'done').map((t) => t.id));
+    const ready = data.tasks.filter(
+      (t) => t.status === 'pending' && Array.isArray(t.dependencies) && t.dependencies.every((d) => doneIds.has(d)),
+    );
+    return { done, total: data.tasks.length, ready };
+  } catch {
+    return null;
+  }
+}
+
+function decisionTitles(featureDir, limit = 5) {
+  try {
+    const path = join(featureDir, 'decisions.md');
+    if (!existsSync(path)) return [];
+    const titles = [...readFileSync(path, 'utf8').matchAll(/^##\s+(.+)$/gm)].map((m) => m[1].trim());
+    return titles.slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+function readWorktreeEnv(cwd) {
+  try {
+    const path = join(cwd, '.morph', 'worktree.env');
+    if (!existsSync(path)) return null;
+    const content = readFileSync(path, 'utf8');
+    const get = (key) => content.match(new RegExp(`^${key}=(.+)$`, 'm'))?.[1] || null;
+    const port = get('PORT');
+    return port ? { port, range: get('MORPH_PORT_RANGE') } : null;
+  } catch {
+    return null;
+  }
+}
+
+function nextAction(feature, phase, tasks, featureName) {
+  const gates = feature.approvals || feature.approvalGates || {};
+  const approved = (g) => gates[g]?.approved === true;
+
+  switch (phase) {
+    case 'proposal':
+      // An approved Gate 1 with no plan artifact yet means "plan work is open":
+      // the derived phase only flips when 2-plan/spec.md lands (derivePhase is
+      // artifact-first). Pointing back at the proposal here would be wrong.
+      return approved('proposal')
+        ? `Gate 1 aprovado — produza \`2-plan/spec.md\` + \`mandate.md\` + \`tasks.json\` (a fase avança com o primeiro artefato; Gate 2 em seguida).`
+        : `Complete \`0-proposal/proposal.md\` e aprove o Gate 1 (\`morph-spec advance ${featureName}\`). Skill: /morph-proposal ${featureName}.`;
+    case 'uiux':
+      return approved('uiux')
+        ? `Gate de uiux aprovado — produza \`2-plan/spec.md\` + \`mandate.md\` + \`tasks.json\` (Gate 2 em seguida).`
+        : `Complete \`1-design/design-system.md\` e aprove o gate de uiux (\`morph-spec advance ${featureName}\`).`;
+    case 'plan':
+      return `Produza \`2-plan/spec.md\` + \`mandate.md\` + \`tasks.json\` e aprove o Gate 2 (\`morph-spec advance ${featureName}\`).`;
+    case 'implement': {
+      const ready = tasks?.ready?.map((t) => `${t.id} "${t.title}"`).join(', ');
+      return ready
+        ? `Execute as tasks ready — ${ready} — via /morph-apply ${featureName} (verify antes do juiz, barra 9).`
+        : `Todas as tasks concluídas ou bloqueadas — rode \`morph-spec advance ${featureName}\` para escancarar a review, ou destrave dependências. Skill: /morph-apply ${featureName}.`;
+    }
+    case 'review':
+      return approved('review')
+        ? `Gate 3 aprovado — feche: \`morph-spec worktree finish ${featureName}\` e depois \`morph-spec archive ${featureName}\` na raiz.`
+        : `Produza \`4-review/review-report.md\` (avaliador independente) e aprove o Gate 3; depois \`worktree finish\` + \`archive\`.`;
+    default:
+      return `Rode \`morph-spec status ${featureName}\` para orientar o próximo passo.`;
+  }
+}
+
+/**
+ * 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]
+ * @returns {{ markdown: string, meta: { generatedAt: string, phase: string, tasksDone: number, tasksTotal: number } } | null}
+ */
+export function buildHandoff(featureName, cwd = process.cwd()) {
+  const featureDir = join(cwd, '.morph', 'features', featureName);
+  if (!existsSync(join(featureDir, 'feature.json'))) return null;
+
+  let feature;
+  try {
+    feature = readJson(join(featureDir, 'feature.json'));
+  } catch {
+    return null;
+  }
+
+  let phase = 'proposal';
+  let pendingGates = [];
+  try {
+    phase = derivePhaseForFeature(featureName, cwd) || 'proposal';
+    pendingGates = getPendingGates(featureName, cwd) || [];
+  } catch { /* fail-open — proposal defaults keep the doc useful */ }
+
+  const generatedAt = new Date().toISOString();
+  const tasks = taskSummary(featureDir);
+  const env = readWorktreeEnv(cwd);
+  const decisions = decisionTitles(featureDir);
+  const worktree = feature.worktree || null;
+
+  const gates = feature.approvals || feature.approvalGates || {};
+  const gateLine = Object.entries(gates)
+    .map(([name, g]) => (g?.approved ? `${name} ✔${g.approvedBy ? ` (${g.approvedBy})` : ''}` : `${name} pendente`))
+    .join(' · ') || '—';
+
+  const relFeatureDir = `.morph/features/${featureName}`;
+  const pointers = POINTER_CANDIDATES
+    .filter(([rel]) => existsSync(join(featureDir, rel)))
+    .map(([rel, why], i) => `${i + 1}. \`${relFeatureDir}/${rel}\` — ${why}`);
+
+  const lines = [
+    `# Handoff — ${featureName}`,
+    '',
+    `> Documento derivado, gerado em ${generatedAt} por \`morph-spec handoff\`.`,
+    '> Regenere com o comando — nunca edite à mão. Aponta para os arquivos da',
+    '> feature em vez de copiá-los: leia os ponteiros, não confie em resumo velho.',
+    '',
+    '## Identidade',
+    '',
+    `- Feature: **${featureName}** (${feature.workType || 'feature'}) · fase: **${phase}** · status: ${feature.status || '—'}`,
+    worktree?.path
+      ? `- Local: worktree \`${worktree.path}\` · branch \`${worktree.branch || `morph/${featureName}`}\``
+      : '- Local: raiz primária (sem worktree registrado)',
+    env
+      ? `- Ambiente: PORT ${env.port}${env.range ? ` (bloco ${env.range})` : ''} — fonte \`.morph/worktree.env\`; suba dev servers SEMPRE nessas portas`
+      : null,
+    '',
+    '## Estado',
+    '',
+    `- Gates: ${gateLine}`,
+    tasks
+      ? `- Tasks: ${tasks.done}/${tasks.total} done · ready agora: ${tasks.ready.length ? tasks.ready.map((t) => `**${t.id}** "${t.title}"`).join(', ') : 'nenhuma'}`
+      : '- Tasks: sem tasks.json ainda (fase de planejamento não concluída)',
+    pendingGates.length ? `- Gates pendentes: ${pendingGates.join(', ')}` : null,
+    '',
+    '## Leia nesta ordem (ponteiros — nada copiado)',
+    '',
+    ...(pointers.length ? pointers : ['1. (nenhum artefato ainda — feature recém-criada)']),
+    decisions.length ? '' : null,
+    decisions.length ? `Últimas decisões: ${decisions.map((d) => `"${d}"`).join(' · ')}` : null,
+    '',
+    '## Próxima ação',
+    '',
+    nextAction(feature, phase, tasks, featureName),
+    '',
+    '## Retomar',
+    '',
+    worktree?.path ? `- \`cd ${worktree.path}\` e abra o Claude Code (uma instância por worktree).` : '- Abra o Claude Code na raiz do projeto.',
+    `- Visão da frota: \`morph-spec fleet\` · status: \`morph-spec status ${featureName}\``,
+    '',
+  ].filter((l) => l !== null);
+
+  return {
+    markdown: `${lines.join('\n')}`,
+    meta: {
+      generatedAt,
+      phase,
+      tasksDone: tasks?.done ?? 0,
+      tasksTotal: tasks?.total ?? 0,
+    },
+  };
+}
+
+/** Marks the exclude block this generator owns in `.git/info/exclude`. */
+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.
+ */
+function ensureHandoffExcluded(cwd) {
+  try {
+    const common = execSync('git rev-parse --git-common-dir', { cwd, stdio: 'pipe' }).toString().trim();
+    if (!common) return;
+    const infoDir = join(resolve(cwd, 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()));
+    if (present.has(HANDOFF_EXCLUDE_PATTERN)) return;
+    mkdirSync(infoDir, { recursive: true });
+    appendFileSync(excludePath, [
+      current && !current.endsWith('\n') ? '\n' : '',
+      present.has(HANDOFF_EXCLUDE_MARKER) ? '' : `${HANDOFF_EXCLUDE_MARKER}\n`,
+      `${HANDOFF_EXCLUDE_PATTERN}\n`,
+    ].join(''));
+  } catch { /* fail-open */ }
+}
+
+/**
+ * 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]
+ * @returns {string|null}
+ */
+export function writeHandoff(featureName, cwd = process.cwd()) {
+  const result = buildHandoff(featureName, cwd);
+  if (!result) return null;
+  const path = join(cwd, '.morph', 'features', featureName, 'handoff.md');
+  try {
+    ensureHandoffExcluded(cwd);
+    writeFileSync(path, result.markdown, 'utf8');
+    return path;
+  } catch {
+    return null;
+  }
+}

package/src/lib/generators/index.js

@@ -5,9 +5,7 @@
  */
 
 export * from './design-system-generator.js';
-export * from './context-generator.js';
-export * from './recap-generator.js';
+export * from './handoff-generator.js';
 export * from './metadata-extractor.js';
 export * from './architecture-scanner.js';
 export * from './scaffold-generator.js';
-export * from './mandate-generator.js';

package/src/lib/worktree/env-allocator.js

@@ -0,0 +1,149 @@
+/**
+ * env-allocator.js — deterministic per-worktree port-block allocation (fleet).
+ *
+ * Two parallel features that both start `next dev` (or `dotnet run`) collide on
+ * the same default port, and the failure is invisible until one server kills
+ * the other. Worktrees isolate files and branches, not runtime — this module
+ * closes that gap by giving every feature worktree its own stable block of
+ * ports.
+ *
+ * The registry lives at `<git-common-dir>/morph-spec/env-registry.json` — under
+ * `.git/` on purpose, for the same reasons as `finish-backup/`: it can never
+ * dirty the `git status` the worktree-finish gates read, it survives
+ * `git clean -fdx`, and the COMMON dir is the one location every linked
+ * worktree of the repo shares.
+ *
+ * Allocation is deterministic (first free index), idempotent per feature, and
+ * released only when `worktree finish` actually removed the worktree. Writes
+ * are tmp+rename so a crash never leaves a torn registry; a corrupt registry
+ * is treated as empty (fail-open — the cost is a re-allocation, never a crash).
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const DEFAULT_BASE_PORT = 4000;
+const DEFAULT_BLOCK_SIZE = 10;
+const MAX_PORT = 65535;
+
+/** Registry file path for a repo's common git dir. */
+export function registryPath(gitCommonDir) {
+  return join(gitCommonDir, 'morph-spec', 'env-registry.json');
+}
+
+function readRegistry(gitCommonDir) {
+  try {
+    const raw = readFileSync(registryPath(gitCommonDir), 'utf8').replace(/^/, '');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.allocations === 'object' && parsed.allocations !== null) {
+      return parsed;
+    }
+  } catch { /* fail-open: corrupt or absent registry restarts empty */ }
+  return { version: 1, allocations: {} };
+}
+
+function writeRegistry(gitCommonDir, registry) {
+  const path = registryPath(gitCommonDir);
+  mkdirSync(join(gitCommonDir, 'morph-spec'), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path);
+}
+
+/**
+ * Read fleet overrides from the project's committed config.json.
+ * Fail-open: missing/malformed config (or a Windows BOM) → defaults.
+ *
+ * @param {string} rootPath - primary root of the project
+ * @returns {{ basePort: number, blockSize: number }}
+ */
+export function resolveFleetConfig(rootPath) {
+  const defaults = { basePort: DEFAULT_BASE_PORT, blockSize: DEFAULT_BLOCK_SIZE };
+  try {
+    const raw = readFileSync(join(rootPath, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, '');
+    const cfg = JSON.parse(raw);
+    const fleet = cfg?.fleet || {};
+    return {
+      basePort: Number.isInteger(fleet.basePort) && fleet.basePort > 0 ? fleet.basePort : defaults.basePort,
+      blockSize: Number.isInteger(fleet.blockSize) && fleet.blockSize > 0 ? fleet.blockSize : defaults.blockSize,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Allocate (or return the existing) port block for a feature.
+ * First-free-index policy: released slots are reused, so long-lived repos
+ * don't creep toward the port ceiling.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string, basePort?: number, blockSize?: number }} opts
+ * @returns {{ index: number, base: number, range: [number, number], created: boolean }}
+ */
+export function allocateEnvBlock(feature, { gitCommonDir, basePort = DEFAULT_BASE_PORT, blockSize = DEFAULT_BLOCK_SIZE }) {
+  const registry = readRegistry(gitCommonDir);
+
+  const existing = registry.allocations[feature];
+  if (existing && Number.isInteger(existing.index)) {
+    const base = basePort + existing.index * blockSize;
+    return { index: existing.index, base, range: [base, base + blockSize - 1], created: false };
+  }
+
+  const used = new Set(
+    Object.values(registry.allocations)
+      .map((a) => a?.index)
+      .filter((i) => Number.isInteger(i)),
+  );
+  let index = 0;
+  while (used.has(index)) index += 1;
+
+  const base = basePort + index * blockSize;
+  if (base + blockSize - 1 > MAX_PORT) {
+    throw new Error(`env-allocator: port block ${base}-${base + blockSize - 1} exceeds ${MAX_PORT}`);
+  }
+
+  registry.allocations[feature] = { index, base, createdAt: new Date().toISOString() };
+  writeRegistry(gitCommonDir, registry);
+  return { index, base, range: [base, base + blockSize - 1], created: true };
+}
+
+/**
+ * Release a feature's block. Returns false when nothing was allocated.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string }} opts
+ * @returns {boolean}
+ */
+export function releaseEnvBlock(feature, { gitCommonDir }) {
+  const registry = readRegistry(gitCommonDir);
+  if (!registry.allocations[feature]) return false;
+  delete registry.allocations[feature];
+  writeRegistry(gitCommonDir, registry);
+  return true;
+}
+
+/**
+ * Render the `.morph/worktree.env` contents for a block, stack-aware.
+ * `PORT` covers next/vite/node dev servers; dotnet gets its own URL on base+1
+ * so a full-stack worktree runs web and api side by side inside one block.
+ *
+ * @param {string} feature
+ * @param {{ base: number, range: [number, number] }} block
+ * @param {string} [stack] - config.json `project.stack` (e.g. "nextjs+dotnet")
+ * @returns {string}
+ */
+export function buildEnvFileContent(feature, block, stack = '') {
+  const lines = [
+    `# Managed by morph-spec — fleet env desta worktree (feature: ${feature}).`,
+    '# Derivado e local: nunca commitar, nunca editar à mão (regenerado pelo worktree setup).',
+    `MORPH_FEATURE=${feature}`,
+    `MORPH_PORT_BASE=${block.base}`,
+    `MORPH_PORT_RANGE=${block.range[0]}-${block.range[1]}`,
+    `PORT=${block.base}`,
+  ];
+  if (/\bdotnet\b/i.test(String(stack))) {
+    lines.push(`ASPNETCORE_URLS=http://localhost:${block.base + 1}`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/lib/worktree/fleet-scanner.js

@@ -0,0 +1,156 @@
+/**
+ * fleet-scanner.js — aggregate view of every active feature across the fleet.
+ *
+ * A fleet is N Claude Code instances, one per feature worktree, plus whatever
+ * is active in the primary root. Each instance only sees its own cwd; the
+ * operator loses track of "what is each session doing, what is waiting on me".
+ * This scanner answers that from the primary root's vantage point: one entry
+ * per active feature, worktree or root-resident, with the operational facts
+ * (phase, pending gates, task counts, port block, handoff freshness, last
+ * commit, dirtiness) resolved per entry.
+ *
+ * Read-only and fail-open per FIELD: a corrupt feature.json or a git hiccup
+ * nulls that field, never the scan.
+ */
+
+import { execSync, execFileSync } from 'child_process';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { isGitRepo, resolvePrimaryRoot, parseWorktreeList } from '../../commands/project/worktree.js';
+import { registryPath, resolveFleetConfig } from './env-allocator.js';
+import {
+  getFeature,
+  derivePhaseForFeature,
+  getPendingGates,
+} from '../../../framework/hooks/shared/state-reader.js';
+
+function taskCounts(featureDir) {
+  try {
+    const data = JSON.parse(readFileSync(join(featureDir, '2-plan', 'tasks.json'), 'utf8'));
+    if (!Array.isArray(data.tasks)) return null;
+    return { done: data.tasks.filter((t) => t.status === 'done').length, total: data.tasks.length };
+  } catch {
+    return null;
+  }
+}
+
+function handoffInfo(featureDir) {
+  try {
+    const path = join(featureDir, 'handoff.md');
+    if (!existsSync(path)) return { exists: false, generatedAt: null };
+    const generatedAt = readFileSync(path, 'utf8').match(/gerado em (\d{4}-\d{2}-\d{2}T[\d:.]+Z)/)?.[1] || null;
+    return { exists: true, generatedAt };
+  } catch {
+    return { exists: false, generatedAt: null };
+  }
+}
+
+function lastCommitRelative(root, branch) {
+  try {
+    return execFileSync('git', ['log', '-1', '--format=%cr', branch], { cwd: root, stdio: 'pipe' })
+      .toString().trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function dirtyCount(worktreePath) {
+  try {
+    const out = execFileSync('git', ['status', '--porcelain'], { cwd: worktreePath, stdio: 'pipe' }).toString();
+    return out.split('\n').filter((l) => l.trim()).length;
+  } catch {
+    return null;
+  }
+}
+
+function buildEntry(feature, { location, path, branch, root, allocations, blockSize }) {
+  let workType = null;
+  let status = 'unknown';
+  let phase = 'proposal';
+  let pendingGates = [];
+  try {
+    const fj = getFeature(feature, path);
+    workType = fj?.workType || null;
+    status = fj?.status || 'unknown';
+    phase = derivePhaseForFeature(feature, path);
+    pendingGates = getPendingGates(feature, path);
+  } catch { /* field-level fail-open */ }
+
+  const featureDir = join(path, '.morph', 'features', feature);
+  const alloc = allocations[feature];
+  return {
+    feature,
+    workType,
+    phase,
+    status,
+    pendingGates,
+    location,
+    path,
+    branch,
+    tasks: taskCounts(featureDir),
+    env: alloc && Number.isInteger(alloc.base)
+      ? { base: alloc.base, range: [alloc.base, alloc.base + blockSize - 1] }
+      : null,
+    handoff: handoffInfo(featureDir),
+    lastCommit: location === 'worktree' && branch ? lastCommitRelative(root, branch) : null,
+    dirty: location === 'worktree' ? dirtyCount(path) : null,
+  };
+}
+
+/**
+ * Scan the fleet from anywhere inside the repo.
+ *
+ * @param {string} [cwd]
+ * @returns {{ root: string, entries: object[] }}
+ */
+export function scanFleet(cwd = process.cwd()) {
+  if (!isGitRepo(cwd)) {
+    return { root: resolve(cwd).replace(/\\/g, '/'), entries: [] };
+  }
+  const root = resolvePrimaryRoot(cwd);
+
+  let allocations = {};
+  try {
+    const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
+    if (common) {
+      const reg = JSON.parse(readFileSync(registryPath(resolve(root, common)), 'utf8'));
+      if (reg && typeof reg.allocations === 'object' && reg.allocations !== null) allocations = reg.allocations;
+    }
+  } catch { /* no registry yet — env stays null per entry */ }
+  const { blockSize } = resolveFleetConfig(root);
+
+  const entries = [];
+  const inWorktree = new Set();
+
+  for (const e of parseWorktreeList(root)) {
+    const m = e.branch && e.branch.match(/^refs\/heads\/morph\/(.+)$/);
+    if (!m) continue; // primary root entry and non-morph worktrees
+    inWorktree.add(m[1]);
+    entries.push(buildEntry(m[1], {
+      location: 'worktree',
+      path: e.path,
+      branch: e.branch.replace(/^refs\/heads\//, ''),
+      root,
+      allocations,
+      blockSize,
+    }));
+  }
+
+  // Root-resident features (no live worktree): whatever has a feature.json.
+  try {
+    const featuresDir = join(root, '.morph', 'features');
+    if (existsSync(featuresDir)) {
+      const names = readdirSync(featuresDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .filter((name) => !inWorktree.has(name) && existsSync(join(featuresDir, name, 'feature.json')));
+      for (const name of names) {
+        entries.push(buildEntry(name, {
+          location: 'root', path: root, branch: null, root, allocations, blockSize,
+        }));
+      }
+    }
+  } catch { /* fail-open */ }
+
+  return { root, entries };
+}