@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * UserPromptSubmit Hook: Enrich User Prompts with Context
+ *
+ * Event: UserPromptSubmit
+ *
+ * Scans user prompt for morph-spec keywords and injects relevant context:
+ *   - Feature name mentioned → inject its current status/phase
+ *   - "implement"/"code" while not in implement phase → warn about wrong phase
+ *   - "approve"/"looks good" → inject approval command syntax
+ *   - "next task" → inject current task list
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, loadState, getActiveFeature, getFeature, getPendingGates } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const userPrompt = payload?.user_prompt || payload?.content || '';
+  if (!userPrompt || userPrompt.length < 3) pass();
+
+  const promptLower = userPrompt.toLowerCase();
+  const state = loadState();
+  if (!state?.features) pass();
+
+  const context = [];
+
+  // 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}`);
+      if (feature.tasks?.total > 0) {
+        context.push(`  Tasks: ${feature.tasks.completed || 0}/${feature.tasks.total} completed`);
+      }
+      break; // Only inject for the first matched feature
+    }
+  }
+
+  // Check for implement/code intent while not in implement phase
+  const active = getActiveFeature();
+  if (active) {
+    const { name, feature } = active;
+
+    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') {
+      context.push(
+        `[morph-spec] WARNING: Feature '${name}' is in '${feature.phase}' phase, not 'implement'.` +
+        ` Complete the current phase first or advance: morph-spec phase advance ${name}`
+      );
+    }
+
+    // Check for approval intent
+    const approvalKeywords = ['approve', 'approved', 'looks good', 'lgtm', 'ship it'];
+    const wantsToApprove = approvalKeywords.some(kw => promptLower.includes(kw));
+
+    if (wantsToApprove) {
+      const pending = getPendingGates(name);
+      if (pending.length > 0) {
+        context.push(
+          `[morph-spec] To approve, use: morph-spec approve ${name} ${pending[0]}`
+        );
+      }
+    }
+
+    // Check for "next task" intent
+    if (promptLower.includes('next task') || promptLower.includes('what\'s next')) {
+      if (feature.phase === 'implement') {
+        context.push(
+          `[morph-spec] Use: morph-spec task next ${name}`
+        );
+      }
+    }
+  }
+
+  if (context.length === 0) pass();
+
+  injectContext(context.join('\n'));
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/shared/hook-response.js

@@ -0,0 +1,45 @@
+/**
+ * Shared hook response builders for Claude Code hooks.
+ *
+ * Claude Code hooks communicate via JSON to stdout.
+ * - PreToolUse: { "decision": "block"|"approve", "reason": "..." }
+ * - SessionStart/Stop/etc: { "additionalContext": "..." }
+ */
+
+/**
+ * Block a tool use with a reason.
+ * @param {string} reason - Human-readable reason for blocking
+ */
+export function block(reason) {
+  console.log(JSON.stringify({ decision: 'block', reason }));
+  process.exit(0);
+}
+
+/**
+ * Approve a tool use, optionally injecting context.
+ * @param {string} [context] - Additional context to inject
+ */
+export function approve(context) {
+  if (context) {
+    console.log(JSON.stringify({ decision: 'approve', additionalContext: context }));
+  }
+  // No output = implicit approve
+  process.exit(0);
+}
+
+/**
+ * Inject additional context (for SessionStart, Stop, UserPromptSubmit, etc.).
+ * @param {string} text - Context text to inject
+ * @param {Object} [extra] - Additional fields to include in response
+ */
+export function injectContext(text, extra = {}) {
+  console.log(JSON.stringify({ additionalContext: text, ...extra }));
+  process.exit(0);
+}
+
+/**
+ * Silent exit — no output, no blocking.
+ */
+export function pass() {
+  process.exit(0);
+}

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

