@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

package/framework/hooks/claude-code/pre-compact/save-morph-context.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+/**
+ * PreCompact Hook: Save Context Before Compaction
+ *
+ * Event: PreCompact
+ *
+ * Snapshots current morph-spec state to .morph/memory/ before context is lost
+ * to compaction. The SessionStart hook can use this to restore awareness.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { stateExists, loadState, getActiveFeature } from '../../shared/state-reader.js';
+import { pass } from '../../shared/hook-response.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const state = loadState();
+  if (!state) pass();
+
+  const active = getActiveFeature();
+
+  const snapshot = {
+    timestamp: new Date().toISOString(),
+    event: 'pre-compact',
+    activeFeature: active ? active.name : null,
+    features: {}
+  };
+
+  // Save minimal feature summaries
+  for (const [name, feature] of Object.entries(state.features || {})) {
+    snapshot.features[name] = {
+      phase: feature.phase,
+      status: feature.status,
+      workflow: feature.workflow,
+      tasks: feature.tasks,
+      approvalGates: Object.fromEntries(
+        Object.entries(feature.approvalGates || {}).map(([gate, data]) => [gate, data.approved])
+      )
+    };
+  }
+
+  // Save to .morph/memory/
+  const memoryDir = join(process.cwd(), '.morph', 'memory');
+  if (!existsSync(memoryDir)) {
+    mkdirSync(memoryDir, { recursive: true });
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const snapshotPath = join(memoryDir, `pre-compact-${timestamp}.json`);
+  writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), 'utf-8');
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Hook: Enforce Phase-Appropriate File Writes
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ *
+ * Ensures writes to .morph/features/{feature}/ go to the current phase's subfolder:
+ *   proposal → only 0-proposal/
+ *   design, clarify → only 1-design/
+ *   uiux → only 2-ui/
+ *   tasks → only 3-tasks/
+ *   implement → 4-implement/ + any source code (unrestricted)
+ *
+ * Files outside .morph/features/ are always allowed.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, getFeaturePhase } from '../../shared/state-reader.js';
+import {
+  isFeaturePath,
+  extractFeatureName,
+  extractPhaseDir,
+  PHASE_DIRS
+} from '../../shared/phase-utils.js';
+import { block, pass } from '../../shared/hook-response.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  if (!filePath) pass();
+
+  // Only check files inside .morph/features/
+  if (!isFeaturePath(filePath)) pass();
+
+  const featureName = extractFeatureName(filePath);
+  if (!featureName) pass();
+
+  const phase = getFeaturePhase(featureName);
+  if (!phase) pass();
+
+  // During implement phase, all writes are allowed (source code is unrestricted)
+  if (phase === 'implement' || phase === 'sync') pass();
+
+  const targetDir = extractPhaseDir(filePath);
+  if (!targetDir) pass(); // File directly in feature root — allow
+
+  const allowedDir = PHASE_DIRS[phase];
+  if (!allowedDir) pass(); // Unknown phase — allow
+
+  if (targetDir !== allowedDir) {
+    const phaseLabel = phase.toUpperCase();
+    block(
+      `MORPH-SPEC: Writing to '${targetDir}/' is not allowed during ${phaseLabel} phase.\n` +
+      `Current phase '${phase}' only permits writes to '${allowedDir}/'.\n\n` +
+      `To write to '${targetDir}/', first advance to the appropriate phase:\n` +
+      `  morph-spec phase advance ${featureName}`
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/pre-tool-use/protect-readonly-files.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Hook: Protect state.json & Framework Files
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ *
+ * Blocks direct edits to:
+ *   - .morph/state.json → must use CLI commands
+ *   - .morph/framework/** → read-only framework files
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { isStatePath, isFrameworkPath } from '../../shared/phase-utils.js';
+import { block, pass } from '../../shared/hook-response.js';
+
+try {
+  // Skip if not a morph-spec project
+  if (!stateExists()) {
+    pass();
+  }
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  if (!filePath) pass();
+
+  // Block edits to state.json
+  if (isStatePath(filePath)) {
+    block(
+      'MORPH-SPEC: Direct edits to .morph/state.json are blocked.\n' +
+      'Use CLI commands instead:\n' +
+      '  morph-spec state set <feature> <key> <value>\n' +
+      '  morph-spec phase advance <feature>\n' +
+      '  morph-spec task done <feature> <taskId>\n' +
+      '  morph-spec approve <feature> <gate>'
+    );
+  }
+
+  // Block edits to framework files
+  if (isFrameworkPath(filePath)) {
+    block(
+      'MORPH-SPEC: Files in .morph/framework/ are read-only.\n' +
+      'These files are managed by the framework and overwritten on update.\n' +
+      'To customize, create project-specific overrides in .morph/context/ or .morph/config/.'
+    );
+  }
+
+  // All other files are allowed
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/pre-tool-use/protect-spec-files.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Hook: Protect Approved Spec Files
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ *
+ * Blocks Write/Edit to spec artifacts after their approval gate has passed:
+ *   - 1-design/spec.md, contracts.cs, etc. → blocked if 'design' gate approved
+ *   - 3-tasks/tasks.md → blocked if 'tasks' gate approved
+ *   - 2-ui/design-system.md, etc. → blocked if 'uiux' gate approved
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, isGateApproved } from '../../shared/state-reader.js';
+import {
+  isFeaturePath,
+  extractFeatureName,
+  getBasename,
+  PROTECTED_SPEC_FILES
+} from '../../shared/phase-utils.js';
+import { block, pass } from '../../shared/hook-response.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  if (!filePath) pass();
+
+  // Only check files inside .morph/features/
+  if (!isFeaturePath(filePath)) pass();
+
+  const featureName = extractFeatureName(filePath);
+  if (!featureName) pass();
+
+  const filename = getBasename(filePath);
+  const requiredGate = PROTECTED_SPEC_FILES[filename];
+
+  // Not a protected file
+  if (!requiredGate) pass();
+
+  // Check if the gate has been approved
+  if (isGateApproved(featureName, requiredGate)) {
+    block(
+      `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
+      `Editing approved specs breaks the spec contract.\n\n` +
+      `If changes are truly needed:\n` +
+      `  1. Revoke approval: morph-spec approve ${featureName} ${requiredGate} --revoke\n` +
+      `  2. Make your edits\n` +
+      `  3. Re-approve: morph-spec approve ${featureName} ${requiredGate}`
+    );
+  }
+
+  // Gate not yet approved — allow editing
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/session-start/inject-morph-context.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart Hook: Inject MORPH-SPEC Context
+ *
+ * Event: SessionStart | Matcher: startup|resume|compact
+ *
+ * Reads state.json and injects a summary as additionalContext so Claude
+ * knows the current morph-spec state at session start.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { loadState, getActiveFeature, getPendingGates, getMissingOutputs } from '../../shared/state-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const SPEC_MAX_CHARS = 3000;
+
+try {
+  if (!stateExists()) pass();
+
+  const state = loadState();
+  if (!state?.features || Object.keys(state.features).length === 0) pass();
+
+  const active = getActiveFeature();
+  const lines = ['MORPH-SPEC Status:'];
+
+  if (active) {
+    const { name, feature } = active;
+    lines.push(`- Active feature: ${name} (phase: ${feature.phase}, workflow: ${feature.workflow || 'auto'})`);
+    lines.push(`- Status: ${feature.status}`);
+
+    // Task progress
+    if (feature.tasks) {
+      lines.push(`- Tasks: ${feature.tasks.completed || 0}/${feature.tasks.total || 0} completed`);
+    }
+
+    // Pending approvals
+    const pending = getPendingGates(name);
+    if (pending.length > 0) {
+      lines.push(`- Pending approvals: ${pending.join(', ')}`);
+    }
+
+    // Next required output
+    const missing = getMissingOutputs(name);
+    if (missing.length > 0) {
+      const next = missing[0];
+      lines.push(`- Next required output: ${next.type} → ${next.path}`);
+    }
+
+    // Checkpoints
+    if (feature.checkpoints?.length > 0) {
+      const lastCp = feature.checkpoints[feature.checkpoints.length - 1];
+      lines.push(`- Last checkpoint: #${lastCp.checkpointNum} (${lastCp.passed ? 'passed' : 'failed'})`);
+    }
+
+    // Active feature spec (truncated for context budget)
+    const specPath = join(process.cwd(), `.morph/features/${name}/1-design/spec.md`);
+    if (existsSync(specPath)) {
+      try {
+        const specContent = readFileSync(specPath, 'utf-8');
+        const truncated = specContent.length > SPEC_MAX_CHARS
+          ? specContent.slice(0, SPEC_MAX_CHARS) + `\n\n[... spec truncated — full file at .morph/features/${name}/1-design/spec.md]`
+          : specContent;
+        lines.push('');
+        lines.push(`--- Active feature spec (${name}/1-design/spec.md) ---`);
+        lines.push(truncated);
+        lines.push('--- End spec ---');
+      } catch {
+        // Non-blocking: skip spec injection on read error
+      }
+    }
+  } else {
+    // Show summary of all features
+    const featureNames = Object.keys(state.features);
+    lines.push(`- Features: ${featureNames.length} (${featureNames.join(', ')})`);
+
+    for (const [name, feature] of Object.entries(state.features)) {
+      lines.push(`  - ${name}: phase=${feature.phase}, status=${feature.status}`);
+    }
+  }
+
+  // Remind about key commands
+  lines.push('');
+  lines.push('Key commands: morph-spec status <feature> | morph-spec phase advance <feature> | morph-spec approve <feature> <gate>');
+
+  injectContext(lines.join('\n'));
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/statusline.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+# framework/hooks/claude-code/statusline.py
+# Claude Code statusline for morph-spec
+# Receives JSON via stdin from Claude Code after each response
+
+import sys
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+
+# Ensure UTF-8 output on Windows (stdout defaults to CP1252 otherwise)
+if hasattr(sys.stdout, 'reconfigure'):
+    sys.stdout.reconfigure(encoding='utf-8')
+
+# ANSI colors
+R = '\033[0m'       # Reset
+BOLD = '\033[1m'
+CYAN = '\033[36m'
+MAGENTA = '\033[35m'
+GREEN = '\033[32m'
+YELLOW = '\033[33m'
+RED = '\033[31m'
+BLUE = '\033[34m'
+GRAY = '\033[90m'
+WHITE = '\033[97m'
+
+
+def ctx_color(pct):
+    if pct < 70:
+        return GREEN
+    if pct < 90:
+        return YELLOW
+    return RED
+
+
+def progress_bar(pct, width=8):
+    filled = int(pct / 100 * width)
+    empty = width - filled
+    return f"{'█' * filled}{'░' * empty}"
+
+
+def format_tokens(n):
+    if n >= 1000:
+        return f"{n // 1000}k"
+    return str(n)
+
+
+def get_git_info(cwd):
+    """Get git branch and file stats. Uses a 5s file cache to avoid lag."""
+    try:
+        cache_file = Path(cwd) / '.morph' / '.git-cache'
+        try:
+            if cache_file.exists():
+                age = time.time() - cache_file.stat().st_mtime
+                if age < 5:
+                    return cache_file.read_text().strip()
+        except Exception:
+            pass
+
+        branch = subprocess.check_output(
+            ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+            cwd=cwd, stderr=subprocess.DEVNULL, timeout=2
+        ).decode().strip()
+
+        status_out = subprocess.check_output(
+            ['git', 'status', '--porcelain'],
+            cwd=cwd, stderr=subprocess.DEVNULL, timeout=2
+        ).decode()
+
+        staged = sum(1 for l in status_out.splitlines() if l and l[0] in 'MADRC')
+        modified = sum(1 for l in status_out.splitlines() if l and l[1] in 'MD')
+        untracked = sum(1 for l in status_out.splitlines() if l.startswith('??'))
+
+        parts = [f"{BLUE} {branch}{R}"]
+        if staged:
+            parts.append(f"{GREEN}+{staged}{R}")
+        if modified:
+            parts.append(f"{YELLOW}~{modified}{R}")
+        if untracked:
+            parts.append(f"{GRAY}?{untracked}{R}")
+
+        result = ' '.join(parts)
+
+        try:
+            cache_file.parent.mkdir(parents=True, exist_ok=True)
+            cache_file.write_text(result)
+        except Exception:
+            pass
+
+        return result
+    except Exception:
+        return ""
+
+
+def get_worktree_info(cwd):
+    """Detect if running in a git worktree (not the main worktree)."""
+    try:
+        worktrees_out = subprocess.check_output(
+            ['git', 'worktree', 'list', '--porcelain'],
+            cwd=cwd, stderr=subprocess.DEVNULL, timeout=2
+        ).decode()
+
+        entries = []
+        current = {}
+        for line in worktrees_out.splitlines():
+            if line.startswith('worktree '):
+                if current:
+                    entries.append(current)
+                current = {'path': line.split(' ', 1)[1]}
+            elif line.startswith('branch '):
+                current['branch'] = line.split(' ', 1)[1]
+
+        if current:
+            entries.append(current)
+
+        if len(entries) > 1:
+            cwd_resolved = str(Path(cwd).resolve())
+            for entry in entries[1:]:
+                entry_path = str(Path(entry.get('path', '')).resolve())
+                if cwd_resolved == entry_path:
+                    branch_ref = entry.get('branch', '')
+                    branch = branch_ref.replace('refs/heads/', '')
+                    return f"{MAGENTA}worktree:{branch}{R}"
+    except Exception:
+        pass
+    return ""
+
+
+def get_morph_info(cwd):
+    """Read active feature info from .morph/state.json."""
+    state_path = Path(cwd) / '.morph' / 'state.json'
+    if not state_path.exists():
+        return None
+    try:
+        state = json.loads(state_path.read_text())
+        features = state.get('features', {})
+        active = [
+            (name, feat)
+            for name, feat in features.items()
+            if feat.get('status') == 'in_progress'
+        ]
+        if not active:
+            return None
+
+        name, feat = active[0]
+        phase = feat.get('phase', '?')
+        tasks = feat.get('tasks', {})
+        done = tasks.get('completed', 0)
+        total = tasks.get('total', 0)
+        gates = feat.get('approvalGates', {})
+        pending = [g for g, v in gates.items() if not v.get('approved')]
+
+        return {
+            'name': name,
+            'phase': phase,
+            'tasks_done': done,
+            'tasks_total': total,
+            'pending_approval': pending[0] if pending else None,
+        }
+    except Exception:
+        return None
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            sys.exit(0)
+        data = json.loads(raw)
+    except Exception:
+        sys.exit(0)
+
+    cwd = data.get('cwd', os.getcwd())
+
+    # === LINE 1: Morph status (only if morph project has active feature) ===
+    morph = get_morph_info(cwd)
+    if morph:
+        parts1 = [
+            f"{CYAN}{BOLD}{morph['name']}{R}",
+            f"{MAGENTA}phase:{morph['phase']}{R}",
+        ]
+        if morph['tasks_total'] > 0:
+            pct = morph['tasks_done'] / morph['tasks_total'] * 100
+            bar = progress_bar(pct, 6)
+            parts1.append(f"{GREEN}{bar} {morph['tasks_done']}/{morph['tasks_total']}{R}")
+        if morph['pending_approval']:
+            parts1.append(f"{YELLOW}⏳ {morph['pending_approval']} pending{R}")
+        print('  |  '.join(parts1))
+
+    # === LINE 2: Session info (always shown) ===
+    parts2 = []
+
+    # Model
+    model = data.get('model', {})
+    model_name = model.get('display_name', model.get('id', ''))
+    if model_name:
+        short = model_name.replace('Claude ', '').replace(' (claude.ai)', '')
+        parts2.append(f"{WHITE}{BOLD}🤖 {short}{R}")
+
+    # Context window
+    ctx = data.get('context_window', {})
+    if ctx:
+        used_pct = ctx.get('used_percentage', 0)
+        cur = ctx.get('current_usage', 0)
+        total_ctx = ctx.get('context_window_size', 0)
+        color = ctx_color(used_pct)
+        bar = progress_bar(used_pct, 8)
+        toks = f"{format_tokens(cur)}/{format_tokens(total_ctx)}"
+        parts2.append(f"{color}{bar} {used_pct:.0f}% ({toks} tok){R}")
+
+    # Cost
+    cost = data.get('cost', {})
+    if cost.get('total_cost_usd'):
+        usd = cost['total_cost_usd']
+        parts2.append(f"{GRAY}${usd:.3f}{R}")
+
+    # Agent name (if running in agent mode)
+    agent = data.get('agent', {})
+    if agent.get('name'):
+        parts2.append(f"{BLUE}agent:{agent['name']}{R}")
+
+    # Git info (cached, non-blocking)
+    git = get_git_info(cwd)
+    if git:
+        parts2.append(git)
+
+    # Worktree info
+    wt = get_worktree_info(cwd)
+    if wt:
+        parts2.append(wt)
+
+    if parts2:
+        print('  |  '.join(parts2))
+
+
+if __name__ == '__main__':
+    main()

package/framework/hooks/claude-code/statusline.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# morph-spec statusline — installed globally to ~/.claude/statusline.sh
+# Claude Code invokes this with JSON via stdin after each response.
+# Requires: Python 3 available as `python3` on PATH.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+python3 "${SCRIPT_DIR}/statusline.py" 2>/dev/null || true

package/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 === null)
+      .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);
+}