@ijfw/memory-server 1.4.3 → 1.4.4

package/src/orchestrator/wave-state.js

@@ -0,0 +1,255 @@
+/**
+ * wave-state.js — Atomic STATE.md read/write for orchestrator wave tracking.
+ *
+ * STATE.md lives at <projectRoot>/.ijfw/wave-<waveId>/STATE.md.
+ * Format: YAML frontmatter (---delimited) + markdown body.
+ * Writes are atomic: withFsLock + write-to-tmp + rename.
+ *
+ * Landed in W10-A0 (v1.4.4 prelude). checkpointWave is a stub;
+ * N4 (W10-A2) will flesh out the blackboard→STATE rollup logic.
+ */
+
+import { mkdir, readFile, writeFile, rename, appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { withFsLock } from '../fs-lock.js';
+
+// ---------------------------------------------------------------------------
+// Internal YAML helpers — flat subset only (string/number/boolean/string[])
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a YAML frontmatter block (lines between the two `---` delimiters).
+ * Supports: scalar string/number/boolean values, arrays of strings (block style).
+ * Rejects nested maps with a clear error.
+ *
+ * @param {string} block  Lines between the two `---` markers (no delimiters)
+ * @returns {object}
+ */
+function parseYaml(block) {
+  const result = {};
+  const lines = block.split('\n');
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim() === '' || line.trimStart().startsWith('#')) { i++; continue; }
+
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) { i++; continue; }
+
+    const key = line.slice(0, colonIdx).trim();
+    const rest = line.slice(colonIdx + 1).trim();
+
+    if (!key) { i++; continue; }
+
+    // Detect nested map: next non-empty lines are indented key: value pairs
+    if (rest === '') {
+      // Could be array or nested map — peek ahead
+      const nextLines = [];
+      let j = i + 1;
+      while (j < lines.length && lines[j].trim() !== '' && !lines[j].match(/^\S.*:/)) {
+        nextLines.push(lines[j]);
+        j++;
+      }
+      if (nextLines.length > 0 && nextLines[0].trimStart().startsWith('- ')) {
+        // Block sequence
+        result[key] = nextLines.map((l) => l.replace(/^\s*-\s?/, ''));
+        i = j;
+        continue;
+      } else if (nextLines.length > 0) {
+        throw new Error(`wave-state: nested YAML maps are not supported (key: "${key}")`);
+      }
+      result[key] = null;
+      i++;
+      continue;
+    }
+
+    // Inline array: [a, b, c]
+    if (rest.startsWith('[')) {
+      const inner = rest.replace(/^\[/, '').replace(/\]$/, '');
+      result[key] = inner ? inner.split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, '')) : [];
+      i++;
+      continue;
+    }
+
+    // Scalar
+    if (rest === 'true') { result[key] = true; }
+    else if (rest === 'false') { result[key] = false; }
+    else if (rest === 'null' || rest === '~') { result[key] = null; }
+    else if (!Number.isNaN(Number(rest)) && rest !== '') { result[key] = Number(rest); }
+    else { result[key] = rest.replace(/^['"]|['"]$/g, ''); }
+    i++;
+  }
+  return result;
+}
+
+/**
+ * Emit a YAML frontmatter block for flat string/number/boolean/string[] values.
+ * @param {object} obj
+ * @returns {string}  (no leading/trailing `---`)
+ */
+function emitYaml(obj) {
+  const lines = [];
+  for (const [key, val] of Object.entries(obj)) {
+    if (val === null || val === undefined) {
+      lines.push(`${key}: null`);
+    } else if (Array.isArray(val)) {
+      if (val.length === 0) {
+        lines.push(`${key}: []`);
+      } else {
+        lines.push(`${key}:`);
+        for (const item of val) lines.push(`  - ${item}`);
+      }
+    } else if (typeof val === 'boolean') {
+      lines.push(`${key}: ${val}`);
+    } else if (typeof val === 'number') {
+      lines.push(`${key}: ${val}`);
+    } else if (typeof val === 'object') {
+      throw new Error(`wave-state: nested YAML objects are not supported (key: "${key}")`);
+    } else {
+      lines.push(`${key}: ${val}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+function wavePaths(waveId, projectRoot) {
+  const dir = join(projectRoot, '.ijfw', `wave-${waveId}`);
+  return {
+    dir,
+    state: join(dir, 'STATE.md'),
+    summary: join(dir, 'SUMMARY.md'),
+    lock: join(dir, '.STATE.md.lock'),
+    summaryLock: join(dir, '.SUMMARY.md.lock'),
+    tmp: join(dir, '.STATE.md.tmp'),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a wave's STATE.md and return parsed { frontmatter, body, raw }.
+ * Returns null if the wave directory or file doesn't exist.
+ * Throws on malformed frontmatter.
+ *
+ * @param {string} waveId       e.g. "W10-A0"
+ * @param {string} projectRoot  absolute path to project root
+ * @returns {Promise<{frontmatter: object, body: string, raw: string} | null>}
+ */
+export async function readWaveState(waveId, projectRoot) {
+  const { state } = wavePaths(waveId, projectRoot);
+  let raw;
+  try {
+    raw = await readFile(state, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+
+  // Parse frontmatter
+  if (!raw.startsWith('---')) {
+    throw new Error(`wave-state: STATE.md for "${waveId}" is missing YAML frontmatter`);
+  }
+  const secondDelim = raw.indexOf('\n---', 3);
+  if (secondDelim === -1) {
+    throw new Error(`wave-state: STATE.md for "${waveId}" has unclosed YAML frontmatter`);
+  }
+  const fmBlock = raw.slice(4, secondDelim); // skip "---\n"
+  const body = raw.slice(secondDelim + 4).replace(/^\n+/, ''); // skip "\n---\n\n"
+
+  const frontmatter = parseYaml(fmBlock);
+  return { frontmatter, body, raw };
+}
+
+/**
+ * Atomically write a wave's STATE.md using withFsLock + tmp+rename.
+ * Auto-creates .ijfw/wave-<waveId>/ if missing.
+ *
+ * @param {string} waveId
+ * @param {{frontmatter: object, body: string}} state
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+export async function writeWaveState(waveId, state, projectRoot) {
+  const { dir, state: statePath, lock, tmp } = wavePaths(waveId, projectRoot);
+  const payload = `---\n${emitYaml(state.frontmatter)}\n---\n\n${state.body}`;
+
+  await withFsLock(lock, async () => {
+    await mkdir(dir, { recursive: true });
+    await writeFile(tmp, payload, 'utf8');
+    await rename(tmp, statePath);
+  });
+}
+
+/**
+ * Append a delta entry to a wave's SUMMARY.md — markdown append-only log.
+ * r13-M-03 (post-Trident r13 fix): minimum-viable implementation closing the
+ * handoff §N4 promise. Full blackboard→STATE rollup remains future work for
+ * v1.5.0 (would mean reading blackboard.js claims/findings and summarising).
+ *
+ * Delta shape (caller chooses what to record):
+ *   { agent_id?, task_id?, commits?: string[], tests_delta?: string,
+ *     contracts_touched?: string[], surprises?: string }
+ *
+ * Atomic via withFsLock + appendFile. Each delta is rendered as a markdown
+ * H3 section dated by ISO timestamp; subsequent entries append below.
+ *
+ * @param {string} waveId
+ * @param {object} delta
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+export async function appendSummary(waveId, delta, projectRoot) {
+  const { dir, summary, summaryLock } = wavePaths(waveId, projectRoot);
+  const ts = new Date().toISOString();
+  const lines = [`### ${ts}`];
+  if (delta.agent_id) lines.push(`- **agent:** ${delta.agent_id}`);
+  if (delta.task_id) lines.push(`- **task:** ${delta.task_id}`);
+  if (Array.isArray(delta.commits) && delta.commits.length) {
+    lines.push(`- **commits:** ${delta.commits.join(', ')}`);
+  }
+  if (delta.tests_delta) lines.push(`- **tests:** ${delta.tests_delta}`);
+  if (Array.isArray(delta.contracts_touched) && delta.contracts_touched.length) {
+    lines.push(`- **contracts:** ${delta.contracts_touched.join(', ')}`);
+  }
+  if (delta.surprises) lines.push(`- **surprises:** ${delta.surprises}`);
+  const payload = lines.join('\n') + '\n\n';
+
+  await withFsLock(summaryLock, async () => {
+    await mkdir(dir, { recursive: true });
+    await appendFile(summary, payload, 'utf8');
+  });
+}
+
+/**
+ * Stub checkpoint — full blackboard→STATE rollup remains v1.5.0 work.
+ * Seeds an empty state if missing; updates only frontmatter.checkpoint_at.
+ *
+ * @param {string} waveId
+ * @param {string} projectRoot
+ * @returns {Promise<{frontmatter: object, body: string}>}
+ */
+export async function checkpointWave(waveId, projectRoot) {
+  const now = new Date().toISOString();
+  const existing = await readWaveState(waveId, projectRoot);
+
+  const next = existing
+    ? { frontmatter: { ...existing.frontmatter, checkpoint_at: now }, body: existing.body }
+    : {
+        frontmatter: {
+          wave_id: waveId,
+          status: 'in_progress',
+          created_at: now,
+          checkpoint_at: now,
+        },
+        body: '',
+      };
+
+  await writeWaveState(waveId, next, projectRoot);
+  return next;
+}

package/src/swarm-config.js

@@ -12,6 +12,9 @@ import { join } from 'node:path';
 export const SCHEMA = {
   project_type: 'string',
   specialists: [{ id: 'string', role: 'string', agent_type: 'string' }],
+  // v1.4.4 N10: auditor roster for phase-e-auto
+  auditors: ['string'],       // roster IDs to use for Cross-Audit Phase; default ['codex','gemini','claude']
+  auditor_count: 'number',    // number of lenses; default 3
 };
 
 const BASE = [
@@ -22,13 +25,20 @@ const BASE = [
 const TESTS_SPECIALIST = { id: 'tests', role: 'Test coverage', agent_type: 'pr-test-analyzer' };
 const TYPES_SPECIALIST = { id: 'types', role: 'Type invariants', agent_type: 'type-design-analyzer' };
 
+// v1.4.4 N6 — 5 specialist agents addressing v1.4.3 build pain points
+const DOC_VERIFIER     = { id: 'doc-verifier',       role: 'Doc accuracy',       agent_type: 'ijfw-doc-verifier' };
+const PATTERN_MAPPER   = { id: 'pattern-mapper',     role: 'Onboarding patterns', agent_type: 'ijfw-pattern-mapper' };
+const SECURITY_AUDITOR = { id: 'security-auditor',   role: 'Security mitigations', agent_type: 'ijfw-security-auditor' };
+const INTEGRATION_CHECKER = { id: 'integration-checker', role: 'E2E flow verification', agent_type: 'ijfw-integration-checker' };
+const NYQUIST_AUDITOR  = { id: 'nyquist-auditor',    role: 'Coverage gaps',      agent_type: 'ijfw-nyquist-auditor' };
+
 export const DEFAULT_SPECIALISTS = {
-  node:   [...BASE, TESTS_SPECIALIST],
-  python: [...BASE, TESTS_SPECIALIST],
-  typed:  [...BASE, TESTS_SPECIALIST, TYPES_SPECIALIST],
-  go:     [...BASE],
-  rust:   [...BASE],
-  other:  [...BASE],
+  node:   [...BASE, TESTS_SPECIALIST, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
+  python: [...BASE, TESTS_SPECIALIST, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
+  typed:  [...BASE, TESTS_SPECIALIST, TYPES_SPECIALIST, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
+  go:     [...BASE, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
+  rust:   [...BASE, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
+  other:  [...BASE, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
 };
 
 // Detects project type from filesystem signals in projectDir.
@@ -51,10 +61,22 @@ export function detectProjectType(projectDir) {
   return 'other';
 }
 
+// Default auditor IDs for Cross-Audit Phase (N10).
+export const DEFAULT_AUDITORS = ['codex', 'gemini', 'claude'];
+export const DEFAULT_AUDITOR_COUNT = 3;
+
+// Merge v1.4.4 N10 defaults into a raw config object (non-destructive).
+function applySwarmDefaults(config) {
+  const out = { ...config };
+  if (!Array.isArray(out.auditors)) out.auditors = [...DEFAULT_AUDITORS];
+  if (typeof out.auditor_count !== 'number' || out.auditor_count < 1) out.auditor_count = DEFAULT_AUDITOR_COUNT;
+  return out;
+}
+
 // Returns a fresh default config object for the given project type.
 function buildDefault(projectType) {
   const specialists = DEFAULT_SPECIALISTS[projectType] ?? DEFAULT_SPECIALISTS.other;
-  return { project_type: projectType, specialists: specialists.map(s => ({ ...s })) };
+  return applySwarmDefaults({ project_type: projectType, specialists: specialists.map(s => ({ ...s })) });
 }
 
 // Reads .ijfw/swarm.json if present, otherwise detects type, generates
@@ -63,7 +85,9 @@ export function loadSwarmConfig(projectDir) {
   const swarmPath = join(projectDir, '.ijfw', 'swarm.json');
 
   if (existsSync(swarmPath)) {
-    return JSON.parse(readFileSync(swarmPath, 'utf8'));
+    const raw = JSON.parse(readFileSync(swarmPath, 'utf8'));
+    // Merge defaults for v1.4.4 N10 fields so older swarm.json files work.
+    return applySwarmDefaults(raw);
   }
 
   const projectType = detectProjectType(projectDir);