/health-audit

name: health-audit
description: Maintainer-only autonomous health audit + auto-heal loop. Runs N=3 fresh-team audit-fix-audit cycles with circuit breakers, reports an F-to-A+ verdict (folding in the shared Claude-integration fitness grade) or escalates.

/health-audit

Maintainer-only. You are the **Orchestrator** for a GAIA health audit.

Pre-flight: Worktree check

This command runs fresh-team audit-fix cycles that commit against the clone. If invoked from a linked worktree, reject hard: `gaia_refuse_if_worktree` (`.gaia/scripts/main-only-lib.sh`) asks the shared resolver which tree this is and refuses out loud, naming the main checkout, when the answer is a worktree.

Detection (run this first, before anything else):

. .gaia/scripts/main-only-lib.sh
gaia_refuse_if_worktree "/health-audit" || exit 1

If the detection does not fire, fall through to `## Step 1, Read the runbook` below.

Step 1, Read the runbook

Read `.gaia/cli/health/runbook.md` end-to-end before doing anything else. The runbook codifies role structure, bucket definitions, fixer lane mapping, model selection, circuit breakers, and escalation criteria. Do not improvise around it.

Step 2, Run the loop

Execute the cycle loop defined in the runbook's **§Cycle loop** (max N=3), applying the **§Termination** section's oscillation-threshold definition to detect a stuck fix. Both sections were already read in full at Step 1. **Do not restate the loop or the oscillation definition here.** The runbook is the single source of truth for this control flow.

Bucket E runs the shared Claude-integration fitness protocol defined in `wiki/decisions/Claude Integration Fitness.md` over every fitness category that page defines. The Bucket E auditor does not re-specify those checks, it reads the wiki page and runs its protocol. Fitness findings route to the existing `claude-surface` Fixer lane.

On the first cycle that meets the clean gate, you spawn a false-clean challenger (BS/MC/GH lenses always, FV when a prior cycle ran a Fixer) before the A+ report and the RUN_DIR deletion; a substantiated finding revokes the clean exit, injected as `real-fix` (non-cycle-3) or escalated `false-clean-refuted` (cycle 3). It runs at most once per run. The runbook's §False-clean challenger is the source of truth.

You spawn the five buckets, the Adjudicator, and the Fixers, and every one is a leaf subagent, because a subagent cannot spawn another subagent (the hard depth-1 limit). So you, the Orchestrator on this main thread, own every spawn. Stay mechanical: counters, directory creation, disk reads, the `jq`/`comm` oscillation compare, and dispatch. You never audit, adjudicate, or fix in your own context, so whatever session state you inherit cannot bias a grade.

A fresh Adjudicator per cycle keeps prior-cycle findings from bleeding into this cycle's verification: it never reads a prior cycle's `findings.json` (you own the cross-cycle oscillation compare), so every cycle's Adjudicator starts on clean context. **Bucket E** runs as its own leaf so its voluminous raw fitness output stays on disk and out of the Adjudicator's context: the Adjudicator reads only Bucket E's findings JSON. Each bucket is spawned with its assigned model (Haiku for the mechanical buckets, Sonnet for the judgment-bearing ones; see the runbook's model table), which pins per-bucket models correctly now that the Orchestrator dispatches them directly.

Step 3, Comprehensive phase (post-loop)

After the loop above breaks or escalates — clean exit and escalation both route through here — and before the Step 5 report is emitted, run the **Comprehensive Audit phase** per `.gaia/cli/health/comprehensive/runbook.md`. It is diff-gated (a pre-flight gauge picks skip / scoped / full), report-only (no auto-heal, files nothing), and maintainer-only.

• Runs **exactly once**, **never inside the loop above**.
• Pass `--comprehensive-full` through to the gauge when the maintainer invoked `/health-audit` with that force flag. Pass `--major` through when the maintainer invoked `/health-audit --major` (the gauge maps it to `source=major`).
• Surfaces only the **top findings by consequence** for the filing offer, discarding the lower-consequence tail (the runbook's `COMPREHENSIVE_FILE_CAP`); it never restocks the tech-debt backlog with every confirmed finding.
• **Do not copy the comprehensive protocol here.** The comprehensive runbook is the single source of truth; this command file only points to it.
• Does **not** recompute or mutate the integrity verdict math (the three-input floor). It reports alongside, in Step 5.

Step 4, Honor the circuit breakers

Follow the runbook's **§Circuit breakers**, already read in full at Step 1. **Do not restate the breaker list here.** The runbook is the single source of truth for this list.

If the human refuses → escalate.

Step 5, Report

On clean exit (no open findings remain; the reported grade is the honest floor: A+ when there were no findings at all, otherwise capped by any non-blocking residual `info`, typically A):

HEALTH AUDIT: <overall grade, A+ or A>
Overall grade: <A+ | A>
Shared-fitness grade: <honest floor of the category grades>
Cycles: <N>
Findings closed: <count> (per cycle: <breakdown>)
Non-blocking residuals: <count> (e.g. wiki/.state.json post-sync drift, recorded not blocking)
Artifacts: cleaned (this run's .gaia/local/audit/archived/<stamp>/ folder removed)
comprehensive: skipped (no framework-facing changes since <tag>)

On escalation:

HEALTH AUDIT: ESCALATED
Overall grade: <F-to-A+, floor of Bucket D verdict, findings-count signal, shared-fitness grade>
Shared-fitness grade: <F-to-A+, floor of the category grades from Bucket E>
Reason: <max-loops | oscillation | circuit-breaker | unclassified-finding | fixer-unable-to-fix | false-clean-refuted>
Outstanding findings: <list with fingerprints>
Cycles run: <N>
Artifacts: preserved at .gaia/local/audit/archived/<stamp>/c1/, c2/, c3/ (see fi