@polymorphism-tech/morph-spec 8.3.0 → 8.4.0

package/src/commands/project/doctor.js

@@ -14,6 +14,7 @@ import {
 import { resetMorphSettings } from '../../utils/claude-settings-manager.js';
 import { checkMissingAgents, checkAgentsDrift } from '../../utils/agents-installer.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
+import { auditFeatureLifecycle } from '../../core/state/lifecycle-audit.js';
 
 const isWindows = platform() === 'win32';
 /**
@@ -896,6 +897,22 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
+  // Feature-lifecycle consistency — the consolidated inconsistency report:
+  // gate-order violations (N approved with N-1 pending), identity-less
+  // features (no description), orphan folders and stale index entries. Warn
+  // only (advisory); the per-feature detail is printed after the summary.
+  const lifecycleIssues = auditFeatureLifecycle(targetPath);
+  if (lifecycleIssues.length === 0) {
+    checks.push({ name: 'feature lifecycle', status: 'ok' });
+  } else {
+    checks.push({
+      name: 'feature lifecycle',
+      status: 'warn',
+      msg: `${lifecycleIssues.length} inconsistenc${lifecycleIssues.length === 1 ? 'y' : 'ies'} (see below)`,
+    });
+    hasWarnings = true;
+  }
+
   // Check key templates exist (in framework package, not project copy)
   const frameworkTemplatesRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'templates');
   const keyTemplates = [
@@ -944,6 +961,17 @@ export async function doctorCommand(options = {}) {
     }
   }
 
+  // Per-feature detail for the lifecycle inconsistencies (item: doctor lists
+  // what's already wrong in the repo, e.g. plan approved with proposal pending).
+  if (lifecycleIssues.length) {
+    logger.blank();
+    console.log(chalk.yellow('  Feature lifecycle inconsistencies:'));
+    for (const issue of lifecycleIssues) {
+      console.log(chalk.gray(`    • ${issue.feature} [${issue.type}] — ${issue.detail}`));
+    }
+    console.log(chalk.gray("    Fix: 'morph-spec approve' (order), '--description' on create, or 'morph-spec delete' for dead scaffolds."));
+  }
+
   logger.blank();
 
   if (hasErrors) {

package/src/commands/state/advance.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { getFeature, setApprovalGate, derivePhase } from '../../core/state/state-manager.js';
+import { unmetPrereqs } from '../../core/state/gate-order.js';
 
 /**
  * `morph-spec advance <feature>` — approve the current phase's gate AND scaffold
@@ -57,6 +58,22 @@ export async function advanceCommand(featureName, options = {}) {
     const gate = PHASE_GATE[phase];
     const approvedBy = resolveApprovedBy(options);
 
+    // Gate monotonicity (mirrors approve.js): advance is a gate write-path too,
+    // so it must not stamp gate N while a predecessor is pending. In the
+    // sanctioned flow advance is always in-order (it approves G1 before the plan
+    // artifact that flips the phase to plan exists), but an anomalous filesystem
+    // state — e.g. 2-plan/spec.md present without Gate 1, the lead-termometro
+    // shape — would otherwise let advance deepen the violation by stamping G2.
+    // Escape via --force for deliberate recovery.
+    if (gate) {
+      const unmet = unmetPrereqs(gate, feature.approvalGates);
+      if (unmet.length && !options.force) {
+        console.error(chalk.red(`\n❌ Cannot advance past the ${phase} phase — prerequisite gate(s) not approved: ${unmet.join(', ')}.`));
+        console.error(chalk.gray(`   Gates must be approved in order (${unmet.join(' → ')} → ${gate}). Approve them first, or pass --force.\n`));
+        process.exit(1);
+      }
+    }
+
     // Hotfix backstop (defensive, mirrors approve.js): the phase==='review'
     // early-return above already stops advance from ever reaching a
     // gate==='review' approval, but guard the approval itself too so this

package/src/commands/state/approve.js

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { getFeature, setApprovalGate, getApprovalGate, getApprovalHistory, derivePhase } from '../../core/state/state-manager.js';
+import { unmetPrereqs } from '../../core/state/gate-order.js';
 
 /**
  * Unapprove action function - Revoke a previously approved gate
@@ -99,6 +100,18 @@ export async function approveCommand(featureName, gateName, options = {}) {
       return;
     }
 
+    // Gate monotonicity: a gate may only be approved once its predecessors are
+    // approved (proposal → plan → review; uiux requires proposal). Prevents the
+    // lead-termometro shape — plan.approved with proposal pending. Policy-stamped
+    // gates count as approved, so chore/hotfix satisfy prereqs naturally.
+    // Escape via --force for deliberate recovery.
+    const unmet = unmetPrereqs(gateName, feature.approvalGates);
+    if (unmet.length && !options.force) {
+      console.error(chalk.red(`\n❌ Cannot approve "${gateName}" — prerequisite gate(s) not approved: ${unmet.join(', ')}.`));
+      console.log(chalk.gray(`   Gates must be approved in order (${unmet.map((u) => u).join(' → ')} → ${gateName}). Approve them first, or pass --force.\n`));
+      process.exit(1);
+    }
+
     // Resolve who approved BEFORE the hotfix backstop — the backstop gates on
     // the resolved signature, not the raw --mode string (see below).
     //

package/src/commands/state/create.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { mkdirSync, cpSync, readFileSync, writeFileSync } from 'fs';
+import { mkdirSync, cpSync, readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { createFeature, setApprovalGate, getFeature } from '../../core/state/state-manager.js';
 import { WORK_TYPES, DEFAULT_WORK_TYPE, POLICY_APPROVER_PREFIX, isValidWorkType, getWorkType } from '../../core/work-types.js';
@@ -98,10 +98,30 @@ export async function createCommand(featureName, options = {}) {
     const now = new Date().toISOString();
     const { workType, workTypeDetection } = resolveWorkType(options, now);
 
+    // Identity at birth: every feature is stamped name (slug by default) +
+    // description, so it is never an anonymous {status,updatedAt} shell.
+    // `--request` (which the router already consumes) doubles as the
+    // description seed. A NEW feature with no description source is refused —
+    // the description is the one identity field a human must supply. An
+    // idempotent re-run on an EXISTING feature never demands it.
+    const description = options.description ?? options.request ?? null;
+    // Existence check via the filesystem, NOT getFeature/loadState — loadState
+    // throws when no state exists yet (a feature can be the first morph action
+    // in a fresh project), which would break birth-from-nothing.
+    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('   This keeps features identifiable — no more anonymous scaffolds.\n'));
+      process.exit(1);
+    }
+
     const { feature, created } = await createFeature(featureName, {
       status: options.status,
       workType,
       workTypeDetection,
+      name: options.name,
+      description: description ?? undefined,
     });
 
     const featureDir = join(process.cwd(), '.morph', 'features', featureName);

package/src/commands/state/delete.js

@@ -0,0 +1,143 @@
+import chalk from 'chalk';
+import { existsSync, rmSync, renameSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * `morph-spec delete <feature>` — remove a feature. Hard by default (folder is
+ * gone), soft via `--archive` (moved to .morph/archive with status
+ * "abandoned"). The complement of `archive`: archive = completed work you keep;
+ * delete = dead scaffolds and abandoned drafts you clear out.
+ *
+ * The critical guarantee — mirrored from `archive` — is that the deletion also
+ * drops the feature from the thin root index (.morph/state.json). Without that,
+ * the next `loadState` resurrects the folder from the stale index entry
+ * (turning a delete into a zombie). We edit the index directly rather than
+ * calling saveState, which would re-materialize .morph/features/{name}.
+ *
+ * Refuses when any gate is approved (real work, not a dead shell), unless
+ * `--force`.
+ */
+
+function isGitRepo(cwd) {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function approvedGates(feature) {
+  const gates = feature?.approvalGates || {};
+  return Object.entries(gates)
+    .filter(([, g]) => g?.approved === true)
+    .map(([name]) => name);
+}
+
+/** Drop the feature from the thin, derivable root index (like archive does). */
+function dropFromIndex(cwd, featureName) {
+  const rootPath = join(cwd, '.morph', 'state.json');
+  if (!existsSync(rootPath)) return;
+  try {
+    const root = JSON.parse(readFileSync(rootPath, 'utf8'));
+    if (root.features && root.features[featureName]) {
+      delete root.features[featureName];
+      root.metadata = root.metadata || {};
+      root.metadata.totalFeatures = Object.keys(root.features).length;
+      writeFileSync(rootPath, JSON.stringify(root, null, 2), 'utf8');
+    }
+  } catch { /* index is derivable — non-fatal */ }
+}
+
+export async function deleteCommand(featureName, options = {}) {
+  try {
+    const cwd = options.cwd || process.cwd();
+    const featuresPath = join(cwd, '.morph', 'features', featureName);
+    const fjPath = join(featuresPath, 'feature.json');
+
+    if (!existsSync(featuresPath)) {
+      console.error(chalk.red(`\n❌ Feature not found: .morph/features/${featureName}\n`));
+      process.exit(1);
+    }
+
+    // Read the authoritative feature.json directly (not loadState — a read that
+    // mutates state has no place inside a delete).
+    let feature = {};
+    if (existsSync(fjPath)) {
+      try { feature = JSON.parse(readFileSync(fjPath, 'utf8')); } catch { feature = {}; }
+    }
+
+    // Precondition: no approved gate (real work) unless --force.
+    const approved = approvedGates(feature);
+    if (approved.length && !options.force) {
+      console.error(chalk.red(`\n❌ "${featureName}" has approved gate(s): ${approved.join(', ')}.`));
+      console.log(chalk.gray(`   Deleting approved work is unusual — pass --force to override,`));
+      console.log(chalk.gray(`   or 'morph-spec archive ${featureName}' if it's actually complete.\n`));
+      process.exit(1);
+    }
+
+    const useGit = isGitRepo(cwd) && options.git !== false;
+
+    if (options.archive) {
+      // Soft delete: move to .morph/archive with status "abandoned".
+      const archiveDir = join(cwd, '.morph', 'archive');
+      const archivePath = join(archiveDir, featureName);
+      if (existsSync(archivePath)) {
+        console.error(chalk.red(`\n❌ Already present in archive: .morph/archive/${featureName}\n`));
+        process.exit(1);
+      }
+      if (existsSync(fjPath)) {
+        feature.status = 'abandoned';
+        feature.abandonedAt = new Date().toISOString();
+        feature.updatedAt = feature.abandonedAt;
+        writeFileSync(fjPath, JSON.stringify(feature, null, 2), 'utf8');
+      }
+      mkdirSync(archiveDir, { recursive: true });
+      let staged = false;
+      if (useGit) {
+        try {
+          execSync(`git mv "${featuresPath}" "${archivePath}"`, { cwd, stdio: 'pipe' });
+          staged = true;
+        } catch {
+          renameSync(featuresPath, archivePath);
+          try { execSync(`git add -A "${featuresPath}" "${archivePath}"`, { cwd, stdio: 'pipe' }); staged = true; } catch { /* not fatal */ }
+        }
+      } else {
+        renameSync(featuresPath, archivePath);
+      }
+      dropFromIndex(cwd, featureName);
+
+      if (options.json) { console.log(JSON.stringify({ deleted: featureName, mode: 'archive', status: 'abandoned', staged })); process.exit(0); }
+      console.log(chalk.yellow(`\n🗃  Abandoned "${featureName}" → .morph/archive/${featureName}/`));
+      console.log(chalk.gray(`   status: abandoned, abandonedAt stamped; dropped from index.`));
+      console.log(staged ? chalk.gray('   Move staged in git.\n') : '');
+      process.exit(0);
+    }
+
+    // Hard delete: remove the folder (git-aware), then drop from index.
+    let staged = false;
+    if (useGit) {
+      try {
+        execSync(`git rm -r -f --quiet "${featuresPath}"`, { cwd, stdio: 'pipe' });
+        staged = true;
+      } catch {
+        // Untracked (never committed) — just remove it from disk.
+        rmSync(featuresPath, { recursive: true, force: true });
+        try { execSync(`git add -A "${featuresPath}"`, { cwd, stdio: 'pipe' }); staged = true; } catch { /* not fatal */ }
+      }
+    } else {
+      rmSync(featuresPath, { recursive: true, force: true });
+    }
+    dropFromIndex(cwd, featureName);
+
+    if (options.json) { console.log(JSON.stringify({ deleted: featureName, mode: 'hard', staged })); process.exit(0); }
+    console.log(chalk.green(`\n🗑  Deleted "${featureName}" (.morph/features/${featureName}/ removed, dropped from index).`));
+    if (approved.length) console.log(chalk.gray(`   (had approved gate(s): ${approved.join(', ')} — removed via --force)`));
+    console.log(staged ? chalk.gray('   Removal staged in git.\n') : '');
+    process.exit(0);
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error deleting feature: ${error.message}\n`));
+    process.exit(1);
+  }
+}

package/src/commands/state/list.js

@@ -0,0 +1,110 @@
+import chalk from 'chalk';
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { derivePhase } from '../../core/state/state-manager.js';
+import { gateOrderViolations } from '../../core/state/gate-order.js';
+import { missingIdentity } from '../../core/state/feature-identity.js';
+
+/**
+ * `morph-spec list [--all] [--json]` — the feature audit board.
+ *
+ * One row per feature: slug × workType × status × phase × gates (G1/G2/G3) ×
+ * description, plus a flags column for anomalies (missing description, gate
+ * order). Complements `delete`: see what's dead before removing it. Replaces
+ * the ad-hoc "loop over every feature.json in python" audit.
+ *
+ * Read-only by construction — reads feature.json straight off disk (never
+ * `loadState`, which mutates), so listing can never resurrect or prune state.
+ * Always exits 0 (fail-open — an empty board is an answer).
+ */
+
+const G = ['proposal', 'uiux', 'plan', 'review'];
+
+function readFeaturesIn(baseDir, subdir, location) {
+  const root = join(baseDir, '.morph', subdir);
+  if (!existsSync(root)) return [];
+  const rows = [];
+  for (const name of readdirSync(root)) {
+    const fdir = join(root, name);
+    try {
+      if (!statSync(fdir).isDirectory()) continue;
+    } catch { continue; }
+    const fjPath = join(fdir, 'feature.json');
+    if (!existsSync(fjPath)) continue;
+    let fj;
+    try {
+      fj = JSON.parse(readFileSync(fjPath, 'utf8'));
+    } catch { fj = { status: 'unknown', __corrupt: true }; }
+    rows.push(buildRow(name, fj, fdir, location));
+  }
+  return rows;
+}
+
+function buildRow(name, fj, fdir, location) {
+  const gates = {};
+  for (const g of G) gates[g] = fj.approvalGates?.[g]?.approved === true;
+
+  const flags = [];
+  if (fj.__corrupt) flags.push('corrupt');
+  // Identity + gate-order anomalies come from the shared rules
+  // (core/state/feature-identity.js, core/state/gate-order.js) — same source
+  // doctor reports from.
+  for (const field of missingIdentity(fj)) flags.push(`missing-${field}`);
+  for (const v of gateOrderViolations(fj.approvalGates)) flags.push(`gate-order:${v.gate}`);
+
+  return {
+    feature: name,
+    name: fj.name || null,
+    description: fj.description || null,
+    workType: fj.workType || 'feature',
+    status: fj.status || 'unknown',
+    phase: location === 'archived' ? 'archived' : derivePhase(fdir),
+    gates,
+    flags,
+    location,
+    createdAt: fj.createdAt || null,
+    updatedAt: fj.updatedAt || null,
+  };
+}
+
+const mark = (on) => (on ? chalk.green('✓') : chalk.gray('·'));
+const truncate = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+export function listCommand(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const rows = readFeaturesIn(cwd, 'features', 'active');
+  if (options.all || options.archived) rows.push(...readFeaturesIn(cwd, 'archive', 'archived'));
+  rows.sort((a, b) => a.feature.localeCompare(b.feature));
+
+  if (options.json) {
+    console.log(JSON.stringify(rows));
+    process.exit(0);
+  }
+
+  if (!rows.length) {
+    console.log(chalk.gray('Nenhuma feature — .morph/features está vazio.'));
+    process.exit(0);
+  }
+
+  const col = (s, w) => String(s ?? '-').padEnd(w);
+  console.log(chalk.white.bold(
+    col('FEATURE', 22) + col('TYPE', 9) + col('STATUS', 13) + col('PHASE', 11)
+    + col('G1', 4) + col('G2', 4) + col('G3', 4) + col('', 3) + 'DESCRIPTION',
+  ));
+  for (const r of rows) {
+    const flag = r.flags.length ? chalk.yellow('⚠') : ' ';
+    const desc = r.description ? truncate(r.description, 44) : chalk.yellow('(sem descrição)');
+    // padEnd counts the invisible color codes; pad the plain marks manually.
+    console.log(
+      col(r.feature, 22) + col(r.workType, 9) + col(r.status, 13) + col(r.phase, 11)
+      + mark(r.gates.proposal) + '   ' + mark(r.gates.plan) + '   ' + mark(r.gates.review) + '   '
+      + flag + ' ' + desc,
+    );
+  }
+  const flagged = rows.filter((r) => r.flags.length);
+  if (flagged.length) {
+    console.log(chalk.gray(`\n⚠ ${flagged.length} com inconsistência — rode 'morph-spec doctor' para detalhes.`));
+  }
+  console.log(chalk.gray(`\nG1=proposal · G2=plan · G3=review${options.all || options.archived ? ' · inclui arquivadas' : ''}`));
+  process.exit(0);
+}

package/src/core/state/feature-identity.js

@@ -0,0 +1,36 @@
+/**
+ * Feature identity — the fields that keep a feature.json from being an
+ * anonymous shell (the {status, updatedAt}-only scaffolds nobody could later
+ * identify). name/createdAt/workType are auto-stamped at birth (explicit
+ * `morph-spec create` or the state-sync hook's implicit registration);
+ * `description` is the one field a human must supply.
+ *
+ * `missingIdentity` powers the audit surfaces (`list`, `doctor`) that flag
+ * pre-existing anonymous features LENIENTLY (warn, never invalidate old
+ * feature.json). `create` enforces `description` HARD at birth — the two-tier
+ * split the schema's `required` array can't express (adding fields there would
+ * invalidate every feature.json that predates this).
+ *
+ * Pure module — no filesystem/CLI side effects.
+ */
+
+export const IDENTITY_FIELDS = ['name', 'description', 'workType', 'createdAt'];
+
+const blank = (v) => v === undefined || v === null || String(v).trim() === '';
+
+/**
+ * Identity fields absent from a feature.json (empty array = fully identified).
+ * `description` leads because its absence is the real anonymity signal.
+ * `workType` is intentionally excluded — absent workType defaults to 'feature',
+ * so it is never a marker of an anonymous shell.
+ *
+ * @param {object} feature - feature.json contents
+ * @returns {string[]} missing identity field names
+ */
+export function missingIdentity(feature) {
+  const missing = [];
+  if (blank(feature?.description)) missing.push('description');
+  if (blank(feature?.createdAt)) missing.push('createdAt');
+  if (blank(feature?.name)) missing.push('name');
+  return missing;
+}

package/src/core/state/gate-order.js

@@ -0,0 +1,51 @@
+/**
+ * Gate monotonicity — single source of truth.
+ *
+ * A gate may only be approved once its predecessors are approved. The strict
+ * chain is proposal → plan → review. uiux is optional: it requires proposal but
+ * gates nothing downstream, so a feature that skips UI/UX is never blocked.
+ *
+ * Policy-stamped gates (approvedBy: "policy:{type}", written at birth by
+ * `morph-spec create` for a work type's skippedGates) count as approved, so
+ * chore/hotfix (proposal+plan pre-stamped) satisfy prereqs naturally.
+ *
+ * Pure module — no filesystem/CLI side effects. Consumed by
+ * `approve`/`advance` (refuse), the state-sync hook (warn), and `list`/`doctor`
+ * (report).
+ */
+
+export const GATE_PREREQ = {
+  proposal: [],
+  uiux: ['proposal'],
+  plan: ['proposal'],
+  review: ['plan'],
+};
+
+const isApproved = (gates, name) => gates?.[name]?.approved === true;
+
+/**
+ * Prerequisite gates NOT yet approved that block approving `gate`.
+ * @param {string} gate - gate about to be approved
+ * @param {object} gates - feature.approvalGates
+ * @returns {string[]} unmet prerequisite gate names (empty = clear to approve)
+ */
+export function unmetPrereqs(gate, gates) {
+  const prereqs = GATE_PREREQ[gate] || [];
+  return prereqs.filter((p) => !isApproved(gates, p));
+}
+
+/**
+ * All monotonicity violations currently present in a feature's gates.
+ * @param {object} gates - feature.approvalGates
+ * @returns {Array<{gate: string, missing: string[]}>} empty when in order
+ */
+export function gateOrderViolations(gates) {
+  if (!gates || typeof gates !== 'object') return [];
+  const out = [];
+  for (const gate of Object.keys(GATE_PREREQ)) {
+    if (!isApproved(gates, gate)) continue;
+    const missing = GATE_PREREQ[gate].filter((p) => !isApproved(gates, p));
+    if (missing.length) out.push({ gate, missing });
+  }
+  return out;
+}

package/src/core/state/lifecycle-audit.js

@@ -0,0 +1,79 @@
+/**
+ * Feature-lifecycle audit — the consolidated inconsistency scanner behind
+ * `morph-spec doctor`. Read-only, non-throwing: scans `.morph/features/*` and
+ * the thin root index and reports what's already wrong in the repo, without
+ * touching state (never calls loadState — a diagnostic must not mutate).
+ *
+ * Issue types:
+ *   • gate-order    — a gate approved with a predecessor pending (item 4)
+ *   • identity      — a feature missing description/name/createdAt (item 3)
+ *   • orphan-folder — a feature folder with no feature.json
+ *   • stale-index   — a root-index entry with no feature folder (auto-heals on
+ *                     the next loadState, but surfaced so it's not a mystery)
+ *   • corrupt       — a feature.json that won't parse
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { gateOrderViolations } from './gate-order.js';
+import { missingIdentity } from './feature-identity.js';
+
+/**
+ * @param {string} [baseDir] - project root (defaults to cwd)
+ * @returns {Array<{ feature: string, type: string, detail: string }>} issues
+ */
+export function auditFeatureLifecycle(baseDir = process.cwd()) {
+  const issues = [];
+  const featuresDir = join(baseDir, '.morph', 'features');
+  const onDisk = new Set();
+
+  if (existsSync(featuresDir)) {
+    for (const name of readdirSync(featuresDir)) {
+      const fdir = join(featuresDir, name);
+      try {
+        if (!statSync(fdir).isDirectory()) continue;
+      } catch { continue; }
+
+      const fjPath = join(fdir, 'feature.json');
+      if (!existsSync(fjPath)) {
+        issues.push({ feature: name, type: 'orphan-folder', detail: 'folder has no feature.json' });
+        continue;
+      }
+      onDisk.add(name);
+
+      let fj;
+      try {
+        fj = JSON.parse(readFileSync(fjPath, 'utf8'));
+      } catch {
+        issues.push({ feature: name, type: 'corrupt', detail: 'feature.json is not valid JSON' });
+        continue;
+      }
+
+      const miss = missingIdentity(fj);
+      if (miss.length) {
+        issues.push({ feature: name, type: 'identity', detail: `missing ${miss.join(', ')}` });
+      }
+      for (const v of gateOrderViolations(fj.approvalGates)) {
+        issues.push({
+          feature: name,
+          type: 'gate-order',
+          detail: `${v.gate} approved but ${v.missing.join(', ')} pending`,
+        });
+      }
+    }
+  }
+
+  const rootPath = join(baseDir, '.morph', 'state.json');
+  if (existsSync(rootPath)) {
+    try {
+      const root = JSON.parse(readFileSync(rootPath, 'utf8'));
+      for (const name of Object.keys(root.features || {})) {
+        if (!onDisk.has(name)) {
+          issues.push({ feature: name, type: 'stale-index', detail: 'in state.json index but no feature folder' });
+        }
+      }
+    } catch { /* index is derivable — non-fatal */ }
+  }
+
+  return issues;
+}

package/src/core/state/state-manager.js

@@ -261,6 +261,14 @@ export function loadState(throwOnError = true) {
     if (fromConfig) state.project = { ...(state.project || {}), ...fromConfig };
   }
 
+  // Snapshot the on-disk version BEFORE the migration blocks below bump it. The
+  // reconciliation loop uses it to tell a legacy monolith (a pre-v5 layout that
+  // predates the split — materialize) from a current-version index entry whose
+  // folder is gone (a deleted feature — prune). A missing root index is treated
+  // as "no migration" (null): the loop is empty in that case (features hydrate
+  // from disk), so the value only matters when the root index exists.
+  const fileVersion = rootExists ? state.version : null;
+
   // A missing root index means we must (re)generate it from the per-feature
   // files we're about to hydrate — this is the self-heal path after a wipe.
   let mutated = !rootExists;
@@ -291,14 +299,36 @@ export function loadState(throwOnError = true) {
     mutated = true;
   }
 
-  // Split-on-load: any feature still living only in the root index (no
-  // feature.json yet) is written out to its authoritative per-feature file.
-  // This migrates pre-split monolithic state and is idempotent thereafter.
+  // Reconcile index entries whose feature.json is missing. The discriminator is
+  // the ON-DISK VERSION (`fileVersion`, snapshotted before the migrations bumped
+  // it) — NOT whether any sibling folder survived. Sibling-existence is the wrong
+  // signal: deleting EVERY folder at once (the reported incident) would leave no
+  // survivor and resurrect them all. Version is unconditional:
+  //
+  //   • A pre-v5 root (v3/v4) or an entry rich beyond the thin {status,updatedAt}
+  //     shape = a legacy monolithic state.json that predates the split. It is the
+  //     sole copy of its feature — materialize each to its authoritative
+  //     feature.json (split-on-load migration; idempotent thereafter).
+  //
+  //   • A current-version (v5) thin entry with NO folder = the feature was
+  //     DELETED and this gitignored index entry is stale. Prune it; NEVER recreate
+  //     the folder — that turned an intentional delete into a zombie. This is safe
+  //     and exhaustive because saveState ALWAYS co-writes feature.json + a thin
+  //     index entry: a v5 thin entry with no feature.json can ONLY mean the folder
+  //     was removed. The prune sticks — saveState below derives the index from this
+  //     same in-memory map, and hydration only re-adds features whose folder exists.
+  const isRichEntry = (f) =>
+    f && typeof f === 'object' && Object.keys(f).some((k) => k !== 'status' && k !== 'updatedAt');
+  const wasVersionMigration = fileVersion !== null && fileVersion !== STATE_VERSION;
   for (const [name, feature] of Object.entries(state.features)) {
-    if (!existsSync(getFeatureJsonPath(name))) {
-      writeFeatureJson(name, feature);
-      mutated = true;
+    if (existsSync(getFeatureJsonPath(name))) continue;
+    if (wasVersionMigration || isRichEntry(feature)) {
+      writeFeatureJson(name, feature); // legacy monolith — materialize, don't lose it
+    } else {
+      delete state.features[name]; // v5 thin entry, no folder = deleted — never resurrect
+      console.error(`ℹ morph-spec: dropped stale index entry "${name}" (feature folder was deleted).`);
     }
+    mutated = true;
   }
 
   // Hydrate from per-feature files (authoritative). Also picks up features that
@@ -509,15 +539,18 @@ async function ensureFeature(featureName) {
  * Works even before any state exists (scaffolds the root index), so a
  * feature can be born as the very first morph action in a project.
  *
- * @param {string} featureName - Feature name (kebab-case)
- * @param {{ status?: string, workType?: string, workTypeDetection?: object }} [options]
- *   `workType` defaults to 'feature' (v8 routing — see src/core/work-types.js).
- *   `workTypeDetection` is only written when provided (source/confidence/matched
- *   audit trail from the `--type`/`--request` resolution in `create.js`).
+ * @param {string} featureName - Feature name (kebab-case), also the folder id
+ * @param {{ status?: string, workType?: string, workTypeDetection?: object, name?: string, description?: string }} [options]
+ *   `name` defaults to `featureName` (the slug) — always stamped so a feature
+ *   is never nameless. `description` is written only when provided (the CLI
+ *   `create` enforces it; internal callers may omit it). `workType` defaults to
+ *   'feature' (v8 routing — see src/core/work-types.js). `workTypeDetection` is
+ *   only written when provided (source/confidence/matched audit trail from the
+ *   `--type`/`--request` resolution in `create.js`).
  * @returns {Promise<{ feature: Object, created: boolean }>}
  */
 export async function createFeature(featureName, options = {}) {
-  const { status = 'in_progress', workType, workTypeDetection } = options;
+  const { status = 'in_progress', workType, workTypeDetection, name, description } = options;
   const state = loadState(false) || scaffoldState();
 
   const existing = state.features[featureName];
@@ -527,6 +560,8 @@ export async function createFeature(featureName, options = {}) {
 
   const now = new Date().toISOString();
   state.features[featureName] = {
+    name: name || featureName,
+    ...(description !== undefined && description !== null ? { description } : {}),
     status,
     workType: workType || 'feature',
     createdAt: now,