@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

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

package/framework/hooks/claude-code/session-start/inject-morph-context.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart Hook: Inject MORPH-SPEC Context
+ *
+ * Event: SessionStart | Matcher: startup|resume|compact
+ *
+ * Reads state.json and injects a summary as additionalContext so Claude
+ * knows the current morph-spec state at session start.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { loadState, getActiveFeature, getPendingGates, getMissingOutputs } from '../../shared/state-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const SPEC_MAX_CHARS = 3000;
+
+try {
+  if (!stateExists()) pass();
+
+  const state = loadState();
+  if (!state?.features || Object.keys(state.features).length === 0) pass();
+
+  const active = getActiveFeature();
+  const lines = ['MORPH-SPEC Status:'];
+
+  if (active) {
+    const { name, feature } = active;
+    lines.push(`- Active feature: ${name} (phase: ${feature.phase}, workflow: ${feature.workflow || 'auto'})`);
+    lines.push(`- Status: ${feature.status}`);
+
+    // Task progress
+    if (feature.tasks) {
+      lines.push(`- Tasks: ${feature.tasks.completed || 0}/${feature.tasks.total || 0} completed`);
+    }
+
+    // Pending approvals
+    const pending = getPendingGates(name);
+    if (pending.length > 0) {
+      lines.push(`- Pending approvals: ${pending.join(', ')}`);
+    }
+
+    // Next required output
+    const missing = getMissingOutputs(name);
+    if (missing.length > 0) {
+      const next = missing[0];
+      lines.push(`- Next required output: ${next.type} → ${next.path}`);
+    }
+
+    // Checkpoints
+    if (feature.checkpoints?.length > 0) {
+      const lastCp = feature.checkpoints[feature.checkpoints.length - 1];
+      lines.push(`- Last checkpoint: #${lastCp.checkpointNum} (${lastCp.passed ? 'passed' : 'failed'})`);
+    }
+
+    // Active feature spec (truncated for context budget)
+    const specPath = join(process.cwd(), `.morph/features/${name}/1-design/spec.md`);
+    if (existsSync(specPath)) {
+      try {
+        const specContent = readFileSync(specPath, 'utf-8');
+        const truncated = specContent.length > SPEC_MAX_CHARS
+          ? specContent.slice(0, SPEC_MAX_CHARS) + `\n\n[... spec truncated — full file at .morph/features/${name}/1-design/spec.md]`
+          : specContent;
+        lines.push('');
+        lines.push(`--- Active feature spec (${name}/1-design/spec.md) ---`);
+        lines.push(truncated);
+        lines.push('--- End spec ---');
+      } catch {
+        // Non-blocking: skip spec injection on read error
+      }
+    }
+  } else {
+    // Show summary of all features
+    const featureNames = Object.keys(state.features);
+    lines.push(`- Features: ${featureNames.length} (${featureNames.join(', ')})`);
+
+    for (const [name, feature] of Object.entries(state.features)) {
+      lines.push(`  - ${name}: phase=${feature.phase}, status=${feature.status}`);
+    }
+  }
+
+  // Remind about key commands
+  lines.push('');
+  lines.push('Key commands: morph-spec status <feature> | morph-spec phase advance <feature> | morph-spec approve <feature> <gate>');
+
+  injectContext(lines.join('\n'));
+} catch {
+  // Fail-open
+  process.exit(0);
+}