@ijfw/memory-server 1.4.3 → 1.4.4

package/src/dispatch/wave-cli.js

@@ -0,0 +1,128 @@
+/**
+ * dispatch/wave-cli.js — IJFW v1.4.4 / N9 wave-status CLI handlers.
+ *
+ * Frozen export contract (v1.4.3 dispatch module convention):
+ *   export const handlers = { '<subcommand>': async (args, ctx) => ({ ok, output?, error? }) };
+ *   export const subcommandHelp = { '<subcommand>': 'one-line description' };
+ *
+ * Subcommands owned by this module:
+ *   - wave-status [<id>|latest]
+ *   - wave-list
+ *
+ * Reads via mcp-server/src/orchestrator/wave-state.js (W10-A0). Read-only,
+ * snapshot-based per lock-in #31 — no daemon, no subscriptions.
+ */
+
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readWaveState } from '../orchestrator/wave-state.js';
+
+const WAVE_DIR_PREFIX = 'wave-';
+
+function tokenize(args) {
+  if (Array.isArray(args)) return args.filter((x) => x !== undefined && x !== null);
+  if (typeof args !== 'string') return [];
+  return args.split(/\s+/).filter(Boolean);
+}
+
+async function listWaveEntries(projectRoot) {
+  const ijfwDir = join(projectRoot, '.ijfw');
+  let entries = [];
+  try {
+    entries = await readdir(ijfwDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const waves = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory() || !ent.name.startsWith(WAVE_DIR_PREFIX)) continue;
+    const id = ent.name.slice(WAVE_DIR_PREFIX.length);
+    if (!id) continue;
+    const dir = join(ijfwDir, ent.name);
+    let mtimeMs = 0;
+    try {
+      const s = await stat(dir);
+      mtimeMs = s.mtimeMs;
+    } catch {
+      // tolerate vanished dirs
+    }
+    waves.push({ id, dir, mtimeMs });
+  }
+  return waves;
+}
+
+async function resolveLatestWaveId(projectRoot) {
+  const waves = await listWaveEntries(projectRoot);
+  if (waves.length === 0) return null;
+  waves.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return waves[0].id;
+}
+
+function renderStateForTerminal({ waveId, frontmatter, body }) {
+  const lines = [];
+  lines.push(`Wave: ${waveId}`);
+  for (const [key, val] of Object.entries(frontmatter || {})) {
+    if (key === 'wave_id') continue;
+    if (Array.isArray(val)) {
+      lines.push(`${key}: [${val.join(', ')}]`);
+    } else {
+      lines.push(`${key}: ${val}`);
+    }
+  }
+  if (body && body.trim()) {
+    lines.push('');
+    lines.push('--- notes ---');
+    lines.push(body.trim());
+  }
+  return lines.join('\n');
+}
+
+export const handlers = {
+  'wave-status': async (args, ctx) => {
+    const tokens = tokenize(args);
+    const projectRoot = (ctx && ctx.projectRoot) || process.cwd();
+    let waveId = tokens[0];
+    if (!waveId || waveId === 'latest') {
+      waveId = await resolveLatestWaveId(projectRoot);
+      if (!waveId) {
+        return { ok: false, output: 'No waves found in .ijfw/wave-*/' };
+      }
+    }
+    const state = await readWaveState(waveId, projectRoot);
+    if (!state) {
+      return { ok: false, output: `Wave ${waveId} not found` };
+    }
+    return {
+      ok: true,
+      output: renderStateForTerminal({
+        waveId,
+        frontmatter: state.frontmatter,
+        body: state.body,
+      }),
+    };
+  },
+
+  'wave-list': async (_args, ctx) => {
+    const projectRoot = (ctx && ctx.projectRoot) || process.cwd();
+    const waves = await listWaveEntries(projectRoot);
+    if (waves.length === 0) {
+      return { ok: true, output: '(no waves)' };
+    }
+    waves.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const rows = [];
+    for (const { id } of waves) {
+      const state = await readWaveState(id, projectRoot);
+      const status = state?.frontmatter?.status ?? '?';
+      const createdAt = state?.frontmatter?.created_at ?? '';
+      rows.push(`${id}\t${status}\t${createdAt}`);
+    }
+    return { ok: true, output: rows.join('\n') };
+  },
+};
+
+export const subcommandHelp = {
+  'wave-status': 'wave-status [<id>|latest] — print live state of a wave',
+  'wave-list':   'wave-list — list all known waves (newest first)',
+};

