@ludecker/aaac 1.1.5 → 1.2.0

package/templates/cursor/aaac/scripts/remediation/verify-remediation-iteration.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * Multi-layer verification gate for remediation campaigns.
+ *
+ * Modes:
+ *   wave      — fast gate after each fix wave (typecheck, vitest, go test)
+ *   iteration — full gate (+ build + Playwright)
+ *   debt      — strict full gate (same layers as iteration; used by debt_sweep)
+ *   strict    — alias for debt
+ *
+ * Usage:
+ *   node verify-remediation-iteration.mjs --campaign-id <id> --iteration <n> \
+ *     --mode wave|iteration|debt [--run-id <run_id>] [--label <suffix>]
+ */
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import { REPO_ROOT, isoNow, writeJson, runDir } from "../run-engine/lib.mjs";
+import {
+  runVerifySteps,
+  writeVerifyLogs,
+} from "./lib/verify-metrics.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, mode: "iteration", runId: null, label: 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 === "--mode") out.mode = argv[++i];
+    else if (a === "--run-id") out.runId = argv[++i];
+    else if (a === "--label") out.label = argv[++i];
+  }
+  return out;
+}
+
+function appendJournal(campaignId, text) {
+  fs.appendFileSync(path.join(CAMPAIGNS_ROOT, campaignId, "journal.md"), text);
+}
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.campaignId) {
+  console.error("verify-remediation-iteration: --campaign-id required");
+  process.exit(2);
+}
+
+const verifyMode = args.mode === "strict" ? "debt" : args.mode;
+const iterDir = path.join(CAMPAIGNS_ROOT, args.campaignId, "iterations", String(args.iteration));
+const logDir = path.join(iterDir, "verify-logs");
+fs.mkdirSync(iterDir, { recursive: true });
+
+const stepMode = verifyMode === "wave" ? "wave" : "debt";
+const report = await runVerifySteps(stepMode);
+report.iteration = args.iteration;
+report.campaign_id = args.campaignId;
+report.label = args.label;
+
+writeVerifyLogs(report, logDir, args.label ?? verifyMode);
+
+const outName =
+  args.label != null
+    ? `verify-${args.label}.json`
+    : verifyMode === "wave"
+      ? "verify-wave.json"
+      : verifyMode === "debt"
+        ? "verify-debt.json"
+        : "verify-iteration.json";
+const outPath = path.join(iterDir, outName);
+writeJson(outPath, report);
+
+if (report.status === "fail") {
+  const classify = spawnSync(
+    process.execPath,
+    [
+      path.join(__dirname, "classify-verify-failure.mjs"),
+      "--report",
+      outPath,
+      "--campaign-id",
+      args.campaignId,
+      "--iteration",
+      String(args.iteration),
+    ],
+    { encoding: "utf8" },
+  );
+  try {
+    const line = classify.stdout.trim().split("\n").pop();
+    report.failure_classification = JSON.parse(line)?.classification ?? null;
+    writeJson(outPath, report);
+  } catch {
+    report.failure_classification = null;
+  }
+}
+
+appendJournal(
+  args.campaignId,
+  `- Verify **${verifyMode}**${args.label ? ` (${args.label})` : ""} iter ${args.iteration}: **${report.status.toUpperCase()}** — total_errors=${report.metrics?.total_errors ?? 0}\n`,
+);
+
+if (args.runId) {
+  const artifactName = args.label
+    ? `verify_${args.label}_iter_${args.iteration}.json`
+    : `verify_${verifyMode}_iter_${args.iteration}.json`;
+  writeJson(path.join(runDir(args.runId), "artifacts", artifactName), report);
+}
+
+const strictPass = report.status === "pass" && (report.metrics?.total_errors ?? 0) === 0;
+console.log(JSON.stringify({ ok: strictPass, report, strict_pass: strictPass }));
+process.exit(strictPass ? 0 : 1);

package/templates/cursor/aaac/scripts/run-engine/advance-phase.mjs

@@ -17,6 +17,7 @@ import {
   isEditPhase,
   isGatePhase,
   resolveSwarmMinimum,
+  validatePhaseArtifactContent,
   writeJson,
   saveActiveRun,
 } from "./lib.mjs";
