murmur8 3.5.0

package/src/retry.js

@@ -0,0 +1,274 @@
+const fs = require('fs');
+const path = require('path');
+const { readHistoryFile } = require('./history');
+
+const CONFIG_FILE = '.claude/retry-config.json';
+
+/**
+ * Returns the default retry configuration.
+ * Per FEATURE_SPEC.md defaults.
+ */
+function getDefaultConfig() {
+  return {
+    maxRetries: 3,
+    windowSize: 10,
+    highFailureThreshold: 0.2,
+    strategies: {
+      alex: ['simplify-prompt', 'add-context'],
+      cass: ['reduce-stories', 'simplify-prompt'],
+      nigel: ['simplify-tests', 'add-context'],
+      'codey-plan': ['add-context', 'simplify-prompt'],
+      'codey-implement': ['incremental', 'rollback']
+    }
+  };
+}
+
+/**
+ * Ensures the .claude directory exists.
+ */
+function ensureConfigDir() {
+  const dir = path.dirname(CONFIG_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Reads the retry config from file.
+ * Returns defaults if file is missing or corrupted.
+ */
+function readConfig() {
+  ensureConfigDir();
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return getDefaultConfig();
+  }
+  try {
+    const content = fs.readFileSync(CONFIG_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    // Graceful degradation: return defaults on parse error
+    return getDefaultConfig();
+  }
+}
+
+/**
+ * Writes the retry config to file.
+ * Creates .claude directory if needed.
+ */
+function writeConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Resets config to defaults by writing default config to file.
+ */
+function resetConfig() {
+  writeConfig(getDefaultConfig());
+}
+
+/**
+ * Calculates failure rate for a stage over a sliding window.
+ * @param {string} stage - The pipeline stage name
+ * @param {Array} history - Array of history entries
+ * @param {number} windowSize - Number of recent entries to consider
+ * @returns {number} Failure rate between 0 and 1
+ */
+function calculateFailureRate(stage, history, windowSize = 10) {
+  // Handle corrupted history gracefully
+  if (!Array.isArray(history) || history.length === 0) {
+    return 0;
+  }
+  const recent = history.slice(-windowSize);
+  if (recent.length === 0) return 0;
+  const failedAtStage = recent.filter(
+    e => e.status === 'failed' && e.failedStage === stage
+  ).length;
+  return failedAtStage / recent.length;
+}
+
+/**
+ * Recommends a retry strategy based on attempt count and failure rate.
+ * @param {string} stage - The pipeline stage name
+ * @param {number} attemptCount - Current attempt number (1-based)
+ * @param {number} failureRate - Calculated failure rate (0-1)
+ * @param {object} config - Retry configuration object
+ * @returns {string} Strategy name or 'abort-recommended'
+ */
+function recommendStrategy(stage, attemptCount, failureRate, config) {
+  if (attemptCount > config.maxRetries) {
+    return 'abort-recommended';
+  }
+  if (failureRate > config.highFailureThreshold) {
+    const strategies = config.strategies[stage] || [];
+    const idx = Math.min(attemptCount - 1, strategies.length - 1);
+    return strategies[idx] || 'retry';
+  }
+  return 'retry';
+}
+
+/**
+ * Applies a strategy by modifying the prompt.
+ * @param {string} strategy - The strategy name
+ * @param {string} originalPrompt - The original prompt text
+ * @returns {string} Modified prompt or original if no modification needed
+ */
+function applyStrategy(strategy, originalPrompt) {
+  const modifications = {
+    'retry': null,
+    'simplify-prompt': 'Focus on core requirements only. Skip edge cases and optional sections.',
+    'reduce-stories': 'Write only the 2-3 most critical user stories. Defer others to follow-up.',
+    'simplify-tests': 'Write only happy-path tests for each AC. Skip edge cases.',
+    'add-context': '[Context from previous stage prepended]',
+    'incremental': 'Implement one test at a time. Stop and report after each.',
+    'rollback': 'git checkout -- .'
+  };
+  const mod = modifications[strategy];
+  return mod ? `${originalPrompt}\n\n${mod}` : originalPrompt;
+}
+
+/**
+ * Orchestrator entry point: determines if/how to retry a failed stage.
+ * @param {string} stage - The pipeline stage that failed
+ * @param {string} featureSlug - The feature being implemented
+ * @param {Array|null} history - History entries (pass null to read from file)
+ * @param {object|null} config - Config object (pass null to read from file)
+ * @param {number} attemptCount - Current attempt number (1-based)
+ * @returns {object} Recommendation object with strategy and metadata
+ */
+function shouldRetry(stage, featureSlug, history, config, attemptCount) {
+  // Read history from file if not provided
+  let historyData = history;
+  if (historyData === null || historyData === undefined) {
+    historyData = readHistoryFile();
+    // Handle corrupted history
+    if (historyData && historyData.error === 'corrupted') {
+      historyData = [];
+    }
+  }
+
+  // Read config from file if not provided
+  const configData = config || readConfig();
+
+  const failureRate = calculateFailureRate(
+    stage,
+    historyData,
+    configData.windowSize
+  );
+
+  const strategy = recommendStrategy(
+    stage,
+    attemptCount,
+    failureRate,
+    configData
+  );
+
+  return {
+    stage,
+    featureSlug,
+    attemptCount,
+    failureRate,
+    strategy,
+    shouldRetry: strategy !== 'abort-recommended',
+    maxRetries: configData.maxRetries
+  };
+}
+
+/**
+ * Displays the current retry configuration.
+ */
+function displayConfig() {
+  const config = readConfig();
+  console.log('\nRetry Configuration\n');
+  console.log(`  Max retries:            ${config.maxRetries}`);
+  console.log(`  Window size:            ${config.windowSize}`);
+  console.log(`  High failure threshold: ${config.highFailureThreshold}`);
+  console.log('\n  Stage Strategies:');
+  for (const [stage, strategies] of Object.entries(config.strategies)) {
+    console.log(`    ${stage.padEnd(16)}: ${strategies.join(' -> ')}`);
+  }
+  console.log('');
+}
+
+/**
+ * Sets a config value by key.
+ * @param {string} key - Config key (maxRetries, windowSize, highFailureThreshold)
+ * @param {string} value - New value (will be parsed appropriately)
+ */
+function setConfigValue(key, value) {
+  const config = readConfig();
+  const numericKeys = ['maxRetries', 'windowSize', 'highFailureThreshold'];
+
+  if (!numericKeys.includes(key)) {
+    throw new Error(
+      `Unknown config key: ${key}. Valid keys: ${numericKeys.join(', ')}`
+    );
+  }
+
+  const numValue = parseFloat(value);
+  if (isNaN(numValue)) {
+    throw new Error(`Invalid value for ${key}: ${value}. Must be a number.`);
+  }
+
+  // Validate specific constraints
+  if (key === 'maxRetries' && (numValue < 0 || !Number.isInteger(numValue))) {
+    throw new Error('maxRetries must be a non-negative integer.');
+  }
+  if (key === 'windowSize' && (numValue < 1 || !Number.isInteger(numValue))) {
+    throw new Error('windowSize must be a positive integer.');
+  }
+  if (key === 'highFailureThreshold' && (numValue < 0 || numValue > 1)) {
+    throw new Error('highFailureThreshold must be between 0 and 1.');
+  }
+
+  config[key] = numValue;
+  writeConfig(config);
+  console.log(`Set ${key} = ${numValue}`);
+}
+
+/**
+ * Maps feedback issues to retry strategies using issue mappings config.
+ * Per FEATURE_SPEC.md:Rule 3.
+ * @param {Array} issues - Array of issue codes from feedback
+ * @param {object} config - Config with issueMappings (from feedback config)
+ * @returns {Array} Array of recommended strategies
+ */
+function mapIssuesToStrategies(issues, config) {
+  if (!issues || !Array.isArray(issues) || issues.length === 0) {
+    return ['retry'];
+  }
+
+  const mappings = config?.issueMappings || {
+    'missing-error-handling': 'add-context',
+    'unclear-scope': 'simplify-prompt',
+    'too-complex': 'simplify-prompt',
+    'too-many-stories': 'reduce-stories',
+    'untestable-criteria': 'simplify-tests',
+    'missing-edge-cases': 'add-context'
+  };
+
+  const strategies = [];
+  for (const issue of issues) {
+    const strategy = mappings[issue];
+    if (strategy && !strategies.includes(strategy)) {
+      strategies.push(strategy);
+    }
+  }
+
+  return strategies.length > 0 ? strategies : ['retry'];
+}
+
+module.exports = {
+  CONFIG_FILE,
+  getDefaultConfig,
+  readConfig,
+  writeConfig,
+  resetConfig,
+  calculateFailureRate,
+  recommendStrategy,
+  applyStrategy,
+  shouldRetry,
+  displayConfig,
+  setConfigValue,
+  mapIssuesToStrategies
+};

package/src/stack.js

@@ -0,0 +1,320 @@
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_FILE = '.claude/stack-config.json';
+
+/**
+ * Returns the default (empty) stack configuration.
+ */
+function getDefaultStackConfig() {
+  return {
+    language: '',
+    runtime: '',
+    packageManager: '',
+    frameworks: [],
+    testRunner: '',
+    testCommand: '',
+    linter: '',
+    tools: []
+  };
+}
+
+/**
+ * Ensures the .claude directory exists.
+ */
+function ensureConfigDir() {
+  const dir = path.dirname(CONFIG_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Reads the stack config from file.
+ * Returns defaults if file is missing or corrupted.
+ */
+function readStackConfig() {
+  ensureConfigDir();
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return getDefaultStackConfig();
+  }
+  try {
+    const content = fs.readFileSync(CONFIG_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    return getDefaultStackConfig();
+  }
+}
+
+/**
+ * Writes the stack config to file.
+ */
+function writeStackConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Resets stack config to defaults by writing empty config to file.
+ */
+function resetStackConfig() {
+  writeStackConfig(getDefaultStackConfig());
+}
+
+const VALID_KEYS = [
+  'language', 'runtime', 'packageManager',
+  'frameworks', 'testRunner', 'testCommand',
+  'linter', 'tools'
+];
+
+const ARRAY_KEYS = ['frameworks', 'tools'];
+
+/**
+ * Sets a config value by key.
+ * Array keys (frameworks, tools) accept JSON array strings.
+ * @param {string} key - Config key
+ * @param {string} value - New value (string or JSON array string)
+ */
+function setStackConfigValue(key, value) {
+  if (!VALID_KEYS.includes(key)) {
+    throw new Error(
+      `Unknown config key: ${key}. Valid keys: ${VALID_KEYS.join(', ')}`
+    );
+  }
+
+  const config = readStackConfig();
+
+  if (ARRAY_KEYS.includes(key)) {
+    // Try parsing as JSON array
+    try {
+      const parsed = JSON.parse(value);
+      if (!Array.isArray(parsed)) {
+        throw new Error(`${key} must be a JSON array, e.g. '["express","react"]'`);
+      }
+      config[key] = parsed;
+    } catch (err) {
+      if (err.message.includes('must be a JSON array')) throw err;
+      throw new Error(`${key} must be a valid JSON array, e.g. '["express","react"]'`);
+    }
+  } else {
+    config[key] = value;
+  }
+
+  writeStackConfig(config);
+  const display = Array.isArray(config[key]) ? JSON.stringify(config[key]) : config[key];
+  console.log(`Set ${key} = ${display}`);
+}
+
+/**
+ * Auto-detect tech stack from project files.
+ * Scans for manifest files and infers configuration.
+ * @param {string} projectDir - Directory to scan (defaults to cwd)
+ * @returns {object} Detected stack config
+ */
+function detectStackConfig(projectDir) {
+  const dir = projectDir || process.cwd();
+  const config = getDefaultStackConfig();
+
+  const exists = (file) => fs.existsSync(path.join(dir, file));
+  const readJSON = (file) => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+    } catch {
+      return null;
+    }
+  };
+  const readText = (file) => {
+    try {
+      return fs.readFileSync(path.join(dir, file), 'utf8');
+    } catch {
+      return null;
+    }
+  };
+
+  // Node.js / JavaScript detection
+  if (exists('package.json')) {
+    config.language = 'JavaScript';
+    config.runtime = 'Node.js';
+
+    const pkg = readJSON('package.json');
+    if (pkg) {
+      // Runtime version from engines
+      if (pkg.engines && pkg.engines.node) {
+        config.runtime = `Node.js ${pkg.engines.node}`;
+      }
+
+      const deps = pkg.dependencies || {};
+      const devDeps = pkg.devDependencies || {};
+      const allDeps = { ...deps, ...devDeps };
+
+      // Frameworks
+      const frameworkNames = [
+        'express', 'fastify', 'koa', 'react', 'next',
+        'vue', 'angular', 'hapi', 'nest', '@hapi/hapi', '@nestjs/core'
+      ];
+      const detected = [];
+      for (const fw of frameworkNames) {
+        if (fw in deps || fw in devDeps) {
+          // Normalize package names to friendly names
+          if (fw === '@hapi/hapi') detected.push('hapi');
+          else if (fw === '@nestjs/core') detected.push('nest');
+          else detected.push(fw);
+        }
+      }
+      if (detected.length > 0) config.frameworks = detected;
+
+      // Test runner
+      const testRunners = ['jest', 'mocha', 'vitest', 'ava'];
+      for (const tr of testRunners) {
+        if (tr in devDeps || tr in deps) {
+          config.testRunner = tr;
+          break;
+        }
+      }
+
+      // Test command from scripts
+      if (pkg.scripts && pkg.scripts.test) {
+        config.testCommand = pkg.scripts.test;
+        // Also try to detect test runner from test script if not found in deps
+        if (!config.testRunner) {
+          for (const tr of testRunners) {
+            if (pkg.scripts.test.includes(tr)) {
+              config.testRunner = tr;
+              break;
+            }
+          }
+        }
+      }
+      if (!config.testCommand) {
+        config.testCommand = 'npm test';
+      }
+
+      // Linter
+      const linters = ['eslint', 'biome', 'oxlint', '@biomejs/biome'];
+      for (const l of linters) {
+        if (l in devDeps || l in deps) {
+          if (l === '@biomejs/biome') config.linter = 'biome';
+          else config.linter = l;
+          break;
+        }
+      }
+
+      // Tools
+      const toolNames = ['nodemon', 'supertest', 'prettier', 'typescript'];
+      const detectedTools = [];
+      for (const t of toolNames) {
+        if (t in devDeps || t in deps) {
+          detectedTools.push(t);
+        }
+      }
+      if (detectedTools.length > 0) config.tools = detectedTools;
+
+      // Package manager from lockfiles
+      if (exists('yarn.lock')) {
+        config.packageManager = 'yarn';
+      } else if (exists('pnpm-lock.yaml')) {
+        config.packageManager = 'pnpm';
+      } else {
+        config.packageManager = 'npm';
+      }
+    }
+  }
+
+  // TypeScript overrides JavaScript
+  if (exists('tsconfig.json')) {
+    config.language = 'TypeScript';
+    if (!config.runtime) config.runtime = 'Node.js';
+  }
+
+  // Python detection
+  if (exists('pyproject.toml') || exists('requirements.txt')) {
+    config.language = 'Python';
+    config.runtime = 'Python 3.x';
+
+    const pyproject = readText('pyproject.toml');
+    if (pyproject) {
+      // Test runner
+      if (pyproject.includes('pytest')) config.testRunner = 'pytest';
+      else if (pyproject.includes('unittest')) config.testRunner = 'unittest';
+
+      // Linter/tools
+      if (pyproject.includes('ruff')) config.linter = 'ruff';
+      else if (pyproject.includes('flake8')) config.linter = 'flake8';
+
+      const pyTools = [];
+      if (pyproject.includes('black')) pyTools.push('black');
+      if (pyproject.includes('mypy')) pyTools.push('mypy');
+      if (pyTools.length > 0) config.tools = pyTools;
+
+      // Frameworks
+      const pyFrameworks = [];
+      if (pyproject.includes('django')) pyFrameworks.push('django');
+      if (pyproject.includes('flask')) pyFrameworks.push('flask');
+      if (pyproject.includes('fastapi')) pyFrameworks.push('fastapi');
+      if (pyFrameworks.length > 0) config.frameworks = pyFrameworks;
+    }
+
+    // Package manager
+    if (exists('poetry.lock')) config.packageManager = 'poetry';
+    else if (exists('Pipfile.lock') || exists('Pipfile')) config.packageManager = 'pipenv';
+    else config.packageManager = 'pip';
+
+    if (!config.testCommand && config.testRunner) {
+      config.testCommand = config.testRunner === 'pytest' ? 'pytest' : 'python -m unittest';
+    }
+  }
+
+  // Go detection
+  if (exists('go.mod')) {
+    config.language = 'Go';
+    config.runtime = 'Go';
+    config.testRunner = 'go test';
+    config.testCommand = 'go test ./...';
+  }
+
+  // Rust detection
+  if (exists('Cargo.toml')) {
+    config.language = 'Rust';
+    config.runtime = 'Rust';
+    config.packageManager = 'cargo';
+    config.testRunner = 'cargo test';
+    config.testCommand = 'cargo test';
+  }
+
+  // Ruby detection
+  if (exists('Gemfile')) {
+    config.language = 'Ruby';
+    config.runtime = 'Ruby';
+    config.packageManager = 'bundler';
+  }
+
+  return config;
+}
+
+/**
+ * Displays the current stack configuration.
+ */
+function displayStackConfig() {
+  const config = readStackConfig();
+  console.log('\nStack Configuration\n');
+  console.log(`  language:       ${config.language || '(not set)'}`);
+  console.log(`  runtime:        ${config.runtime || '(not set)'}`);
+  console.log(`  packageManager: ${config.packageManager || '(not set)'}`);
+  console.log(`  frameworks:     ${config.frameworks.length > 0 ? config.frameworks.join(', ') : '(not set)'}`);
+  console.log(`  testRunner:     ${config.testRunner || '(not set)'}`);
+  console.log(`  testCommand:    ${config.testCommand || '(not set)'}`);
+  console.log(`  linter:         ${config.linter || '(not set)'}`);
+  console.log(`  tools:          ${config.tools.length > 0 ? config.tools.join(', ') : '(not set)'}`);
+  console.log('\nTo change: murmur8 stack-config set <key> <value>');
+}
+
+module.exports = {
+  CONFIG_FILE,
+  getDefaultStackConfig,
+  readStackConfig,
+  writeStackConfig,
+  resetStackConfig,
+  setStackConfigValue,
+  detectStackConfig,
+  displayStackConfig
+};

package/src/tools/index.js

@@ -0,0 +1,27 @@
+/**
+ * Tools Module - Model Native Features
+ * Exports tool schemas, validation, and prompt utilities
+ */
+
+const { FEEDBACK_TOOL_SCHEMA, HANDOFF_TOOL_SCHEMA } = require('./schemas');
+const { validateToolInput, normalizeFeedbackInput } = require('./validation');
+const {
+  buildPromptMessages,
+  identifyCacheableContent,
+  SYSTEM_PROMPT_TEMPLATE,
+  USER_PROMPT_TEMPLATE
+} = require('./prompts');
+
+module.exports = {
+  // Schemas
+  FEEDBACK_TOOL_SCHEMA,
+  HANDOFF_TOOL_SCHEMA,
+  // Validation
+  validateToolInput,
+  normalizeFeedbackInput,
+  // Prompts
+  buildPromptMessages,
+  identifyCacheableContent,
+  SYSTEM_PROMPT_TEMPLATE,
+  USER_PROMPT_TEMPLATE
+};

package/src/tools/prompts.js

@@ -0,0 +1,45 @@
+/**
+ * Prompt Structure Utilities
+ * Helpers for system/user prompt separation and caching
+ */
+
+const SYSTEM_PROMPT_TEMPLATE = {
+  role: 'system',
+  content: '[AGENT_SPEC]\n[GUARDRAILS]\n[TEMPLATES]',
+  cache_control: { type: 'ephemeral' }
+};
+
+const USER_PROMPT_TEMPLATE = {
+  role: 'user',
+  content: '[TASK_INSTRUCTIONS]\n[INPUTS]\n[OUTPUTS]'
+};
+
+/**
+ * Build prompt messages with system and user separation
+ * @param {string} staticContent - Content for system prompt (agent specs, guardrails)
+ * @param {string} dynamicContent - Content for user prompt (task instructions, inputs)
+ * @returns {Array<Object>} Array of message objects
+ */
+function buildPromptMessages(staticContent, dynamicContent) {
+  return [
+    { ...SYSTEM_PROMPT_TEMPLATE, content: staticContent },
+    { ...USER_PROMPT_TEMPLATE, content: dynamicContent }
+  ];
+}
+
+/**
+ * Identify if content should be cached (static, reusable content)
+ * @param {string} content - Content to analyze
+ * @returns {boolean} True if content is cacheable
+ */
+function identifyCacheableContent(content) {
+  const cacheablePatterns = ['AGENT_', 'GUARDRAIL', 'TEMPLATE', 'SPEC.md'];
+  return cacheablePatterns.some(p => content.includes(p));
+}
+
+module.exports = {
+  SYSTEM_PROMPT_TEMPLATE,
+  USER_PROMPT_TEMPLATE,
+  buildPromptMessages,
+  identifyCacheableContent
+};

package/src/tools/schemas.js

@@ -0,0 +1,38 @@
+/**
+ * Tool Schema Definitions
+ * Reusable schema constants for Claude tool use
+ */
+
+const FEEDBACK_TOOL_SCHEMA = {
+  name: 'submit_feedback',
+  description: 'Submit quality rating for prior stage',
+  input_schema: {
+    type: 'object',
+    properties: {
+      rating: { type: 'number', minimum: 1, maximum: 5 },
+      issues: { type: 'array', items: { type: 'string' } },
+      recommendation: { enum: ['proceed', 'pause', 'revise'] }
+    },
+    required: ['rating', 'issues', 'recommendation']
+  }
+};
+
+const HANDOFF_TOOL_SCHEMA = {
+  name: 'submit_handoff',
+  description: 'Submit summary for next agent',
+  input_schema: {
+    type: 'object',
+    properties: {
+      from_agent: { type: 'string', enum: ['alex', 'cass', 'nigel', 'codey'] },
+      to_agent: { type: 'string', enum: ['alex', 'cass', 'nigel', 'codey'] },
+      summary: { type: 'string', maxLength: 500 },
+      artifacts: { type: 'array', items: { type: 'string' } }
+    },
+    required: ['from_agent', 'to_agent', 'summary']
+  }
+};
+
+module.exports = {
+  FEEDBACK_TOOL_SCHEMA,
+  HANDOFF_TOOL_SCHEMA
+};