aura doctor

Diagnose repository health; optionally fix common issues in place.

Synopsis

aura doctor [--fix] [--reindex] [--check=<id>...] [--verbose] [--json]

Description

aura doctor runs a battery of diagnostic checks over the Aura installation in the current repository and reports their results. Each check has an id, a severity, a human-readable finding, and — for most checks — a --fix path that repairs the issue automatically. Running aura doctor with no flags performs the checks read-only; running with --fix applies repairs for every check that has a safe automatic remediation and prints a summary of what was changed. Checks with dangerous remediations (for example, deleting orphaned snapshots older than 30 days) are never auto-fixed; they print the exact command you would run.

The intended cadence is: run aura doctor when something feels off, when aura status reports a warning, after pulling a large batch of teammate changes, and as part of CI (aura doctor --json). It is idempotent and safe.

What it checks

Checks are grouped into five categories. Ids are stable across versions so you can allowlist or suppress them in aura.toml.

Index and semantic state

IDX001 — semantic index exists and is readable.
IDX002 — index age vs working tree age; triggers a suggestion to reindex if stale.
IDX003 — no AST parse errors on tracked files. Parse errors are reported per-file.
IDX004 — no orphaned logic nodes (nodes whose source file no longer exists).
IDX005 — shadow branch in sync with primary branch.

Sessions and snapshots

SES001 — no stuck sessions from previous process crashes. Fixable.
SES002 — session lock file belongs to a live process. Fixable (removes stale locks).
SNP001 — snapshot storage integrity (hashes match contents).
SNP002 — orphaned snapshots older than 30 days. Not auto-fixed; printed as a command.
SNP003 — snapshot directory size within snapshot.max_storage_mb (default 500 MB).

Git integration

GIT001 — pre-commit hook is installed and current version.
GIT002 — post-merge hook is installed.
GIT003 — .gitignore includes .aura/ excluding the bits meant to be versioned.
GIT004 — no unmerged paths left from a previous aura merge.
GIT005 — current branch has a Git remote configured.

Mothership and team sync

MOT001 — mothership endpoint reachable.
MOT002 — auth token is valid and not near expiry.
MOT003 — outgoing delta queue not stalled (no pending delta older than 10 minutes).
MOT004 — incoming cursor not behind by more than sync.max_lag_deltas (default 500).
MOT005 — clock skew vs Mothership under 5 seconds.

Configuration

CFG001 — aura.toml parses and matches the current schema version.
CFG002 — strict-mode settings consistent between local and team config.
CFG003 — registered proofs can still be grounded (otherwise they would false-fail).
CFG004 — no deprecated config keys remaining.

Flags

| Flag | Description | | --- | --- | | --fix | Apply automatic remediations for any check that has one. | | --reindex | Force a full semantic reindex before running checks. | | --check=<id>... | Run only the listed checks. Comma-separated or repeatable. | | --verbose | Print the steps each check performs. | | --json | Machine-readable output for CI. |

Output format

aura doctor  (repo: aura-cli  v0.12.6)

Index and semantic state
  ok      IDX001  index present (1,842 nodes)
  warn    IDX002  index is 14m old (threshold: 10m)            suggest: aura doctor --reindex
  ok      IDX003  no parse errors
  fail    IDX004  3 orphaned nodes (files removed outside of aura)
                  fixable: --fix will prune them

Sessions and snapshots
  ok      SES001  no stuck sessions
  ok      SES002  session lock belongs to pid 44121 (this process)
  warn    SNP002  14 snapshots older than 30 days (not auto-fixed)
                  run: aura snapshot gc --older-than 30d

Git integration
  ok      GIT001  pre-commit hook current (v12)
  fail    GIT002  post-merge hook missing
                  fixable: --fix will install it

Mothership and team sync
  ok      MOT001  origin-mothership reachable (47 ms)
  ok      MOT002  token valid until 2026-07-14
  warn    MOT003  1 delta pending for 12 minutes (teammate offline?)
  ok      MOT004  cursor lag: 0
  ok      MOT005  clock skew: 0.4s

Configuration
  ok      CFG001  aura.toml schema: v3
  ok      CFG002  strict-mode consistent
  ok      CFG003  4 proofs ground cleanly
  ok      CFG004  no deprecated keys

