@polymorphism-tech/morph-spec 4.8.19 → 4.9.0

package/src/lib/hooks/stop-hook-executor.js

@@ -1,286 +0,0 @@
-/**
- * Stop Hook Executor — L-Thread validation loops
- *
- * Manages stop hooks for Long-Running threads.
- * Executes hook scripts, captures output, provides structured feedback.
- *
- * On failure: writes feedback to .morph/stop-hook-feedback/{threadId}.json
- * Agent reads feedback before retrying.
- *
- * Max retries: 5. Interval: configurable (default: 30 min).
- */
-
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { execSync } from 'child_process';
-import { recordEvent } from '../analytics/analytics-engine.js';
-
-const FEEDBACK_DIR = join(process.cwd(), '.morph/stop-hook-feedback');
-const MAX_RETRIES = 5;
-const DEFAULT_INTERVAL_MINUTES = 30;
-
-// Hook registry — hooks registered for each thread
-const hookRegistry = new Map(); // threadId → [{ hookPath, config }]
-
-// ============================================================================
-// Hook Registration
-// ============================================================================
-
-/**
- * Register a stop hook for a thread
- * @param {string} threadId - Thread ID
- * @param {string} hookPath - Path to hook script
- * @param {Object} [config]
- * @param {string[]} [config.triggers] - When to run: ['interval', 'on-stop', 'on-error']
- * @param {number} [config.intervalMinutes] - Interval for periodic execution
- * @param {boolean} [config.blocking] - Whether failure blocks thread progress
- */
-export function registerStopHook(threadId, hookPath, config = {}) {
-  if (!hookRegistry.has(threadId)) {
-    hookRegistry.set(threadId, []);
-  }
-
-  hookRegistry.get(threadId).push({
-    hookPath,
-    config: {
-      triggers: config.triggers || ['on-stop'],
-      intervalMinutes: config.intervalMinutes || DEFAULT_INTERVAL_MINUTES,
-      blocking: config.blocking !== false,
-      ...config
-    }
-  });
-}
-
-/**
- * Get registered hooks for a thread
- * @param {string} threadId
- * @returns {Array}
- */
-export function getThreadHooks(threadId) {
-  return hookRegistry.get(threadId) || [];
-}
-
-// ============================================================================
-// Hook Execution
-// ============================================================================
-
-/**
- * Execute all stop hooks for a thread
- * @param {string} threadId - Thread ID
- * @param {string} hookType - Trigger type ('interval' | 'on-stop' | 'on-error')
- * @param {Object} [context] - Additional context passed to hooks
- * @returns {Promise<Object>} { passed, feedback, results }
- */
-export async function executeStopHooks(threadId, hookType = 'on-stop', context = {}) {
-  const hooks = hookRegistry.get(threadId) || loadDefaultHooks(threadId);
-  const results = [];
-  let allPassed = true;
-
-  for (const hook of hooks) {
-    if (!hook.config.triggers.includes(hookType) && !hook.config.triggers.includes('all')) {
-      continue;
-    }
-
-    const result = await executeHook(hook.hookPath, { threadId, hookType, ...context });
-    results.push(result);
-
-    if (!result.passed && hook.config.blocking) {
-      allPassed = false;
-    }
-  }
-
-  const passed = allPassed;
-  const feedback = buildFeedback(results, passed);
-
-  if (!passed) {
-    saveFeedback(threadId, feedback);
-  }
-
-  recordEvent({
-    type: passed ? 'stop_hook_passed' : 'stop_hook_failed',
-    data: { threadId, hookType, resultsCount: results.length, passed }
-  });
-
-  return { passed, feedback, results };
-}
-
-/**
- * Execute a single hook script
- * @param {string} hookPath - Path to hook script
- * @param {Object} context - Context passed as environment variables
- * @returns {Promise<Object>} { hookPath, passed, output, error }
- */
-async function executeHook(hookPath, context) {
-  const fullPath = existsSync(hookPath) ? hookPath : join(process.cwd(), hookPath);
-
-  if (!existsSync(fullPath)) {
-    return {
-      hookPath,
-      passed: true, // Missing hooks don't block
-      output: null,
-      error: `Hook not found: ${hookPath} (skipped)`,
-      skipped: true
-    };
-  }
-
-  try {
-    const env = {
-      ...process.env,
-      MORPH_THREAD_ID: context.threadId || '',
-      MORPH_HOOK_TYPE: context.hookType || '',
-      MORPH_FEATURE: context.feature || ''
-    };
-
-    const output = execSync(`node "${fullPath}"`, {
-      encoding: 'utf8',
-      stdio: 'pipe',
-      timeout: 120000, // 2 minute timeout per hook
-      env
-    });
-
-    // Parse JSON output from hook
-    let parsed;
-    try {
-      parsed = JSON.parse(output);
-    } catch {
-      // Non-JSON output means pass (for legacy hooks)
-      parsed = { passed: true, output };
-    }
-
-    return {
-      hookPath,
-      passed: parsed.passed !== false,
-      output: parsed,
-      error: parsed.error || null
-    };
-  } catch (err) {
-    return {
-      hookPath,
-      passed: false,
-      output: null,
-      error: err.message || 'Hook execution failed'
-    };
-  }
-}
-
-// ============================================================================
-// Feedback Management
-// ============================================================================
-
-/**
- * Build structured feedback from hook results
- * @param {Array} results - Hook execution results
- * @param {boolean} passed - Overall pass/fail
- * @returns {Object} Structured feedback
- */
-function buildFeedback(results, passed) {
-  const failures = results.filter(r => !r.passed && !r.skipped);
-  const issues = failures.flatMap(r => {
-    const output = r.output;
-    if (output?.issues) return output.issues;
-    if (output?.errors) return output.errors;
-    if (r.error) return [{ message: r.error, severity: 'error' }];
-    return [];
-  });
-
-  return {
-    passed,
-    timestamp: new Date().toISOString(),
-    hooksRun: results.length,
-    hooksFailed: failures.length,
-    issues,
-    suggestions: failures.flatMap(r => r.output?.suggestions || []),
-    nextAction: passed
-      ? 'continue'
-      : failures.length > 0 ? 'fix-and-retry' : 'investigate'
-  };
-}
-
-/**
- * Save feedback to file for agent to read
- * @param {string} threadId - Thread ID
- * @param {Object} feedback - Feedback object
- * @returns {string} Path to feedback file
- */
-export function saveFeedback(threadId, feedback) {
-  if (!existsSync(FEEDBACK_DIR)) {
-    mkdirSync(FEEDBACK_DIR, { recursive: true });
-  }
-
-  const filePath = join(FEEDBACK_DIR, `${threadId}.json`);
-  writeFileSync(filePath, JSON.stringify(feedback, null, 2), 'utf8');
-  return filePath;
-}
-
-/**
- * Load feedback for a thread (agent reads this after failure)
- * @param {string} threadId - Thread ID
- * @returns {Object|null} Feedback object or null
- */
-export function loadFeedback(threadId) {
-  const filePath = join(FEEDBACK_DIR, `${threadId}.json`);
-  if (!existsSync(filePath)) return null;
-  try {
-    return JSON.parse(readFileSync(filePath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Track retry count for a thread
- * @param {string} threadId
- * @returns {number} Current retry count
- */
-export function getRetryCount(threadId) {
-  const feedback = loadFeedback(threadId);
-  return feedback?.retryCount || 0;
-}
-
-/**
- * Increment retry count
- * @param {string} threadId
- * @returns {number} New retry count
- */
-export function incrementRetryCount(threadId) {
-  const feedback = loadFeedback(threadId) || {};
-  feedback.retryCount = (feedback.retryCount || 0) + 1;
-  saveFeedback(threadId, feedback);
-  return feedback.retryCount;
-}
-
-/**
- * Check if max retries exceeded
- * @param {string} threadId
- * @param {number} [maxRetries=5]
- * @returns {boolean}
- */
-export function isMaxRetriesExceeded(threadId, maxRetries = MAX_RETRIES) {
-  return getRetryCount(threadId) >= maxRetries;
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-function loadDefaultHooks(threadId) {
-  // Load hooks from llm-interaction.json if no hooks registered
-  const configPath = join(process.cwd(), '.morph/config/llm-interaction.json');
-  if (!existsSync(configPath)) return [];
-
-  try {
-    const config = JSON.parse(readFileSync(configPath, 'utf8'));
-    const hookNames = config.stopHooks?.hooks || [];
-
-    return hookNames.map(name => ({
-      hookPath: `framework/hooks/agent-stop/${name}.js`,
-      config: {
-        triggers: ['on-stop', 'interval'],
-        intervalMinutes: config.stopHooks?.interval || DEFAULT_INTERVAL_MINUTES,
-        blocking: true
-      }
-    }));
-  } catch {
-    return [];
-  }
-}

package/src/lib/hops/hop-composer.js

@@ -1,221 +0,0 @@
-/**
- * HOP Composer — Higher-Order Prompt rendering and nesting
- *
- * Compiles Handlebars templates for agent prompts (HOPs).
- * Supports:
- *   - renderHOP(templatePath, variables) → compiled prompt string
- *   - composeHOPs(hopChain[], variables) → nested HOPs (outer wraps inner)
- *   - listAvailableHOPs() → scan meta-prompts/ and return HOPDescriptor[]
- *
- * Standard HOP variables auto-injected:
- *   FEATURE_NAME, AGENT_ID, MISSION, SPEC_SUMMARY, STANDARDS, TASKS,
- *   DELIVERABLES, CONSTRAINTS, DATE, TIMESTAMP
- */
-
-import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
-import { join, relative, extname, basename } from 'path';
-
-const META_PROMPTS_DIR = join(process.cwd(), 'framework/templates/meta-prompts');
-const REGISTRY_PATH = join(process.cwd(), 'framework/templates/REGISTRY.json');
-
-// ============================================================================
-// Handlebars-Compatible Mini-Compiler
-// ============================================================================
-
-/**
- * Compile a Handlebars template with variables (subset of Handlebars features)
- * Supports: {{variable}}, {{#if condition}}...{{/if}}, {{#each array}}...{{/each}}
- * Also supports built-in helpers: {{pascalCase}}, {{camelCase}}, {{snakeCase}}
- *
- * @param {string} template - Handlebars template string
- * @param {Object} variables - Variables to inject
- * @returns {string} Compiled template
- */
-export function compileTemplate(template, variables) {
-  const vars = {
-    DATE: new Date().toISOString().split('T')[0],
-    TIMESTAMP: new Date().toISOString(),
-    ...injectCasedHelpers(variables),
-    ...variables
-  };
-
-  let result = template;
-
-  // 1. Process {{#if VAR}}...{{/if}} blocks
-  result = result.replace(/\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g, (_, key, content) => {
-    return vars[key] ? content : '';
-  });
-
-  // 2. Process {{#each ARRAY}}...{{/each}} blocks
-  result = result.replace(/\{\{#each\s+(\w+)\}\}([\s\S]*?)\{\{\/each\}\}/g, (_, key, content) => {
-    const arr = vars[key];
-    if (!Array.isArray(arr)) return '';
-    return arr.map(item => {
-      const itemVars = typeof item === 'object' ? { ...vars, ...item, this: item } : { ...vars, this: item };
-      return compileTemplate(content, itemVars);
-    }).join('');
-  });
-
-  // 3. Process helper calls: {{pascalCase VARIABLE}}, {{camelCase VARIABLE}}, etc.
-  result = result.replace(/\{\{(pascalCase|camelCase|snakeCase|titleCase|pluralize)\s+(\w+)\}\}/g, (_, helper, key) => {
-    const value = String(vars[key] || '');
-    return applyHelper(helper, value);
-  });
-
-  // 4. Process simple {{VARIABLE}} substitutions
-  result = result.replace(/\{\{(\w+)\}\}/g, (_, key) => {
-    return vars[key] !== undefined ? String(vars[key]) : `{{${key}}}`;
-  });
-
-  return result;
-}
-
-function injectCasedHelpers(variables) {
-  const extras = {};
-  for (const [key, value] of Object.entries(variables)) {
-    if (typeof value === 'string') {
-      extras[`${key}_PASCAL`] = applyHelper('pascalCase', value);
-      extras[`${key}_CAMEL`] = applyHelper('camelCase', value);
-      extras[`${key}_SNAKE`] = applyHelper('snakeCase', value);
-    }
-  }
-  return extras;
-}
-
-function applyHelper(helper, value) {
-  const words = value.replace(/[-_\s]+/g, ' ').trim().split(' ');
-  switch (helper) {
-    case 'pascalCase':
-      return words.map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
-    case 'camelCase':
-      return words[0].toLowerCase() + words.slice(1).map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
-    case 'snakeCase':
-      return value.replace(/[-\s]+/g, '_').replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase();
-    case 'titleCase':
-      return words.map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ');
-    case 'pluralize':
-      const last = value.slice(-1);
-      if (last === 'y') return value.slice(0, -1) + 'ies';
-      if (last === 's') return value;
-      return value + 's';
-    default:
-      return value;
-  }
-}
-
-// ============================================================================
-// HOP Rendering
-// ============================================================================
-
-/**
- * Render a HOP template with variables
- * @param {string} templatePath - Path to template (relative to meta-prompts/ or absolute)
- * @param {Object} variables - Variables to inject
- * @returns {string} Rendered prompt string
- */
-export function renderHOP(templatePath, variables = {}) {
-  // Resolve template path
-  const paths = [
-    templatePath,
-    join(META_PROMPTS_DIR, templatePath),
-    join(META_PROMPTS_DIR, templatePath + '.md'),
-    join(process.cwd(), templatePath)
-  ];
-
-  let resolved = null;
-  for (const p of paths) {
-    if (existsSync(p)) {
-      resolved = p;
-      break;
-    }
-  }
-
-  if (!resolved) {
-    throw new Error(`HOP template not found: ${templatePath}\nSearched: ${paths.join(', ')}`);
-  }
-
-  const template = readFileSync(resolved, 'utf8');
-  return compileTemplate(template, variables);
-}
-
-/**
- * Compose nested HOPs (outer wraps inner, variables bubble down)
- * @param {Array} hopChain - Array of { templatePath, variables } objects (outer first)
- * @param {Object} [sharedVariables] - Variables shared across all HOPs
- * @returns {string} Composed prompt string
- */
-export function composeHOPs(hopChain, sharedVariables = {}) {
-  if (!hopChain || hopChain.length === 0) {
-    throw new Error('hopChain must be a non-empty array');
-  }
-
-  if (hopChain.length === 1) {
-    return renderHOP(hopChain[0].templatePath, { ...sharedVariables, ...hopChain[0].variables });
-  }
-
-  // Render inner HOPs first, then wrap with outer
-  let innerContent = '';
-  for (let i = hopChain.length - 1; i >= 1; i--) {
-    const hop = hopChain[i];
-    const vars = { ...sharedVariables, ...hop.variables, INNER_PROMPT: innerContent };
-    innerContent = renderHOP(hop.templatePath, vars);
-  }
-
-  // Render outermost HOP with inner content
-  const outerHop = hopChain[0];
-  return renderHOP(outerHop.templatePath, {
-    ...sharedVariables,
-    ...outerHop.variables,
-    INNER_PROMPT: innerContent
-  });
-}
-
-// ============================================================================
-// HOP Discovery
-// ============================================================================
-
-/**
- * List all available HOPs from the meta-prompts directory
- * @returns {Array} Array of HOPDescriptor objects
- */
-export function listAvailableHOPs() {
-  if (!existsSync(META_PROMPTS_DIR)) return [];
-
-  const hops = [];
-  scanDir(META_PROMPTS_DIR, META_PROMPTS_DIR, hops);
-  return hops;
-}
-
-function scanDir(dir, baseDir, hops) {
-  if (!existsSync(dir)) return;
-
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      scanDir(fullPath, baseDir, hops);
-    } else if (entry.name.endsWith('.md') || entry.name.endsWith('.hbs')) {
-      const relPath = relative(baseDir, fullPath);
-      const content = readFileSync(fullPath, 'utf8');
-      const firstLine = content.split('\n')[0] || '';
-      const description = firstLine.startsWith('#')
-        ? firstLine.replace(/^#+\s*/, '')
-        : 'Higher-Order Prompt template';
-
-      // Extract variables from template
-      const variables = [...new Set(
-        (content.match(/\{\{(\w+)\}\}/g) || [])
-          .map(m => m.replace(/\{\{|\}\}/g, ''))
-          .filter(v => !['if', 'each', 'this', 'else', 'pascalCase', 'camelCase', 'snakeCase', 'titleCase', 'pluralize'].includes(v))
-      )];
-
-      hops.push({
-        id: relPath.replace(/\\/g, '/').replace(/\.(md|hbs)$/, ''),
-        path: fullPath,
-        relativePath: relPath.replace(/\\/g, '/'),
-        description,
-        variables,
-        category: relPath.split(/[\\/]/)[0]
-      });
-    }
-  }
-}