doctor

Cladding doctor

Run clad doctor from the project root. The verb is observability — it never mutates the working tree.

• --cwd <path> — read events from a project directory other than the current one (default cwd).
• --json — emit the raw DoctorReport shape instead of the formatted text surface; the additive shape ({cwd, events, sentinelMiss, governance, hooks, ciVersion}) is the stable wire format for MCP clients and follow-up tooling.

The text surface prints:

1. One pulse line with total events and total sentinel-miss count (pass when zero misses, note otherwise).
2. An event-type breakdown line (one <type>=<count> token per non-zero EventType).
3. Claude Code hook health: whether the runtime has actually been observed, whether the observed engine version matches the current CLI, and the last firing time (or never observed) for session start, prompt submit, before edit, after edit, and session stop.
4. A non-blocking CI warning naming each GitHub Actions workflow that invokes an unversioned or floating npx cladding package. Numeric selectors such as [email protected] and [email protected] stay quiet.
5. Governance counts for gate runs, done attempts and rejections, stop blocks, known-failing Stop exits, blocked fingerprints reproduced by a later gate, and attestation state.
6. When sentinel-miss events exist:
   • by phase / by cause / by fallback aggregates from the v0.3.39 telemetry payload.
   • Top-5 missed sentinels (CONVENTIONS_MD / ARCHITECTURE_YAML / SCENARIO_FLOWS / CAPABILITIES_YAML / WHY / WHAT / PURPOSE) sorted by count desc, name asc.
   • Last 3 unique dispatcher error strings (most recent first; errors are truncated to 200 chars at the emit site).
   • A one-line tuning hint.

Exit codes

• 0 — events.log was either missing (greenfield) or readable. A greenfield workspace prints a friendly note and exits 0; a healthy host with zero misses also exits 0 with a pass line.
• 1 — events.log.jsonl exists but cannot be parsed as JSONL (corrupt telemetry).