@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

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

@@ -12,6 +12,9 @@
  *                     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
  */
 
@@ -20,6 +23,8 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
 import { gateOrderViolations } from './gate-order.js';
 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) {
@@ -72,6 +77,125 @@ 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.
+ */
+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]) {
+    const t = ts ? Date.parse(ts) : NaN;
+    if (!Number.isNaN(t)) newest = Math.max(newest, t);
+  }
+  if (newest) return newest;
+  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.
+ */
+function hasArtifacts(fdir) {
+  let entries;
+  try { entries = readdirSync(fdir, { withFileTypes: true }); } catch { return false; }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (hasArtifacts(join(fdir, e.name))) return true;
+      continue;
+    }
+    if (e.name === 'feature.json') continue;
+    return true;
+  }
+  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.
+ */
+function ownCommitCount(baseDir, branch) {
+  try {
+    execFileSync('git', ['rev-parse', '--git-dir'], { cwd: baseDir, stdio: 'pipe' });
+  } catch {
+    return null;
+  }
+  const baseRef = resolveBaseRef(detectDefaultBranch(baseDir), baseDir);
+  if (!baseRef) return null;
+  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 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.
+  const decided = Object.values(fj.approvalGates || {}).some(
+    (g) => g?.approved === true && !String(g?.approvedBy ?? '').startsWith('policy:'),
+  );
+  if (decided) return null;
+
+  if (hasArtifacts(fdir)) return null;
+  const wtFeatureDir = fj.worktree?.path
+    ? join(fj.worktree.path, '.morph', 'features', feature)
+    : null;
+  if (wtFeatureDir && existsSync(wtFeatureDir) && hasArtifacts(wtFeatureDir)) return null;
+
+  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;
+
+  const days = Math.floor(age / (24 * 60 * 60 * 1000));
+  return `in_progress há ${days}d sem nada produzido: 0 artefatos, 0 gates aprovados `
+    + `e \`${branch}\` sem commit próprio — rode \`morph-spec delete ${feature} --archive\` `
+    + 'ou retome a feature';
+}
+
 /**
  * @param {string} [baseDir] - project root (defaults to cwd)
  * @returns {Array<{ feature: string, type: string, detail: string }>} issues
@@ -106,6 +230,9 @@ export function auditFeatureLifecycle(baseDir = process.cwd()) {
       const drift = branchDrift(baseDir, name, fj);
       if (drift) issues.push({ feature: name, type: 'branch-drift', detail: drift });
 
+      const dead = abandonedScaffold(baseDir, name, fdir, fj);
+      if (dead) issues.push({ feature: name, type: 'abandoned-scaffold', detail: dead });
+
       const miss = missingIdentity(fj);
       if (miss.length) {
         issues.push({ feature: name, type: 'identity', detail: `missing ${miss.join(', ')}` });

package/src/core/state/phase-state-machine.js

@@ -1,197 +1,197 @@
-/**
- * Phase State Machine - Enforces valid phase transitions
- *
- * Prevents invalid workflow jumps and ensures sequential phase progression.
- * Based on the MORPH 5-phase workflow.
- */
-
-/**
- * Valid phase transitions map
- * Each phase can only transition to specific next phases
- */
-const VALID_TRANSITIONS = {
-  'proposal': ['uiux', 'plan'],
-  'uiux': ['plan'],
-  'plan': ['implement'],
-  'implement': ['review'],
-  'review': []
-};
-
-/**
- * Phase display names for error messages
- */
-const PHASE_NAMES = {
-  'proposal': 'Proposal (Phase 0)',
-  'uiux': 'UI/UX Design (Phase 1)',
-  'plan': 'Plan (Phase 2)',
-  'implement': 'Implement (Phase 3)',
-  'review': 'Quality Review (Phase 4)'
-};
-
-/**
- * Optional phases that can be skipped
- */
-const OPTIONAL_PHASES = ['uiux'];
-
-/**
- * Validate if a phase transition is allowed
- * @param {string} fromPhase - Current phase
- * @param {string} toPhase - Target phase
- * @returns {boolean} True if transition is valid
- */
-export function isValidTransition(fromPhase, toPhase) {
-  if (!fromPhase || !toPhase) {
-    return false;
-  }
-
-  const validNextPhases = VALID_TRANSITIONS[fromPhase];
-  return validNextPhases ? validNextPhases.includes(toPhase) : false;
-}
-
-/**
- * Get list of valid next phases for a given phase
- * @param {string} currentPhase - Current phase
- * @returns {string[]} Array of valid next phase names
- */
-export function getValidNextPhases(currentPhase) {
-  return VALID_TRANSITIONS[currentPhase] || [];
-}
-
-/**
- * Get display name for a phase
- * @param {string} phase - Phase identifier
- * @returns {string} Human-readable phase name
- */
-export function getPhaseDisplayName(phase) {
-  return PHASE_NAMES[phase] || phase;
-}
-
-/**
- * Check if a phase is optional
- * @param {string} phase - Phase identifier
- * @returns {boolean} True if phase is optional
- */
-export function isOptionalPhase(phase) {
-  return OPTIONAL_PHASES.includes(phase);
-}
-
-/**
- * Validate transition and throw error if invalid
- * @param {string} fromPhase - Current phase
- * @param {string} toPhase - Target phase
- * @throws {Error} If transition is invalid
- */
-export function validateTransition(fromPhase, toPhase) {
-  if (!fromPhase) {
-    throw new Error('Current phase is undefined. Cannot validate transition.');
-  }
-
-  if (!toPhase) {
-    throw new Error('Target phase is undefined. Cannot validate transition.');
-  }
-
-  if (!isValidTransition(fromPhase, toPhase)) {
-    const validPhases = getValidNextPhases(fromPhase);
-    const fromDisplay = getPhaseDisplayName(fromPhase);
-    const toDisplay = getPhaseDisplayName(toPhase);
-
-    throw new Error(
-      `Invalid phase transition: ${fromDisplay} → ${toDisplay}\n\n` +
-      `Valid next phases from ${fromDisplay}:\n` +
-      validPhases.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
-      '\n\n' +
-      'You cannot skip phases in the MORPH workflow.\n' +
-      'To override this check, use the --force flag (not recommended).'
-    );
-  }
-}
-
-/**
- * Get the sequential order of phases
- * @returns {string[]} Ordered list of phases
- */
-export function getPhaseSequence() {
-  return ['proposal', 'uiux', 'plan', 'implement', 'review'];
-}
-
-/**
- * Get phase order index (for comparison)
- * @param {string} phase - Phase identifier
- * @returns {number} Index in sequence (-1 if not found)
- */
-export function getPhaseOrder(phase) {
-  return getPhaseSequence().indexOf(phase);
-}
-
-/**
- * Check if target phase is ahead of current phase
- * @param {string} currentPhase - Current phase
- * @param {string} targetPhase - Target phase
- * @returns {boolean} True if target is ahead
- */
-export function isPhaseAhead(currentPhase, targetPhase) {
-  return getPhaseOrder(targetPhase) > getPhaseOrder(currentPhase);
-}
-
-/**
- * Check if target phase is behind current phase (rollback scenario)
- * @param {string} currentPhase - Current phase
- * @param {string} targetPhase - Target phase
- * @returns {boolean} True if target is behind
- */
-export function isPhaseRollback(currentPhase, targetPhase) {
-  return getPhaseOrder(targetPhase) < getPhaseOrder(currentPhase);
-}
-
-/**
- * Get all skipped phases between two phases
- * @param {string} fromPhase - Starting phase
- * @param {string} toPhase - Ending phase
- * @returns {string[]} Array of skipped phases
- */
-export function getSkippedPhases(fromPhase, toPhase) {
-  const sequence = getPhaseSequence();
-  const fromIndex = sequence.indexOf(fromPhase);
-  const toIndex = sequence.indexOf(toPhase);
-
-  if (fromIndex === -1 || toIndex === -1 || toIndex <= fromIndex) {
-    return [];
-  }
-
-  return sequence.slice(fromIndex + 1, toIndex);
-}
-
-/**
- * Validate that no required phases were skipped
- * @param {string} fromPhase - Starting phase
- * @param {string} toPhase - Ending phase
- * @throws {Error} If required phases were skipped
- */
-export function validateNoRequiredPhasesSkipped(fromPhase, toPhase) {
-  const skipped = getSkippedPhases(fromPhase, toPhase);
-  const requiredSkipped = skipped.filter(p => !isOptionalPhase(p));
-
-  if (requiredSkipped.length > 0) {
-    throw new Error(
-      `Cannot skip required phases:\n` +
-      requiredSkipped.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
-      '\n\nYou must complete each required phase in sequence.'
-    );
-  }
-}
-
-/**
- * Get comprehensive phase information
- * @param {string} phase - Phase identifier
- * @returns {Object} Phase metadata
- */
-export function getPhaseInfo(phase) {
-  return {
-    id: phase,
-    displayName: getPhaseDisplayName(phase),
-    order: getPhaseOrder(phase),
-    isOptional: isOptionalPhase(phase),
-    validNextPhases: getValidNextPhases(phase),
-    canTransitionTo: (targetPhase) => isValidTransition(phase, targetPhase)
-  };
-}
+/**
+ * Phase State Machine - Enforces valid phase transitions
+ *
+ * Prevents invalid workflow jumps and ensures sequential phase progression.
+ * Based on the MORPH 5-phase workflow.
+ */
+
+/**
+ * Valid phase transitions map
+ * Each phase can only transition to specific next phases
+ */
+const VALID_TRANSITIONS = {
+  'proposal': ['uiux', 'plan'],
+  'uiux': ['plan'],
+  'plan': ['implement'],
+  'implement': ['review'],
+  'review': []
+};
+
+/**
+ * Phase display names for error messages
+ */
+const PHASE_NAMES = {
+  'proposal': 'Proposal (Phase 0)',
+  'uiux': 'UI/UX Design (Phase 1)',
+  'plan': 'Plan (Phase 2)',
+  'implement': 'Implement (Phase 3)',
+  'review': 'Quality Review (Phase 4)'
+};
+
+/**
+ * Optional phases that can be skipped
+ */
+const OPTIONAL_PHASES = ['uiux'];
+
+/**
+ * Validate if a phase transition is allowed
+ * @param {string} fromPhase - Current phase
+ * @param {string} toPhase - Target phase
+ * @returns {boolean} True if transition is valid
+ */
+export function isValidTransition(fromPhase, toPhase) {
+  if (!fromPhase || !toPhase) {
+    return false;
+  }
+
+  const validNextPhases = VALID_TRANSITIONS[fromPhase];
+  return validNextPhases ? validNextPhases.includes(toPhase) : false;
+}
+
+/**
+ * Get list of valid next phases for a given phase
+ * @param {string} currentPhase - Current phase
+ * @returns {string[]} Array of valid next phase names
+ */
+export function getValidNextPhases(currentPhase) {
+  return VALID_TRANSITIONS[currentPhase] || [];
+}
+
+/**
+ * Get display name for a phase
+ * @param {string} phase - Phase identifier
+ * @returns {string} Human-readable phase name
+ */
+export function getPhaseDisplayName(phase) {
+  return PHASE_NAMES[phase] || phase;
+}
+
+/**
+ * Check if a phase is optional
+ * @param {string} phase - Phase identifier
+ * @returns {boolean} True if phase is optional
+ */
+export function isOptionalPhase(phase) {
+  return OPTIONAL_PHASES.includes(phase);
+}
+
+/**
+ * Validate transition and throw error if invalid
+ * @param {string} fromPhase - Current phase
+ * @param {string} toPhase - Target phase
+ * @throws {Error} If transition is invalid
+ */
+export function validateTransition(fromPhase, toPhase) {
+  if (!fromPhase) {
+    throw new Error('Current phase is undefined. Cannot validate transition.');
+  }
+
+  if (!toPhase) {
+    throw new Error('Target phase is undefined. Cannot validate transition.');
+  }
+
+  if (!isValidTransition(fromPhase, toPhase)) {
+    const validPhases = getValidNextPhases(fromPhase);
+    const fromDisplay = getPhaseDisplayName(fromPhase);
+    const toDisplay = getPhaseDisplayName(toPhase);
+
+    throw new Error(
+      `Invalid phase transition: ${fromDisplay} → ${toDisplay}\n\n` +
+      `Valid next phases from ${fromDisplay}:\n` +
+      validPhases.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
+      '\n\n' +
+      'You cannot skip phases in the MORPH workflow.\n' +
+      'To override this check, use the --force flag (not recommended).'
+    );
+  }
+}
+
+/**
+ * Get the sequential order of phases
+ * @returns {string[]} Ordered list of phases
+ */
+export function getPhaseSequence() {
+  return ['proposal', 'uiux', 'plan', 'implement', 'review'];
+}
+
+/**
+ * Get phase order index (for comparison)
+ * @param {string} phase - Phase identifier
+ * @returns {number} Index in sequence (-1 if not found)
+ */
+export function getPhaseOrder(phase) {
+  return getPhaseSequence().indexOf(phase);
+}
+
+/**
+ * Check if target phase is ahead of current phase
+ * @param {string} currentPhase - Current phase
+ * @param {string} targetPhase - Target phase
+ * @returns {boolean} True if target is ahead
+ */
+export function isPhaseAhead(currentPhase, targetPhase) {
+  return getPhaseOrder(targetPhase) > getPhaseOrder(currentPhase);
+}
+
+/**
+ * Check if target phase is behind current phase (rollback scenario)
+ * @param {string} currentPhase - Current phase
+ * @param {string} targetPhase - Target phase
+ * @returns {boolean} True if target is behind
+ */
+export function isPhaseRollback(currentPhase, targetPhase) {
+  return getPhaseOrder(targetPhase) < getPhaseOrder(currentPhase);
+}
+
+/**
+ * Get all skipped phases between two phases
+ * @param {string} fromPhase - Starting phase
+ * @param {string} toPhase - Ending phase
+ * @returns {string[]} Array of skipped phases
+ */
+export function getSkippedPhases(fromPhase, toPhase) {
+  const sequence = getPhaseSequence();
+  const fromIndex = sequence.indexOf(fromPhase);
+  const toIndex = sequence.indexOf(toPhase);
+
+  if (fromIndex === -1 || toIndex === -1 || toIndex <= fromIndex) {
+    return [];
+  }
+
+  return sequence.slice(fromIndex + 1, toIndex);
+}
+
+/**
+ * Validate that no required phases were skipped
+ * @param {string} fromPhase - Starting phase
+ * @param {string} toPhase - Ending phase
+ * @throws {Error} If required phases were skipped
+ */
+export function validateNoRequiredPhasesSkipped(fromPhase, toPhase) {
+  const skipped = getSkippedPhases(fromPhase, toPhase);
+  const requiredSkipped = skipped.filter(p => !isOptionalPhase(p));
+
+  if (requiredSkipped.length > 0) {
+    throw new Error(
+      `Cannot skip required phases:\n` +
+      requiredSkipped.map(p => `  • ${getPhaseDisplayName(p)}`).join('\n') +
+      '\n\nYou must complete each required phase in sequence.'
+    );
+  }
+}
+
+/**
+ * Get comprehensive phase information
+ * @param {string} phase - Phase identifier
+ * @returns {Object} Phase metadata
+ */
+export function getPhaseInfo(phase) {
+  return {
+    id: phase,
+    displayName: getPhaseDisplayName(phase),
+    order: getPhaseOrder(phase),
+    isOptional: isOptionalPhase(phase),
+    validNextPhases: getValidNextPhases(phase),
+    canTransitionTo: (targetPhase) => isValidTransition(phase, targetPhase)
+  };
+}