@ludecker/aaac 1.1.6 → 1.2.0

package/templates/cursor/aaac/scripts/remediation/runner-health-check.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Safety checks for remediation runner + babysit loop.
+ *
+ * Exit codes:
+ *   0 — healthy
+ *   1 — stall or regression detected (babysit should investigate)
+ *   2 — missing state
+ *
+ * Usage:
+ *   node runner-health-check.mjs --campaign-id <id> [--max-stall-ticks 20] [--max-yield-minutes 120]
+ */
+import fs from "fs";
+import path from "path";
+import {
+  campaignDir,
+  iterDir,
+  loadCampaign,
+  loadRunnerState,
+  loadYield,
+  runnerStatePath,
+} from "./lib/runner-state.mjs";
+import { readStartBaseline } from "./lib/fallow-metrics.mjs";
+
+function parseArgs(argv) {
+  const out = { campaignId: null, maxStallTicks: 20, maxYieldMinutes: 120 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--campaign-id") out.campaignId = argv[++i];
+    else if (a === "--max-stall-ticks") out.maxStallTicks = Number(argv[++i]);
+    else if (a === "--max-yield-minutes") out.maxYieldMinutes = Number(argv[++i]);
+  }
+  return out;
+}
+
+function minutesSince(iso) {
+  if (!iso) return Infinity;
+  return (Date.now() - new Date(iso).getTime()) / 60_000;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("runner-health-check: --campaign-id required");
+  process.exit(2);
+}
+
+const campaign = loadCampaign(args.campaignId);
+const state = loadRunnerState(args.campaignId);
+if (!campaign || !state) {
+  console.error("Missing campaign or runner-state.json");
+  process.exit(2);
+}
+
+const issues = [];
+const warnings = [];
+
+if (state.stall_count >= args.maxStallTicks) {
+  issues.push({
+    code: "stall_ticks",
+    message: `No score/clone progress for ${state.stall_count} ticks`,
+  });
+}
+
+const yieldPayload = loadYield(args.campaignId);
+if (state.status === "yielded" && yieldPayload) {
+  const yieldAge = minutesSince(yieldPayload.at ?? state.updated_at);
+  if (yieldAge > args.maxYieldMinutes) {
+    issues.push({
+      code: "yield_timeout",
+      message: `Agent yield pending ${Math.round(yieldAge)}m (type=${yieldPayload.type})`,
+      yield: yieldPayload,
+    });
+  }
+}
+
+const cDir = campaignDir(args.campaignId);
+const dupesStart = readStartBaseline(cDir, "fallow-start-dupes-baseline.json", "clone_groups");
+const healthStart = readStartBaseline(cDir, "fallow-start-health-baseline.json", "health_score");
+const currentDupes = campaign.current?.fallow_dupes_clone_groups;
+const currentHealth = campaign.current?.fallow_health_score;
+
+if (
+  dupesStart.value != null &&
+  currentDupes != null &&
+  currentDupes > dupesStart.value * 1.05
+) {
+  issues.push({
+    code: "dupes_regression",
+    message: `Clone groups ${currentDupes} > baseline ${dupesStart.value}`,
+  });
+}
+
+if (
+  healthStart.value != null &&
+  currentHealth != null &&
+  currentHealth < healthStart.value - 2
+) {
+  issues.push({
+    code: "health_regression",
+    message: `Health ${currentHealth} dropped >2 vs baseline ${healthStart.value}`,
+  });
+}
+
+const threshold = campaign.config?.satisfaction_threshold ?? 85;
+const score = campaign.current?.satisfaction_score;
+const maxIter = campaign.config?.max_iterations ?? 5;
+if (
+  score != null &&
+  score < threshold &&
+  state.iteration >= maxIter - 1 &&
+  state.phase !== "report"
+) {
+  warnings.push({
+    code: "near_max_iterations",
+    message: `Iteration ${state.iteration}/${maxIter - 1} with score ${score}/${threshold}`,
+  });
+}
+
+if (state.status === "running" && !yieldPayload) {
+  const sinceProgress = minutesSince(state.last_progress_at);
+  if (sinceProgress > args.maxYieldMinutes && score != null && score < threshold) {
+    warnings.push({
+      code: "long_run_no_progress",
+      message: `No metric progress in ${Math.round(sinceProgress)}m`,
+    });
+  }
+}
+
+const historyPath = path.join(cDir, "satisfaction-history.yaml");
+if (fs.existsSync(historyPath)) {
+  try {
+    const raw = fs.readFileSync(historyPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed?.entries?.length >= 3) {
+      const last3 = parsed.entries.slice(-3);
+      const scores = last3.map((e) => e.score);
+      if (scores[0] === scores[1] && scores[1] === scores[2]) {
+        warnings.push({
+          code: "flat_satisfaction",
+          message: `Score flat at ${scores[2]} for 3 iterations`,
+        });
+      }
+    }
+  } catch {
+    /* ignore parse errors */
+  }
+}
+
+const healthy = issues.length === 0;
+const payload = {
+  ok: healthy,
+  campaign_id: args.campaignId,
+  runner_status: state.status,
+  phase: state.phase,
+  iteration: state.iteration,
+  score,
+  threshold,
+  issues,
+  warnings,
+  runner_state_path: runnerStatePath(args.campaignId),
+};
+
+console.log(JSON.stringify(payload, null, 2));
+process.exit(healthy ? 0 : 1);

