@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

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

@@ -1,44 +1,16 @@
-/**
- * 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'],
+  plan: [],
+  uiux: ['plan'],
   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 = [];

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

@@ -1,23 +1,3 @@
-/**
- * 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)
- *   • branch-drift  — the root's copy of a feature.json disagrees with the copy
- *                     committed on `morph/{f}` (B5 — the root's view lags)
- *   • abandoned-scaffold — an `in_progress` feature that never produced
- *                     anything: no artifacts, no approved gate, and a branch
- *                     with no commit of its own (see abandonedScaffold)
- *   • corrupt       — a feature.json that won't parse
- */
-
 import { execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
@@ -26,40 +6,19 @@ import { missingIdentity } from './feature-identity.js';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
 import { commitsAhead, resolveBaseRef } from '../../lib/git/branch-classifier.js';
 
-/** The operational truth of a feature.json: its status and which gates are approved. */
 function operationalShape(fj) {
   const gates = {};
   for (const [g, v] of Object.entries(fj?.approvalGates || {})) gates[g] = v?.approved === true;
   return JSON.stringify({ status: fj?.status ?? null, gates });
 }
 
-/**
- * Does the root's working-tree copy of a feature.json disagree with the copy
- * COMMITTED on that feature's own branch?
- *
- * `.morph/state.json` is gitignored and derived, and every worktree keeps its
- * own — so "the index diverges between worktrees" is by design, not a defect to
- * fix by making the index authoritative (that would undo the whole per-feature
- * state model). The defect is that the divergence was INVISIBLE: since v8.4 the
- * authoritative feature.json travels committed on `morph/{f}`, so a primary root
- * parked on the default holds a copy that silently lags, and everything derived
- * from it (status, gates, and the index rebuilt from it) lags with it.
- *
- * Comparison is on the OPERATIONAL fields only — status and approved-gate flags
- * — not on bytes: reformatting or a timestamp bump is not a divergence anyone
- * needs to hear about.
- *
- * Fail-open at every step: no repo, no branch, no blob, unparseable JSON → no
- * issue. A diagnostic that invents problems is worse than one that misses some.
- *
- * @returns {string|null} the issue detail, or null when the copies agree
- */
+// Compares only status and approved gates (bytes and timestamps are not drift).
+// Fail-open: no repo, branch, blob or parseable JSON means no issue.
 function branchDrift(baseDir, feature, rootFj) {
   const branch = `morph/${feature}`;
   try {
     const current = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: baseDir, stdio: 'pipe' })
       .toString().trim();
-    // On the feature's own branch the working tree IS the branch — nothing to compare.
     if (current === branch) return null;
 
     execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: baseDir, stdio: 'pipe' });
@@ -77,18 +36,9 @@ function branchDrift(baseDir, feature, rootFj) {
   }
 }
 
-/**
- * How long a scaffold has to sit untouched before it counts as abandoned.
- *
- * A dead scaffold and a feature born five minutes ago have the SAME shape:
- * `create` forks `morph/{f}` off the default branch without committing, so at
- * birth the branch has no commit of its own and the folder holds nothing but
- * `feature.json`. Only elapsed time separates the two — and a check that fires
- * on every fresh `create` is one people learn to scroll past.
- */
+// A dead scaffold and a feature born minutes ago have the same shape; only age tells them apart.
 const ABANDONED_SCAFFOLD_MIN_AGE_MS = 24 * 60 * 60 * 1000;
 