Summary:  ok 15  warn 3  fail 2
Run `aura doctor --fix` to apply 2 automatic remediations.

Severities are:

| Severity | Meaning | | --- | --- | | ok | No action needed. | | warn | Degraded but functional. Usually fixable, sometimes intentional. | | fail | Aura will not function correctly until addressed. |

Examples

1. Read-only diagnostic

aura doctor

2. Fix everything fixable

aura doctor --fix

Applying fixes...
  IDX004  pruned 3 orphaned nodes
  GIT002  installed post-merge hook
2 fixes applied. Re-running checks:
  ok  IDX004
  ok  GIT002

3. Scope to one category

aura doctor --check=MOT001,MOT002,MOT003

Runs only the Mothership reachability and auth checks. Good for a quick network triage.

4. Force a reindex

aura doctor --reindex --fix

Rebuilds the semantic index from scratch before running checks. Use after a large git pull, a branch switch with many changes, or when IDX002/IDX003 are persistent.

5. CI usage

aura doctor --json > aura-doctor.json
# fail the build if any check is 'fail'
jq -e '.checks[] | select(.severity == "fail")' aura-doctor.json && exit 1 || exit 0

The JSON output is stable and schema-versioned. A lightweight wrapper can fail the build on any fail, or on any warn above a configured threshold.

Common findings

IDX002 stale index. Normal after long breaks. --reindex resolves.
GIT001/GIT002 hook missing. Happens after git clone or after running a third-party git config core.hooksPath. --fix reinstalls.
MOT001 unreachable. Check VPN. Aura will continue to work locally; pushes queue until the Mothership is back.
SNP002 old snapshots. Snapshots are cheap but not free. Run aura snapshot gc when prompted.
CFG003 proof ungroundable. A registered proof is no longer valid because the code it referenced was removed. Either update the proof or delete it from aura.toml.

Exit Codes

| Code | Meaning | | --- | --- | | 0 | All checks passed (possibly with warnings, unless --strict was set via config). | | 1 | Generic failure running doctor itself. | | 2 | One or more checks are at fail severity. | | 3 | --fix was requested but one or more fixes could not be applied. |

When to run it

Run aura doctor when any of the following happens: a fresh clone of the repository; a machine migration; the first time after an Aura version upgrade; after a force-push or a history rewrite; after a network outage longer than a few minutes; whenever aura status reports a cached or stale banner; whenever a save unexpectedly fails; whenever a teammate reports that your Mothership presence is stuck.

In healthy day-to-day use, most developers run aura doctor perhaps once a week. In CI it runs on every build. The cost is a few hundred milliseconds and a small amount of I/O; there is no reason to avoid it.

A triage recipe

When aura doctor reports several warnings and failures at once, work through them in this order.

First, handle GIT001/GIT002 (hooks missing). Without the hooks, subsequent saves cannot be verified. --fix reinstalls them.

Second, handle IDX003 (parse errors). A file that does not parse has no logic nodes and therefore does not participate in diffs, traces, or proofs. Fix the parse error or exclude the file in aura.toml.

Third, handle IDX002/IDX004 (stale or orphaned index). --reindex rebuilds from scratch.

Fourth, handle MOT001/MOT002 (Mothership reachability and auth). If these are failing, team sync is offline — confirm network and refresh the token.

Fifth, handle SNP002/SNP003 (snapshot storage). These rarely block anything but can silently bloat the .aura directory.

Sixth, handle configuration checks. CFG003 in particular — a broken proof — will cause aura pr-review to report false regressions, which is confusing.

Suppressing checks

A check can be suppressed in aura.toml when it is expected to fail in a given repository:

[doctor.suppress]
IDX002 = { reason = "CI reindexes on entry; staleness is expected locally" }
SNP002 = { reason = "snapshots retained for audit, GC handled externally" }

Suppressed checks still run and are printed under a suppressed banner, but do not contribute to the exit code. Use suppression sparingly; the goal is to keep the baseline clean so real problems stand out.

Relationship to CI

In CI, the pattern is:

aura doctor --json --strict > report.json

With --strict, warnings are treated as failures. This is stricter than most teams want locally but appropriate as a gate on main. Run the non-strict version in PR checks so warnings surface without blocking.