@ludecker/aaac 1.1.6 → 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/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.

package/templates/cursor/agents/remediation-remediator.md

@@ -0,0 +1,69 @@
+# Agent: remediation-remediator
+
+## Role
+
+Execute the **Remediator** step when `remediator-gate.mjs` or `debt-sweep-gate.mjs` exits **3** (`action: remediate`).
+
+## Critical rule
+
+**Exit 3 is not a stop signal.** The parent orchestrator must:
+
+1. Apply the handoff inline
+2. Re-run the gate with `--attempt N+1` (or debt-sweep retry_command)
+3. Repeat until promote (exit 0) or true block (exit 1 after debt sweep exhaustion)
+
+Never set `campaign.status=blocked` on exit 3. Never skip remaining waves.
+
+## Trigger
+
+```bash
+node .cursor/aaac/scripts/remediation/remediator-gate.mjs \
+  --campaign-id <id> --iteration <n> --mode wave|debt \
+  --wave-index <w> --run-id <run_id> --attempt 1
+```
+
+Read stdout JSON. When `action === "remediate"` OR `orchestrator_must_not_stop === true`:
+
+- Apply handoff **inside parent `execute` or `debt_sweep` phase** (same chat — no nested Run)
+
+## Handoff fields
+
+| Field | Use |
+|-------|-----|
+| `handoff.command` | `fix-module` or `fix-bug` |
+| `handoff.domain` | e.g. `frontend`, `backend` |
+| `handoff.intent` | Full intent including validator output |
+| `handoff.file_paths` | Prioritize these files |
+| `handoff.log_path` | **Read full log** — primary evidence source |
+| `handoff.layer` | Failed layer |
+| `retry_command` | Exact re-run command after fix |
+
+## Evidence (mandatory)
+
+1. Read `handoff.log_path` or `iterations/{n}/verify-logs/{mode}-{layer}.log`
+2. Do **not** rely on truncated `stderr_tail` alone
+3. For wave regression handoffs, fix only **introduced** layers (`introduced_layers` in payload)
+
+## Execution
+
+1. Load `iterations/{n}/remediator-handoff-attempt-{attempt}.json`
+2. Run fix-module / fix-bug **inline** (discover → execute → test_execute → verify)
+3. Re-run gate using `retry_command` from payload
+4. Repeat until `action: promote` | `promote_wave` | `defer_to_debt_sweep` | `debt_sweep_complete`
+
+## Wave vs debt
+
+| Mode | Fix scope |
+|------|-----------|
+| `wave` | Only layers in `introduced_layers` (new regression) |
+| `debt` | All failing layers until strict pass |
+
+## Return
+
+```yaml
+status: promoted | deferred | debt_sweep_complete | remediate_again
+attempt: number
+max_attempts: number
+layers_fixed: []
+remaining_failures: []
+```

package/templates/cursor/commands/remediate-app.md

