@polymorphism-tech/morph-spec 8.4.0 → 8.6.0

package/src/commands/state/archive.js

@@ -1,14 +1,20 @@
 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';
+import { promoteUseCases, SPECS_USECASES_PATHSPEC } from '../../lib/specs/usecase-promoter.js';
 
 /**
  * `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 +22,204 @@ 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, promotedUseCases?: 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".
+  //
+  // Consequence, deliberate: this short-circuits BEFORE the use-case promotion
+  // below, so a promotion that degraded fail-open is NOT retried by re-running
+  // `finish`. That is the price of "closing a feature never fails" — an archived
+  // feature stays archived, and the only signal is an absent `promotedUseCases`
+  // in the output. Recovering means copying the UCs into `.morph/specs/usecases/`
+  // by hand; making this retry would mean re-entering the archive path for an
+  // already-closed feature, which is a worse trade.
+  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 */ }
+  }
+
+  // 3) Promote the feature's use cases into the project's permanent archive
+  //    (.morph/specs/usecases/). Read from the ALREADY-MOVED folder so there is
+  //    a single source path, and land inside the SAME scoped commit below — the
+  //    archive travels with the integration, exactly like the archived state
+  //    (MORPH.md §2.2). Fail-open: any failure degrades to "promoted nothing",
+  //    never to a refused close.
+  let promotedUseCases = [];
+  try {
+    const { promoted } = promoteUseCases(cwd, archivePath);
+    promotedUseCases = promoted;
+    if (promoted.length && useGit && staged) {
+      // This staging exists for the NEW files: promoted use cases are untracked,
+      // and the scoped `commit -- <pathspec>` below only knows paths git already
+      // tracks. The replaced-by-ID deletions are tracked, so that same commit
+      // would carry them even without this line (verified by mutating it away) —
+      // `-A` is belt-and-braces, but dropping the `git add` entirely would
+      // silently promote nothing on a first delivery.
+      try { execFileSync('git', ['add', '-A', '--', SPECS_USECASES_PATHSPEC], { cwd, stdio: 'pipe' }); } catch { /* non-fatal */ }
     }
+  } catch { /* promotion must never block archiving */ }
 
-    // 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 */ }
+  // 4) 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).
+  //    The acervo pathspec joins only when something was promoted: git refuses a
+  //    pathspec that matches nothing, and that refusal would leave the tree dirty
+  //    and break the checkout/merge that follows.
+  let committed = false;
+  if (useGit && staged) {
+    const pathspecs = promotedUseCases.length
+      ? [featPathspec, archivePathspec, SPECS_USECASES_PATHSPEC]
+      : [featPathspec, archivePathspec];
+    try {
+      execFileSync('git', ['commit', '-m', `morph-spec archive: ${feature}`, '--', ...pathspecs], { cwd, stdio: 'pipe' });
+      committed = true;
+    } catch { /* nothing to commit / no identity — not fatal, the move + stage stand */ }
+  }
+
+  // 5) 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, promotedUseCases };
+}
+
+/**
+ * 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.promotedUseCases?.length) {
+      console.log(chalk.gray(`   ${result.promotedUseCases.length} use case(s) promoted → .morph/specs/usecases/ (status: implemented).`));
+    }
+    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 { 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-]*$/;
@@ -128,6 +163,7 @@ export async function createCommand(featureName, options = {}) {
     const wt = getWorkType(feature);
 
     let worktreeResult = null;
+    let branchResult = null;
 
     if (created) {
       // Scaffold the phase folders this work type starts with.
@@ -158,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.
@@ -183,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);
       }
     }
 
@@ -194,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;
     }
@@ -216,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`));