@agile-vibe-coding/avc 0.1.1 → 0.3.1

package/cli/messaging-api.js

@@ -0,0 +1,291 @@
+/**
+ * Messaging API - Simple interface for command message handling
+ *
+ * Provides convenient methods for commands to send messages through
+ * the MessageManager without directly importing it.
+ */
+
+import { messageManager } from './message-manager.js';
+import { MessageType } from './message-types.js';
+import { boldCyan, gray, cyan } from './ansi-colors.js';
+
+/**
+ * Track sent ceremony headers to prevent duplication
+ * Cleared on each startCommand() call
+ */
+let ceremonySent = new Set();
+
+/**
+ * Start a new command execution context
+ * Should be called at the beginning of every command
+ *
+ * @param {string} commandName - Name of the command (e.g., 'sponsor-call')
+ * @returns {ExecutionContext} New execution context
+ *
+ * @example
+ * import { startCommand, endCommand } from './messaging-api.js';
+ *
+ * async function sponsorCallCommand() {
+ *   startCommand('sponsor-call');
+ *   try {
+ *     // ... command logic
+ *   } finally {
+ *     endCommand();
+ *   }
+ * }
+ */
+export function startCommand(commandName) {
+  // Clear ceremony header tracking for new command
+  ceremonySent.clear();
+  return messageManager.startExecution(commandName);
+}
+
+/**
+ * End the current command execution context
+ * Should be called in finally block to ensure cleanup
+ *
+ * @example
+ * try {
+ *   // ... command logic
+ * } finally {
+ *   endCommand();
+ * }
+ */
+export function endCommand() {
+  messageManager.endExecution();
+}
+
+/**
+ * Cancel the current command execution context
+ * Used when user interrupts or restarts command
+ */
+export function cancelCommand() {
+  messageManager.cancelExecution();
+}
+
+/**
+ * Send a ceremony header (title + documentation URL)
+ * Automatically prevents duplicate headers within same command execution
+ *
+ * @param {string} title - Ceremony title
+ */
+export function sendCeremonyHeader(title) {
+  // Prevent duplicate ceremony headers within the same command execution
+  if (ceremonySent.has(title)) {
+    return;
+  }
+
+  ceremonySent.add(title);
+  const content = boldCyan(title);
+  messageManager.send(MessageType.CEREMONY_HEADER, content);
+}
+
+/**
+ * Send a progress message (shows in executing state)
+ *
+ * @param {string} message - Progress message
+ *
+ * @example
+ * sendProgress('Analyzing database requirements...');
+ */
+export function sendProgress(message) {
+  messageManager.send(MessageType.PROGRESS, message);
+}
+
+/**
+ * Send a substep message (detailed progress)
+ *
+ * @param {string} message - Substep message
+ *
+ * @example
+ * sendSubstep('Calling Claude API...');
+ */
+export function sendSubstep(message) {
+  messageManager.send(MessageType.SUBSTEP, message);
+}
+
+/**
+ * Send user output (main content)
+ *
+ * @param {string} content - Content to display
+ *
+ * @example
+ * sendOutput('Mission statement: Build a task manager\n');
+ */
+export function sendOutput(content) {
+  messageManager.send(MessageType.USER_OUTPUT, content);
+}
+
+/**
+ * Send an error message
+ *
+ * @param {string} message - Error message
+ *
+ * @example
+ * sendError('Failed to load configuration file');
+ */
+export function sendError(message) {
+  messageManager.send(MessageType.ERROR, message);
+}
+
+/**
+ * Send a warning message
+ *
+ * @param {string} message - Warning message
+ *
+ * @example
+ * sendWarning('API rate limit approaching');
+ */
+export function sendWarning(message) {
+  messageManager.send(MessageType.WARNING, message);
+}
+
+/**
+ * Send a success message
+ *
+ * @param {string} message - Success message
+ *
+ * @example
+ * sendSuccess('Documentation generated successfully');
+ */
+export function sendSuccess(message) {
+  messageManager.send(MessageType.SUCCESS, message);
+}
+
+/**
+ * Send an info message
+ *
+ * @param {string} message - Info message
+ *
+ * @example
+ * sendInfo('Using Claude provider for LLM operations');
+ */
+export function sendInfo(message) {
+  messageManager.send(MessageType.INFO, message);
+}
+
+/**
+ * Send a debug message (only to console.log)
+ *
+ * @param {string} message - Debug message
+ * @param {Object} data - Optional data to log
+ *
+ * @example
+ * sendDebug('Processing questionnaire', { currentIndex: 2, total: 6 });
+ */
+export function sendDebug(message, data = null) {
+  messageManager.send(MessageType.DEBUG, message, { data });
+}
+
+/**
+ * Clear progress indicators
+ *
+ * @example
+ * clearProgress();
+ */
+export function clearProgress() {
+  messageManager.clearProgress();
+}
+
+/**
+ * Get current execution context
+ *
+ * @returns {ExecutionContext|null} Current context or null
+ */
+export function getCurrentContext() {
+  return messageManager.getCurrentContext();
+}
+
+/**
+ * Check if current context is active
+ *
+ * @returns {boolean} True if active context exists
+ */
+export function isContextActive() {
+  const context = messageManager.getCurrentContext();
+  return context ? context.isActive() : false;
+}
+
+/**
+ * Register callbacks from React state
+ * Called once during REPL initialization
+ *
+ * @param {Object} callbacks - Callback functions
+ * @param {Function} callbacks.setExecutingMessage - setExecutingMessage React state setter
+ * @param {Function} callbacks.setExecutingSubstep - setExecutingSubstep React state setter
+ *
+ * @example
+ * // In repl-ink.js
+ * useEffect(() => {
+ *   registerCallbacks({
+ *     setExecutingMessage,
+ *     setExecutingSubstep
+ *   });
+ * }, []);
+ */
+export function registerCallbacks(callbacks) {
+  if (callbacks.setExecutingMessage) {
+    messageManager.setExecutingMessageCallback(callbacks.setExecutingMessage);
+  }
+  if (callbacks.setExecutingSubstep) {
+    messageManager.setExecutingSubstepCallback(callbacks.setExecutingSubstep);
+  }
+}
+
+/**
+ * Helper: Send formatted section header (cyan bold)
+ *
+ * @param {string} title - Section title
+ *
+ * @example
+ * sendSectionHeader('Database Options Comparison');
+ */
+export function sendSectionHeader(title) {
+  sendOutput(`\n${title}\n\n`);
+}
+
+/**
+ * Helper: Send formatted list item
+ *
+ * @param {string} item - List item text
+ * @param {number} indent - Indentation level (default: 0)
+ *
+ * @example
+ * sendListItem('PostgreSQL - ACID compliant');
+ * sendListItem('Supports complex queries', 1);
+ */
+export function sendListItem(item, indent = 0) {
+  const spacing = '  '.repeat(indent);
+  sendOutput(`${spacing}- ${item}\n`);
+}
+
+/**
+ * Helper: Send indented content
+ *
+ * @param {string} content - Content to indent
+ * @param {number} level - Indentation level (0-3, each level = 2 spaces)
+ *
+ * @example
+ * sendIndented('Details about the option', 1);
+ * sendIndented('Nested information', 2);
+ */
+export function sendIndented(content, level = 0) {
+  const spacing = '  '.repeat(level);
+  sendOutput(`${spacing}${content}`);
+}
+
+/**
+ * Helper: Send newline
+ */
+export function sendNewline() {
+  sendOutput('\n');
+}
+
+/**
+ * Helper: Send multiple newlines
+ *
+ * @param {number} count - Number of newlines (default: 2)
+ */
+export function sendNewlines(count = 2) {
+  sendOutput('\n'.repeat(count));
+}

