@ludecker/aaac 1.1.6 → 1.2.0

package/templates/cursor/skills/shared/remediation/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: shared-remediation
+description: Remediation campaign loop — scan, check, fix waves, regression gates, debt sweep, satisfaction.
+disable-model-invocation: true
+---
+
+# Used by `/remediate-app`. See [orchestrator/SKILL.md](./orchestrator/SKILL.md).
+
+**Autonomous campaigns:** [babysit/SKILL.md](./babysit/SKILL.md) is **auto-required** when `campaign.config.autonomous` (see `artifacts/autonomous_bootstrap.json`).
+
+## Agentic OS loop
+
+```text
+Planner (check_swarm mirrors check-app + check-architecture → plan_waves)
+  ↓
+Executor (fix wave)
+  ↓
+Validator — regression gate (remediator-gate --mode wave)
+  ↓
+Remediator (fix-module / fix-bug)  ← exit 3 = CONTINUE, not stop
+  ↓
+Validator retry (attempt++)
+  ↓
+Promote wave (no new regression) → next wave
+  ↓
+Debt sweep — strict gate (debt-sweep-gate)
+  ↓
+Remediator loop until all layers green
+  ↓
+Satisfaction gate → report (validate-campaign-complete first)
+```
+
+## Two-tier validation
+
+| Tier | Script | Pass when |
+|------|--------|-----------|
+| Regression | `remediator-gate --mode wave` | Errors did not **increase** vs pre-wave snapshot |
+| Strict | `debt-sweep-gate` | All layers pass; `total_errors === 0` |
+
+## Loop invariant
+
+Every iteration must persist:
+
+1. Verify baseline (campaign start)
+2. Fallow scan snapshot
+3. Pre-wave snapshots + wave verify reports
+4. Debt sweep state + verify-debt.json
+5. Full logs in `verify-logs/*.log`
+6. Satisfaction score
+
+**Exit 3 never ends the campaign.** Pre-existing debt never blocks cleanup waves.

