infrastructure-doctor

Doctor Module

Repository-level "doctor mode": a diagnostic engine plus an automated, audited resolution engine. The doctor never leaves the patient worse off — every mutation is snapshotted before it runs and can be reversed by a single undo command.

Quick start

# Diagnose only (read-only).
uv run python -m infrastructure.doctor

# Same, JSON for an agent.
uv run python -m infrastructure.doctor --json diagnose

# Show what would be fixed (no changes).
uv run python -m infrastructure.doctor fix --plan

# Apply the safest set of fixes.
uv run python -m infrastructure.doctor fix --apply

# Allow `uv sync` and other moderate-therapy fixes.
uv run python -m infrastructure.doctor fix --apply --moderate

# Allow radical fixes (e.g. delete orphan output directories — still backed up).
uv run python -m infrastructure.doctor fix --apply --aggressive

# Reverse the most recent applied, reversible action.
uv run python -m infrastructure.doctor undo --last

# Reverse one specific action (see `history`).
uv run python -m infrastructure.doctor undo --action-id <id>

# Inspect the journal.
uv run python -m infrastructure.doctor history

# Agent-facing capability manifest.
uv run python -m infrastructure.doctor capabilities

# Stable-text robot manual.
uv run python -m infrastructure.doctor robot-docs

Safety contract

Every fix flows through infrastructure.doctor.safety.mutate(plan, state). That function is the only code in this module that writes to the filesystem on behalf of a fixer. It guarantees:

1. Paths in plan.affected_paths are resolved and confirmed to be inside the repo and outside .doctor/.
2. Every existing path is copied byte-for-byte into .doctor/backups/<action_id>/ and its SHA-256 is recorded.
3. The registered handler for plan.action_kind runs (delete_paths, chmod, write_file, run_uv_sync).
4. Post-mutation hashes are taken; the result is appended to .doctor/actions.jsonl as a single JSON line.
5. If the handler raises, the journal still records the attempt with applied=false and error populated — audit is never silently lost.