@ludecker/aaac 1.1.6 → 1.2.0

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

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * Shared verify execution + metric extraction for remediation campaigns.
+ * Layer commands come from project.config.json → remediation.verify.layers.
+ */
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { REPO_ROOT, isoNow } from "../../run-engine/lib.mjs";
+import { loadRemediationConfig, resolveLayerKeys } from "./remediation-config.mjs";
+
+export function countTypeScriptErrors(text) {
+  const matches = text.match(/error TS\d+:/g);
+  return matches ? matches.length : 0;
+}
+
+export function countVitestFailures(text) {
+  const summary = text.match(/Tests\s+\d+\s+failed\s+\((\d+)\)/);
+  if (summary) return Number(summary[1]);
+  const failedBlocks = text.match(/^\s*FAIL\s+/gm);
+  return failedBlocks ? failedBlocks.length : text.includes("FAIL") ? 1 : 0;
+}
+
+export function countGoTestFailures(text) {
+  const failLines = text.match(/^--- FAIL:/gm);
+  if (failLines) return failLines.length;
+  return text.includes("FAIL") && text.includes("go test") ? 1 : 0;
+}
+
+export function layerErrorCount(layer, step) {
+  if (!step || step.status === "skipped") return 0;
+  if (step.status === "pass") return 0;
+  const combined = `${step.stdout_full ?? step.stdout_tail ?? ""}\n${step.stderr_full ?? step.stderr_tail ?? ""}\n${step.detail ?? ""}`;
+  if (layer === "typecheck") return countTypeScriptErrors(combined);
+  if (layer === "vitest") return countVitestFailures(combined);
+  if (layer === "go_test") return countGoTestFailures(combined);
+  return 1;
+}
+
+export function runStep(name, cmd, cmdArgs, cwd, optional = false) {
+  const started = isoNow();
+  const result = spawnSync(cmd, cmdArgs, {
+    cwd: path.resolve(REPO_ROOT, cwd),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: process.env,
+    maxBuffer: 50 * 1024 * 1024,
+  });
+  const status =
+    result.status === 0 ? "pass" : optional && result.status !== 0 ? "skipped" : "fail";
+  return {
+    name,
+    status,
+    exit_code: result.status,
+    started_at: started,
+    completed_at: isoNow(),
+    stdout_full: result.stdout || "",
+    stderr_full: result.stderr || "",
+    stdout_tail: (result.stdout || "").slice(-4000),
+    stderr_tail: (result.stderr || "").slice(-4000),
+  };
+}
+
+export async function waitForDevServer(url, maxWaitSec = 30) {
+  for (let i = 0; i < maxWaitSec; i++) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+      if (res.ok) return true;
+    } catch {
+      /* retry */
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return false;
+}
+
+function runConfiguredLayer(layerDef) {
+  const name = layerDef.name ?? layerDef.id;
+  return runStep(
+    name,
+    layerDef.command,
+    layerDef.args ?? [],
+    layerDef.cwd ?? ".",
+    Boolean(layerDef.optional),
+  );
+}
+
+async function runPlaywrightLayer(config, mode) {
+  const pw = config.verify.playwright;
+  if (!pw?.enabled) {
+    return {
+      name: "playwright_remediation",
+      status: "skipped",
+      reason: "playwright disabled in project.config.json",
+    };
+  }
+  if (!config.verify.strict_modes.includes(mode)) {
+    return {
+      name: "playwright_remediation",
+      status: "skipped",
+      reason: `playwright not run for mode ${mode}`,
+    };
+  }
+
+  const pwCwd = path.resolve(REPO_ROOT, pw.cwd ?? ".");
+  const configPath = pw.config ? path.resolve(REPO_ROOT, pw.config) : null;
+  if (configPath && !fs.existsSync(configPath)) {
+    return {
+      name: "playwright_remediation",
+      status: "fail",
+      detail: `playwright config missing: ${pw.config}`,
+    };
+  }
+
+  const devUrl = config.verify.dev_server?.url;
+  const serverUp = devUrl ? await waitForDevServer(devUrl) : true;
+  if (!serverUp) {
+    return {
+      name: "playwright_remediation",
+      status: "fail",
+      detail: `dev server not reachable at ${devUrl} — ${config.verify.dev_server?.launch_hint ?? "start dev server"}`,
+    };
+  }
+
+  const playwrightCli = path.join(pwCwd, "node_modules", "@playwright", "test", "cli.js");
+  const args = configPath
+    ? [playwrightCli, "test", "-c", configPath]
+    : [playwrightCli, "test"];
+  const step = runStep("playwright_remediation", process.execPath, args, pw.cwd ?? ".");
+  step.base_url = devUrl ?? null;
+  return step;
+}
+
+export async function runVerifySteps(mode) {
+  const config = loadRemediationConfig();
+  const layerKeys = resolveLayerKeys(config);
+  const report = {
+    status: "pass",
+    mode,
+    checked_at: isoNow(),
+    metrics: {},
+  };
+
+  for (const layerDef of config.verify.layers) {
+    report[layerDef.id] = runConfiguredLayer(layerDef);
+  }
+
+  if (config.verify.playwright?.enabled) {
+    report.playwright = await runPlaywrightLayer(config, mode);
+  }
+
+  for (const key of layerKeys) {
+    const step = report[key];
+    if (step && step.status === "fail") report.status = "fail";
+    report.metrics[key] = {
+      status: step?.status ?? "skipped",
+      error_count: layerErrorCount(key, step),
+    };
+  }
+
+  report.metrics.total_errors = layerKeys.reduce(
+    (sum, k) => sum + (report.metrics[k]?.error_count ?? 0),
+    0,
+  );
+
+  return report;
+}
+
+export function writeVerifyLogs(report, logDir, prefix) {
+  fs.mkdirSync(logDir, { recursive: true });
+  const keys = Object.keys(report).filter(
+    (k) => k !== "status" && k !== "mode" && k !== "checked_at" && k !== "metrics",
+  );
+  for (const key of keys) {
+    const step = report[key];
+    if (!step || typeof step !== "object") continue;
+    const logPath = path.join(logDir, `${prefix}-${key}.log`);
+    const body = [
+      `# ${key} exit=${step.exit_code} status=${step.status}`,
+      "## stdout",
+      step.stdout_full ?? step.stdout_tail ?? "",
+      "## stderr",
+      step.stderr_full ?? step.stderr_tail ?? "",
+    ].join("\n");
+    fs.writeFileSync(logPath, body);
+    step.log_path = logPath;
+  }
+}
+
+export function summarizeMetrics(report) {
+  const keys = Object.keys(report.metrics ?? {}).filter((k) => k !== "total_errors");
+  return {
+    status: report.status,
+    total_errors: report.metrics?.total_errors ?? 0,
+    layers: Object.fromEntries(
+      keys.map((k) => [
+        k,
+        {
+          status: report.metrics?.[k]?.status ?? report[k]?.status,
+          error_count: report.metrics?.[k]?.error_count ?? 0,
+        },
+      ]),
+    ),
+  };
+}

