@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

package/framework/hooks/README.md

@@ -1,282 +1,201 @@
-# MORPH-SPEC Hooks Architecture
-
-Git hooks and Agent Teams event handlers for automated validation.
-
-## Architecture
-
-```
-framework/hooks/              # Universal hooks (all stacks share)
-├── pre-commit/
-│   ├── agents.sh             # Validates agents.json Schema
-│   ├── specs.sh              # Validates spec.md sections
-│   └── orchestrator.sh       # Calls framework + stack hooks
-├── commit-msg/
-│   └── conventional-commits.sh # Enforces Conventional Commits format
-├── pre-push/
-│   └── run-tests.sh          # Runs test suite before push
-├── agent-teams/
-│   ├── teammate-idle.js      # Agent Teams idle event
-│   ├── task-completed.js     # Task completion validation
-│   └── phase-advanced.js     # Phase advancement validation
-└── README.md                 # This file
-
-.morph/hooks/                 # Project-specific hooks (optional)
-└── pre-commit/
-    └── tests-{lang}.sh       # Language-specific test coverage
-```
-
-## Hook Types
-
-### Pre-Commit Hooks (Bash)
-
-**Universal (framework/hooks/pre-commit/):**
-- `agents.sh` - Validates agents.json with JSON Schema (BLOCKING)
-- `specs.sh` - Validates spec.md required sections (BLOCKING)
-- `orchestrator.sh` - Master hook that calls all hooks (BLOCKING)
-
-**Project-Specific (.morph/hooks/pre-commit/):**
-- `tests-csharp.sh` - C# test coverage (WARNING ONLY)
-- `tests-typescript.sh` - TypeScript test coverage (WARNING ONLY)
-
-### Commit Message Hook (Bash)
-
-**Universal (framework/hooks/commit-msg/):**
-- `conventional-commits.sh` - Enforces Conventional Commits format (BLOCKING)
-  - Validates: `<type>(<scope>): <description>` format
-  - Allowed types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert
-
-### Pre-Push Hook (Bash)
-
-**Universal (framework/hooks/pre-push/):**
-- `run-tests.sh` - Runs full test suite before push (BLOCKING)
-  - Auto-detects .NET (`dotnet test`) or Node.js (`npm test`) projects
-
-### Agent Teams Hooks (JavaScript)
-
-**Universal (framework/hooks/agent-teams/):**
-- `teammate-idle.js` - Triggered when teammate is idle, validates recent work
-- `task-completed.js` - Triggered when task marked complete, validates deliverables
-- `phase-advanced.js` - Triggered when advancing phases, validates outputs and deliverables
-
-## Installation
-
-### Git Hooks (Pre-Commit, Commit-Msg, Pre-Push)
-
-```bash
-# In your project root (.git/hooks directory)
-cd .git/hooks
-
-# Pre-commit hook (validates agents.json, spec.md, runs stack tests)
-ln -sf ../../framework/hooks/pre-commit/orchestrator.sh pre-commit
-chmod +x pre-commit
-
-# Commit-msg hook (enforces Conventional Commits format)
-ln -sf ../../framework/hooks/commit-msg/conventional-commits.sh commit-msg
-chmod +x commit-msg
-
-# Pre-push hook (runs test suite before push)
-ln -sf ../../framework/hooks/pre-push/run-tests.sh pre-push
-chmod +x pre-push
-```
-
-### Agent Teams Hooks
-
-Add to `.claude/settings.local.json`:
-
-```json
-{
-  "hooks": {
-    "TeammateIdle": "node framework/hooks/agent-teams/teammate-idle.js {feature}",
-    "TaskCompleted": "node framework/hooks/agent-teams/task-completed.js {feature} {taskId}",
-    "PhaseAdvanced": "node framework/hooks/agent-teams/phase-advanced.js {feature} {fromPhase} {toPhase}"
-  }
-}
-```
-
-## How It Works
-
-### Pre-Commit Flow
-
-```
-git commit -m "message"
-    ↓
-.git/hooks/pre-commit executes
-    ↓
-framework/hooks/pre-commit/orchestrator.sh
-    ├─ Runs framework hooks (agents.sh, specs.sh)
-    └─ Runs stack hooks (.morph/hooks/pre-commit/*.sh)
-    ↓
-If ANY FAILS → COMMIT BLOCKED
-If ALL PASS → COMMIT ALLOWED
-```
-
-### Agent Teams Flow
-
-```
-Teammate becomes idle
-    ↓
-Claude Code triggers "TeammateIdle" event
-    ↓
-framework/hooks/agent-teams/teammate-idle.js
-    ├─ Loads agents.json
-    ├─ Filters validators with hook_triggers: ["TeammateIdle"]
-    ├─ Executes validators via hook-executor.js
-    └─ Formats results
-    ↓
-If BLOCKED → Show errors, prevent teammate from proceeding
-If PASSED → Allow teammate to continue
-```
-
-## Configuring Validators
-
-Validators register for hook events in `agents.json`:
-
-```json
-{
-  "security-expert": {
-    "tier": 4,
-    "role": "validator",
-    "relationships": {
-      "runs_in": "hooks",
-      "hook_triggers": ["TeammateIdle", "TaskCompleted"]
-    },
-    "hook_behavior": {
-      "validates": ["SQL injection", "XSS", "Secrets"],
-      "severity": "error",
-      "blocks_on_fail": true
-    }
-  }
-}
-```
-
-## Testing Hooks
-
-### Pre-Commit Hooks
-
-```bash
-# Test orchestrator
-bash framework/hooks/pre-commit/orchestrator.sh
-
-# Test individual hook
-bash framework/hooks/pre-commit/agents.sh
-```
-
-### Git Hooks
-
-```bash
-# Test pre-commit orchestrator
-bash framework/hooks/pre-commit/orchestrator.sh
-
-# Test individual framework hooks
-bash framework/hooks/pre-commit/agents.sh
-bash framework/hooks/pre-commit/specs.sh
-
-# Test commit-msg hook (pass test message as argument)
-echo "feat(test): add new feature" > /tmp/test-msg.txt
-bash framework/hooks/commit-msg/conventional-commits.sh /tmp/test-msg.txt
-
-# Test pre-push hook
-bash framework/hooks/pre-push/run-tests.sh
-```
-
-### Agent Teams Hooks
-
-```bash
-# Simulate TeammateIdle event
-node framework/hooks/agent-teams/teammate-idle.js test-feature --verbose --dry-run
-
-# Simulate TaskCompleted event
-node framework/hooks/agent-teams/task-completed.js test-feature T001 --verbose --dry-run
-
-# Simulate PhaseAdvanced event
-node framework/hooks/agent-teams/phase-advanced.js test-feature design clarify --verbose --dry-run
-```
-
-## Bypassing Hooks
-
-```bash
-# Skip pre-commit hooks (NOT RECOMMENDED)
-git commit --no-verify
-
-# Skip commit-msg hook (NOT RECOMMENDED)
-git commit --no-verify
-
-# Skip pre-push hook (NOT RECOMMENDED)
-git push --no-verify
-
-# Skip task completion validation (NOT RECOMMENDED)
-morph-spec task done feature-name task-id --skip-validation
-```
-
-## Creating Custom Hooks
-
-### Stack-Specific Pre-Commit Hook
-
-Create `.morph/hooks/pre-commit/my-hook.sh`:
-
-```bash
-#!/bin/bash
-# Scope: my-stack | Custom validation
-echo "🎯 Running custom validation..."
-
-# Your validation logic here
-
-exit 0
-```
-
-The orchestrator will automatically detect and run it.
-
-### New Hook Event Type
-
-Add to `framework/hooks/agent-teams/`:
-
-```javascript
-#!/usr/bin/env node
-// Scope: universal | My custom event
-
-import { executeHook, formatHookResults } from '../../src/lib/hooks/hook-executor.js';
-
-// Your hook logic here
-```
-
-Register in `agents.json`:
-
-```json
-{
-  "hook_triggers": ["MyCustomEvent"]
-}
-```
-
-## Troubleshooting
-
-### Pre-Commit Hook Not Running
-
-```bash
-# Check if hook exists
-ls -la .git/hooks/pre-commit
-
-# Recreate symlink
-cd .git/hooks
-ln -sf ../../framework/hooks/pre-commit/orchestrator.sh pre-commit
-chmod +x pre-commit
-```
-
-### Agent Teams Hook Failing
-
-```bash
-# Test manually with verbose output
-node framework/hooks/agent-teams/teammate-idle.js my-feature --verbose
-
-# Check agents.json configuration
-npx morph-spec validate-agents-skills
-```
-
-## References
-
-- Hook executor: `src/lib/hooks/hook-executor.js`
-- Checkpoint hooks: `src/lib/checkpoints/checkpoint-hooks.js`
-- Agents configuration: `.morph/config/agents.json`
-
----
-
-*MORPH-SPEC v4.0.0 - Hooks Architecture*
+# 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) | protect-readonly-files.js | 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** (Write) | track-output-creation.js | Auto-state | Marks outputs as created when files are written |
+| **PostToolUse** (Bash) | dispatch.js | Dispatch | Triggers checkpoints on task completion |
+| **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/outputs |
+| **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`.
+
+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: "..." } }
+    ↓
+protect-readonly-files.js
+    ├── Is .morph/state.json? → BLOCK (use CLI)
+    ├── Is .morph/framework/**? → BLOCK (read-only)
+    └── Other → pass
+    ↓
+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.3.7 — Hooks Architecture v2*

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

@@ -0,0 +1,52 @@
+#!/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 = {
+    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/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(`node bin/morph-spec.js 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/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);