@ijfw/memory-server 1.4.3 → 1.5.0

package/src/orchestrator/post-done-runner.js

@@ -0,0 +1,249 @@
+/**
+ * post-done-runner.js — v1.5.0-major S02: enforced post-DONE pipeline.
+ *
+ * Runs after a subagent's DONE has been verified by runtime-loop.js. Wraps
+ * reviewTask (v1.4.4 N3 two-stage review) and checkVerificationGate
+ * (v1.4.4 N5) into a single callable the orchestrator-LLM invokes via MCP,
+ * so the post-DONE contract isn't satisfied by markdown prose.
+ *
+ * v1.5.0 T13: the standalone `ijfw_subagent_post_done` MCP tool was retired and
+ * absorbed into the single `ijfw_state` MCP tool as the `subagent.post-done`
+ * verb (see STATE-SDK-CONTRACT §7). `runSelfCheck` is re-exported through
+ * `state-sdk.js` for that verb; `runPostDone` is still exported here for the
+ * direct-import test path (`test-orchestrator-post-done-runner.js`).
+ *
+ * Outcome shape (uniform regardless of branch taken):
+ *   {
+ *     verdict: 'approved' | 'spec_failed' | 'quality_failed',
+ *     reviewStage: 'spec' | 'quality',
+ *     reviewOk: boolean,
+ *     reviewFindings: string[],
+ *     gatePassed: boolean,
+ *     gateAction: 'block' | 'advise' | 'pass',
+ *     gateViolation: object | null,
+ *   }
+ *
+ * `gateAction` (W12-F/F4 — RT2-H1) tells the MCP tool handler what to do
+ * with a gate failure:
+ *   - 'pass'   → gate passed; advance normally.
+ *   - 'block'  → strict mode (default) AND gate failed. Caller MUST refuse
+ *                to claim success. The MCP handler should surface a structured
+ *                `block: true` so the orchestrator-LLM treats it as a hard stop.
+ *   - 'advise' → caller opted out of strict via `strictGate: false` AND gate
+ *                failed. Caller may proceed but should still surface the
+ *                violation so it gets routed into memory-feedback.
+ *
+ * The `dispatch` parameter is the reviewTask injected dispatcher:
+ *   (kind: 'spec-compliance'|'code-quality', ctx: object)
+ *     => Promise<{ verdict: 'PASS'|'FAIL', findings: string[] }>
+ *
+ * If `dispatch` is null/undefined we still run the gate check (the orchestrator
+ * may invoke the reviewers itself via the Agent tool); verdict becomes
+ * 'no_review' to signal that.
+ */
+
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { reviewTask } from './review.js';
+import { checkVerificationGate, recordViolation } from './verification-gate.js';
+
+/**
+ * Extract paths claimed in the report. Naive but effective: looks for
+ * "created/modified/file: <path>" plus bullet-list `- path/...` patterns.
+ * Skip lines under "Self-Check" section (don't recurse into reported self-checks).
+ */
+function extractClaimedPaths(reportText) {
+  const lines = String(reportText || '').split('\n');
+  const paths = new Set();
+  let inSelfCheck = false;
+  for (const line of lines) {
+    if (/^##\s*Self-Check/i.test(line)) { inSelfCheck = true; continue; }
+    if (inSelfCheck) continue;
+    const m = line.match(/(?:created|modified|file):\s*[`"]?([^\s`"]+)[`"]?/i);
+    if (m && m[1].includes('.')) paths.add(m[1]);
+    const m2 = line.match(/^\s*-\s+[`"]?([^\s`"]+\.\w+)[`"]?/);
+    if (m2) paths.add(m2[1]);
+  }
+  return [...paths];
+}
+
+/**
+ * Extract plausible commit SHAs (hex, 7-40 chars) from the report.
+ */
+function extractClaimedCommits(reportText) {
+  const matches = String(reportText || '').match(/\b[0-9a-f]{7,40}\b/g) || [];
+  return [...new Set(matches.filter((s) => /^[0-9a-f]+$/.test(s) && s.length >= 7))];
+}
+
+/**
+ * runSelfCheck — verify claimed files + commits actually exist before review.
+ * @param {string} reportText
+ * @param {string} projectRoot
+ * @returns {{
+ *   verdict: 'PASSED'|'FAILED',
+ *   files_claimed: number,
+ *   files_present: number,
+ *   files_missing: string[],
+ *   commits_claimed: number,
+ *   commits_present: number,
+ *   commits_missing: string[],
+ * }}
+ */
+export function runSelfCheck(reportText, projectRoot) {
+  const claimedPaths = extractClaimedPaths(reportText);
+  const claimedCommits = extractClaimedCommits(reportText);
+  const filesPresent = claimedPaths.filter((p) =>
+    existsSync(p.startsWith('/') ? p : `${projectRoot}/${p}`),
+  );
+  let commitsPresent = [];
+  try {
+    const allShas = execFileSync('git', ['log', '--all', '--format=%H'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).split('\n');
+    commitsPresent = claimedCommits.filter((c) => allShas.some((sha) => sha.startsWith(c)));
+  } catch {
+    /* not a git repo — skip commit check */
+  }
+  const verdict =
+    filesPresent.length === claimedPaths.length &&
+    commitsPresent.length === claimedCommits.length
+      ? 'PASSED'
+      : 'FAILED';
+  return {
+    verdict,
+    files_claimed: claimedPaths.length,
+    files_present: filesPresent.length,
+    files_missing: claimedPaths.filter((p) => !filesPresent.includes(p)),
+    commits_claimed: claimedCommits.length,
+    commits_present: commitsPresent.length,
+    commits_missing: claimedCommits.filter((c) => !commitsPresent.includes(c)),
+  };
+}
+
+/**
+/**
+ * @param {object} params
+ * @param {string} params.taskId
+ * @param {string} [params.taskSpec]
+ * @param {string} params.commitSha
+ * @param {string} [params.branch]
+ * @param {string} params.reportText
+ * @param {Array<{tool: string, input?: {command?: string}}>} [params.toolCallsInMessage]
+ * @param {Function|null} [params.dispatch]   Reviewer dispatcher; null = skip review
+ * @param {string} params.projectRoot
+ * @param {string} [params.projectConventions]
+ * @param {boolean} [params.strictGate=true]
+ *   W12-F/F4 — RT2-H1. When true (default) and the verification gate fails,
+ *   the result includes `gateAction: 'block'` and the MCP handler MUST refuse
+ *   to claim success. Pass `false` for legacy advisory-only behavior.
+ * @returns {Promise<{
+ *   verdict: 'approved'|'spec_failed'|'quality_failed'|'no_review',
+ *   reviewStage: 'spec'|'quality'|null,
+ *   reviewOk: boolean,
+ *   reviewFindings: string[],
+ *   gatePassed: boolean,
+ *   gateAction: 'block'|'advise'|'pass',
+ *   gateViolation: object|null,
+ *   selfCheck: {
+ *     verdict: 'PASSED'|'FAILED',
+ *     files_claimed: number,
+ *     files_present: number,
+ *     files_missing: string[],
+ *     commits_claimed: number,
+ *     commits_present: number,
+ *     commits_missing: string[],
+ *   },
+ * }>}
+ */
+export async function runPostDone({
+  taskId,
+  taskSpec = '',
+  commitSha,
+  branch = '',
+  reportText,
+  toolCallsInMessage,
+  dispatch,
+  projectRoot,
+  projectConventions = '',
+  strictGate = true,
+}) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new TypeError('runPostDone: projectRoot is required');
+  }
+  if (typeof reportText !== 'string') {
+    throw new TypeError('runPostDone: reportText must be a string');
+  }
+
+  // ---- Self-Check (S09) ------------------------------------------------
+  // Verify claimed files + commits exist before spending review tokens.
+  // Additive: doesn't gate downstream — surfaces the divergence in result.
+  const selfCheck = runSelfCheck(reportText, projectRoot);
+
+  // ---- Two-stage review (N3) -------------------------------------------
+  let reviewOk = false;
+  let reviewStage = null;
+  let reviewFindings = [];
+  let verdict = 'no_review';
+
+  if (typeof dispatch === 'function') {
+    const r = await reviewTask({
+      taskId,
+      taskSpec,
+      commitSha,
+      branch,
+      projectConventions,
+      dispatch,
+    });
+    reviewOk = !!r.ok;
+    reviewStage = r.stage ?? null;
+    reviewFindings = Array.isArray(r.findings) ? r.findings : [];
+    if (reviewOk) {
+      verdict = 'approved';
+    } else {
+      verdict = r.stage === 'spec' ? 'spec_failed' : 'quality_failed';
+    }
+  }
+
+  // ---- Verification gate (N5) ------------------------------------------
+  const gateOutcome = checkVerificationGate(
+    reportText,
+    Array.isArray(toolCallsInMessage) ? toolCallsInMessage : [],
+  );
+  if (!gateOutcome.ok) {
+    try {
+      // recordViolation signature is (violation, projectRoot) -- see verification-gate.js
+      await recordViolation(
+        { taskId, ...gateOutcome },
+        projectRoot,
+      );
+    } catch {
+      // Advisory -- never block on violation log failure (matches v1.4.4 N5 contract)
+    }
+  }
+
+  // W12-F/F4 — RT2-H1: classify the gate outcome so the caller knows whether
+  // to BLOCK (strict default + failure), ADVISE (caller opted out + failure),
+  // or PASS (gate succeeded). The MCP tool handler reads `gateAction` and
+  // surfaces a structured `block: true` to the orchestrator-LLM when 'block'.
+  let gateAction;
+  if (gateOutcome.ok) {
+    gateAction = 'pass';
+  } else if (strictGate === false) {
+    gateAction = 'advise';
+  } else {
+    gateAction = 'block';
+  }
+
+  return {
+    verdict,
+    reviewStage,
+    reviewOk,
+    reviewFindings,
+    gatePassed: gateOutcome.ok === true,
+    gateAction,
+    gateViolation: gateOutcome.ok ? null : { violation: gateOutcome.violation, claim: gateOutcome.claim },
+    selfCheck,
+  };
+}

