@ludecker/aaac 1.1.5 → 1.2.0

package/templates/cursor/aaac/scripts/remediation/lib/remediation-config.mjs

@@ -0,0 +1,69 @@
+/**
+ * SSOT for /remediate-app project wiring — reads `.cursor/aaac/project.config.json`.
+ */
+import path from "path";
+import { REPO_ROOT, readJson } from "../../run-engine/lib.mjs";
+
+const CONFIG_PATH = path.join(REPO_ROOT, ".cursor/aaac/project.config.json");
+
+const DEFAULT_LAYERS = [
+  {
+    id: "typecheck",
+    command: "npm",
+    args: ["run", "typecheck"],
+    cwd: ".",
+    optional: true,
+  },
+  {
+    id: "vitest",
+    command: "npm",
+    args: ["test"],
+    cwd: ".",
+    optional: true,
+  },
+  {
+    id: "build",
+    command: "npm",
+    args: ["run", "build"],
+    cwd: ".",
+    optional: true,
+  },
+];
+
+export function loadRemediationConfig() {
+  const project = readJson(CONFIG_PATH, {});
+  const remediation = project.remediation ?? {};
+  const verify = remediation.verify ?? {};
+
+  const fallowCwd = remediation.fallow_cwd ?? remediation.scan_root ?? ".";
+  const scanRoot = remediation.scan_root ?? fallowCwd;
+
+  return {
+    fallow_cwd: fallowCwd,
+    scan_root: scanRoot,
+    verify: {
+      layers: Array.isArray(verify.layers) && verify.layers.length > 0 ? verify.layers : DEFAULT_LAYERS,
+      playwright: {
+        enabled: false,
+        config: null,
+        cwd: ".",
+        ...(verify.playwright ?? {}),
+      },
+      dev_server: {
+        url: "http://localhost:3000",
+        launch_hint:
+          "Start your dev server before debt sweep / Playwright gates (see project.config.json remediation.verify.dev_server).",
+        ...(verify.dev_server ?? {}),
+      },
+      strict_modes: verify.strict_modes ?? ["iteration", "strict", "debt"],
+    },
+  };
+}
+
+export function resolveLayerKeys(config = loadRemediationConfig()) {
+  const keys = config.verify.layers.map((layer) => layer.id);
+  if (config.verify.playwright?.enabled) {
+    keys.push("playwright");
+  }
+  return keys;
+}

package/templates/cursor/aaac/scripts/remediation/lib/remediation-progress.mjs

@@ -0,0 +1,58 @@
+/**
+ * Human-readable progress snapshots for remediation CLI / Cursor monitoring.
+ */
+import fs from "fs";
+import path from "path";
+import { campaignDir, loadRunnerState, loadYield } from "./runner-state.mjs";
+import { isoNow, readJson, writeJson } from "../../run-engine/lib.mjs";
+
+export function loadSatisfaction(campaignId, iteration) {
+  const p = path.join(campaignDir(campaignId), "iterations", String(iteration), "satisfaction.json");
+  return fs.existsSync(p) ? readJson(p, null) : null;
+}
+
+export function buildProgressSnapshot(campaignId, runId, extra = {}) {
+  const campaign = readJson(path.join(campaignDir(campaignId), "campaign.json"), null);
+  const runner = loadRunnerState(campaignId);
+  const yieldPayload = loadYield(campaignId);
+  const iteration = campaign?.iteration ?? runner?.iteration ?? 0;
+  const satisfaction = loadSatisfaction(campaignId, iteration);
+
+  return {
+    at: isoNow(),
+    campaign_id: campaignId,
+    run_id: runId,
+    iteration,
+    phase: runner?.phase ?? null,
+    substep: runner?.substep ?? null,
+    wave_index: runner?.wave_index ?? null,
+    runner_status: runner?.status ?? null,
+    yield_type: yieldPayload?.type ?? null,
+    satisfaction_score: satisfaction?.score ?? campaign?.current?.satisfaction_score ?? null,
+    satisfaction_threshold: campaign?.config?.satisfaction_threshold ?? null,
+    health_score: campaign?.current?.fallow_health_score ?? null,
+    clone_groups: campaign?.current?.fallow_dupes_clone_groups ?? null,
+    intent: campaign?.intent ?? null,
+    ...extra,
+  };
+}
+
+export function writeProgressArtifact(campaignId, snapshot) {
+  const out = path.join(campaignDir(campaignId), "progress.json");
+  writeJson(out, snapshot);
+  return out;
+}
+
+export function formatProgressLine(snapshot, event) {
+  const score = snapshot.satisfaction_score ?? "?";
+  const threshold = snapshot.satisfaction_threshold ?? "?";
+  const health = snapshot.health_score ?? "?";
+  const phase = [snapshot.phase, snapshot.substep].filter(Boolean).join("/") || "—";
+  const wave = snapshot.wave_index != null && snapshot.phase === "execute" ? ` wave ${snapshot.wave_index}` : "";
+  const yieldHint = snapshot.yield_type ? ` → yield ${snapshot.yield_type}` : "";
+  const eventHint = event ? ` [${event}]` : "";
+  return (
+    `[remediate] iter ${snapshot.iteration} | ${phase}${wave} | ` +
+    `score ${score}/${threshold} | health ${health}${yieldHint}${eventHint}`
+  );
+}