package/templates/cursor/aaac/scripts/remediation/merge-check-swarm.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+/**
+ * Merge remediation check_swarm agent outputs → FP registry, reclassify, guardrail artifacts.
+ *
+ * Usage:
+ *   node merge-check-swarm.mjs --campaign-id <id> --iteration <n> [--run-id <run_id>]
+ *
+ * Reads iterations/{n}/check-swarm-raw.json (parent-collected agent JSON blocks).
+ */
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+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");
+
+function parseArgs(argv) {
+  const out = { campaignId: null, iteration: 0, runId: null, rawPath: null };
+  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 === "--raw") out.rawPath = argv[++i];
+  }
+  return out;
+}
+
+function normalizePath(p) {
+  return (p ?? "").replace(/^frontend\//, "").replace(/^\//, "");
+}
+
+function uniqByPath(items) {
+  const seen = new Set();
+  const out = [];
+  for (const item of items) {
+    const key = `${normalizePath(item.path)}:${item.export_name ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ ...item, path: normalizePath(item.path) });
+  }
+  return out;
+}
+
+function yamlList(items, indent = 2) {
+  const pad = " ".repeat(indent);
+  if (!items.length) return `${pad}[]\n`;
+  return items.map((i) => `${pad}- ${JSON.stringify(i)}`).join("\n") + "\n";
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("merge-check-swarm: --campaign-id required");
+  process.exit(2);
+}
+
+const campaignDir = path.join(CAMPAIGNS_ROOT, args.campaignId);
+const iterDir = path.join(campaignDir, "iterations", String(args.iteration));
+const rawPath =
+  args.rawPath ?? path.join(iterDir, "check-swarm-raw.json");
+
+if (!fs.existsSync(rawPath)) {
+  console.error(`merge-check-swarm: missing ${rawPath}`);
+  process.exit(2);
+}
+
+const raw = readJson(rawPath, { agents: [] });
+const agents = Array.isArray(raw.agents) ? raw.agents : Array.isArray(raw) ? raw : [];
+
+const falsePositives = [];
+const protectedPaths = [];
+const doNotDelete = [];
+const safeToFix = [];
+const findings = [];
+const gaps = [];
+
+for (const agent of agents) {
+  for (const fp of agent.false_positives ?? []) {
+    falsePositives.push({
+      ...fp,
+      source: agent.agent_id ?? agent.command_mirror ?? "check-swarm",
+      iteration: args.iteration,
+    });
+  }
+  for (const p of agent.protected_paths ?? []) {
+    protectedPaths.push(normalizePath(p));
+  }
+  for (const d of agent.do_not_delete ?? []) {
+    doNotDelete.push({ path: normalizePath(d.path ?? d), reason: d.reason ?? "protected" });
+  }
+  for (const s of agent.safe_to_fix ?? []) {
+    safeToFix.push({
+      path: normalizePath(s.path),
+      category: s.category ?? null,
+      export_name: s.export_name ?? null,
+      evidence: s.evidence ?? null,
+    });
+  }
+  if (Array.isArray(agent.findings)) findings.push(...agent.findings.map((f) => `[${agent.agent_id}] ${f}`));
+  if (Array.isArray(agent.gaps)) gaps.push(...agent.gaps.map((g) => `[${agent.agent_id}] ${g}`));
+}
+
+const fpDeduped = uniqByPath(falsePositives);
+const protectedDeduped = [...new Set(protectedPaths)];
+const doNotDeleteDeduped = uniqByPath(
+  doNotDelete.map((d) => ({ path: d.path, export_name: null, reason: d.reason })),
+);
+
+if (fpDeduped.length) {
+  const batchPath = path.join(iterDir, "check-swarm-fp-batch.json");
+  writeJson(batchPath, { entries: fpDeduped });
+  spawnSync(
+    process.execPath,
+    [
+      path.join(__dirname, "record-fallow-fp.mjs"),
+      "--campaign-id",
+      args.campaignId,
+      "--from-json",
+      batchPath,
+    ],
+    { encoding: "utf8" },
+  );
+}
+
+spawnSync(
+  process.execPath,
+  [
+    path.join(__dirname, "classify-fallow-issues.mjs"),
+    "--campaign-id",
+    args.campaignId,
+    "--iteration",
+    String(args.iteration),
+  ],
+  { encoding: "utf8" },
+);
+
+const classification = readJson(path.join(iterDir, "fallow-classification.json"), {});
+const context = readJson(path.join(iterDir, "check-context.json"), {});
+
+const merge = {
+  merged_at: isoNow(),
+  campaign_id: args.campaignId,
+  iteration: args.iteration,
+  agents_reported: agents.length,
+  false_positives_recorded: fpDeduped.length,
+  protected_paths: protectedDeduped,
+  do_not_delete: doNotDeleteDeduped,
+  safe_to_fix: safeToFix,
+  classification_after_merge: classification.summary ?? null,
+  findings,
+  gaps,
+};
+
+writeJson(path.join(iterDir, "check-swarm-merge.json"), merge);
+
+const checkAppAgents = agents.filter((a) => a.command_mirror === "check-app" || (a.agent_id ?? "").includes("check-app"));
+const archAgents = agents.filter(
+  (a) => a.command_mirror === "check-architecture" || (a.agent_id ?? "").includes("check-architecture"),
+);
+
+const checkAppValidate = {
+  run_id: args.runId ?? null,
+  phase: "validate",
+  command: "check-app",
+  command_mirror: true,
+  campaign_id: args.campaignId,
+  iteration: args.iteration,
+  intent: context.questions?.check_app ?? "Fallow false-positive triage for app runtime surfaces",
+  answer: checkAppAgents.some((a) => a.answer === "partial")
+    ? "partial"
+    : checkAppAgents.every((a) => a.answer === "yes")
+      ? "yes"
+      : "partial",
+  confidence: {
+    overall: checkAppAgents.length >= 3 ? 0.85 : 0.6,
+  },
+  requirements_met: [
+    "Traced Fallow review/actionable paths against app entry points and workers",
+    `Recorded ${fpDeduped.length} false-positive paths for satisfaction scoring`,
+    `Protected ${protectedDeduped.length} paths from wave deletion`,
+  ],
+  requirements_not_met: gaps.filter((g) => g.includes("check-app")),
+  protected_paths: protectedDeduped,
+  safe_to_fix_count: safeToFix.length,
+};
+
+const checkArchFitness = {
+  run_id: args.runId ?? null,
+  phase: "fitness_functions",
+  command: "check-architecture",
+  command_mirror: true,
+  campaign_id: args.campaignId,
+  iteration: args.iteration,
+  intent: context.questions?.check_architecture ?? "Fallow deletion impact on architecture",
+  answer: archAgents.some((a) => a.answer === "no") ? "no" : "partial",
+  criteria: [
+    "No wave may delete protected_paths or false_positive registry entries",
+    "Dupes consolidation must preserve main/worker SSOT pairs until shared extract exists",
+    "Boundary violations are fix targets; barrel facades default to review not delete",
+  ],
+  violations: findings.filter((f) => f.includes("boundary") || f.includes("check-architecture")),
+  protected_paths: protectedDeduped,
+};
+
+const protectedYaml = {
+  campaign_id: args.campaignId,
+  iteration: args.iteration,
+  updated_at: isoNow(),
+  protected_paths: protectedDeduped,
+  do_not_delete: doNotDeleteDeduped.map((d) => d.path),
+  false_positive_paths: fpDeduped.map((f) => f.path),
+  wave_exclude_block: protectedDeduped,
+};
+
+function writeArtifact(runId, name, data) {
+  if (!runId) return;
+  const dir = path.join(runDir(runId), "artifacts");
+  fs.mkdirSync(dir, { recursive: true });
+  const ext = name.endsWith(".yaml") ? ".yaml" : ".json";
+  if (ext === ".json") {
+    writeJson(path.join(dir, name), data);
+    return;
+  }
+  const yaml = `campaign_id: ${args.campaignId}\niteration: ${args.iteration}\nupdated_at: ${isoNow()}\n\nprotected_paths:\n${protectedDeduped.map((p) => `  - ${p}`).join("\n") || "  []"}\n\ndo_not_delete:\n${doNotDeleteDeduped.map((d) => `  - path: ${d.path}\n    reason: ${JSON.stringify(d.reason)}`).join("\n") || "  []"}\n`;
+  fs.writeFileSync(path.join(dir, name), yaml);
+}
+
+writeJson(path.join(iterDir, "protected-paths.json"), protectedYaml);
+writeJson(path.join(iterDir, "check-app-validate.json"), checkAppValidate);
+writeJson(path.join(iterDir, "check-architecture-fitness.json"), checkArchFitness);
+
+if (args.runId) {
+  const artDir = path.join(runDir(args.runId), "artifacts");
+  fs.mkdirSync(artDir, { recursive: true });
+  writeJson(path.join(artDir, "check_app_validate.yaml"), checkAppValidate);
+  writeJson(path.join(artDir, "check_architecture_fitness.yaml"), checkArchFitness);
+  writeJson(path.join(artDir, "check_swarm_merge.json"), merge);
+  const yaml = `campaign_id: ${args.campaignId}\niteration: ${args.iteration}\nupdated_at: ${isoNow()}\n\nprotected_paths:\n${protectedDeduped.map((p) => `  - ${p}`).join("\n") || "  []"}\n\ndo_not_delete:\n${doNotDeleteDeduped.map((d) => `  - path: ${d.path}\n    reason: ${JSON.stringify(d.reason)}`).join("\n") || "  []"}\n`;
+  fs.writeFileSync(path.join(artDir, "protected_paths.yaml"), yaml);
+}
+
+fs.appendFileSync(
+  path.join(campaignDir, "journal.md"),
+  `\n- **Check swarm merged** iter ${args.iteration}: agents=${agents.length}, fp_recorded=${fpDeduped.length}, protected=${protectedDeduped.length}, actionable_after=${classification.summary?.actionable_total ?? "?"}\n`,
+);
+
+console.log(
+  JSON.stringify({
+    ok: true,
+    merge_path: path.join(iterDir, "check-swarm-merge.json"),
+    false_positives_recorded: fpDeduped.length,
+    protected_paths: protectedDeduped.length,
+    actionable_total: classification.summary?.actionable_total,
+  }),
+);

package/templates/cursor/aaac/scripts/remediation/plan-waves-from-queue.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Build plan_waves.yaml from dispatch-queue.yaml (scriptable plan_waves phase).
+ *
+ * Usage:
+ *   node plan-waves-from-queue.mjs --campaign-id <id> --run-id <run_id> [--iteration <n>]
+ */
+import fs from "fs";
+import path from "path";
+import {
+  campaignDir,
+  loadCampaign,
+  runArtifactsDir,
+} from "./lib/runner-state.mjs";
+import {
+  buildPlanWavesYaml,
+  copyFileIfExists,
+  journal,
+  parseDispatchQueueYaml,
+  writeRunArtifact,
+} from "./lib/runner-exec.mjs";
+
+function parseArgs(argv) {
+  const out = { campaignId: null, runId: null, iteration: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--campaign-id") out.campaignId = argv[++i];
+    else if (a === "--run-id") out.runId = argv[++i];
+    else if (a === "--iteration") out.iteration = Number(argv[++i]);
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId || !args.runId) {
+  console.error("plan-waves-from-queue: --campaign-id and --run-id required");
+  process.exit(2);
+}
+
+const campaign = loadCampaign(args.campaignId);
+if (!campaign) {
+  console.error(`Campaign not found: ${args.campaignId}`);
+  process.exit(2);
+}
+
+const iteration = args.iteration ?? campaign.iteration;
+const queuePath = path.join(campaignDir(args.campaignId), "dispatch-queue.yaml");
+if (!fs.existsSync(queuePath)) {
+  console.error(`Missing dispatch-queue.yaml at ${queuePath}`);
+  process.exit(2);
+}
+
+const queueText = fs.readFileSync(queuePath, "utf8");
+let waves = parseDispatchQueueYaml(queueText);
+const maxWaves = campaign.config?.max_waves_per_iteration ?? 3;
+waves = waves.slice(0, maxWaves);
+
+if (waves.length === 0) {
+  console.error("dispatch-queue.yaml has no waves");
+  process.exit(2);
+}
+
+const yaml = buildPlanWavesYaml({ campaign: { ...campaign, iteration }, waves });
+const campaignPlan = path.join(campaignDir(args.campaignId), "artifacts", "plan_waves.yaml");
+const runPlan = path.join(runArtifactsDir(args.runId), "plan_waves.yaml");
+fs.mkdirSync(path.dirname(campaignPlan), { recursive: true });
+fs.writeFileSync(campaignPlan, yaml);
+fs.mkdirSync(path.dirname(runPlan), { recursive: true });
+fs.writeFileSync(runPlan, yaml);
+
+journal(
+  args.campaignId,
+  `- **Plan waves** iter ${iteration}: ${waves.length} wave(s) from dispatch-queue.yaml`,
+);
+
+console.log(
+  JSON.stringify({
+    ok: true,
+    campaign_id: args.campaignId,
+    iteration,
+    wave_count: waves.length,
+    plan_path: runPlan,
+    waves: waves.map((w) => ({ index: w.index, command: w.command, priority: w.priority })),
+  }),
+);

package/templates/cursor/aaac/scripts/remediation/prepare-check-context.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Build readonly check_swarm context from Fallow scan + classification.
+ *
+ * Usage:
+ *   node prepare-check-context.mjs --campaign-id <id> --iteration <n> [--run-id <run_id>]
+ */
+import fs from "fs";
+import path from "path";
+import { REPO_ROOT, isoNow, readJson, writeJson, runDir } from "../run-engine/lib.mjs";
+import {
+  summarizeDeadCode,
+  summarizeDupes,
+  summarizeHealth,
+} from "./lib/fallow-metrics.mjs";
+
+const CAMPAIGNS_ROOT = path.join(REPO_ROOT, ".cursor/aaac/state/campaigns");
+const FRONTEND_ROOT = path.join(REPO_ROOT, "frontend");
+
+function parseArgs(argv) {
+  const out = { campaignId: null, iteration: 0, runId: null };
+  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];
+  }
+  return out;
+}
+
+function loadLayer(iterDir, file, summarize) {
+  const p = path.join(iterDir, file);
+  if (!fs.existsSync(p)) return null;
+  const payload = readJson(p, {});
+  return payload._remediation?.summary ?? summarize(payload);
+}
+
+function topCloneGroups(dupesPayload, limit = 15) {
+  const groups = dupesPayload?.clone_groups;
+  if (!Array.isArray(groups)) return [];
+  return [...groups]
+    .sort((a, b) => (b.token_count ?? 0) - (a.token_count ?? 0))
+    .slice(0, limit)
+    .map((g) => ({
+      token_count: g.token_count,
+      line_count: g.line_count,
+      instances: (g.instances ?? []).map((i) => ({
+        file: i.file,
+        start_line: i.start_line,
+        end_line: i.end_line,
+      })),
+    }));
+}
+
+function inventoryByClassification(classification) {
+  const buckets = { true_positive: [], review: [], false_positive: [] };
+  for (const item of classification?.inventory ?? []) {
+    const bucket = buckets[item.classification] ?? buckets.review;
+    bucket.push({
+      id: item.id,
+      category: item.category,
+      path: item.path,
+      export_name: item.export_name,
+      reason: item.reason,
+      rule_id: item.rule_id,
+    });
+  }
+  return buckets;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("prepare-check-context: --campaign-id required");
+  process.exit(2);
+}
+
+const campaignDir = path.join(CAMPAIGNS_ROOT, args.campaignId);
+const iterDir = path.join(campaignDir, "iterations", String(args.iteration));
+const campaign = readJson(path.join(campaignDir, "campaign.json"), {});
+
+const deadScan = readJson(path.join(iterDir, "fallow-scan.json"), null);
+const dupesScan = readJson(path.join(iterDir, "fallow-dupes.json"), null);
+const healthScan = readJson(path.join(iterDir, "fallow-health.json"), null);
+const classification = readJson(path.join(iterDir, "fallow-classification.json"), null);
+const registry = readJson(path.join(campaignDir, "fallow-false-positives.json"), { entries: [] });
+
+if (!deadScan) {
+  console.error("prepare-check-context: fallow-scan.json missing — run fallow-scan.mjs first");
+  process.exit(2);
+}
+
+const inventory = inventoryByClassification(classification);
+const context = {
+  prepared_at: isoNow(),
+  campaign_id: args.campaignId,
+  iteration: args.iteration,
+  scope: campaign.scope ?? "whole-repo",
+  root: FRONTEND_ROOT,
+  questions: {
+    check_app:
+      "Which Fallow unused files, exports, and class members are live runtime surfaces (workers, hooks, barrels, lazy routes, provider interfaces) and must NOT be deleted?",
+    check_architecture:
+      "Which dead-code removals or dupes consolidations would break layer boundaries, SSOT, import graphs, or main/worker pairs?",
+  },
+  fallow: {
+    dead_code: loadLayer(iterDir, "fallow-scan.json", summarizeDeadCode),
+    dupes: loadLayer(iterDir, "fallow-dupes.json", summarizeDupes),
+    health: loadLayer(iterDir, "fallow-health.json", summarizeHealth),
+    classification_summary: classification?.summary ?? null,
+    inventory,
+    top_review_for_trace: inventory.review.slice(0, 25),
+    top_actionable: inventory.true_positive.slice(0, 40),
+  },
+  dupes_top_groups: topCloneGroups(dupesScan),
+  registry_entry_count: registry.entries?.length ?? 0,
+  registry_paths: (registry.entries ?? []).map((e) => e.path),
+  trace_commands: {
+    trace_file: "fallow dead-code --format json --quiet --trace-file <path>",
+    trace_export: "fallow dead-code --format json --quiet --trace <path>:<export>",
+    trace_clone: "fallow dupes --format json --quiet --trace <path>:<line>",
+  },
+  agent_specs: {
+    check_app: [
+      ".cursor/agents/remediation-check-app-inventory.md",
+      ".cursor/agents/remediation-check-app-ssot.md",
+      ".cursor/agents/remediation-check-app-trace.md",
+    ],
+    check_architecture: [
+      ".cursor/agents/remediation-check-architecture-boundaries.md",
+      ".cursor/agents/remediation-check-architecture-deps.md",
+      ".cursor/agents/remediation-check-architecture-decomposition.md",
+    ],
+    check_risk: ".cursor/agents/remediation-check-risk.md",
+  },
+  merge_script:
+    "node .cursor/aaac/scripts/remediation/merge-check-swarm.mjs --campaign-id <id> --iteration <n>",
+  record_fp_script:
+    "node .cursor/aaac/scripts/remediation/record-fallow-fp.mjs --campaign-id <id> --from-json <file>",
+};
+
+const outPath = path.join(iterDir, "check-context.json");
+writeJson(outPath, context);
+
+if (args.runId) {
+  writeJson(path.join(runDir(args.runId), "artifacts", "check_context.json"), context);
+}
+
+console.log(JSON.stringify({ ok: true, path: outPath, actionable: inventory.true_positive.length, review: inventory.review.length }));