@ludecker/aaac 1.1.6 → 1.2.0

package/templates/cursor/aaac/scripts/remediation/lib/autonomous-mode.mjs

@@ -0,0 +1,63 @@
+/**
+ * Autonomous mode resolution for /remediate-app.
+ * When true, orchestrator MUST use remediation-runner + babysit (not manual chat phases).
+ */
+
+export const AUTONOMOUS_DEFAULTS = {
+  max_iterations_auto: 10,
+  satisfaction_threshold_auto: 100,
+};
+
+/**
+ * @param {string} intent
+ * @param {object} config - parsed intent config (threshold, max_iterations, …)
+ * @returns {{ autonomous: boolean, reason: string }}
+ */
+export function resolveAutonomousMode(intent, config) {
+  const text = (intent ?? "").toLowerCase();
+
+  if (/\bautonomous\b/.test(text) || /\bauto[-_]?babysit\b/.test(text)) {
+    return { autonomous: true, reason: "intent_token_autonomous" };
+  }
+  if (/\bmanual\b/.test(text) || /\bno[-_]?autonomous\b/.test(text)) {
+    return { autonomous: false, reason: "intent_token_manual" };
+  }
+  if (config.satisfaction_threshold >= AUTONOMOUS_DEFAULTS.satisfaction_threshold_auto) {
+    return {
+      autonomous: true,
+      reason: `satisfaction_threshold_${config.satisfaction_threshold}`,
+    };
+  }
+  if (config.max_iterations >= AUTONOMOUS_DEFAULTS.max_iterations_auto) {
+    return {
+      autonomous: true,
+      reason: `max_iterations_${config.max_iterations}`,
+    };
+  }
+  return { autonomous: false, reason: "default_manual_orchestrator" };
+}
+
+export function applyAutonomousToConfig(config, intent) {
+  const { autonomous, reason } = resolveAutonomousMode(intent, config);
+  return {
+    ...config,
+    autonomous,
+    autonomous_reason: reason,
+    runner_mode: autonomous ? "shell_runner_yield_watcher" : "chat_orchestrator",
+  };
+}
+
+export const BABYSIT_SKILL = ".cursor/skills/shared/remediation/babysit/SKILL.md";
+
+export function autonomousBootstrapCommands(runId, campaignId) {
+  return {
+    health: `node .cursor/aaac/scripts/remediation/runner-health-check.mjs --campaign-id ${campaignId}`,
+    cli_watch: `node .cursor/aaac/scripts/remediation/remediation-cli.mjs watch --run-id ${runId} --campaign-id ${campaignId}`,
+    cli_cursor: `node .cursor/aaac/scripts/remediation/remediation-cli.mjs cursor --run-id ${runId} --campaign-id ${campaignId}`,
+    cli_status: `node .cursor/aaac/scripts/remediation/remediation-cli.mjs status --run-id ${runId} --campaign-id ${campaignId}`,
+    yield_watcher: `node .cursor/aaac/scripts/remediation/remediation-yield-watcher.mjs --run-id ${runId} --campaign-id ${campaignId}`,
+    runner_until_yield: `node .cursor/aaac/scripts/remediation/remediation-runner.mjs --run-id ${runId} --campaign-id ${campaignId} --until-yield`,
+    runner_status: `node .cursor/aaac/scripts/remediation/remediation-runner.mjs --run-id ${runId} --campaign-id ${campaignId} --status`,
+    skill: BABYSIT_SKILL,
+  };
+}

package/templates/cursor/aaac/scripts/remediation/lib/campaign-focus.mjs