@@ -0,0 +1,129 @@
+// GENERATED by scripts/generate-refs.js — DO NOT EDIT manually
+// Source of truth: src/core/paths/output-schema.js
+// Regenerate with: node scripts/generate-refs.js
+/**
+ * Shared phase utilities for Claude Code hooks.
+ *
+ * Maps phases to directories and output types.
+ */
+
+/** Phase order */
+export const PHASE_ORDER = ["proposal","setup","uiux","design","clarify","tasks","implement","sync"];
+
+/** Map phase → allowed output subdirectory */
+export const PHASE_DIRS = {
+  proposal: '0-proposal',
+  setup: '0-proposal',
+  uiux: '2-ui',
+  design: '1-design',
+  clarify: '1-design',
+  tasks: '3-tasks',
+  implement: '4-implement',
+  sync: '4-implement',
+};
+
+/** Map output type (camelCase) → phase that produces it */
+export const OUTPUT_PHASE_MAP = {
+  proposal: 'proposal',
+  schemaAnalysis: 'design',
+  spec: 'design',
+  clarifications: 'clarify',
+  contracts: 'design',
+  tasks: 'tasks',
+  uiDesignSystem: 'uiux',
+  uiMockups: 'uiux',
+  uiComponents: 'uiux',
+  uiFlows: 'uiux',
+  decisions: 'design',
+  recap: 'implement',
+};
+
+/** Map filename → output type (camelCase) */
+export const FILENAME_TO_OUTPUT = {
+  'proposal.md': 'proposal',
+  'schema-analysis.md': 'schemaAnalysis',
+  'spec.md': 'spec',
+  'clarifications.md': 'clarifications',
+  'contracts.cs': 'contracts',
+  'tasks.md': 'tasks',
+  'design-system.md': 'uiDesignSystem',
+  'mockups.md': 'uiMockups',
+  'components.md': 'uiComponents',
+  'flows.md': 'uiFlows',
+  'decisions.md': 'decisions',
+  'recap.md': 'recap',
+};
+
+/** Protected spec files and the approval gate that locks them */
+export const PROTECTED_SPEC_FILES = {
+  'schema-analysis.md': 'design',
+  'spec.md': 'design',
+  'contracts.cs': 'design',
+  'tasks.md': 'tasks',
+  'design-system.md': 'uiux',
+  'mockups.md': 'uiux',
+  'components.md': 'uiux',
+  'flows.md': 'uiux',
+};
+
+/**
+ * Extract feature name from a .morph/features/{feature}/... path
+ * @param {string} filePath - File path to analyze
+ * @returns {string|null} Feature name or null
+ */
+export function extractFeatureName(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const match = normalized.match(/\.morph\/features\/([^/]+)\//);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract phase subdirectory from a .morph/features/{feature}/{phaseDir}/... path
+ * @param {string} filePath - File path to analyze
+ * @returns {string|null} Phase directory (e.g., '0-proposal', '1-design') or null
+ */
+export function extractPhaseDir(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const match = normalized.match(/\.morph\/features\/[^/]+\/(\d+-[^/]+)\//);
+  return match ? match[1] : null;
+}
+
+/**
+ * Check if a file path is inside .morph/features/
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isFeaturePath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized.includes('.morph/features/');
+}
+
+/**
+ * Check if a file path is inside .morph/framework/ (readonly)
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isFrameworkPath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized.includes('.morph/framework/');
+}
+
+/**
+ * Check if a file path is state.json
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isStatePath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized.endsWith('.morph/state.json');
+}
+
+/**
+ * Get the basename of a file path
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function getBasename(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized.split('/').pop();
+}

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

@@ -0,0 +1,138 @@
+/**
+ * Shared read-only state accessor for Claude Code hooks.
+ *
+ * Wraps state.json reads with fail-open semantics:
+ * - Returns null instead of throwing on missing/corrupt state
+ * - Never writes to state.json (read-only)
+ * - Uses synchronous reads for <100ms performance
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const STATE_FILE = '.morph/state.json';
+
+/**
+ * Load state.json from the project root.
+ * Fail-open: returns null if file missing or corrupt.
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ * @returns {Object|null} State object or null
+ */
+export function loadState(projectPath) {
+  try {
+    const statePath = join(projectPath || process.cwd(), STATE_FILE);
+    if (!existsSync(statePath)) return null;
+    return JSON.parse(readFileSync(statePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if state.json exists.
+ * @param {string} [projectPath]
+ * @returns {boolean}
+ */
+export function stateExists(projectPath) {
+  return existsSync(join(projectPath || process.cwd(), STATE_FILE));
+}
+
+/**
+ * Get the active feature (most recently updated in_progress feature).
+ * @param {string} [projectPath]
+ * @returns {{ name: string, feature: Object }|null}
+ */
+export function getActiveFeature(projectPath) {
+  const state = loadState(projectPath);
+  if (!state?.features) return null;
+
+  let active = null;
+  let latestUpdate = '';
+
+  for (const [name, feature] of Object.entries(state.features)) {
+    if (feature.status === 'in_progress' || feature.status === 'draft') {
+      const updated = feature.updatedAt || feature.createdAt || '';
+      if (updated >= latestUpdate) {
+        latestUpdate = updated;
+        active = { name, feature };
+      }
+    }
+  }
+
+  return active;
+}
+
+/**
+ * Get a specific feature by name.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {Object|null}
+ */
+export function getFeature(featureName, projectPath) {
+  const state = loadState(projectPath);
+  return state?.features?.[featureName] || null;
+}
+
+/**
+ * Get the current phase of a feature.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string|null}
+ */
+export function getFeaturePhase(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  return feature?.phase || null;
+}
+
+/**
+ * Get approval status for a gate.
+ * @param {string} featureName
+ * @param {string} gate - 'proposal'|'uiux'|'design'|'tasks'
+ * @param {string} [projectPath]
+ * @returns {boolean}
+ */
+export function isGateApproved(featureName, gate, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  return feature?.approvalGates?.[gate]?.approved === true;
+}
+
+/**
+ * Get all pending approval gates for a feature.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string[]} List of gate names that are not yet approved
+ */
+export function getPendingGates(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  if (!feature?.approvalGates) return [];
+
+  return Object.entries(feature.approvalGates)
+    .filter(([, gate]) => !gate.approved)
+    .map(([name]) => name);
+}
+
+/**
+ * Get feature outputs status.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {Object|null} outputs map or null
+ */
+export function getOutputs(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  return feature?.outputs || null;
+}
+
+/**
+ * Get uncompleted required outputs for current phase.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {Array<{type: string, path: string}>}
+ */
+export function getMissingOutputs(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  if (!feature?.outputs) return [];
+
+  return Object.entries(feature.outputs)
+    .filter(([, output]) => !output.created)
+    .map(([type, output]) => ({ type, path: output.path }));
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Shared stdin reader for Claude Code hooks.
+ *
+ * Reads JSON payload from stdin (provided by Claude Code to hooks).
+ * Returns parsed object or null on failure.
+ */
+
+/**
+ * Read and parse JSON from stdin
+ * @returns {Promise<Object|null>} Parsed JSON or null
+ */
+export function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input || '{}'));
+      } catch {
+        resolve(null);
+      }
+    });
+    process.stdin.on('error', () => resolve(null));
+  });
+}

