@ludecker/aaac 1.1.6 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludecker/aaac",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "description": "Agentic Architecture as Code (AAAC) — installable Cursor agent framework",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,13 @@
     "src/",
     "templates/"
   ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:node": "node --test tests/log.test.mjs",
+    "test:e2e": "pnpm exec playwright test",
+    "test:e2e:ui": "pnpm exec playwright test --ui"
+  },
   "devDependencies": {
     "@playwright/test": "^1.52.0",
     "vitest": "^3.2.4",
@@ -39,12 +46,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:node": "node --test tests/log.test.mjs",
-    "test:e2e": "pnpm exec playwright test",
-    "test:e2e:ui": "pnpm exec playwright test --ui"
   }
-}
+}

package/templates/cursor/aaac/enforcement.json

@@ -1,8 +1,23 @@
 {
   "version": 3,
   "description": "AAAC runtime enforcement — SSOT for hooks and run engine",
-  "edit_phases": ["execute", "test_execute", "sync_inventory", "persist", "write"],
-  "artifact_write_phases": ["plan", "report"],
+  "edit_phases": [
+    "execute",
+    "debt_sweep",
+    "test_execute",
+    "sync_inventory",
+    "persist",
+    "write"
+  ],
+  "artifact_write_phases": [
+    "plan",
+    "report",
+    "campaign_init",
+    "scan",
+    "check_swarm",
+    "plan_waves",
+    "satisfaction_gate"
+  ],
   "mutating_verbs": ["create", "update", "fix"],
   "phase_edit_scopes": {
     "execute": { "deny_test_paths": true },
@@ -19,6 +34,11 @@
     "verify_fix": 3,
     "review_swarm": 3
   },
+  "swarm_min_agents_by_command": {
+    "remediate-app": {
+      "check_swarm": 7
+    }
+  },
   "phase_artifacts": {
     "investigate_swarm": ["artifacts/investigation.md"],
     "root_cause": ["artifacts/root_cause.yaml"],
@@ -35,7 +55,68 @@
   },
   "allowed_path_prefixes": {
     "run_artifacts": [".cursor/aaac/state/runs/", "aaac/state/runs/"],
-    "write_article": [".cursor/write-article-runs/"]
+    "campaign_artifacts": [".cursor/aaac/state/campaigns/", "aaac/state/campaigns/"]
+  },
+  "remediation_gate": {
+    "script": "verify-remediation-iteration.mjs",
+    "remediator_gate_script": "remediator-gate.mjs",
+    "debt_sweep_script": "debt-sweep-gate.mjs",
+    "satisfaction_loop_script": "satisfaction-loop-gate.mjs",
+    "repair_fallow_start_script": "repair-fallow-start-baseline.mjs",
+    "bootstrap_autonomous_script": "bootstrap-autonomous.mjs",
+    "runner_script": "remediation-runner.mjs",
+    "runner_daemon_script": "remediation-runner-daemon.sh",
+    "runner_health_script": "runner-health-check.mjs",
+    "plan_waves_script": "plan-waves-from-queue.mjs",
+    "validate_script": "validate-campaign-complete.mjs",
+    "baseline_script": "capture-verify-baseline.mjs",
+    "wave_snapshot_script": "capture-wave-snapshot.mjs",
+    "classify_fallow_script": "classify-fallow-issues.mjs",
+    "record_fallow_fp_script": "record-fallow-fp.mjs",
+    "fallow_fp_rules": "fallow-fp-rules.json",
+    "classify_script": "classify-verify-failure.mjs",
+    "dispatch_rules": "dispatch-rules.json",
+    "wave_mode": "wave",
+    "debt_mode": "debt",
+    "wave_gate_mode": "regression",
+    "debt_gate_mode": "strict",
+    "campaign_artifact": "artifacts/campaign.json",
+    "exit_codes": {
+      "promote": 0,
+      "block": 1,
+      "runtime_error": 2,
+      "remediate": 3
+    },
+    "invariants": {
+      "exit_3_is_continue": true,
+      "never_block_campaign_on_wave_exit_3": true,
+      "satisfaction_exit_3_is_continue_loop": true,
+      "fallow_start_baseline_immutable": true,
+      "validate_before_report": true
+    }
+  },
+  "phase_artifacts_remediate": {
+    "campaign_init": ["artifacts/campaign.json", "artifacts/verify_baseline.json"],
+    "scan": [
+      "artifacts/fallow_scan.json",
+      "artifacts/fallow_dupes.json",
+      "artifacts/fallow_health.json",
+      "artifacts/fallow_scan_bundle.json",
+      "artifacts/fallow_classification.json"
+    ],
+    "check_swarm": [
+      "artifacts/check_synthesis.md",
+      "artifacts/dispatch-queue.yaml",
+      "artifacts/check_app_validate.yaml",
+      "artifacts/check_architecture_fitness.yaml",
+      "artifacts/protected_paths.yaml",
+      "artifacts/check_swarm_merge.json"
+    ],
+    "plan_waves": ["artifacts/plan_waves.yaml"],
+    "execute": ["artifacts/execute_waves.yaml"],
+    "debt_sweep": ["artifacts/debt_sweep.json", "artifacts/verify_debt.json"],
+    "satisfaction_gate": ["artifacts/satisfaction.json", "artifacts/satisfaction_loop_gate.json"],
+    "report": ["artifacts/report.md"]
   },
   "fix_commands": ["fix-module", "fix-bug", "module-fix", "bug-fix"]
 }

