@polymorphism-tech/morph-spec 4.8.12 → 4.8.15

package/framework/hooks/README.md

@@ -1,202 +1,202 @@
-# 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)
-│   ├── 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": "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.5*
+# 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)
+│   ├── 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": "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.5*

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

@@ -14,9 +14,11 @@
  */
 
 import { execSync } from 'child_process';
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists, getFeature } from '../../shared/state-reader.js';
-import { pass } from '../../shared/hook-response.js';
+import { pass, injectContext } from '../../shared/hook-response.js';
 
 try {
   if (!stateExists()) pass();
@@ -59,7 +61,8 @@ function dispatch(command) {
   // 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
+    const [, featureName] = phaseAdvanceMatch;
+    evaluatePhaseChain(featureName);
     pass();
   }
 
@@ -74,6 +77,49 @@ function dispatch(command) {
   pass();
 }
 
+/**
+ * Evaluate whether the phase chain should auto-continue after a phase advance.
+ * Injects a `morph-spec phase run` instruction when the workflow has phaseChain.enabled.
+ * Silently passes when workflow doesn't support chaining or feature is not found.
+ *
+ * @param {string} featureName
+ */
+function evaluatePhaseChain(featureName) {
+  try {
+    const feature = getFeature(featureName);
+    if (!feature) return;
+
+    const workflowId = feature.workflow;
+    if (!workflowId || workflowId === 'auto') return;
+
+    // Load workflow config to check phaseChain.enabled
+    const configPath = resolve(
+      process.cwd(),
+      `.morph/framework/workflows/configs/${workflowId}.json`
+    );
+    if (!existsSync(configPath)) return;
+
+    let workflowConfig;
+    try {
+      workflowConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      return;
+    }
+
+    if (!workflowConfig?.phaseChain?.enabled) return;
+
+    // Inject instruction to continue the phase chain
+    injectContext(
+      `Phase advance complete. Continue the phase chain:\n` +
+      `  morph-spec phase run ${featureName}\n\n` +
+      `The phase runner will check eligibility and auto-advance if all gates pass. ` +
+      `It will pause automatically on blocked tasks, low pass rate, or trust gates.`
+    );
+  } catch {
+    // Non-blocking — fail silently
+  }
+}
+
 function run(cmd) {
   try {
     execSync(cmd, { stdio: 'pipe', cwd: process.cwd(), timeout: 30000 });

package/framework/hooks/claude-code/post-tool-use/validator-feedback.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: Validator Feedback
+ *
+ * Event: PostToolUse | Matcher: Bash
+ *
+ * Fires after `morph-spec task done` completes.
+ * Reads validationHistory for the completed task and injects
+ * remediation context when validation failed.
+ *
+ * This closes the Builder-Validator loop:
+ *   task done → runValidation → validationHistory → hook injects context
+ *   → LLM sees remediation prompt before next step → auto-fix attempt
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+
+// Standard IDs referenced in remediation messages
+const STANDARD_REFS = {
+  'di': 'backend/dotnet/core.md#dependency-injection',
+  'async': 'backend/dotnet/async.md#cancellation-token-pattern',
+  'security': 'core/architecture.md#security-patterns',
+  'packages': 'backend/dotnet/program-cs-checklist.md#nuget-packages',
+  'design-system': 'frontend/design-system/naming.md#css-class-conventions',
+  'blazor': 'frontend/blazor/pitfalls.md#dbcontext-in-blazor',
+};
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const command = payload?.tool_input?.command || '';
+  if (!command) pass();
+
+  // Match: morph-spec task done <feature> <taskId>
+  const taskDoneMatch = command.match(/morph-spec\s+task\s+done\s+(\S+)\s+(\S+)/);
+  if (!taskDoneMatch) pass();
+
+  const [, featureName, taskId] = taskDoneMatch;
+
+  // Load state and find validationHistory for this task
+  const statePath = join(process.cwd(), '.morph', 'state.json');
+  if (!existsSync(statePath)) pass();
+
+  let state;
+  try {
+    state = JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    pass();
+  }
+
+  const feature = state?.features?.[featureName];
+  if (!feature) pass();
+
+  const taskHistory = feature.validationHistory?.[taskId];
+  if (!taskHistory) pass();
+
+  // Only act on failed validations (passed = no feedback needed)
+  if (taskHistory.status === 'passed') pass();
+
+  // Build remediation context based on validation issues
+  buildRemediationContext(featureName, taskId, taskHistory);
+} catch {
+  // Fail-open
+  process.exit(0);
+}
+
+/**
+ * Build and inject remediation context for a failed validation.
+ *
+ * @param {string} featureName
+ * @param {string} taskId
+ * @param {Object} taskHistory - validationHistory[taskId]
+ */
+function buildRemediationContext(featureName, taskId, taskHistory) {
+  const attempt = taskHistory.attempt || 1;
+  const validators = taskHistory.validators || {};
+
+  // Collect all issues across all validators
+  const allIssues = [];
+  for (const [validatorName, result] of Object.entries(validators)) {
+    if (result.passed) continue;
+    const issues = result.issues || [];
+    for (const issue of issues) {
+      allIssues.push({ validator: validatorName, ...issue });
+    }
+  }
+
+  if (allIssues.length === 0 && taskHistory.status !== 'blocked') pass();
+
+  const lines = [];
+
+  if (taskHistory.status === 'blocked') {
+    // Max attempts reached — escalation message
+    lines.push(`⛔ ESCALATION REQUIRED — Task ${taskId} in feature '${featureName}'`);
+    lines.push(`   Validation failed ${attempt} times (max attempts reached).`);
+    lines.push(`   Human review required before proceeding.`);
+    lines.push(`   Last failures:`);
+    for (const issue of allIssues.slice(0, 5)) {
+      lines.push(`     • [${issue.validator}] ${issue.message} ${issue.file ? `(${issue.file}${issue.line ? ':' + issue.line : ''})` : ''}`);
+    }
+  } else {
+    // Active remediation — attempt N of 3
+    lines.push(`🔄 REMEDIATION REQUIRED — Task ${taskId} (attempt ${attempt}/3)`);
+    lines.push(`   Validation failed. Fix the following issues and re-run:`);
+    lines.push(`   morph-spec task done ${featureName} ${taskId}`);
+    lines.push(``);
+
+    for (const issue of allIssues) {
+      const refKey = getRefKey(issue.rule || issue.validator);
+      const ref = refKey ? ` — Ref: ${STANDARD_REFS[refKey] || refKey}` : '';
+      const location = issue.file
+        ? ` (${issue.file}${issue.line ? ':' + issue.line : ''})`
+        : '';
+      lines.push(`  • [${issue.validator}] ${issue.message}${location}${ref}`);
+    }
+
+    if (attempt >= 2) {
+      lines.push(``);
+      lines.push(`  ⚠️  If this fails again, it will be escalated (attempt ${attempt + 1} = final).`);
+    }
+  }
+
+  injectContext(lines.join('\n'));
+}
+
+/**
+ * Map a rule/validator name to a STANDARD_REFS key.
+ * @param {string} ruleOrValidator
+ * @returns {string|null}
+ */
+function getRefKey(ruleOrValidator) {
+  if (!ruleOrValidator) return null;
+  const lower = ruleOrValidator.toLowerCase();
+  if (lower.includes('di') || lower.includes('dependency') || lower.includes('injection')) return 'di';
+  if (lower.includes('async') || lower.includes('await') || lower.includes('cancellation')) return 'async';
+  if (lower.includes('security') || lower.includes('sql') || lower.includes('xss')) return 'security';
+  if (lower.includes('package') || lower.includes('nuget')) return 'packages';
+  if (lower.includes('design') || lower.includes('css') || lower.includes('naming')) return 'design-system';
+  if (lower.includes('blazor') || lower.includes('dbcontext')) return 'blazor';
+  return null;
+}

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

@@ -17,6 +17,8 @@
  * Fail-open: exits 0 on any error.
  */
 
+import { existsSync } from 'fs';
+import { resolve } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists, getFeaturePhase } from '../../shared/state-reader.js';
 import {
@@ -28,6 +30,12 @@ import {
 import { block, pass } from '../../shared/hook-response.js';
 
 try {
+  // Amend mode: bypass phase write enforcement for legitimate corrections
+  if (process.env.MORPH_AMEND_PHASE) {
+    console.error(`[morph-spec] AMEND MODE: bypassing phase protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
+    pass();
+  }
+
   if (!stateExists()) pass();
 
   const payload = await readStdin();
@@ -55,6 +63,10 @@ try {
   if (!allowedDir) pass(); // Unknown phase — allow
 
   if (targetDir !== allowedDir) {
+    // Allow editing already-existing files from previous phases
+    const absolutePath = resolve(process.cwd(), filePath);
+    if (existsSync(absolutePath)) pass(); // editing existing file — allow
+
     const phaseLabel = phase.toUpperCase();
     block(
       `MORPH-SPEC: Writing to '${targetDir}/' is not allowed during ${phaseLabel} phase.\n` +

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

@@ -24,6 +24,12 @@ import {
 import { block, pass } from '../../shared/hook-response.js';
 
 try {
+  // Amend mode: bypass spec protection for legitimate in-implementation corrections
+  if (process.env.MORPH_AMEND_PHASE) {
+    console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
+    pass();
+  }
+
   if (!stateExists()) pass();
 
   const payload = await readStdin();