package/templates/cursor/aaac/scripts/remediation/satisfaction-loop-gate.mjs

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+/**
+ * Enforced satisfaction loop decision — blocks premature report / run completion.
+ *
+ * Exit codes:
+ *   0 — allow report (threshold met OR max_iterations exhausted)
+ *   1 — prerequisites missing (debt sweep incomplete, verify fail)
+ *   3 — continue loop (increment iteration → scan); orchestrator MUST NOT report
+ *
+ * Usage:
+ *   node satisfaction-loop-gate.mjs --campaign-id <id> --iteration <n> \
+ *     [--run-id <run_id>] [--advance] [--recompute]
+ */
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import { readStartBaseline } from "./lib/fallow-metrics.mjs";
+import { resolveActionableBaseline } from "./lib/fallow-classifier.mjs";
+import { REPO_ROOT, isoNow, readJson, writeJson, runDir } from "../run-engine/lib.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CAMPAIGNS_ROOT = path.join(REPO_ROOT, ".cursor/aaac/state/campaigns");
+const COMPUTE_SCRIPT = path.join(__dirname, "compute-satisfaction.mjs");
+
+function parseArgs(argv) {
+  const out = {
+    campaignId: null,
+    iteration: 0,
+    runId: null,
+    advance: false,
+    recompute: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--campaign-id") out.campaignId = argv[++i];
+    else if (a === "--iteration") out.iteration = Number(argv[++i]);
+    else if (a === "--run-id") out.runId = argv[++i];
+    else if (a === "--advance") out.advance = true;
+    else if (a === "--recompute") out.recompute = true;
+  }
+  return out;
+}
+
+function campaignDir(id) {
+  return path.join(CAMPAIGNS_ROOT, id);
+}
+
+function appendJournal(campaignId, text) {
+  fs.appendFileSync(path.join(campaignDir(campaignId), "journal.md"), text);
+}
+
+function runCompute(campaignId, iteration) {
+  const result = spawnSync(
+    process.execPath,
+    [COMPUTE_SCRIPT, "--campaign-id", campaignId, "--iteration", String(iteration)],
+    { encoding: "utf8" },
+  );
+  try {
+    return JSON.parse(result.stdout.trim().split("\n").pop());
+  } catch {
+    return { ok: false, error: "compute-satisfaction parse failed", stderr: result.stderr };
+  }
+}
+
+function verifyStrictPass(iterDir) {
+  const verify =
+    readJson(path.join(iterDir, "verify-debt.json"), null) ??
+    readJson(path.join(iterDir, "verify-iteration.json"), null);
+  if (!verify) return { pass: false, reason: "missing_verify_debt" };
+  const totalErrors = verify.metrics?.total_errors ?? 0;
+  const pass =
+    verify.status === "pass" &&
+    totalErrors === 0 &&
+    verify.typecheck?.status === "pass" &&
+    verify.vitest?.status === "pass" &&
+    (verify.go_test?.status === "pass" || verify.go_test?.status === "skipped") &&
+    verify.build?.status === "pass" &&
+    verify.playwright?.status === "pass";
+  return { pass, verify, totalErrors };
+}
+
+function fallowRegression(campaign, satisfaction) {
+  const cDir = campaignDir(campaign.campaign_id);
+  const regressions = [];
+
+  const actionableBaseline = resolveActionableBaseline(cDir);
+  const startActionable =
+    actionableBaseline?.actionable_total ??
+    readJson(path.join(cDir, "fallow-start-baseline.json"), null)?.fallow_total_issues ??
+    campaign.baseline?.fallow_total_issues ??
+    null;
+  const currentActionable =
+    satisfaction.fallow_actionable_total ??
+    satisfaction.fallow_total_issues ??
+    satisfaction.fallow_raw_total ??
+    0;
+
+  if (startActionable != null && currentActionable > startActionable * 1.05) {
+    regressions.push("dead_code");
+  }
+
+  const dupesStart = readStartBaseline(cDir, "fallow-start-dupes-baseline.json", "clone_groups");
+  const currentDupes = satisfaction.fallow_dupes_clone_groups;
+  if (
+    dupesStart.value != null &&
+    currentDupes != null &&
+    currentDupes > dupesStart.value * 1.05
+  ) {
+    regressions.push("dupes");
+  }
+
+  const healthStart = readStartBaseline(cDir, "fallow-start-health-baseline.json", "health_score");
+  const currentHealth = satisfaction.fallow_health_score;
+  if (
+    healthStart.value != null &&
+    currentHealth != null &&
+    currentHealth < healthStart.value - 2
+  ) {
+    regressions.push("health");
+  }
+
+  return regressions;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("satisfaction-loop-gate: --campaign-id required");
+  process.exit(2);
+}
+
+const cDir = campaignDir(args.campaignId);
+const campaignPath = path.join(cDir, "campaign.json");
+const campaign = readJson(campaignPath, null);
+if (!campaign) {
+  console.error("satisfaction-loop-gate: campaign not found");
+  process.exit(2);
+}
+
+const iteration = args.iteration ?? campaign.iteration ?? 0;
+const iterDir = path.join(cDir, "iterations", String(iteration));
+const satisfactionPath = path.join(iterDir, "satisfaction.json");
+
+if (args.recompute || !fs.existsSync(satisfactionPath)) {
+  runCompute(args.campaignId, iteration);
+}
+
+const satisfaction = readJson(satisfactionPath, null);
+if (!satisfaction) {
+  console.error("satisfaction-loop-gate: satisfaction.json missing");
+  process.exit(2);
+}
+
+const threshold = campaign.config?.satisfaction_threshold ?? 85;
+const maxIterations = campaign.config?.max_iterations ?? 5;
+const debtSweep = campaign.debt_sweep ?? {};
+const verifyCheck = verifyStrictPass(iterDir);
+
+const violations = [];
+if (debtSweep.status !== "complete" || debtSweep.iteration !== iteration) {
+  violations.push("debt_sweep_incomplete");
+}
+if (!verifyCheck.pass) {
+  violations.push(`verify_not_strict_pass:${verifyCheck.reason ?? verifyCheck.totalErrors}`);
+}
+
+if (violations.length) {
+  const output = {
+    action: "block",
+    status: "fail",
+    violations,
+    iteration,
+    satisfaction,
+    campaign_must_continue: true,
+    message: "Debt sweep or strict verify must pass before satisfaction loop decision",
+  };
+  if (args.runId) {
+    writeJson(path.join(runDir(args.runId), "artifacts", "satisfaction_loop_gate.json"), output);
+  }
+  console.log(JSON.stringify(output));
+  process.exit(1);
+}
+
+const score = satisfaction.score ?? 0;
+const e2ePass = satisfaction.e2e_pass === true;
+const vitestPass = satisfaction.vitest_pass === true;
+const typecheckPass = satisfaction.typecheck_pass === true;
+const buildPass = satisfaction.build_pass === true;
+const regressions = fallowRegression(campaign, satisfaction);
+const regressed = regressions.length > 0;
+
+const allVerifyPass = e2ePass && vitestPass && typecheckPass && buildPass;
+const thresholdMet = score >= threshold && allVerifyPass && !regressed;
+const maxIterationsReached = iteration + 1 >= maxIterations;
+
+if (thresholdMet) {
+  campaign.status = "satisfied";
+  campaign.updated_at = isoNow();
+  writeJson(campaignPath, campaign);
+
+  const output = {
+    action: "complete",
+    status: "pass",
+    reason: "satisfaction_threshold_met",
+    iteration,
+    score,
+    threshold,
+    allow_report: true,
+    campaign_must_continue: false,
+    fallow_regressions: regressions,
+  };
+  appendJournal(
+    args.campaignId,
+    `- Satisfaction loop **COMPLETE** iter ${iteration} — score ${score} >= ${threshold}\n`,
+  );
+  if (args.runId) {
+    writeJson(path.join(runDir(args.runId), "artifacts", "satisfaction_loop_gate.json"), output);
+  }
+  console.log(JSON.stringify(output));
+  process.exit(0);
+}
+
+if (maxIterationsReached) {
+  campaign.status = "running";
+  campaign.updated_at = isoNow();
+  writeJson(campaignPath, campaign);
+
+  const output = {
+    action: "partial_complete",
+    status: "pass",
+    reason: "max_iterations_reached",
+    iteration,
+    score,
+    threshold,
+    allow_report: true,
+    campaign_must_continue: false,
+    message: `Max iterations (${maxIterations}) reached with score ${score}/${threshold}`,
+  };
+  appendJournal(
+    args.campaignId,
+    `- Satisfaction loop **PARTIAL** — max_iterations=${maxIterations}, score ${score}/${threshold}\n`,
+  );
+  if (args.runId) {
+    writeJson(path.join(runDir(args.runId), "artifacts", "satisfaction_loop_gate.json"), output);
+  }
+  console.log(JSON.stringify(output));
+  process.exit(0);
+}
+
+const nextIteration = iteration + 1;
+if (args.advance) {
+  campaign.iteration = nextIteration;
+  campaign.debt_sweep = { status: "pending", iteration: null };
+  campaign.status = "running";
+  campaign.updated_at = isoNow();
+  writeJson(campaignPath, campaign);
+  appendJournal(
+    args.campaignId,
+    `- Satisfaction loop **CONTINUE** — iter ${iteration} score ${score}/${threshold} → iteration ${nextIteration}\n`,
+  );
+}
+
+const output = {
+  action: "continue_loop",
+  status: "fail",
+  reason: "below_satisfaction_threshold",
+  iteration,
+  next_iteration: nextIteration,
+  score,
+  threshold,
+  max_iterations: maxIterations,
+  allow_report: false,
+  campaign_must_continue: true,
+  orchestrator_must_not_stop: true,
+  orchestrator_must_not_report: true,
+  retry_command: `node .cursor/aaac/scripts/remediation/satisfaction-loop-gate.mjs --campaign-id ${args.campaignId} --iteration ${nextIteration}${args.runId ? ` --run-id ${args.runId}` : ""} --advance --recompute`,
+  next_phase: "scan",
+  message: `Score ${score} < ${threshold} with ${maxIterations - nextIteration} iteration(s) remaining — return to scan`,
+};
+
+if (args.runId) {
+  writeJson(path.join(runDir(args.runId), "artifacts", "satisfaction_loop_gate.json"), output);
+}
+
+console.log(JSON.stringify(output));
+process.exit(3);

