@polymorphism-tech/morph-spec 4.7.1 → 4.8.1

package/framework/hooks/dev/check-sync-health.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * Dev Stop Hook: Sync Health Check (Advisory)
+ *
+ * Event: Stop
+ * Scope: Framework codebase only (dev hook)
+ *
+ * When Claude stops, checks for out-of-sync conditions:
+ *   1. Templates not in REGISTRY.json
+ *   2. Standards not in STANDARDS.json
+ *
+ * Uses readdirSync (no git dependency, fast).
+ * Returns advisory context if out-of-sync items found.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { injectContext, pass } from '../shared/hook-response.js';
+
+/**
+ * Recursively collect .md files from a directory.
+ * @param {string} dir - Directory to scan
+ * @param {string} [base] - Base path for relative paths
+ * @returns {string[]} Relative paths
+ */
+function collectMdFiles(dir, base) {
+  base = base || dir;
+  const results = [];
+  if (!existsSync(dir)) return results;
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules') continue;
+        results.push(...collectMdFiles(fullPath, base));
+      } else if (entry.name.endsWith('.md') && entry.name !== 'README.md') {
+        const rel = fullPath.replace(base + '/', '').replace(base + '\\', '').replace(/\\/g, '/');
+        results.push(rel);
+      }
+    }
+  } catch {
+    // Fail-open
+  }
+
+  return results;
+}
+
+try {
+  // Prevent infinite loop
+  if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
+
+  const warnings = [];
+
+  // Check templates vs REGISTRY.json
+  const registryPath = 'framework/templates/REGISTRY.json';
+  if (existsSync(registryPath)) {
+    try {
+      const registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+      const registeredPaths = new Set((registry.templates || []).map(t => t.path));
+      const templateFiles = collectMdFiles('framework/templates');
+
+      const unregistered = templateFiles.filter(f => !registeredPaths.has(f));
+      if (unregistered.length > 0) {
+        warnings.push(`Templates not in REGISTRY.json (${unregistered.length}):`);
+        for (const f of unregistered.slice(0, 5)) {
+          warnings.push(`  - ${f}`);
+        }
+        if (unregistered.length > 5) {
+          warnings.push(`  ... and ${unregistered.length - 5} more`);
+        }
+      }
+    } catch {
+      // Skip on error
+    }
+  }
+
+  // Check standards vs STANDARDS.json
+  const standardsPath = 'framework/standards/STANDARDS.json';
+  if (existsSync(standardsPath)) {
+    try {
+      const registry = JSON.parse(readFileSync(standardsPath, 'utf-8'));
+      const registeredPaths = new Set((registry.standards || []).map(s => s.path));
+      const standardFiles = collectMdFiles('framework/standards');
+
+      const unregistered = standardFiles.filter(f => !registeredPaths.has(f));
+      if (unregistered.length > 0) {
+        warnings.push(`Standards not in STANDARDS.json (${unregistered.length}):`);
+        for (const f of unregistered.slice(0, 5)) {
+          warnings.push(`  - ${f}`);
+        }
+        if (unregistered.length > 5) {
+          warnings.push(`  ... and ${unregistered.length - 5} more`);
+        }
+        warnings.push('  Run: node scripts/generate-standards-registry.js');
+      }
+    } catch {
+      // Skip on error
+    }
+  }
+
+  if (warnings.length === 0) pass();
+
+  const message = [
+    'MORPH-SPEC Dev: Out-of-sync items detected:',
+    ...warnings.map(w => `  ${w}`),
+  ].join('\n');
+
+  injectContext(message);
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/dev/guard-version-numbers.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PreToolUse Hook: Guard Version Numbers
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ * Scope: Framework codebase only (dev hook)
+ *
+ * Blocks Write/Edit to files that contain hardcoded version patterns
+ * like "MORPH-SPEC v4.8.1". Version should only be in package.json.
+ *
+ * Checked extensions: .md, .cs, .css, .js (covers templates + source)
+ * Exceptions: CHANGELOG.md, node_modules/, test/, package.json, package-lock.json
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath, getContentToValidate } from '../shared/payload-utils.js';
+import { block, pass } from '../shared/hook-response.js';
+
+const VERSION_PATTERN = /MORPH-SPEC\s+v\d+\.\d+\.\d+/;
+const CHECKED_EXTENSIONS = ['.md', '.cs', '.css', '.js', '.html', '.txt'];
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check relevant file types
+  if (!CHECKED_EXTENSIONS.some(ext => filePath.endsWith(ext))) pass();
+
+  // Exceptions
+  if (filePath.includes('node_modules/')) pass();
+  if (filePath.endsWith('CHANGELOG.md')) pass();
+  if (filePath.includes('test/')) pass();
+  if (filePath.endsWith('package.json')) pass();
+  if (filePath.endsWith('package-lock.json')) pass();
+
+  const content = getContentToValidate(payload);
+  if (!content) pass();
+
+  if (VERSION_PATTERN.test(content)) {
+    block(
+      `MORPH-SPEC: Hardcoded version number detected in '${filePath}'.\n` +
+      `Version should only be in package.json. Use 'MORPH-SPEC by Polymorphism Tech' without version.\n` +
+      `Pattern found: ${content.match(VERSION_PATTERN)?.[0]}`
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/dev/sync-standards-registry.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PostToolUse Hook: Standards Registry Sync Advisory
+ *
+ * Event: PostToolUse | Matcher: Write
+ * Scope: Framework codebase only (dev hook)
+ *
+ * After a Write to framework/standards/**/*.md, checks if the file
+ * is registered in framework/standards/STANDARDS.json.
+ * If not, injects an advisory to regenerate the registry.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath } from '../shared/payload-utils.js';
+import { approve, pass } from '../shared/hook-response.js';
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check framework/standards/**/*.md
+  if (!filePath.includes('framework/standards/')) pass();
+  if (!filePath.endsWith('.md')) pass();
+
+  // Skip meta files
+  const basename = filePath.split('/').pop();
+  if (basename === 'README.md') pass();
+  if (basename === 'STANDARDS.json') pass();
+
+  // Extract relative path from framework/standards/
+  const standardsIdx = filePath.indexOf('framework/standards/');
+  if (standardsIdx === -1) pass();
+  const relativePath = filePath.slice(standardsIdx + 'framework/standards/'.length);
+
+  // Read STANDARDS.json
+  const registryPath = 'framework/standards/STANDARDS.json';
+  if (!existsSync(registryPath)) pass();
+
+  const registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+  const registeredPaths = (registry.standards || []).map(s => s.path);
+
+  if (!registeredPaths.includes(relativePath)) {
+    approve(
+      `MORPH-SPEC: Standard '${relativePath}' is not in STANDARDS.json.\n` +
+      `Run: node scripts/generate-standards-registry.js`
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/dev/sync-template-registry.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PostToolUse Hook: Template Registry Sync Advisory
+ *
+ * Event: PostToolUse | Matcher: Write
+ * Scope: Framework codebase only (dev hook)
+ *
+ * After a Write to framework/templates/**/*.md, checks if the file
+ * is registered in framework/templates/REGISTRY.json.
+ * If not, injects an advisory to add the entry.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath } from '../shared/payload-utils.js';
+import { approve, pass } from '../shared/hook-response.js';
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check framework/templates/**/*.md
+  if (!filePath.includes('framework/templates/')) pass();
+  if (!filePath.endsWith('.md')) pass();
+
+  // Skip meta files
+  const basename = filePath.split('/').pop();
+  if (basename === 'README.md') pass();
+  if (basename === 'REGISTRY.json') pass();
+
+  // Extract relative path from framework/templates/
+  const templateIdx = filePath.indexOf('framework/templates/');
+  if (templateIdx === -1) pass();
+  const relativePath = filePath.slice(templateIdx + 'framework/templates/'.length);
+
+  // Read REGISTRY.json
+  const registryPath = 'framework/templates/REGISTRY.json';
+  if (!existsSync(registryPath)) pass();
+
+  const registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+  const registeredPaths = (registry.templates || []).map(t => t.path);
+
+  if (!registeredPaths.includes(relativePath)) {
+    approve(
+      `MORPH-SPEC: Template '${relativePath}' is not in REGISTRY.json.\n` +
+      `Add an entry to framework/templates/REGISTRY.json with id, path, phase, and outputName fields.`
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/dev/validate-skill-format.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PreToolUse Hook: Validate Skill Frontmatter Format
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ * Scope: Framework codebase only (dev hook)
+ *
+ * Validates that SKILL.md files written to framework/skills/ have valid
+ * YAML frontmatter with required `name:` and `description:` fields.
+ *
+ * Only validates on Write (full content). Edit operations pass through.
+ * Simple regex parsing (no YAML library dependency).
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath, getContentToValidate, isWriteOperation } from '../shared/payload-utils.js';
+import { block, pass } from '../shared/hook-response.js';
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check framework/skills/**/SKILL.md
+  if (!filePath.includes('framework/skills/')) pass();
+  if (!filePath.endsWith('SKILL.md')) pass();
+
+  // Only validate full Write operations (not Edit patches)
+  if (!isWriteOperation(payload)) pass();
+
+  const content = getContentToValidate(payload);
+  if (!content) pass();
+
+  // Check for YAML frontmatter delimiters
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!frontmatterMatch) {
+    block(
+      `MORPH-SPEC: SKILL.md at '${filePath}' is missing YAML frontmatter.\n` +
+      'All skill files must start with --- delimited YAML frontmatter containing name: and description: fields.'
+    );
+  }
+
+  const frontmatter = frontmatterMatch[1];
+  const missing = [];
+
+  if (!/^name:/m.test(frontmatter)) {
+    missing.push('name:');
+  }
+  if (!/^description:/m.test(frontmatter)) {
+    missing.push('description:');
+  }
+
+  if (missing.length > 0) {
+    block(
+      `MORPH-SPEC: SKILL.md at '${filePath}' is missing required frontmatter fields:\n` +
+      missing.map(m => `  - ${m}`).join('\n') + '\n\n' +
+      'All skill files must have name: and description: in their YAML frontmatter.'
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/dev/validate-standard-format.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PreToolUse Hook: Validate Standard Format
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ * Scope: Framework codebase only (dev hook)
+ *
+ * Validates that files written to framework/standards/ follow the required format:
+ *   - `> **Scope:**` metadata header
+ *   - `> **Layer:**` metadata header
+ *   - `> **Keywords:**` metadata header
+ *   - Footer: `*MORPH-SPEC by Polymorphism Tech*`
+ *
+ * Only validates on Write (full content). Edit operations pass through.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath, getContentToValidate, isWriteOperation } from '../shared/payload-utils.js';
+import { block, pass } from '../shared/hook-response.js';
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check framework/standards/**/*.md
+  if (!filePath.includes('framework/standards/')) pass();
+  if (!filePath.endsWith('.md')) pass();
+
+  // Skip non-standard files
+  const basename = filePath.split('/').pop();
+  if (basename === 'README.md') pass();
+  if (basename === 'STANDARDS.json') pass();
+
+  // Only validate full Write operations (not Edit patches)
+  if (!isWriteOperation(payload)) pass();
+
+  const content = getContentToValidate(payload);
+  if (!content) pass();
+
+  const missing = [];
+
+  if (!/>\s*\*\*Scope:\*\*/.test(content)) {
+    missing.push('> **Scope:** metadata header');
+  }
+  if (!/>\s*\*\*Layer:\*\*/.test(content)) {
+    missing.push('> **Layer:** metadata header');
+  }
+  if (!/>\s*\*\*Keywords:\*\*/.test(content)) {
+    missing.push('> **Keywords:** metadata header');
+  }
+  if (!/\*MORPH-SPEC by Polymorphism Tech\*/.test(content)) {
+    missing.push('Footer: *MORPH-SPEC by Polymorphism Tech*');
+  }
+
+  if (missing.length > 0) {
+    block(
+      `MORPH-SPEC: Standard file '${basename}' is missing required format elements:\n` +
+      missing.map(m => `  - ${m}`).join('\n') + '\n\n' +
+      'All framework standards must include Scope/Layer/Keywords metadata headers and the standard footer.'
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/shared/payload-utils.js

@@ -0,0 +1,39 @@
+/**
+ * Shared payload utilities for Claude Code Write/Edit hooks.
+ *
+ * Extracts file path and content from tool_input payloads,
+ * normalizing between Write (content, file_path) and Edit (new_string, old_string, file_path).
+ */
+
+/**
+ * Get the file path from a hook payload, normalizing backslashes.
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Normalized file path or empty string
+ */
+export function getFilePath(payload) {
+  const raw = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  return raw.replace(/\\/g, '/');
+}
+
+/**
+ * Get the content being written or edited.
+ * For Write: returns `content` (full file content).
+ * For Edit: returns `new_string` (replacement text).
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Content string or empty string
+ */
+export function getContentToValidate(payload) {
+  const input = payload?.tool_input;
+  if (!input) return '';
+  // Write tool uses 'content', Edit tool uses 'new_string'
+  return input.content || input.new_string || '';
+}
+
+/**
+ * Check if this is a Write operation (full file content available).
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {boolean} True if Write (content exists), false if Edit or unknown
+ */
+export function isWriteOperation(payload) {
+  return typeof payload?.tool_input?.content === 'string';
+}

package/framework/hooks/shared/state-reader.js

@@ -73,15 +73,39 @@ export function getFeature(featureName, projectPath) {
   return state?.features?.[featureName] || null;
 }
 
+/**
+ * Derive phase from filesystem (v5.0.0+: phase deleted from state).
+ * Checks for phase folders in descending order, returns highest present.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string} Phase name
+ */
+export function derivePhaseForFeature(featureName, projectPath) {
+  const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
+  const phaseMap = [
+    ['4-implement', 'implement'],
+    ['3-tasks', 'tasks'],
+    ['2-ui', 'uiux'],
+    ['1-design', 'design'],
+    ['0-proposal', 'proposal'],
+  ];
+  for (const [folder, phase] of phaseMap) {
+    if (existsSync(join(basePath, folder))) return phase;
+  }
+  return 'setup';
+}
+
 /**
  * Get the current phase of a feature.
+ * Falls back to filesystem derivation when phase is not in state (v5.0.0+).
  * @param {string} featureName
  * @param {string} [projectPath]
  * @returns {string|null}
  */
 export function getFeaturePhase(featureName, projectPath) {
   const feature = getFeature(featureName, projectPath);
-  return feature?.phase || null;
+  if (!feature) return null;
+  return feature.phase || derivePhaseForFeature(featureName, projectPath);
 }
 
 /**

package/framework/rules/morph-workflow.md

@@ -58,7 +58,7 @@ Run a checkpoint every 3 completed tasks:
 **Design Gate:** Before moving from Design → Tasks, spec must be approved.
 **Implementation Gate:** Before starting implementation, task list must be approved.
 
-Check approval status: `morph-spec state show {feature}`
+Check approval status: `morph-spec approval-status {feature}`
 
 ---