package/src/orchestrator/review.js

@@ -0,0 +1,101 @@
+/**
+ * review.js — Two-stage per-task review for the IJFW orchestrator.
+ *
+ * Stage 1: spec-compliance reviewer — confirms the diff faithfully
+ *   implements every requirement in the task spec.
+ * Stage 2: code-quality reviewer — checks correctness, security, and
+ *   project-convention adherence (runs only after Stage 1 passes).
+ *
+ * The `dispatch` parameter is injected by the caller so this module is
+ * testable without a live Agent tool. Signature:
+ *   (kind: 'spec-compliance' | 'code-quality', ctx: object)
+ *     => Promise<{ verdict: 'PASS' | 'FAIL', findings: string[] }>
+ *
+ * Landed in W10-A2 (v1.4.4 — N3).
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Maximum re-review iterations before escalation. */
+export const REVIEW_MAX_ITERATIONS = 3;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when re-review should be triggered.
+ *
+ * @param {'PASS'|'FAIL'} prevVerdict
+ * @param {number} iteration  1-based iteration count (1 = first attempt)
+ * @returns {boolean}
+ */
+export function shouldReReview(prevVerdict, iteration) {
+  return prevVerdict !== 'PASS' && iteration < REVIEW_MAX_ITERATIONS;
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Run two-stage review for a completed task.
+ *
+ * @param {object} params
+ * @param {string} params.taskId               Blackboard task ID
+ * @param {string} params.taskSpec             Full task specification text
+ * @param {string} params.commitSha            SHA of the implementer's commit
+ * @param {string} params.branch               Branch name
+ * @param {string} [params.projectConventions] CLAUDE.md / AGENTS.md excerpt
+ * @param {Function} params.dispatch           Injected reviewer dispatcher
+ *
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   stage: 'spec' | 'quality',
+ *   findings: string[]
+ * }>}
+ */
+export async function reviewTask({
+  taskId,
+  taskSpec,
+  commitSha,
+  branch,
+  projectConventions = '',
+  dispatch,
+}) {
+  // ------------------------------------------------------------------
+  // Stage 1: spec-compliance reviewer
+  // ------------------------------------------------------------------
+  const spec = await dispatch('spec-compliance', {
+    taskId,
+    taskSpec,
+    commitSha,
+    branch,
+  });
+
+  if (spec.verdict !== 'PASS') {
+    return {
+      ok: false,
+      stage: 'spec',
+      findings: spec.findings ?? [],
+    };
+  }
+
+  // ------------------------------------------------------------------
+  // Stage 2: code-quality reviewer (only runs after spec PASS)
+  // ------------------------------------------------------------------
+  const quality = await dispatch('code-quality', {
+    taskId,
+    commitSha,
+    branch,
+    projectConventions,
+  });
+
+  return {
+    ok: quality.verdict === 'PASS',
+    stage: 'quality',
+    findings: quality.findings ?? [],
+  };
+}

package/src/orchestrator/status-protocol.js