package/framework/phases.json

@@ -0,0 +1,145 @@
+{
+  "version": "1.0.0",
+  "phases": {
+    "proposal": {
+      "id": "proposal",
+      "index": 0,
+      "folder": "0-proposal",
+      "displayName": "Proposal",
+      "goals": [
+        "Understand the feature scope",
+        "Agree on high-level approach",
+        "Produce initial proposal document"
+      ],
+      "requiredOutputs": ["proposal"],
+      "optionalOutputs": [],
+      "recommendedMCPs": ["context7"],
+      "pausePoints": [
+        { "id": "proposal", "label": "Approve Proposal" }
+      ],
+      "agentTiers": [1]
+    },
+    "setup": {
+      "id": "setup",
+      "index": 1,
+      "folder": null,
+      "displayName": "Setup",
+      "goals": [
+        "Load project context from .morph/context/",
+        "Activate relevant agents by tier and keyword",
+        "Confirm workflow type (fast-track / standard / full-morph)"
+      ],
+      "requiredOutputs": [],
+      "optionalOutputs": [],
+      "recommendedMCPs": ["github"],
+      "pausePoints": [],
+      "agentTiers": [1, 2]
+    },
+    "uiux": {
+      "id": "uiux",
+      "index": 1.5,
+      "folder": "2-ui",
+      "displayName": "UI/UX Design",
+      "optional": true,
+      "goals": [
+        "Define visual design and design system",
+        "Create component inventory and style guide",
+        "Produce wireframes and user flows"
+      ],
+      "requiredOutputs": ["uiDesignSystem"],
+      "optionalOutputs": ["uiMockups", "uiComponents", "uiFlows"],
+      "recommendedMCPs": ["playwright", "context7"],
+      "pausePoints": [
+        { "id": "uiux", "label": "Approve UI/UX Design" }
+      ],
+      "agentTiers": [1, 2, 3]
+    },
+    "design": {
+      "id": "design",
+      "index": 2,
+      "folder": "1-design",
+      "displayName": "Technical Design",
+      "goals": [
+        "Write technical specification",
+        "Define C# contracts and interfaces",
+        "Analyse schema changes",
+        "Document architectural decisions"
+      ],
+      "requiredOutputs": ["spec", "contracts"],
+      "optionalOutputs": ["schemaAnalysis", "clarifications", "decisions"],
+      "recommendedMCPs": ["supabase", "context7", "github"],
+      "pausePoints": [
+        { "id": "design", "label": "Approve Design Spec" }
+      ],
+      "agentTiers": [1, 2, 3, 4]
+    },
+    "clarify": {
+      "id": "clarify",
+      "index": 3,
+      "folder": "1-design",
+      "displayName": "Clarification",
+      "goals": [
+        "Resolve open questions and ambiguities",
+        "Update spec with clarification decisions",
+        "Confirm edge cases are handled"
+      ],
+      "requiredOutputs": ["clarifications"],
+      "optionalOutputs": [],
+      "recommendedMCPs": ["context7", "github"],
+      "pausePoints": [],
+      "agentTiers": [1, 2]
+    },
+    "tasks": {
+      "id": "tasks",
+      "index": 4,
+      "folder": "3-tasks",
+      "displayName": "Task Breakdown",
+      "goals": [
+        "Break approved spec into numbered, atomic tasks",
+        "Order tasks by dependency",
+        "Assign tasks to agent tiers"
+      ],
+      "requiredOutputs": ["tasks"],
+      "optionalOutputs": [],
+      "recommendedMCPs": ["context7", "github"],
+      "pausePoints": [
+        { "id": "tasks", "label": "Approve Task List" }
+      ],
+      "agentTiers": [1, 2, 3]
+    },
+    "implement": {
+      "id": "implement",
+      "index": 5,
+      "folder": "4-implement",
+      "displayName": "Implementation",
+      "goals": [
+        "Execute approved tasks in order",
+        "Follow framework standards at each step",
+        "Checkpoint every 3 tasks",
+        "Write implementation recap"
+      ],
+      "requiredOutputs": ["recap"],
+      "optionalOutputs": [],
+      "recommendedMCPs": ["supabase", "context7", "playwright", "github", "docker", "azure"],
+      "pausePoints": [],
+      "agentTiers": [1, 2, 3, 4]
+    },
+    "sync": {
+      "id": "sync",
+      "index": 6,
+      "folder": null,
+      "displayName": "Sync Standards",
+      "optional": true,
+      "goals": [
+        "Update framework standards from feature learnings",
+        "Capture new patterns to learning library",
+        "Archive completed feature"
+      ],
+      "requiredOutputs": [],
+      "optionalOutputs": [],
+      "recommendedMCPs": [],
+      "pausePoints": [],
+      "agentTiers": [1]
+    }
+  }
+}

package/framework/rules/csharp-standards.md

@@ -0,0 +1,10 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csproj"
+---
+
+# C# and .NET Standards
+
+@.morph/framework/standards/core/coding.md
+@.morph/framework/standards/backend/dotnet/core.md

package/framework/rules/frontend-standards.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "**/*.razor"
+  - "**/*.tsx"
+  - "**/*.ts"
+  - "**/*.css"
+  - "**/*.scss"
+---
+
+# Frontend Standards
+
+@.morph/framework/standards/frontend/blazor/design-checklist.md
+@.morph/framework/standards/frontend/nextjs/nextjs-patterns.md
+@.morph/framework/standards/frontend/design-system/naming.md

package/framework/rules/infrastructure-standards.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "**/*.bicep"
+  - "**/Dockerfile"
+  - "**/docker-compose*.yml"
+  - "**/pipelines/**"
+  - "**/.github/workflows/**"
+---
+
+# Infrastructure Standards
+
+@.morph/framework/standards/infrastructure/azure/azure.md
+@.morph/framework/standards/infrastructure/docker/easypanel-deploy.md