@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

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

@@ -1,205 +0,0 @@
-# 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

@@ -1,54 +0,0 @@
-#!/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

@@ -1,83 +0,0 @@
-#!/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

@@ -1,42 +0,0 @@
-#!/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

@@ -1,61 +0,0 @@
-#!/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

@@ -1,71 +0,0 @@
-#!/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

@@ -1,58 +0,0 @@
-#!/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

@@ -1,64 +0,0 @@
-#!/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);
-}