package/templates/cursor/aaac/graph.project.yaml

@@ -31,6 +31,12 @@ orchestrators:
     path: skills/shared/platform-release/orchestrator
     requires: [testing, verification, execution, reporting]
 
+  remediate-app:
+    path: skills/shared/remediation/orchestrator
+    requires: [remediation, discovery, check, execution, testing, verification, reporting]
+    check_swarm_skill: skills/shared/remediation/check-swarm
+    phases: [campaign_init, scan, check_swarm, plan_waves, execute, debt_sweep, satisfaction_gate, report]
+
   verb-create:
     path: skills/shared/verbs/create/orchestrator
     requires: [discovery, investigation-lite, planning, validation, impact-analysis, dependency-graph, fitness-functions, rollback, execution, testing, verification, reporting, module-authoring]
@@ -143,6 +149,10 @@ skills:
     path: skills/shared/module-authoring
   platform-release:
     path: skills/shared/platform-release
+  remediation:
+    path: skills/shared/remediation
+  remediation-check-swarm:
+    path: skills/shared/remediation/check-swarm
   governance/implementation:
     path: skills/shared/governance/implementation
 
@@ -199,6 +209,24 @@ agents:
     path: agents/release-git.md
     wave: 1
     blocking: true
+  remediation-check-app-inventory:
+    path: agents/remediation-check-app-inventory.md
+  remediation-check-app-ssot:
+    path: agents/remediation-check-app-ssot.md
+  remediation-check-app-trace:
+    path: agents/remediation-check-app-trace.md
+  remediation-check-architecture-boundaries:
+    path: agents/remediation-check-architecture-boundaries.md
+  remediation-check-architecture-deps:
+    path: agents/remediation-check-architecture-deps.md
+  remediation-check-architecture-decomposition:
+    path: agents/remediation-check-architecture-decomposition.md
+  remediation-check-risk:
+    path: agents/remediation-check-risk.md
+  remediation-remediator:
+    path: agents/remediation-remediator.md
+  remediation-e2e-gate:
+    path: agents/remediation-e2e-gate.md
 
 policies:
   - policies/master-rules.md

package/templates/cursor/aaac/lifecycle/lifecycle.json

@@ -125,6 +125,20 @@
         "report"
       ],
       "gate_stack": "pre_execute"
+    },
+    "remediate-app": {
+      "description": "Long-running remediation campaign — Fallow scan, check swarm, fix waves, debt sweep, satisfaction loop",
+      "work_phases": [
+        "campaign_init",
+        "scan",
+        "check_swarm",
+        "plan_waves",
+        "execute",
+        "debt_sweep",
+        "satisfaction_gate",
+        "report"
+      ],
+      "gate_stack": null
     }
   }
 }

package/templates/cursor/aaac/lifecycle/phases.json

@@ -17,6 +17,12 @@
     "test_execute": { "skill": "test-authoring" },
     "verify": { "skills": ["testing", "verification"] },
     "review_swarm": { "skill": "implementation-review", "readonly": true },
-    "report": { "skill": "reporting" }
+    "report": { "skill": "reporting" },
+    "campaign_init": { "skill": "remediation", "readonly": true },
+    "scan": { "skill": "remediation", "readonly": true },
+    "check_swarm": { "skill": "check", "readonly": true },
+    "plan_waves": { "skill": "planning", "readonly": true },
+    "debt_sweep": { "skill": "remediation" },
+    "satisfaction_gate": { "skill": "remediation", "readonly": true }
   }
 }

package/templates/cursor/aaac/ontology.json

