@polymorphism-tech/morph-spec 4.10.9 → 4.10.10

package/framework/hooks/README.md

@@ -1,204 +1,204 @@
-# 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-spec-files.js    # Block edits to approved spec artifacts
-│   │   └── enforce-phase-writes.js  # Enforce writes to correct phase dir
-│   ├── post-tool-use/
-│   │   ├── dispatch.js              # Dispatch on CLI commands (auto-checkpoint)
-│   │   └── context-refresh.js       # Auto-refresh context on structural git commits
-│   ├── 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 |
-| **PostToolUse** (Bash) | context-refresh.js | Inject context | Detects `git commit` with structural changes → instructs Claude to update `.morph/context/README.md` and `.morph/config/config.json` |
-| **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": "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 by Polymorphism Tech — Hooks Architecture v2.7*
+# 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-spec-files.js    # Block edits to approved spec artifacts
+│   │   └── enforce-phase-writes.js  # Enforce writes to correct phase dir
+│   ├── post-tool-use/
+│   │   ├── dispatch.js              # Dispatch on CLI commands (auto-checkpoint)
+│   │   └── context-refresh.js       # Auto-refresh context on structural git commits
+│   ├── 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 |
+| **PostToolUse** (Bash) | context-refresh.js | Inject context | Detects `git commit` with structural changes → instructs Claude to update `.morph/context/README.md` and `.morph/config/config.json` |
+| **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": "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 by Polymorphism Tech — Hooks Architecture v2.7*