package/src/orchestrator/review.js

@@ -0,0 +1,136 @@
+/**
+ * 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.
+ *
+ * v1.5.0 audit-MED-work-M7: optional `bothStages: true` lets callers surface
+ * code-quality findings even when the spec stage FAILs. Quality findings are
+ * downgraded to INFO severity (prefixed `[INFO]`) so the orchestrator's
+ * fail-on-block path still keys off the spec failure — but the operator
+ * gets a fuller picture of what's wrong instead of only seeing spec gaps.
+ *
+ * @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 {boolean} [params.bothStages=false]  Run quality stage even on spec FAIL (M7).
+ * @param {Function} params.dispatch           Injected reviewer dispatcher
+ *
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   stage: 'spec' | 'quality',
+ *   findings: string[],
+ *   qualityFindings?: string[]
+ * }>}
+ */
+export async function reviewTask({
+  taskId,
+  taskSpec,
+  commitSha,
+  branch,
+  projectConventions = '',
+  bothStages = false,
+  dispatch,
+}) {
+  // ------------------------------------------------------------------
+  // Stage 1: spec-compliance reviewer
+  // ------------------------------------------------------------------
+  const spec = await dispatch('spec-compliance', {
+    taskId,
+    taskSpec,
+    commitSha,
+    branch,
+  });
+
+  if (spec.verdict !== 'PASS') {
+    const base = {
+      ok: false,
+      stage: 'spec',
+      findings: spec.findings ?? [],
+    };
+
+    // M7: when bothStages is true, also fire the quality reviewer and
+    // surface its findings with an [INFO] downgrade prefix. The outer ok
+    // / stage remains 'spec' fail — quality verdict here is advisory only.
+    if (bothStages) {
+      try {
+        const quality = await dispatch('code-quality', {
+          taskId,
+          commitSha,
+          branch,
+          projectConventions,
+        });
+        const downgraded = (quality.findings ?? []).map(
+          (f) => (typeof f === 'string' && f.startsWith('[INFO] ') ? f : `[INFO] ${f}`),
+        );
+        return {
+          ...base,
+          qualityFindings: downgraded,
+        };
+      } catch {
+        // Quality dispatch failure is non-fatal when we're only running it
+        // for advisory surfacing — fall through to the spec-only result.
+      }
+    }
+
+    return base;
+  }
+
+  // ------------------------------------------------------------------
+  // Stage 2: code-quality reviewer (always after spec PASS)
+  // ------------------------------------------------------------------
+  const quality = await dispatch('code-quality', {
+    taskId,
+    commitSha,
+    branch,
+    projectConventions,
+  });
+
+  return {
+    ok: quality.verdict === 'PASS',
+    stage: 'quality',
+    findings: quality.findings ?? [],
+  };
+}