@@ -180,6 +180,7 @@
     "review-incident": { "orchestrator": "review-incident" },
     "test-function": { "orchestrator": "test-function" },
     "release-app": { "orchestrator": "release-app" },
+    "remediate-app": { "orchestrator": "remediate-app", "object": "app" },
     "module-update": { "alias": "update-module" },
     "update-doc": { "alias": "update-architecture" },
     "architecture": { "alias": "update-architecture" },

package/templates/cursor/aaac/project.config.json

@@ -2,5 +2,41 @@
   "manual_commands": [],
   "verify": {
     "enabled": false
+  },
+  "remediation": {
+    "fallow_cwd": ".",
+    "scan_root": ".",
+    "verify": {
+      "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
+        }
+      ],
+      "playwright": {
+        "enabled": false
+      },
+      "dev_server": {
+        "url": "http://localhost:3000",
+        "launch_hint": "Start your dev server before debt sweep / Playwright gates."
+      }
+    }
   }
 }

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Synthesize check-swarm-raw.json from Fallow health targets (scriptable check_swarm).
+ */
+import fs from "fs";
+import path from "path";
+import { isoNow } from "../run-engine/lib.mjs";
+import { campaignDir, iterDir } from "./lib/runner-state.mjs";
+import { loadCampaignContext } from "./lib/campaign-focus.mjs";
+import {
+  fetchHealthTargets,
+  filterTargetsForWaves,
+} from "./lib/fallow-health-targets.mjs";
+
+const AGENT_IDS = [
+  "remediation-check-app-inventory",
+  "remediation-check-app-ssot",
+  "remediation-check-app-trace",
+  "remediation-check-architecture-boundaries",
+  "remediation-check-architecture-deps",
+  "remediation-check-architecture-decomposition",
+  "remediation-check-risk",
+];
+
+function parseArgs(argv) {
+  const out = { campaignId: null, iteration: 0 };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--campaign-id") out.campaignId = argv[++i];
+    else if (argv[i] === "--iteration") out.iteration = Number(argv[++i]);
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("--campaign-id required");
+  process.exit(2);
+}
+
+const ctx = loadCampaignContext(args.campaignId);
+const { targets, score } = fetchHealthTargets({ scope: ctx.scope, limit: 15 });
+const filtered = filterTargetsForWaves(targets, {
+  protected_paths: ctx.protected_paths,
+  defer_high_fan_in: ctx.focus.defer_high_fan_in,
+});
+
+const safeToFix = filtered.slice(0, 8).map((t) => ({
+  path: t.path,
+  category: "health_decompose",
+  evidence: t.recommendation ?? null,
+}));
+
+const baseFinding = `health ${score ?? "?"}; focus=${ctx.focus.health_functions_above_60_loc ? "functions>60LOC" : "general"}`;
+
+const agents = AGENT_IDS.map((agent_id) => ({
+  agent_id,
+  command_mirror: agent_id.includes("risk") ? "check-risk" : agent_id.includes("architecture") ? "check-architecture" : "check-app",
+  answer: "partial",
+  confidence: "high",
+  false_positives: [],
+  protected_paths: ctx.protected_paths,
+  do_not_delete: ctx.protected_paths.map((p) => ({ path: p, reason: "protected" })),
+  safe_to_fix: safeToFix,
+  findings: [baseFinding, `auto-synthesis iter ${args.iteration}`],
+  gaps: [],
+}));
+
+const outPath = path.join(iterDir(args.campaignId, args.iteration), "check-swarm-raw.json");
+fs.mkdirSync(path.dirname(outPath), { recursive: true });
+fs.writeFileSync(
+  outPath,
+  JSON.stringify({ merged_at: isoNow(), iteration: args.iteration, focus: ctx.focus, agents }, null, 2),
+);
+
+console.log(JSON.stringify({ ok: true, path: outPath, agents: agents.length, safe_to_fix: safeToFix.length }));

