@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

package/framework/hooks/claude-code/session-start/post-compact-restore.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart Hook: Post-Compact Context Restore
+ *
+ * Event: SessionStart | Matcher: compact
+ *
+ * Fires ONLY when a session starts after context compaction.
+ * Reads the latest pre-compact memory file and injects the richContext
+ * block (decisions.md snippet + task list) so Claude resumes with full
+ * morph awareness even if the compact summary was truncated.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { buildRestoreBlock, findLatestMemoryFile } from '../../shared/compact-restore.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const memoryDir = join(process.cwd(), '.morph', 'memory');
+  if (!existsSync(memoryDir)) pass();
+
+  const files = readdirSync(memoryDir);
+  const latest = findLatestMemoryFile(files);
+  if (!latest) pass();
+
+  const raw = readFileSync(join(memoryDir, latest), 'utf-8');
+  const snapshot = JSON.parse(raw);
+
+  const block = buildRestoreBlock(snapshot);
+  if (!block) pass();
+
+  injectContext(block);
+} catch {
+  process.exit(0);
+}

package/framework/hooks/claude-code/stop/validate-completion.js

@@ -21,7 +21,7 @@
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import {
-  stateExists, loadState, getActiveFeature, getMissingOutputs, derivePhaseForFeature,
+  stateExists, getActiveFeature, getMostRecentFeature, getMissingOutputs, derivePhaseForFeature,
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
@@ -40,20 +40,7 @@ try {
 
   // getActiveFeature() only returns in_progress/draft features.
   // Fall back to the most recently updated feature when all features are 'done'.
-  let active = getActiveFeature();
-  if (!active) {
-    const state = loadState();
-    if (state?.features) {
-      let latestUpdate = '';
-      for (const [name, feature] of Object.entries(state.features)) {
-        const updated = feature.updatedAt || feature.createdAt || '';
-        if (updated >= latestUpdate) {
-          latestUpdate = updated;
-          active = { name, feature };
-        }
-      }
-    }
-  }
+  let active = getActiveFeature() || getMostRecentFeature();
   if (!active) pass();
 
   const { name, feature } = active;

package/framework/hooks/claude-code/user-prompt/enrich-prompt.js

@@ -15,7 +15,7 @@
  */
 
 import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists, loadState, getActiveFeature, getFeature, getPendingGates } from '../../shared/state-reader.js';
+import { stateExists, loadState, getActiveFeature, getFeature, getPendingGates, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 
@@ -37,7 +37,8 @@ try {
   // Check if a feature name is mentioned
   for (const [featureName, feature] of Object.entries(state.features)) {
     if (promptLower.includes(featureName.toLowerCase())) {
-      context.push(`[morph-spec] Feature '${featureName}': phase=${feature.phase}, status=${feature.status}`);
+      const featurePhase = feature.phase || derivePhaseForFeature(featureName);
+      context.push(`[morph-spec] Feature '${featureName}': phase=${featurePhase}, status=${feature.status}`);
       if (feature.tasks?.total > 0) {
         context.push(`  Tasks: ${feature.tasks.completed || 0}/${feature.tasks.total} completed`);
       }
@@ -50,16 +51,33 @@ try {
   if (active) {
     const { name, feature } = active;
 
+    const activePhase = feature.phase || derivePhaseForFeature(name);
     const codeKeywords = ['implement', 'code', 'start coding', 'write the code', 'build it', 'let\'s build'];
     const wantsToCode = codeKeywords.some(kw => promptLower.includes(kw));
 
-    if (wantsToCode && feature.phase !== 'implement' && feature.phase !== 'sync') {
+    if (wantsToCode && activePhase !== 'implement' && activePhase !== 'sync') {
       context.push(
-        `[morph-spec] WARNING: Feature '${name}' is in '${feature.phase}' phase, not 'implement'.` +
+        `[morph-spec] WARNING: Feature '${name}' is in '${activePhase}' phase, not 'implement'.` +
         ` Complete the current phase first or advance: morph-spec phase advance ${name}`
       );
     }
 
+    // Coding intent during implement phase but no task in_progress
+    if (wantsToCode && activePhase === 'implement') {
+      let hasActiveTask = feature.tasks?.inProgress > 0;
+      if (!hasActiveTask && feature.taskList) {
+        hasActiveTask = feature.taskList.some(t => t.status === 'in_progress');
+      }
+      if (!hasActiveTask) {
+        context.push(
+          `[morph-spec] REMINDER: No task is currently in_progress for '${name}'.` +
+          ` Start a task before coding:\n` +
+          `  npx morph-spec task next ${name}        # see what's next\n` +
+          `  npx morph-spec task start ${name} <id>   # mark it in progress`
+        );
+      }
+    }
+
     // Check for approval intent
     const approvalKeywords = ['approve', 'approved', 'looks good', 'lgtm', 'ship it'];
     const wantsToApprove = approvalKeywords.some(kw => promptLower.includes(kw));
@@ -75,7 +93,7 @@ try {
 
     // Check for "next task" intent
     if (promptLower.includes('next task') || promptLower.includes('what\'s next')) {
-      if (feature.phase === 'implement') {
+      if (activePhase === 'implement') {
         context.push(
           `[morph-spec] Use: morph-spec task next ${name}`
         );

package/framework/hooks/shared/compact-restore.js

@@ -0,0 +1,100 @@
+/**
+ * Shared helpers for post-compact context restoration.
+ *
+ * Used by:
+ *   - pre-compact hook: buildRichContext() to enrich memory file
+ *   - post-compact-restore hook: buildRestoreBlock() + findLatestMemoryFile() to inject context
+ *
+ * Pure functions — no I/O.
+ */
+
+export const DECISIONS_MAX_CHARS = 1500;
+export const MAX_PENDING_TASKS   = 8;
+
+/**
+ * Build the richContext object to embed in pre-compact memory file.
+ * @param {Object} feature          - Feature state object (tasks, taskList)
+ * @param {string} phase            - Current derived phase string
+ * @param {string} decisionsContent - Raw text of decisions.md (may be empty string)
+ * @returns {Object} richContext
+ */
+export function buildRichContext(feature, phase, decisionsContent) {
+  const taskList = Array.isArray(feature.taskList) ? feature.taskList : [];
+
+  const inProgress = taskList
+    .filter(t => t.status === 'in_progress')
+    .map(t => t.id);
+
+  const nextPending = taskList
+    .filter(t => t.status === 'pending')
+    .slice(0, MAX_PENDING_TASKS)
+    .map(t => ({ id: t.id, title: t.title }));
+
+  const decisionsSnippet = decisionsContent.length > DECISIONS_MAX_CHARS
+    ? decisionsContent.slice(0, DECISIONS_MAX_CHARS)
+    : decisionsContent;
+
+  return {
+    phase,
+    tasks:            feature.tasks || {},
+    decisionsSnippet,
+    inProgress,
+    nextPending,
+  };
+}
+
+/**
+ * Build the context block string to inject in session-start after compact.
+ * @param {Object} memorySnapshot - Parsed pre-compact-*.json file contents
+ * @returns {string|null} Block string, or null if no richContext present
+ */
+export function buildRestoreBlock(memorySnapshot) {
+  const rc = memorySnapshot?.richContext;
+  if (!rc) return null;
+
+  const { timestamp, activeFeature } = memorySnapshot;
+  const { phase, tasks, decisionsSnippet, inProgress, nextPending } = rc;
+
+  const done  = tasks?.completed ?? '?';
+  const total = tasks?.total     ?? '?';
+
+  const lines = [
+    `\uD83D\uDD04 POST-COMPACT RESTORE \u2014 context from pre-compact snapshot (${timestamp})`,
+    `Active feature: ${activeFeature} | Phase: ${phase} | Tasks: ${done}/${total}`,
+  ];
+
+  if (decisionsSnippet) {
+    lines.push('');
+    lines.push('Key decisions (at time of compact):');
+    lines.push(decisionsSnippet);
+  }
+
+  if (inProgress.length > 0) {
+    lines.push('');
+    lines.push(`In progress at compact time: [${inProgress.join(', ')}]`);
+  }
+
+  if (nextPending.length > 0) {
+    lines.push('');
+    lines.push('Next pending at compact time:');
+    for (const t of nextPending) {
+      lines.push(`  [${t.id}] ${t.title}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Find the most recent pre-compact memory file from a list of filenames.
+ * Files named pre-compact-{ISO-timestamp-sanitized}.json — sort descending picks latest.
+ * @param {string[]} filenames - Array of filenames in the memory directory
+ * @returns {string|null} Latest filename, or null if none found
+ */
+export function findLatestMemoryFile(filenames) {
+  const matches = filenames
+    .filter(f => f.startsWith('pre-compact-') && f.endsWith('.json'))
+    .sort()
+    .reverse();
+  return matches.length > 0 ? matches[0] : null;
+}

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 */
@@ -31,6 +32,7 @@ export const OUTPUT_PHASE_MAP = {
   contracts: 'design',
   contractsTs: 'design',
   contractsVsa: 'design',
+  plan: 'plan',
   tasks: 'tasks',
   uiDesignSystem: 'uiux',
   uiMockups: 'uiux',
@@ -49,6 +51,7 @@ export const FILENAME_TO_OUTPUT = {
   'contracts.cs': 'contracts',
   'contracts.ts': 'contractsTs',
   'contracts-vsa.cs': 'contractsVsa',
+  'plan.md': 'plan',
   'tasks.md': 'tasks',
   'design-system.md': 'uiDesignSystem',
   'mockups.md': 'uiMockups',
@@ -65,6 +68,7 @@ export const PROTECTED_SPEC_FILES = {
   '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/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
@@ -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'],

package/framework/phases.json

@@ -82,6 +82,7 @@
       ],
       "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" },
@@ -104,13 +105,36 @@
       "pausePoints": [],
       "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",
@@ -125,15 +149,14 @@
       ],
       "agentTiers": [1, 2, 3],
       "requiredSkills": [
-        { "trigger": "beforePhaseStart",          "skill": "superpowers:writing-plans" },
         { "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",
@@ -143,7 +166,7 @@
       ],
       "requiredOutputs": ["recap"],
       "optionalOutputs": [],
-      "recommendedMCPs": ["supabase", "context7", "playwright", "github", "docker", "azure"],
+      "recommendedMCPs": ["supabase", "context7", "playwright", "github", "vercel", "docker", "azure"],
       "pausePoints": [],
       "agentTiers": [1, 2, 3, 4],
       "requiredSkills": [
@@ -157,7 +180,7 @@
     },
     "sync": {
       "id": "sync",
-      "index": 6,
+      "index": 8,
       "folder": null,
       "displayName": "Sync Standards",
       "optional": true,

package/framework/rules/csharp-standards.md

@@ -2,6 +2,9 @@
 paths:
   - "**/*.cs"
   - "**/*.csproj"
+stacks:
+  - dotnet
+  - blazor
 ---
 
 # C# and .NET Standards

package/framework/rules/frontend-standards.md

@@ -3,6 +3,8 @@ paths:
   - "**/*.razor"
   - "**/*.css"
   - "**/*.scss"
+stacks:
+  - blazor
 ---
 
 # Frontend Standards

package/framework/rules/infrastructure-standards.md

@@ -5,6 +5,9 @@ paths:
   - "**/docker-compose*.yml"
   - "**/pipelines/**"
   - "**/.github/workflows/**"
+stacks:
+  - azure
+  - docker
 ---
 
 # Infrastructure Standards