@ludecker/aaac 1.1.5 → 1.2.0

package/src/run-engine/lib.mjs

@@ -123,6 +123,28 @@ export function isEditPhase(phase, enforcement) {
   return enforcement.edit_phases.includes(phase);
 }
 
+/** Test/spec file paths — used for writer vs tester phase scoping. */
+export function isTestPath(filePath) {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+  return (
+    /\.(test|spec)\.(mjs|cjs|js|ts|tsx)$/.test(normalized) ||
+    /(?:^|\/)__tests__(?:\/|$)/.test(normalized) ||
+    /(?:^|\/)tests\/(?:unit|integration|e2e|fixtures)\//.test(normalized)
+  );
+}
+
+/** Phase-scoped edit rules from enforcement.phase_edit_scopes (v3+). */
+export function isPathAllowedForPhase(filePath, phase, enforcement) {
+  if (!filePath) return true;
+  const scopes = enforcement.phase_edit_scopes?.[phase];
+  if (!scopes) return true;
+  const isTest = isTestPath(filePath);
+  if (scopes.deny_test_paths && isTest) return false;
+  if (scopes.test_paths_only && !isTest) return false;
+  return true;
+}
+
 export function isArtifactPath(filePath, enforcement) {
   const normalized = filePath.replace(/\\/g, "/");
   const prefixes = [
@@ -138,11 +160,22 @@ export function phaseKind(phase, registry) {
 
 /** Swarm minimum for completed phase — check verb uses check_swarm on discover. */
 export function resolveSwarmMinimum(completedPhase, manifest, enforcement) {
-  if (
-    completedPhase === "verify" &&
-    (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
-  ) {
-    return enforcement.swarm_min_agents?.verify_fix;
+  const mutating = enforcement.mutating_verbs ?? ["create", "update", "fix"];
+  const isMutating =
+    mutating.includes(manifest.verb) ||
+    enforcement.fix_commands?.includes(manifest.command);
+
+  if (completedPhase === "verify" && isMutating) {
+    return (
+      enforcement.swarm_min_agents?.verify ??
+      enforcement.swarm_min_agents?.verify_fix
+    );
+  }
+  if (completedPhase === "test_execute" && isMutating) {
+    return enforcement.swarm_min_agents?.test_execute;
+  }
+  if (completedPhase === "review_swarm" && isMutating) {
+    return enforcement.swarm_min_agents?.review_swarm;
   }
   if (completedPhase === "discover" && manifest.verb === "check") {
     return (
@@ -189,3 +222,118 @@ export function clearActiveRun(conversationId) {
     // already cleared
   }
 }
+
+export function isMutatingVerb(manifest, enforcement) {
+  const mutating = enforcement.mutating_verbs ?? ["create", "update", "fix"];
+  return (
+    mutating.includes(manifest.verb) ||
+    (enforcement.fix_commands ?? []).includes(manifest.command)
+  );
+}
+
+/** List items under a YAML field (lines starting with `-` before next top-level key). */
+export function readYamlListField(content, fieldName) {
+  if (!content) return [];
+  const lines = content.split("\n");
+  const start = lines.findIndex((line) => line.startsWith(`${fieldName}:`));
+  if (start < 0) return [];
+
+  const inline = lines[start].slice(`${fieldName}:`.length).trim();
+  if (inline === "[]") return [];
+  if (inline && !inline.startsWith("-")) return [inline];
+
+  const items = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (/^\S/.test(line) && line.trim()) break;
+    const itemMatch = line.match(/^\s+-\s+(.*)$/);
+    if (itemMatch) items.push(itemMatch[1].trim());
+  }
+  return items;
+}
+
+export function readYamlScalarField(content, fieldName) {
+  if (!content) return null;
+  const match = content.match(new RegExp(`^${fieldName}:\\s*(.+)$`, "m"));
+  if (!match) return null;
+  return match[1].trim().replace(/^["']|["']$/g, "");
+}
+
+export function hasYamlField(content, fieldName) {
+  if (!content) return false;
+  return new RegExp(`^${fieldName}:`, "m").test(content);
+}
+
+export function planRequiresTests(planContent) {
+  if (!planContent) return false;
+  if (hasYamlField(planContent, "tests_to_add")) {
+    return readYamlListField(planContent, "tests_to_add").length > 0;
+  }
+  return /^\s*create:[\s\S]*?^\s+-\s+path:.*\/lib\//m.test(planContent);
+}
+
+export function validatePhaseArtifactContent(runId, completedPhase, manifest, enforcement) {
+  if (!isMutatingVerb(manifest, enforcement)) {
+    return { ok: true };
+  }
+
+  const planPath = path.join(runDir(runId), "artifacts/plan.yaml");
+  const planContent = fs.existsSync(planPath)
+    ? fs.readFileSync(planPath, "utf8")
+    : "";
+
+  if (completedPhase === "plan") {
+    if (!hasYamlField(planContent, "tests_to_add")) {
+      return {
+        ok: false,
+        reason:
+          "plan.yaml must include tests_to_add (behaviors to cover, or tests_to_add: [] when no tests are needed)",
+      };
+    }
+    return { ok: true };
+  }
+
+  if (completedPhase === "test_execute") {
+    const testPlanPath = path.join(runDir(runId), "artifacts/test_plan.yaml");
+    const testPlanContent = fs.existsSync(testPlanPath)
+      ? fs.readFileSync(testPlanPath, "utf8")
+      : "";
+
+    const filesWritten = readYamlListField(testPlanContent, "files_written");
+    const skippedReason = readYamlScalarField(testPlanContent, "skipped_reason");
+    const testsRequired = planRequiresTests(planContent);
+
+    if (/status:\s*deferred/i.test(testPlanContent) && filesWritten.length === 0) {
+      return {
+        ok: false,
+        reason:
+          "test_plan.yaml cannot defer tests — author test files in test_execute (files_written required)",
+      };
+    }
+
+    if (testsRequired && filesWritten.length === 0) {
+      return {
+        ok: false,
+        reason:
+          "plan.yaml tests_to_add requires non-empty test_plan.files_written — launch test-author Task in test_execute",
+      };
+    }
+
+    if (
+      hasYamlField(planContent, "tests_to_add") &&
+      /tests_to_add:\s*\[\]/m.test(planContent) &&
+      filesWritten.length === 0 &&
+      !skippedReason
+    ) {
+      return {
+        ok: false,
+        reason:
+          "tests_to_add is empty — test_plan.yaml must include skipped_reason explaining why no tests were authored",
+      };
+    }
+
+    return { ok: true };
+  }
+
+  return { ok: true };
+}

package/templates/cursor/aaac/enforcement.json

@@ -1,15 +1,43 @@
 {
-  "version": 2,
+  "version": 3,
   "description": "AAAC runtime enforcement — SSOT for hooks and run engine",
-  "edit_phases": ["execute", "sync_inventory", "persist", "write"],
-  "artifact_write_phases": ["plan", "report", "verify"],
+  "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 },
+    "test_execute": { "test_paths_only": true }
+  },
   "verify_verbs": ["create", "update", "fix"],
   "swarm_min_agents": {
     "discover": 4,
     "check_swarm": 3,
     "investigate_swarm": 7,
     "research_swarm": 6,
-    "verify_fix": 3
+    "test_execute": 1,
+    "verify": 3,
+    "verify_fix": 3,
+    "review_swarm": 3
+  },
+  "swarm_min_agents_by_command": {
+    "remediate-app": {
+      "check_swarm": 7
+    }
   },
   "phase_artifacts": {
     "investigate_swarm": ["artifacts/investigation.md"],
@@ -20,12 +48,75 @@
     "dependency_graph": ["artifacts/dependency_graph.yaml"],
     "fitness_functions": ["artifacts/fitness.yaml"],
     "rollback": ["artifacts/rollback.yaml"],
+    "test_execute": ["artifacts/test_plan.yaml"],
     "verify": ["artifacts/verify.yaml"],
+    "review_swarm": ["artifacts/review.yaml"],
     "report": ["artifacts/report.md"]
   },
   "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

@@ -1,5 +1,6 @@
-# Generic AAAC project overlay — verb orchestrators + exception commands only.
-# Add domain resolvers, orchestrators, and project skills in your repo after init.
+# Generic AAAC project overlay — copied into consumer repos by `aaac init`.
+# Add `resolvers:` and domain orchestrators when you create `.cursor/domains/<slug>/`.
+# Reference implementation (Lüdecker cms/ui/database): ludecker repo `.cursor/aaac/graph.project.yaml`
 
 orchestrators:
   update-doc:
@@ -30,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]
@@ -41,7 +48,7 @@ orchestrators:
   verb-fix:
     path: skills/shared/verbs/fix/orchestrator
     requires: [discovery, investigation, root-cause, planning, validation, impact-analysis, dependency-graph, fitness-functions, rollback, execution, testing, verification, reporting]
-    phases: [load_inventory, discover, investigate_swarm, root_cause, plan, validate, impact_analysis, dependency_graph, fitness_functions, rollback, execute, verify, sync_inventory, report]
+    phases: [load_inventory, discover, investigate_swarm, root_cause, plan, validate, impact_analysis, dependency_graph, fitness_functions, rollback, execute, test_execute, verify, review_swarm, sync_inventory, report]
 
   verb-review:
     path: skills/shared/verbs/review/orchestrator
@@ -72,11 +79,17 @@ skills:
   execution:
     path: skills/shared/execution
     depends: [governance/implementation]
+  test-authoring:
+    path: skills/shared/test-authoring
+    agents: [test-author]
   testing:
     path: skills/shared/testing
     agents: [unit-test-run, fallow-check-changed, fix-repro-verify]
   verification:
     path: skills/shared/verification
+  implementation-review:
+    path: skills/shared/implementation-review
+    agents: [boundary-review, doc-conformance, implementation-review]
   reporting:
     path: skills/shared/reporting
   architecture:
@@ -136,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
 
@@ -182,14 +199,36 @@ agents:
     path: agents/fix-repro-verify.md
   fix-hypothesis-validate:
     path: agents/fix-hypothesis-validate.md
+  test-author:
+    path: agents/test-author.md
+  doc-conformance:
+    path: agents/doc-conformance.md
+  implementation-review:
+    path: agents/implementation-review.md
   release-git:
     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
-  - policies/project-context.md
-  - policies/ui-design.md
   - policies/implementation.md
   - policies/mcp-and-deploy.md

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

@@ -8,7 +8,9 @@
         "investigate_lite",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -19,7 +21,9 @@
         "investigate_lite",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -31,7 +35,9 @@
         "root_cause",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -58,7 +64,9 @@
         "investigate_lite",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -96,7 +104,9 @@
         "root_cause",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -109,10 +119,26 @@
         "root_cause",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "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

@@ -14,7 +14,15 @@
     "fitness_functions": { "skill": "fitness-functions", "gate": true },
     "rollback": { "skill": "rollback", "gate": true },
     "execute": { "skill": "execution" },
+    "test_execute": { "skill": "test-authoring" },
     "verify": { "skills": ["testing", "verification"] },
-    "report": { "skill": "reporting" }
+    "review_swarm": { "skill": "implementation-review", "readonly": true },
+    "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 }));