@polymorphism-tech/morph-spec 7.8.1 → 7.9.0

package/src/commands/state/gate-decision.js

@@ -0,0 +1,99 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { getFeature, updateFeature } from '../../core/state/state-manager.js';
+
+const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
+
+function parsePauseValue(raw) {
+  const v = String(raw).toLowerCase();
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  console.error(chalk.red(`\n❌ Invalid --pause: "${raw}" — expected true or false\n`));
+  process.exit(1);
+}
+
+/** trust from the committed config (BOM-tolerant), defaulting to "auto". */
+function readTrustFromConfig() {
+  try {
+    const path = join(process.cwd(), '.morph', 'config', 'config.json');
+    if (!existsSync(path)) return 'auto';
+    const raw = readFileSync(path, 'utf8').replace(/^/, '');
+    return JSON.parse(raw).trust || 'auto';
+  } catch {
+    return 'auto';
+  }
+}
+
+/**
+ * `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>]
+ * [--signals <json>] [--trust <mode>]` — record the trust decision for a gate
+ * under `gateDecisions` in the authoritative feature.json.
+ *
+ * Same philosophy as `morph-spec score`: the timestamp (`decidedAt`) is
+ * stamped server-side and the write is atomic (state-manager). This replaces
+ * the manual Edit of feature.json from the skills — which collided with the
+ * state-sync hook rewriting the file between the agent's Read and Edit
+ * ("file modified since read"). The canonical shape is documented in
+ * framework/schemas/feature.schema.json and consumed by gate-guard.js.
+ */
+export async function gateDecisionCommand(featureName, gateName, options = {}) {
+  try {
+    if (!VALID_GATES.includes(gateName)) {
+      console.error(chalk.red(`\n❌ Invalid gate: ${gateName}`));
+      console.error(chalk.gray(`Valid gates: ${VALID_GATES.join(', ')}\n`));
+      process.exit(1);
+    }
+
+    if (options.pause === undefined) {
+      console.error(chalk.red('\n❌ --pause is required (true or false)\n'));
+      process.exit(1);
+    }
+    const pause = parsePauseValue(options.pause);
+
+    const feature = getFeature(featureName);
+    if (!feature) {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+      process.exit(1);
+    }
+
+    let signals = {};
+    if (options.signals !== undefined) {
+      try {
+        signals = JSON.parse(options.signals);
+      } catch (err) {
+        console.error(chalk.red(`\n❌ Invalid --signals: not valid JSON (${err.message})\n`));
+        process.exit(1);
+      }
+      if (!signals || typeof signals !== 'object' || Array.isArray(signals)) {
+        console.error(chalk.red('\n❌ Invalid --signals: expected a JSON object, e.g. \'{"taskCount":12}\'\n'));
+        process.exit(1);
+      }
+    }
+
+    const entry = {
+      pause,
+      reason: options.reason || (pause ? 'risco detectado' : 'nenhum sinal de risco'),
+      signals,
+      trust: options.trust || readTrustFromConfig(),
+      decidedAt: new Date().toISOString(),
+    };
+
+    await updateFeature(featureName, `gateDecisions.${gateName}`, entry);
+
+    if (options.json) {
+      console.log(JSON.stringify({ feature: featureName, gate: gateName, ...entry }, null, 2));
+      return;
+    }
+
+    console.log(chalk.green(`\n✅ Gate decision recorded: ${featureName}/${gateName} → pause: ${entry.pause}`));
+    console.log(chalk.gray(`   reason: ${entry.reason} | trust: ${entry.trust} | decidedAt: ${entry.decidedAt}`));
+    if (Object.keys(entry.signals).length > 0) {
+      console.log(chalk.gray(`   signals: ${JSON.stringify(entry.signals)}`));
+    }
+    console.log('');
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error recording gate decision: ${error.message}\n`));
+    process.exit(1);
+  }
+}

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

package/src/core/state/state-manager.js

@@ -484,6 +484,61 @@ async function ensureFeature(featureName) {
   return state.features[featureName];
 }
 
+/**
+ * Explicitly create a feature with the canonical shape (documented in
+ * framework/schemas/feature.schema.json). Idempotent: an existing feature is
+ * returned untouched. This is the server-side birth path behind
+ * `morph-spec create` — replacing the implicit registration on the first
+ * Write into .morph/features/ (the state-sync hook remains as fallback).
+ *
+ * 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 }} [options]
+ * @returns {Promise<{ feature: Object, created: boolean }>}
+ */
+export async function createFeature(featureName, options = {}) {
+  const { status = 'in_progress' } = options;
+  const state = loadState(false) || scaffoldState();
+
+  const existing = state.features[featureName];
+  if (existing) {
+    return { feature: existing, created: false };
+  }
+
+  const now = new Date().toISOString();
+  state.features[featureName] = {
+    status,
+    createdAt: now,
+    updatedAt: now,
+    activeAgents: [],
+    approvalGates: {
+      proposal: { approved: false, timestamp: null, approvedBy: null },
+      uiux: { approved: false, timestamp: null, approvedBy: null },
+      plan: { approved: false, timestamp: null, approvedBy: null },
+      review: { approved: false, timestamp: null, approvedBy: null }
+    },
+    gateDecisions: {},
+    taskScores: {},
+    tasks: {
+      total: 0,
+      completed: 0,
+      inProgress: 0,
+      pending: 0
+    },
+    checkpoints: [],
+    dispatchLog: [],
+    trustConfig: {},
+    contextBundles: [],
+    fileChanges: []
+  };
+
+  state.metadata.totalFeatures = Object.keys(state.features).length;
+  saveState(state);
+  return { feature: state.features[featureName], created: true };
+}
+
 /**
  * Update feature property (supports nested keys like "tasks.completed")
  * @param {string} featureName - Feature name