@polymorphism-tech/morph-spec 4.7.1 → 4.7.2

package/.morph/framework/hooks/README.md

@@ -0,0 +1,205 @@
+# MORPH-SPEC Hooks Architecture (v2)
+
+Comprehensive hooks system for enforcing spec-driven development at the Claude Code level.
+
+## Architecture
+
+```
+framework/hooks/
+├── claude-code/                     # Claude Code native hooks
+│   ├── session-start/
+│   │   └── inject-morph-context.js  # Inject state summary on session start
+│   ├── user-prompt/
+│   │   └── enrich-prompt.js         # Context-aware prompt enrichment
+│   ├── pre-tool-use/
+│   │   ├── protect-readonly-files.js # Block edits to state.json & framework/
+│   │   ├── protect-spec-files.js    # Block edits to approved spec artifacts
+│   │   └── enforce-phase-writes.js  # Enforce writes to correct phase dir
+│   ├── post-tool-use/
+│   │   ├── track-output-creation.js # Auto-mark outputs as created
+│   │   └── dispatch.js              # Dispatch on CLI commands
+│   ├── stop/
+│   │   └── validate-completion.js   # Advisory: warn about incomplete work
+│   ├── pre-compact/
+│   │   └── save-morph-context.js    # Snapshot state before compaction
+│   └── notification/
+│       └── approval-reminder.js     # Remind about pending approvals
+├── shared/                          # Reusable utilities for all hooks
+│   ├── state-reader.js              # Read-only state.json accessor
+│   ├── phase-utils.js               # Phase constants and path utilities
+│   ├── hook-response.js             # JSON response builders
+│   └── stdin-reader.js              # Stdin JSON reader
+├── git/                             # Git hooks (Bash)
+│   ├── pre-commit/
+│   │   ├── orchestrator.sh          # Master hook dispatcher
+│   │   ├── agents.sh                # Validates agents.json schema
+│   │   └── specs.sh                 # Validates spec.md sections
+│   ├── commit-msg/
+│   │   └── conventional-commits.sh  # Enforces conventional commits
+│   └── pre-push/
+│       └── run-tests.sh             # Runs test suite before push
+└── README.md                        # This file
+```
+
+## Hook Events
+
+| Event | Hook | Type | Purpose |
+|-------|------|------|---------|
+| **SessionStart** | inject-morph-context.js | Inject context | Shows active feature, phase, pending approvals |
+| **UserPromptSubmit** | enrich-prompt.js | Inject context | Warns about wrong-phase work, injects commands |
+| **PreToolUse** (Write\|Edit) | _(native permissions.deny)_ | Block | Blocks edits to state.json and .morph/framework/ |
+| **PreToolUse** (Write\|Edit) | protect-spec-files.js | Block | Blocks edits to spec files after approval |
+| **PreToolUse** (Write\|Edit) | enforce-phase-writes.js | Block | Ensures writes go to current phase directory |
+| **PreToolUse** (Bash) | _(prompt-type inline guard)_ | Block | Blocks `rm -rf .morph/` and direct state edits via Claude's reasoning |
+| **PostToolUse** (Bash) | dispatch.js | Dispatch | Triggers checkpoints on task completion |
+| **PostToolUseFailure** | handle-tool-failure.js | Logging | Appends structured JSON to .morph/logs/tool-failures.log |
+| **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/pending gates |
+| **PreCompact** | save-morph-context.js | Snapshot | Saves state to .morph/memory/ before compaction |
+| **Notification** | approval-reminder.js | Advisory | Reminds about pending approval gates |
+
+## Design Principles
+
+1. **Fail-open**: All hooks catch exceptions and `exit 0` — never accidentally block legitimate work
+2. **Non-morph projects**: Every hook checks for `.morph/state.json` first and exits silently if missing
+3. **Performance**: PreToolUse hooks use synchronous state reads for <100ms execution
+4. **Cross-platform**: All hooks use `path.join()`/`path.resolve()`, no hardcoded path separators
+5. **Node.js only**: All hooks use `node` as executor (no PowerShell/bash dependency)
+
+## Installation
+
+Hooks are automatically installed by `morph-spec init` and updated by `morph-spec update`.
+
+During init/update, the entire `framework/hooks/` directory is copied to `.morph/framework/hooks/`.
+Hook commands in `.claude/settings.local.json` reference `$CLAUDE_PROJECT_DIR/.morph/framework/hooks/`
+so they work correctly in any project regardless of how morph-spec was installed.
+
+The installer writes to `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{ "matcher": "startup|resume|compact", "hooks": [...] }],
+    "UserPromptSubmit": [{ "hooks": [...] }],
+    "PreToolUse": [
+      { "matcher": "Write|Edit", "hooks": [...] },
+      { "matcher": "Bash", "hooks": [...] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Write", "hooks": [...] },
+      { "matcher": "Bash", "hooks": [...] }
+    ],
+    "Stop": [{ "hooks": [...] }],
+    "PreCompact": [{ "hooks": [...] }],
+    "Notification": [{ "matcher": "idle_prompt", "hooks": [...] }]
+  }
+}
+```
+
+### Git Hooks
+
+```bash
+# In your project root
+cd .git/hooks
+ln -sf ../../framework/hooks/git/pre-commit/orchestrator.sh pre-commit
+ln -sf ../../framework/hooks/git/commit-msg/conventional-commits.sh commit-msg
+ln -sf ../../framework/hooks/git/pre-push/run-tests.sh pre-push
+chmod +x pre-commit commit-msg pre-push
+```
+
+## Shared Utilities
+
+All Claude Code hooks import from `framework/hooks/shared/`:
+
+| Module | Purpose |
+|--------|---------|
+| `state-reader.js` | `loadState()`, `getActiveFeature()`, `getFeaturePhase()`, `isGateApproved()`, `getPendingGates()`, `getMissingOutputs()` |
+| `phase-utils.js` | Phase constants, path extraction, file classification |
+| `hook-response.js` | `block(reason)`, `approve(context)`, `injectContext(text)`, `pass()` |
+| `stdin-reader.js` | `readStdin()` — Promise-based stdin JSON reader |
+
+## How Hooks Work
+
+### PreToolUse (Write|Edit) Flow
+
+```
+Claude calls Write/Edit tool
+    ↓
+Claude Code sends JSON to stdin: { tool_input: { file_path: "..." } }
+    ↓
+[native permissions.deny]
+    ├── Is .morph/state.json? → BLOCK (use CLI)
+    ├── Is .morph/framework/**? → BLOCK (read-only)
+    └── Other → continue
+    ↓
+protect-spec-files.js
+    ├── Is in .morph/features/{feature}/?
+    │   ├── Is spec.md and design gate approved? → BLOCK
+    │   ├── Is tasks.md and tasks gate approved? → BLOCK
+    │   └── Gate not approved → pass
+    └── Not a feature file → pass
+    ↓
+enforce-phase-writes.js
+    ├── Is in .morph/features/{feature}/?
+    │   ├── Phase is implement → pass (unrestricted)
+    │   ├── Target dir matches phase dir → pass
+    │   └── Target dir doesn't match → BLOCK
+    └── Not a feature file → pass
+```
+
+### SessionStart Flow
+
+```
+Session starts/resumes/compacts
+    ↓
+inject-morph-context.js
+    ├── No state.json → silent exit
+    ├── Has active feature → inject summary:
+    │   "MORPH-SPEC Status:
+    │    - Active feature: my-feature (phase: implement)
+    │    - Tasks: 3/10 completed
+    │    - Pending approvals: design, tasks"
+    └── No active feature → inject feature list
+```
+
+## Testing
+
+```bash
+# Run hook tests
+npm test -- test/hooks/
+
+# Run shared utilities tests
+npm test -- test/hooks/shared-utils.test.js
+
+# Run installer tests
+npm test -- test/hooks/hooks-installer.test.js
+```
+
+## Troubleshooting
+
+### Hooks Not Running
+
+```bash
+# Check if hooks are installed
+cat .claude/settings.local.json | jq '.hooks'
+
+# Reinstall hooks
+morph-spec update
+```
+
+### Hook Blocking Legitimate Work
+
+All hooks are fail-open. If a hook is incorrectly blocking:
+
+1. The hook catches its own errors and exits 0
+2. If truly stuck, remove the specific hook from `.claude/settings.local.json`
+3. Report the issue so the hook logic can be fixed
+
+### Resetting All Morph Hooks
+
+```bash
+morph-spec doctor --reset
+```
+
+---
+
+*MORPH-SPEC v4.5.0 — Hooks Architecture v2.5*