package/templates/cursor/aaac/scripts/remediation/lib/remediation-watch-loop.mjs

@@ -0,0 +1,168 @@
+/**
+ * Shared remediation watch loop — used by yield-watcher and remediation-cli.
+ */
+import fs from "fs";
+import path from "path";
+import { isoNow, writeJson } from "../../run-engine/lib.mjs";
+import { campaignDir, loadCampaign, saveCampaign } from "./runner-state.mjs";
+import { isGoalAchieved } from "./campaign-focus.mjs";
+import { runNode } from "./runner-exec.mjs";
+import {
+  buildProgressSnapshot,
+  formatProgressLine,
+  loadSatisfaction,
+  writeProgressArtifact,
+} from "./remediation-progress.mjs";
+
+const RUNNER = "remediation-runner.mjs";
+const HANDLE = "handle-yield.mjs";
+const HEALTH = "runner-health-check.mjs";
+
+function extendMaxIterationsIfNeeded(campaign, satisfaction) {
+  const threshold = campaign.config?.satisfaction_threshold ?? 85;
+  const score = satisfaction?.score ?? campaign.current?.satisfaction_score ?? 0;
+  if (score >= threshold) return false;
+  const iter = campaign.iteration ?? 0;
+  const max = campaign.config?.max_iterations ?? 5;
+  if (iter + 1 < max) return false;
+  campaign.config.max_iterations = max + 25;
+  campaign.status = "running";
+  saveCampaign(campaign);
+  return true;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.runId
+ * @param {string} args.campaignId
+ * @param {number} [args.pollMs]
+ * @param {number} [args.maxRetries]
+ * @param {object} [args.reporter]
+ */
+export async function runRemediationWatchLoop(args) {
+  const pollMs = args.pollMs ?? 5000;
+  const maxRetries = args.maxRetries ?? 5;
+  const reporter = args.reporter ?? {};
+  const emit = (event, detail = {}) => reporter.onEvent?.(event, detail);
+  const progress = (event, extra = {}) => {
+    const snap = buildProgressSnapshot(args.campaignId, args.runId, { event, ...extra });
+    writeProgressArtifact(args.campaignId, snap);
+    reporter.onProgress?.(snap, event);
+    return snap;
+  };
+
+  const statePath = path.join(campaignDir(args.campaignId), "watcher-state.json");
+  let watcherState = fs.existsSync(statePath)
+    ? JSON.parse(fs.readFileSync(statePath, "utf8"))
+    : { started_at: isoNow(), cycles: 0, failures: 0 };
+  watcherState.status = "running";
+  writeJson(statePath, watcherState);
+
+  emit("start", { run_id: args.runId, campaign_id: args.campaignId });
+  progress("start");
+
+  while (true) {
+    const campaign = loadCampaign(args.campaignId);
+    if (!campaign) {
+      emit("error", { message: "campaign missing" });
+      process.exit(2);
+    }
+
+    const satisfaction = loadSatisfaction(args.campaignId, campaign.iteration ?? 0);
+    if (isGoalAchieved(campaign, satisfaction)) {
+      progress("goal_achieved", { satisfaction_score: satisfaction?.score ?? campaign.current?.satisfaction_score });
+      watcherState.status = "complete";
+      watcherState.completed_at = isoNow();
+      writeJson(statePath, watcherState);
+      emit("goal_achieved");
+      return 0;
+    }
+
+    if (extendMaxIterationsIfNeeded(campaign, satisfaction)) {
+      progress("extend_max_iterations");
+    }
+
+    runNode(HEALTH, ["--campaign-id", args.campaignId]);
+    progress("health_ok");
+
+    const runner = runNode(RUNNER, [
+      "--run-id", args.runId,
+      "--campaign-id", args.campaignId,
+      "--until-yield",
+    ]);
+
+    watcherState.cycles += 1;
+    writeJson(statePath, watcherState);
+
+    if (runner.status === 10) {
+      progress("runner_progressed");
+      continue;
+    }
+
+    if (runner.status === 0) {
+      progress("runner_complete");
+      watcherState.status = "complete";
+      watcherState.completed_at = isoNow();
+      writeJson(statePath, watcherState);
+      emit("runner_complete");
+      return 0;
+    }
+
+    if (runner.status === 3) {
+      const yieldType = runner.json?.yield?.type ?? "unknown";
+      progress("yield", { yield_type: yieldType });
+      emit("yield", { yield_type: yieldType, runner: runner.json });
+
+      let handled = false;
+      for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        progress("handle_start", { yield_type: yieldType, attempt });
+        const handle = runNode(HANDLE, ["--run-id", args.runId, "--campaign-id", args.campaignId]);
+        if (!handle.ok) {
+          emit("handle_failed", { attempt, stderr: handle.stderr.slice(0, 300) });
+          watcherState.failures += 1;
+          writeJson(statePath, watcherState);
+          progress("handle_failed", { attempt });
+          await sleep(pollMs * attempt);
+          continue;
+        }
+        const ackType = handle.json?.ack_type;
+        const ack = runNode(RUNNER, [
+          "--run-id", args.runId,
+          "--campaign-id", args.campaignId,
+          "--ack-yield", ackType,
+        ]);
+        if (ack.status === 0 || ack.status === 10 || ack.ok) {
+          handled = true;
+          progress("yield_acked", { ack_type: ackType, attempt });
+          emit("yield_acked", { ack_type: ackType, attempt });
+          break;
+        }
+        progress("ack_failed", { ack_type: ackType, attempt });
+        await sleep(pollMs);
+      }
+      if (!handled) {
+        progress("yield_stuck");
+        emit("yield_stuck");
+        await sleep(pollMs * 2);
+      }
+      continue;
+    }
+
+    if (runner.status === 1) {
+      progress("blocked");
+      emit("blocked", { stderr: runner.stderr.slice(0, 300) });
+      await sleep(pollMs * 3);
+      continue;
+    }
+
+    progress("runner_error", { exit: runner.status });
+    emit("runner_error", { exit: runner.status, stderr: runner.stderr.slice(0, 300) });
+    watcherState.failures += 1;
+    writeJson(statePath, watcherState);
+    await sleep(pollMs * 2);
+  }
+}

