@polymorphism-tech/morph-spec 4.11.0 → 4.11.1

package/src/commands/agents/dispatch-agents.js

@@ -19,7 +19,7 @@
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { loadState, stateExists } from '../../core/state/state-manager.js';
+import { loadState, stateExists, logDispatch } from '../../core/state/state-manager.js';
 import { buildAgentBriefing, buildValidatorPrompt } from '../../lib/standards/digest-builder.js';
 import { agentIdToSubagentType } from '../../utils/agent-id-mapper.js';
 import { shouldInstall, getProjectTags } from '../../lib/stack-filter.js';
@@ -434,6 +434,30 @@ export async function dispatchAgentsCommand(featureName, phase, options = {}) {
     if (options.mode) dispatchOpts.mode = options.mode;
     const config = await buildDispatchConfig(process.cwd(), featureName, normalizedPhase, dispatchOpts);
 
+    // Log dispatch to state.json so enforcement gates can verify it happened
+    if (config.agents?.length > 0) {
+      try {
+        logDispatch(featureName, {
+          timestamp: new Date().toISOString(),
+          phase: normalizedPhase,
+          mode: config.mode,
+          agents: config.agents.map(a => {
+            const groupEntry = Object.entries(config.taskGroups || {}).find(
+              ([, g]) => g.agentId === a.id
+            );
+            return {
+              id: a.id,
+              subagentType: a.subagentType,
+              group: a.parallelGroup,
+              tasks: groupEntry ? groupEntry[1].tasks : [],
+            };
+          }),
+        });
+      } catch {
+        // Non-blocking — dispatch output still succeeds even if log fails
+      }
+    }
+
     if (options.table) {
       // Human-readable table format
       console.log(chalk.bold(`\n  Dispatch Config — ${featureName} (${normalizedPhase})`));

package/src/commands/tasks/task.js

@@ -42,6 +42,8 @@ export async function taskDoneCommand(featureName, taskIds, options) {
   try {
     const args = ['done', featureName, ...taskIds];
     if (options.skipValidation) args.push('--skip-validation');
+    if (options.reason) args.push('--reason', options.reason);
+    if (options.note) args.push('--note', options.note);
     if (options.dryRun) args.push('--dry-run');
     await executeTaskManager(args);
   } catch (error) {
@@ -64,6 +66,58 @@ export async function taskStartCommand(featureName, taskId, options) {
   }
 }
 
+/**
+ * Bulk-start tasks command
+ */
+export async function taskBulkStartCommand(featureName, range, options) {
+  try {
+    const args = ['bulk-start', featureName];
+    if (range) args.push(range);
+    if (options.all) args.push('--all');
+    if (options.from) args.push('--from', options.from);
+    if (options.to) args.push('--to', options.to);
+    await executeTaskManager(args);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Bulk-done tasks command
+ */
+export async function taskBulkDoneCommand(featureName, range, options) {
+  try {
+    const args = ['bulk-done', featureName];
+    if (range) args.push(range);
+    if (options.all) args.push('--all');
+    if (options.from) args.push('--from', options.from);
+    if (options.to) args.push('--to', options.to);
+    if (options.skipValidation) args.push('--skip-validation');
+    if (options.reason) args.push('--reason', options.reason);
+    if (options.note) args.push('--note', options.note);
+    if (options.dryRun) args.push('--dry-run');
+    await executeTaskManager(args);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Annotate a task with a note
+ */
+export async function taskAnnotateCommand(featureName, taskId, text, options) {
+  try {
+    const args = ['annotate', featureName, taskId, text];
+    if (options.type) args.push('--type', options.type);
+    await executeTaskManager(args);
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
 /**
  * Get next task command
  */

package/src/lib/build/build-runner.js

@@ -0,0 +1,99 @@
+/**
+ * Build Runner — Resolves and executes the project's build command.
+ *
+ * Resolution order for build command:
+ *   1. .morph/config/config.json → project.buildCommand
+ *   2. Stack profile → profile.buildCommand
+ *   3. package.json → scripts.build → "npm run build"
+ *   4. tsconfig.json at root → "npx tsc --noEmit"
+ *   5. null (no build command detected)
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { getStackProfile } from '../stack/stack-profile.js';
+
+/**
+ * Resolve the build command for a project.
+ *
+ * @param {string} [projectPath] - Project root directory (defaults to '.')
+ * @returns {string | null} The build command to run, or null if none found
+ */
+export function resolveBuildCommand(projectPath = '.') {
+  // 1. Explicit override from .morph/config/config.json
+  const configPath = join(projectPath, '.morph', 'config', 'config.json');
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf8'));
+      const cmd = config?.project?.buildCommand;
+      if (cmd && typeof cmd === 'string') {
+        return cmd;
+      }
+    } catch {
+      // Malformed config — fall through to detection
+    }
+  }
+
+  // 2. Stack profile default (only when an actual stack is configured)
+  const profile = getStackProfile(projectPath);
+  if (profile.stack !== 'unknown' && profile.buildCommand) {
+    return profile.buildCommand;
+  }
+
+  // 3. package.json with a build script
+  const packageJsonPath = join(projectPath, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+      if (pkg?.scripts?.build) {
+        return 'npm run build';
+      }
+    } catch {
+      // Malformed package.json — fall through
+    }
+  }
+
+  // 4. tsconfig.json at root → generic type-check
+  if (existsSync(join(projectPath, 'tsconfig.json'))) {
+    return 'npx tsc --noEmit';
+  }
+
+  // 5. Nothing found
+  return null;
+}
+
+/**
+ * Run the project's build check.
+ *
+ * @param {string} [projectPath] - Project root directory (defaults to '.')
+ * @param {object} [opts] - Optional overrides for testing
+ * @param {Function} [opts._execSync] - Override execSync for unit testing
+ * @returns {{ passed?: boolean, output?: string, exitCode?: number, command?: string, skipped?: boolean, reason?: string }}
+ */
+export function runBuildCheck(projectPath = '.', opts = {}) {
+  const cmd = resolveBuildCommand(projectPath);
+
+  if (!cmd) {
+    return { skipped: true, reason: 'No buildCommand configured and no known project file detected' };
+  }
+
+  const exec = opts._execSync ?? execSync;
+
+  try {
+    const output = exec(cmd, {
+      cwd: projectPath,
+      timeout: 120_000,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+    return { passed: true, output: output ?? '', exitCode: 0, command: cmd };
+  } catch (err) {
+    return {
+      passed: false,
+      output: (err.stdout || '') + (err.stderr || ''),
+      exitCode: err.status ?? 1,
+      command: cmd
+    };
+  }
+}

package/src/lib/checkpoints/checkpoint-hooks.js

@@ -0,0 +1,110 @@
+/**
+ * Checkpoint Hooks — Orchestrates validation, build, and test phases at checkpoints.
+ *
+ * This is the module that task-manager.js imports at:
+ *   import('../src/lib/checkpoints/checkpoint-hooks.js')
+ *
+ * All three phases run independently (failures don't short-circuit) so the user
+ * gets a complete picture of all issues in a single checkpoint report.
+ */
+
+import chalk from 'chalk';
+import { runValidation } from '../validators/validation-runner.js';
+import { runBuildCheck } from '../build/build-runner.js';
+import { runTestSuite } from '../tasks/test-runner.js';
+import { persistCheckpointValidation } from '../validators/checkpoint-persistence.js';
+
+/**
+ * Determine whether a checkpoint should run based on task count and frequency.
+ *
+ * @param {number} tasksCompleted - Number of tasks completed so far
+ * @param {number} frequency - Run every N tasks (default: 3)
+ * @returns {boolean}
+ */
+export function shouldRunCheckpoint(tasksCompleted, frequency = 3) {
+  return tasksCompleted > 0 && tasksCompleted % frequency === 0;
+}
+
+/**
+ * Run all checkpoint hooks: static validation, build check, and test suite.
+ *
+ * @param {string} featureName - The feature being worked on
+ * @param {number} checkpointNum - Checkpoint sequence number
+ * @param {object} [opts] - Options
+ * @param {string} [opts.projectPath] - Project root (defaults to cwd)
+ * @returns {Promise<{ passed: boolean, summary: { errors: number, warnings: number }, results: object }>}
+ */
+export async function runCheckpointHooks(featureName, checkpointNum, opts = {}) {
+  const projectPath = opts.projectPath ?? process.cwd();
+  const results = {};
+  let totalErrors = 0;
+  let totalWarnings = 0;
+
+  // Phase 1: Static validators
+  console.log(chalk.gray('\n  Phase 1/3: Running static validators...'));
+  try {
+    const valResult = await runValidation(projectPath, featureName, { verbose: false, mode: 'full' });
+    results.validators = {
+      passed: valResult.passed,
+      errors: valResult.errors,
+      warnings: valResult.warnings,
+      details: valResult.results
+    };
+    totalErrors += valResult.errors;
+    totalWarnings += valResult.warnings;
+  } catch (err) {
+    results.validators = { passed: false, errors: 1, warnings: 0, details: {}, error: err.message };
+    totalErrors += 1;
+  }
+
+  // Phase 2: Build check
+  console.log(chalk.gray('  Phase 2/3: Running build check...'));
+  const buildResult = runBuildCheck(projectPath);
+  results.build = buildResult;
+  if (buildResult.skipped) {
+    console.log(chalk.gray(`    Skipped: ${buildResult.reason}`));
+  } else if (buildResult.passed) {
+    console.log(chalk.green(`    ✓ Build passed (${buildResult.command})`));
+  } else {
+    console.log(chalk.red(`    ✗ Build failed (${buildResult.command})`));
+    totalErrors += 1;
+  }
+
+  // Phase 3: Test suite
+  console.log(chalk.gray('  Phase 3/3: Running test suite...'));
+  const testResult = runTestSuite(projectPath);
+  results.tests = testResult;
+  if (testResult.skipped) {
+    console.log(chalk.gray(`    Skipped: ${testResult.reason}`));
+  } else if (testResult.passed) {
+    console.log(chalk.green('    ✓ Tests passed'));
+  } else {
+    console.log(chalk.red('    ✗ Tests failed'));
+    totalErrors += 1;
+  }
+
+  // Persist results
+  const summaryText = [
+    `Validators: ${results.validators?.errors || 0} errors, ${results.validators?.warnings || 0} warnings`,
+    buildResult.skipped ? 'Build: skipped' : `Build: ${buildResult.passed ? 'passed' : 'FAILED'}`,
+    testResult.skipped ? 'Tests: skipped' : `Tests: ${testResult.passed ? 'passed' : 'FAILED'}`
+  ].join(' | ');
+
+  try {
+    persistCheckpointValidation(projectPath, featureName, {
+      checkpointNum,
+      timestamp: new Date().toISOString(),
+      passed: totalErrors === 0,
+      validators: results,
+      summary: summaryText
+    });
+  } catch {
+    // Non-blocking — persistence failure shouldn't break the checkpoint
+  }
+
+  return {
+    passed: totalErrors === 0,
+    summary: { errors: totalErrors, warnings: totalWarnings },
+    results
+  };
+}

package/src/lib/generators/recap-generator.js

@@ -233,11 +233,34 @@ function buildRecapMarkdown(data) {
 
   // Tasks Detail
   if (tasksSummary.items.length > 0) {
+    const anyNotes = tasksSummary.items.some(t => t.notes?.length > 0);
     md += `## Tasks\n\n`;
-    md += `| ID | Title | Status |\n|----|-------|--------|\n`;
-    for (const task of tasksSummary.items) {
-      const statusIcon = task.status === 'completed' ? '✅' : task.status === 'in_progress' ? '🔄' : '⏳';
-      md += `| ${task.id} | ${task.title || '-'} | ${statusIcon} ${task.status} |\n`;
+    if (anyNotes) {
+      md += `| ID | Title | Status | Notes |\n|----|-------|--------|-------|\n`;
+      for (const task of tasksSummary.items) {
+        const statusIcon = task.status === 'completed' ? '✅' : task.status === 'in_progress' ? '🔄' : '⏳';
+        const noteCount = task.notes?.length || 0;
+        const notesCell = noteCount > 0 ? `${noteCount} note${noteCount > 1 ? 's' : ''}` : '-';
+        md += `| ${task.id} | ${task.title || '-'} | ${statusIcon} ${task.status} | ${notesCell} |\n`;
+      }
+    } else {
+      md += `| ID | Title | Status |\n|----|-------|--------|\n`;
+      for (const task of tasksSummary.items) {
+        const statusIcon = task.status === 'completed' ? '✅' : task.status === 'in_progress' ? '🔄' : '⏳';
+        md += `| ${task.id} | ${task.title || '-'} | ${statusIcon} ${task.status} |\n`;
+      }
+    }
+    md += `\n`;
+  }
+
+  // Deviations from Plan
+  const deviations = tasksSummary.items
+    .filter(t => t.notes?.some(n => n.type === 'deviation'))
+    .flatMap(t => t.notes.filter(n => n.type === 'deviation').map(n => ({ taskId: t.id, text: n.text })));
+  if (deviations.length > 0) {
+    md += `## Deviations from Plan\n\n`;
+    for (const d of deviations) {
+      md += `- **${d.taskId}**: ${d.text}\n`;
     }
     md += `\n`;
   }

package/src/lib/stack/stack-profile.js

@@ -24,6 +24,7 @@ const PROFILES = {
     isDotnet: true, isNextjs: false,
     defaultValidators: ['architecture', 'packages'],
     checkpointValidators: ['architecture', 'packages', 'design-system', 'security'],
+    buildCommand: 'dotnet build --no-restore',
     contractsOutputType: 'contracts',
     contractsFilename: 'contracts.cs',
     contractsLanguage: 'csharp',
@@ -32,6 +33,7 @@ const PROFILES = {
     isDotnet: false, isNextjs: true,
     defaultValidators: ['nextjs-component'],
     checkpointValidators: ['nextjs-component', 'css'],
+    buildCommand: 'npx tsc --noEmit',
     contractsOutputType: 'contractsTs',
     contractsFilename: 'contracts.ts',
     contractsLanguage: 'typescript',
@@ -40,6 +42,7 @@ const PROFILES = {
     isDotnet: false, isNextjs: false,
     defaultValidators: [],
     checkpointValidators: [],
+    buildCommand: null,
     contractsOutputType: 'contracts',
     contractsFilename: 'contracts.cs',
     contractsLanguage: 'csharp',

package/src/lib/tasks/task-parser.js

@@ -122,18 +122,32 @@ export async function parseTasksMd(featureName, cwd = process.cwd()) {
     return [];
   }
 
-  const tasks = [];
+  // Phase 1: collect heading positions
   const headingRe = /^###\s+(T\d+)\s*[—–:\-]\s*(.+)$/gm;
+  const depRe = /\*\*Dependenc(?:y|ies):\*\*\s*(.+)/i;
+  const positions = [];
   let match;
   while ((match = headingRe.exec(content)) !== null) {
-    tasks.push({
-      id: match[1],
-      title: match[2].trim(),
-      status: 'pending',
-      dependencies: [],
-      files: [],
-      checkpoint: null,
-    });
+    positions.push({ id: match[1], title: match[2].trim(), pos: match.index });
+  }
+
+  // Phase 2: extract body and parse dependencies
+  const tasks = [];
+  for (let i = 0; i < positions.length; i++) {
+    const { id, title, pos } = positions[i];
+    const end = i + 1 < positions.length ? positions[i + 1].pos : content.length;
+    const block = content.slice(pos, end);
+
+    let dependencies = [];
+    const depMatch = depRe.exec(block);
+    if (depMatch) {
+      const val = depMatch[1].trim();
+      if (val.toLowerCase() !== 'none') {
+        dependencies = val.split(/[,\s]+/).filter(s => /^T\d+$/.test(s));
+      }
+    }
+
+    tasks.push({ id, title, status: 'pending', dependencies, files: [], checkpoint: null });
   }
   return tasks;
 }

package/src/utils/file-copier.js

@@ -149,6 +149,7 @@ export async function updateGitignore(projectPath) {
     '.claude/CLAUDE.md',
     '.claude/settings.local.json',
     '.worktrees/',
+    'docs/superpowers/',
     ''
   ];
 

package/framework/hooks/claude-code/pre-tool-use/protect-readonly-files.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-/**
- * DEPRECATED — This hook has been replaced by native permissions.deny in settings.local.json.
- * The file is kept as an empty stub. It is NOT registered in hooks-installer.js.
- * Safe to delete.
- */
-process.exit(0);