@polymorphism-tech/morph-spec 4.7.1 → 4.7.2

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

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * Stop Hook: Validate Completion (Advisory)
+ *
+ * Event: Stop
+ *
+ * When Claude stops, checks for incomplete work:
+ *   - In implement phase: checks uncompleted tasks
+ *   - In spec phases: checks required outputs still created: false
+ *   - Returns additionalContext with what remains (advisory, not blocking)
+ *
+ * Uses stop_hook_active env check to prevent infinite loops.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { stateExists, getActiveFeature, getMissingOutputs } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+
+try {
+  // Prevent infinite loop
+  if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
+
+  if (!stateExists()) pass();
+
+  const active = getActiveFeature();
+  if (!active) pass();
+
+  const { name, feature } = active;
+  const warnings = [];
+
+  // Check for incomplete tasks during implement phase
+  if (feature.phase === 'implement' && feature.tasks) {
+    const remaining = (feature.tasks.total || 0) - (feature.tasks.completed || 0);
+    if (remaining > 0) {
+      warnings.push(`${remaining} task(s) remaining for feature '${name}'`);
+      if (feature.tasks.inProgress > 0) {
+        warnings.push(`  ${feature.tasks.inProgress} task(s) still in progress`);
+      }
+    }
+  }
+
+  // Check for missing outputs in spec phases
+  if (['proposal', 'design', 'clarify', 'tasks', 'uiux'].includes(feature.phase)) {
+    const missing = getMissingOutputs(name);
+    if (missing.length > 0) {
+      warnings.push(`Missing outputs for '${name}' (${feature.phase} phase):`);
+      for (const output of missing.slice(0, 5)) {
+        warnings.push(`  - ${output.type}: ${output.path}`);
+      }
+      if (missing.length > 5) {
+        warnings.push(`  ... and ${missing.length - 5} more`);
+      }
+    }
+  }
+
+  // Check pending approval gates
+  if (feature.approvalGates) {
+    const pendingGates = Object.entries(feature.approvalGates)
+      .filter(([, gate]) => !gate.approved && !gate.timestamp)
+      .map(([name]) => name);
+
+    // Only warn about gates relevant to current/past phases
+    const relevantGates = pendingGates.filter(gate => {
+      const gatePhaseMap = { proposal: 'proposal', uiux: 'uiux', design: 'design', tasks: 'tasks' };
+      return gatePhaseMap[gate] !== undefined;
+    });
+
+    if (relevantGates.length > 0) {
+      warnings.push(`Pending approvals: ${relevantGates.join(', ')}`);
+    }
+  }
+
+  if (warnings.length === 0) pass();
+
+  const message = [
+    'MORPH-SPEC: Incomplete work detected:',
+    ...warnings.map(w => `  ${w}`),
+    '',
+    'Resume with: morph-spec status ' + name
+  ].join('\n');
+
+  injectContext(message);
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/.morph/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?.prompt || 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/.morph/framework/hooks/git/commit-msg/conventional-commits.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Scope: universal | Validates commit message format (Conventional Commits)
+# MORPH-SPEC Commit Message Hook
+# Enforces Conventional Commits specification
+
+COMMIT_MSG_FILE="$1"
+COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+# Conventional Commits pattern: type(scope): description
+# Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert
+PATTERN="^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\(.+\))?: .{1,100}"
+
+if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
+  echo "❌ Invalid commit message format!"
+  echo ""
+  echo "Required format: <type>(<scope>): <description>"
+  echo ""
+  echo "Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert"
+  echo ""
+  echo "Examples:"
+  echo "  feat(auth): add JWT refresh token rotation"
+  echo "  fix(api): resolve null reference in UserService"
+  echo "  docs(readme): update installation instructions"
+  echo ""
+  echo "Your message:"
+  echo "  $COMMIT_MSG"
+  echo ""
+  echo "Override with: git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Commit message format valid"
+exit 0

package/.morph/framework/hooks/git/pre-commit/agents.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Scope: universal | Validates agents.json Schema
+# MORPH-SPEC Pre-Commit Hook: Agent Configuration Validation
+# Uses validate-agents.js to check agents.json
+
+echo "🤖 Validating agent configuration..."
+
+# Check if agents.json is being modified
+if git diff --cached --name-only | grep -q 'agents\.json$'; then
+  echo "Detected changes to agents.json"
+
+  # Run validator
+  if ! npx morph-spec validate-agents-skills; then
+    echo ""
+    echo "❌ COMMIT BLOCKED: agents.json validation failed"
+    echo "   Fix errors above before committing"
+    exit 1
+  fi
+
+  echo "✓ agents.json is valid"
+else
+  echo "✓ No changes to agents.json"
+fi
+
+exit 0

package/.morph/framework/hooks/git/pre-commit/orchestrator.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Scope: universal | Orchestrates framework + stack-specific pre-commit hooks
+# MORPH-SPEC Master Pre-Commit Hook
+# Runs universal framework hooks + stack-specific hooks in sequence
+
+echo "╔════════════════════════════════════════════════╗"
+echo "║     MORPH-SPEC PRE-COMMIT VALIDATION           ║"
+echo "╚════════════════════════════════════════════════╝"
+echo ""
+
+FRAMEWORK_HOOKS_DIR="$(dirname "$0")"
+STACK_HOOKS_DIR=".morph/hooks/pre-commit"
+
+HAS_FAILURES=false
+
+# Run framework hooks (universal - all stacks)
+echo "📦 Running framework hooks (universal)..."
+for hook in "$FRAMEWORK_HOOKS_DIR"/*.sh; do
+  # Skip orchestrator itself
+  if [[ "$hook" == */orchestrator.sh ]]; then
+    continue
+  fi
+
+  if [[ -f "$hook" ]]; then
+    hook_name=$(basename "$hook")
+    echo "─────────────────────────────────────────────────"
+    if ! bash "$hook"; then
+      HAS_FAILURES=true
+      echo "❌ Framework hook failed: $hook_name"
+    fi
+    echo ""
+  fi
+done
+
+# Run stack-specific hooks (if exist)
+if [[ -d "$STACK_HOOKS_DIR" ]]; then
+  echo "🎯 Running stack-specific hooks..."
+  for hook in "$STACK_HOOKS_DIR"/*.sh; do
+    if [[ -f "$hook" ]]; then
+      hook_name=$(basename "$hook")
+      echo "─────────────────────────────────────────────────"
+      if ! bash "$hook"; then
+        HAS_FAILURES=true
+        echo "❌ Stack hook failed: $hook_name"
+      fi
+      echo ""
+    fi
+  done
+else
+  echo "ℹ️  No stack-specific hooks found (optional)"
+  echo ""
+fi
+
+echo "═════════════════════════════════════════════════"
+
+if [[ "$HAS_FAILURES" == "true" ]]; then
+  echo "❌ PRE-COMMIT VALIDATION FAILED"
+  echo "   Fix errors above before committing"
+  echo "   Or use: git commit --no-verify to skip"
+  exit 1
+fi
+
+echo "✅ ALL PRE-COMMIT VALIDATIONS PASSED"
+exit 0

package/.morph/framework/hooks/git/pre-commit/specs.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Scope: universal | Validates spec.md required sections
+# MORPH-SPEC Pre-Commit Hook: Spec Validation
+# Validates that spec.md files have required sections
+
+echo "🔍 Validating spec files..."
+
+# Find modified spec.md files
+SPEC_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep 'spec\.md$')
+
+if [ -z "$SPEC_FILES" ]; then
+  echo "✓ No spec files modified"
+  exit 0
+fi
+
+HAS_ERRORS=false
+
+for spec_file in $SPEC_FILES; do
+  echo "Checking: $spec_file"
+
+  # Required sections
+  REQUIRED_SECTIONS=(
+    "## 📋 Metadata"
+    "## 🎯 Overview"
+    "## 🏗️ Technical Design"
+    "## ✅ Acceptance Criteria"
+  )
+
+  for section in "${REQUIRED_SECTIONS[@]}"; do
+    if ! grep -q "$section" "$spec_file"; then
+      echo "  ❌ Missing section: $section"
+      HAS_ERRORS=true
+    fi
+  done
+
+  # Check if has at least one user story or requirement
+  if ! grep -qi "user story\|requirement\|acceptance criteria" "$spec_file"; then
+    echo "  ⚠️  Warning: No user stories or requirements found"
+  fi
+done
+
+if [ "$HAS_ERRORS" = true ]; then
+  echo ""
+  echo "❌ COMMIT BLOCKED: spec.md files are incomplete"
+  echo "   Add missing sections before committing"
+  exit 1
+fi
+
+echo "✓ All spec files are valid"
+exit 0

package/.morph/framework/hooks/git/pre-push/run-tests.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Scope: universal | Runs test suite before push
+# MORPH-SPEC Pre-Push Hook
+# Ensures all tests pass before pushing to remote
+
+echo "🧪 Running test suite before push..."
+echo ""
+
+# Detect project type and run appropriate tests
+if [[ -f *.csproj ]] || find . -maxdepth 2 -name "*.csproj" 2>/dev/null | grep -q .; then
+  # .NET project detected
+  echo "📦 Detected .NET project"
+
+  if ! dotnet test --verbosity minimal --no-build --no-restore 2>/dev/null; then
+    echo ""
+    echo "❌ .NET tests failed!"
+    echo ""
+    echo "Fix failing tests before pushing."
+    echo "Override with: git push --no-verify"
+    exit 1
+  fi
+
+elif [[ -f package.json ]]; then
+  # Node.js project detected
+  echo "📦 Detected Node.js project"
+
+  if ! npm test 2>/dev/null; then
+    echo ""
+    echo "❌ Node.js tests failed!"
+    echo ""
+    echo "Fix failing tests before pushing."
+    echo "Override with: git push --no-verify"
+    exit 1
+  fi
+
+else
+  echo "⚠️  No recognized test framework found"
+  echo "   Skipping test execution"
+  exit 0
+fi
+
+echo ""
+echo "✅ All tests passed - safe to push"
+exit 0

package/.morph/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/.morph/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();
+}