@jaimevalasek/aioson 1.6.0 → 1.7.2

package/src/squad/reflection.js

@@ -0,0 +1,365 @@
+'use strict';
+
+/**
+ * Squad executor reflection module
+ *
+ * Before marking a task DONE, an executor runs a self-critique pass
+ * against its output. If the output fails the quality checklist, the
+ * executor iterates (up to max_iterations) before escalating to the
+ * coordinator or marking as DONE_WITH_CONCERNS.
+ *
+ * Reflection is triggered automatically when:
+ *   - A worker calls reflect() before returning its result
+ *   - The task-decomposer runs a plan step with reflection enabled
+ *   - The squad:autorun command is invoked with --reflect
+ *
+ * Checklist sources (in priority order):
+ *   1. squad.json → executors[slug].reflection.checklist
+ *   2. .aioson/squads/{slug}/quality.md (freeform checklist file)
+ *   3. Built-in generic quality criteria (fallback)
+ *
+ * Verdict:
+ *   DONE              — passed all checks, no issues
+ *   DONE_WITH_CONCERNS — passed minimally but has minor issues (flagged)
+ *   NEEDS_ITERATION   — failed critical checks, should retry
+ *   ESCALATE          — exhausted iterations, coordinator must decide
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { checkMustHaves } = require('./verify-gate');
+
+// ─── Built-in quality criteria (generic fallback) ────────────────────────────
+
+const GENERIC_CHECKLIST = [
+  { id: 'non_empty',     label: 'Output is not empty',                  critical: true  },
+  { id: 'on_topic',      label: 'Output addresses the task objective',  critical: true  },
+  { id: 'no_truncation', label: 'Output is not abruptly cut off',       critical: true  },
+  { id: 'no_filler',     label: 'Output has no generic filler content', critical: false },
+  { id: 'actionable',    label: 'Output contains concrete information', critical: false }
+];
+
+// ─── Checklist loading ────────────────────────────────────────────────────────
+
+async function loadSquadJson(projectDir, squadSlug) {
+  const p = path.join(projectDir, '.aioson', 'squads', squadSlug, 'squad.json');
+  try {
+    return JSON.parse(await fs.readFile(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function loadQualityFile(projectDir, squadSlug) {
+  const p = path.join(projectDir, '.aioson', 'squads', squadSlug, 'quality.md');
+  try {
+    const raw = await fs.readFile(p, 'utf8');
+    return parseQualityMarkdown(raw);
+  } catch {
+    return null;
+  }
+}
+
+function parseQualityMarkdown(content) {
+  const criteria = [];
+  const lines = content.split(/\r?\n/);
+  let id = 0;
+
+  for (const line of lines) {
+    // Support: "- [critical] Label" or "- Label" or "* Label"
+    const match = line.match(/^[-*]\s+(?:\[(\w+)\]\s+)?(.+)$/);
+    if (!match) continue;
+
+    const tag = (match[1] || '').toLowerCase();
+    const label = match[2].trim();
+    if (!label) continue;
+
+    criteria.push({
+      id: `custom_${++id}`,
+      label,
+      critical: tag === 'critical'
+    });
+  }
+
+  return criteria.length > 0 ? criteria : null;
+}
+
+async function loadChecklist(projectDir, squadSlug, executorSlug) {
+  // 1. squad.json executor-specific checklist
+  const squadJson = await loadSquadJson(projectDir, squadSlug);
+  if (squadJson) {
+    const executorConfig = squadJson.executors && squadJson.executors[executorSlug];
+    const checklist = executorConfig && executorConfig.reflection && executorConfig.reflection.checklist;
+    if (Array.isArray(checklist) && checklist.length > 0) {
+      return checklist.map((item, i) => {
+        if (typeof item === 'string') {
+          return { id: `exec_${i}`, label: item, critical: false };
+        }
+        return { id: item.id || `exec_${i}`, label: item.label || item, critical: !!item.critical };
+      });
+    }
+  }
+
+  // 2. quality.md file
+  const fromFile = await loadQualityFile(projectDir, squadSlug);
+  if (fromFile) return fromFile;
+
+  // 3. Generic fallback
+  return GENERIC_CHECKLIST;
+}
+
+function loadMaxIterations(squadJson, executorSlug) {
+  const config = squadJson && squadJson.executors && squadJson.executors[executorSlug];
+  const val = config && config.reflection && config.reflection.max_iterations;
+  return Number.isFinite(val) && val > 0 ? Math.min(val, 5) : 2;
+}
+
+// ─── Deterministic checks ────────────────────────────────────────────────────
+
+const FILLER_PATTERNS = [
+  /\bi will\b/i,
+  /\bof course\b/i,
+  /\bcertainly\b/i,
+  /\bsure,?\s+here\b/i,
+  /\bas an ai\b/i,
+  /\bgreat question\b/i,
+  /\bhappy to help\b/i,
+  /\bI'?d be happy\b/i
+];
+
+function runBuiltinCheck(id, output) {
+  const text = String(output || '').trim();
+  switch (id) {
+    case 'non_empty':
+      return text.length > 0;
+    case 'on_topic':
+      // heuristic: output has at least 50 chars and is not just whitespace
+      return text.length >= 50;
+    case 'no_truncation':
+      // heuristic: doesn't end mid-sentence (no trailing comma or open paren)
+      return !/[,(\[{]$/.test(text.replace(/\s+$/, ''));
+    case 'no_filler':
+      return !FILLER_PATTERNS.some((re) => re.test(text));
+    case 'actionable':
+      // heuristic: contains at least one noun or verb indicator
+      return text.split(/\s+/).length >= 10;
+    default:
+      // Custom criteria without a built-in check — mark as needs-llm-review
+      return null;
+  }
+}
+
+// ─── Core reflection ─────────────────────────────────────────────────────────
+
+/**
+ * Run a reflection pass on an executor's output.
+ *
+ * @param {string}  output       — The text output to evaluate
+ * @param {object}  context      — { projectDir, squadSlug, executorSlug, taskTitle?, iteration?, task? }
+ *                                  task: the full task object (optional) — enables must_haves verification
+ * @param {object}  [options]    — { checklist?, verbose? }
+ * @returns {Promise<ReflectionResult>}
+ *
+ * ReflectionResult:
+ *   {
+ *     verdict: 'DONE' | 'DONE_WITH_CONCERNS' | 'NEEDS_ITERATION' | 'ESCALATE',
+ *     passed: boolean,
+ *     score: number,          // 0.0–1.0
+ *     iteration: number,      // current iteration number
+ *     max_iterations: number,
+ *     issues: string[],       // failed criteria labels
+ *     critical_failures: string[],
+ *     needs_llm_review: string[],  // criteria that couldn't be checked deterministically
+ *     summary: string,        // one-line human-readable result
+ *     checklist: object[]     // full results per criterion
+ *   }
+ */
+async function reflect(output, context, options = {}) {
+  const { projectDir, squadSlug, executorSlug, taskTitle = 'task', iteration = 1, task } = context;
+
+  const squadJson = await loadSquadJson(projectDir, squadSlug);
+  const maxIterations = loadMaxIterations(squadJson, executorSlug);
+
+  const checklist = options.checklist
+    ? options.checklist.map((item, i) => (
+        typeof item === 'string'
+          ? { id: `opt_${i}`, label: item, critical: false }
+          : item
+      ))
+    : await loadChecklist(projectDir, squadSlug, executorSlug);
+
+  const results = [];
+  const issues = [];
+  const criticalFailures = [];
+  const needsLlmReview = [];
+
+  for (const criterion of checklist) {
+    const checkResult = runBuiltinCheck(criterion.id, output);
+
+    if (checkResult === null) {
+      needsLlmReview.push(criterion.label);
+      results.push({ ...criterion, result: 'needs_review', passed: null });
+      continue;
+    }
+
+    results.push({ ...criterion, result: checkResult ? 'pass' : 'fail', passed: checkResult });
+
+    if (!checkResult) {
+      issues.push(criterion.label);
+      if (criterion.critical) criticalFailures.push(criterion.label);
+    }
+  }
+
+  // ── must_haves verification (4-tier gate) ─────────────────────────────────
+  let mustHavesResult = null;
+  if (task && task.must_haves) {
+    mustHavesResult = await checkMustHaves(task.must_haves, output, projectDir).catch(() => null);
+
+    if (mustHavesResult) {
+      // Artifact failures are critical (file must exist and be substantive)
+      for (const failure of mustHavesResult.failures) {
+        criticalFailures.push(`[must_have] ${failure}`);
+        issues.push(`[must_have] ${failure}`);
+      }
+      // Warnings are non-critical (truths, key_links)
+      for (const warning of mustHavesResult.warnings) {
+        issues.push(`[must_have] ${warning}`);
+      }
+    }
+  }
+
+  const evaluated = results.filter((r) => r.passed !== null);
+  const passedCount = evaluated.filter((r) => r.passed).length;
+  const score = evaluated.length > 0 ? passedCount / evaluated.length : 1.0;
+  const passed = criticalFailures.length === 0;
+
+  let verdict;
+  if (criticalFailures.length > 0 && iteration < maxIterations) {
+    verdict = 'NEEDS_ITERATION';
+  } else if (criticalFailures.length > 0 && iteration >= maxIterations) {
+    verdict = 'ESCALATE';
+  } else if (issues.length > 0) {
+    verdict = 'DONE_WITH_CONCERNS';
+  } else {
+    verdict = 'DONE';
+  }
+
+  const summary = buildSummary(verdict, score, issues, criticalFailures, taskTitle, iteration, maxIterations);
+
+  return {
+    verdict,
+    passed,
+    score: Math.round(score * 100) / 100,
+    iteration,
+    max_iterations: maxIterations,
+    issues,
+    critical_failures: criticalFailures,
+    needs_llm_review: needsLlmReview,
+    must_haves_result: mustHavesResult,
+    summary,
+    checklist: results
+  };
+}
+
+function buildSummary(verdict, score, issues, criticalFailures, taskTitle, iteration, maxIterations) {
+  const scoreStr = `${Math.round(score * 100)}%`;
+  switch (verdict) {
+    case 'DONE':
+      return `[DONE] "${taskTitle}" passed all checks (${scoreStr})`;
+    case 'DONE_WITH_CONCERNS':
+      return `[DONE_WITH_CONCERNS] "${taskTitle}" passed (${scoreStr}) with ${issues.length} minor issue(s): ${issues.slice(0, 2).join(', ')}`;
+    case 'NEEDS_ITERATION':
+      return `[NEEDS_ITERATION] "${taskTitle}" failed ${criticalFailures.length} critical check(s) — iteration ${iteration}/${maxIterations}: ${criticalFailures.slice(0, 2).join(', ')}`;
+    case 'ESCALATE':
+      return `[ESCALATE] "${taskTitle}" exhausted ${maxIterations} iterations — coordinator must decide. Failed: ${criticalFailures.join(', ')}`;
+    default:
+      return `[${verdict}] ${scoreStr}`;
+  }
+}
+
+/**
+ * Decide whether to iterate based on a reflection result.
+ * Returns true if another attempt is warranted.
+ */
+function shouldIterate(reflectionResult) {
+  return reflectionResult.verdict === 'NEEDS_ITERATION';
+}
+
+/**
+ * Run a full reflection loop: reflect → iterate if needed → return final result.
+ *
+ * @param {function}  executeFn   — async function that produces output: async () => string
+ * @param {object}    context     — same as reflect()
+ * @param {object}    [options]   — { checklist?, onIteration?, verbose? }
+ * @returns {Promise<{ output: string, reflection: ReflectionResult, iterations: number }>}
+ */
+async function reflectLoop(executeFn, context, options = {}) {
+  const { projectDir, squadSlug, executorSlug } = context;
+  const squadJson = await loadSquadJson(projectDir, squadSlug);
+  const maxIterations = loadMaxIterations(squadJson, executorSlug);
+
+  let lastOutput = null;
+  let lastReflection = null;
+  let iteration = 1;
+
+  while (iteration <= maxIterations) {
+    lastOutput = await executeFn(iteration, lastReflection);
+
+    lastReflection = await reflect(lastOutput, { ...context, iteration }, options);
+
+    if (options.onIteration) {
+      try { await options.onIteration(iteration, lastOutput, lastReflection); } catch { /* ignore */ }
+    }
+
+    if (!shouldIterate(lastReflection)) break;
+    iteration++;
+  }
+
+  return {
+    output: lastOutput,
+    reflection: lastReflection,
+    iterations: iteration
+  };
+}
+
+/**
+ * Format a reflection result as a markdown report.
+ * Useful for the bus (posting reflection results as feedback messages).
+ */
+function formatReport(result, executorSlug) {
+  const lines = [
+    `## Reflection: ${result.verdict}`,
+    `Executor: ${executorSlug || 'unknown'}`,
+    `Score: ${Math.round(result.score * 100)}%  |  Iteration: ${result.iteration}/${result.max_iterations}`,
+    '',
+    `**Summary:** ${result.summary}`
+  ];
+
+  if (result.critical_failures.length > 0) {
+    lines.push('', '**Critical failures:**');
+    for (const f of result.critical_failures) lines.push(`- ❌ ${f}`);
+  }
+
+  if (result.issues.length > result.critical_failures.length) {
+    lines.push('', '**Minor issues:**');
+    for (const issue of result.issues) {
+      if (!result.critical_failures.includes(issue)) lines.push(`- ⚠ ${issue}`);
+    }
+  }
+
+  if (result.needs_llm_review.length > 0) {
+    lines.push('', '**Needs LLM review (could not evaluate deterministically):**');
+    for (const c of result.needs_llm_review) lines.push(`- 🔍 ${c}`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  reflect,
+  reflectLoop,
+  shouldIterate,
+  formatReport,
+  loadChecklist,
+  GENERIC_CHECKLIST
+};

package/src/squad/squad-scaffold.js

@@ -0,0 +1,177 @@
+'use strict';
+
+/**
+ * Squad Scaffold — Plan 80, Script 3
+ *
+ * Deterministic generator of squad directory structure.
+ * Eliminates ~2,000 tokens of LLM usage by creating all 15+ files/directories
+ * that every squad needs via templates.
+ *
+ * Integrates with state-manager.js for STATE.md generation.
+ *
+ * Usage:
+ *   node squad-scaffold.js --slug=<slug> --name="Name" --mode=content|code|hybrid
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const stateManager = require('./state-manager');
+
+const SQUADS_DIR = path.join('.aioson', 'squads');
+
+// ─── Templates ───────────���─────────────────────────��─────────────────────────
+
+function agentsSkeleton(name, mode) {
+  const executorTypes = {
+    content: ['writer', 'editor', 'researcher'],
+    code: ['developer', 'reviewer', 'tester'],
+    hybrid: ['researcher', 'developer', 'writer']
+  };
+
+  const types = executorTypes[mode] || executorTypes.hybrid;
+  const slots = types.map((t) => `### ${t}\n- **Role:** (define)\n- **Tools:** (define)\n- **Checklist:** (define)`);
+
+  return `# ${name} — Agent Roster\n\n${slots.join('\n\n')}\n`;
+}
+
+function manifestSkeleton(slug, name, mode) {
+  return JSON.stringify({
+    slug,
+    name,
+    mode,
+    created_at: new Date().toISOString(),
+    budget: {
+      max_tokens_per_session: null,
+      max_tokens_per_task: null,
+      action_on_exceed: 'pause'
+    },
+    depends_on: [],
+    subscriptions: [],
+    hooks: {
+      pre_run: null,
+      post_run: null
+    },
+    anti_loop: {
+      threshold: 8,
+      action: 'feedback'
+    }
+  }, null, 2);
+}
+
+function squadMdSkeleton(name, mode) {
+  return `# ${name}\n\n## Overview\n(describe the squad's purpose)\n\n## Mode\n${mode}\n\n## Executors\nSee agents/agents.md\n\n## Workflows\n(define execution workflows)\n\n## Quality Gates\nSee checklists/quality.md\n`;
+}
+
+function designDocSkeleton(name) {
+  return `# ${name} — Design Document\n\n## Problem Statement\n(what problem does this squad solve?)\n\n## Approach\n(how will it be solved?)\n\n## Executors & Responsibilities\n(who does what?)\n\n## Data Flow\n(how do executors communicate?)\n\n## Risks & Mitigations\n(what could go wrong?)\n`;
+}
+
+function readinessSkeleton(name) {
+  return `# ${name} — Readiness Checklist\n\n- [ ] Squad manifest configured\n- [ ] All executors defined in agents.md\n- [ ] Quality checklist in place\n- [ ] At least one workflow defined\n- [ ] Design doc reviewed\n- [ ] Test run completed\n`;
+}
+
+function qualitySkeleton(name) {
+  return `# ${name} — Quality Checklist\n\n## Per-Task Checks\n- [ ] Output matches acceptance criteria\n- [ ] No placeholder or TODO content\n- [ ] Files listed in brief are created/modified\n\n## Per-Session Checks\n- [ ] All tasks completed or properly escalated\n- [ ] Bus has no unresolved blocks\n- [ ] STATE.md updated with decisions\n\n## Per-Deliverable Checks\n- [ ] verify:gate passes on final output\n- [ ] No sensitive data in output files\n`;
+}
+
+function learningsIndexSkeleton(name) {
+  return `# ${name} — Learnings Index\n\nsession_count: 0\n\n## Extracted Learnings\n*(populated automatically by learning-extractor after sessions)*\n\n## Manual Observations\n*(add observations here)*\n`;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Scaffold a new squad directory structure.
+ *
+ * @param {string} projectDir  — Project root
+ * @param {object} options  — { slug, name, mode }
+ * @returns {Promise<object>}  — { ok, slug, files, directories }
+ */
+async function scaffoldSquad(projectDir, options = {}) {
+  const { slug, name, mode = 'hybrid' } = options;
+
+  if (!slug) return { ok: false, error: 'slug is required' };
+  if (!name) return { ok: false, error: 'name is required' };
+  if (!['content', 'code', 'hybrid'].includes(mode)) {
+    return { ok: false, error: `Invalid mode "${mode}" — use content|code|hybrid` };
+  }
+
+  const squadDir = path.join(projectDir, SQUADS_DIR, slug);
+
+  // Check if slug already exists
+  try {
+    await fs.access(squadDir);
+    return { ok: false, error: `Squad "${slug}" already exists at ${squadDir}` };
+  } catch { /* expected — directory doesn't exist yet */ }
+
+  const createdFiles = [];
+  const createdDirs = [];
+
+  // Helper
+  async function writeFile(relPath, content) {
+    const fullPath = path.join(projectDir, relPath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, content, 'utf8');
+    createdFiles.push(relPath);
+  }
+
+  async function ensureDir(relPath) {
+    const fullPath = path.join(projectDir, relPath);
+    await fs.mkdir(fullPath, { recursive: true });
+    createdDirs.push(relPath);
+  }
+
+  const base = path.join(SQUADS_DIR, slug);
+
+  // Squad directory files
+  await writeFile(path.join(base, 'agents', 'agents.md'), agentsSkeleton(name, mode));
+  await writeFile(path.join(base, 'squad.manifest.json'), manifestSkeleton(slug, name, mode));
+  await writeFile(path.join(base, 'squad.md'), squadMdSkeleton(name, mode));
+  await writeFile(path.join(base, 'docs', 'design-doc.md'), designDocSkeleton(name));
+  await writeFile(path.join(base, 'docs', 'readiness.md'), readinessSkeleton(name));
+  await writeFile(path.join(base, 'checklists', 'quality.md'), qualitySkeleton(name));
+  await writeFile(path.join(base, 'learnings', 'index.md'), learningsIndexSkeleton(name));
+
+  // Empty directories
+  await ensureDir(path.join(base, 'workflows'));
+  await ensureDir(path.join(base, 'scripts'));
+  await ensureDir(path.join(base, 'script-plans'));
+  await ensureDir(path.join(base, 'bus'));
+
+  // Output directories
+  await ensureDir(path.join('output', slug));
+  await ensureDir(path.join('aioson-logs', slug));
+  await ensureDir(path.join('media', slug));
+
+  // STATE.md via state-manager (already formatted)
+  await stateManager.writeState(projectDir, slug, stateManager.readState
+    ? await stateManager.readState(projectDir, slug)
+    : {
+        meta: {
+          squad: slug,
+          current_session: '',
+          sessions_completed: 0,
+          tasks_completed_total: 0,
+          avg_tasks_per_session: 0,
+          last_activity: new Date().toISOString()
+        },
+        decisions: [],
+        blockers: [],
+        pending: [],
+        notes: [`Squad "${name}" scaffolded (mode: ${mode})`]
+      }
+  );
+  createdFiles.push(path.join(base, 'STATE.md'));
+
+  return {
+    ok: true,
+    slug,
+    name,
+    mode,
+    files: createdFiles,
+    directories: createdDirs,
+    total: createdFiles.length + createdDirs.length
+  };
+}
+
+module.exports = { scaffoldSquad };