@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

package/framework/hooks/shared/dispatch-helpers.js

@@ -0,0 +1,116 @@
+/**
+ * Pure helper functions for the dispatch PostToolUse hook.
+ *
+ * Extracted for testability — no I/O, no process.exit, no stdin/stdout.
+ */
+
+/**
+ * Extract VALIDATION DISPATCH JSON from tool output string.
+ * Strips ANSI escape codes and parses the JSON block between delimiters.
+ *
+ * @param {string} toolOutput - Raw tool output (may contain ANSI codes)
+ * @returns {object|null} - Parsed dispatch object or null
+ */
+export function extractValidationDispatch(toolOutput) {
+  if (!toolOutput || typeof toolOutput !== 'string') return null;
+
+  // Strip ANSI escape codes (chalk colors)
+  const clean = toolOutput.replace(/\x1B\[[0-9;]*m/g, '');
+
+  const match = clean.match(/--- VALIDATION DISPATCH ---\s*\n([\s\S]*?)\n\s*--- END VALIDATION DISPATCH ---/);
+  if (!match) return null;
+
+  try {
+    const dispatch = JSON.parse(match[1]);
+    if (!dispatch?.validators?.length) return null;
+    return dispatch;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format a dispatch object as a mandatory instruction string for Claude.
+ *
+ * @param {object} dispatch - Dispatch object with validators array
+ * @returns {string} - Formatted injection text
+ */
+export function formatValidatorInstruction(dispatch) {
+  if (!dispatch?.validators?.length) return '';
+
+  const lines = [
+    '🔍 MANDATORY VALIDATOR DISPATCH',
+    '════════════════════════════════════════',
+    'You MUST dispatch each validator below as a READ-ONLY subagent using the Agent tool.',
+    'Do NOT skip this step. Do NOT proceed until all blocking validators pass.',
+    '',
+  ];
+
+  for (const v of dispatch.validators) {
+    const blocks = v.blocksOnFail !== false;
+    const sev = v.severity || 'error';
+    lines.push(`### ${v.title} (${v.id})`);
+    lines.push(`Severity: ${sev} | Blocks: ${blocks}`);
+    if (v.checks?.length) lines.push(`Checks: ${v.checks.join(', ')}`);
+    lines.push('');
+    if (v.taskPrompt) {
+      lines.push('Subagent prompt:');
+      lines.push(v.taskPrompt);
+    }
+    lines.push('---');
+  }
+
+  lines.push('');
+  lines.push('DISPATCH INSTRUCTIONS:');
+  lines.push('1. Use the Agent tool for each validator. Set subagent_type to the validator name shown above.');
+  lines.push('2. Use model="haiku" for efficiency. Each validator is read-only.');
+  lines.push('3. Each must return { "passed": boolean, "issues": [] }');
+  lines.push('4. If any blocking validator (Blocks: true) fails, fix issues before proceeding.');
+
+  return lines.join('\n');
+}
+
+/**
+ * Parse `morph-spec task done <feature> <taskId>` from a bash command string.
+ * Returns { featureName, taskId } or null if the command doesn't match.
+ *
+ * @param {string} command
+ * @returns {{ featureName: string, taskId: string } | null}
+ */
+export function parseTaskDoneCommand(command) {
+  if (!command || typeof command !== 'string') return null;
+  const match = command.match(/morph-spec\s+task\s+done\s+(\S+)\s+(\S+)/);
+  if (!match) return null;
+  return { featureName: match[1], taskId: match[2] };
+}
+
+/**
+ * Parse `morph-spec phase advance <feature>` from a bash command string.
+ * Returns { featureName } or null if the command doesn't match.
+ *
+ * @param {string} command
+ * @returns {{ featureName: string } | null}
+ */
+export function parsePhaseAdvanceCommand(command) {
+  if (!command || typeof command !== 'string') return null;
+  const match = command.match(/morph-spec\s+phase\s+advance\s+(\S+)/);
+  if (!match) return null;
+  return { featureName: match[1] };
+}
+
+/**
+ * Extract the tool result string from a PostToolUse hook payload.
+ * Handles multiple possible formats.
+ *
+ * @param {object} payload - Hook payload
+ * @returns {string} - Tool output string (empty string if not found)
+ */
+export function getToolOutput(payload) {
+  if (!payload) return '';
+  const result = payload.tool_result;
+  if (typeof result === 'string') return result;
+  if (result && typeof result === 'object') {
+    return result.stdout || result.content || '';
+  }
+  return '';
+}

package/framework/hooks/shared/phase-utils.js

@@ -8,7 +8,7 @@
  */
 
 /** Phase order */
-export const PHASE_ORDER = ["proposal","setup","uiux","design","clarify","tasks","implement","sync"];
+export const PHASE_ORDER = ["proposal","setup","uiux","design","clarify","plan","tasks","implement","sync"];
 
 /** Map phase → allowed output subdirectory */
 export const PHASE_DIRS = {
@@ -16,10 +16,11 @@ export const PHASE_DIRS = {
   setup: '0-proposal',
   uiux: '2-ui',
   design: '1-design',
-  clarify: '2-clarify',
-  tasks: '3-tasks',
-  implement: '4-implement',
-  sync: '4-implement',
+  clarify: '1-design',
+  plan: '3-plan',
+  tasks: '4-tasks',
+  implement: '5-implement',
+  sync: '5-implement',
 };
 
 /** Map output type (camelCase) → phase that produces it */
@@ -29,7 +30,9 @@ export const OUTPUT_PHASE_MAP = {
   spec: 'design',
   clarifications: 'clarify',
   contracts: 'design',
+  contractsTs: 'design',
   contractsVsa: 'design',
+  plan: 'plan',
   tasks: 'tasks',
   uiDesignSystem: 'uiux',
   uiMockups: 'uiux',
@@ -46,7 +49,9 @@ export const FILENAME_TO_OUTPUT = {
   'spec.md': 'spec',
   'clarifications.md': 'clarifications',
   'contracts.cs': 'contracts',
+  'contracts.ts': 'contractsTs',
   'contracts-vsa.cs': 'contractsVsa',
+  'plan.md': 'plan',
   'tasks.md': 'tasks',
   'design-system.md': 'uiDesignSystem',
   'mockups.md': 'uiMockups',
@@ -61,7 +66,9 @@ export const PROTECTED_SPEC_FILES = {
   'schema-analysis.md': 'design',
   'spec.md': 'design',
   'contracts.cs': 'design',
+  'contracts.ts': 'design',
   'contracts-vsa.cs': 'design',
+  'plan.md': 'plan',
   'tasks.md': 'tasks',
   'design-system.md': 'uiux',
   'mockups.md': 'uiux',

package/framework/hooks/shared/skill-reminder-helpers.js

@@ -0,0 +1,79 @@
+/**
+ * Pure helper functions for the skill-reminder PostToolUse hook.
+ * Extracted to shared/ so they can be unit-tested without running the hook entry point.
+ */
+
+/**
+ * Parse `morph-spec task start <feature> <taskId>` from a bash command string.
+ * Returns { featureName, taskId } or null if the command doesn't match.
+ *
+ * @param {string} command
+ * @returns {{ featureName: string, taskId: string } | null}
+ */
+export function parseTaskStartCommand(command) {
+  if (!command || typeof command !== 'string') return null;
+  const match = command.match(/morph-spec\s+task\s+start\s+(\S+)\s+(\S+)/);
+  if (!match) return null;
+  return { featureName: match[1], taskId: match[2] };
+}
+
+/**
+ * Build the mandatory skill reminder message for a task start event.
+ * Returns null if no relevant skills exist for this phase at task-start time.
+ *
+ * Relevant triggers:
+ *   - beforeEachTask   → invoke NOW before writing any code
+ *   - beforeTaskDone   → invoke BEFORE marking task done
+ *   - onBugOrUnexpected → invoke IF a bug is encountered
+ *
+ * @param {string} featureName
+ * @param {string} taskId
+ * @param {string} phase
+ * @param {Object|null} phasesData - Parsed phases.json content
+ * @returns {string|null}
+ */
+export function buildSkillReminderMessage(featureName, taskId, phase, phasesData) {
+  try {
+    const allSkills = phasesData?.phases?.[phase]?.requiredSkills;
+    if (!allSkills || allSkills.length === 0) return null;
+
+    const nowSkills   = allSkills.filter(s => s.trigger === 'beforeEachTask');
+    const laterSkills = allSkills.filter(s => s.trigger === 'beforeTaskDone');
+    const bugSkills   = allSkills.filter(s => s.trigger === 'onBugOrUnexpected');
+
+    if (nowSkills.length === 0 && laterSkills.length === 0) return null;
+
+    const lines = [];
+    lines.push(`⚠️  MORPH-SPEC SKILL REMINDER — Task ${taskId} started (phase: ${phase})`);
+    lines.push('');
+
+    if (nowSkills.length > 0) {
+      lines.push('INVOKE NOW before writing any code:');
+      for (const s of nowSkills) {
+        lines.push(`  → Skill(${s.skill})`);
+      }
+      lines.push('');
+    }
+
+    if (laterSkills.length > 0) {
+      lines.push('INVOKE BEFORE marking task done:');
+      for (const s of laterSkills) {
+        lines.push(`  → Skill(${s.skill})`);
+      }
+      lines.push('');
+    }
+
+    if (bugSkills.length > 0) {
+      lines.push('IF you encounter a bug or unexpected behavior:');
+      for (const s of bugSkills) {
+        lines.push(`  → Skill(${s.skill})`);
+      }
+      lines.push('');
+    }
+
+    lines.push('These are MANDATORY. Use the Skill() tool. Do NOT skip.');
+    return lines.join('\n');
+  } catch {
+    return null;
+  }
+}

package/framework/hooks/shared/stale-task-reset.js

@@ -0,0 +1,57 @@
+/**
+ * Stale Task Reset — shared hook utility
+ *
+ * Detects tasks stuck in `in_progress` for longer than STALE_MS and resets
+ * them to `pending`. Works for both v2 (tasks is array) and v3 (taskList)
+ * state formats. Pure function: mutates state in-place, returns reset log.
+ *
+ * Stale threshold: 1 hour (hardcoded — not user-configurable)
+ */
+
+export const STALE_MS = 60 * 60 * 1000; // 1 hour
+
+/**
+ * Determine if a task is stale (in_progress for longer than STALE_MS).
+ * @param {Object} task
+ * @param {number} [now] - timestamp for testability (defaults to Date.now())
+ * @returns {boolean}
+ */
+export function isStaleTask(task, now = Date.now()) {
+  if (task.status !== 'in_progress') return false;
+  if (!task.startedAt) return true; // missing timestamp → treat as stale
+  return now - new Date(task.startedAt).getTime() > STALE_MS;
+}
+
+/**
+ * Reset all stale in_progress tasks across all features in state.
+ * Mutates state in-place. Returns log of reset task identifiers.
+ *
+ * @param {Object} state - Full state object (state.features)
+ * @param {number} [now] - Timestamp for testability
+ * @returns {string[]} resetLog — entries like "feature-name/T008"
+ */
+export function resetStaleTasks(state, now = Date.now()) {
+  const resetLog = [];
+
+  for (const [featureName, feature] of Object.entries(state.features || {})) {
+    // Resolve task list for both v2 (array) and v3 (taskList) formats
+    const isV2 = Array.isArray(feature.tasks);
+    const list = isV2 ? feature.tasks : (feature.taskList || []);
+
+    for (const task of list) {
+      if (isStaleTask(task, now)) {
+        task.status = 'pending';
+        delete task.startedAt;
+        resetLog.push(`${featureName}/${task.id ?? '(unknown)'}`);
+      }
+    }
+
+    // Re-sync counters (v3 only — v2 tasks IS the list, no separate counters)
+    if (!isV2 && feature.tasks) {
+      feature.tasks.inProgress = list.filter(t => t.status === 'in_progress').length;
+      feature.tasks.pending = list.filter(t => t.status === 'pending').length;
+    }
+  }
+
+  return resetLog;
+}

package/framework/hooks/shared/state-reader.js

@@ -62,6 +62,30 @@ export function getActiveFeature(projectPath) {
   return active;
 }
 
+/**
+ * Get the most recently updated feature (any status).
+ * Useful as a fallback when getActiveFeature returns null (all features done).
+ * @param {string} [projectPath]
+ * @returns {{ name: string, feature: Object }|null}
+ */
+export function getMostRecentFeature(projectPath) {
+  const state = loadState(projectPath);
+  if (!state?.features) return null;
+
+  let result = null;
+  let latestUpdate = '';
+
+  for (const [name, feature] of Object.entries(state.features)) {
+    const updated = feature.updatedAt || feature.createdAt || '';
+    if (updated >= latestUpdate) {
+      latestUpdate = updated;
+      result = { name, feature };
+    }
+  }
+
+  return result;
+}
+
 /**
  * Get a specific feature by name.
  * @param {string} featureName
@@ -74,7 +98,7 @@ export function getFeature(featureName, projectPath) {
 }
 
 /**
- * Derive phase from filesystem (v5.0.0+: phase deleted from state).
+ * Derive phase from filesystem (phase deleted from state).
  * Checks for phase folders in descending order, returns highest present.
  * @param {string} featureName
  * @param {string} [projectPath]
@@ -83,9 +107,9 @@ export function getFeature(featureName, projectPath) {
 export function derivePhaseForFeature(featureName, projectPath) {
   const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
   const phaseMap = [
-    ['4-implement', 'implement'],
-    ['3-tasks', 'tasks'],
-    ['2-clarify', 'clarify'],
+    ['5-implement', 'implement'],
+    ['4-tasks', 'tasks'],
+    ['3-plan', 'plan'],
     ['2-ui', 'uiux'],
     ['1-design', 'design'],
     ['0-proposal', 'proposal'],
@@ -98,7 +122,7 @@ export function derivePhaseForFeature(featureName, projectPath) {
 
 /**
  * Get the current phase of a feature.
- * Falls back to filesystem derivation when phase is not in state (v5.0.0+).
+ * Falls back to filesystem derivation when phase is not in state.
  * @param {string} featureName
  * @param {string} [projectPath]
  * @returns {string|null}

package/framework/hooks/shared/worktree-helpers.js

@@ -0,0 +1,53 @@
+/**
+ * Shared helpers for worktree-related hook logic.
+ * Pure functions — no side effects, easy to test.
+ */
+
+/**
+ * Parse JSON output from `morph-spec worktree setup`.
+ * Finds the last line starting with '{' to skip chalk-colored output.
+ * @param {string} stdout - Raw stdout from the command
+ * @returns {Object|null}
+ */
+export function parseWorktreeResult(stdout) {
+  if (!stdout || typeof stdout !== 'string') return null;
+  try {
+    const trimmed = stdout.trim();
+    if (!trimmed) return null;
+    const lines = trimmed.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (line.startsWith('{')) {
+        return JSON.parse(line);
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build context line(s) to inject based on worktree setup result.
+ * @param {Object|null} result - Parsed result from parseWorktreeResult
+ * @returns {string} Context lines to inject, or '' to skip injection
+ */
+export function buildWorktreeContextLine(result) {
+  if (!result) return '';
+  if (result.error) return '';
+
+  if (result.created) {
+    return `🪴 Worktree created: Working in .worktrees/${result.feature || ''} on branch ${result.branch}`;
+  }
+
+  if (result.alreadyExists) {
+    return [
+      `⚠️  Existing worktree found for feature '${result.feature}': ${result.path} (branch: ${result.branch})`,
+      `   Use AskUserQuestion to ask: "resume existing worktree or start fresh (--fresh)?"`,
+      `   • Resume: continue in existing worktree (no change)`,
+      `   • Fresh: run \`morph-spec worktree setup ${result.feature} --fresh\``
+    ].join('\n');
+  }
+
+  return '';
+}

package/framework/phases.json

@@ -17,7 +17,10 @@
       "pausePoints": [
         { "id": "proposal", "label": "Approve Proposal" }
       ],
-      "agentTiers": [1]
+      "agentTiers": [1],
+      "requiredSkills": [
+        { "trigger": "beforePhaseStart", "skill": "morph:brainstorming" }
+      ]
     },
     "setup": {
       "id": "setup",
@@ -33,7 +36,8 @@
       "optionalOutputs": [],
       "recommendedMCPs": ["github"],
       "pausePoints": [],
-      "agentTiers": [1, 2]
+      "agentTiers": [1, 2],
+      "requiredSkills": []
     },
     "uiux": {
       "id": "uiux",
@@ -52,7 +56,12 @@
       "pausePoints": [
         { "id": "uiux", "label": "Approve UI/UX Design" }
       ],
-      "agentTiers": [1, 2, 3]
+      "agentTiers": [1, 2, 3],
+      "requiredSkills": [
+        { "trigger": "beforeArchitecturalDecision", "skill": "morph:brainstorming" },
+        { "trigger": "onHTMLPrototypeAvailable",    "skill": "morph:replicate" },
+        { "trigger": "beforePhaseComplete",         "skill": "morph:frontend-review" }
+      ]
     },
     "design": {
       "id": "design",
@@ -71,7 +80,14 @@
       "pausePoints": [
         { "id": "design", "label": "Approve Design Spec" }
       ],
-      "agentTiers": [1, 2, 3, 4]
+      "agentTiers": [1, 2, 3, 4],
+      "requiredSkills": [
+        { "trigger": "beforePhaseStart",             "skill": "morph:phase-design" },
+        { "trigger": "beforePhaseStart",             "skill": "morph:phase-codebase-analysis" },
+        { "trigger": "beforeArchitecturalDecision",  "skill": "morph:brainstorming" },
+        { "trigger": "onExternalServiceIntegration", "skill": "morph:simulation-checklist" },
+        { "trigger": "beforePhaseComplete",          "skill": "morph:verification-before-completion" }
+      ]
     },
     "clarify": {
       "id": "clarify",
@@ -87,12 +103,38 @@
       "optionalOutputs": [],
       "recommendedMCPs": ["context7", "github"],
       "pausePoints": [],
-      "agentTiers": [1, 2]
+      "agentTiers": [1, 2],
+      "requiredSkills": [
+        { "trigger": "beforePhaseStart",    "skill": "morph:phase-clarify" },
+        { "trigger": "beforePhaseComplete", "skill": "morph:verification-before-completion" }
+      ]
+    },
+    "plan": {
+      "id": "plan",
+      "index": 5,
+      "folder": "3-plan",
+      "displayName": "Implementation Plan",
+      "goals": [
+        "Create detailed implementation plan with exact file paths and code",
+        "Define bite-sized TDD tasks with test-first approach",
+        "Establish execution strategy based on project analysis"
+      ],
+      "requiredOutputs": ["plan"],
+      "optionalOutputs": [],
+      "recommendedMCPs": ["context7", "github"],
+      "pausePoints": [
+        { "id": "plan", "label": "Approve Implementation Plan" }
+      ],
+      "agentTiers": [1, 2],
+      "requiredSkills": [
+        { "trigger": "beforePhaseStart",    "skill": "morph:phase-plan" },
+        { "trigger": "beforePhaseComplete", "skill": "morph:verification-before-completion" }
+      ]
     },
     "tasks": {
       "id": "tasks",
-      "index": 4,
-      "folder": "3-tasks",
+      "index": 6,
+      "folder": "4-tasks",
       "displayName": "Task Breakdown",
       "goals": [
         "Break approved spec into numbered, atomic tasks",
@@ -105,12 +147,16 @@
       "pausePoints": [
         { "id": "tasks", "label": "Approve Task List" }
       ],
-      "agentTiers": [1, 2, 3]
+      "agentTiers": [1, 2, 3],
+      "requiredSkills": [
+        { "trigger": "onParallelTasksIdentified", "skill": "superpowers:dispatching-parallel-agents" },
+        { "trigger": "beforePhaseComplete",       "skill": "morph:verification-before-completion" }
+      ]
     },
     "implement": {
       "id": "implement",
-      "index": 5,
-      "folder": "4-implement",
+      "index": 7,
+      "folder": "5-implement",
       "displayName": "Implementation",
       "goals": [
         "Execute approved tasks in order",
@@ -120,13 +166,21 @@
       ],
       "requiredOutputs": ["recap"],
       "optionalOutputs": [],
-      "recommendedMCPs": ["supabase", "context7", "playwright", "github", "docker", "azure"],
+      "recommendedMCPs": ["supabase", "context7", "playwright", "github", "vercel", "docker", "azure"],
       "pausePoints": [],
-      "agentTiers": [1, 2, 3, 4]
+      "agentTiers": [1, 2, 3, 4],
+      "requiredSkills": [
+        { "trigger": "beforeEachTask",    "skill": "superpowers:test-driven-development" },
+        { "trigger": "beforeTaskDone",    "skill": "morph:verification-before-completion" },
+        { "trigger": "onBugOrUnexpected", "skill": "superpowers:systematic-debugging" },
+        { "trigger": "afterAllTasks",     "skill": "morph:post-implementation" },
+        { "trigger": "afterAllTasks",     "skill": "superpowers:requesting-code-review" },
+        { "trigger": "beforePR",          "skill": "morph:checklist" }
+      ]
     },
     "sync": {
       "id": "sync",
-      "index": 6,
+      "index": 8,
       "folder": null,
       "displayName": "Sync Standards",
       "optional": true,
@@ -139,7 +193,8 @@
       "optionalOutputs": [],
       "recommendedMCPs": [],
       "pausePoints": [],
-      "agentTiers": [1]
+      "agentTiers": [1],
+      "requiredSkills": []
     }
   }
 }