@polymorphism-tech/morph-spec 4.8.19 → 4.10.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/scope/escalate.js

@@ -0,0 +1,215 @@
+/**
+ * MORPH-SPEC Scope Escalate Command
+ *
+ * Handles mid-implementation scope discovery by analyzing impact,
+ * regressing phase or expanding tasks, and creating an audit trail.
+ *
+ * Usage:
+ *   morph-spec scope escalate <feature> --task <id> --reason "..."
+ *   morph-spec scope escalate <feature> --task <id> --reason "..." --dry-run
+ *   morph-spec scope escalate <feature> --task <id> --reason "..." --target design
+ */
+
+import chalk from 'chalk';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { loadState, saveState } from '../../core/state/state-manager.js';
+import { analyzeImpact } from '../../lib/scope/impact-analyzer.js';
+
+/**
+ * Core escalation logic — exported for testing.
+ *
+ * @param {string} featureName
+ * @param {Object} options
+ * @param {string} options.task - Trigger task ID
+ * @param {string} options.reason - Reason for escalation
+ * @param {string} [options.target] - Override target phase
+ * @param {boolean} [options.dryRun] - Don't execute, just recommend
+ * @returns {Promise<{ success: boolean, error?: string, recommendation?: Object }>}
+ */
+export async function escalateScope(featureName, options) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature) {
+    return { success: false, error: `Feature "${featureName}" not found in state.json` };
+  }
+
+  if (feature.phase !== 'implement') {
+    return { success: false, error: `Scope escalation only available during implement phase (current: ${feature.phase})` };
+  }
+
+  // Read tasks.md
+  const tasksPath = join(process.cwd(), '.morph', 'features', featureName, '4-tasks', 'tasks.md');
+  let tasksMd = '';
+  try {
+    tasksMd = readFileSync(tasksPath, 'utf-8');
+  } catch {
+    return { success: false, error: 'tasks.md not found' };
+  }
+
+  // Read spec.md (optional — not all features have it)
+  const specPath = join(process.cwd(), '.morph', 'features', featureName, '1-design', 'spec.md');
+  let specMd = '';
+  try { specMd = readFileSync(specPath, 'utf-8'); } catch { /* ok */ }
+
+  // Analyze impact
+  const analysis = analyzeImpact({
+    triggerTaskId: options.task,
+    tasksMd,
+    specMd,
+    reason: options.reason
+  });
+
+  // Apply target override
+  if (options.target) {
+    analysis.recommendation = `regress-${options.target}`;
+    analysis.targetPhase = options.target;
+    if (analysis.targetPhase === 'design') analysis.impact = 'high';
+    else if (analysis.targetPhase === 'tasks') analysis.impact = 'medium';
+  }
+
+  // Dry-run: return recommendation without modifying state
+  if (options.dryRun) {
+    return { success: true, recommendation: analysis };
+  }
+
+  // Build escalation record
+  const escId = `ESC-${String((feature.escalations?.length || 0) + 1).padStart(3, '0')}`;
+  const record = {
+    id: escId,
+    triggerTask: options.task,
+    reason: options.reason,
+    impact: analysis.impact,
+    action: analysis.recommendation,
+    affectedTasks: analysis.affectedTasks,
+    reviewedTasks: [],
+    targetPhase: analysis.targetPhase || 'tasks',
+    previousPhase: 'implement',
+    createdAt: new Date().toISOString(),
+    resolvedAt: null
+  };
+
+  // Execute based on recommendation
+  if (analysis.recommendation.startsWith('regress')) {
+    const targetPhase = analysis.targetPhase || 'tasks';
+
+    // Flag completed tasks as needsReview (supports both v2 'done' and v3 'completed')
+    if (feature.taskList) {
+      for (const task of feature.taskList) {
+        if (task.status === 'done' || task.status === 'completed') {
+          task.needsReview = true;
+        }
+      }
+    }
+
+    // Reset phase
+    feature.phase = targetPhase;
+
+    // Reset relevant approval gates
+    if (feature.approvalGates) {
+      if (targetPhase === 'tasks' && feature.approvalGates.tasks) {
+        feature.approvalGates.tasks = { approved: false, timestamp: null, approvedBy: null };
+      }
+      if (targetPhase === 'design') {
+        if (feature.approvalGates.design) {
+          feature.approvalGates.design = { approved: false, timestamp: null, approvedBy: null };
+        }
+        if (feature.approvalGates.tasks) {
+          feature.approvalGates.tasks = { approved: false, timestamp: null, approvedBy: null };
+        }
+      }
+    }
+  }
+
+  // Write escalation record to state
+  if (!feature.escalations) feature.escalations = [];
+  feature.escalations.push(record);
+  feature.updatedAt = new Date().toISOString();
+
+  saveState(state);
+
+  // Create/append escalation-log.md
+  writeEscalationLog(featureName, record);
+
+  return { success: true, recommendation: analysis, escalationId: escId };
+}
+
+/**
+ * Write escalation log entry to 4-tasks/escalation-log.md
+ */
+function writeEscalationLog(featureName, record) {
+  const logDir = join(process.cwd(), '.morph', 'features', featureName, '4-tasks');
+  mkdirSync(logDir, { recursive: true });
+  const logPath = join(logDir, 'escalation-log.md');
+
+  const doneTasks = record.reviewedTasks?.length > 0
+    ? record.reviewedTasks.join(', ')
+    : '(all completed tasks flagged)';
+
+  const entry = `
+## ${record.id} — ${record.createdAt.split('T')[0]}
+- **Trigger:** ${record.triggerTask}
+- **Discovery:** ${record.reason}
+- **Impact:** ${record.impact} (${record.affectedTasks.length} tasks affected: ${record.affectedTasks.join(', ')})
+- **Action:** ${record.action} → ${record.targetPhase} phase
+- **Affected completed tasks flagged for review:** ${doneTasks}
+`;
+
+  let existing = '';
+  try { existing = readFileSync(logPath, 'utf-8'); } catch { /* new file */ }
+
+  if (!existing) {
+    writeFileSync(logPath, `# Scope Escalation Log\n${entry}`);
+  } else {
+    writeFileSync(logPath, existing + entry);
+  }
+}
+
+/**
+ * CLI command handler
+ */
+export async function scopeEscalateCommand(feature, options) {
+  console.log(chalk.cyan('\n========================================'));
+  console.log(chalk.cyan('  MORPH-SPEC SCOPE ESCALATION'));
+  console.log(chalk.cyan('========================================\n'));
+
+  if (!options.task) {
+    console.error(chalk.red('--task <id> is required'));
+    process.exit(1);
+  }
+  if (!options.reason) {
+    console.error(chalk.red('--reason "..." is required'));
+    process.exit(1);
+  }
+
+  const result = await escalateScope(feature, options);
+
+  if (!result.success) {
+    console.error(chalk.red(`\n  ${result.error}`));
+    process.exit(1);
+  }
+
+  const rec = result.recommendation;
+  console.log(chalk.gray('Trigger task:'), rec.triggerTask);
+  console.log(chalk.gray('Impact:'), rec.impact);
+  console.log(chalk.gray('Affected tasks:'), rec.affectedTasks.join(', '));
+  console.log(chalk.gray('Recommendation:'), rec.recommendation);
+  if (rec.targetPhase) console.log(chalk.gray('Target phase:'), rec.targetPhase);
+
+  if (options.dryRun) {
+    console.log(chalk.cyan('\n  Dry-run — no changes made'));
+    process.exit(2);
+  }
+
+  if (rec.recommendation === 'expand') {
+    console.log(chalk.green(`\n  Escalation ${result.escalationId} recorded (low impact)`));
+    console.log(chalk.yellow(`  Action: Use task expand to split the task:`));
+    console.log(chalk.gray(`    morph-spec task expand ${feature} ${options.task} --into "ID: Title" ...`));
+  } else {
+    console.log(chalk.green(`\n  Escalation ${result.escalationId} executed`));
+    console.log(chalk.yellow(`  Phase regressed to: ${rec.targetPhase || 'tasks'}`));
+  }
+  console.log(chalk.gray(`  Escalation log: .morph/features/${feature}/4-tasks/escalation-log.md`));
+  console.log('');
+}