env-doctor — Execution Environment Diagnostics & Remediation

Operating Invariants

Idempotent Local Boundary: Confine remediation strictly to project-scoped actions (declared dependency sync, local service boot, test datastore migration, synthetic test secrets); forbid system-wide mutations (sudo, brew), host PATH tampering, or remote secret fetching. Halt with UNRESOLVED for port collisions, missing daemons, or destructive actions.
Zero-Secret Exposure: Never inspect or copy production secret files (.env* except .env.example); inject deterministic mocks into .env.test or environment stubs.
Manifest SSOT Grounding: Read .agents/environment.md as the authoritative specification. Treat omissible sections (services for pure libraries, external datastores) as PASS when absent.
Adaptive Invocation Output: Render the full Canonical Output Contract when invoked by a human; output only a single-line Micro-Summary token (READY or UNRESOLVED: <blocker>) when called by an autonomous runner.

Domain Rubric

1. Dimension Audit & Probing Discipline

Cross-reference declared manifests against host runtimes and execution wrappers (pnpm, cargo, uv). Execute declared service readiness probes (socket, HTTP /healthz, database ping) with exponential backoff (max 15s); forbid treating process state (Up) as readiness. Verify test datastore migrations, fixtures, and synthetic .env.test stubs.

Canonical Output Contract

# Environment Health Report: <Scope> · <READY | STAGED | UNRESOLVED>