package/templates/cursor/aaac/scripts/remediation/lib/runner-exec.mjs

@@ -0,0 +1,156 @@
+/**
+ * Subprocess helpers for remediation runner.
+ */
+import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import fs from "fs";
+import { REPO_ROOT, isoNow, writeJson } from "../../run-engine/lib.mjs";
+import { runArtifactsDir } from "./runner-state.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCRIPTS = path.join(__dirname, "..");
+const ADVANCE = path.join(REPO_ROOT, ".cursor/aaac/scripts/run-engine/advance-phase.mjs");
+
+export function runNode(scriptName, args = [], { cwd = REPO_ROOT } = {}) {
+  const scriptPath = path.join(SCRIPTS, scriptName);
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    encoding: "utf8",
+    cwd,
+  });
+  let json = null;
+  const lines = (result.stdout ?? "").trim().split("\n").filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      json = JSON.parse(lines[i]);
+      break;
+    } catch {
+      /* continue */
+    }
+  }
+  return {
+    ok: result.status === 0,
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    json,
+  };
+}
+
+export function advancePhase(runId, completedPhase, { force = false } = {}) {
+  const args = [ADVANCE, runId, completedPhase];
+  if (force) args.push("--force");
+  const result = spawnSync(process.execPath, args, { encoding: "utf8" });
+  return {
+    ok: result.status === 0,
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+export function copyFileIfExists(src, dest) {
+  if (!fs.existsSync(src)) return false;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  return true;
+}
+
+export function writeRunArtifact(runId, rel, content) {
+  const dest = path.join(runArtifactsDir(runId), rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (typeof content === "string") {
+    fs.writeFileSync(dest, content);
+  } else {
+    writeJson(dest, content);
+  }
+  return dest;
+}
+
+export function parseDispatchQueueYaml(text) {
+  const waves = [];
+  const lines = text.split("\n");
+  let inWaves = false;
+  let current = null;
+
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+    if (line === "waves:") {
+      inWaves = true;
+      continue;
+    }
+    if (!inWaves) continue;
+    if (line.startsWith("- priority:")) {
+      if (current) waves.push(current);
+      current = { priority: Number(line.split(":")[1].trim()) };
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith("command:")) {
+      current.command = line.slice("command:".length).trim();
+    } else if (line.startsWith("intent:")) {
+      current.intent = line.slice("intent:".length).trim();
+    } else if (line.startsWith("risk:")) {
+      current.risk = line.slice("risk:".length).trim();
+    } else if (line.startsWith("est_clone_groups_delta:")) {
+      current.est_clone_groups_delta = Number(line.split(":")[1].trim());
+    } else if (line.startsWith("intent: >-")) {
+      current.intent = "";
+      current._intentBlock = true;
+    } else if (current._intentBlock && line && !line.includes(":")) {
+      current.intent = `${current.intent} ${line.trim()}`.trim();
+    } else if (line.includes(":") && !line.startsWith(" ")) {
+      current._intentBlock = false;
+    }
+  }
+  if (current) waves.push(current);
+  return waves.map((w, index) => ({
+    index,
+    priority: w.priority ?? index + 1,
+    command: w.command ?? "fix-module",
+    intent: (w.intent ?? "").trim(),
+    risk: w.risk ?? "low",
+    est_clone_groups_delta: w.est_clone_groups_delta ?? null,
+    status: "pending",
+  }));
+}
+
+export function buildPlanWavesYaml({ campaign, waves, source = "dispatch-queue.yaml" }) {
+  const header = [
+    `# Iteration ${campaign.iteration} plan waves`,
+    "",
+    `campaign_id: ${campaign.campaign_id}`,
+    `iteration: ${campaign.iteration}`,
+    `scope: ${campaign.scope ?? "whole-repo"}`,
+    `max_waves: ${campaign.config?.max_waves_per_iteration ?? 3}`,
+    `source: ${source}`,
+    "",
+    "waves:",
+  ];
+  const body = waves.flatMap((w) => [
+    `  - index: ${w.index}`,
+    `    priority: ${w.priority}`,
+    `    command: ${w.command}`,
+    `    status: pending`,
+    `    risk: ${w.risk}`,
+    w.est_clone_groups_delta != null
+      ? `    est_clone_groups_delta: ${w.est_clone_groups_delta}`
+      : null,
+    `    intent: >-`,
+    `      ${w.intent}`,
+    "",
+  ].filter(Boolean));
+  return `${header.join("\n")}\n${body.join("\n")}`;
+}
+
+export function journal(campaignId, line) {
+  const journalPath = path.join(
+    REPO_ROOT,
+    ".cursor/aaac/state/campaigns",
+    campaignId,
+    "journal.md",
+  );
+  fs.appendFileSync(journalPath, `\n${line}\n`);
+}
+
+export { isoNow };

package/templates/cursor/aaac/scripts/remediation/lib/runner-state.mjs

@@ -0,0 +1,145 @@
+/**
+ * SSOT helpers for remediation shell runner state.
+ */
+import fs from "fs";
+import path from "path";
+import {
+  REPO_ROOT,
+  isoNow,
+  readJson,
+  writeJson,
+  loadRunManifest,
+  runDir,
+} from "../../run-engine/lib.mjs";
+
+export const CAMPAIGNS_ROOT = path.join(REPO_ROOT, ".cursor/aaac/state/campaigns");
+export const RUNNER_VERSION = 1;
+
+/** Runner exit codes (documented in babysit skill + remediate-app command). */
+export const EXIT = {
+  complete: 0,
+  blocked: 1,
+  runtime_error: 2,
+  yield_agent: 3,
+  progressed: 10,
+};
+
+export const PHASES = [
+  "campaign_init",
+  "scan",
+  "check_swarm",
+  "plan_waves",
+  "execute",
+  "debt_sweep",
+  "satisfaction_gate",
+  "report",
+];
+
+export function campaignDir(campaignId) {
+  return path.join(CAMPAIGNS_ROOT, campaignId);
+}
+
+export function iterDir(campaignId, iteration) {
+  return path.join(campaignDir(campaignId), "iterations", String(iteration));
+}
+
+export function runnerStatePath(campaignId) {
+  return path.join(campaignDir(campaignId), "runner-state.json");
+}
+
+export function yieldArtifactPath(campaignId) {
+  return path.join(campaignDir(campaignId), "runner-yield.json");
+}
+
+export function loadCampaign(campaignId) {
+  return readJson(path.join(campaignDir(campaignId), "campaign.json"), null);
+}
+
+export function saveCampaign(campaign) {
+  campaign.updated_at = isoNow();
+  writeJson(path.join(campaignDir(campaign.campaign_id), "campaign.json"), campaign);
+}
+
+export function defaultRunnerState({ runId, campaignId, iteration = 0, phase = "campaign_init" }) {
+  return {
+    version: RUNNER_VERSION,
+    run_id: runId,
+    campaign_id: campaignId,
+    status: "running",
+    phase,
+    substep: null,
+    iteration,
+    wave_index: 0,
+    attempt: 1,
+    tick_count: 0,
+    stall_count: 0,
+    last_score: null,
+    last_clone_groups: null,
+    last_progress_at: isoNow(),
+    yield: null,
+    started_at: isoNow(),
+    updated_at: isoNow(),
+  };
+}
+
+export function loadRunnerState(campaignId) {
+  return readJson(runnerStatePath(campaignId), null);
+}
+
+export function saveRunnerState(state) {
+  state.updated_at = isoNow();
+  writeJson(runnerStatePath(state.campaign_id), state);
+}
+
+export function writeYield(campaignId, yieldPayload) {
+  writeJson(yieldArtifactPath(campaignId), {
+    ...yieldPayload,
+    at: isoNow(),
+  });
+}
+
+export function clearYield(campaignId) {
+  const p = yieldArtifactPath(campaignId);
+  if (fs.existsSync(p)) fs.unlinkSync(p);
+}
+
+export function loadYield(campaignId) {
+  return readJson(yieldArtifactPath(campaignId), null);
+}
+
+export function syncRunnerFromManifest(state, manifest) {
+  if (!manifest) return state;
+  state.phase = manifest.phase ?? state.phase;
+  state.iteration = manifest.campaign_iteration ?? state.iteration;
+  return state;
+}
+
+export function loadManifest(runId) {
+  return loadRunManifest(runId);
+}
+
+export function runArtifactsDir(runId) {
+  return path.join(runDir(runId), "artifacts");
+}
+
+export function emitResult(state, extra = {}) {
+  const payload = {
+    ok: true,
+    status: state.status,
+    phase: state.phase,
+    substep: state.substep,
+    iteration: state.iteration,
+    wave_index: state.wave_index,
+    attempt: state.attempt,
+    tick_count: state.tick_count,
+    yield: state.yield,
+    ...extra,
+  };
+  console.log(JSON.stringify(payload));
+  return payload;
+}
+
+export function fail(message, code = EXIT.runtime_error) {
+  console.error(message);
+  process.exit(code);
+}