package/templates/cursor/aaac/scripts/remediation/auto-dispatch-queue-from-health.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Build dispatch-queue.yaml from Fallow health targets + campaign focus.
+ */
+import fs from "fs";
+import path from "path";
+import { campaignDir, loadCampaign } from "./lib/runner-state.mjs";
+import { loadCampaignContext, normalizeRepoPath } from "./lib/campaign-focus.mjs";
+import {
+  fetchHealthTargets,
+  filterTargetsForWaves,
+  targetToWaveIntent,
+} from "./lib/fallow-health-targets.mjs";
+import { journal } from "./lib/runner-exec.mjs";
+
+function parseArgs(argv) {
+  const out = { campaignId: null, iteration: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--campaign-id") out.campaignId = argv[++i];
+    else if (argv[i] === "--iteration") out.iteration = Number(argv[++i]);
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("--campaign-id required");
+  process.exit(2);
+}
+
+const ctx = loadCampaignContext(args.campaignId);
+const campaign = ctx.campaign;
+const iteration = args.iteration ?? campaign.iteration ?? 0;
+const maxWaves = campaign.config?.max_waves_per_iteration ?? 3;
+
+const { targets } = fetchHealthTargets({ scope: ctx.scope, limit: 20 });
+const filtered = filterTargetsForWaves(targets, {
+  protected_paths: ctx.protected_paths,
+  defer_high_fan_in: ctx.focus.defer_high_fan_in,
+}).slice(0, maxWaves);
+
+if (filtered.length === 0) {
+  console.error("No health targets available for waves");
+  process.exit(2);
+}
+
+const lines = [
+  `# iteration ${iteration} health waves — auto from Fallow targets`,
+  `iteration: ${iteration}`,
+  `campaign_id: ${args.campaignId}`,
+  `scope: ${ctx.scope}`,
+  `intent_focus: health`,
+  "",
+  "protected_paths:",
+  ...ctx.protected_paths.map((p) => `  - ${p}`),
+  "",
+  "waves:",
+];
+
+for (let i = 0; i < filtered.length; i++) {
+  const t = filtered[i];
+  const risk = t.effort === "high" ? "medium" : "low";
+  lines.push(`- priority: ${i + 1}`);
+  lines.push(`  command: fix-module`);
+  lines.push(`  intent: ${targetToWaveIntent(t)}`);
+  lines.push(`  risk: ${risk}`);
+}
+
+const yaml = `${lines.join("\n")}\n`;
+const dest = path.join(campaignDir(args.campaignId), "dispatch-queue.yaml");
+const artifact = path.join(campaignDir(args.campaignId), "artifacts", "dispatch-queue.yaml");
+fs.writeFileSync(dest, yaml);
+fs.mkdirSync(path.dirname(artifact), { recursive: true });
+fs.writeFileSync(artifact, yaml);
+
+journal(args.campaignId, `- **Auto dispatch-queue** iter ${iteration}: ${filtered.length} health wave(s)`);
+
+console.log(JSON.stringify({ ok: true, waves: filtered.length, paths: filtered.map((t) => t.path) }));

package/templates/cursor/aaac/scripts/remediation/bootstrap-autonomous.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Write run + campaign artifacts when autonomous mode is active.
+ * Called from init-campaign.mjs — orchestrator MUST follow bootstrap.next_action.
+ *
+ * Usage:
+ *   node bootstrap-autonomous.mjs --run-id <id> --campaign-id <id>
+ */
+import fs from "fs";
+import path from "path";
+import { REPO_ROOT, isoNow, readJson, runDir, writeJson } from "../run-engine/lib.mjs";
+import {
+  autonomousBootstrapCommands,
+  BABYSIT_SKILL,
+} from "./lib/autonomous-mode.mjs";
+import { loadRunnerState, loadYield, runnerStatePath, yieldArtifactPath } from "./lib/runner-state.mjs";
+
+function parseArgs(argv) {
+  const out = { runId: null, campaignId: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--run-id") out.runId = argv[++i];
+    else if (a === "--campaign-id") out.campaignId = argv[++i];
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.runId || !args.campaignId) {
+  console.error("bootstrap-autonomous: --run-id and --campaign-id required");
+  process.exit(2);
+}
+
+const campaignPath = path.join(
+  REPO_ROOT,
+  ".cursor/aaac/state/campaigns",
+  args.campaignId,
+  "campaign.json",
+);
+const campaign = readJson(campaignPath, null);
+if (!campaign?.config?.autonomous) {
+  console.log(JSON.stringify({ ok: true, autonomous: false, skipped: true }));
+  process.exit(0);
+}
+
+const commands = autonomousBootstrapCommands(args.runId, args.campaignId);
+const runnerState = loadRunnerState(args.campaignId);
+const yieldPayload = loadYield(args.campaignId);
+
+const bootstrap = {
+  ok: true,
+  autonomous: true,
+  autonomous_reason: campaign.config.autonomous_reason,
+  campaign_id: args.campaignId,
+  run_id: args.runId,
+  iteration: campaign.iteration,
+  satisfaction_threshold: campaign.config.satisfaction_threshold,
+  orchestrator_mode: "shell_runner_yield_watcher",
+  skill_required: BABYSIT_SKILL,
+  orchestrator_must_not: [
+    "walk_phases_manually_in_chat",
+    "end_turn_before_runner_exit_0",
+    "report_when_satisfaction_below_threshold",
+  ],
+  loop: [
+    "read_babysit_skill",
+    "runner_health_check",
+    "remediation_yield_watcher",
+    "if_exit_3_handle_yield_then_ack_yield",
+    "repeat_until_exit_0",
+  ],
+  commands,
+  runner_state_path: runnerStatePath(args.campaignId),
+  yield_path: yieldArtifactPath(args.campaignId),
+  current_runner: runnerState,
+  pending_yield: yieldPayload,
+  next_action: yieldPayload
+    ? {
+        type: "handle_yield",
+        yield_type: yieldPayload.type,
+        ack_command: `node .cursor/aaac/scripts/remediation/remediation-runner.mjs --run-id ${args.runId} --campaign-id ${args.campaignId} --ack-yield ${yieldPayload.type}`,
+      }
+    : {
+        type: "run_until_yield",
+        command: commands.runner_until_yield,
+      },
+  at: isoNow(),
+};
+
+const runArtifact = path.join(runDir(args.runId), "artifacts", "autonomous_bootstrap.json");
+writeJson(runArtifact, bootstrap);
+
+const campaignArtifact = path.join(
+  REPO_ROOT,
+  ".cursor/aaac/state/campaigns",
+  args.campaignId,
+  "autonomous-bootstrap.json",
+);
+writeJson(campaignArtifact, bootstrap);
+
+appendJournal(args.campaignId, `- **Autonomous mode** — ${campaign.config.autonomous_reason}; bootstrap written`);
+
+console.log(JSON.stringify(bootstrap));
+
+function appendJournal(campaignId, line) {
+  const journalPath = path.join(
+    REPO_ROOT,
+    ".cursor/aaac/state/campaigns",
+    campaignId,
+    "journal.md",
+  );
+  fs.appendFileSync(journalPath, `\n${line}\n`);
+}

package/templates/cursor/aaac/scripts/remediation/capture-verify-baseline.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Capture campaign verify baseline at start (before any waves).
+ *
+ * Usage:
+ *   node capture-verify-baseline.mjs --campaign-id <id> [--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 {
+  runVerifySteps,
+  writeVerifyLogs,
+  summarizeMetrics,
+} from "./lib/verify-metrics.mjs";
+
+const CAMPAIGNS_ROOT = path.join(REPO_ROOT, ".cursor/aaac/state/campaigns");
+
+function parseArgs(argv) {
+  const out = { campaignId: null, runId: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--campaign-id") out.campaignId = argv[++i];
+    else if (argv[i] === "--run-id") out.runId = argv[++i];
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("capture-verify-baseline: --campaign-id required");
+  process.exit(2);
+}
+
+const campaignDir = path.join(CAMPAIGNS_ROOT, args.campaignId);
+const baselineDir = path.join(campaignDir, "baseline");
+fs.mkdirSync(baselineDir, { recursive: true });
+
+const report = await runVerifySteps("wave");
+writeVerifyLogs(report, baselineDir, "baseline");
+
+const snapshot = {
+  captured_at: isoNow(),
+  kind: "campaign_verify_baseline",
+  summary: summarizeMetrics(report),
+  metrics: report.metrics,
+  report_path: path.join(baselineDir, "verify-baseline.json"),
+};
+
+writeJson(snapshot.report_path, report);
+writeJson(path.join(campaignDir, "verify-baseline.json"), snapshot);
+
+const campaign = readJson(path.join(campaignDir, "campaign.json"), {});
+if (campaign) {
+  campaign.verify_baseline = snapshot.summary;
+  campaign.updated_at = isoNow();
+  writeJson(path.join(campaignDir, "campaign.json"), campaign);
+}
+
+if (args.runId) {
+  writeJson(path.join(runDir(args.runId), "artifacts", "verify_baseline.json"), snapshot);
+}
+
+const journal = `\n- **Verify baseline captured** — total_errors=${snapshot.summary.total_errors} (typecheck ${snapshot.summary.layers.typecheck.error_count}, vitest ${snapshot.summary.layers.vitest.error_count})\n`;
+fs.appendFileSync(path.join(campaignDir, "journal.md"), journal);
+
+console.log(JSON.stringify({ ok: true, baseline: snapshot }));