@polymorphism-tech/morph-spec 8.3.0 → 8.5.0

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

@@ -123,7 +123,7 @@ export function atomicWriteJson(targetPath, data) {
  * A formatting mismatch is NOT free, though: the guard compares bytes, so a
  * sibling committed with a trailing newline fails it and gets rewritten. The
  * content is equivalent, but git sees ` M` on a file this caller never meant to
- * touch — enough to fail a whole-tree clean check (see worktreeFinishCommand).
+ * touch — enough to fail a whole-tree clean check (see the finish teardown's clearRootWorktreeRegistration).
  * And the guard only skips IDENTICAL content: a concurrent instance's CHANGED
  * write to a sibling would still be clobbered by the sweep.
  */
@@ -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
@@ -343,7 +373,7 @@ export function saveState(state) {
   //    and shows up as ` M` — dirtying the tree on behalf of a feature the
   //    caller never touched. Callers that need to change ONE feature's field
   //    should write that feature.json directly instead of round-tripping state
-  //    through here (see worktreeFinishCommand's registration cleanup).
+  //    through here (see the finish teardown's clearRootWorktreeRegistration).
   const thinFeatures = {};
   for (const [name, feature] of Object.entries(features)) {
     writeFeatureJson(name, feature);
@@ -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,

package/src/dashboard/scanner/state-scanner.js

@@ -35,7 +35,7 @@ export function scanState(projectDir) {
   // (.worktrees/{wt}/.morph/features/*/feature.json). In the v8 multi-instance
   // model a feature's authoritative feature.json is committed on its
   // `morph/{feature}` branch and only lands in the root .morph/features/ after
-  // `worktree finish`. This is read-only visibility for the dashboard — root
+  // `morph-spec finish`. This is read-only visibility for the dashboard — root
   // features (the merged, authoritative state) always take precedence, and
   // worktree-sourced entries are tagged with `_worktree` so the UI can
   // distinguish them.

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

@@ -111,8 +111,8 @@ function nextAction(feature, phase, tasks, 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\`.`;
+        ? `Gate 3 aprovado — feche: \`morph-spec finish ${featureName} --pr\` (abre PR) ou \`--merge\` (merge local na default). Arquiva + integra num passo.`
+        : `Produza \`4-review/review-report.md\` (avaliador independente) e aprove o Gate 3; depois \`morph-spec finish ${featureName} --pr|--merge\`.`;
     default:
       return `Rode \`morph-spec status ${featureName}\` para orientar o próximo passo.`;
   }

package/src/lib/git/default-branch.js

@@ -0,0 +1,73 @@
+import { execFileSync } from 'child_process';
+
+/**
+ * Git helpers shared by `create` (which branches `morph/{f}` off the default)
+ * and `finish` (which merges/PRs back into it). Kept tiny and pure so both
+ * call sites read the same source of truth for "what is the default branch"
+ * and "is there a remote to push to".
+ */
+
+/**
+ * Does a local branch exist? execFile (argv, never a cmd.exe string) so the
+ * name reaches git as one token — the same anti-injection discipline the rest
+ * of the worktree/finish path uses.
+ *
+ * @param {string} branch
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function localBranchExists(branch, cwd) {
+  try {
+    execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the repository's default branch NAME (e.g. `main`), never assuming
+ * `master`. Strategy, in order:
+ *   1. `refs/remotes/origin/HEAD` symbolic ref — the remote's declared default,
+ *      the authoritative answer when a remote is configured.
+ *   2. A local `main`, then `master` — the fallback for a repo with no remote
+ *      (or one whose `origin/HEAD` was never set).
+ *
+ * Returns `null` when none of these resolve (a repo whose default is some other
+ * name, with no `origin/HEAD` set) — the caller decides: `create` fails open
+ * (no branch), `finish` refuses with a clear message.
+ *
+ * @param {string} [cwd]
+ * @returns {string|null} the default branch name, or null if undeterminable
+ */
+export function detectDefaultBranch(cwd = process.cwd()) {
+  try {
+    const ref = execFileSync('git', ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], { cwd, stdio: 'pipe' })
+      .toString()
+      .trim();
+    // e.g. "refs/remotes/origin/main" → "main"
+    const m = ref.match(/^refs\/remotes\/origin\/(.+)$/);
+    if (m && m[1]) return m[1];
+  } catch { /* no origin/HEAD — fall back to a local default */ }
+
+  for (const candidate of ['main', 'master']) {
+    if (localBranchExists(candidate, cwd)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Is an `origin` remote configured? `--pr` needs one to push the feature branch;
+ * `--merge` is purely local and never calls this.
+ *
+ * @param {string} [cwd]
+ * @returns {boolean}
+ */
+export function hasOriginRemote(cwd = process.cwd()) {
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, stdio: 'pipe' }).toString().trim();
+    return url.length > 0;
+  } catch {
+    return false;
+  }
+}

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

@@ -14,7 +14,7 @@
  * 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
+ * released only when `morph-spec 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).
  */

package/src/utils/file-copier.js

@@ -225,7 +225,7 @@ export async function updateGitignore(projectPath) {
  * Windows with `core.autocrlf=true` (the Git-for-Windows default) and no
  * attribute pinning EOL, Git flags EVERY rewritten feature.json as modified
  * even when the content is byte-identical. That silently breaks the whole-root
- * clean-check in `morph-spec worktree finish` as soon as a project has more
+ * clean-check in `morph-spec finish` as soon as a project has more
  * than one feature — precisely the multi-instance / parallel-worktree flow,
  * where one `saveState` touches sibling feature.json files and marks them dirty.
  * This mirrors the .gitattributes this framework repo already carries for its
@@ -242,7 +242,7 @@ export async function ensureGitattributes(projectPath) {
     `${MARKER} — LF-pin morph state so core.autocrlf never churns it`,
     '# (feature.json is committed + rewritten by saveState with LF; without this,',
     '#  Windows autocrlf marks every feature.json dirty and breaks the whole-root',
-    '#  clean-check in `morph-spec worktree finish`).',
+    '#  clean-check in `morph-spec finish`).',
     '.morph/** text=auto eol=lf',
   ];