OrchestKit Health Diagnostics
Host-neutral workflow. Invoke by skill name (doctor). Claude Code slash routing, YAML hook loaders, and .claude/chain live in references/claude-code.md.
Argument Resolution
FLAGS = "$ARGUMENTS" # Full argument string, e.g., "--verbose" or "--json"
FLAG = "$ARGUMENTS[0]" # First token: -v, --verbose, --json, --category=X
# $ARGUMENTS[0], $ARGUMENTS[1] for indexed access (CC 2.1.59)
STEP 0: Choose Scope (AskUserQuestion — M118 #1464)
A full doctor run takes ~20s. Most invocations only need one slice. Ask the user up-front so voice-flow shortcuts ("just the MCPs") map cleanly:
# Skip the prompt when an explicit scope arg or env override is present:
# doctor cc → skip, use cc-only
# doctor mcp → skip, use mcp-only
# doctor plugin → skip, use plugin-only
# ORK_DOCTOR_SCOPE=all (or any of the above) → skip, use the env value
#
# Otherwise, ask:
AskUserQuestion(questions=[{
"question": "What should doctor check?",
"header": "Scope",
"options": [
{"label": "Everything (default)", "description": "Full system health — ~20s; runs all 15 categories"},
{"label": "CC version & features only", "description": "Categories 10 + 13 + 14; ~3s — for 'is my CC up to date?'"},
{"label": "MCP servers only", "description": "Category 12 (incl. pinning sub-check); ~5s — for 'are MCPs working?'"},
{"label": "Plugin health only", "description": "Categories 0-3 + 5 (skills, agents, hooks, build); ~8s — for 'after npm run build'"}
]
}])
Skip the prompt entirely when the scope is unambiguous from the invocation. The fast scopes (3-8s) are 3-7× faster than the full run — voice users say "just the MCPs" and get a 5s answer.
Overview
The doctor command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 16 categories:
- Installed Plugins - Detects ork plugin
- Skills Validation - Frontmatter, references, token budget (dynamic count)
- Agents Validation - Frontmatter, tool refs, skill refs (dynamic count)
- Hook Health - Registration, bundles, async patterns
- Permission Rules - Detects unreachable rules
- Schema Compliance - Validates JSON files against schemas
- Coordination System - Checks lock health and registry integrity
- Context Budget - Monitors token usage against budget
- Memory System - Graph memory health
- Claude Code Version - Validates CC >= the
supported_floor in shared/cc-support.json (read it; it is the single source). Everything the old "recommends 2.1.154+" note gated (xhigh effort, /ultrareview, stream-json plugin_errors) is floor-guaranteed now, so there is nothing left to recommend
- External Dependencies - Checks optional tool availability (agent-browser), plus one line per peer skill installed from another marketplace:
typesafe@typesafe-ai installed version against the marketplace's, via scripts/check-peer-skill.py (missing marketplace and missing plugin are separate verdicts, the vendor's update commands are the fix text; #4233)
- MCP Status - Active vs disabled vs misconfigured, API key presence for paid MCPs. CC 2.1.110: detects duplicate definitions across config scopes. Sub-check warns when HIGH-tier servers resolve to
@latest in .mcp.json (closes #1462)
- Plugin Validate - Runs
claude plugin validate for official CC frontmatter + hooks.json validation (CC >= 2.1.77)
- Effort/Model Compatibility - Warns only when
xhigh effort is configured AND the active model is provably unable to run it. Silent otherwise, because the fallback itself is silent
- Sandbox Posture - CC Bash-sandbox on/off across all four settings scopes (incl.
~/.claude/settings.json, where real configs usually live), with a /sandbox nudge; sub-check 15b queries the macOS unified log for recent sandbox deny events (fail-closed: a denied log query reports UNOBSERVABLE, never zero)
- Operator Settings Posture - Detects security controls that a plugin bundle cannot carry (credential-read deny rules, the
sandbox block, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) and are therefore missing unless the operator wrote them into their own settings
When to Use
- After installing or updating OrchestKit
- When hooks aren't firing as expected
- Before deploying to a team environment
- When debugging coordination issues
- After running
npm run build
Quick Start
doctor # Standard health check
doctor -v # Verbose output
doctor --json # Machine-readable for CI
CLI Options
| Flag |
Description |
-v, --verbose |
Detailed output per check |
--json |
JSON output for CI integration |
--category=X |
Run only specific category |
Health Check Categories
Detailed check procedures: Load Read("rules/diagnostic-checks.md") for bash commands and validation logic per category.
MCP-specific checks: Load Read("rules/mcp-status-checks.md") for credential validation and misconfiguration detection.
Output examples: Load Read("references/health-check-outputs.md") for sample output per category.
Categories 0-3: Core Validation
| Category |
What It Checks |
Reference |
| 0. Installed Plugins |
Auto-detects ork plugin, counts skills/agents |
load rules/diagnostic-checks.md |
| 1. Skills |
Frontmatter, context field, token budget, links, activation-channel reachability (no orphaned user-invocable skills) |
load references/skills-validation.md |
| 2. Agents |
Frontmatter, model, skill refs, tool refs |
load references/agents-validation.md |
| 3. Hooks |
hooks.json schema, bundles, async patterns — across all three hook scopes: global, agent-scoped, and skill-scoped. Detects the common hook problems: missing files (registered but not on disk), syntax errors in hooks.json or bundles, permission issues (non-executable scripts), and stale references (entries pointing at renamed/removed handlers) |
load references/hook-validation.md |
Activation-channel orphans (repo / pre-release): a user-invocable skill should be reachable by more than a human typing it — via a chain (another skill references /ork:<skill>), a subagent grant (skills: in src/agents/*.md), or a background trigger. A skill with none is an "island" that silently rots. In a repo checkout, run npm run test:manifests:channels (gated in CI via test:manifests). Fix an island by wiring any one channel, or add it to STANDALONE_ALLOWLIST with a justification.
Categories 4-5: System Health
| Category |
What It Checks |
Reference |
| 4. Memory |
.claude/memory/ graph integrity + queue depth; auto-memory MEMORY.md index budget; per-agent .claude/agent-memory/NAME/MEMORY.md (orphans, staleness, 150-line warn, secret/PII) |
load references/memory-health.md and references/agent-memory-dir.md |
| 5. Build |
plugins/ sync with src/, manifest counts, orphans |
load rules/diagnostic-checks.md |
Analytics writer liveness (System Health): the local analytics pipeline has several independent JSONL writers under ~/.claude/analytics/ (skill-usage, agent-usage, hook-timing). A writer can die silently while its siblings stay hot — observed once for four months (skill-usage.jsonl, 2026-03 to 2026-07). The check is a peer comparison: flag any watched file whose last write is ≥48h old while a sibling wrote within 24h (stat -f '%m %N' ~/.claude/analytics/*.jsonl). The lifecycle/analytics-liveness-check SessionStart hook runs the same comparison continuously.
A flagged writer means the write path was dropped from dispatch, so check both surfaces — src/hooks/hooks.json AND the entries map (src/hooks/src/entries/*.ts). A hook present in one but not the other is registered-looking and silently dead: the #959 failure class. telemetry-inspect gives the per-file deep dive, covering the field-level defects this structural check cannot see: constant fields and phantom rows, the two classes fixed in #3034 and #3035 (both closed 2026-07-20). Cite them as prior art, not as open work.
(Category numbering in this file is inconsistent between the Overview list above and these tables — the Overview numbers 4 as Hook Health, the tables number 4 as Memory. This check belongs to System Health regardless of which numbering a reader follows.)
Categories 6-9: Infrastructure
| Category |
What It Checks |
| 6. Permission Rules |
Unreachable rules detection |
| 7. Schema Compliance |
JSON files against schemas |
| 8. Coordination |
Multi-worktree lock health, stale locks, sparse paths config |
| 9. Context Budget |
Token usage against budget |
Categories 10-16: Environment
| Category |
What It Checks |
Reference |
| 10. CC Version |
Runtime version against minimum required |
load references/version-compatibility.md |
| 11. External Deps |
Optional tools (agent-browser, portless) |
load rules/diagnostic-checks.md |
| 12. MCP Status |
Enabled/disabled state, credential checks, HIGH-tier @latest pinning warn |
load rules/mcp-status-checks.md + references/mcp-pinning-check.md |
| 13. Plugin Validate |
Official CC frontmatter + hooks.json validation (CC >= 2.1.77) |
load rules/diagnostic-checks.md |
| 14. Effort/Model |
xhigh effort configured on a model that provably cannot run it (see below). Defaults to silence |
inline |
| 15. Sandbox Posture |
CC Bash-sandbox on/off across all four settings scopes + /sandbox nudge (opt-in, Bash-only; info-level). 15b: bounded read-only query of the macOS unified log for recent Sandbox deny events via scripts/check-sandbox-violations.sh (warn-level; fail-closed when the log query itself is denied; explicit skip off macOS) |
load references/sandbox-posture.md |
| 16. Operator Settings Posture |
Controls a plugin bundle cannot carry, so they exist only if the operator wrote them: credential-read permissions.deny rules (defence in depth: pretool/read/credential-read-guard already covers the Read tool), the sandbox block incl. network.deniedDomains (the egress guard only asks on the upload shape; a plain GET abstains), and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS (ork's own agent-teams.ts gates on it). Since CC 2.1.257 it also reports permissions.blockReadsOutsideWorkingDirectories and warns when it is true without ~/.claude in additionalDirectories (the reads ork skills make outside the project would be refused, not prompted). Since #3877 it also names a project-scope sandbox.enabled: false that overrides a user-scope true (sandbox_override, project file:line and user file:line; the project file wins and Bash runs unsandboxed). Since CC 2.1.299 to 2.1.305 it also reports unattended-lane posture under unattended: an idleCompaction: false scope (warned) and, with CLAUDE_CODE_RETRY_WATCHDOG on, each missing watchdog cap (offered). Since #3835 the audit is a script: bash ${CLAUDE_SKILL_DIR}/scripts/check-operator-permissions.sh <project_dir> --json (exit 0 all payload rules enforced, 1 missing with the remedy, 2 could-not-observe); the remedy is setup phase 3.6, consent-gated. Warn-level; prints the JSON to paste |
load references/settings-posture.md |
Why Check 16 exists at all: plugins-reference.md:858 says "Only the agent and subagentStatusLine keys are currently supported" in a plugin's bundled settings.json. Everything else ork used to declare there was inert, so the protection it looked like it shipped was never in force. Check 16 is the replacement: detect the gap in a scope CC really reads, then hand the operator the exact JSON. The ork:configure skill, section Operator-Scope Settings, carries the paste-ready blocks, staged loose-then-strict per #3424; the full JSON is in ../configure/references/operator-scope-settings.md.
Category 14: Effort/Model Compatibility (CC 2.1.111+)
CC 2.1.111 added the xhigh effort tier. The only reason this category exists is the silence: a model that does not implement xhigh degrades the request to high with no error, no warning, and no log line, so the extra deepening pass the affected skills document is lost without any visible signal. If CC ever surfaces the downgrade itself, delete this category.
The check is capability-shaped, not model-name-shaped. Never hardcode "the current frontier model" here: that guarantees a false failure the day the next one ships, and it prescribes a downgrade to a superseded model.
Do not route this through src/hooks/src/lib/models.vocab.json. That file is the model-id/pricing vocabulary and carries no effort or capability fields at all, so keying off it would leave the check permanently, accidentally dead rather than deliberately quiet.
Detection (warn only on positive proof):
- Resolve the configured effort, in order:
.claude/settings.json → effort, then $ORCHESTKIT_EFFORT (populated by the effort-detector hook), then any .claude/chain/*.json entry that explicitly set effort: xhigh. No xhigh anywhere means pass, no output.
- Resolve the active model id.
- Warn only when that model id matches a prefix in doctor's local
XHIGH_UNSUPPORTED_PREFIXES table below. Every other outcome (model absent from the table, model id unresolvable, settings file missing) is a pass. A check that cannot prove a problem stays quiet.
# Doctor-local capability table. Deliberately a DENY-list, not an allow-list:
# a model absent from this table is assumed to support xhigh and emits nothing.
# Add an entry only from an OBSERVED silent degrade, citing the CC version it was
# seen on. Never add one by inferring from a model being new, old, or cheap.
XHIGH_UNSUPPORTED_PREFIXES = [
# prefix evidence
"claude-3-", # the whole Claude 3 line predates CC 2.1.111, which introduced the tier
]
An empty or short table is the correct resting state. Silence here means "doctor has no proof of a problem", which is a true statement, whereas a name-matched failure against an unrecognized model is a false one.
Warning format (no model name is hardcoded, both sides are read at runtime):
WARNING: effort is set to `xhigh`, but <model-id> matches XHIGH_UNSUPPORTED_PREFIXES.
Configured effort: xhigh (source: <settings.json | $ORCHESTKIT_EFFORT | chain>)
Impact: the run degrades to `high` with no error and no log line, so the extra
deepening pass is lost with nothing to notice it by.
Fix: run this on a model that implements `xhigh`, or set effort to `high` so the
config matches what actually executes.
Exit code: Non-zero in --json mode only when the warning actually fires; soft warning in interactive mode. A silent pass is exit 0.
Report Format
Every category reports an explicit pass / warn / fail status, and every warn or fail comes with specific fix steps for that failure type (the exact command to run, file to edit, or config to change) — doctor diagnoses AND prescribes, it never just lists problems.
Load Read("references/report-format.md") for ASCII report templates, JSON CI output schema, and exit codes.
Interpreting Results & Troubleshooting
Load Read("references/remediation-guide.md") for the full results interpretation table and troubleshooting steps for common failures (skills validation, build sync, memory).
Bisect with --safe-mode (CC 2.1.169+): when doctor findings don't explain a misbehaving session, restart with claude --safe-mode (or CLAUDE_CODE_SAFE_MODE=1) — it disables ALL customizations (CLAUDE.md, plugins incl. ork, skills, hooks, MCP). If the problem disappears, it's a customization; re-enable halves to isolate. If it persists, it's CC itself — file upstream.
Host load vs session load (macOS): when doctor findings say the session is healthy but the machine is slow, do not diagnose from memory_pressure's "System-wide memory free percentage": it once read 84% free while 59 of 64 GB was in use and swap stood at 6.9 of 8 GB, and the first culprit named from that number was wrong (the real load was a test suite in another project). Read the evidence before naming anything: sysctl vm.swapusage for swap, vm_stat for the memory split, and a process view sorted by memory use (e.g. ps aux | sort -nrk 4 | head) for who is actually consuming memory.
After you fix an issue
CC 2.1.69+: Run /reload-plugins to activate plugin changes in the current session without restarting.
CC 2.1.116+: /reload-plugins and background plugin auto-update now auto-install missing plugin dependencies from marketplaces you've already added. If ork:doctor flagged a plugin-load failure due to a missing dep, /reload-plugins resolves it in place — no manual plugin install step needed.
CC 2.1.152+: For non-plugin skills in a skill directory (~/.claude/skills/ or .claude/skills/), run /reload-skills to re-scan without restarting — the skill analogue of /reload-plugins.
CC 2.1.268+: /plugin install, enable and disable take effect when the menu closes, so /reload-plugins is no longer needed after them.
Chain: Deeper Audit
After a clean health report, audit the observability pipeline itself:
telemetry-inspect
doctor validates structure (manifests, hooks, skills, agents); telemetry-inspect validates the data plane — every telemetry writer's row count, schema lock, growth trend, and orphaned analytics files that structural checks don't cover.
Related Skills
ork:configure - Configure plugin settings
ork:telemetry-inspect - Audit the telemetry/analytics pipeline after a clean structural check
ork:quality-gates - CI/CD integration
security-scanning - Comprehensive audits
References
Load on demand with Read("references/<file>") or Read("rules/<file>"):
| File |
Content |
rules/diagnostic-checks.md |
Bash commands and validation logic per category |
rules/mcp-status-checks.md |
Credential validation and misconfiguration detection |
references/remediation-guide.md |
Results interpretation and troubleshooting steps |
references/health-check-outputs.md |
Sample output per category |
references/skills-validation.md |
Skills frontmatter and structure checks |
references/agents-validation.md |
Agents frontmatter and tool ref checks |
references/hook-validation.md |
Hook registration and bundle checks |
references/memory-health.md |
Memory system integrity checks |
references/agent-memory-dir.md |
Per-agent agent-memory dir: orphans, staleness, 150-line warn, secrets |
references/permission-rules.md |
Permission rule detection |
references/skill-preapproval.md |
Skills whose allowed-tools pre-grant stops under managed allowManagedPermissionRulesOnly (CC 2.1.282, 2.1.284), detection and admin remedy |
references/schema-validation.md |
JSON schema compliance |
references/report-format.md |
ASCII report templates and JSON CI output |
references/version-compatibility.md |
CC version and channel validation |
references/mcp-pinning-check.md |
HIGH-tier MCP @latest warning logic + tier source-of-truth |
references/sandbox-posture.md |
CC Bash-sandbox on/off detection + /sandbox nudge (Check 15) + unified-log violation query (15b) |
references/settings-posture.md |
Operator-scope security posture: what a plugin bundle cannot carry, and how to detect it missing (Check 16) |
1---2name: doctor-23license: MIT4compatibility: "Claude Code 2.1.277+ for xhigh effort warning (Category 14); earlier versions skip that check."5description: "Diagnoses OrchestKit and project health: manifests, hooks, skills, agents, MCP servers, CC version and permissions, with severity and remedies. Use to run doctor checks, diagnose issues or check project health before a release."6argument-hint: "[--verbose]"7context: inherit8user-invocable: true9disable-model-invocation: false10allowed-tools: "Bash Read Grep Glob AskUserQuestion Write"11skills: [configure]12effort: low13model: haiku14hooks:15 PreToolUse:16 - matcher: "Bash"17 hooks:18 - type: command19 command: "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs skill/doctor-env-snapshot"20 once: true21metadata:22 source: https://skillmd.com/skills/yonatangross/doctor-223 category: document-asset-creation24 version: "3.3.0"25 author: "OrchestKit"26 complexity: "low"27 tags: "health-check, diagnostics, validation, permissions, hooks, skills, agents, memory"28---2930# OrchestKit Health Diagnostics3132Host-neutral workflow. Invoke by skill name (`doctor`). Claude Code slash routing, YAML hook loaders, and `.claude/chain` live in `references/claude-code.md`.3334## Argument Resolution3536```python37FLAGS = "$ARGUMENTS" # Full argument string, e.g., "--verbose" or "--json"38FLAG = "$ARGUMENTS[0]" # First token: -v, --verbose, --json, --category=X39# $ARGUMENTS[0], $ARGUMENTS[1] for indexed access (CC 2.1.59)40```4142## STEP 0: Choose Scope (AskUserQuestion — M118 #1464)4344A full doctor run takes ~20s. Most invocations only need one slice. Ask the user up-front so voice-flow shortcuts ("just the MCPs") map cleanly:4546```python47# Skip the prompt when an explicit scope arg or env override is present:48# doctor cc → skip, use cc-only49# doctor mcp → skip, use mcp-only50# doctor plugin → skip, use plugin-only51# ORK_DOCTOR_SCOPE=all (or any of the above) → skip, use the env value52#53# Otherwise, ask:54AskUserQuestion(questions=[{55 "question": "What should doctor check?",56 "header": "Scope",57 "options": [58 {"label": "Everything (default)", "description": "Full system health — ~20s; runs all 15 categories"},59 {"label": "CC version & features only", "description": "Categories 10 + 13 + 14; ~3s — for 'is my CC up to date?'"},60 {"label": "MCP servers only", "description": "Category 12 (incl. pinning sub-check); ~5s — for 'are MCPs working?'"},61 {"label": "Plugin health only", "description": "Categories 0-3 + 5 (skills, agents, hooks, build); ~8s — for 'after npm run build'"}62 ]63}])64```6566Skip the prompt entirely when the scope is unambiguous from the invocation. The fast scopes (3-8s) are 3-7× faster than the full run — voice users say "just the MCPs" and get a 5s answer.6768## Overview6970The `doctor` command performs comprehensive health checks on your OrchestKit installation. It auto-detects installed plugins and validates 16 categories:71721. **Installed Plugins** - Detects ork plugin732. **Skills Validation** - Frontmatter, references, token budget (dynamic count)743. **Agents Validation** - Frontmatter, tool refs, skill refs (dynamic count)754. **Hook Health** - Registration, bundles, async patterns765. **Permission Rules** - Detects unreachable rules776. **Schema Compliance** - Validates JSON files against schemas787. **Coordination System** - Checks lock health and registry integrity798. **Context Budget** - Monitors token usage against budget809. **Memory System** - Graph memory health8110. **Claude Code Version** - Validates CC >= the `supported_floor` in `shared/cc-support.json` (read it; it is the single source). Everything the old "recommends 2.1.154+" note gated (`xhigh` effort, `/ultrareview`, stream-json `plugin_errors`) is floor-guaranteed now, so there is nothing left to recommend8211. **External Dependencies** - Checks optional tool availability (agent-browser), plus one line per peer skill installed from another marketplace: `typesafe@typesafe-ai` installed version against the marketplace's, via `scripts/check-peer-skill.py` (missing marketplace and missing plugin are separate verdicts, the vendor's update commands are the fix text; #4233)8312. **MCP Status** - Active vs disabled vs misconfigured, API key presence for paid MCPs. CC 2.1.110: detects duplicate definitions across config scopes. Sub-check warns when HIGH-tier servers resolve to `@latest` in `.mcp.json` (closes #1462)8413. **Plugin Validate** - Runs `claude plugin validate` for official CC frontmatter + hooks.json validation (CC >= 2.1.77)8514. **Effort/Model Compatibility** - Warns only when `xhigh` effort is configured AND the active model is provably unable to run it. Silent otherwise, because the fallback itself is silent8615. **Sandbox Posture** - CC Bash-sandbox on/off across all four settings scopes (incl. `~/.claude/settings.json`, where real configs usually live), with a `/sandbox` nudge; sub-check 15b queries the macOS unified log for recent sandbox deny events (fail-closed: a denied log query reports UNOBSERVABLE, never zero)8716. **Operator Settings Posture** - Detects security controls that a plugin bundle **cannot** carry (credential-read deny rules, the `sandbox` block, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`) and are therefore missing unless the operator wrote them into their own settings8889## When to Use9091- After installing or updating OrchestKit92- When hooks aren't firing as expected93- Before deploying to a team environment94- When debugging coordination issues95- After running `npm run build`9697## Quick Start9899```bash100doctor # Standard health check101doctor -v # Verbose output102doctor --json # Machine-readable for CI103```104105## CLI Options106107| Flag | Description |108|------|-------------|109| `-v`, `--verbose` | Detailed output per check |110| `--json` | JSON output for CI integration |111| `--category=X` | Run only specific category |112113## Health Check Categories114115> **Detailed check procedures**: Load `Read("rules/diagnostic-checks.md")` for bash commands and validation logic per category.116>117> **MCP-specific checks**: Load `Read("rules/mcp-status-checks.md")` for credential validation and misconfiguration detection.118>119> **Output examples**: Load `Read("references/health-check-outputs.md")` for sample output per category.120121### Categories 0-3: Core Validation122123| Category | What It Checks | Reference |124|----------|---------------|-----------|125| **0. Installed Plugins** | Auto-detects ork plugin, counts skills/agents | load `rules/diagnostic-checks.md` |126| **1. Skills** | Frontmatter, context field, token budget, links, **activation-channel reachability** (no orphaned user-invocable skills) | load `references/skills-validation.md` |127| **2. Agents** | Frontmatter, model, skill refs, tool refs | load `references/agents-validation.md` |128| **3. Hooks** | hooks.json schema, bundles, async patterns — across all three hook scopes: **global**, **agent-scoped**, and **skill-scoped**. Detects the common hook problems: missing files (registered but not on disk), syntax errors in hooks.json or bundles, permission issues (non-executable scripts), and stale references (entries pointing at renamed/removed handlers) | load `references/hook-validation.md` |129130> **Activation-channel orphans (repo / pre-release):** a user-invocable skill should be reachable by more than a human typing it — via a chain (another skill references `/ork:<skill>`), a subagent grant (`skills:` in `src/agents/*.md`), or a background trigger. A skill with none is an "island" that silently rots. In a repo checkout, run `npm run test:manifests:channels` (gated in CI via `test:manifests`). Fix an island by wiring any one channel, or add it to `STANDALONE_ALLOWLIST` with a justification.131132### Categories 4-5: System Health133134| Category | What It Checks | Reference |135|----------|---------------|-----------|136| **4. Memory** | .claude/memory/ graph integrity + queue depth; auto-memory MEMORY.md index budget; per-agent `.claude/agent-memory/NAME/MEMORY.md` (orphans, staleness, 150-line warn, secret/PII) | load `references/memory-health.md` and `references/agent-memory-dir.md` |137| **5. Build** | plugins/ sync with src/, manifest counts, orphans | load `rules/diagnostic-checks.md` |138139> **Analytics writer liveness (System Health):** the local analytics pipeline has several independent JSONL writers under `~/.claude/analytics/` (skill-usage, agent-usage, hook-timing). A writer can die silently while its siblings stay hot — observed once for four months (skill-usage.jsonl, 2026-03 to 2026-07). The check is a peer comparison: flag any watched file whose last write is ≥48h old while a sibling wrote within 24h (`stat -f '%m %N' ~/.claude/analytics/*.jsonl`). The `lifecycle/analytics-liveness-check` SessionStart hook runs the same comparison continuously.140>141> A flagged writer means the write path was dropped from dispatch, so check **both** surfaces — `src/hooks/hooks.json` AND the entries map (`src/hooks/src/entries/*.ts`). A hook present in one but not the other is registered-looking and silently dead: the #959 failure class. `telemetry-inspect` gives the per-file deep dive, covering the field-level defects this structural check cannot see: constant fields and phantom rows, the two classes fixed in #3034 and #3035 (both closed 2026-07-20). Cite them as prior art, not as open work.142>143> *(Category numbering in this file is inconsistent between the Overview list above and these tables — the Overview numbers 4 as Hook Health, the tables number 4 as Memory. This check belongs to System Health regardless of which numbering a reader follows.)*144145### Categories 6-9: Infrastructure146147| Category | What It Checks |148|----------|---------------|149| **6. Permission Rules** | Unreachable rules detection |150| **7. Schema Compliance** | JSON files against schemas |151| **8. Coordination** | Multi-worktree lock health, stale locks, sparse paths config |152| **9. Context Budget** | Token usage against budget |153154### Categories 10-16: Environment155156| Category | What It Checks | Reference |157|----------|---------------|-----------|158| **10. CC Version** | Runtime version against minimum required | load `references/version-compatibility.md` |159| **11. External Deps** | Optional tools (agent-browser, portless) | load `rules/diagnostic-checks.md` |160| **12. MCP Status** | Enabled/disabled state, credential checks, **HIGH-tier `@latest` pinning warn** | load `rules/mcp-status-checks.md` + `references/mcp-pinning-check.md` |161| **13. Plugin Validate** | Official CC frontmatter + hooks.json validation (CC >= 2.1.77) | load `rules/diagnostic-checks.md` |162| **14. Effort/Model** | `xhigh` effort configured on a model that provably cannot run it (see below). Defaults to silence | inline |163| **15. Sandbox Posture** | CC Bash-sandbox on/off across all four settings scopes + `/sandbox` nudge (opt-in, Bash-only; info-level). **15b**: bounded read-only query of the macOS unified log for recent `Sandbox` deny events via `scripts/check-sandbox-violations.sh` (warn-level; fail-closed when the log query itself is denied; explicit skip off macOS) | load `references/sandbox-posture.md` |164| **16. Operator Settings Posture** | Controls a plugin bundle **cannot** carry, so they exist only if the operator wrote them: credential-read `permissions.deny` rules (defence in depth: `pretool/read/credential-read-guard` already covers the `Read` tool), the `sandbox` block incl. `network.deniedDomains` (the egress guard only `ask`s on the upload shape; a plain GET abstains), and `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` (ork's own `agent-teams.ts` gates on it). Since CC 2.1.257 it also reports `permissions.blockReadsOutsideWorkingDirectories` and warns when it is true without `~/.claude` in `additionalDirectories` (the reads ork skills make outside the project would be refused, not prompted). Since #3877 it also names a project-scope `sandbox.enabled: false` that overrides a user-scope `true` (`sandbox_override`, project file:line and user file:line; the project file wins and Bash runs unsandboxed). Since CC 2.1.299 to 2.1.305 it also reports unattended-lane posture under `unattended`: an `idleCompaction: false` scope (warned) and, with `CLAUDE_CODE_RETRY_WATCHDOG` on, each missing watchdog cap (offered). Since #3835 the audit is a script: `bash ${CLAUDE_SKILL_DIR}/scripts/check-operator-permissions.sh <project_dir> --json` (exit 0 all payload rules enforced, 1 missing with the remedy, 2 could-not-observe); the remedy is setup phase 3.6, consent-gated. Warn-level; prints the JSON to paste | load `references/settings-posture.md` |165166> **Why Check 16 exists at all:** `plugins-reference.md:858` says "Only the `agent` and `subagentStatusLine` keys are currently supported" in a plugin's bundled `settings.json`. Everything else ork used to declare there was inert, so the protection it looked like it shipped was never in force. Check 16 is the replacement: detect the gap in a scope CC really reads, then hand the operator the exact JSON. The `ork:configure` skill, section *Operator-Scope Settings*, carries the paste-ready blocks, staged loose-then-strict per #3424; the full JSON is in `../configure/references/operator-scope-settings.md`.167168### Category 14: Effort/Model Compatibility (CC 2.1.111+)169170CC 2.1.111 added the `xhigh` effort tier. **The only reason this category exists is the silence**: a model that does not implement `xhigh` degrades the request to `high` with no error, no warning, and no log line, so the extra deepening pass the affected skills document is lost without any visible signal. If CC ever surfaces the downgrade itself, delete this category.171172The check is **capability-shaped, not model-name-shaped**. Never hardcode "the current frontier model" here: that guarantees a false failure the day the next one ships, and it prescribes a downgrade to a superseded model.173174**Do not route this through `src/hooks/src/lib/models.vocab.json`.** That file is the model-id/pricing vocabulary and carries no effort or capability fields at all, so keying off it would leave the check permanently, accidentally dead rather than deliberately quiet.175176**Detection (warn only on positive proof):**1771781. Resolve the configured effort, in order: `.claude/settings.json` → `effort`, then `$ORCHESTKIT_EFFORT` (populated by the effort-detector hook), then any `.claude/chain/*.json` entry that explicitly set `effort: xhigh`. No `xhigh` anywhere means pass, no output.1792. Resolve the active model id.1803. Warn **only** when that model id matches a prefix in doctor's local `XHIGH_UNSUPPORTED_PREFIXES` table below. Every other outcome (model absent from the table, model id unresolvable, settings file missing) is a pass. A check that cannot prove a problem stays quiet.181182```python183# Doctor-local capability table. Deliberately a DENY-list, not an allow-list:184# a model absent from this table is assumed to support xhigh and emits nothing.185# Add an entry only from an OBSERVED silent degrade, citing the CC version it was186# seen on. Never add one by inferring from a model being new, old, or cheap.187XHIGH_UNSUPPORTED_PREFIXES = [188 # prefix evidence189 "claude-3-", # the whole Claude 3 line predates CC 2.1.111, which introduced the tier190]191```192193An empty or short table is the correct resting state. Silence here means "doctor has no proof of a problem", which is a true statement, whereas a name-matched failure against an unrecognized model is a false one.194195**Warning format** (no model name is hardcoded, both sides are read at runtime):196```197WARNING: effort is set to `xhigh`, but <model-id> matches XHIGH_UNSUPPORTED_PREFIXES.198 Configured effort: xhigh (source: <settings.json | $ORCHESTKIT_EFFORT | chain>)199 Impact: the run degrades to `high` with no error and no log line, so the extra200 deepening pass is lost with nothing to notice it by.201 Fix: run this on a model that implements `xhigh`, or set effort to `high` so the202 config matches what actually executes.203```204205**Exit code**: Non-zero in `--json` mode only when the warning actually fires; soft warning in interactive mode. A silent pass is exit 0.206207## Report Format208209Every category reports an explicit **pass / warn / fail** status, and every warn or fail comes with **specific fix steps** for that failure type (the exact command to run, file to edit, or config to change) — doctor diagnoses AND prescribes, it never just lists problems.210211> Load `Read("references/report-format.md")` for ASCII report templates, JSON CI output schema, and exit codes.212213## Interpreting Results & Troubleshooting214215> Load `Read("references/remediation-guide.md")` for the full results interpretation table and troubleshooting steps for common failures (skills validation, build sync, memory).216217> **Bisect with `--safe-mode` (CC 2.1.169+):** when doctor findings don't explain a misbehaving session, restart with `claude --safe-mode` (or `CLAUDE_CODE_SAFE_MODE=1`) — it disables ALL customizations (CLAUDE.md, plugins incl. ork, skills, hooks, MCP). If the problem disappears, it's a customization; re-enable halves to isolate. If it persists, it's CC itself — file upstream.218219> **Host load vs session load (macOS):** when doctor findings say the session is healthy but the machine is slow, do not diagnose from `memory_pressure`'s "System-wide memory free percentage": it once read 84% free while 59 of 64 GB was in use and swap stood at 6.9 of 8 GB, and the first culprit named from that number was wrong (the real load was a test suite in another project). Read the evidence before naming anything: `sysctl vm.swapusage` for swap, `vm_stat` for the memory split, and a process view sorted by memory use (e.g. `ps aux | sort -nrk 4 | head`) for who is actually consuming memory.220221### After you fix an issue222223> **CC 2.1.69+**: Run `/reload-plugins` to activate plugin changes in the current session without restarting.224>225> **CC 2.1.116+**: `/reload-plugins` and background plugin auto-update now **auto-install missing plugin dependencies** from marketplaces you've already added. If `ork:doctor` flagged a plugin-load failure due to a missing dep, `/reload-plugins` resolves it in place — no manual `plugin install` step needed.226>227> **CC 2.1.152+**: For non-plugin **skills** in a skill directory (`~/.claude/skills/` or `.claude/skills/`), run `/reload-skills` to re-scan without restarting — the skill analogue of `/reload-plugins`.228>229> **CC 2.1.268+**: `/plugin` install, enable and disable take effect when the menu closes, so `/reload-plugins` is no longer needed after them.230231## Chain: Deeper Audit232233> After a clean health report, audit the observability pipeline itself:234>235> ```236> telemetry-inspect237> ```238>239> `doctor` validates structure (manifests, hooks, skills, agents); `telemetry-inspect` validates the *data plane* — every telemetry writer's row count, schema lock, growth trend, and orphaned analytics files that structural checks don't cover.240241## Related Skills242243- `ork:configure` - Configure plugin settings244- `ork:telemetry-inspect` - Audit the telemetry/analytics pipeline after a clean structural check245- `ork:quality-gates` - CI/CD integration246- `security-scanning` - Comprehensive audits247248## References249250Load on demand with `Read("references/<file>")` or `Read("rules/<file>")`:251| File | Content |252|------|---------|253| `rules/diagnostic-checks.md` | Bash commands and validation logic per category |254| `rules/mcp-status-checks.md` | Credential validation and misconfiguration detection |255| `references/remediation-guide.md` | Results interpretation and troubleshooting steps |256| `references/health-check-outputs.md` | Sample output per category |257| `references/skills-validation.md` | Skills frontmatter and structure checks |258| `references/agents-validation.md` | Agents frontmatter and tool ref checks |259| `references/hook-validation.md` | Hook registration and bundle checks |260| `references/memory-health.md` | Memory system integrity checks |261| `references/agent-memory-dir.md` | Per-agent agent-memory dir: orphans, staleness, 150-line warn, secrets |262| `references/permission-rules.md` | Permission rule detection |263| `references/skill-preapproval.md` | Skills whose `allowed-tools` pre-grant stops under managed `allowManagedPermissionRulesOnly` (CC 2.1.282, 2.1.284), detection and admin remedy |264| `references/schema-validation.md` | JSON schema compliance |265| `references/report-format.md` | ASCII report templates and JSON CI output |266| `references/version-compatibility.md` | CC version and channel validation |267| `references/mcp-pinning-check.md` | HIGH-tier MCP `@latest` warning logic + tier source-of-truth |268| `references/sandbox-posture.md` | CC Bash-sandbox on/off detection + `/sandbox` nudge (Check 15) + unified-log violation query (15b) |269| `references/settings-posture.md` | Operator-scope security posture: what a plugin bundle cannot carry, and how to detect it missing (Check 16) |