Doctor

doctor

Adapted from donor skills/doctor/scripts/check-*.sh (one bash script per section) into a single Python check-harness (skills.doctor.lib.run_checks()) — the new checks below need to call directly into this repo's Python lib modules (collect, promotion, code-map, backup, portability), so the harness itself is Python, not bash, per this task's ADAPT (not CARRY) label.

Checks

Carried (logic ported from donor's bash):

Check	What it verifies
check_env	git + python3 on PATH, ANTHROPIC_API_KEY set
check_wiki_structure	wiki root exists, identity.md/log.md present
check_frontmatter	scripts/lint-yaml-frontmatter.py passes over the wiki
check_schema_versions	every typed page vs. skills.wiki-migration.lib's registry — behind-current pages named with their pending migration chain

Donor's Node/gh/claude-cli checks, activity-feed/RC-channel/fleet checks, and the wikilink dead-link/stale-page/heavy-page check are all dropped — see the module docstring's "DROPPED entirely" note for why each one doesn't apply here.

New (Task 7.3, all warn-not-block):

Check	What it verifies
check_budget_lint	measured capability_tokens (Task 3.1) vs. any SKILL.md-declared tokens: ceiling — info when nothing's declared to compare against yet, skip when no measured data exists
check_dangling_pointers	every l2-map page's "## Decision map" pointer targets actually exist
check_hub_convention	legacy projects/*/knowledge/**/index.md knowledge hubs still pending the folder-note-hubs-1 migration (#56) — names the first 5
check_graphify_status	importlib.import_module("skills.code-map.lib").status() — not installed → info w/ companions.md pointer; version outside pin → warn; stale graph → info
check_companions	registry choices vs reality (lib/companions) — accepted-but-missing → warn; undecided-and-absent → info; consistent → ok
check_backup_configured	skills.backup.lib.backup_configured()
check_global_drift	lib.memory.promotion.demote_check() — non-doctrine/preference pages in global/
check_harness_neutrality	lib.portability.agents_surface.lint_generated_surfaces — soft-wired: skips cleanly if that module (Task 7.2, built in parallel) isn't present
check_routing_audit	0.6.1 E4: harvested subagent_spawn metrics vs. doctrine/model-classes.md's class table — warn when >30% of spawns used orchestrator-class models or any parallel_peak > 5; info with per-class counts otherwise; info "no spawn data yet" when empty
check_model_map_staleness	0.6.1 E4: the renos:model-map-updated stamp in doctrine/model-classes.md — warn if older than 180 days, info otherwise
check_orphaned_projects	issue #19: every projects/<slug>/ reachable from a repo — warn naming each slug with neither a projects.json repo mapping nor a <dev_root>/<slug>/ dir (memory nothing can ever inject)
check_execution_doctrine	0.6.4: agents/ren-reviewer.md present (doctrine card references it) → error if missing; a manual pre-0.6.4 <!-- renos:doctrine-stopgap --> block left in ~/.claude/CLAUDE.md → warn (the wake-up hook injects the card now, the manual block is redundant residue)
check_standing_instructions_drift	#63: repo CLAUDE.md standing-instructions block matches a fresh render of the wiki page
check_agent_shadowing	0.6.5: a user or project .claude/agents/<name>.md filename colliding with a shipped agents/*.md → warn naming the colliding agent(s); checks both claude_user_dir()/agents and, when the cwd resolves to a registered project, that project's .claude/agents/; skip when neither directory exists
check_cache_env_hygiene	#40: any <cache>/<version>/.venv inside the versioned plugin cache dir → warn naming the version(s) — invocations should redirect via UV_PROJECT_ENVIRONMENT (see ren_paths.envs_dir()); ok when none found; skip when the cache root is unresolvable
check_interpreter_freshness	spec 2026-08-21 (0.8.2) §8: the wake-up hook's recorded fast-path interpreter — dangling path or non-current version → warn (fast path degraded to cold uv); valid + current → ok; no record → info; another machine's synced record → skip

Behavior

1. Call skills.doctor.lib.run_checks().
2. Each check is isolated — a crashing check produces a CheckResult(status="error", message="check crashed: ...") rather than aborting the run; every OTHER check still executes (same isolation discipline as skills.metric-watch.lib.watch, Task 6.3).
3. Render the report: one line per check, <name> | <status> | <message>.

Why every check is warn-not-block

Per the task brief: doctor is diagnostic, not a gate. Even the carried checks (env, wiki structure, frontmatter) report their findings as ok/warn/skip/info — none of them can fail a build or block a command. The risk-tier gate (Task 6.1) and the PreToolUse hooks (Task 6.2) are where blocking actually happens; doctor's job is visibility.

What this skill does NOT do

• Fix anything. Every check is read-only; remediation is always a follow-up action the friend or another skill takes.
• Validate verify.json/schema conformance in the JSON-Schema sense. check_schema_versions only asks "is this page's declared schema_version behind the registry's current for its type" — that's skills.wiki-migration.lib.migration_chain's job, reused here, not reimplemented.
• Require graphify, backup, or lib.portability to be present. Each of those checks degrades gracefully (info/skip) rather than erroring when its dependency is absent.

References

• Task 3.1 (lib/instrument/collect.py) — capability_tokens data check_budget_lint reads
• Task 6.1 (lib/memory/promotion.py's demote_check) — the global-tier drift this check surfaces
• Task 7.2 (lib/portability/agents_surface.py) — soft-wired dependency for check_harness_neutrality
• skills/code-map/lib/__init__.py — status(), the graphify-presence/freshness check
• skills/backup/lib/__init__.py — backup_configured(), shared with metric-watch's own backup check
• skills/wiki-migration/lib/__init__.py — the registry check_schema_versions reads