@polymorphism-tech/morph-spec 8.3.0 → 8.5.0

package/src/commands/state/finish.js

@@ -0,0 +1,422 @@
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import {
+  findWorktreeForFeature,
+  shedRootFeatureScope,
+  primaryRootUnexplainedDirt,
+  teardownWorktree,
+  resolvePrimaryRoot,
+  isValidFeatureName,
+  buildBranchName,
+  branchExists,
+} from '../project/worktree.js';
+import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
+import { runArchive } from './archive.js';
+
+/**
+ * `morph-spec finish <feature> --pr|--merge` — the single, symmetric close of a
+ * feature's lifecycle, for BOTH the worktree flow and the common flow.
+ *
+ * Order (see the plan's backbone): validate → ARCHIVE inside the `morph/{f}`
+ * branch (committed, so the archived state travels in one integration) →
+ * integrate:
+ *   --merge  : merge `--no-ff` into the default branch, LOCAL (no push).
+ *   --pr     : push `morph/{f}` + `gh pr create` (does NOT merge locally).
+ * → teardown the worktree (PROVE-or-DECLINE) when there is one.
+ *
+ * Every refusal is fail-CLOSED, exit 1, and — since the `--pr` remote
+ * preconditions run BEFORE the archive — a refused `--pr` leaves no side effect.
+ * `finished` is the integration (the actual value); `worktreeRemoved` is the
+ * best-effort teardown — two independent signals, as before.
+ *
+ * @param {string} feature
+ * @param {{ pr?: boolean, merge?: boolean, keep?: boolean, force?: boolean,
+ *   discardIgnored?: boolean, cwd?: string }} [options]
+ */
+export async function finishCommand(feature, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const root = resolvePrimaryRoot(cwd);
+  const emit = (obj) => console.log(JSON.stringify(obj));
+  const rootNorm = resolve(root).replace(/\\/g, '/');
+
+  // Gate 0: valid kebab name — anti command-injection (the name flows into every
+  // git/gh call below) and the same gate the worktree path always applied.
+  if (!isValidFeatureName(feature)) {
+    emit({ finished: false, error: 'invalid-feature-name', feature });
+    process.exit(1);
+  }
+
+  // Mode: exactly one of --pr / --merge (they are alternative integrations — the
+  // finish merges OR opens a PR, never both, never neither).
+  const wantPr = !!options.pr;
+  const wantMerge = !!options.merge;
+  if (wantPr === wantMerge) {
+    emit({ finished: false, error: 'mode-required', hint: 'informe exatamente um de --pr ou --merge', feature });
+    process.exit(1);
+  }
+  const mode = wantPr ? 'pr' : 'merge';
+  const expectedBranch = buildBranchName(feature);
+
+  // ── Resolve the flow ──────────────────────────────────────────────────────
+  // findWorktreeForFeature matches ANY worktree on morph/{feature} — including
+  // the PRIMARY ROOT itself when the common flow checked the branch out there.
+  // A match whose path IS the root is the common flow (no separate worktree to
+  // tear down); a match elsewhere is the worktree flow.
+  const found = findWorktreeForFeature(feature, root);
+  const isWorktreeFlow = !!found && found.path.replace(/\\/g, '/') !== rootNorm;
+
+  let worktreePath = null;
+  let featureCwd = root; // where the feature's own tree (and Gate 3) lives
+
+  if (isWorktreeFlow) {
+    // Validation 0: the worktree must actually be ON the branch we will merge.
+    if (found.branch !== found.expectedBranch) {
+      emit({
+        finished: false,
+        error: 'worktree-branch-mismatch',
+        feature,
+        expectedBranch,
+        actualBranch: found.branch,
+        path: found.path,
+        hint: `o worktree em ${found.path} está em ${found.branch || 'HEAD destacado'}, não em ${expectedBranch}`,
+      });
+      process.exit(1);
+    }
+    worktreePath = found.path;
+    featureCwd = worktreePath;
+  } else {
+    // COMMON flow: the feature branch must exist and be the ROOT's current
+    // branch (so the archive commits on it and we can checkout the default to
+    // merge). A feature with NO morph/{f} branch was born before this flow —
+    // route it explicitly to archive-without-integrate, never a generic refusal.
+    if (!branchExists(expectedBranch, root)) {
+      emit({
+        finished: false,
+        error: 'no-feature-branch',
+        feature,
+        hint: `feature sem branch ${expectedBranch} (criada antes deste fluxo) — feche com \`morph-spec archive ${feature}\` (arquivar sem integrar), ou continue o trabalho numa branch`,
+      });
+      process.exit(1);
+    }
+    const current = currentBranch(root);
+    if (current !== expectedBranch) {
+      emit({
+        finished: false,
+        error: 'not-on-feature-branch',
+        feature,
+        currentBranch: current,
+        expectedBranch,
+        hint: `faça checkout de ${expectedBranch} antes do finish (\`git checkout ${expectedBranch}\`)`,
+      });
+      process.exit(1);
+    }
+    featureCwd = root;
+  }
+
+  // Validation 1: Gate 3 (review) approved on the feature's own feature.json.
+  const fj = readFeatureJson(featureCwd, feature);
+  if (!options.force && !(fj?.approvalGates?.review?.approved === true || fj?.approvals?.review?.approved === true)) {
+    emit({ finished: false, error: 'review-not-approved', feature });
+    process.exit(1);
+  }
+  const prTitle = `morph: ${feature}`;
+  const prBody = (fj?.description && String(fj.description).trim())
+    ? String(fj.description).trim()
+    : `Feature ${feature} — integrada via morph-spec finish --pr.`;
+
+  // Validation 2: the tree that will carry the archive commit must be clean
+  // (work committed), so the scoped archive commit contains only the move.
+  const cleanCwd = isWorktreeFlow ? worktreePath : root;
+  const dirty = gitStatusPorcelain(cleanCwd);
+  if (dirty === null) {
+    emit({ finished: false, error: 'status-failed', feature });
+    process.exit(1);
+  }
+  if (dirty.trim() !== '') {
+    emit({ finished: false, error: isWorktreeFlow ? 'worktree-dirty' : 'working-dir-dirty', hint: 'commit seu trabalho na branch antes do finish', feature });
+    process.exit(1);
+  }
+
+  // Default branch — needed as the merge target and the PR base. Never assume
+  // "master"; refuse clearly when it cannot be resolved.
+  const defaultBranch = detectDefaultBranch(root);
+  if (!defaultBranch) {
+    emit({ finished: false, error: 'no-default-branch', hint: 'não foi possível resolver a branch default (origin/HEAD, main ou master)', feature });
+    process.exit(1);
+  }
+  if (defaultBranch === expectedBranch) {
+    emit({ finished: false, error: 'feature-is-default', hint: `a branch da feature (${expectedBranch}) é a própria default — nada a integrar`, feature });
+    process.exit(1);
+  }
+
+  // ── PR preconditions run BEFORE the archive, so a refused --pr has NO side
+  //    effect (nothing archived, nothing committed). ─────────────────────────
+  if (mode === 'pr') {
+    if (!hasOriginRemote(root)) {
+      emit({ finished: false, error: 'no-origin-remote', hint: 'não há remoto `origin` para abrir PR — configure um ou use --merge', feature });
+      process.exit(1);
+    }
+    if (!ghAuthOk()) {
+      emit({ finished: false, error: 'gh-unavailable', hint: '`gh` não está instalado/autenticado — rode `gh auth login` ou use --merge', feature });
+      process.exit(1);
+    }
+  }
+
+  // ── ARCHIVE (inside morph/{f}) ────────────────────────────────────────────
+  const arch = runArchive(feature, { cwd: featureCwd, force: options.force, git: true });
+  if (!arch.ok) {
+    emit({ finished: false, error: `archive-${arch.error}`, feature });
+    process.exit(1);
+  }
+  // A move that could not be committed (e.g. missing git identity) would leave
+  // the tree dirty and break the checkout/merge below — refuse, recoverable.
+  if (arch.archived && !arch.committed) {
+    emit({ finished: false, error: 'archive-not-committed', hint: 'o move de archive não pôde ser commitado (identidade git ausente?)', feature });
+    process.exit(1);
+  }
+
+  // ── INTEGRATE ─────────────────────────────────────────────────────────────
+  if (mode === 'merge') {
+    return integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch });
+  }
+  return integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch });
+}
+
+// ── merge integration (local, no push) ───────────────────────────────────────
+
+async function integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch }) {
+  const mergeMsg = `morph-spec finish: merge ${expectedBranch}`;
+
+  if (isWorktreeFlow) {
+    // The root stays on the default; shed this feature's own root-side scaffold,
+    // then guard the whole root before landing the merge commit.
+    const { shedBackup } = shedRootFeatureScope(root, feature);
+    const backupNote = shedBackup ? { shedBackup } : {};
+
+    const rootClean = primaryRootUnexplainedDirt(root, feature);
+    if (!rootClean.ok) {
+      emit({ finished: false, error: 'primary-root-status-failed', feature, ...backupNote });
+      process.exit(1);
+    }
+    if (rootClean.dirt.length) {
+      emit({ finished: false, error: 'primary-root-dirty', feature, ...backupNote });
+      process.exit(1);
+    }
+
+    try {
+      execFileSync('git', ['merge', '--no-ff', expectedBranch, '-m', mergeMsg], { cwd: root, stdio: 'pipe' });
+    } catch (err) {
+      tryGit(['merge', '--abort'], root);
+      emit({ finished: false, error: 'merge-conflict', output: gitErr(err), hint: 'resolva manualmente ou re-execute sequencialmente', feature, ...backupNote });
+      process.exit(1);
+    }
+
+    if (options.keep) {
+      dropFromRootIndex(root, feature);
+      emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false, ...backupNote });
+      process.exit(0);
+    }
+
+    const teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: true });
+    dropFromRootIndex(root, feature);
+    emit(mergeOutput({ feature, branch: expectedBranch, worktreePath, teardown, shedBackup }));
+    process.exit(0);
+  }
+
+  // COMMON flow: we are on morph/{f} in the root, archive committed. Move to the
+  // default and merge the feature branch in.
+  try {
+    execFileSync('git', ['checkout', defaultBranch], { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    emit({ finished: false, error: 'checkout-default-failed', output: gitErr(err), hint: `não foi possível trocar para ${defaultBranch}`, feature });
+    process.exit(1);
+  }
+  try {
+    execFileSync('git', ['merge', '--no-ff', expectedBranch, '-m', mergeMsg], { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    tryGit(['merge', '--abort'], root);
+    emit({
+      finished: false,
+      error: 'merge-conflict',
+      output: gitErr(err),
+      // The abort left the working dir on the default WITHOUT the feature — say
+      // where the intact work is so the user can recover it.
+      hint: `conflito ao mergear ${expectedBranch} em ${defaultBranch}. Seu trabalho está intacto em ${expectedBranch} — rode \`git checkout ${expectedBranch}\` para voltar a ele`,
+      feature,
+    });
+    process.exit(1);
+  }
+  tryGit(['branch', '-d', expectedBranch], root);
+  // The root index (gitignored) was already updated by the archive (same cwd).
+  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: null });
+  process.exit(0);
+}
+
+// ── PR integration (push + gh, no local merge) ───────────────────────────────
+
+async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody }) {
+  try {
+    execFileSync('git', ['push', '-u', 'origin', expectedBranch], { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    emit({ finished: false, error: 'push-failed', output: gitErr(err), hint: 'o archive está commitado localmente — resolva o push e re-execute', feature });
+    process.exit(1);
+  }
+
+  let prUrl = null;
+  try {
+    const { bin, prefix } = resolveGh();
+    prUrl = execFileSync(bin, [...prefix, 'pr', 'create', '--base', defaultBranch, '--head', expectedBranch, '--title', prTitle, '--body', prBody], { cwd: root, stdio: 'pipe' }).toString().trim();
+  } catch (err) {
+    emit({ finished: false, error: 'pr-create-failed', output: gitErr(err), hint: 'a branch foi enviada (push OK); abra o PR manualmente com `gh pr create`', feature, pushed: expectedBranch });
+    process.exit(1);
+  }
+
+  // Worktree flow: remove the worktree but KEEP the branch (the open PR needs it).
+  // Common flow: nothing to tear down; stay on morph/{f} (the default has no
+  // feature yet — honest until the PR merges).
+  let teardown = null;
+  let shedBackup = null;
+  if (isWorktreeFlow && !options.keep) {
+    // Shed the transient root-side scaffold BEFORE teardown — exactly as --merge
+    // does. The real `create --worktree` leaves the root's .morph/features/{f}
+    // UNTRACKED; without this, teardown's clearRootWorktreeRegistration would
+    // `git add` + commit that scaffold onto the default branch. Then when the PR
+    // later merges (carrying features/{f} → archive/{f}), the default would hold
+    // the feature in BOTH features/ and archive/ at once — active and archived.
+    // The branch/PR owns the authoritative copy; the root scaffold is transient.
+    shedBackup = shedRootFeatureScope(root, feature).shedBackup;
+    teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: false });
+    // The shed removed the root's features/{f} scaffold from disk, but runArchive
+    // dropped the feature only from the WORKTREE's index (its cwd). Drop it from
+    // the ROOT index too — exactly as --merge does — or `doctor`'s lifecycle audit
+    // flags a `stale-index` phantom (index lists {f}, no folder on disk).
+    dropFromRootIndex(root, feature);
+  }
+
+  const out = {
+    finished: true,
+    mode: 'pr',
+    feature,
+    pushed: expectedBranch,
+    base: defaultBranch,
+    pr: prUrl,
+    ...(shedBackup ? { shedBackup } : {}),
+    ...(teardown
+      ? { worktreeRemoved: teardown.worktreeRemoved, ...teardownExtras(teardown, worktreePath, expectedBranch, false) }
+      : { worktreeRemoved: false }),
+  };
+  emit(out);
+  process.exit(0);
+}
+
+// ── output helpers ────────────────────────────────────────────────────────
+
+function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
+  return {
+    finished: true,
+    mode: 'merge',
+    feature,
+    merged: branch,
+    worktreeRemoved: teardown.worktreeRemoved,
+    ...(shedBackup ? { shedBackup } : {}),
+    ...teardownExtras(teardown, worktreePath, branch, true),
+  };
+}
+
+/** Shared teardown reporting for both modes (kept identical to the old finish). */
+function teardownExtras(teardown, worktreePath, branch, deleteBranch) {
+  const out = {};
+  if (teardown.ignoredBackup) out.worktreeIgnoredBackup = teardown.ignoredBackup;
+  if (teardown.worktreeRemoved && teardown.discarded.length) out.discardedIgnored = teardown.discarded;
+  if (!teardown.worktreeRemoved) {
+    out.path = worktreePath;
+    out.branch = branch;
+    if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
+    if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
+    out.cleanupHint = teardown.declineReason;
+    out.relinkHint = `as junctions de infra foram soltas antes desta recusa — para continuar no worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``;
+  }
+  return out;
+}
+
+// ── small git helpers ────────────────────────────────────────────────────────
+
+function currentBranch(cwd) {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+function gitStatusPorcelain(cwd) {
+  try {
+    return execFileSync('git', ['status', '--porcelain'], { cwd, stdio: 'pipe' }).toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the `gh` invocation. Defaults to the `gh` binary on PATH. Overridable
+ * via MORPH_GH_BIN: a plain string names a different binary (a corporate wrapper,
+ * `hub`, …); a JSON array is a full argv prefix — e.g.
+ * `["/path/to/node","/path/to/gh-shim.js"]` — which is how the tests inject a
+ * cross-platform stub that execFileSync can actually spawn (Node ≥20 refuses to
+ * run `.cmd`/`.bat` shims without `shell:true`, and shell:true would reopen the
+ * arg-injection hole the whole file avoids).
+ *
+ * @returns {{ bin: string, prefix: string[] }}
+ */
+function resolveGh() {
+  const raw = process.env.MORPH_GH_BIN;
+  if (raw && raw.trim().startsWith('[')) {
+    try {
+      const arr = JSON.parse(raw);
+      if (Array.isArray(arr) && arr.length) return { bin: String(arr[0]), prefix: arr.slice(1).map(String) };
+    } catch { /* not JSON — treat as a plain binary name below */ }
+  }
+  return { bin: raw && raw.trim() ? raw.trim() : 'gh', prefix: [] };
+}
+
+function ghAuthOk() {
+  const { bin, prefix } = resolveGh();
+  try {
+    execFileSync(bin, [...prefix, 'auth', 'status'], { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function tryGit(args, cwd) {
+  try { execFileSync('git', args, { cwd, stdio: 'pipe' }); } catch { /* best-effort */ }
+}
+
+function gitErr(err) {
+  return (((err.stdout && err.stdout.toString()) || '') + ((err.stderr && err.stderr.toString()) || '')).slice(0, 2000) || (err.message || '').slice(0, 500);
+}
+
+function readFeatureJson(cwd, feature) {
+  try {
+    return JSON.parse(readFileSync(join(cwd, '.morph', 'features', feature, 'feature.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Drop a feature from the thin, gitignored root index (never via saveState). */
+function dropFromRootIndex(root, feature) {
+  const rootPath = join(root, '.morph', 'state.json');
+  if (!existsSync(rootPath)) return;
+  try {
+    const idx = JSON.parse(readFileSync(rootPath, 'utf8'));
+    if (idx.features && idx.features[feature]) {
+      delete idx.features[feature];
+      idx.metadata = idx.metadata || {};
+      idx.metadata.totalFeatures = Object.keys(idx.features).length;
+      writeFileSync(rootPath, JSON.stringify(idx, null, 2), 'utf8');
+    }
+  } catch { /* index is derivable — non-fatal */ }
+}

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