package/templates/cursor/skills/shared/remediation/babysit/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: remediate-app-babysit
+description: >-
+  Babysit an active /remediate-app campaign using the shell runner. Handles
+  runner yields (check_swarm, execute waves, remediator handoffs, report),
+  runs health checks, and loops until satisfaction or max iterations. Use when
+  asked to continue remediation autonomously, babysit the campaign, or resume
+  run_*/campaign_* remediation.
+disable-model-invocation: true
+---
+
+# Remediation babysit (safety layer)
+
+**Auto-invoked** when `campaign.config.autonomous === true` (set by `init-campaign.mjs`). The user does not need a separate “babysit” prompt.
+
+Pairs with the **shell runner** (foundation). The runner drives scriptable phases; this skill handles **yields** and **safety**.
+
+| Layer | Script / skill | Role |
+|-------|----------------|------|
+| Foundation | `remediation-runner.mjs` | State machine, gates, satisfaction loop |
+| Daemon | `remediation-runner-daemon.sh` | Delegates to continuous yield watcher |
+| Watcher | `remediation-yield-watcher.mjs` | Continuous loop until satisfaction goal |
+
+## When to use
+
+- Campaign `status: running` but chat stopped mid-iteration
+- `runner-yield.json` exists (runner exit **3**)
+- User asks to **continue**, **babysit**, or **run autonomously** to satisfaction threshold
+- After `/remediate-app` with `max_iterations` > 5 or `satisfaction_threshold=100`
+
+## When NOT to use
+
+- Campaign `status: complete` and satisfaction gate says `complete`
+- No `runner-state.json` — run `remediation-runner.mjs --tick` once to init, or start via `/remediate-app`
+- User explicitly wants a single manual iteration only
+
+## Hard rules
+
+1. **Exit 3 ≠ stop** — runner yield, remediator gate, satisfaction gate continue = keep going
+2. **Never report** while `satisfaction-loop-gate` says `continue_loop`
+3. **Run health check** before each babysit cycle
+4. **Ack every yield** with `--ack-yield <type>` after agent work — runner will not advance otherwise
+5. **check_swarm** — exactly **7** readonly Task agents (see [check-swarm/SKILL.md](../check-swarm/SKILL.md))
+6. **Test-only waves** — use `test_execute` phase for test file dedupes, or mark wave `degraded` in `execute_waves.json`
+
+
+
+## Cursor CLI watch (preferred for monitoring)
+
+Readable live progress in the **Cursor integrated terminal** (not a background shell task):
+
+```bash
+node .cursor/aaac/scripts/remediation/remediation-cli.mjs watch \
+  --run-id <run_id> --campaign-id <campaign_id>
+```
+
+Each cycle prints a line like:
+`[remediate] iter 8 | execute/wave_fix wave 1 | score 45/100 | health 88.7 → yield execute_wave`
+
+Snapshot SSOT: `.cursor/aaac/state/campaigns/<campaign_id>/progress.json`
+
+One-shot status:
+```bash
+node .cursor/aaac/scripts/remediation/remediation-cli.mjs status --campaign-id <id> --run-id <run_id>
+```
+
+Via Cursor agent CLI (agent session supervises the watch command):
+```bash
+node .cursor/aaac/scripts/remediation/remediation-cli.mjs cursor --run-id <run_id> --campaign-id <id>
+# or: .cursor/aaac/scripts/remediation/remediation-cursor-watch.sh <run_id> <campaign_id>
+```
+
+## Continuous yield watcher (headless / CI)
+
+Runs until `satisfaction_threshold` is met (extends `max_iterations` if needed):
+
+```bash
+node .cursor/aaac/scripts/remediation/remediation-yield-watcher.mjs \
+  --run-id <run_id> --campaign-id <campaign_id>
+# Monitor: ^AGENT_REMEDIATION_WATCHER
+```
+
+Each cycle: health-check → runner `--until-yield` → `handle-yield.mjs` (scriptable + Cursor agent for code waves) → `--ack-yield` → repeat.
+
+Background via daemon:
+
+```bash
+.cursor/aaac/scripts/remediation/remediation-runner-daemon.sh <run_id> <campaign_id>
+```
+
+Focus is parsed from campaign intent (`focus: Health Functions >60 LOC`, protected paths, wave intents).
+
+## Autonomous loop (mandatory pattern)
+
+```text
+1. health-check
+2. runner --until-yield  (or daemon script)
+3. if exit 0 → validate + report → done
+4. if exit 3 → read runner-yield.json → do agent work → --ack-yield <type> → goto 1
+5. if exit 1 → journal + user handoff (blocked)
+```
+
+### Commands
+
+```bash
+# Status
+node .cursor/aaac/scripts/remediation/remediation-runner.mjs \
+  --run-id <run_id> --campaign-id <campaign_id> --status
+
+# Health (stall / regression)
+node .cursor/aaac/scripts/remediation/runner-health-check.mjs \
+  --campaign-id <campaign_id>
+
+# Automated burst (stops at yield)
+node .cursor/aaac/scripts/remediation/remediation-runner.mjs \
+  --run-id <run_id> --campaign-id <campaign_id> --until-yield
+
+# Background daemon with sentinel (optional)
+.cursor/aaac/scripts/remediation/remediation-runner-daemon.sh \
+  <run_id> <campaign_id>
+# Monitor: ^AGENT_REMEDIATION_RUNNER
+```
+
+## Yield handlers
+
+| `yield.type` | Agent work | Ack |
+|--------------|------------|-----|
+| `check_swarm` | 7 parallel Task agents → `iterations/{n}/check-swarm-raw.json` | `--ack-yield check_swarm` |
+| `dispatch_queue` | Write `dispatch-queue.yaml` from merge synthesis | `--ack-yield dispatch_queue` |
+| `execute_wave` | Inline `fix-module` / `fix-app` per wave intent; update `execute_waves.json` | `--ack-yield execute_wave` |
+| `remediator` | Run handoff from `remediator-handoff-attempt-*.json` inline | `--ack-yield remediator` |
+| `report` | Write `artifacts/report.md`, complete Run | `--ack-yield report` |
+
+After each ack:
+
+```bash
+node .cursor/aaac/scripts/remediation/remediation-runner.mjs \
+  --run-id <run_id> --campaign-id <campaign_id> --ack-yield <type>
+```
+
+Then immediately `--until-yield` again.
+
+### check_swarm yield (7 agents)
+
+Read `iterations/{n}/check-context.json`. Launch in **one message**:
+
+- 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
+
+Merge parent writes `check-swarm-raw.json`, then:
+
+```bash
+node .cursor/aaac/scripts/remediation/merge-check-swarm.mjs \
+  --campaign-id <id> --iteration <n> --run-id <run_id>
+```
+
+Parent writes `dispatch-queue.yaml` + `artifacts/check_synthesis.md`, then `--ack-yield check_swarm`.
+
+### execute_wave yield
+
+1. Read `artifacts/plan_waves.yaml` wave `wave_index`
+2. Respect `artifacts/protected_paths.yaml`
+3. Apply fix inline (no nested AAAC Run)
+4. Record wave in `artifacts/execute_waves.json` (`completed` | `degraded` | `deferred`)
+5. `--ack-yield execute_wave` → runner runs regression gate
+
+### remediator yield
+
+1. Read `yield.handoff` or latest `remediator-handoff-attempt-*.json`
+2. Fix inline per [remediation-remediator.md](../../../../agents/remediation-remediator.md)
+3. `--ack-yield remediator` → runner retries gate with `attempt + 1`
+
+## Safety checks (`runner-health-check.mjs`)
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `stall_ticks` | Score/clones flat too long | Change wave plan or fix stuck yield |
+| `yield_timeout` | Agent yield stale | Complete ack or escalate |
+| `dupes_regression` | Clone groups grew >5% vs baseline | Stop deletes; re-run check_swarm |
+| `health_regression` | Health dropped >2 pts | Roll back last wave |
+| `flat_satisfaction` | 3 iterations same score | Prioritize dupes/health waves |
+
+Exit **1** from health check → investigate before continuing automated runner.
+
+## Resume paused campaign (chat died at iteration N)
+
+```bash
+# 1. Find run + campaign from campaign.json
+cat .cursor/aaac/state/campaigns/<campaign_id>/campaign.json
+
+# 2. Init runner state from manifest (if missing)
+node .cursor/aaac/scripts/remediation/remediation-runner.mjs \
+  --run-id <run_id> --campaign-id <campaign_id> --status
+
+# 3. If phase=scan and iter 3 has stale artifacts from older run, re-scan:
+node .cursor/aaac/scripts/remediation/fallow-scan.mjs \
+  --campaign-id <id> --iteration <n>
+
+# 4. Babysit loop
+```
+
+## Completion
+
+Only when runner exits **0**:
+
+```bash
+node .cursor/aaac/scripts/remediation/validate-campaign-complete.mjs \
+  --campaign-id <id> --iteration <n> \
+  --require-debt-sweep --require-satisfaction-loop
+```
+
+Write report if `yield.type=report` not yet acked.
+
+## Related
+
+- [orchestrator/SKILL.md](../orchestrator/SKILL.md) — phase contracts
+- [check-swarm/SKILL.md](../check-swarm/SKILL.md) — 7-agent mirror
+- `/remediate-app` command — manual + runner bootstrap