@@ -0,0 +1,168 @@
+/**
+ * status-protocol.js — 4-value agent status protocol + commit-before-report verification.
+ *
+ * Every implementer agent must end its report with:
+ *   Status: <VALUE>
+ *   Branch: <branch>
+ *   Commit: <sha>
+ *   Tests: <summary>
+ *
+ * Landed in W10-A1 (v1.4.4 N2).
+ */
+
+import { execFileSync } from 'node:child_process';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const STATUS_VALUES = Object.freeze([
+  'DONE',
+  'DONE_WITH_CONCERNS',
+  'NEEDS_CONTEXT',
+  'BLOCKED',
+]);
+
+// ---------------------------------------------------------------------------
+// ProtocolViolation
+// ---------------------------------------------------------------------------
+
+export class ProtocolViolation extends Error {
+  /**
+   * @param {string} reason  Human-readable explanation
+   * @param {string} raw     The original report text
+   */
+  constructor(reason, raw) {
+    super(reason);
+    this.name = 'ProtocolViolation';
+    this.reason = reason;
+    this.raw = raw;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// parseAgentReport
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a structured agent report into its constituent fields.
+ *
+ * Required field: `Status: <VALUE>` — throws ProtocolViolation if missing or invalid.
+ * All other fields are extracted best-effort (undefined if absent).
+ *
+ * @param {string} reportText
+ * @returns {{ status: string, commit_sha?: string, branch?: string, tests?: string,
+ *             concerns?: string, reason?: string, missing?: string, tried?: string,
+ *             raw: string }}
+ * @throws {ProtocolViolation}
+ */
+export function parseAgentReport(reportText) {
+  const raw = reportText;
+
+  const statusMatch = raw.match(/^Status:\s*(\S+)\s*$/m);
+  if (!statusMatch) {
+    throw new ProtocolViolation('missing Status: line in agent report', raw);
+  }
+  const status = statusMatch[1];
+  if (!STATUS_VALUES.includes(status)) {
+    throw new ProtocolViolation(
+      `invalid status "${status}"; expected one of ${STATUS_VALUES.join(', ')}`,
+      raw,
+    );
+  }
+
+  return {
+    status,
+    commit_sha: extract(raw, 'Commit'),
+    branch:     extract(raw, 'Branch'),
+    tests:      extract(raw, 'Tests'),
+    concerns:   extract(raw, 'Concerns'),
+    reason:     extract(raw, 'Reason'),
+    missing:    extract(raw, 'Missing'),
+    tried:      extract(raw, 'Tried'),
+    raw,
+  };
+}
+
+/** Extract a single-line field value, or undefined if absent. */
+function extract(text, field) {
+  const m = text.match(new RegExp(`^${field}:\\s*(.+?)\\s*$`, 'm'));
+  return m ? m[1] : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// verifyFreshCommit (internal)
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if the commit at `sha` was authored at or after
+ * (dispatchTimestamp - 5s tolerance).
+ *
+ * @param {string|undefined} sha
+ * @param {string|undefined} _branch  (reserved for future ref-checking)
+ * @param {number}           dispatchTimestamp  Unix seconds
+ * @param {{ projectRoot: string }} ctx
+ * @returns {boolean}
+ */
+function verifyFreshCommit(sha, _branch, dispatchTimestamp, ctx) {
+  if (!sha) return false;
+  try {
+    const out = execFileSync(
+      'git',
+      ['log', '-1', '--format=%ct', sha],
+      { cwd: ctx.projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    const commitTs = parseInt(out, 10);
+    if (!Number.isFinite(commitTs)) return false;
+    // r13-M-02: 5s window was too generous — let pre-existing commits pass as "fresh"
+    // when the orchestrator dispatched ~4s after a stale commit. 1s preserves
+    // minimal clock-skew tolerance. Future v1.5.0: verify commit is on the
+    // dispatched branch (tuple check), not just newer-than-dispatch.
+    return commitTs >= dispatchTimestamp - 1;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// handleStatus
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide the orchestrator action based on a parsed agent report.
+ *
+ * @param {{ status: string, commit_sha?: string, branch?: string, concerns?: string,
+ *           missing?: string, reason?: string, tried?: string }} parsed
+ * @param {number}  dispatchTimestamp  Unix seconds (Date.now()/1000 at dispatch)
+ * @param {{ projectRoot: string }} ctx
+ * @returns {{ action: string, [key: string]: unknown }}
+ */
+export function handleStatus(parsed, dispatchTimestamp, ctx) {
+  switch (parsed.status) {
+    case 'DONE': {
+      const fresh = verifyFreshCommit(
+        parsed.commit_sha,
+        parsed.branch,
+        dispatchTimestamp,
+        ctx,
+      );
+      if (!fresh) {
+        return { action: 'redispatch_needs_context', missing: 'commit-before-report' };
+      }
+      return { action: 'proceed_to_review', commit_sha: parsed.commit_sha };
+    }
+
+    case 'DONE_WITH_CONCERNS':
+      return { action: 'proceed_with_flag', concerns: parsed.concerns };
+
+    case 'NEEDS_CONTEXT':
+      return { action: 'redispatch_with_context', missing: parsed.missing };
+
+    case 'BLOCKED':
+      return { action: 'escalate_to_user', reason: parsed.reason, tried: parsed.tried };
+
+    default:
+      // STATUS_VALUES is exhaustive; parseAgentReport guards this.
+      throw new ProtocolViolation(`unhandled status "${parsed.status}"`, parsed.raw ?? '');
+  }
+}

package/src/orchestrator/verification-gate.js

@@ -0,0 +1,97 @@
+/**
+ * verification-gate.js — Advisory lint: detects completion claims in a
+ * message that lack fresh verification evidence (a Bash test/build call
+ * in the same message).
+ *
+ * ADVISORY ONLY — never throws, never blocks. Returns { ok: true } or
+ * { ok: false, violation: string, claim: string }.
+ *
+ * Violations are persisted to .ijfw/memory/verification-violations.jsonl
+ * so the memory-feedback system (v1.4.1 B10) can pattern-detect over time.
+ *
+ * Landed in W10-A2 (v1.4.4 — N5).
+ */
+
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Detection patterns
+// ---------------------------------------------------------------------------
+
+// r13-M-01 + r13-M-04: dropped bare `complete`, lowercase `done`, AND lowercase
+// `pass(?:es)?` — all three fired falsely on common neutral language ("not yet
+// complete", "to be done in v1.5", "pass the context"). Detection list is now:
+// protocol literal `DONE`, `completed`/`shipped` (deliberate completion verbs),
+// uppercase `PASS` (verdict literal), `✅` emoji, and explicit completion phrases
+// ("all tests pass" / "build succeeded" / "deployed" / "ready to ship").
+const COMPLETION_PATTERNS = [
+  /\b(?:DONE|completed|shipped|PASS)\b/,
+  /✅/,
+  /\b(?:all tests pass|build succeeded|deployed|ready to ship)\b/i,
+];
+
+// Bash tool calls that count as fresh verification evidence.
+const VERIFICATION_COMMAND_RE =
+  /(?:npm test|node --test|cargo test|pytest|preflight|ijfw preflight|build)/i;
+
+// ---------------------------------------------------------------------------
+// Core gate
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a message that contains a completion claim also has fresh
+ * verification evidence (a Bash tool call running tests/build).
+ *
+ * @param {string} message           Full text of the agent message.
+ * @param {Array<{tool: string, input?: {command?: string}}>} toolCallsInMessage
+ *   Tool calls that appeared in the same message turn.
+ *
+ * @returns {{ ok: true } | { ok: false, violation: string, claim: string }}
+ */
+export function checkVerificationGate(message, toolCallsInMessage) {
+  const claims = COMPLETION_PATTERNS.flatMap((p) => message.match(p) ?? []);
+  if (claims.length === 0) return { ok: true };
+
+  const verificationCalls = toolCallsInMessage.filter(
+    (t) =>
+      t.tool === 'Bash' &&
+      VERIFICATION_COMMAND_RE.test(t.input?.command ?? ''),
+  );
+
+  if (verificationCalls.length === 0) {
+    return {
+      ok: false,
+      violation: `Completion claim "${claims[0]}" without fresh verification in same message`,
+      claim: claims[0],
+    };
+  }
+
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// Violation recorder
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a violation record to .ijfw/memory/verification-violations.jsonl.
+ * Auto-creates parent directories. Advisory — errors are silently swallowed
+ * so a write failure never blocks the orchestrator.
+ *
+ * @param {{ violation: string, claim: string, [key: string]: unknown }} violation
+ * @param {string} projectRoot  Absolute path to the project root.
+ * @returns {Promise<void>}
+ */
+export async function recordViolation(violation, projectRoot) {
+  const file = join(projectRoot, '.ijfw', 'memory', 'verification-violations.jsonl');
+  try {
+    await mkdir(dirname(file), { recursive: true });
+    await appendFile(
+      file,
+      JSON.stringify({ ...violation, recorded_at: new Date().toISOString() }) + '\n',
+    );
+  } catch {
+    // Advisory — never propagate write errors.
+  }
+}