@polymorphism-tech/morph-spec 4.8.19 → 4.9.0

package/src/commands/project/worktree.js

@@ -0,0 +1,154 @@
+/**
+ * MORPH-SPEC Worktree Setup Command
+ *
+ * Creates a git worktree at .worktrees/{feature}/ on branch morph/{feature}.
+ * Used by SessionStart hook to isolate feature work from the main branch.
+ *
+ * Usage:
+ *   morph-spec worktree setup <feature>
+ *   morph-spec worktree setup <feature> --fresh
+ *
+ * Exit codes:
+ *   0  — success (created) or fail-open (not a git repo, git error)
+ *   2  — worktree already exists (signals resume scenario to hook caller)
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+// ── Pure helpers (exported for tests) ──────────────────────────────────────
+
+/**
+ * Check if a directory is inside a git repository.
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function isGitRepo(cwd = process.cwd()) {
+  try {
+    execSync('git rev-parse --git-dir', { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a branch exists locally.
+ * @param {string} branch
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function branchExists(branch, cwd = process.cwd()) {
+  try {
+    execSync(`git show-ref --verify --quiet refs/heads/${branch}`, { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a worktree path is already registered with git.
+ * @param {string} worktreePath  Relative or absolute path
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function worktreeExists(worktreePath, cwd = process.cwd()) {
+  try {
+    const output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
+    const normalizedPath = worktreePath.replace(/\\/g, '/');
+    const absPath = normalizedPath.startsWith('/') ? normalizedPath : `${cwd.replace(/\\/g, '/')}/${normalizedPath}`;
+    return output.replace(/\\/g, '/').includes(absPath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build the worktree directory path (always forward slashes).
+ * @param {string} feature
+ * @param {string} cwd
+ * @param {{ fresh?: boolean }} options
+ * @returns {string}
+ */
+export function buildWorktreePath(feature, cwd = process.cwd(), options = {}) {
+  const suffix = options.fresh ? `-${getDateSuffix()}` : '';
+  const normalizedCwd = cwd.replace(/\\/g, '/');
+  return `${normalizedCwd}/.worktrees/${feature}${suffix}`;
+}
+
+/**
+ * Build the branch name for a feature worktree.
+ * @param {string} feature
+ * @param {{ fresh?: boolean }} options
+ * @returns {string}
+ */
+export function buildBranchName(feature, options = {}) {
+  const suffix = options.fresh ? `-${getDateSuffix()}` : '';
+  return `morph/${feature}${suffix}`;
+}
+
+function getDateSuffix() {
+  return new Date().toISOString().slice(0, 10).replace(/-/g, '');
+}
+
+// ── Command handler ─────────────────────────────────────────────────────────
+
+/**
+ * Main command handler for `morph-spec worktree setup <feature>`
+ * @param {string} feature
+ * @param {{ fresh?: boolean, cwd?: string }} options
+ */
+export async function worktreeSetupCommand(feature, options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  // Gate 1: Must be a git repo
+  if (!isGitRepo(cwd)) {
+    console.log(JSON.stringify({ created: false, error: 'not-a-git-repo', feature }));
+    process.exit(0); // Fail-open
+  }
+
+  const branch = buildBranchName(feature, options);
+  const worktreePath = buildWorktreePath(feature, cwd, options);
+
+  // Gate 2: If worktree already registered and not --fresh, signal resume
+  if (!options.fresh && worktreeExists(worktreePath, cwd)) {
+    console.log(JSON.stringify({ created: false, alreadyExists: true, path: worktreePath, branch, feature }));
+    process.exit(2); // Convention: 2 = already exists
+  }
+
+  try {
+    // Create branch if needed (based off current HEAD)
+    if (!branchExists(branch, cwd)) {
+      execSync(`git branch ${branch}`, { cwd, stdio: 'pipe' });
+    }
+
+    // Create worktree directory parent if needed
+    const parentDir = join(cwd, '.worktrees');
+    if (!existsSync(parentDir)) {
+      mkdirSync(parentDir, { recursive: true });
+    }
+
+    // Add worktree
+    execSync(`git worktree add "${worktreePath}" ${branch}`, { cwd, stdio: 'pipe' });
+
+    // Persist in state (non-blocking — feature may not be in state yet)
+    try {
+      const { loadState, saveState } = await import('../../lib/state/state-manager.js');
+      const state = loadState(cwd);
+      if (state?.features?.[feature]) {
+        state.features[feature].worktree = { path: worktreePath, branch, createdAt: new Date().toISOString() };
+        saveState(state, cwd);
+      }
+    } catch {
+      // Non-blocking
+    }
+
+    console.log(JSON.stringify({ created: true, path: worktreePath, branch, feature }));
+    process.exit(0);
+  } catch (err) {
+    console.log(JSON.stringify({ created: false, error: (err.message || 'unknown').slice(0, 200), feature }));
+    process.exit(0); // Fail-open
+  }
+}