package/templates/cursor/skills/shared/remediation/check-swarm/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: remediate-check-swarm
+description: >-
+  Remediation check_swarm — mirrors /check-app and /check-architecture before
+  Fallow-driven fix waves. Readonly. Prevents false-positive deletions.
+disable-model-invocation: true
+---
+
+# Remediation check_swarm
+
+**Readonly.** Runs after `fallow-scan.mjs` + `classify-fallow-issues.mjs`. **No code edits** in this phase.
+
+Mirrors two AAAC check commands with Fallow-scoped intent:
+
+| Mirror | Question | Object skills (graph) |
+|--------|----------|------------------------|
+| `/check-app` | Which Fallow dead-code/dupes hits are **live app surface** (workers, barrels, lazy routes, payment providers)? | `architecture`, `integration` |
+| `/check-architecture` | Which proposed deletions/dedup extractions would **break boundaries, SSOT, or runtime graphs**? | `architecture`, `documentation` |
+
+## Preflight (parent — mandatory)
+
+```bash
+node .cursor/aaac/scripts/remediation/prepare-check-context.mjs \
+  --campaign-id <id> --iteration <n> [--run-id <run_id>]
+```
+
+Read `iterations/{n}/check-context.json` — SSOT input for every agent.
+
+## Swarm (mandatory — **7 parallel Task agents**, one message)
+
+Each agent: `subagent_type: explore`, `readonly: true`. Prompt **must** include policy from [_task-prompt-policy.md](../../_task-prompt-policy.md), `check-context.json` path, and agent spec path.
+
+### Wave A — check-app mirror (3 agents)
+
+| # | Agent spec | Base agent | Focus |
+|---|------------|------------|-------|
+| 1 | [remediation-check-app-inventory.md](../../../../agents/remediation-check-app-inventory.md) | discovery-inventory | Entry points, workers, dynamic imports, overlay barrels vs Fallow `unused_files` |
+| 2 | [remediation-check-app-ssot.md](../../../../agents/remediation-check-app-ssot.md) | discovery-ssot | Ownership: who consumes each `review`/`true_positive` symbol; runtime vs static |
+| 3 | [remediation-check-app-trace.md](../../../../agents/remediation-check-app-trace.md) | check-capability-trace | `fallow dead-code --trace-file` / `--trace` for top `review` items in context |
+
+### Wave B — check-architecture mirror (3 agents)
+
+| # | Agent spec | Base agent | Focus |
+|---|------------|------------|-------|
+| 4 | [remediation-check-architecture-boundaries.md](../../../../agents/remediation-check-architecture-boundaries.md) | boundary-review | Layer violations, cross-module coupling on delete candidates |
+| 5 | [remediation-check-architecture-deps.md](../../../../agents/remediation-check-architecture-deps.md) | dependency-analysis | Import cycles, fan-in, blast radius of file/export removal |
+| 6 | [remediation-check-architecture-decomposition.md](../../../../agents/remediation-check-architecture-decomposition.md) | system-decomposition | Dupes families (operations/, workers/ mirrors); safe extract vs delete |
+
+### Wave C — remediation guard (1 agent)
+
+| # | Agent spec | Focus |
+|---|------------|-------|
+| 7 | [remediation-check-risk.md](../../../../agents/remediation-check-risk.md) | Confirm FP traps; **must** output `false_positives[]` for `merge-check-swarm.mjs` |
+
+**Dispatch planner** is parent synthesis (not a Task agent) after merge.
+
+## Agent return shape (mandatory JSON block in final message)
+
+```json
+{
+  "agent_id": "remediation-check-app-inventory",
+  "command_mirror": "check-app",
+  "answer": "yes | no | partial",
+  "confidence": "high | medium | low",
+  "false_positives": [
+    { "path": "src/hooks/useCryptoPriceWorker.ts", "export_name": null, "reason": "worker_hook_runtime", "evidence": "path:line" }
+  ],
+  "protected_paths": ["src/overlays/renderers/line/index.ts"],
+  "do_not_delete": [{ "path": "...", "reason": "..." }],
+  "safe_to_fix": [{ "path": "...", "category": "unused_export", "evidence": "path:line" }],
+  "findings": ["bullet"],
+  "gaps": ["what was not confirmed"]
+}
+```
+
+## Post-swarm merge (parent — mandatory)
+
+1. Collect all 7 JSON blocks into `iterations/{n}/check-swarm-raw.json`
+2. Run merge:
+
+```bash
+node .cursor/aaac/scripts/remediation/merge-check-swarm.mjs \
+  --campaign-id <id> --iteration <n> [--run-id <run_id>]
+```
+
+3. Re-read `iterations/{n}/fallow-classification.json` (merge re-runs classifier)
+
+## Parent artifacts (run + campaign)
+
+| Artifact | Mirrors |
+|----------|---------|
+| `artifacts/check_app_validate.yaml` | `/check-app` validate phase |
+| `artifacts/check_architecture_fitness.yaml` | `/check-architecture` fitness phase |
+| `artifacts/check_synthesis.md` | Combined Answer + How + guardrails |
+| `artifacts/dispatch-queue.yaml` | Ranked waves — **must** include `protected_paths` |
+| `artifacts/protected_paths.yaml` | Paths/regions waves must not delete |
+| `iterations/{n}/check-swarm-merge.json` | Merged FP registry + actionable list |
+
+## Dispatch guardrails (mandatory in every wave intent)
+
+Every wave in `dispatch-queue.yaml` **must**:
+
+1. Copy `protected_paths` from merge output verbatim into `exclude:` block
+2. Never target paths classified `false_positive` in `fallow-false-positives.json`
+3. Prefer `fix-module` export trim over file delete when classification is `review`
+4. Run `fallow dead-code --trace-file` before any `remove-module` / file delete wave
+
+## Anti-patterns (forbidden)
+
+- Skipping check-app or check-architecture mirrors (all 7 agents required)
+- Deleting files from Fallow `unused_files` without trace-file evidence
+- Bulk `fallow fix --yes` without swarm FP review
+- Planning waves from raw Fallow totals (use `actionable_total` + merge output)
+- Ignoring dupes **main/worker mirror** families — extract shared, do not delete one side

