@polymorphism-tech/morph-spec 4.9.0 → 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 */
@@ -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/morph-workflow.md

@@ -1,86 +1,88 @@
-# MORPH-SPEC Workflow Rules
-
-> Always-active rules for all MORPH-SPEC managed projects.
-
----
-
-## Spec-First Mandate
-
-**NEVER skip to code without a specification.** Every feature must progress through phases:
-
-1. **Proposal** — User story + acceptance criteria (`0-proposal/proposal.md`)
-2. **Design** — Technical spec + C# contracts + decisions (`1-design/`)
-3. **Tasks** — Atomic task list (`3-tasks/tasks.md`)
-4. **Implement** — Code + recap (`4-implement/recap.md`)
-
-UI-heavy features also include **UI/UX** phase (`2-ui/`) between Design and Tasks.
-
----
-
-## Phase Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
-| `/morph-apply {feature}` | Implement feature (phase 5) |
-| `/morph-status` | Feature dashboard |
-
----
-
-## Output Paths
-
-All outputs go in `.morph/features/{feature}/`:
-
-| Phase | Path |
-|-------|------|
-| Proposal | `0-proposal/proposal.md` |
-| Spec | `1-design/spec.md` |
-| Contracts | `1-design/contracts.cs` |
-| Decisions | `1-design/decisions.md` |
-| UI Design | `2-ui/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
-| Tasks | `3-tasks/tasks.md` |
-| Recap | `4-implement/recap.md` |
-
----
-
-## Checkpoints
-
-Run a checkpoint every 3 completed tasks:
-- Validate architecture compliance
-- Check package versions
-- Scan for security issues
-- Verify design system adherence (UI features)
-
----
-
-## Approval Gates
-
-**Design Gate:** Before moving from Design → Tasks, spec must be approved.
-**Implementation Gate:** Before starting implementation, task list must be approved.
-
-Check approval status: `morph-spec approval-status {feature}`
-
----
-
-## Protected Files
-
-**NEVER directly edit:**
-- `.morph/state.json` — Managed by CLI only
-- `.morph/framework/**` — Read-only framework content
-
----
-
-## Test File Policy
-
-When a test fails, always follow this order:
-
-1. **Analyze first** — determine if the IMPLEMENTATION is wrong or the TEST SPEC is wrong
-2. **Fix implementation first** — the test is the spec; trust it by default
-3. **Only modify a test file if the test expectation itself is incorrect** — wrong expected value, wrong behavior modeled
-4. **Before modifying any test file, explain WHY the test spec is wrong** — what the correct behavior is and why the test doesn't model it
-
-Do not modify test files to make a failing test pass when the implementation is the actual problem.
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# MORPH-SPEC Workflow Rules
+
+> Always-active rules for all MORPH-SPEC managed projects.
+
+---
+
+## Spec-First Mandate
+
+**NEVER skip to code without a specification.** Every feature must progress through phases:
+
+1. **Proposal** — User story + acceptance criteria (`0-proposal/proposal.md`)
+2. **Design** — Technical spec + C# contracts + decisions (`1-design/`)
+3. **Plan** — Detailed implementation plan (`3-plan/plan.md`)
+4. **Tasks** — Atomic task list (`4-tasks/tasks.md`)
+5. **Implement** — Code + recap (`5-implement/recap.md`)
+
+UI-heavy features also include **UI/UX** phase (`2-ui/`) between Design and Tasks.
+
+---
+
+## Phase Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
+| `/morph-apply {feature}` | Implement feature (phase 5) |
+| `/morph-status` | Feature dashboard |
+
+---
+
+## Output Paths
+
+All outputs go in `.morph/features/{feature}/`:
+
+| Phase | Path |
+|-------|------|
+| Proposal | `0-proposal/proposal.md` |
+| Spec | `1-design/spec.md` |
+| Contracts | `1-design/contracts.cs` |
+| Decisions | `1-design/decisions.md` |
+| UI Design | `2-ui/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
+| Plan | `3-plan/plan.md` |
+| Tasks | `4-tasks/tasks.md` |
+| Recap | `5-implement/recap.md` |
+
+---
+
+## Checkpoints
+
+Run a checkpoint every 3 completed tasks:
+- Validate architecture compliance
+- Check package versions
+- Scan for security issues
+- Verify design system adherence (UI features)
+
+---
+
+## Approval Gates
+
+**Design Gate:** Before moving from Design → Tasks, spec must be approved.
+**Implementation Gate:** Before starting implementation, task list must be approved.
+
+Check approval status: `morph-spec approval-status {feature}`
+
+---
+
+## Protected Files
+
+**NEVER directly edit:**
+- `.morph/state.json` — Managed by CLI only
+- `.morph/framework/**` — Read-only framework content
+
+---
+
+## Test File Policy
+
+When a test fails, always follow this order:
+
+1. **Analyze first** — determine if the IMPLEMENTATION is wrong or the TEST SPEC is wrong
+2. **Fix implementation first** — the test is the spec; trust it by default
+3. **Only modify a test file if the test expectation itself is incorrect** — wrong expected value, wrong behavior modeled
+4. **Before modifying any test file, explain WHY the test spec is wrong** — what the correct behavior is and why the test doesn't model it
+
+Do not modify test files to make a failing test pass when the implementation is the actual problem.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*