-/** Newest timestamp the feature carries, in ms; falls back to the folder's mtime. */
 function lastTouched(fdir, fj) {
   let newest = 0;
   for (const ts of [fj?.updatedAt, fj?.createdAt]) {
@@ -99,12 +49,7 @@ function lastTouched(fdir, fj) {
   try { return statSync(fdir).mtimeMs; } catch { return 0; }
 }
 
-/**
- * Does the feature dir hold any FILE other than its own `feature.json`?
- *
- * Files, not entries: `create` scaffolds the phase folders empty, so an empty
- * `0-proposal/` is the absence of work, not evidence of it.
- */
+// Files, not entries: `create` scaffolds the phase folders empty.
 function hasArtifacts(fdir) {
   let entries;
   try { entries = readdirSync(fdir, { withFileTypes: true }); } catch { return false; }
@@ -119,22 +64,7 @@ function hasArtifacts(fdir) {
   return false;
 }
 
-/**
- * Commits on the feature's branch that the base does not already contain, or
- * `null` when git cannot answer (no repo, no resolvable base, no branch, no
- * rev-list). "Cannot prove" must never read as "proved zero" — the predicate
- * below hinges on this number, so an unanswerable repo has to stay silent.
- *
- * The counting itself is `branch-classifier.js`'s `commitsAhead` against its
- * `resolveBaseRef`, NOT a second copy: `origin/{default}` is the authority on
- * what actually landed, and two drifting answers to "does this branch carry
- * anything of its own?" is exactly what the `doctor`/`branch prune` split was
- * unified to avoid.
- *
- * Note the field evidence this exists for: the branch pointed at the merge
- * commit of somebody else's PR. That is the base's own tip — reachable from
- * the base, and therefore zero commits of its own.
- */
+// `null` when git cannot answer: "cannot prove" must never read as "proved zero".
 function ownCommitCount(baseDir, branch) {
   try {
     execFileSync('git', ['rev-parse', '--git-dir'], { cwd: baseDir, stdio: 'pipe' });
@@ -146,31 +76,15 @@ function ownCommitCount(baseDir, branch) {
   try {
     execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: baseDir, stdio: 'pipe' });
   } catch {
-    return 0; // the branch never existed — nothing was ever committed for it
+    return 0; // the branch never existed: nothing was committed on it
   }
   return commitsAhead(baseRef, branch, baseDir);
 }
 
-/**
- * The orphan skeleton `create --worktree` can leave behind: a feature.json on
- * its own, `status: in_progress`, no tasks, no gates, and a branch parked on
- * somebody else's commit. Every one of those alone is normal at some point in
- * a feature's life; together, and only after the feature has gone stale, they
- * mean nobody ever came back to it.
- *
- * The artifact test is deliberately broader than the "0 tasks" the report
- * named: a proposal drafted and waiting on Gate 1 also has zero tasks and is
- * very much alive. What a dead scaffold has is NOTHING — checked in the root
- * and, if the feature registered one, in its worktree, where uncommitted work
- * would otherwise be invisible to both the disk scan and `rev-list`.
- *
- * @returns {string|null} the issue detail, or null when the feature is alive
- */
 function abandonedScaffold(baseDir, feature, fdir, fj) {
   if (fj?.status !== 'in_progress') return null;
 
-  // "0 gates": a gate stamped `policy:{workType}` at birth (chore/hotfix) was
-  // never a decision anyone took, so it must not read as progress.
+  // A gate stamped `policy:{workType}` at birth was never a decision, so it is not progress.
   const decided = Object.values(fj.approvalGates || {}).some(
     (g) => g?.approved === true && !String(g?.approvedBy ?? '').startsWith('policy:'),
   );
@@ -185,8 +99,6 @@ function abandonedScaffold(baseDir, feature, fdir, fj) {
   const age = Date.now() - lastTouched(fdir, fj);
   if (age < ABANDONED_SCAFFOLD_MIN_AGE_MS) return null;
 
-  // The registered branch when the feature has one, `morph/{f}` otherwise —
-  // same name `branchDrift` above assumes.
   const branch = fj.worktree?.branch || `morph/${feature}`;
   if (ownCommitCount(baseDir, branch) !== 0) return null;
 
@@ -196,10 +108,6 @@ function abandonedScaffold(baseDir, feature, fdir, fj) {
     + 'ou retome a feature';
 }
 
-/**
- * @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');
@@ -256,7 +164,7 @@ export function auditFeatureLifecycle(baseDir = process.cwd()) {
           issues.push({ feature: name, type: 'stale-index', detail: 'in state.json index but no feature folder' });
         }
       }
-    } catch { /* index is derivable — non-fatal */ }
+    } catch { }
   }
 
   return issues;