package/cli/micro-check-fixer.js

@@ -0,0 +1,335 @@
+/**
+ * micro-check-fixer.js
+ *
+ * Handles atomic targeted fixes for failed micro-checks with regression revert.
+ * Each failed check is fixed individually, verified, and reverted if it doesn't pass.
+ * After all fixes, a regression scan ensures no previously-passing checks broke.
+ */
+
+import { runTier1Check, runTier2Check } from './micro-check-runner.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const FIX_SYSTEM_INSTRUCTIONS =
+  'You are a precise work item editor. You fix exactly one issue at a time. ' +
+  'Make the minimum change needed to address the failed check. Never remove existing content. ' +
+  'Never add unrelated improvements.';
+
+const SEVERITY_PRIORITY = { critical: 0, major: 1, minor: 2 };
+
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+
+function buildFixPrompt(workItemType, workItemText, check) {
+  const fieldsHint =
+    workItemType === 'epic'
+      ? '- features: string[] (for epics)'
+      : '- acceptanceCriteria: string[] (for stories)';
+
+  return (
+    '# Fix Required\n\n' +
+    `## Work Item (${workItemType})\n${workItemText}\n\n` +
+    '## Failed Check\n' +
+    `- **Check:** ${check.failDescription || check.id}\n` +
+    `- **Suggestion:** ${check.failSuggestion || 'N/A'}\n` +
+    `- **Evidence:** ${check.evidence || 'N/A'}\n\n` +
+    '## Instructions\n' +
+    'Modify the work item to address ONLY this specific issue. Do not change anything else.\n' +
+    'Return the complete updated work item as JSON with these fields:\n' +
+    '- description: string (the full updated description)\n' +
+    `${fieldsHint}\n` +
+    '- dependencies: string[] (keep unchanged unless the fix requires it)\n\n' +
+    'CRITICAL: Make the MINIMUM change necessary to pass this check. Do not add unrelated improvements.'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helper: deep clone a work item (plain object)
+// ---------------------------------------------------------------------------
+
+function cloneWorkItem(workItem) {
+  return JSON.parse(JSON.stringify(workItem));
+}
+
+// ---------------------------------------------------------------------------
+// Helper: merge work item fields from a fix into the original
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge fix fields into the original work item without removing existing content.
+ * @param {Object} original - The current work item
+ * @param {Object} fixed - The fix result from LLM
+ * @param {string} type - "epic" or "story"
+ * @returns {Object} Merged work item
+ */
+export function mergeWorkItemFields(original, fixed, type) {
+  const merged = cloneWorkItem(original);
+
+  // Update description from fix
+  if (fixed.description) {
+    merged.description = fixed.description;
+  }
+
+  if (type === 'epic') {
+    const existingFeatures = Array.isArray(merged.features) ? merged.features : [];
+    const fixedFeatures = Array.isArray(fixed.features) ? fixed.features : [];
+    const featureSet = new Set(existingFeatures);
+    for (const f of fixedFeatures) {
+      featureSet.add(f);
+    }
+    merged.features = [...featureSet];
+  } else {
+    const existingCriteria = Array.isArray(merged.acceptanceCriteria) ? merged.acceptanceCriteria : [];
+    const fixedCriteria = Array.isArray(fixed.acceptanceCriteria) ? fixed.acceptanceCriteria : [];
+    const criteriaSet = new Set(existingCriteria);
+    for (const c of fixedCriteria) {
+      criteriaSet.add(c);
+    }
+    merged.acceptanceCriteria = [...criteriaSet];
+  }
+
+  // Keep original dependencies, add new ones from fix if any
+  const existingDeps = Array.isArray(merged.dependencies) ? merged.dependencies : [];
+  const fixedDeps = Array.isArray(fixed.dependencies) ? fixed.dependencies : [];
+  const depSet = new Set(existingDeps);
+  for (const d of fixedDeps) {
+    depSet.add(d);
+  }
+  merged.dependencies = [...depSet];
+
+  return merged;
+}
+
+// ---------------------------------------------------------------------------
+// Helper: re-run a single check
+// ---------------------------------------------------------------------------
+
+async function rerunCheck(checkDef, workItemText, llmProvider, tier1Results = null) {
+  if (checkDef.tier === 2) {
+    // Tier 2 checks need tier1Results map for template variable resolution
+    return runTier2Check(checkDef, workItemText, tier1Results || new Map(), llmProvider);
+  }
+  return runTier1Check(checkDef, workItemText, llmProvider);
+}
+
+// ---------------------------------------------------------------------------
+// Helper: generate basic context text from a work item
+// ---------------------------------------------------------------------------
+
+function generateBasicContext(workItem, workItemType) {
+  const lines = [`# ${workItemType === 'epic' ? 'Epic' : 'Story'}: ${workItem.title || workItem.id || 'Untitled'}`];
+  if (workItem.description) {
+    lines.push('', workItem.description);
+  }
+  if (workItemType === 'epic' && Array.isArray(workItem.features)) {
+    lines.push('', '## Features');
+    for (const f of workItem.features) {
+      lines.push(`- ${f}`);
+    }
+  }
+  if (workItemType === 'story' && Array.isArray(workItem.acceptanceCriteria)) {
+    lines.push('', '## Acceptance Criteria');
+    for (const c of workItem.acceptanceCriteria) {
+      lines.push(`- ${c}`);
+    }
+  }
+  if (Array.isArray(workItem.dependencies) && workItem.dependencies.length > 0) {
+    lines.push('', '## Dependencies');
+    for (const d of workItem.dependencies) {
+      lines.push(`- ${d}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Fix failed checks one at a time with regression detection.
+ * @param {Object} params - Named parameters
+ * @param {Object[]} params.failedChecks - Array of failed check results (from scorer), sorted by severity
+ * @param {Object[]} params.allCheckDefinitions - All check definitions (for re-running)
+ * @param {Object[]} params.allCheckResults - All check results from initial run (for regression comparison)
+ * @param {Object} params.workItem - The work item object (epic or story) to fix
+ * @param {string} params.workItemText - The work item context markdown
+ * @param {string} params.workItemType - "epic" or "story"
+ * @param {Object} params.llmProvider - LLM provider instance
+ * @param {number} [params.maxFixAttempts=3] - Max fix iterations
+ * @param {Function} [params.generateContextFn] - Regenerate context markdown from work item
+ * @param {Function} [params.progressCallback] - Progress reporting callback
+ * @param {number} [params.concurrency] - Concurrency limit (unused for now, fixes are sequential)
+ * @param {Map} [params.tier1Results] - Tier 1 results map for Tier 2 re-runs
+ * @returns {Object} { fixedWorkItem, fixedWorkItemText, fixResults[], rerunResults[], regressionDetected }
+ */
+export async function fixFailedChecks({
+  failedChecks,
+  allCheckDefinitions,
+  allCheckResults = [],
+  workItem,
+  workItemText,
+  workItemType,
+  llmProvider,
+  maxFixAttempts = 3,
+  generateContextFn = null,
+  progressCallback = null,
+  concurrency = 5,
+  tier1Results = null,
+} = {}) {
+
+  // Sort by severity: critical first, then major. Skip minor.
+  const fixable = [...failedChecks]
+    .filter((c) => c.severity === 'critical' || c.severity === 'major')
+    .sort((a, b) => (SEVERITY_PRIORITY[a.severity] || 99) - (SEVERITY_PRIORITY[b.severity] || 99));
+
+  // Build a lookup map for check definitions by id
+  const checkDefMap = new Map();
+  for (const def of allCheckDefinitions) {
+    checkDefMap.set(def.id, def);
+  }
+
+  // Working copies that accumulate fixes
+  let currentWorkItem = cloneWorkItem(workItem);
+  let currentText = workItemText;
+  const originalWorkItem = cloneWorkItem(workItem);
+  const originalText = workItemText;
+
+  const fixResults = [];
+  let fixCount = 0;
+
+  // 2. Fix each failed check individually
+  for (const failedCheck of fixable) {
+    if (fixCount >= maxFixAttempts) {
+      break;
+    }
+
+    const snapshotWorkItem = cloneWorkItem(currentWorkItem);
+    const snapshotText = currentText;
+
+    // 2a. Build prompt and call LLM for fix
+    const prompt = buildFixPrompt(workItemType, currentText, failedCheck);
+    let fixResponse;
+    try {
+      fixResponse = await llmProvider.generateJSON(prompt, FIX_SYSTEM_INSTRUCTIONS);
+    } catch (err) {
+      console.error(`[DEBUG] Fix LLM call failed for check ${failedCheck.id}:`, err.message);
+      fixResults.push({ checkId: failedCheck.id, attempted: true, fixed: false, reverted: false });
+      continue;
+    }
+
+    // Parse fix response (may already be an object from generateJSON)
+    let fixData;
+    if (fixResponse && typeof fixResponse === 'object') {
+      fixData = fixResponse;
+    } else {
+      try {
+        fixData = JSON.parse(String(fixResponse));
+      } catch {
+        console.error(`[DEBUG] Failed to parse fix response for check ${failedCheck.id}`);
+        fixResults.push({ checkId: failedCheck.id, attempted: true, fixed: false, reverted: false });
+        continue;
+      }
+    }
+
+    // 2b. Apply fix to working copy
+    currentWorkItem = mergeWorkItemFields(currentWorkItem, fixData, workItemType);
+    if (generateContextFn) {
+      currentText = await generateContextFn(currentWorkItem);
+    } else {
+      currentText = generateBasicContext(currentWorkItem, workItemType);
+    }
+
+    // 2c. Re-run the specific check that was fixed
+    const checkDef = checkDefMap.get(failedCheck.id);
+    if (!checkDef) {
+      // Cannot verify without definition — accept optimistically
+      fixResults.push({ checkId: failedCheck.id, attempted: true, fixed: true, reverted: false });
+      fixCount++;
+      continue;
+    }
+
+    let rerunResult;
+    try {
+      rerunResult = await rerunCheck(checkDef, currentText, llmProvider, tier1Results);
+    } catch (err) {
+      console.error(`[DEBUG] Re-run check failed for ${failedCheck.id}:`, err.message);
+      // Revert on verification failure
+      currentWorkItem = snapshotWorkItem;
+      currentText = snapshotText;
+      fixResults.push({ checkId: failedCheck.id, attempted: true, fixed: false, reverted: true });
+      continue;
+    }
+
+    if (rerunResult.passed) {
+      // Fix accepted
+      fixResults.push({ checkId: failedCheck.id, attempted: true, fixed: true, reverted: false });
+      fixCount++;
+    } else {
+      // Fix didn't work — revert
+      currentWorkItem = snapshotWorkItem;
+      currentText = snapshotText;
+      fixResults.push({ checkId: failedCheck.id, attempted: true, fixed: false, reverted: true });
+    }
+  }
+
+  // 3. Post-fix regression scan
+  // Tolerate minor noise from local models — only revert if regression rate > 20%
+  // of previously-passing checks (single flipped result on a noisy model ≠ true regression)
+  const previouslyPassing = allCheckResults.filter(
+    (r) => r.applicable !== false && r.passed === true
+  );
+
+  const rerunResults = [];
+  let regressionCount = 0;
+
+  for (const passingResult of previouslyPassing) {
+    const checkDef = checkDefMap.get(passingResult.id);
+    if (!checkDef) {
+      continue;
+    }
+
+    let rerunResult;
+    try {
+      rerunResult = await rerunCheck(checkDef, currentText, llmProvider, tier1Results);
+    } catch {
+      // If we can't verify, treat as potential regression
+      rerunResult = { id: passingResult.id, passed: false, evidence: 'Re-run failed' };
+    }
+    rerunResults.push(rerunResult);
+
+    if (rerunResult.passed === false) {
+      regressionCount++;
+    }
+  }
+
+  // Only revert if >20% of previously-passing checks now fail (accounts for LLM noise)
+  const regressionRate = previouslyPassing.length > 0 ? regressionCount / previouslyPassing.length : 0;
+  const regressionDetected = regressionRate > 0.2;
+
+  if (regressionDetected) {
+    console.warn(`[DEBUG] Regression detected during post-fix scan. ${regressionCount}/${previouslyPassing.length} (${(regressionRate * 100).toFixed(0)}%) checks flipped. Reverting all fixes.`);
+    return {
+      fixedWorkItem: originalWorkItem,
+      fixedWorkItemText: originalText,
+      fixResults,
+      rerunResults,
+      regressionDetected: true,
+    };
+  }
+
+  if (regressionCount > 0) {
+    console.log(`[DEBUG] Post-fix scan: ${regressionCount}/${previouslyPassing.length} checks flipped (${(regressionRate * 100).toFixed(0)}%) — within noise tolerance, keeping fixes.`);
+  }
+
+  return {
+    fixedWorkItem: currentWorkItem,
+    fixedWorkItemText: currentText,
+    fixResults,
+    rerunResults,
+    regressionDetected: false,
+  };
+}