murmur8 3.5.0

package/src/feedback.js

@@ -0,0 +1,201 @@
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_FILE = '.claude/feedback-config.json';
+
+/**
+ * Normalizes abbreviated keys to full names.
+ * Converts "rec" to "recommendation" while preserving existing full key.
+ * @param {Object} feedback - Raw feedback object
+ * @returns {Object} - Normalized feedback object
+ */
+function normalizeFeedbackKeys(feedback) {
+  const normalized = { ...feedback };
+  if ('rec' in normalized && !('recommendation' in normalized)) {
+    normalized.recommendation = normalized.rec;
+    delete normalized.rec;
+  }
+  return normalized;
+}
+
+/**
+ * Parses FEEDBACK: JSON from agent output text.
+ * @param {string} output - Raw agent output
+ * @returns {Object|null} - Parsed feedback or null if not found/invalid
+ */
+function parseFeedbackFromOutput(output) {
+  const match = output.match(/FEEDBACK:\s*(\{[^}]+\})/);
+  if (!match) return null;
+  try {
+    return JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Returns the default feedback configuration.
+ * Per FEATURE_SPEC.md defaults.
+ */
+function getDefaultConfig() {
+  return {
+    minRatingThreshold: 3.0,
+    enabled: true,
+    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'
+    }
+  };
+}
+
+/**
+ * Ensures the .claude directory exists.
+ */
+function ensureConfigDir() {
+  const dir = path.dirname(CONFIG_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Reads the feedback 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) {
+    return getDefaultConfig();
+  }
+}
+
+/**
+ * Writes the feedback config to file.
+ */
+function writeConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Validates a feedback object against the schema.
+ * Per FEATURE_SPEC.md:Rule 1.
+ * Accepts both "rec" and "recommendation" keys for recommendation field.
+ * @param {object} feedback - Feedback object to validate
+ * @returns {object} { valid: boolean, errors: string[] }
+ */
+function validateFeedback(feedback) {
+  const errors = [];
+
+  // Rating validation
+  if (typeof feedback.rating !== 'number' || !Number.isInteger(feedback.rating)) {
+    errors.push('rating must be an integer');
+  } else if (feedback.rating < 1 || feedback.rating > 5) {
+    errors.push('rating must be between 1 and 5');
+  }
+
+  // Issues validation
+  if (!Array.isArray(feedback.issues)) {
+    errors.push('issues must be an array');
+  } else if (!feedback.issues.every(i => typeof i === 'string')) {
+    errors.push('issues must be an array of strings');
+  }
+
+  // Recommendation validation - accept both "rec" and "recommendation" keys
+  const rec = feedback.recommendation || feedback.rec;
+  const validRecs = ['proceed', 'pause', 'revise'];
+  if (!validRecs.includes(rec)) {
+    errors.push(`recommendation must be one of: ${validRecs.join(', ')}`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Determines whether the pipeline should pause based on feedback.
+ * Per FEATURE_SPEC.md:Rule 2.
+ * @param {object} feedback - Validated feedback object
+ * @param {object} config - Feedback configuration
+ * @returns {boolean} True if pipeline should pause
+ */
+function shouldPause(feedback, config) {
+  return feedback.rating < config.minRatingThreshold ||
+         feedback.recommendation === 'pause';
+}
+
+/**
+ * Validates and sets a config value.
+ * @param {string} key - Config key
+ * @param {string} value - New value (will be parsed)
+ */
+function setConfigValue(key, value) {
+  const config = readConfig();
+
+  if (key === 'minRatingThreshold') {
+    const numValue = parseFloat(value);
+    if (isNaN(numValue) || numValue < 1.0 || numValue > 5.0) {
+      throw new Error(
+        'minRatingThreshold must be a number between 1.0 and 5.0'
+      );
+    }
+    config.minRatingThreshold = numValue;
+  } else if (key === 'enabled') {
+    if (value !== 'true' && value !== 'false') {
+      throw new Error('enabled must be true or false');
+    }
+    config.enabled = value === 'true';
+  } else {
+    throw new Error(
+      `Unknown config key: ${key}. Valid keys: minRatingThreshold, enabled`
+    );
+  }
+
+  writeConfig(config);
+  console.log(`Set ${key} = ${config[key]}`);
+}
+
+/**
+ * Displays the current feedback configuration.
+ */
+function displayConfig() {
+  const config = readConfig();
+  console.log('\nFeedback Configuration\n');
+  console.log(`  Min rating threshold:   ${config.minRatingThreshold}`);
+  console.log(`  Enabled:                ${config.enabled}`);
+  console.log('\n  Issue Mappings:');
+  for (const [issue, strategy] of Object.entries(config.issueMappings)) {
+    console.log(`    ${issue.padEnd(24)}: ${strategy}`);
+  }
+  console.log('');
+}
+
+/**
+ * Resets feedback config to defaults.
+ */
+function resetConfig() {
+  writeConfig(getDefaultConfig());
+}
+
+module.exports = {
+  CONFIG_FILE,
+  getDefaultConfig,
+  readConfig,
+  writeConfig,
+  normalizeFeedbackKeys,
+  parseFeedbackFromOutput,
+  validateFeedback,
+  shouldPause,
+  setConfigValue,
+  displayConfig,
+  resetConfig
+};

package/src/handoff.js

@@ -0,0 +1,148 @@
+/**
+ * Handoff summary helper functions.
+ * Parses and validates handoff summary format for agent-to-agent communication.
+ */
+
+/**
+ * Parses a handoff summary and extracts key fields.
+ * @param {string} content - The handoff summary markdown content
+ * @returns {object} Parsed summary fields
+ */
+function parseHandoffSummary(content) {
+  return {
+    hasHeading: /^## Handoff Summary/m.test(content),
+    forField: content.match(/\*\*For:\*\*\s*(.+)/)?.[1]?.trim(),
+    featureField: content.match(/\*\*Feature:\*\*\s*(.+)/)?.[1]?.trim(),
+    hasKeyDecisions: /### Key Decisions/m.test(content),
+    hasFilesCreated: /### Files Created/m.test(content),
+    hasOpenQuestions: /### Open Questions/m.test(content),
+    hasCriticalContext: /### Critical Context/m.test(content),
+    lineCount: content.split('\n').length
+  };
+}
+
+/**
+ * Extracts a named section from the summary.
+ * @param {string} content - The handoff summary markdown content
+ * @param {string} sectionName - Name of the section (e.g., 'Key Decisions')
+ * @returns {string} The section content, or empty string if not found
+ */
+function extractSection(content, sectionName) {
+  const regex = new RegExp(`### ${sectionName}\\n([\\s\\S]*?)(?=\\n###|$)`);
+  const match = content.match(regex);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Counts bullet items in a section.
+ * @param {string} section - Section content
+ * @returns {number} Number of bullet items
+ */
+function countBulletItems(section) {
+  return section.split('\n').filter(line => /^[-*]\s/.test(line)).length;
+}
+
+/**
+ * Extracts file paths from a section.
+ * @param {string} section - Section content
+ * @returns {string[]} Array of file paths
+ */
+function extractFilePaths(section) {
+  const lines = section.split('\n').filter(line => /^[-*]\s/.test(line));
+  return lines.map(line => line.replace(/^[-*]\s+/, '').trim());
+}
+
+/**
+ * Validates a handoff summary against format rules.
+ * @param {string} content - The handoff summary markdown content
+ * @returns {object} { valid: boolean, errors: string[] }
+ */
+function validateHandoffSummary(content) {
+  const errors = [];
+  const parsed = parseHandoffSummary(content);
+
+  if (!parsed.hasHeading) {
+    errors.push('Missing ## Handoff Summary heading');
+  }
+
+  if (!parsed.forField) {
+    errors.push('Missing **For:** field');
+  }
+
+  if (!parsed.featureField) {
+    errors.push('Missing **Feature:** field');
+  }
+
+  if (!parsed.hasKeyDecisions) {
+    errors.push('Missing ### Key Decisions section');
+  }
+
+  if (!parsed.hasFilesCreated) {
+    errors.push('Missing ### Files Created section');
+  }
+
+  if (!parsed.hasOpenQuestions) {
+    errors.push('Missing ### Open Questions section');
+  }
+
+  if (!parsed.hasCriticalContext) {
+    errors.push('Missing ### Critical Context section');
+  }
+
+  if (parsed.lineCount >= 30) {
+    errors.push(`Summary exceeds 30 lines (found ${parsed.lineCount})`);
+  }
+
+  // Validate Key Decisions bullet count
+  const keyDecisions = extractSection(content, 'Key Decisions');
+  const bulletCount = countBulletItems(keyDecisions);
+  if (bulletCount < 1 || bulletCount > 5) {
+    errors.push(`Key Decisions should have 1-5 items (found ${bulletCount})`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Returns the handoff file path for an agent.
+ * @param {string} featureDir - Feature directory path
+ * @param {string} agent - Agent name (alex, cass, nigel)
+ * @returns {string} Full path to handoff file
+ */
+function getHandoffPath(featureDir, agent) {
+  return `${featureDir}/handoff-${agent.toLowerCase()}.md`;
+}
+
+/**
+ * Generates a handoff summary template.
+ * @param {string} forAgent - Target agent name
+ * @param {string} featureSlug - Feature slug
+ * @returns {string} Template markdown content
+ */
+function getHandoffTemplate(forAgent, featureSlug) {
+  return `## Handoff Summary
+**For:** ${forAgent}
+**Feature:** ${featureSlug}
+
+### Key Decisions
+-
+
+### Files Created
+-
+
+### Open Questions
+- None
+
+### Critical Context
+`;
+}
+
+module.exports = {
+  parseHandoffSummary,
+  extractSection,
+  countBulletItems,
+  extractFilePaths,
+  validateHandoffSummary,
+  getHandoffPath,
+  getHandoffTemplate
+};

package/src/history.js

@@ -0,0 +1,306 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const HISTORY_FILE = '.claude/pipeline-history.json';
+
+function ensureHistoryDir() {
+  const dir = path.dirname(HISTORY_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readHistoryFile() {
+  ensureHistoryDir();
+  if (!fs.existsSync(HISTORY_FILE)) {
+    return [];
+  }
+  try {
+    const content = fs.readFileSync(HISTORY_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    return { error: 'corrupted' };
+  }
+}
+
+function writeHistoryFile(entries) {
+  ensureHistoryDir();
+  fs.writeFileSync(HISTORY_FILE, JSON.stringify(entries, null, 2));
+}
+
+function recordHistory(entry) {
+  try {
+    const history = readHistoryFile();
+    if (history.error) {
+      console.warn('Warning: History file is corrupted, cannot record entry.');
+      return false;
+    }
+    history.push(entry);
+    writeHistoryFile(history);
+    return true;
+  } catch (err) {
+    console.warn(`Warning: Failed to record history: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Stores feedback for a specific stage in a feature's history entry.
+ * Per FEATURE_SPEC.md - feedback is stored at stages[stage].feedback
+ * @param {string} slug - Feature slug
+ * @param {string} stage - Stage name (alex, cass, nigel, etc.)
+ * @param {object} feedback - Feedback object to store
+ * @returns {boolean} True if stored successfully
+ */
+function storeStageFeedback(slug, stage, feedback) {
+  try {
+    const history = readHistoryFile();
+    if (history.error) {
+      console.warn('Warning: History file is corrupted, cannot store feedback.');
+      return false;
+    }
+
+    // Find the most recent entry for this slug
+    const entry = history.findLast(e => e.slug === slug);
+    if (!entry) {
+      console.warn(`Warning: No history entry found for slug: ${slug}`);
+      return false;
+    }
+
+    // Ensure stages object exists
+    if (!entry.stages) {
+      entry.stages = {};
+    }
+
+    // Ensure stage object exists
+    if (!entry.stages[stage]) {
+      entry.stages[stage] = {};
+    }
+
+    // Store feedback
+    entry.stages[stage].feedback = feedback;
+
+    writeHistoryFile(history);
+    return true;
+  } catch (err) {
+    console.warn(`Warning: Failed to store feedback: ${err.message}`);
+    return false;
+  }
+}
+
+function formatDuration(ms) {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const secs = seconds % 60;
+  if (minutes === 0) {
+    return `${secs}s`;
+  }
+  return `${minutes}m ${secs}s`;
+}
+
+function formatDate(isoString) {
+  const date = new Date(isoString);
+  return date.toISOString().replace('T', ' ').slice(0, 19);
+}
+
+function colorize(text, color, useColor) {
+  if (!useColor) return text;
+  const colors = {
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    reset: '\x1b[0m'
+  };
+  return `${colors[color] || ''}${text}${colors.reset}`;
+}
+
+function displayHistory(options = {}) {
+  const showAll = options.all || false;
+  const useColor = options.color !== false && process.stdout.isTTY;
+
+  const history = readHistoryFile();
+
+  if (history.error === 'corrupted') {
+    console.log("Warning: History file is corrupted. Run 'murmur8 history clear' to reset.");
+    return;
+  }
+
+  if (!history || history.length === 0) {
+    console.log('No pipeline history found.');
+    return;
+  }
+
+  const sorted = [...history].sort((a, b) =>
+    new Date(b.completedAt) - new Date(a.completedAt)
+  );
+
+  const entries = showAll ? sorted : sorted.slice(0, 10);
+  const total = history.length;
+  const showing = entries.length;
+
+  console.log(`\nPipeline History (showing ${showing} of ${total} runs)\n`);
+  console.log('  SLUG                STATUS    DATE                  DURATION');
+
+  for (const entry of entries) {
+    const slug = entry.slug.padEnd(18);
+    let status = entry.status.padEnd(8);
+    const date = formatDate(entry.completedAt);
+    const duration = formatDuration(entry.totalDurationMs);
+
+    if (entry.status === 'success') {
+      status = colorize(status, 'green', useColor);
+    } else if (entry.status === 'failed') {
+      status = colorize(status, 'red', useColor);
+    } else if (entry.status === 'paused') {
+      status = colorize(status, 'yellow', useColor);
+    }
+
+    let suffix = '';
+    if (entry.status === 'failed' && entry.failedStage) {
+      suffix = ` (failed at: ${entry.failedStage})`;
+    } else if (entry.status === 'paused' && entry.pausedAfter) {
+      suffix = ` (paused at: ${entry.pausedAfter})`;
+    }
+
+    console.log(`  ${slug}  ${status}  ${date}   ${duration}${suffix}`);
+  }
+
+  if (!showAll && total > 10) {
+    console.log(`\nRun 'murmur8 history --all' to see all entries.`);
+  }
+  console.log(`Run 'murmur8 history --stats' for aggregate statistics.`);
+}
+
+function showStats() {
+  const history = readHistoryFile();
+
+  if (history.error === 'corrupted') {
+    console.log("Warning: History file is corrupted. Run 'murmur8 history clear' to reset.");
+    return;
+  }
+
+  if (!history || history.length === 0) {
+    console.log('Insufficient data for statistics. Complete at least one pipeline run.');
+    return;
+  }
+
+  const total = history.length;
+  const successRuns = history.filter(e => e.status === 'success');
+  const failedRuns = history.filter(e => e.status === 'failed');
+  const pausedRuns = history.filter(e => e.status === 'paused');
+
+  const successCount = successRuns.length;
+  const successRate = Math.round((successCount / total) * 100);
+
+  console.log(`\nPipeline Statistics (based on ${total} runs)\n`);
+  console.log('  METRIC                    VALUE');
+  console.log(`  Success rate              ${successRate}% (${successCount}/${total} runs)`);
+  console.log(`  Total runs                ${total} (${successCount} success, ${failedRuns.length} failed, ${pausedRuns.length} paused)`);
+
+  if (successRuns.length > 0) {
+    const avgTotal = Math.round(
+      successRuns.reduce((sum, e) => sum + e.totalDurationMs, 0) / successRuns.length
+    );
+    console.log(`  Avg pipeline duration     ${formatDuration(avgTotal)}`);
+  }
+
+  const stages = ['alex', 'cass', 'nigel', 'codey-plan', 'codey-implement'];
+  const stageStats = {};
+  const failureCounts = {};
+
+  for (const stage of stages) {
+    stageStats[stage] = { durations: [], failures: 0 };
+  }
+
+  for (const entry of history) {
+    if (entry.stages) {
+      for (const stage of stages) {
+        if (entry.stages[stage] && entry.stages[stage].durationMs) {
+          stageStats[stage].durations.push(entry.stages[stage].durationMs);
+        }
+      }
+    }
+    if (entry.status === 'failed' && entry.failedStage) {
+      failureCounts[entry.failedStage] = (failureCounts[entry.failedStage] || 0) + 1;
+    }
+  }
+
+  console.log('\n  STAGE             AVG DURATION    FAILURES');
+  for (const stage of stages) {
+    const stats = stageStats[stage];
+    const avgDuration = stats.durations.length > 0
+      ? formatDuration(Math.round(stats.durations.reduce((a, b) => a + b, 0) / stats.durations.length))
+      : 'N/A';
+    const failures = failureCounts[stage] || 0;
+    console.log(`  ${stage.padEnd(16)}  ${avgDuration.padEnd(14)}  ${failures}`);
+  }
+
+  if (failedRuns.length === 0) {
+    console.log('\n  No failures recorded');
+  } else {
+    const maxFailures = Math.max(...Object.values(failureCounts));
+    const topFailures = Object.entries(failureCounts)
+      .filter(([, count]) => count === maxFailures)
+      .map(([stage]) => stage);
+
+    if (topFailures.length === 1) {
+      console.log(`\n  Most common failure: ${topFailures[0]} (${maxFailures} failures)`);
+    } else {
+      console.log(`\n  Most common failures: ${topFailures.join(', ')} (${maxFailures} each)`);
+    }
+  }
+}
+
+async function clearHistory(options = {}) {
+  const force = options.force || false;
+
+  const history = readHistoryFile();
+
+  if (history.error === 'corrupted') {
+    writeHistoryFile([]);
+    console.log('History file was corrupted. File has been reset.');
+    return;
+  }
+
+  if (!history || history.length === 0) {
+    console.log('No history to clear.');
+    return;
+  }
+
+  const count = history.length;
+
+  if (!force) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    const answer = await new Promise((resolve) => {
+      rl.question(`This will delete all ${count} history entries. Continue? (y/N) `, (ans) => {
+        rl.close();
+        resolve(ans.toLowerCase().trim());
+      });
+    });
+
+    if (answer !== 'y' && answer !== 'yes') {
+      console.log('Clear cancelled. History unchanged.');
+      return;
+    }
+  }
+
+  writeHistoryFile([]);
+  console.log(`Pipeline history cleared. ${count} entries removed.`);
+}
+
+module.exports = {
+  HISTORY_FILE,
+  readHistoryFile,
+  writeHistoryFile,
+  recordHistory,
+  storeStageFeedback,
+  displayHistory,
+  showStats,
+  clearHistory,
+  formatDuration
+};