package/src/commands/state/advance-phase.js

@@ -11,14 +11,15 @@
 
 import chalk from 'chalk';
 import { loadState, saveState, getFeature, getApprovalGate, derivePhase } from '../../core/state/state-manager.js';
-import { PHASES, validatePhase } from './validate-phase.js';
+import { PHASES, validatePhase } from '../../lib/phase-chain/phase-validator.js';
 import { detectDesignSystem, hasUIAgentsActive } from '../../lib/detectors/design-system-detector.js';
-import { getOutputPath } from '../../core/paths/output-schema.js';
-import { shouldAutoApprove, autoCalculateTrust } from '../../lib/trust/trust-manager.js';
+import { getOutputPath, getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+import { shouldAutoApprove } from '../../lib/trust/trust-manager.js';
 import { validateSpec } from '../../lib/validators/spec-validator.js';
 import { validateTransition, getPhaseDisplayName } from '../../core/state/phase-state-machine.js';
 import { validateSpecContent, validateTasksContent, validateFeatureOutputs } from '../../lib/validators/content/content-validator.js';
 import { getWorkflowConfig } from '../../core/workflows/workflow-detector.js';
+import { getStackProfile } from '../../lib/stack/stack-profile.js';
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -28,6 +29,17 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // Phase order for advancing (skips optional phases unless active)
 const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks', 'implement', 'sync'];
 
+/**
+ * Phases that require an explicit approval gate before advancing.
+ * When --skip-approval is passed, these gates are bypassed and a warning is logged.
+ * Exported for use in tests and in phase-runner warnings.
+ */
+export const APPROVAL_GATE_MAP = {
+  'design': 'design',
+  'tasks': 'tasks',
+  'uiux': 'uiux'
+};
+
 /**
  * Get the next phase after the current one.
  * Returns { nextPhase, skippedPhases } so callers can persist skipped phases in state.
@@ -119,14 +131,11 @@ function getNextPhase(currentPhase, feature, skipOptional, featureName) {
         }
       }
 
-      // Skip sync for simple workflows
-      if (candidate === 'sync') {
-        const isSimple = feature.workflow === 'fast-track';
-        if (isSimple && skipOptional !== false) {
-          console.log(chalk.gray(`  ⏩ Skipping ${candidate}: fast-track workflow`));
-          skippedPhases.push(candidate);
-          continue;
-        }
+      // sync is optional — only skip if --skip-optional is set
+      if (candidate === 'sync' && skipOptional) {
+        console.log(chalk.gray(`  ⏩ Skipping ${candidate}: optional phase`));
+        skippedPhases.push(candidate);
+        continue;
       }
     }
 
@@ -189,13 +198,15 @@ export async function advancePhaseCommand(feature, options = {}) {
 
   // === GATE 2: Approval Gate Check ===
   // Check if current phase requires approval before advancing
-  const approvalGateMap = {
-    'design': 'design',
-    'tasks': 'tasks',
-    'uiux': 'uiux'
-  };
-
-  const requiredGate = approvalGateMap[currentPhase];
+  // Track gates that get approved implicitly so we can persist them after state load.
+  let gateApprovedImplicitly = null;   // { gate, approvedBy, reason }
+
+  const requiredGate = APPROVAL_GATE_MAP[currentPhase];
+  if (requiredGate && options.skipApproval) {
+    console.log(chalk.yellow(`\n⚠ --skip-approval: Approval gate "${requiredGate}" bypassed for phase "${currentPhase}"`));
+    console.log(chalk.gray('  Intended for CI/automation only. Run without --skip-approval for normal workflow.\n'));
+    gateApprovedImplicitly = { gate: requiredGate, approvedBy: 'skip-approval' };
+  }
   if (requiredGate && !options.skipApproval) {
     const gateStatus = getApprovalGate(feature, requiredGate);
 
@@ -206,6 +217,7 @@ export async function advancePhaseCommand(feature, options = {}) {
         if (trustResult.autoApprove) {
           console.log(chalk.green(`\n✓ Auto-approved gate "${requiredGate}" (${trustResult.reason})`));
           // Proceed — trust bypasses manual gate requirement
+          gateApprovedImplicitly = { gate: requiredGate, approvedBy: `trust:${trustResult.level}` };
         } else {
           console.log(chalk.red(`\n✗ Phase "${currentPhase}" requires approval before advancing`));
           console.log(chalk.gray(`   Trust level: ${trustResult.level} (${trustResult.reason})`));
@@ -245,9 +257,10 @@ export async function advancePhaseCommand(feature, options = {}) {
   // === GATE 4: Content Validation ===
   // Validate spec.md and contracts.cs when advancing from design phase
   if (currentPhase === 'design' && (nextPhase === 'clarify' || nextPhase === 'tasks')) {
-    // Check spec.md structure and content
-    if (featureData.outputs?.spec?.created) {
-      const specContentValidation = validateSpecContent(featureData.outputs.spec.path);
+    // Check spec.md structure and content (filesystem-based)
+    const specAbsPath = getAbsoluteOutputPath(process.cwd(), feature, 'spec');
+    if (existsSync(specAbsPath)) {
+      const specContentValidation = validateSpecContent(specAbsPath);
 
       if (!specContentValidation.valid) {
         console.log(chalk.red('\n✗ Spec content validation failed:'));
@@ -294,8 +307,9 @@ export async function advancePhaseCommand(feature, options = {}) {
   // === GATE 5: Tasks Content Validation ===
   // Validate tasks.md structure when advancing to implement
   if (currentPhase === 'tasks' && nextPhase === 'implement') {
-    if (featureData.outputs?.tasks?.created) {
-      const tasksContentValidation = validateTasksContent(featureData.outputs.tasks.path);
+    const tasksAbsPath = getAbsoluteOutputPath(process.cwd(), feature, 'tasks');
+    if (existsSync(tasksAbsPath)) {
+      const tasksContentValidation = validateTasksContent(tasksAbsPath);
 
       if (!tasksContentValidation.valid) {
         console.log(chalk.red('\n✗ Tasks content validation failed:'));
@@ -345,6 +359,40 @@ export async function advancePhaseCommand(feature, options = {}) {
     const existingSkipped = state.features[feature].skippedPhases || [];
     state.features[feature].skippedPhases = [...new Set([...existingSkipped, ...skippedPhases])];
   }
+
+  // Ensure approvalGates object exists
+  if (!state.features[feature].approvalGates) {
+    state.features[feature].approvalGates = {};
+  }
+
+  const now = new Date().toISOString();
+  const gates = state.features[feature].approvalGates;
+
+  // Auto-approve proposal gate when advancing past the proposal phase.
+  // The act of advancing is itself the approval — no explicit gate check needed.
+  if (currentPhase === 'proposal' && !gates.proposal?.approved) {
+    gates.proposal = { approved: true, timestamp: now, approvedBy: 'workflow-advance' };
+  }
+
+  // Persist gates approved implicitly (trust auto-approve or --skip-approval bypass).
+  if (gateApprovedImplicitly && !gates[gateApprovedImplicitly.gate]?.approved) {
+    gates[gateApprovedImplicitly.gate] = {
+      approved: true,
+      timestamp: now,
+      approvedBy: gateApprovedImplicitly.approvedBy
+    };
+  }
+
+  // Auto-approve gates for phases that were legitimately skipped.
+  // Skipped phases never run their explicit approve step, so their gate would
+  // otherwise stay false in state — making approval-status misleading.
+  for (const skippedPhase of skippedPhases) {
+    const skippedGate = APPROVAL_GATE_MAP[skippedPhase];
+    if (skippedGate && !gates[skippedGate]?.approved) {
+      gates[skippedGate] = { approved: true, timestamp: now, approvedBy: 'phase-skipped' };
+    }
+  }
+
   saveState(state);
 
   // Run PhaseAdvanced agent-teams hook (non-blocking)
@@ -369,6 +417,9 @@ export async function advancePhaseCommand(feature, options = {}) {
     await emitValidatorDispatch(feature, validationPhase, process.cwd());
   }
 
+  // Emit SKILL DISPATCH for any phase that has requiredSkills
+  await emitSkillDispatch(nextPhase, process.cwd());
+
   console.log(chalk.green(`\n✓ Advanced to ${nextPhaseDef.name}`));
 
   // Show what's needed in the new phase
@@ -407,11 +458,14 @@ function getPhaseGuidance(phase, feature) {
       'Provide layout references and preferences',
       'Review wireframes before proceeding'
     ],
-    'design': [
-      `Resume spec pipeline: /morph-proposal ${feature}`,
-      'Review DECISION POINTS carefully',
-      'Approve spec.md and contracts.cs'
-    ],
+    'design': (() => {
+      const { isDotnet } = getStackProfile();
+      return [
+        `Resume spec pipeline: /morph-proposal ${feature}`,
+        'Review DECISION POINTS carefully',
+        isDotnet ? 'Approve spec.md and contracts.cs' : 'Approve spec.md and contracts.ts (TypeScript + Zod schemas)'
+      ];
+    })(),
     'clarify': [
       `Resume spec pipeline: /morph-proposal ${feature}`,
       'Resolve edge cases and unknowns'
@@ -428,7 +482,7 @@ function getPhaseGuidance(phase, feature) {
     ],
     'sync': [
       'Review decisions.md for standards to promote',
-      `Sync: morph-spec sync --path ${getOutputPath(feature, 'decisions')}`
+      `Decisions file: ${getOutputPath(feature, 'decisions')}`
     ]
   };
 
@@ -466,7 +520,7 @@ function designSystemGate(feature, projectPath = '.') {
       'Create a design system with one of these options:',
       '  1. Project-level: .morph/context/design-system.md (shared across features)',
       `  2. Feature-level: ${getOutputPath(feature, 'uiDesignSystem')} (feature-specific)`,
-      '  3. Auto-generate: morph-spec generate design-system (scans existing CSS)',
+      '  3. Run /morph:phase-uiux skill to auto-generate from existing codebase',
       '',
       'Or remove UI agents if they are not needed:',
       `  morph-spec state remove-agent ${feature} blazor-builder`
@@ -522,3 +576,39 @@ async function emitValidatorDispatch(featureName, phase, cwd) {
     // Non-blocking — fail silently
   }
 }
+
+/**
+ * Emit a SKILL DISPATCH block when advancing to a phase that has requiredSkills.
+ * Outputs structured JSON for the LLM to read and follow.
+ * Non-blocking — fails silently.
+ *
+ * @param {string} nextPhase - The phase being advanced into
+ * @param {string} cwd - Project root path (for locating phases.json)
+ */
+async function emitSkillDispatch(nextPhase, cwd) {
+  try {
+    // Try project-local phases.json first, fall back to package-level
+    const localPath = join(cwd, 'framework', 'phases.json');
+    const packagePath = join(__dirname, '../../../framework/phases.json');
+    const resolvedPath = existsSync(localPath) ? localPath : packagePath;
+
+    if (!existsSync(resolvedPath)) return;
+
+    const phasesData = JSON.parse(readFileSync(resolvedPath, 'utf8'));
+    const skills = phasesData?.phases?.[nextPhase]?.requiredSkills;
+    if (!skills || skills.length === 0) return;
+
+    const dispatch = {
+      skillDispatch: true,
+      phase: nextPhase,
+      skills,
+      instruction: `These skills are MANDATORY for phase '${nextPhase}'. Invoke them at the specified trigger points using Skill(). Do NOT skip them.`,
+    };
+
+    console.log(chalk.cyan('\n--- SKILL DISPATCH ---'));
+    console.log(JSON.stringify(dispatch, null, 2));
+    console.log(chalk.cyan('--- END SKILL DISPATCH ---\n'));
+  } catch {
+    // Non-blocking — fail silently
+  }
+}

package/src/commands/state/approve.js

@@ -25,7 +25,7 @@ export async function unapproveCommand(featureName, gateName, options = {}) {
       return;
     }
 
-    setApprovalGate(featureName, gateName, false, {
+    await setApprovalGate(featureName, gateName, false, {
       revokedBy: options.revoker || process.env.USER || process.env.USERNAME || 'user',
       revokedAt: new Date().toISOString(),
       reason: options.reason
@@ -85,7 +85,7 @@ export async function approveCommand(featureName, gateName, options = {}) {
     }
 
     // Set approval
-    setApprovalGate(featureName, gateName, true, {
+    await setApprovalGate(featureName, gateName, true, {
       approvedBy: options.approver || process.env.USER || process.env.USERNAME || 'user',
       approvedAt: new Date().toISOString(),
       notes: options.notes

package/src/commands/state/index.js

@@ -1,8 +1,7 @@
-/**
- * State Management Commands
- */
-export { stateCommand } from './state.js';
-export { advancePhaseCommand } from './advance-phase.js';
-export { approveCommand, unapproveCommand, approvalStatusCommand } from './approve.js';
-export { validatePhaseCommand } from './validate-phase.js';
-export { phaseRunCommand } from './phase-runner.js';
+/**
+ * State Management Commands
+ */
+export { stateCommand } from './state.js';
+export { advancePhaseCommand } from './advance-phase.js';
+export { approveCommand, unapproveCommand, approvalStatusCommand } from './approve.js';
+export { phaseRunCommand } from './phase-runner.js';

package/src/commands/state/phase-runner.js

@@ -23,7 +23,7 @@
 
 import chalk from 'chalk';
 import { join } from 'path';
-import { checkPhaseEligibility, computePassRate } from '../../lib/phase-chain/eligibility-checker.js';
+import { checkPhaseEligibility, computePassRate } from '../../lib/phase-chain/phase-validator.js';
 import { advancePhaseCommand } from './advance-phase.js';
 import { loadState } from '../../core/state/state-manager.js';
 import { derivePhase } from '../../core/state/state-manager.js';

package/src/commands/state/state.js

@@ -11,6 +11,36 @@ import { logger } from '../../utils/logger.js';
 import * as StateManager from '../../core/state/state-manager.js';
 import { derivePhase } from '../../core/state/state-manager.js';
 
+// ============================================================================
+// Phase Protection
+// ============================================================================
+
+/**
+ * Phases that have approval gates and cannot be set directly via `state set`.
+ * These phases must be reached through `morph-spec phase advance` which enforces
+ * all validation gates (approval, output requirements, spec content, etc.).
+ *
+ * Lightweight phases (proposal, setup, clarify, sync) are not in this list
+ * because they have no approval gates and are safe to set directly.
+ */
+export const PROTECTED_PHASES = ['design', 'tasks', 'uiux', 'implement'];
+
+/**
+ * Validate a direct phase-set request.
+ *
+ * @param {string} phase - The target phase value
+ * @returns {{ blocked: boolean, message?: string }}
+ */
+export function validatePhaseSet(phase) {
+  if (PROTECTED_PHASES.includes(phase)) {
+    return {
+      blocked: true,
+      message: `Phase "${phase}" has approval gates — use "morph-spec phase advance" instead of setting it directly.`
+    };
+  }
+  return { blocked: false };
+}
+
 // ============================================================================
 // Command Functions
 // ============================================================================
@@ -174,10 +204,30 @@ async function setCommand(featureName, key, value, options) {
   }
 
   try {
-    // Warn when bypassing the validated phase advance flow
+    // Guard: block protected phases unless --force is explicitly passed
     if (key === 'phase') {
-      logger.warn(`Direct phase override — all validation gates will be bypassed.`);
-      logger.dim(`  Recommended: morph-spec phase advance ${featureName}`);
+      const phaseValidation = validatePhaseSet(value);
+      if (phaseValidation.blocked && !options.force) {
+        logger.error(phaseValidation.message);
+        logger.blank();
+        logger.dim(`  Protected phases (have approval gates): ${PROTECTED_PHASES.join(', ')}`);
+        logger.dim(`  Use the validated advance flow instead:`);
+        logger.dim(`    morph-spec phase advance ${featureName}`);
+        logger.blank();
+        logger.dim(`  To bypass all gates (expert use only):`);
+        logger.dim(`    morph-spec state set ${featureName} phase ${value} --force`);
+        process.exit(1);
+      }
+
+      if (phaseValidation.blocked) {
+        logger.warn(`FORCED phase override to "${value}" — all approval gates bypassed.`);
+      } else {
+        logger.warn(`Direct phase override — validation gates may be bypassed.`);
+        logger.dim(`  The actual phase is derived from filesystem subdirectories`);
+        logger.dim(`  (0-proposal/, 1-design/, 3-tasks/, 4-implement/). This sets a state.json`);
+        logger.dim(`  override used only for lightweight phases (setup, clarify, sync).`);
+        logger.dim(`  Recommended: morph-spec phase advance ${featureName}`);
+      }
       logger.blank();
     }
 
@@ -328,13 +378,18 @@ async function markOutputCommand(featureName, outputType, options) {
     logger.dim('  Usage: morph-spec state mark-output <feature> <output-type>');
     logger.blank();
     logger.dim('  Valid types:');
-    logger.dim('    Standard: proposal, spec, contracts, tasks, decisions, recap');
-    logger.dim('    UI/UX:    uiDesignSystem, uiMockups, uiComponents, uiFlows');
+    logger.dim('    Proposal:  proposal');
+    logger.dim('    Design:    schemaAnalysis, spec, contracts, contractsVsa, decisions');
+    logger.dim('    Clarify:   clarifications');
+    logger.dim('    Tasks:     tasks');
+    logger.dim('    UI/UX:     uiDesignSystem, uiMockups, uiComponents, uiFlows');
+    logger.dim('    Implement: recap');
     logger.blank();
-    logger.dim('  Note: UI types also accept kebab-case (e.g., ui-design-system)');
+    logger.dim('  Note: kebab-case aliases accepted (e.g., ui-design-system, schema-analysis)');
     logger.blank();
     logger.dim('  Examples:');
     logger.dim('    morph-spec state mark-output my-feature spec');
+    logger.dim('    morph-spec state mark-output my-feature schemaAnalysis');
     logger.dim('    morph-spec state mark-output my-feature uiDesignSystem');
     logger.dim('    morph-spec state mark-output my-feature ui-design-system');
     process.exit(1);