package/.morph/framework/hooks/claude-code/notification/approval-reminder.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+/**
+ * Notification Hook: Approval Reminder on Idle
+ *
+ * Event: Notification | Matcher: idle_prompt
+ *
+ * When Claude is idle, checks for pending approval gates and reminds the user.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { stateExists, getActiveFeature, getPendingGates } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const active = getActiveFeature();
+  if (!active) pass();
+
+  const { name, feature } = active;
+  const pending = getPendingGates(name);
+
+  if (pending.length === 0) pass();
+
+  // Only remind about gates relevant to the current phase
+  const phaseGateRelevance = {
+    proposal: ['proposal'],
+    setup: ['proposal'],
+    design: ['design'],
+    clarify: ['design'],
+    tasks: ['design', 'tasks'],
+    uiux: ['uiux'],
+    implement: ['design', 'tasks']
+  };
+
+  const relevantGates = phaseGateRelevance[feature.phase] || [];
+  const pendingRelevant = pending.filter(g => relevantGates.includes(g));
+
+  if (pendingRelevant.length === 0) pass();
+
+  const reminders = pendingRelevant.map(gate =>
+    `  morph-spec approve ${name} ${gate}`
+  );
+
+  injectContext(
+    `MORPH-SPEC: Feature '${name}' has pending approval(s) that may be blocking progress:\n` +
+    reminders.join('\n')
+  );
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/.morph/framework/hooks/claude-code/post-tool-use/dispatch.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: Improved Dispatch
+ *
+ * Event: PostToolUse | Matcher: Bash
+ *
+ * Replaces the old agent-teams/dispatch.js with:
+ *   - Reads state BEFORE dispatching to pass correct from/to phases
+ *   - Handles more CLI commands: approve, state init, checkpoint commands
+ *   - Triggers checkpoint validation on task completion when count % 3 === 0
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { execSync } from 'child_process';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, getFeature } from '../../shared/state-reader.js';
+import { pass } from '../../shared/hook-response.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const command = payload?.tool_input?.command || '';
+  if (!command) pass();
+
+  dispatch(command);
+} catch {
+  // Fail-open
+  process.exit(0);
+}
+
+function dispatch(command) {
+  // morph-spec task done <feature> <taskId> [--skip-validation]
+  const taskDoneMatch = command.match(/morph-spec\s+task\s+done\s+(\S+)\s+(\S+)/);
+  if (taskDoneMatch) {
+    const [, featureName, taskId] = taskDoneMatch;
+
+    // Check if checkpoint should run (every 3 tasks)
+    try {
+      const feature = getFeature(featureName);
+      if (feature?.tasks) {
+        const completed = (feature.tasks.completed || 0) + 1; // +1 because task-done hasn't executed yet
+        if (completed > 0 && completed % 3 === 0) {
+          const checkpointNum = Math.floor(completed / 3);
+          run(`morph-spec checkpoint-save ${featureName} --note "Auto-checkpoint #${checkpointNum} at task ${completed}"`);
+        }
+      }
+    } catch {
+      // Non-blocking
+    }
+
+    pass();
+  }
+
+  // morph-spec phase advance <feature>
+  const phaseAdvanceMatch = command.match(/morph-spec\s+phase\s+advance\s+(\S+)/);
+  if (phaseAdvanceMatch) {
+    // Phase advancement hooks are handled internally by advance-phase.js
+    pass();
+  }
+
+  // morph-spec approve <feature> <gate>
+  const approveMatch = command.match(/morph-spec\s+approve\s+(\S+)\s+(\S+)/);
+  if (approveMatch) {
+    // Approval handled by CLI — just pass through
+    pass();
+  }
+
+  // No match — exit cleanly
+  pass();
+}
+
+function run(cmd) {
+  try {
+    execSync(cmd, { stdio: 'pipe', cwd: process.cwd(), timeout: 30000 });
+  } catch {
+    // Non-blocking
+  }
+}

package/.morph/framework/hooks/claude-code/post-tool-use/handle-tool-failure.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUseFailure Hook: Log Tool Failures
+ *
+ * Event: PostToolUseFailure
+ *
+ * Runs when any tool fails. Appends a structured JSON entry to
+ * .morph/logs/tool-failures.log for debugging and pattern analysis.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { appendFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+
+try {
+  // Only log in morph-spec projects
+  if (!stateExists()) {
+    process.exit(0);
+  }
+
+  const input = await readStdin();
+
+  const logDir = join(process.cwd(), '.morph', 'logs');
+  mkdirSync(logDir, { recursive: true });
+
+  const entry = {
+    timestamp: new Date().toISOString(),
+    tool: input?.tool_name ?? 'unknown',
+    error: input?.error ?? null,
+    input: input?.tool_input ?? null,
+  };
+
+  appendFileSync(join(logDir, 'tool-failures.log'), JSON.stringify(entry) + '\n');
+} catch {
+  // Fail-open: logging is non-critical
+}
+
+process.exit(0);

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