@@ -0,0 +1,212 @@
+# remediate-app
+
+AAAC: `/remediate-app [domain] "<intent>"`
+
+**Layer:** system  
+**Campaign loop** — Fallow suite (dead-code + dupes + health) → check swarm → ranked fix waves → **regression wave gates** → **mandatory debt sweep** → satisfaction loop.
+
+## Dispatch
+
+1. [.cursor/aaac/dispatch.md](../aaac/dispatch.md)
+2. [.cursor/aaac/graph.yaml](../aaac/graph.yaml) — **`remediate-app`**
+3. [skills/shared/remediation/orchestrator/SKILL.md](../skills/shared/remediation/orchestrator/SKILL.md)
+
+## Hard invariants
+
+- **Exit 3 = continue** — never stop the campaign on `remediate` handoff
+- **Waves use regression gate** — pre-existing TS/vitest debt does not block cleanup waves
+- **Debt sweep is mandatory** — all layers must pass before report
+- **All planned waves must run** — no skipping on verify failure
+- **Satisfaction exit 3 = next iteration** — never report when score < threshold and iterations remain
+- **Fallow start baselines are immutable** — `fallow-start-baseline.json` (dead-code), `fallow-start-dupes-baseline.json`, `fallow-start-health-baseline.json` set once at campaign start (dupes/health auto-backfill on first scan if missing)
+- **Fallow false positives excluded from satisfaction** — dead-code score uses actionable issues; dupes uses `clone_groups`; health uses `health_score`
+
+## Intent tokens
+
+| Token | Default | Example |
+|-------|---------|---------|
+| `max_iterations` | `5` | `max_iterations=8` |
+| `max_waves_per_iteration` | `3` | `max_waves_per_iteration=2` |
+| `max_debt_sweep_rounds` | `10` | `max_debt_sweep_rounds=15` |
+| `max_remediator_attempts_per_wave` | `3` | `max_remediator_attempts_per_wave=5` |
+| `max_remediator_attempts_per_debt_round` | `3` | `max_remediator_attempts_per_debt_round=5` |
+| `satisfaction_threshold` | `85` | `satisfaction_threshold=90` |
+| `autonomous` | auto when threshold≥100 or max_iterations≥10 | `autonomous` / `manual` |
+| `resume` | — | `resume campaign_20260617_abc123` |
+
+## Example
+
+```text
+/remediate-app "whole repo; max_iterations=5; satisfaction_threshold=85"
+/remediate-app cms "Fallow cleanup until regression clean"
+/remediate-app cms "manual; max_iterations=3"
+```
+
+Ensure dev server is running when Playwright is enabled — see `project.config.json` → `remediation.verify.dev_server`.
+
+## Two-tier verification
+
+### Wave gate (regression — after each fix wave)
+
+```bash
+node .cursor/aaac/scripts/remediation/capture-wave-snapshot.mjs \
+  --campaign-id <id> --iteration <n> --wave-index <w>
+
+node .cursor/aaac/scripts/remediation/remediator-gate.mjs \
+  --campaign-id <id> --iteration <n> --mode wave --wave-index <w> \
+  --run-id <run_id> --attempt 1
+```
+
+Promotes when errors did **not increase** vs pre-wave snapshot. Pre-existing debt is deferred to debt sweep.
+
+**Exit 3** → run [remediation-remediator.md](../agents/remediation-remediator.md) → `--attempt N+1` → **do not stop**.
+
+### Debt sweep (strict — after all waves)
+
+```bash
+node .cursor/aaac/scripts/remediation/debt-sweep-gate.mjs \
+  --campaign-id <id> --iteration <n> --run-id <run_id> --round 1 --attempt 1
+```
+
+Loops until typecheck, vitest, go test, build, and Playwright all pass.
+
+### Satisfaction loop (after debt sweep)
+
+```bash
+node .cursor/aaac/scripts/remediation/compute-satisfaction.mjs \
+  --campaign-id <id> --iteration <n>
+
+node .cursor/aaac/scripts/remediation/satisfaction-loop-gate.mjs \
+  --campaign-id <id> --iteration <n> --run-id <run_id> --advance
+```
+
+| Code | Meaning |
+|------|---------|
+| `0` + `complete` | Threshold met → allow `report` |
+| `0` + `partial_complete` | Max iterations → allow partial `report` |
+| `3` + `continue_loop` | Score below threshold → **iteration N+1, return to scan** |
+
+### Campaign complete check
+
+```bash
+node .cursor/aaac/scripts/remediation/validate-campaign-complete.mjs \
+  --campaign-id <id> --iteration <n> --require-debt-sweep --require-satisfaction-loop
+```
+
+### Repair corrupted Fallow baseline (legacy campaigns)
+
+```bash
+node .cursor/aaac/scripts/remediation/repair-fallow-start-baseline.mjs \
+  --campaign-id <id> --total 1649 --dupes-clone-groups 171 --health-score 87.7
+```
+
+## Fallow scan suite (scan phase)
+
+`fallow-scan.mjs` runs three Fallow commands from `frontend/`:
+
+| Layer | Command | Artifact | Baseline file | Scoring metric |
+|-------|---------|----------|---------------|----------------|
+| Dead code | `fallow dead-code` | `iterations/{n}/fallow-scan.json` | `fallow-start-baseline.json` | actionable issues (excludes FP) |
+| Dupes | `fallow dupes` | `iterations/{n}/fallow-dupes.json` | `fallow-start-dupes-baseline.json` | `clone_groups` reduction |
+| Health | `fallow health --score` | `iterations/{n}/fallow-health.json` | `fallow-start-health-baseline.json` | `health_score` improvement |
+
+Combined summary: `iterations/{n}/fallow-scan-bundle.json`
+
+### Satisfaction weights (40% Fallow total)
+
+| Component | Weight |
+|-----------|--------|
+| `fallow_dead_code` | 0.25 |
+| `fallow_dupes` | 0.10 |
+| `fallow_health` | 0.05 |
+| `structural_clean` | 0.15 |
+| `unit_tests` | 0.15 |
+| `build` | 0.10 |
+| `e2e` | 0.20 |
+
+Regression blocks completion when actionable dead-code, `clone_groups`, or `health_score` regresses vs immutable baselines.
+
+## Exit codes (remediator-gate / debt-sweep-gate / satisfaction-loop-gate)
+
+| Code | Meaning | Agent action |
+|------|---------|--------------|
+| `0` | Promote / debt sweep complete | Continue pipeline |
+| `1` | Blocked (max rounds / infra) | Report with handoff |
+| `3` | Remediate / continue loop | **Fix inline or advance iteration — never stop, never report** |
+
+## Persistence
+
+`.cursor/aaac/state/campaigns/{campaign_id}/` — see orchestrator SKILL for layout.
+
+Full verify logs: `iterations/{n}/verify-logs/*.log` (not stderr tails).
+
+## Fallow false positives (SSOT)
+
+Fallow raw counts include issues that are not real debt. The loop bridges swarm knowledge into metrics via **check-app + check-architecture mirrors** (7-agent swarm).
+
+### check_swarm flow
+
+```bash
+# After fallow-scan + classify
+node .cursor/aaac/scripts/remediation/prepare-check-context.mjs \
+  --campaign-id <id> --iteration <n> --run-id <run_id>
+
+# 7 parallel readonly Task agents (see skills/shared/remediation/check-swarm/SKILL.md)
+# Parent collects JSON → iterations/{n}/check-swarm-raw.json
+
+node .cursor/aaac/scripts/remediation/merge-check-swarm.mjs \
+  --campaign-id <id> --iteration <n> --run-id <run_id>
+```
+
+| Agent wave | Mirrors | Purpose |
+|------------|---------|---------|
+| check-app (×3) | `/check-app` | Workers, barrels, lazy routes, trace-file |
+| check-architecture (×3) | `/check-architecture` | Boundaries, blast radius, dupes families |
+| check-risk (×1) | remediation guard | FP registry, protected paths |
+
+```bash
+# Auto-runs after every fallow-scan
+node .cursor/aaac/scripts/remediation/classify-fallow-issues.mjs \
+  --campaign-id <id> --iteration <n>
+
+# check-risk swarm records confirmed false positives
+node .cursor/aaac/scripts/remediation/record-fallow-fp.mjs \
+  --campaign-id <id> --path src/hooks/useCryptoPriceWorker.ts \
+  --classification false_positive --reason dynamically_loaded_worker --source check-risk
+```
+
+| File | Purpose |
+|------|---------|
+| `fallow-fp-rules.json` | Rule SSOT (workers, overlay barrels, barrel heuristics) |
+| `fallow-false-positives.json` | Campaign registry (swarm + manual overrides) |
+| `iterations/{n}/fallow-classification.json` | Per-scan classified inventory |
+| `iterations/{n}/check-context.json` | Swarm input SSOT (Fallow inventory + dupes top groups) |
+| `iterations/{n}/check-swarm-merge.json` | Merged FP/protected paths + reclassified totals |
+| `artifacts/check_app_validate.yaml` | check-app mirror verdict |
+| `artifacts/check_architecture_fitness.yaml` | check-architecture mirror criteria |
+| `artifacts/protected_paths.yaml` | Wave exclusion list (mandatory in dispatch-queue) |
+
+**Satisfaction** uses `actionable_total` for dead-code (excludes `false_positive`), `clone_groups` for dupes, and `health_score` for health. Waves must not delete paths in `fallow-false-positives.json`.
+
+## Autonomous platform (runner + babysit)
+
+Long campaigns (`satisfaction_threshold=100`, many iterations) must use the **shell runner**, not chat turns alone.
+
+| Layer | Path |
+|-------|------|
+| Shell runner | `.cursor/aaac/scripts/remediation/remediation-runner.mjs` |
+| Daemon | `.cursor/aaac/scripts/remediation/remediation-runner-daemon.sh` |
+| Health | `.cursor/aaac/scripts/remediation/runner-health-check.mjs` |
+| Babysit skill | [skills/shared/remediation/babysit/SKILL.md](../skills/shared/remediation/babysit/SKILL.md) |
+
+```bash
+# Bootstrap (after /remediate-app creates Run + campaign)
+node .cursor/aaac/scripts/remediation/remediation-runner.mjs \
+  --run-id <run_id> --campaign-id <campaign_id> --until-yield
+
+# Babysit: handle exit 3 yields, then --ack-yield <type>, repeat until exit 0
+```
+
+Stop-hook `loop_limit` (200) is a **guardrail** for short chat continuations — not the primary loop driver.
+
+**Autonomous is baked into `init-campaign.mjs`:** when `campaign.config.autonomous`, the orchestrator reads `artifacts/autonomous_bootstrap.json` and follows [babysit/SKILL.md](../skills/shared/remediation/babysit/SKILL.md) — no extra user prompt required.