@jaimevalasek/aioson 1.6.0 → 1.7.2

package/src/squad/context-compactor.js

@@ -0,0 +1,265 @@
+'use strict';
+
+/**
+ * Context Compactor — Plan 80, Script 5
+ *
+ * Standalone context compaction for any agent session (not just squads).
+ * Produces a last-handoff.json compatible with recovery-context.js.
+ *
+ * Usage:
+ *   node context-compactor.js --agent=<agent> [--input=devlog.md] [--session=<id>]
+ *
+ * Reads: stdin or --input (devlog, notes, partial output)
+ * Produces: .aioson/context/last-handoff.json
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+
+const CONTEXT_DIR = path.join('.aioson', 'context');
+
+// ─── Content extractors ──────────────────────────────────────────────────────
+
+/**
+ * Extract tool usage from session content.
+ * Looks for patterns like "Used X tool", "Called X", tool names in backticks.
+ */
+function extractToolsUsed(content) {
+  const tools = new Set();
+  const patterns = [
+    /\b(Read|Write|Edit|Glob|Grep|Bash|Agent)\b/g,
+    /tool[:\s]+["`](\w+)["`]/gi,
+    /using\s+(\w+)\s+tool/gi
+  ];
+
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      tools.add(match[1]);
+    }
+  }
+
+  return [...tools];
+}
+
+/**
+ * Extract recent requests/instructions from content.
+ * Looks for imperative sentences, commands, task descriptions.
+ */
+function extractRecentRequests(content) {
+  const requests = [];
+  const lines = content.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Match task-like lines
+    if (/^[-*]\s*\[.\]/.test(trimmed)) {
+      requests.push(trimmed.replace(/^[-*]\s*\[.\]\s*/, ''));
+    }
+    // Match "Task:" or "Goal:" prefixed lines
+    if (/^(task|goal|objective|instruction):/i.test(trimmed)) {
+      requests.push(trimmed);
+    }
+  }
+
+  return requests.slice(-10);
+}
+
+/**
+ * Extract pending/incomplete work from content.
+ */
+function extractPendingWork(content) {
+  const pending = [];
+  const lines = content.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Unchecked checkboxes
+    if (/^[-*]\s*\[\s\]/.test(trimmed)) {
+      pending.push(trimmed.replace(/^[-*]\s*\[\s\]\s*/, ''));
+    }
+    // Lines with TODO/FIXME/HACK
+    if (/\b(TODO|FIXME|HACK|PENDING)\b/i.test(trimmed)) {
+      pending.push(trimmed);
+    }
+  }
+
+  return pending.slice(-10);
+}
+
+/**
+ * Extract key file references from content.
+ */
+function extractKeyFiles(content) {
+  const files = new Set();
+  // Match file paths with extensions
+  const pattern = /(?:^|\s)([\w./\\-]+\.\w{1,8})\b/g;
+  let match;
+
+  while ((match = pattern.exec(content)) !== null) {
+    const candidate = match[1];
+    // Filter out obvious non-paths
+    if (candidate.includes('/') || candidate.includes('\\')) {
+      files.add(candidate);
+    }
+  }
+
+  return [...files].slice(0, 20);
+}
+
+/**
+ * Extract timeline events from content.
+ * Looks for timestamps, "Step N:", numbered lists with actions.
+ */
+function extractTimeline(content) {
+  const events = [];
+  const lines = content.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // ISO timestamps
+    if (/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(trimmed)) {
+      events.push(trimmed.slice(0, 120));
+    }
+    // "Step N:" pattern
+    if (/^step\s+\d+/i.test(trimmed)) {
+      events.push(trimmed.slice(0, 120));
+    }
+    // Section headers that indicate progress
+    if (/^#+\s*(phase|step|stage|sprint|iteration)\b/i.test(trimmed)) {
+      events.push(trimmed.replace(/^#+\s*/, ''));
+    }
+  }
+
+  return events.slice(-15);
+}
+
+// ─── XML format ──────────────────────────────────────────────────────────────
+
+/**
+ * Generate <summary> XML compatible with Claude Code internal format.
+ */
+function toSummaryXml(summary, agent, sessionId) {
+  const lines = [
+    '<summary>',
+    `<agent>${agent}</agent>`,
+    `<session_id>${sessionId}</session_id>`,
+    '<tools_used>'
+  ];
+
+  for (const tool of summary.tools_used) {
+    lines.push(`  <tool>${tool}</tool>`);
+  }
+  lines.push('</tools_used>');
+
+  if (summary.recent_requests.length > 0) {
+    lines.push('<recent_requests>');
+    for (const req of summary.recent_requests) {
+      lines.push(`  <request>${escapeXml(req)}</request>`);
+    }
+    lines.push('</recent_requests>');
+  }
+
+  if (summary.pending_work.length > 0) {
+    lines.push('<pending_work>');
+    for (const item of summary.pending_work) {
+      lines.push(`  <item>${escapeXml(item)}</item>`);
+    }
+    lines.push('</pending_work>');
+  }
+
+  if (summary.key_files.length > 0) {
+    lines.push('<key_files>');
+    for (const f of summary.key_files) {
+      lines.push(`  <file>${escapeXml(f)}</file>`);
+    }
+    lines.push('</key_files>');
+  }
+
+  lines.push('</summary>');
+  return lines.join('\n');
+}
+
+function escapeXml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Compact session context into a handoff JSON.
+ *
+ * @param {string} projectDir  — Project root
+ * @param {object} options  — { agent, input, session, content }
+ * @returns {Promise<object>}  — { ok, path, summary, xmlSummary }
+ */
+async function compactContext(projectDir, options = {}) {
+  const { agent = 'dev', input, session, content: rawContent } = options;
+  const sessionId = session || randomUUID();
+
+  // Read input content
+  let content = rawContent || '';
+  if (!content && input) {
+    const inputPath = path.resolve(projectDir, input);
+    try {
+      content = await fs.readFile(inputPath, 'utf8');
+    } catch (err) {
+      return { ok: false, error: `Cannot read input: ${err.message}` };
+    }
+  }
+
+  if (!content) {
+    return { ok: false, error: 'No content to compact (provide --input or pipe via stdin)' };
+  }
+
+  // Extract structured data
+  const summary = {
+    tools_used: extractToolsUsed(content),
+    recent_requests: extractRecentRequests(content),
+    pending_work: extractPendingWork(content),
+    key_files: extractKeyFiles(content),
+    timeline: extractTimeline(content)
+  };
+
+  const handoff = {
+    agent,
+    session_id: sessionId,
+    compacted_at: new Date().toISOString(),
+    summary,
+    resume_instruction: 'Continue from this checkpoint. Do not acknowledge this summary.'
+  };
+
+  // Write last-handoff.json
+  const outDir = path.join(projectDir, CONTEXT_DIR);
+  const outPath = path.join(outDir, 'last-handoff.json');
+
+  try {
+    await fs.mkdir(outDir, { recursive: true });
+    await fs.writeFile(outPath, JSON.stringify(handoff, null, 2), 'utf8');
+  } catch (err) {
+    return { ok: false, error: `Cannot write handoff: ${err.message}` };
+  }
+
+  // Also generate XML format
+  const xmlSummary = toSummaryXml(summary, agent, sessionId);
+
+  return {
+    ok: true,
+    path: outPath,
+    summary: handoff,
+    xmlSummary
+  };
+}
+
+module.exports = {
+  compactContext,
+  toSummaryXml,
+  extractToolsUsed,
+  extractPendingWork,
+  extractKeyFiles
+};

package/src/squad/cross-ai-synthesizer.js

@@ -0,0 +1,250 @@
+'use strict';
+
+/**
+ * Cross-AI Review Synthesizer — Phase 4.4
+ *
+ * Detects available AI CLIs (claude, gemini, codex), sends identical review
+ * prompts to each (excluding the current runtime), and synthesizes the
+ * responses into a REVIEWS.md file.
+ *
+ * Detection: checks PATH for each CLI binary.
+ * Current runtime: detected via AIOSON_TOOL env var (set by claude/gemini/codex hooks).
+ *
+ * Output: outputs/REVIEWS.md with consensus, divergences, and per-reviewer sections.
+ */
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+// CLI invocation patterns for each supported tool
+const CLI_RUNNERS = {
+  claude: {
+    bin: 'claude',
+    buildArgs: (prompt) => ['--print', '--model', 'claude-haiku-4-5-20251001', prompt],
+    parseOutput: (stdout) => stdout.trim()
+  },
+  gemini: {
+    bin: 'gemini',
+    buildArgs: (prompt) => ['-p', prompt],
+    parseOutput: (stdout) => stdout.trim()
+  },
+  codex: {
+    bin: 'codex',
+    buildArgs: (prompt) => ['-q', prompt],
+    parseOutput: (stdout) => stdout.trim()
+  }
+};
+
+/**
+ * Check if a binary is available in PATH.
+ */
+function binaryExists(bin) {
+  const result = spawnSync('which', [bin], { encoding: 'utf8', timeout: 3000 });
+  return result.status === 0 && Boolean(result.stdout.trim());
+}
+
+/**
+ * Detect which AI CLIs are available in the current environment.
+ * Excludes the current runtime (detected from AIOSON_TOOL or process title).
+ */
+function detectAvailableCLIs({ excludeCurrent = true } = {}) {
+  const currentTool = process.env.AIOSON_TOOL || '';
+  const available = [];
+
+  for (const [name, runner] of Object.entries(CLI_RUNNERS)) {
+    if (excludeCurrent && currentTool && currentTool.toLowerCase().includes(name)) continue;
+    if (binaryExists(runner.bin)) {
+      available.push(name);
+    }
+  }
+
+  return available;
+}
+
+/**
+ * Send a prompt to a specific CLI and return its response.
+ */
+function queryCliReviewer(cliName, prompt, timeoutMs = 60_000) {
+  const runner = CLI_RUNNERS[cliName];
+  if (!runner) return { ok: false, error: `Unknown CLI: ${cliName}` };
+
+  try {
+    const result = spawnSync(runner.bin, runner.buildArgs(prompt), {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      stdio: 'pipe'
+    });
+
+    if (result.status !== 0) {
+      return {
+        ok: false,
+        cli: cliName,
+        error: (result.stderr || '').trim() || `exited with code ${result.status}`
+      };
+    }
+
+    const response = runner.parseOutput(result.stdout || '');
+    return { ok: true, cli: cliName, response };
+  } catch (err) {
+    return { ok: false, cli: cliName, error: err.message };
+  }
+}
+
+/**
+ * Build a review prompt for a given output file.
+ */
+function buildReviewPrompt(outputContent, reviewCriteria = []) {
+  const criteria = reviewCriteria.length > 0
+    ? reviewCriteria.map((c, i) => `${i + 1}. ${c}`).join('\n')
+    : '1. Is the content complete and accurate?\n2. Are there any logical errors or gaps?\n3. What could be improved?';
+
+  return `You are reviewing the following output. Be concise and direct.
+
+## Content to Review
+
+\`\`\`
+${outputContent.slice(0, 4000)}${outputContent.length > 4000 ? '\n... (truncated)' : ''}
+\`\`\`
+
+## Review Criteria
+
+${criteria}
+
+## Your Review
+
+Provide your review in 3 sections:
+- **Strengths**: what works well
+- **Issues**: specific problems found (if any)
+- **Recommendations**: concrete improvements (max 3)
+
+Keep total response under 400 words.`;
+}
+
+/**
+ * Synthesize multiple reviews into a REVIEWS.md document.
+ */
+function synthesizeReviews(reviews, outputPath, squadSlug) {
+  const ts = new Date().toISOString();
+  const successful = reviews.filter((r) => r.ok);
+  const failed = reviews.filter((r) => !r.ok);
+
+  const lines = [
+    `# Cross-AI Review`,
+    ``,
+    `**Squad:** ${squadSlug || 'unknown'}  `,
+    `**Output:** ${outputPath || 'unknown'}  `,
+    `**Generated:** ${ts}  `,
+    `**Reviewers:** ${successful.map((r) => r.cli).join(', ') || 'none'}`,
+    ``
+  ];
+
+  if (successful.length === 0) {
+    lines.push('> No AI reviewers were available or all failed.');
+    if (failed.length > 0) {
+      lines.push('');
+      lines.push('**Failed reviewers:**');
+      for (const f of failed) {
+        lines.push(`- ${f.cli}: ${f.error}`);
+      }
+    }
+    return lines.join('\n');
+  }
+
+  // Per-reviewer sections
+  for (const review of successful) {
+    lines.push(`## ${review.cli.charAt(0).toUpperCase() + review.cli.slice(1)}'s Review`);
+    lines.push('');
+    lines.push(review.response);
+    lines.push('');
+  }
+
+  // Divergence note (heuristic: reviewers that mention different keywords)
+  if (successful.length > 1) {
+    const issueKeywords = ['problem', 'error', 'issue', 'missing', 'incorrect', 'wrong', 'fail'];
+    const reviewersWithIssues = successful.filter((r) =>
+      issueKeywords.some((kw) => r.response.toLowerCase().includes(kw))
+    );
+
+    lines.push('---');
+    lines.push('');
+    lines.push('## Synthesis');
+    lines.push('');
+
+    if (reviewersWithIssues.length === 0) {
+      lines.push('**Consensus:** All reviewers found no significant issues.');
+    } else if (reviewersWithIssues.length === successful.length) {
+      lines.push(`**Consensus:** All reviewers identified issues — address before shipping.`);
+    } else {
+      lines.push(`**Divergence:** ${reviewersWithIssues.map((r) => r.cli).join(', ')} found issues; others approved.`);
+    }
+    lines.push('');
+  }
+
+  if (failed.length > 0) {
+    lines.push('> **Note:** The following reviewers failed: ' + failed.map((f) => `${f.cli} (${f.error})`).join(', '));
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Run the full cross-AI review pipeline.
+ *
+ * @param {{ projectDir, outputFile, reviewCriteria?, squadSlug?, excludeCurrent?, synthesizeTo? }} opts
+ */
+async function runCrossAIReview({
+  projectDir,
+  outputFile,
+  reviewCriteria = [],
+  squadSlug = '',
+  excludeCurrent = true,
+  synthesizeTo = null,
+  timeoutMs = 60_000
+}) {
+  // Read output content
+  let outputContent;
+  try {
+    outputContent = await fs.readFile(outputFile, 'utf8');
+  } catch {
+    return { ok: false, error: `Output file not found: ${outputFile}` };
+  }
+
+  // Detect available CLIs
+  const clis = detectAvailableCLIs({ excludeCurrent });
+  if (clis.length === 0) {
+    return {
+      ok: false,
+      error: 'No AI CLIs detected. Install claude, gemini, or codex in PATH.',
+      detectedCLIs: []
+    };
+  }
+
+  // Build review prompt
+  const prompt = buildReviewPrompt(outputContent, reviewCriteria);
+
+  // Query each reviewer
+  const reviews = clis.map((cli) => queryCliReviewer(cli, prompt, timeoutMs));
+
+  // Synthesize
+  const markdown = synthesizeReviews(reviews, outputFile, squadSlug);
+
+  // Write REVIEWS.md
+  const reviewsPath = synthesizeTo ||
+    path.join(path.dirname(outputFile), 'REVIEWS.md');
+
+  await fs.mkdir(path.dirname(reviewsPath), { recursive: true });
+  await fs.writeFile(reviewsPath, markdown, 'utf8');
+
+  return {
+    ok: true,
+    reviewers: clis,
+    successCount: reviews.filter((r) => r.ok).length,
+    failCount: reviews.filter((r) => !r.ok).length,
+    reviewsPath,
+    reviews
+  };
+}
+
+module.exports = { runCrossAIReview, detectAvailableCLIs, synthesizeReviews, buildReviewPrompt };

package/src/squad/hooks-generator.js

@@ -0,0 +1,196 @@
+'use strict';
+
+/**
+ * Hooks Generator — Plan 81, Phase 1.2
+ *
+ * Generates Claude Code .claude/settings.json hooks for squad execution.
+ * Uses hook types: command, agent.
+ *
+ * Generated hooks:
+ *   - Stop hook: quality gate agent that blocks incomplete work
+ *   - TaskCompleted hook: learning extraction after each task
+ *   - PostToolUse hook: mailbox-to-bus bridge (SendMessage interception)
+ *
+ * The hooks are session-scoped: written before squad:autorun starts,
+ * cleaned up after the session ends (or left for the next session).
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const CLAUDE_DIR = '.claude';
+const SETTINGS_FILE = 'settings.json';
+const AGENTS_DIR = path.join(CLAUDE_DIR, 'agents');
+
+// ─── Quality Gate Agent Template ─────────────────────────────────────────────
+
+function qualityGateAgentTemplate(squadSlug) {
+  return `# Squad Quality Gate — ${squadSlug}
+
+You are a verification agent for the "${squadSlug}" squad. Before allowing a worker to finish:
+
+1. Read the worker's output files listed in the task brief
+2. Check must_haves from the task specification:
+   - **Tier 1 (Exists):** All required files exist on disk
+   - **Tier 2 (Substantive):** Files have meaningful content (no stubs, TODOs, or placeholders)
+   - **Tier 3 (Wired):** Files are referenced/imported where they should be
+3. If any tier fails: respond with BLOCK and specific feedback on what is missing
+4. If all pass: respond with ALLOW
+
+## Output Format
+
+\`\`\`json
+{
+  "decision": "allow|block",
+  "tier_results": {
+    "exists": true,
+    "substantive": true,
+    "wired": true
+  },
+  "reason": "All tiers passed — output meets acceptance criteria",
+  "issues": []
+}
+\`\`\`
+
+## Important
+
+- You have NO context from the generating agent's conversation
+- Judge ONLY the artifacts on disk vs the spec requirements
+- Be strict on Tier 1 (exists) and Tier 2 (substantive)
+- Be lenient on Tier 3 (wired) — warn but don't block for minor wiring issues
+`;
+}
+
+// ─── Settings Generator ──────────────────────────────────────────────────────
+
+/**
+ * Generate Claude Code hooks configuration for a squad session.
+ *
+ * @param {string} projectDir
+ * @param {string} squadSlug
+ * @param {object} [options]  — { enableQualityGate, enableLearning, enableBusBridge }
+ * @returns {object}  — hooks configuration object
+ */
+function generateHooksConfig(squadSlug, options = {}) {
+  const {
+    enableQualityGate = true,
+    enableLearning = true,
+    enableBusBridge = false
+  } = options;
+
+  const hooks = {};
+
+  // Stop hook: quality gate (blocks workers from finishing with incomplete work)
+  if (enableQualityGate) {
+    hooks.Stop = [{
+      type: 'agent',
+      agent: `.claude/agents/squad-quality-gate-${squadSlug}.md`,
+      matcher: `agent:squad-worker-*`
+    }];
+  }
+
+  // TaskCompleted hook: automatic learning extraction
+  if (enableLearning) {
+    if (!hooks.TaskCompleted) hooks.TaskCompleted = [];
+    hooks.TaskCompleted.push({
+      type: 'command',
+      command: `node -e "require('./src/squad/learning-extractor').extractLearnings(process.cwd(), '${squadSlug}', process.env.SESSION_ID || 'unknown', { busMessages: [], taskResults: [], reflectionReports: [] }).catch(() => {})"`
+    });
+  }
+
+  // PostToolUse hook: mailbox-to-bus bridge (intercepts SendMessage)
+  if (enableBusBridge) {
+    if (!hooks.PostToolUse) hooks.PostToolUse = [];
+    hooks.PostToolUse.push({
+      type: 'command',
+      matcher: 'SendMessage',
+      command: `node -e "require('./src/squad/bus-bridge').bridgeMailboxToBus(process.cwd(), '${squadSlug}', process.env.SESSION_ID || 'unknown', process.env.TOOL_INPUT || '{}').catch(() => {})"`
+    });
+  }
+
+  return hooks;
+}
+
+/**
+ * Write hooks to .claude/settings.json (merge with existing).
+ *
+ * @param {string} projectDir
+ * @param {string} squadSlug
+ * @param {object} [options]
+ * @returns {Promise<object>}  — { settingsPath, agentPath, hooks }
+ */
+async function writeSquadHooks(projectDir, squadSlug, options = {}) {
+  const settingsDir = path.join(projectDir, CLAUDE_DIR);
+  const settingsPath = path.join(settingsDir, SETTINGS_FILE);
+  const agentsDir = path.join(projectDir, AGENTS_DIR);
+
+  // Ensure directories
+  await fs.mkdir(settingsDir, { recursive: true });
+  await fs.mkdir(agentsDir, { recursive: true });
+
+  // Read existing settings
+  let existing = {};
+  try {
+    existing = JSON.parse(await fs.readFile(settingsPath, 'utf8'));
+  } catch { /* no existing settings */ }
+
+  // Generate hooks
+  const hooks = generateHooksConfig(squadSlug, options);
+
+  // Merge hooks (squad hooks go into a namespaced section)
+  const merged = {
+    ...existing,
+    hooks: {
+      ...(existing.hooks || {}),
+      ...hooks
+    },
+    _squadHooksFor: squadSlug,
+    _squadHooksAt: new Date().toISOString()
+  };
+
+  await fs.writeFile(settingsPath, JSON.stringify(merged, null, 2), 'utf8');
+
+  // Write quality gate agent template
+  let agentPath = null;
+  if (options.enableQualityGate !== false) {
+    agentPath = path.join(agentsDir, `squad-quality-gate-${squadSlug}.md`);
+    await fs.writeFile(agentPath, qualityGateAgentTemplate(squadSlug), 'utf8');
+  }
+
+  return {
+    settingsPath,
+    agentPath,
+    hooks,
+    merged: Object.keys(hooks).length
+  };
+}
+
+/**
+ * Remove squad-specific hooks from .claude/settings.json.
+ */
+async function cleanupSquadHooks(projectDir, squadSlug) {
+  const settingsPath = path.join(projectDir, CLAUDE_DIR, SETTINGS_FILE);
+
+  try {
+    const existing = JSON.parse(await fs.readFile(settingsPath, 'utf8'));
+
+    if (existing._squadHooksFor === squadSlug) {
+      // Remove squad-specific hooks
+      delete existing.hooks;
+      delete existing._squadHooksFor;
+      delete existing._squadHooksAt;
+      await fs.writeFile(settingsPath, JSON.stringify(existing, null, 2), 'utf8');
+    }
+
+    // Remove quality gate agent
+    const agentPath = path.join(projectDir, AGENTS_DIR, `squad-quality-gate-${squadSlug}.md`);
+    await fs.unlink(agentPath).catch(() => {});
+  } catch { /* no settings to clean */ }
+}
+
+module.exports = {
+  generateHooksConfig,
+  writeSquadHooks,
+  cleanupSquadHooks,
+  qualityGateAgentTemplate
+};