@polymorphism-tech/morph-spec 8.3.0 → 8.5.0

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/archive.js

@@ -1,14 +1,19 @@
 import chalk from 'chalk';
 import { existsSync, renameSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
-import { execSync } from 'child_process';
-import { getFeature, getApprovalGate } from '../../core/state/state-manager.js';
+import { execFileSync } from 'child_process';
 
 /**
  * `morph-spec archive <feature>` — atomic, git-aware archive of a completed
- * feature. Replaces the manual `/morph-archive` mv: it stamps the feature
- * completed, moves `.morph/features/{name}/` → `.morph/archive/{name}/`
- * (staging the move in git when possible), and cleans the thin root index.
+ * feature. Stamps the feature completed, moves `.morph/features/{name}/` →
+ * `.morph/archive/{name}/`, COMMITS the move (scoped to the feature's pathspec),
+ * and cleans the thin root index.
+ *
+ * Two callers:
+ *   - `archiveCommand` (standalone `morph-spec archive` / `/morph-archive`) —
+ *     archive-without-integrate, for legacy features and cleanup.
+ *   - `finishCommand` — runs `runArchive` INSIDE the `morph/{feature}` branch so
+ *     the committed archived state travels with the merge/PR in one integration.
  *
  * Taxonomy: archived = `status: "completed"` + `archivedAt` (per the project
  * decision — no separate "archived" status value).
@@ -16,93 +21,166 @@ import { getFeature, getApprovalGate } from '../../core/state/state-manager.js';
 
 function isGitRepo(cwd) {
   try {
-    execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'pipe' });
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd, stdio: 'pipe' });
     return true;
   } catch {
     return false;
   }
 }
 
-export async function archiveCommand(featureName, options = {}) {
+/** Tolerant read of the review gate — mirrors the finish path's shape handling. */
+function readReviewApproved(fjPath) {
   try {
-    const feature = getFeature(featureName);
-    if (!feature) {
-      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
-      process.exit(1);
-    }
+    const fj = JSON.parse(readFileSync(fjPath, 'utf8'));
+    const gates = fj?.approvalGates || fj?.approvals || {};
+    return gates?.review?.approved === true;
+  } catch {
+    return false;
+  }
+}
 
-    // Precondition: Gate 3 (review) approved — archiving is for completed work.
-    const reviewGate = getApprovalGate(featureName, 'review');
-    if (!reviewGate?.approved && !options.force) {
-      console.error(chalk.red(`\n❌ Gate 3 (review) is not approved for "${featureName}".`));
-      console.log(chalk.gray(`Approve it first (morph-spec approve ${featureName} review) or pass --force.\n`));
-      process.exit(1);
-    }
+/**
+ * Core archive — NO process.exit. Returns a result the caller reports.
+ *
+ * Reads/writes everything relative to `cwd` (never a hard-coded process.cwd()),
+ * so `finishCommand` can archive inside a worktree's own tree.
+ *
+ * Idempotent: if `.morph/archive/{feature}` already exists, returns
+ * `{ ok: true, alreadyArchived: true }` WITHOUT failing — essential so a re-run
+ * of `finish` (which archives inside the branch) does not blow up.
+ *
+ * @param {string} feature
+ * @param {{ cwd?: string, force?: boolean, git?: boolean }} [opts]
+ * @returns {{ ok: boolean, error?: string, archived?: boolean, alreadyArchived?: boolean,
+ *   committed?: boolean, staged?: boolean, archivePath?: string }}
+ */
+export function runArchive(feature, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const featuresPath = join(cwd, '.morph', 'features', feature);
+  const archiveDir = join(cwd, '.morph', 'archive');
+  const archivePath = join(archiveDir, feature);
+  const featPathspec = join('.morph', 'features', feature);
+  const archivePathspec = join('.morph', 'archive', feature);
 
-    const cwd = process.cwd();
-    const featuresPath = join(cwd, '.morph', 'features', featureName);
-    if (!existsSync(featuresPath)) {
-      console.error(chalk.red(`\n❌ Feature folder not found: .morph/features/${featureName}\n`));
-      process.exit(1);
-    }
-    const archiveDir = join(cwd, '.morph', 'archive');
-    const archivePath = join(archiveDir, featureName);
-    if (existsSync(archivePath)) {
-      console.error(chalk.red(`\n❌ Already archived: .morph/archive/${featureName}\n`));
-      process.exit(1);
+  // Idempotent short-circuit: already archived here. Checked FIRST so a re-run
+  // after a partial finish reports "already done", never "not found".
+  if (existsSync(archivePath)) {
+    return { ok: true, alreadyArchived: true, archived: false, archivePath };
+  }
+
+  if (!existsSync(featuresPath)) {
+    return { ok: false, error: 'feature-folder-not-found' };
+  }
+
+  // Precondition: Gate 3 (review) approved — archiving is for completed work.
+  // Read from the feature's own folder (pre-move), tolerant of legacy shapes.
+  const fjPathBefore = join(featuresPath, 'feature.json');
+  if (!opts.force && !readReviewApproved(fjPathBefore)) {
+    return { ok: false, error: 'review-not-approved' };
+  }
+
+  const useGit = opts.git !== false && isGitRepo(cwd);
+
+  // 1) Move the folder. Prefer `git mv` (keeps history + stages in one step);
+  //    fall back to a filesystem rename (+ git add) when the folder isn't
+  //    tracked yet or git mv fails.
+  mkdirSync(archiveDir, { recursive: true });
+  let staged = false;
+  if (useGit) {
+    try {
+      execFileSync('git', ['mv', featuresPath, archivePath], { cwd, stdio: 'pipe' });
+      staged = true;
+    } catch {
+      renameSync(featuresPath, archivePath);
+      try {
+        execFileSync('git', ['add', '-A', '--', featPathspec, archivePathspec], { cwd, stdio: 'pipe' });
+        staged = true;
+      } catch { /* not fatal — the move succeeded */ }
     }
+  } else {
+    renameSync(featuresPath, archivePath);
+  }
 
-    // 1) Stamp the authoritative feature.json (in place) as completed + archived.
-    const fjPath = join(featuresPath, 'feature.json');
-    if (existsSync(fjPath)) {
-      const fj = JSON.parse(readFileSync(fjPath, 'utf8'));
+  // 2) Stamp the authoritative feature.json (now at the archive path) as
+  //    completed + archived, and re-stage it so the commit carries the stamp.
+  const fjPathAfter = join(archivePath, 'feature.json');
+  if (existsSync(fjPathAfter)) {
+    try {
+      const fj = JSON.parse(readFileSync(fjPathAfter, 'utf8'));
       fj.status = 'completed';
       fj.archivedAt = new Date().toISOString();
       fj.updatedAt = fj.archivedAt;
-      writeFileSync(fjPath, JSON.stringify(fj, null, 2), 'utf8');
-    }
+      writeFileSync(fjPathAfter, JSON.stringify(fj, null, 2), 'utf8');
+      if (useGit && staged) {
+        try { execFileSync('git', ['add', '--', archivePathspec], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
+      }
+    } catch { /* non-fatal — the move is what matters */ }
+  }
 
-    // 2) Move the folder. Prefer `git mv` (keeps history + stages in one step);
-    //    fall back to a filesystem rename (+ git add) when the folder isn't
-    //    tracked yet or git mv fails.
-    mkdirSync(archiveDir, { recursive: true });
-    const useGit = isGitRepo(cwd) && options.git !== false;
-    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 — the move succeeded */ }
+  // 3) Commit the move — SCOPED to this feature's pathspec, NEVER `commit -a`
+  //    (same anti-sweep discipline as `finish`'s worktree teardown). This is what
+  //    lets the archived state travel with the branch on `finish` (archive-before-merge).
+  let committed = false;
+  if (useGit && staged) {
+    try {
+      execFileSync('git', ['commit', '-m', `morph-spec archive: ${feature}`, '--', featPathspec, archivePathspec], { cwd, stdio: 'pipe' });
+      committed = true;
+    } catch { /* nothing to commit / no identity — not fatal, the move + stage stand */ }
+  }
+
+  // 4) Drop the feature from the thin root index. Edit the index file directly
+  //    rather than calling saveState — saveState would re-create
+  //    .morph/features/{name}/feature.json and undo the archive.
+  const rootPath = join(cwd, '.morph', 'state.json');
+  if (existsSync(rootPath)) {
+    try {
+      const root = JSON.parse(readFileSync(rootPath, 'utf8'));
+      if (root.features && root.features[feature]) {
+        delete root.features[feature];
+        root.metadata = root.metadata || {};
+        root.metadata.totalFeatures = Object.keys(root.features).length;
+        writeFileSync(rootPath, JSON.stringify(root, null, 2), 'utf8');
       }
-    } else {
-      renameSync(featuresPath, archivePath);
+    } catch { /* index is derivable — non-fatal */ }
+  }
+
+  return { ok: true, archived: true, committed, staged, archivePath };
+}
+
+/**
+ * Standalone `morph-spec archive <feature>` — thin wrapper over `runArchive`
+ * that maps its result to the CLI's messages and exit codes. Preserves the
+ * historical behaviour: an already-archived feature is reported as a refusal.
+ */
+export async function archiveCommand(featureName, options = {}) {
+  try {
+    const result = runArchive(featureName, {
+      cwd: process.cwd(),
+      force: options.force,
+      git: options.git,
+    });
+
+    if (!result.ok) {
+      if (result.error === 'feature-folder-not-found') {
+        console.error(chalk.red(`\n❌ Feature folder not found: .morph/features/${featureName}\n`));
+      } else if (result.error === 'review-not-approved') {
+        console.error(chalk.red(`\n❌ Gate 3 (review) is not approved for "${featureName}".`));
+        console.log(chalk.gray(`Approve it first (morph-spec approve ${featureName} review) or pass --force.\n`));
+      } else {
+        console.error(chalk.red(`\n❌ Error archiving feature: ${result.error}\n`));
+      }
+      process.exit(1);
     }
 
-    // 3) Drop the feature from the thin root index. We edit the index file
-    //    directly rather than calling saveState — saveState would re-create
-    //    .morph/features/{name}/feature.json and undo the archive.
-    const rootPath = join(cwd, '.morph', 'state.json');
-    if (existsSync(rootPath)) {
-      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 */ }
+    if (result.alreadyArchived) {
+      console.error(chalk.red(`\n❌ Already archived: .morph/archive/${featureName}\n`));
+      process.exit(1);
     }
 
     console.log(chalk.green(`\n📦 Archived "${featureName}" → .morph/archive/${featureName}/`));
     console.log(chalk.gray(`   status: completed, archivedAt stamped in feature.json.`));
-    if (staged) console.log(chalk.gray(`   Move staged in git.\n`));
-    else if (useGit) console.log(chalk.gray(`   Move complete; stage it manually if needed.\n`));
+    if (result.committed) console.log(chalk.gray(`   Move committed on the current branch.\n`));
+    else if (result.staged) console.log(chalk.gray(`   Move staged in git; commit it when ready.\n`));
     else console.log('');
   } catch (error) {
     console.error(chalk.red(`\n❌ Error archiving feature: ${error.message}\n`));

package/src/commands/state/create.js

@@ -1,10 +1,45 @@
 import chalk from 'chalk';
-import { mkdirSync, cpSync, readFileSync, writeFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+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';
 import { detectWorkType } from '../../lib/work-type-detector.js';
-import { runWorktreeSetup, materializeState } from '../project/worktree.js';
+import { runWorktreeSetup, materializeState, isGitRepo, branchExists, buildBranchName } from '../project/worktree.js';
+import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+
+/**
+ * Common flow (no `--worktree`): still isolate the feature on its own branch
+ * `morph/{feature}`, branched from the DEFAULT branch (never HEAD — so it never
+ * inherits another feature branch's commits) and checked out in place, so
+ * `morph-spec finish` can later merge/PR it back. Symmetric with the worktree
+ * flow, which gets its branch from `runWorktreeSetup`.
+ *
+ * Fail-open: outside a git repo, with no resolvable default, or on any git
+ * error, the feature is simply left on the current branch — never a failed birth.
+ *
+ * @param {string} featureName
+ * @returns {{ branched: boolean, branch?: string, from?: string, reason?: string }}
+ */
+function branchCommonFlow(featureName) {
+  const cwd = process.cwd();
+  try {
+    if (!isGitRepo(cwd)) return { branched: false, reason: 'not-a-git-repo' };
+    const branch = buildBranchName(featureName);
+    const defaultBranch = detectDefaultBranch(cwd);
+    if (!defaultBranch) return { branched: false, reason: 'no-default-branch' };
+    if (!branchExists(branch, cwd)) {
+      execFileSync('git', ['branch', branch, defaultBranch], { cwd, stdio: 'pipe' });
+    }
+    const current = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
+    if (current !== branch) {
+      execFileSync('git', ['checkout', branch], { cwd, stdio: 'pipe' });
+    }
+    return { branched: true, branch, from: defaultBranch };
+  } catch {
+    return { branched: false, reason: 'git-error' };
+  }
+}
 
 /** Feature names are kebab-case: lowercase alphanumerics and hyphens. */
 const FEATURE_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
@@ -98,16 +133,37 @@ 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);
     const wt = getWorkType(feature);
 
     let worktreeResult = null;
+    let branchResult = null;
 
     if (created) {
       // Scaffold the phase folders this work type starts with.
@@ -138,7 +194,7 @@ export async function createCommand(featureName, options = {}) {
             // stamped it onto the root's feature.json, which cpSync just copied in).
             // Strip it from the worktree's branch-local copy so the branch commits a
             // clean feature.json — otherwise it merges back into the root at
-            // `worktree finish` and the post-merge cleanup leaves the root dirty.
+            // `morph-spec finish` and the post-merge cleanup leaves the root dirty.
             // verify.decidePersistence reads the registration from the ROOT's copy,
             // never this branch-local one (see verify.js), so stripping is safe and
             // restores the invariant that comment relies on.
@@ -163,6 +219,10 @@ export async function createCommand(featureName, options = {}) {
             } catch { /* fail-open */ }
           } catch { /* fail-open — the feature already exists in root */ }
         }
+      } else {
+        // Common flow: still isolate the feature on its own branch so `finish`
+        // can merge/PR it back. Fail-open (see branchCommonFlow).
+        branchResult = branchCommonFlow(featureName);
       }
     }
 
@@ -174,6 +234,7 @@ export async function createCommand(featureName, options = {}) {
     if (options.json) {
       const out = { feature: featureName, created, ...finalFeature };
       if (worktreeResult) out.worktree = worktreeResult;
+      if (branchResult) out.branch = branchResult;
       console.log(JSON.stringify(out, null, 2));
       return;
     }
@@ -196,6 +257,9 @@ export async function createCommand(featureName, options = {}) {
           const why = worktreeResult.error || (worktreeResult.alreadyExists ? 'already exists' : 'unknown');
           console.log(chalk.yellow(`   ⚠️  worktree setup skipped (${why}) — feature stays in the root worktree\n`));
         }
+      } else if (branchResult?.branched) {
+        console.log(chalk.green(`   branch: ${branchResult.branch} (from ${branchResult.from})`));
+        console.log(chalk.gray(`   close it with: morph-spec finish ${featureName} --pr | --merge\n`));
       }
     } else {
       console.log(chalk.yellow(`\n⚠️  Feature "${featureName}" already exists — left untouched`));

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);
+  }
+}