package/templates/cursor/aaac/scripts/remediation/validate-campaign-complete.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Hard invariants before remediate-app may advance to report / complete.
+ *
+ * Exit 0 — safe to report (or loop iteration with partial satisfaction)
+ * Exit 1 — blocked with reasons (orchestrator must NOT complete run)
+ *
+ * Usage:
+ *   node validate-campaign-complete.mjs --campaign-id <id> [--iteration <n>] \
+ *     [--require-debt-sweep] [--require-satisfaction-loop]
+ */
+import fs from "fs";
+import path from "path";
+import { REPO_ROOT, readJson } from "../run-engine/lib.mjs";
+
+const CAMPAIGNS_ROOT = path.join(REPO_ROOT, ".cursor/aaac/state/campaigns");
+
+function parseArgs(argv) {
+  const out = { campaignId: null, iteration: null, requireDebtSweep: false, requireSatisfactionLoop: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--campaign-id") out.campaignId = argv[++i];
+    else if (a === "--iteration") out.iteration = Number(argv[++i]);
+    else if (a === "--require-debt-sweep") out.requireDebtSweep = true;
+    else if (a === "--require-satisfaction-loop") out.requireSatisfactionLoop = true;
+  }
+  return out;
+}
+
+function iterDir(campaignId, n) {
+  return path.join(CAMPAIGNS_ROOT, campaignId, "iterations", String(n));
+}
+
+function checkRemediatorLoops(iterationPath) {
+  const violations = [];
+  if (!fs.existsSync(iterationPath)) return violations;
+  for (const name of fs.readdirSync(iterationPath)) {
+    if (!name.startsWith("remediator-loop-") || !name.endsWith(".json")) continue;
+    const state = readJson(path.join(iterationPath, name), {});
+    if (state.status === "running") {
+      violations.push(`remediator_loop_running:${name}`);
+    }
+  }
+  return violations;
+}
+
+function checkPlannedWaves(campaignId, iteration, runArtifactsDir) {
+  const violations = [];
+  const planPath = runArtifactsDir
+    ? path.join(runArtifactsDir, "plan_waves.yaml")
+    : null;
+  const executePath = runArtifactsDir
+    ? path.join(runArtifactsDir, "execute_waves.yaml")
+    : null;
+
+  let plannedCount = null;
+  if (planPath && fs.existsSync(planPath)) {
+    const text = fs.readFileSync(planPath, "utf8");
+    const matches = text.match(/^\s*-\s+priority:/gm);
+    plannedCount = matches?.length ?? 0;
+  }
+
+  if (executePath && fs.existsSync(executePath)) {
+    const executed = readJson(executePath.replace(/\.yaml$/, ".json"), null);
+    if (executed?.waves) {
+      const incomplete = executed.waves.filter(
+        (w) => !["completed", "degraded", "deferred", "promoted"].includes(w.status),
+      );
+      if (incomplete.length) {
+        violations.push(`waves_not_executed:${incomplete.map((w) => w.wave_index).join(",")}`);
+      }
+    }
+  } else if (plannedCount != null && plannedCount > 0) {
+    violations.push("execute_waves_artifact_missing");
+  }
+
+  const loopFiles = fs.existsSync(iterDir(campaignId, iteration))
+    ? fs.readdirSync(iterDir(campaignId, iteration)).filter((n) => n.startsWith("remediator-loop-wave-"))
+    : [];
+  if (plannedCount != null && loopFiles.length < plannedCount) {
+    violations.push(`wave_gates_incomplete:${loopFiles.length}/${plannedCount}`);
+  }
+
+  return violations;
+}
+
+function checkDebtSweep(campaign, iteration) {
+  const violations = [];
+  const sweep = campaign.debt_sweep;
+  if (!sweep || sweep.status !== "complete") {
+    violations.push("debt_sweep_incomplete");
+  } else if (sweep.iteration != null && sweep.iteration < iteration) {
+    violations.push("debt_sweep_stale_for_iteration");
+  }
+
+  const sweepState = readJson(path.join(iterDir(campaign.campaign_id, iteration), "debt-sweep-state.json"), null);
+  if (sweepState?.status === "running") {
+    violations.push("debt_sweep_running");
+  }
+
+  const verifyDebt = readJson(path.join(iterDir(campaign.campaign_id, iteration), "verify-debt.json"), null);
+  if (verifyDebt && (verifyDebt.status !== "pass" || (verifyDebt.metrics?.total_errors ?? 0) > 0)) {
+    violations.push(`verify_debt_errors:${verifyDebt.metrics?.total_errors ?? "unknown"}`);
+  }
+
+  return violations;
+}
+
+function checkSatisfactionLoop(campaign, iteration, runArtifactsDir) {
+  const violations = [];
+  const gatePath = runArtifactsDir
+    ? path.join(runArtifactsDir, "satisfaction_loop_gate.json")
+    : null;
+  const gate = gatePath && fs.existsSync(gatePath) ? readJson(gatePath, null) : null;
+  if (!gate) {
+    violations.push("satisfaction_loop_gate_missing");
+    return violations;
+  }
+  if (gate.action === "continue_loop" || gate.allow_report === false) {
+    violations.push(`satisfaction_loop_blocks_report:${gate.action}`);
+  }
+  if (gate.orchestrator_must_not_report === true) {
+    violations.push("satisfaction_loop_must_continue");
+  }
+  const threshold = campaign.config?.satisfaction_threshold ?? 85;
+  const maxIter = campaign.config?.max_iterations ?? 5;
+  const satisfied = gate.action === "complete" && gate.reason === "satisfaction_threshold_met";
+  const partial = gate.action === "partial_complete" && gate.reason === "max_iterations_reached";
+  if (!satisfied && !partial && iteration + 1 < maxIter) {
+    const sat = readJson(path.join(iterDir(campaign.campaign_id, iteration), "satisfaction.json"), null);
+    if (sat && sat.score < threshold) {
+      violations.push(`satisfaction_below_threshold:${sat.score}<${threshold}`);
+    }
+  }
+  return violations;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("validate-campaign-complete: --campaign-id required");
+  process.exit(2);
+}
+
+const campaign = readJson(path.join(CAMPAIGNS_ROOT, args.campaignId, "campaign.json"), null);
+if (!campaign) {
+  console.error("validate-campaign-complete: campaign not found");
+  process.exit(2);
+}
+
+const iteration = args.iteration ?? campaign.iteration ?? 0;
+const iterationPath = iterDir(args.campaignId, iteration);
+const runArtifactsDir = campaign.run_id
+  ? path.join(REPO_ROOT, ".cursor/aaac/state/runs", campaign.run_id, "artifacts")
+  : null;
+
+const violations = [
+  ...checkRemediatorLoops(iterationPath),
+  ...checkPlannedWaves(args.campaignId, iteration, runArtifactsDir),
+];
+
+if (args.requireDebtSweep) {
+  violations.push(...checkDebtSweep(campaign, iteration));
+}
+
+if (args.requireSatisfactionLoop) {
+  violations.push(...checkSatisfactionLoop(campaign, iteration, runArtifactsDir));
+}
+
+if (campaign.status === "blocked" && args.requireDebtSweep) {
+  violations.push("campaign_status_blocked");
+}
+
+const ok = violations.length === 0;
+const result = {
+  ok,
+  campaign_id: args.campaignId,
+  iteration,
+  violations,
+  invariants: {
+    no_running_remediator_loops: !violations.some((v) => v.startsWith("remediator_loop_running")),
+    all_waves_gated: !violations.some((v) => v.startsWith("wave_gates_incomplete") || v.startsWith("waves_not_executed")),
+    debt_sweep_complete: args.requireDebtSweep ? !violations.some((v) => v.includes("debt_sweep")) : null,
+    no_remaining_verify_errors: args.requireDebtSweep ? !violations.some((v) => v.startsWith("verify_debt")) : null,
+    satisfaction_loop_allows_report: args.requireSatisfactionLoop
+      ? !violations.some((v) => v.startsWith("satisfaction_loop"))
+      : null,
+  },
+};
+
+console.log(JSON.stringify(result));
+process.exit(ok ? 0 : 1);