package/templates/cursor/skills/shared/remediation/orchestrator/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: remediate-app-orchestrator
+description: >-
+  Orchestrates /remediate-app — Fallow scan, check swarm, ranked fix waves,
+  regression wave gates, mandatory debt sweep, satisfaction loop.
+disable-model-invocation: true
+---
+
+# remediate-app orchestrator
+
+Campaign loop for whole-repo health remediation. Model after [platform-release/orchestrator](../../platform-release/orchestrator/SKILL.md) wave blocking.
+
+Fallow scan suite: **dead-code** + **dupes** + **health** (all three run every iteration via `fallow-scan.mjs`).
+
+Contract: [contract.yaml](./contract.yaml)
+
+## Hard invariants (never violate)
+
+| Rule | Meaning |
+|------|---------|
+| **Exit 3 ≠ stop** | `remediator-gate` / `debt-sweep-gate` exit **3** means **remediate and retry**. Never set `campaign.status=blocked`, never skip remaining waves, never advance to `report`. |
+| **Wave = regression** | Pre-existing typecheck/vitest debt does **not** block wave promotion. Only **new** regressions vs pre-wave snapshot trigger wave remediator. |
+| **Debt sweep = strict** | After all waves, `debt_sweep` must reach **zero errors** on all layers before `satisfaction_gate` or `report`. |
+| **All waves run** | Every wave in `plan_waves.yaml` must execute (status `completed`, `degraded`, or `deferred`) — never skip waves 2–3 because wave 1 handed off. |
+| **Validate before report** | Run `validate-campaign-complete.mjs --require-debt-sweep --require-satisfaction-loop`; exit 1 → do not complete Run. |
+| **Satisfaction exit 3 ≠ report** | `satisfaction-loop-gate` exit **3** → `--advance` to next iteration, return to `scan`. |
+| **Immutable Fallow start** | `fallow-start-baseline.json` (dead-code), `fallow-start-dupes-baseline.json`, `fallow-start-health-baseline.json` written once; dupes/health auto-backfill if missing |
+
+## Parse
+
+| Slot | Rule |
+|------|------|
+| Domain | Optional — `frontend`, `backend`, or omit for `whole-repo` |
+| Intent | `max_iterations`, `max_waves_per_iteration`, `max_remediator_attempts_per_wave`, `max_remediator_attempts_per_debt_round`, `max_debt_sweep_rounds`, `satisfaction_threshold`, `resume campaign_*`, `autonomous` / `manual` |
+
+**Autonomous mode (baked in):** `init-campaign.mjs` sets `config.autonomous` when any of:
+
+- intent contains `autonomous`
+- `satisfaction_threshold >= 100`
+- `max_iterations >= 10`
+
+Override off with `manual` in intent.
+
+When `config.autonomous === true`, **do not walk phases manually**. Read [babysit/SKILL.md](../babysit/SKILL.md) and follow `artifacts/autonomous_bootstrap.json` → `next_action` until runner exit **0**.
+
+**Preflight:** When `remediation.verify.playwright.enabled`, ensure dev server is reachable at `project.config.json` → `remediation.verify.dev_server.url` before debt sweep / Playwright gates.
+
+## Scripts (mandatory)
+
+| Step | Command |
+|------|---------|
+| Init campaign | `node .cursor/aaac/scripts/remediation/init-campaign.mjs --run-id <run_id> --scope whole-repo --intent "<intent>"` |
+| Verify baseline | `node .cursor/aaac/scripts/remediation/capture-verify-baseline.mjs --campaign-id <id> --run-id <run_id>` |
+| Fallow scan | `node .cursor/aaac/scripts/remediation/fallow-scan.mjs --campaign-id <id> --iteration <n> [--save-baseline]` — runs dead-code, dupes, health |
+| Classify Fallow | `node .cursor/aaac/scripts/remediation/classify-fallow-issues.mjs --campaign-id <id> --iteration <n>` (auto after scan) |
+| Prepare check context | `node .cursor/aaac/scripts/remediation/prepare-check-context.mjs --campaign-id <id> --iteration <n> --run-id <run_id>` |
+| Merge check swarm | `node .cursor/aaac/scripts/remediation/merge-check-swarm.mjs --campaign-id <id> --iteration <n> --run-id <run_id>` |
+| Record false positive | `node .cursor/aaac/scripts/remediation/record-fallow-fp.mjs --campaign-id <id> --path <file> --classification false_positive` |
+| Pre-wave snapshot | `node .cursor/aaac/scripts/remediation/capture-wave-snapshot.mjs --campaign-id <id> --iteration <n> --wave-index <w>` |
+| Wave gate | `node .cursor/aaac/scripts/remediation/remediator-gate.mjs --campaign-id <id> --iteration <n> --mode wave --wave-index <w> --run-id <run_id> --attempt 1` |
+| Debt sweep | `node .cursor/aaac/scripts/remediation/debt-sweep-gate.mjs --campaign-id <id> --iteration <n> --run-id <run_id> --round 1 --attempt 1` |
+| Validate complete | `node .cursor/aaac/scripts/remediation/validate-campaign-complete.mjs --campaign-id <id> --iteration <n> --require-debt-sweep` |
+| Satisfaction | `node .cursor/aaac/scripts/remediation/compute-satisfaction.mjs --campaign-id <id> --iteration <n>` |
+| Satisfaction loop gate | `node .cursor/aaac/scripts/remediation/satisfaction-loop-gate.mjs --campaign-id <id> --iteration <n> --run-id <run_id> [--advance]` |
+| Repair Fallow start | `node .cursor/aaac/scripts/remediation/repair-fallow-start-baseline.mjs --campaign-id <id> --total <n>` |
+| Journal step | `node .cursor/aaac/scripts/remediation/record-iteration-step.mjs --campaign-id <id> --step <name> --detail "..." --status pass\|fail` |
+
+## Phases
+
+### 1. campaign_init
+
+1. Run `init-campaign.mjs`
+2. If `config.autonomous` → read `artifacts/autonomous_bootstrap.json` and **[babysit/SKILL.md](../babysit/SKILL.md)**; enter runner loop (skip manual phase walk below)
+3. Run `capture-verify-baseline.mjs` (records pre-campaign error counts) — runner also does this on first tick if resuming
+4. Write `artifacts/campaign.json` and `artifacts/verify_baseline.json`
+
+**Autonomous first action after init:**
+
+```bash
+node .cursor/aaac/scripts/remediation/runner-health-check.mjs --campaign-id <id>
+node .cursor/aaac/scripts/remediation/remediation-runner.mjs \
+  --run-id <run_id> --campaign-id <id> --until-yield
+```
+
+Then babysit loop until exit **0**. Never end turn on exit **3**.
+
+### 2. scan
+
+1. Set iteration `n = campaign.iteration`
+2. Run `fallow-scan.mjs --save-baseline` **only** when:
+   - New campaign (`fallow-start-baseline.json` missing), or
+   - Starting a **new** iteration (`n > 0` or first scan after `--advance`)
+3. On **resume** of same iteration: run `fallow-scan.mjs` **without** `--save-baseline`
+
+Readonly. No code edits.
+
+### 3. check_swarm (parallel — **7 Task agents**, one message)
+
+**Skill:** [check-swarm/SKILL.md](../check-swarm/SKILL.md) — mirrors `/check-app` + `/check-architecture`.
+
+**Preflight:**
+
+```bash
+node .cursor/aaac/scripts/remediation/prepare-check-context.mjs \
+  --campaign-id <id> --iteration <n> --run-id <run_id>
+```
+
+| Wave | Agent spec | Mirrors |
+|------|------------|---------|
+| A1 | remediation-check-app-inventory | `/check-app` inventory |
+| A2 | remediation-check-app-ssot | `/check-app` SSOT |
+| A3 | remediation-check-app-trace | `/check-app` trace (+ `fallow --trace-file`) |
+| B1 | remediation-check-architecture-boundaries | `/check-architecture` boundaries |
+| B2 | remediation-check-architecture-deps | `/check-architecture` dependencies |
+| B3 | remediation-check-architecture-decomposition | `/check-architecture` dupes families |
+| C1 | remediation-check-risk | FP registry guard |
+
+**Post-merge (mandatory):**
+
+```bash
+# Parent writes iterations/{n}/check-swarm-raw.json from agent JSON blocks first
+node .cursor/aaac/scripts/remediation/merge-check-swarm.mjs \
+  --campaign-id <id> --iteration <n> --run-id <run_id>
+```
+
+**Parent synthesis:** `artifacts/check_synthesis.md`, `artifacts/dispatch-queue.yaml` (include `protected_paths` from merge)
+
+Outputs: `check_app_validate.yaml`, `check_architecture_fitness.yaml`, `protected_paths.yaml`, `check_swarm_merge.json`, updates `fallow-false-positives.json`
+
+**Fallow SSOT:** Dead-code raw counts are not remediation truth. After scan, `classify-fallow-issues.mjs` splits dead-code into `true_positive`, `review`, and `false_positive`. Satisfaction uses **actionable** dead-code, **clone_groups** (dupes), and **health_score** (health). Swarm-confirmed false positives go to `record-fallow-fp.mjs` → `fallow-false-positives.json`.
+
+### 4. plan_waves
+
+1. Validate dispatch queue entries
+2. Truncate to `max_waves_per_iteration`
+3. Write `artifacts/plan_waves.yaml`
+
+Readonly.
+
+### 5. execute (sequential waves only)
+
+For **each** wave in `plan_waves.yaml`:
+
+1. `capture-wave-snapshot.mjs --wave-index <w>` (pre-wave metrics)
+2. Apply fix per wave `command` + `intent` (inline fix-* orchestrator — no nested Run)
+3. **Remediator sub-loop (mandatory):**
+
+```text
+attempt ← 1
+loop:
+  remediator-gate --mode wave --wave-index <w> --attempt <attempt>
+  if action in (promote, promote_wave, defer_to_debt_sweep) → break  # continue to NEXT wave
+  if action=remediate (exit 3):
+    run remediation-remediator handoff inline
+    attempt ← attempt + 1
+    goto loop   # NEVER stop campaign here
+  if action=infrastructure → fix infra, retry
+```
+
+4. Record wave status `completed` | `degraded` | `deferred` in `artifacts/execute_waves.json`
+5. **Always proceed to next wave** — never abort execute phase on exit 3
+
+### 6. debt_sweep (mandatory strict gate)
+
+Clears **all** remaining errors (old + new). Runs after every iteration's execute phase.
+
+```text
+round ← 1
+attempt ← 1
+loop:
+  debt-sweep-gate --round <round> --attempt <attempt>
+  if action=debt_sweep_complete → break
+  if action=remediate (exit 3):
+    run remediation-remediator handoff inline
+    attempt ← attempt + 1
+    goto loop
+  if action=debt_sweep_next_round → round++, attempt←1, goto loop
+  if action=debt_sweep_blocked → campaign blocked (only after max_debt_sweep_rounds)
+```
+
+Full logs: `iterations/{n}/verify-logs/debt-*.log`  
+Artifacts: `artifacts/debt_sweep.json`, `verify-debt.json`
+
+### 7. satisfaction_gate
+
+```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
+```
+
+| Gate exit | Action |
+|-----------|--------|
+| `0` + `action: complete` | Threshold met → `report` |
+| `0` + `action: partial_complete` | Max iterations → `report` (partial) |
+| `3` + `action: continue_loop` | **Return to `scan`** for `next_iteration` — **never report** |
+| `1` | Debt/verify prerequisites missing — fix first |
+
+**Fallow start baseline** is immutable (`fallow-start-baseline.json`). Never rescored from resume scans.
+
+### 8. report
+
+**Before writing report:**
+
+```bash
+node .cursor/aaac/scripts/remediation/validate-campaign-complete.mjs \
+  --campaign-id <id> --iteration <n> --require-debt-sweep --require-satisfaction-loop
+```
+
+If violations → do not complete Run. `satisfaction_loop_blocks_report` means iteration 1+ was required.
+
+## Autonomous platform
+
+For multi-iteration campaigns, use the shell runner + babysit skill instead of relying on chat stop-hook loops.
+
+| Component | Role |
+|-----------|------|
+| `remediation-runner.mjs` | Drives scriptable phases; **yields** (exit 3) for agent work |
+| `remediation-runner-daemon.sh` | Background automated bursts; emits `AGENT_REMEDIATION_RUNNER` |
+| `runner-health-check.mjs` | Stall, regression, yield-timeout detection |
+| [babysit/SKILL.md](../babysit/SKILL.md) | Handles yields, acks, safety |
+
+```bash
+node .cursor/aaac/scripts/remediation/remediation-runner.mjs \
+  --run-id <run_id> --campaign-id <id> --until-yield
+# exit 3 → babysit → --ack-yield <type> → repeat
+```
+
+Runner state: `campaigns/{id}/runner-state.json`, yields: `runner-yield.json`.
+
+## Two-tier validation
+
+| Tier | When | Pass condition |
+|------|------|----------------|
+| **Regression** | After each cleanup wave | Error counts did **not increase** vs pre-wave snapshot |
+| **Strict** | `debt_sweep` phase | typecheck, vitest, go test, build, Playwright all pass; `total_errors === 0` |
+
+## Anti-patterns (forbidden)
+
+- Treating remediator exit **3** as campaign stop
+- Setting `campaign.status=blocked` on wave handoff
+- Skipping waves because verify failed on pre-existing debt
+- Completing Run while `debt_sweep` pending or remediator loop `running`
+- Writing report when `satisfaction-loop-gate` exits **3**
+- Re-scanning with `--save-baseline` on resume (overwrites immutable start baseline)
+- Using stderr tails only — read `verify-logs/*.log` for full evidence
+- Bulk `fallow fix --yes` without trace-file
+
+## Persistence paths
+
+```
+.cursor/aaac/state/campaigns/{campaign_id}/
+  campaign.json
+  fallow-start-baseline.json
+  fallow-start-dupes-baseline.json
+  fallow-start-health-baseline.json
+  journal.md
+  iterations/{n}/
+    fallow-scan.json
+    fallow-dupes.json
+    fallow-health.json
+    fallow-scan-bundle.json
+    fallow-scan-bundle.json
+    fallow-classification.json
+    check-context.json
+    check-swarm-raw.json
+    check-swarm-merge.json
+    protected-paths.json
+    verify-wave.json
+    verify-debt.json
+    verify-logs/
+    debt-sweep-state.json
+    remediator-loop-wave-{w}.json
+```