@@ -0,0 +1,87 @@
+/**
+ * Parse campaign intent into remediation focus constraints.
+ */
+import fs from "fs";
+import path from "path";
+import { campaignDir, loadCampaign } from "./runner-state.mjs";
+
+const DEFAULT_PROTECTED = [
+  "src/lib/views/hooks/useView.ts",
+  "src/lib/views/hooks/useWidgetOperations.ts",
+  "src/lib/views/hooks/useViewActionCallbacks.ts",
+  "src/lib/views/utils/LayoutSaveQueue.ts",
+  "src/operations/formula/evaluator.ts",
+  "src/operations/formula/dsl.ts",
+];
+
+export function normalizeRepoPath(p) {
+  return (p ?? "").replace(/^frontend\//, "").replace(/^\//, "").trim();
+}
+
+export function parseCampaignFocus(intent = "") {
+  const text = (intent ?? "").toLowerCase();
+  const healthFocus =
+    /health\s*functions?\s*>\s*60\s*loc/.test(text) ||
+    /functions?\s*>\s*60\s*loc/.test(text) ||
+    /focus:\s*health/.test(text) ||
+    text.includes("health functions");
+
+  return {
+    intent_raw: intent,
+    health_functions_above_60_loc: healthFocus,
+    primary_metric: healthFocus ? "functions_above_threshold" : "health_score",
+    wave_command: "fix-module",
+    defer_high_fan_in: true,
+    max_function_loc: 60,
+  };
+}
+
+export function loadProtectedPaths(campaignId) {
+  const paths = new Set(DEFAULT_PROTECTED.map(normalizeRepoPath));
+
+  for (const rel of ["artifacts/protected_paths.yaml", "dispatch-queue.yaml"]) {
+    const filePath = path.join(campaignDir(campaignId), rel);
+    if (!fs.existsSync(filePath)) continue;
+    let inProtected = false;
+    for (const line of fs.readFileSync(filePath, "utf8").split("\n")) {
+      if (line.trim() === "protected_paths:") {
+        inProtected = true;
+        continue;
+      }
+      const m = line.match(/^\s*-\s+(.+)/);
+      if (inProtected && m) paths.add(normalizeRepoPath(m[1].trim()));
+      if (inProtected && line.trim() && !line.startsWith(" ") && !m) inProtected = false;
+    }
+  }
+
+  return [...paths];
+}
+
+export function loadCampaignContext(campaignId) {
+  const campaign = loadCampaign(campaignId);
+  if (!campaign) return null;
+  return {
+    campaign,
+    focus: parseCampaignFocus(campaign.intent),
+    protected_paths: loadProtectedPaths(campaignId),
+    threshold: campaign.config?.satisfaction_threshold ?? 85,
+    max_iterations: campaign.config?.max_iterations ?? 5,
+    scope: campaign.scope ?? "frontend",
+  };
+}
+
+export function isGoalAchieved(campaign, satisfaction = null) {
+  const threshold = campaign.config?.satisfaction_threshold ?? 85;
+  const score = satisfaction?.score ?? campaign.current?.satisfaction_score ?? 0;
+  if (score < threshold) return false;
+  if (campaign.status === "complete" || campaign.status === "satisfied") return true;
+  if (satisfaction) {
+    const verifyOk =
+      satisfaction.e2e_pass !== false &&
+      satisfaction.vitest_pass !== false &&
+      satisfaction.typecheck_pass !== false &&
+      satisfaction.build_pass !== false;
+    if (!verifyOk) return false;
+  }
+  return score >= threshold;
+}

package/templates/cursor/aaac/scripts/remediation/lib/fallow-classifier.mjs

@@ -0,0 +1,190 @@
+/**
+ * Classify Fallow scan issues: true_positive | false_positive | review
+ * Bridges swarm/check-risk knowledge into remediation metrics (SSOT).
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { REPO_ROOT, readJson } from "../../run-engine/lib.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FRONTEND_ROOT = path.join(REPO_ROOT, "frontend");
+const RULES_PATH = path.join(__dirname, "..", "fallow-fp-rules.json");
+
+const ISSUE_ARRAYS = [
+  "unused_files",
+  "unused_exports",
+  "unused_types",
+  "unused_dependencies",
+  "unused_enum_members",
+  "unused_class_members",
+  "unresolved_imports",
+  "duplicate_exports",
+  "circular_dependencies",
+  "boundary_violations",
+];
+
+export function loadFpRules() {
+  return readJson(RULES_PATH, { path_globs: [], path_regex: [], issue_heuristics: {}, scoring: {} });
+}
+
+function loadFallowrcGlobs() {
+  const rc = readJson(path.join(FRONTEND_ROOT, ".fallowrc.json"), {});
+  return Array.isArray(rc.dynamicallyLoaded) ? rc.dynamicallyLoaded : [];
+}
+
+function globToRegex(glob) {
+  const normalized = glob.replace(/^frontend\//, "").replace(/^\//, "");
+  const escaped = normalized
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "§§")
+    .replace(/\*/g, "[^/]*")
+    .replace(/§§/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+
+function normalizePath(p) {
+  return (p ?? "").replace(/^frontend\//, "").replace(/^\//, "");
+}
+
+function pathMatchesGlob(filePath, glob) {
+  const norm = normalizePath(filePath);
+  const g = glob.replace(/^frontend\//, "");
+  if (g.includes("*")) return globToRegex(g).test(norm);
+  return norm === g || norm.endsWith(`/${g}`);
+}
+
+function pathMatchesAnyGlob(filePath, globs) {
+  return globs.some((g) => pathMatchesGlob(filePath, g));
+}
+
+function issueKey(category, issue) {
+  const p = normalizePath(issue.path ?? issue.file ?? "");
+  const name = issue.export_name ?? issue.name ?? issue.dependency ?? issue.symbol ?? "";
+  const line = issue.line ?? "";
+  return `${category}:${p}:${name}:${line}`;
+}
+
+function loadCampaignRegistry(campaignDir) {
+  const jsonPath = path.join(campaignDir, "fallow-false-positives.json");
+  if (fs.existsSync(jsonPath)) {
+    return readJson(jsonPath, { entries: [] });
+  }
+  return { version: 1, entries: [] };
+}
+
+function registryLookup(registry, key, filePath, exportName) {
+  for (const entry of registry.entries ?? []) {
+    if (entry.id === key) return entry;
+    if (entry.path && normalizePath(entry.path) === normalizePath(filePath)) {
+      if (!entry.export_name || entry.export_name === exportName) return entry;
+    }
+  }
+  return null;
+}
+
+function classifyByRules(category, issue, rules, dynamicGlobs) {
+  const filePath = normalizePath(issue.path ?? issue.file ?? "");
+
+  for (const rule of rules.path_globs ?? []) {
+    const globs =
+      rule.glob === "from_fallowrc_dynamicallyLoaded" ? dynamicGlobs : [rule.glob];
+    if (pathMatchesAnyGlob(filePath, globs)) {
+      return { classification: rule.classification, reason: rule.reason, rule_id: rule.id };
+    }
+  }
+
+  for (const rule of rules.path_regex ?? []) {
+    if (new RegExp(rule.pattern).test(filePath)) {
+      return { classification: rule.classification, reason: rule.reason, rule_id: rule.id };
+    }
+  }
+
+  const heuristics = rules.issue_heuristics?.[category] ?? [];
+  for (const h of heuristics) {
+    if (h.path_suffix && !filePath.endsWith(h.path_suffix.replace(/^\//, ""))) continue;
+    if (h.is_re_export != null && issue.is_re_export !== h.is_re_export) continue;
+    if (h.action_note_contains) {
+      const notes = (issue.actions ?? []).map((a) => a.note ?? "").join(" ");
+      if (!notes.includes(h.action_note_contains)) continue;
+    }
+    return { classification: h.classification, reason: h.reason, rule_id: h.id };
+  }
+
+  return { classification: "true_positive", reason: "fallow_reported_unused", rule_id: null };
+}
+
+export function classifyFallowScan({ scan, campaignDir, rules = loadFpRules() }) {
+  const dynamicGlobs = loadFallowrcGlobs();
+  const registry = campaignDir ? loadCampaignRegistry(campaignDir) : { entries: [] };
+  const inventory = [];
+  const counts = { true_positive: 0, false_positive: 0, review: 0 };
+
+  for (const category of ISSUE_ARRAYS) {
+    const items = scan[category];
+    if (!Array.isArray(items)) continue;
+
+    for (const issue of items) {
+      const key = issueKey(category, issue);
+      const filePath = normalizePath(issue.path ?? issue.file ?? "");
+      const exportName = issue.export_name ?? null;
+      const manual = registryLookup(registry, key, filePath, exportName);
+
+      let result;
+      if (manual) {
+        result = {
+          classification: manual.classification ?? "false_positive",
+          reason: manual.reason ?? "campaign_registry",
+          rule_id: manual.source ?? "manual",
+          source: "campaign_registry",
+        };
+      } else {
+        const ruled = classifyByRules(category, issue, rules, dynamicGlobs);
+        result = { ...ruled, source: "fallow-fp-rules" };
+      }
+
+      counts[result.classification] = (counts[result.classification] ?? 0) + 1;
+      inventory.push({
+        id: key,
+        category,
+        path: filePath,
+        export_name: exportName,
+        classification: result.classification,
+        reason: result.reason,
+        rule_id: result.rule_id,
+        source: result.source,
+        is_re_export: issue.is_re_export ?? null,
+      });
+    }
+  }
+
+  const rawTotal = scan.total_issues ?? scan.summary?.total_issues ?? inventory.length;
+  const actionable = (counts.true_positive ?? 0) + (counts.review ?? 0);
+  const excluded = counts.false_positive ?? 0;
+
+  return {
+    classified_at: new Date().toISOString(),
+    raw_total: rawTotal,
+    inventory_count: inventory.length,
+    counts,
+    actionable_total: actionable,
+    excluded_false_positives: excluded,
+    actionable_classifications: rules.scoring?.actionable_classifications ?? [
+      "true_positive",
+      "review",
+    ],
+    inventory,
+    summary: {
+      raw_total: rawTotal,
+      actionable_total: actionable,
+      false_positive_total: excluded,
+      review_total: counts.review ?? 0,
+      true_positive_total: counts.true_positive ?? 0,
+    },
+  };
+}
+
+export function resolveActionableBaseline(campaignDir) {
+  const p = path.join(campaignDir, "fallow-start-actionable-baseline.json");
+  return readJson(p, null);
+}

package/templates/cursor/aaac/scripts/remediation/lib/fallow-health-targets.mjs

@@ -0,0 +1,56 @@
+/**
+ * Fetch ranked Fallow health decomposition targets for wave planning.
+ */
+import { spawnSync } from "child_process";
+import path from "path";
+import { REPO_ROOT } from "../../run-engine/lib.mjs";
+import { normalizeRepoPath } from "./campaign-focus.mjs";
+
+const HIGH_FAN_IN_DEFER = new Set([
+  "src/operations/formula/evaluator.ts",
+  "src/operations/formula/dsl.ts",
+]);
+
+export function fetchHealthTargets({ scope = "frontend", limit = 12 } = {}) {
+  const cwd = scope === "frontend" ? path.join(REPO_ROOT, "frontend") : REPO_ROOT;
+  const npx = spawnSync("npx", ["fallow", "health", "--score", "--targets", "--format", "json", "--quiet"], {
+    cwd,
+    encoding: "utf8",
+  });
+
+  try {
+    const parsed = JSON.parse(npx.stdout || "{}");
+    const targets = (parsed.targets ?? []).map((t) => ({
+      ...t,
+      path: normalizeRepoPath(t.path),
+    }));
+    return {
+      score: parsed.health_score?.score ?? parsed.score ?? null,
+      targets: targets.slice(0, limit),
+    };
+  } catch {
+    return { score: null, targets: [] };
+  }
+}
+
+export function filterTargetsForWaves(targets, { protected_paths = [], defer_high_fan_in = true } = {}) {
+  const protectedSet = new Set(protected_paths.map(normalizeRepoPath));
+  return targets.filter((t) => {
+    const p = normalizeRepoPath(t.path);
+    if (protectedSet.has(p)) return false;
+    if (defer_high_fan_in && HIGH_FAN_IN_DEFER.has(p)) return false;
+    const fanIn = (t.factors ?? []).find((f) => f.metric === "fan_in")?.value;
+    if (defer_high_fan_in && fanIn != null && fanIn >= 10) return false;
+    return true;
+  });
+}
+
+export function targetToWaveIntent(target) {
+  const rec = target.recommendation ?? target.actions?.[0]?.description ?? "";
+  const filePath = normalizeRepoPath(target.path);
+  const fn = target.evidence?.complex_functions?.[0]?.name;
+  if (fn) {
+    return `Extract ${fn} from ${filePath} into focused modules; keep every function under 60 LOC; preserve exports`;
+  }
+  return `Health decompose ${filePath}: ${rec}`.slice(0, 260);
+}

package/templates/cursor/aaac/scripts/remediation/lib/fallow-metrics.mjs

@@ -0,0 +1,119 @@
+/**
+ * Shared Fallow command runners and metric summarizers for remediation campaigns.
+ */
+import { spawnSync } from "child_process";
+import path from "path";
+import { REPO_ROOT, readJson } from "../../run-engine/lib.mjs";
+import { loadRemediationConfig } from "./remediation-config.mjs";
+
+export function getScanRoot() {
+  const config = loadRemediationConfig();
+  return path.resolve(REPO_ROOT, config.scan_root ?? config.fallow_cwd ?? ".");
+}
+
+/** @deprecated use getScanRoot() */
+export const FRONTEND_ROOT = getScanRoot();
+export const FALLOW_BUFFER = 100 * 1024 * 1024;
+
+export function runFallow(subcommand, extraArgs = [], cwd = getScanRoot()) {
+  const args = [subcommand, "--format", "json", "--quiet", "--explain", ...extraArgs];
+  const result = spawnSync("fallow", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: FALLOW_BUFFER,
+  });
+
+  let payload;
+  if (result.stdout?.trim()) {
+    try {
+      payload = JSON.parse(result.stdout);
+    } catch (e) {
+      return {
+        ok: false,
+        exit_code: 2,
+        error: true,
+        message: `invalid JSON from fallow ${subcommand}: ${e.message}`,
+        payload: null,
+      };
+    }
+  } else {
+    payload = {
+      error: true,
+      message: result.stderr || `fallow ${subcommand} produced no output`,
+      exit_code: result.status,
+    };
+  }
+
+  return {
+    ok: result.status !== 2,
+    exit_code: result.status,
+    payload,
+  };
+}
+
+export function summarizeDeadCode(payload) {
+  const s = payload?.summary ?? payload?.totals ?? payload ?? {};
+  return {
+    total_issues: s.total_issues ?? payload?.total_issues ?? 0,
+    unused_files: s.unused_files ?? (payload?.unused_files?.length ?? 0),
+    unused_exports: s.unused_exports ?? (payload?.unused_exports?.length ?? 0),
+    unused_dependencies: s.unused_dependencies ?? (payload?.unused_dependencies?.length ?? 0),
+    circular_dependencies: s.circular_dependencies ?? (payload?.circular_dependencies?.length ?? 0),
+    unresolved_imports: s.unresolved_imports ?? (payload?.unresolved_imports?.length ?? 0),
+    duplicate_exports: s.duplicate_exports ?? (payload?.duplicate_exports?.length ?? 0),
+    boundary_violations: s.boundary_violations ?? (payload?.boundary_violations?.length ?? 0),
+    elapsed_ms: payload?.elapsed_ms ?? null,
+  };
+}
+
+export function summarizeDupes(payload) {
+  const stats = payload?.stats ?? {};
+  return {
+    clone_groups: stats.clone_groups ?? (payload?.clone_groups?.length ?? 0),
+    clone_instances: stats.clone_instances ?? 0,
+    files_with_clones: stats.files_with_clones ?? 0,
+    total_files: stats.total_files ?? 0,
+    duplicated_lines: stats.duplicated_lines ?? 0,
+    duplicated_tokens: stats.duplicated_tokens ?? 0,
+    duplication_percentage: stats.duplication_percentage ?? 0,
+    elapsed_ms: payload?.elapsed_ms ?? null,
+  };
+}
+
+export function summarizeHealth(payload) {
+  const summary = payload?.summary ?? {};
+  const healthScore = payload?.health_score ?? {};
+  return {
+    health_score: healthScore.score ?? null,
+    health_grade: healthScore.grade ?? null,
+    functions_analyzed: summary.functions_analyzed ?? 0,
+    functions_above_threshold: summary.functions_above_threshold ?? 0,
+    severity_critical_count: summary.severity_critical_count ?? 0,
+    severity_high_count: summary.severity_high_count ?? 0,
+    severity_moderate_count: summary.severity_moderate_count ?? 0,
+    findings_count: Array.isArray(payload?.findings) ? payload.findings.length : 0,
+    hotspots_count: Array.isArray(payload?.hotspots) ? payload.hotspots.length : 0,
+    elapsed_ms: payload?.elapsed_ms ?? null,
+  };
+}
+
+/** Lower-is-better metric: fraction reduced vs baseline (0–1). */
+export function reductionRate(baseline, current) {
+  if (baseline == null || current == null) return null;
+  if (baseline <= 0) return current <= 0 ? 1 : 0;
+  return Math.max(0, Math.min(1, (baseline - current) / baseline));
+}
+
+/** Higher-is-better score on 0–100 scale: fraction of remaining headroom gained. */
+export function improvementRate(baselineScore, currentScore, ceiling = 100) {
+  if (baselineScore == null || currentScore == null) return null;
+  const headroom = ceiling - baselineScore;
+  if (headroom <= 0) return currentScore >= ceiling ? 1 : 0;
+  return Math.max(0, Math.min(1, (currentScore - baselineScore) / headroom));
+}
+
+export function readStartBaseline(campaignDir, filename, field) {
+  const data = readJson(path.join(campaignDir, filename), null);
+  if (data?.[field] != null) return { value: data[field], source: filename, record: data };
+  return { value: null, source: "none", record: data };
+}

package/templates/cursor/aaac/scripts/remediation/lib/invoke-cursor-agent.mjs

@@ -0,0 +1,51 @@
+/**
+ * Invoke Cursor Agent non-interactively for yield handling.
+ */
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { REPO_ROOT, isoNow } from "../../run-engine/lib.mjs";
+
+const DEFAULT_CURSOR_BIN = "/Applications/Cursor.app/Contents/Resources/app/bin/cursor";
+
+export function resolveCursorBin() {
+  if (process.env.CURSOR_AGENT_BIN && fs.existsSync(process.env.CURSOR_AGENT_BIN)) {
+    return process.env.CURSOR_AGENT_BIN;
+  }
+  if (fs.existsSync(DEFAULT_CURSOR_BIN)) return DEFAULT_CURSOR_BIN;
+  const which = spawnSync("which", ["cursor"], { encoding: "utf8" });
+  if (which.status === 0 && which.stdout.trim()) return which.stdout.trim();
+  return null;
+}
+
+export function invokeCursorAgent(prompt, opts = {}) {
+  const bin = resolveCursorBin();
+  if (!bin) {
+    return { ok: false, status: 127, stdout: "", stderr: "cursor agent binary not found" };
+  }
+
+  const cwd = opts.cwd ?? REPO_ROOT;
+  const timeoutMs = opts.timeoutMs ?? 900_000;
+  const result = spawnSync(bin, ["agent", "-p", "-f", "--approve-mcps", "--output-format", "text", prompt], {
+    cwd,
+    encoding: "utf8",
+    timeout: timeoutMs,
+    env: { ...process.env, CI: process.env.CI ?? "1" },
+    maxBuffer: 20 * 1024 * 1024,
+  });
+
+  if (opts.logPath) {
+    fs.mkdirSync(path.dirname(opts.logPath), { recursive: true });
+    fs.writeFileSync(
+      opts.logPath,
+      `# Cursor agent ${isoNow()}\n\n## Prompt\n${prompt}\n\n## Exit ${result.status}\n\n## Stdout\n${result.stdout ?? ""}\n\n## Stderr\n${result.stderr ?? ""}\n`,
+    );
+  }
+
+  return {
+    ok: (result.status ?? 1) === 0,
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}

package/templates/cursor/aaac/scripts/remediation/lib/reconcile-run-manifest.mjs

@@ -0,0 +1,41 @@
+/**
+ * Reconcile AAAC run manifest pending queue with remediation runner state.
+ * Prevents advance-phase from jumping to report when pending was drained by a prior chat session.
+ */
+import path from "path";
+import { isoNow, loadRunManifest, runDir, writeJson } from "../../run-engine/lib.mjs";
+import { PHASES } from "./runner-state.mjs";
+
+export function phasesFrom(phase) {
+  const idx = PHASES.indexOf(phase);
+  if (idx < 0) return [...PHASES];
+  return PHASES.slice(idx);
+}
+
+export function reconcileRemediationRun(runId, runnerState) {
+  const manifestPath = path.join(runDir(runId), "run.json");
+  const manifest = loadRunManifest(runId);
+  if (!manifest || manifest.command !== "remediate-app") {
+    return { ok: false, reason: "not_remediate_run" };
+  }
+
+  const targetPhase = runnerState?.phase ?? manifest.phase ?? "scan";
+  const pending = phasesFrom(targetPhase);
+
+  manifest.phase = targetPhase;
+  manifest.pending = pending.slice(1);
+  manifest.status = "running";
+  manifest.campaign_iteration = runnerState?.iteration ?? manifest.campaign_iteration;
+  manifest.updated_at = isoNow();
+  manifest.swarm = manifest.swarm ?? {};
+  manifest.swarm.task_launches_this_phase = 0;
+  manifest.swarm.phase = targetPhase;
+
+  writeJson(manifestPath, manifest);
+  return {
+    ok: true,
+    phase: targetPhase,
+    pending: manifest.pending,
+    iteration: manifest.campaign_iteration,
+  };
+}

package/templates/cursor/aaac/scripts/remediation/lib/regression-analysis.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Compare verify metrics: campaign baseline vs pre-wave vs current.
+ */
+import { readJson } from "../../run-engine/lib.mjs";
+
+const LAYER_KEYS = ["typecheck", "vitest", "go_test", "build", "playwright"];
+
+function layerCount(snapshot, layer) {
+  if (!snapshot) return 0;
+  return (
+    snapshot.metrics?.[layer]?.error_count ??
+    (snapshot.layers?.[layer]?.error_count ?? 0)
+  );
+}
+
+function layerStatus(snapshot, layer) {
+  if (!snapshot) return "pass";
+  return snapshot.metrics?.[layer]?.status ?? snapshot.layers?.[layer]?.status ?? "pass";
+}
+
+export function analyzeRegression({ current, preWave, campaignBaseline }) {
+  const deltas = {};
+  const introduced = {};
+  let introducedRegression = false;
+
+  for (const layer of LAYER_KEYS) {
+    const cur = layerCount(current, layer);
+    const pre = layerCount(preWave, layer);
+    const base = layerCount(campaignBaseline, layer);
+    const deltaPre = cur - pre;
+    const deltaBase = cur - base;
+    deltas[layer] = { current: cur, pre_wave: pre, campaign_baseline: base, delta_pre_wave: deltaPre, delta_baseline: deltaBase };
+    introduced[layer] = deltaPre > 0 || (layerStatus(current, layer) === "fail" && layerStatus(preWave, layer) === "pass" && cur > 0);
+    if (introduced[layer]) introducedRegression = true;
+  }
+
+  const debtRemaining = LAYER_KEYS.some((l) => layerCount(current, l) > 0 || layerStatus(current, l) === "fail");
+  const strictPass = current?.status === "pass" && (current?.metrics?.total_errors ?? 0) === 0;
+
+  return {
+    introduced_regression: introducedRegression,
+    introduced_layers: Object.entries(introduced).filter(([, v]) => v).map(([k]) => k),
+    deltas,
+    debt_remaining: debtRemaining,
+    strict_pass: strictPass,
+    total_errors: current?.metrics?.total_errors ?? 0,
+    total_errors_baseline: campaignBaseline?.metrics?.total_errors ?? layerCount(campaignBaseline, "typecheck"),
+  };
+}
+
+export function loadSnapshot(path) {
+  if (!path) return null;
+  return readJson(path, null);
+}