@@ -132,6 +133,28 @@ for (const rel of requiredArtifacts) {
   }
 }
 
+if (!force) {
+  const contentGate = validatePhaseArtifactContent(
+    runId,
+    completedPhase,
+    manifest,
+    enforcement,
+  );
+  if (!contentGate.ok) {
+    recordLog(manifest, {
+      event: "gate_fail",
+      phase: completedPhase,
+      phase_kind: manifest.phase_kind,
+      detail: contentGate.reason,
+      level: "warn",
+    });
+    manifest.updated_at = isoNow();
+    writeJson(manifestPath, manifest);
+    console.error(contentGate.reason);
+    process.exit(2);
+  }
+}
+
 const now = isoNow();
 const completedIsGate = isGatePhase(completedPhase, registry);
 

package/templates/cursor/aaac/scripts/run-engine/gate-write.mjs

@@ -7,6 +7,7 @@ import {
   loadEnforcement,
   isEditPhase,
   isArtifactPath,
+  isPathAllowedForPhase,
   conversationIdFromHook,
   runDir,
   writeJson,
@@ -86,6 +87,18 @@ process.stdin.on("end", () => {
   }
 
   if (isEditPhase(manifest.phase, enforcement)) {
+    if (filePath && !isPathAllowedForPhase(filePath, manifest.phase, enforcement)) {
+      persistEditEvent(
+        manifest,
+        active.run_id,
+        "edit_denied",
+        `${toolName} path not allowed in phase ${manifest.phase}: ${filePath}`,
+      );
+      deny(
+        `AAAC: ${manifest.phase} phase cannot edit this path. Run: ${active.run_id}`,
+        `Phase "${manifest.phase}" scope violation${filePath ? `: ${filePath}` : ""}. Use test_execute for tests; execute for prod code only.`,
+      );
+    }
     persistEditEvent(manifest, active.run_id, "edit_allowed", `${toolName} in phase ${manifest.phase}`);
     allow();
   }

package/templates/cursor/aaac/scripts/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/agents/doc-conformance.md

@@ -0,0 +1,25 @@
+# Agent: doc-conformance
+
+**Readonly.**
+
+## Role
+
+Compare implementation diff against supporting docs and policies — not layer boundaries (see boundary-review).
+
+## Sources (read before judging)
+
+- [docs/master_rules.md](../../docs/master_rules.md)
+- [docs/architecture.md](../../docs/architecture.md) when present
+- Domain inventory under `.cursor/domains/<slug>/update/inventory/` when available
+- [.cursor/policies/](../../.cursor/policies/)
+
+## Check
+
+- SSOT violations (duplicated constants, mirrored state)
+- Undocumented exceptions to master rules
+- Plan `requirement_map` entries satisfied in code
+- Missing validation at boundaries when plan promised schemas
+
+## Return
+
+Findings, Evidence (`path:line`), Severity (critical | suggestion), Confidence.

package/templates/cursor/agents/implementation-review.md

@@ -0,0 +1,21 @@
+# Agent: implementation-review
+
+**Readonly.**
+
+## Role
+
+Independent post-execute review of the diff — **not** the agent that wrote the code. Spot-check that the change matches plan and does not introduce obvious defects.
+
+## Check
+
+- Plan `paths_to_touch` vs actual diff scope
+- No drive-by refactors outside plan
+- Error paths logged, not swallowed
+- Async flows use explicit state machines where plan required
+- Size budgets not violated on touched files (flag if file grew past 80% budget)
+
+## Return
+
+Findings, Evidence (`path:line`), Severity (critical | suggestion), Confidence.
+
+**Blocking:** any **critical** finding must be fixed before `report` on mutating verbs.

package/templates/cursor/agents/remediation-check-app-inventory.md

@@ -0,0 +1,32 @@
+# Agent: remediation-check-app-inventory
+
+**Readonly.** Mirrors `/check-app` discover phase for Fallow remediation.
+
+## Role
+
+Map Fallow `unused_files` and `review` inventory to **live app surfaces**: Vite entry points, workers (`src/workers/**`), hooks (`*Worker*`), overlay renderer barrels, lazy routes, Playwright-critical imports.
+
+## Inputs (mandatory)
+
+- `iterations/{n}/check-context.json`
+- `iterations/{n}/fallow-scan.json`
+- `frontend/.fallowrc.json` (`dynamicallyLoaded`)
+
+## Commands (run as needed)
+
+```bash
+cd frontend && fallow list --entry-points --format json --quiet 2>/dev/null || true
+cd frontend && fallow dead-code --format json --quiet --trace-file <path> 2>/dev/null || true
+```
+
+## Return
+
+Structured JSON block (see [check-swarm SKILL](../skills/shared/remediation/check-swarm/SKILL.md)) plus:
+
+- **Answer** — are flagged unused files actually unreachable from app runtime?
+- **protected_paths** — paths waves must never delete
+- **false_positives** — with `reason` + `evidence` (`path:line`)
+
+## Confidence
+
+high | medium | low

package/templates/cursor/agents/remediation-check-app-ssot.md

@@ -0,0 +1,24 @@
+# Agent: remediation-check-app-ssot
+
+**Readonly.** Mirrors `/check-app` SSOT trace for Fallow remediation.
+
+## Role
+
+For each Fallow `review` / `true_positive` export: who owns the symbol? Is it consumed via barrel re-export, dynamic import, worker postMessage, or external package API?
+
+## Inputs (mandatory)
+
+- `iterations/{n}/check-context.json` — `fallow.inventory`
+- `fallow-false-positives.json` (campaign registry)
+
+## Method
+
+1. Grep importers for top `review` exports
+2. Check barrel `index.ts` re-export chains
+3. Flag provider interface methods (`name`, `createInvoice`) as **protected** not dead
+
+## Return
+
+JSON block with `false_positives`, `do_not_delete`, `safe_to_fix`, `findings`, `gaps`.
+
+Set `command_mirror: "check-app"`.

package/templates/cursor/agents/remediation-check-app-trace.md

@@ -0,0 +1,29 @@
+# Agent: remediation-check-app-trace
+
+**Readonly.** Mirrors `/check-app` capability trace for Fallow remediation.
+
+## Role
+
+Run Fallow trace CLI for every item in `check-context.fallow.top_review_for_trace`. Confirm whether static unused = actually unreachable.
+
+## Commands (mandatory for each review item)
+
+```bash
+cd frontend && fallow dead-code --format json --quiet --trace-file <path> 2>/dev/null || true
+cd frontend && fallow dead-code --format json --quiet --trace <path>:<export> 2>/dev/null || true
+```
+
+## Classification rules
+
+| Trace result | Classification |
+|--------------|----------------|
+| Entry-point or dynamically loaded | `false_positive` |
+| Re-export chain to live entry | `false_positive` |
+| Zero importers, not entry | `true_positive` or `safe_to_fix` |
+| Ambiguous (test-only import) | `review` |
+
+## Return
+
+JSON block with per-path trace summary in `findings`. Populate `false_positives` for confirmed runtime paths.
+
+Set `command_mirror: "check-app"`, `agent_id: "remediation-check-app-trace"`.

package/templates/cursor/agents/remediation-check-architecture-boundaries.md

@@ -0,0 +1,21 @@
+# Agent: remediation-check-architecture-boundaries
+
+**Readonly.** Mirrors `/check-architecture` boundary review for remediation waves.
+
+## Role
+
+Evaluate whether proposed Fallow deletions or dupes extractions would cross layer boundaries (UI→fetch, domain→infrastructure, worker↔main SSOT violations).
+
+## Inputs
+
+- `check-context.json`
+- `docs/architecture.md` (if present)
+- Fallow `boundary_violations` from dead-code scan
+
+## Return
+
+JSON block: `command_mirror: "check-architecture"`. List boundary risks in `findings`. Add blast-radius paths to `protected_paths` / `do_not_delete`.
+
+## Severity
+
+critical = deletion would break boundary; suggestion = refactor-only

package/templates/cursor/agents/remediation-check-architecture-decomposition.md

@@ -0,0 +1,25 @@
+# Agent: remediation-check-architecture-decomposition
+
+**Readonly.** Mirrors `/check-architecture` system decomposition for dupes remediation.
+
+## Role
+
+Classify dupes clone families (operations/, workers/, e2e specs) into:
+
+- **extract-shared** — safe consolidation target
+- **main-worker mirror** — do not delete one side; extract to shared module first
+- **test-only dupes** — low risk extract
+- **intentional parallel** — mark protected (e.g. provider adapters)
+
+## Inputs
+
+- `check-context.dupes_top_groups`
+- `fallow-dupes.json` clone_groups
+
+## Return
+
+JSON block: `command_mirror: "check-architecture"`. Dupes safe targets in `safe_to_fix`. Mirrored paths in `protected_paths`.
+
+## Anti-pattern
+
+Never recommend deleting `src/lib/**` because worker has a copy — recommend shared extract wave instead.

package/templates/cursor/agents/remediation-check-architecture-deps.md

@@ -0,0 +1,23 @@
+# Agent: remediation-check-architecture-deps
+
+**Readonly.** Mirrors `/check-architecture` dependency analysis for remediation.
+
+## Role
+
+For top `true_positive` file deletions and large dupes groups: compute fan-in, import cycles, and downstream test breakage risk.
+
+## Inputs
+
+- `check-context.json` — `dupes_top_groups`, `fallow.inventory.true_positive`
+- `fallow dead-code` circular_dependencies list
+
+## Commands
+
+```bash
+cd frontend && fallow dead-code --format json --quiet --trace-file <path> 2>/dev/null || true
+cd frontend && fallow dupes --format json --quiet --trace <path>:<line> 2>/dev/null || true
+```
+
+## Return
+
+JSON block: `command_mirror: "check-architecture"`. High fan-in paths → `protected_paths`. Isolated leaves → `safe_to_fix`.

package/templates/cursor/agents/remediation-check-risk.md

@@ -0,0 +1,37 @@
+# Agent: remediation-check-risk
+
+**Readonly.** Remediation guard — consolidates FP traps before fix waves.
+
+## Role
+
+Final pass on all Fallow layers (dead-code, dupes, health). Confirm or reject classifications from other swarm agents. **This agent owns the FP registry update.**
+
+## Mandatory actions
+
+1. Read `check-context.json` + `fallow-classification.json`
+2. Cross-check other agents' `false_positives` proposals
+3. Write batch file for merge script OR confirm parent will run:
+
+```bash
+node .cursor/aaac/scripts/remediation/record-fallow-fp.mjs \
+  --campaign-id <id> --from-json iterations/<n>/check-swarm-fp-batch.json
+```
+
+## Known FP patterns (always verify)
+
+| Pattern | Reason |
+|---------|--------|
+| `src/hooks/*Worker*.ts` | worker_hook_runtime |
+| `src/workers/**` | dynamically_loaded |
+| `src/overlays/renderers/*/index.ts` | overlay_renderer_barrel |
+| `LayoutSaveQueue.enqueue/cancel` | framework lifecycle |
+| `AtlosPaymentProvider.name/createInvoice` | provider interface |
+| `src/operations/categories/**` dupes | boilerplate — extract, don't delete ops |
+
+## Return
+
+JSON block with complete `false_positives[]`, `protected_paths[]`, `do_not_delete[]`. Set `agent_id: "remediation-check-risk"`.
+
+## Rule
+
+When uncertain → `review` + `protected_paths`, never `true_positive` delete.

package/templates/cursor/agents/remediation-e2e-gate.md

@@ -0,0 +1,30 @@
+# Agent: remediation-e2e-gate
+
+## Role
+
+Run the full iteration verification gate for a remediation campaign and return structured pass/fail.
+
+## Steps
+
+1. Confirm `SE100_BASE_URL` (default `http://localhost:5173`) is reachable
+2. Run:
+   ```bash
+   node .cursor/aaac/scripts/remediation/verify-remediation-iteration.mjs \
+     --campaign-id <campaign_id> --iteration <n> --mode iteration --run-id <run_id>
+   ```
+3. Read output JSON — report each layer status
+
+## Return
+
+```yaml
+status: pass | fail
+layers:
+  typecheck: pass | fail
+  vitest: pass | fail
+  go_test: pass | fail | skipped
+  build: pass | fail
+  playwright: pass | fail
+artifact_path: .cursor/aaac/state/campaigns/{id}/iterations/{n}/verify-iteration.json
+```
+
+On fail: include `stderr_tail` excerpts and whether rollback is recommended.