doctor

OrchestKit のヘルス診断

ホストに依存しないワークフローです。スキル名（doctor）を指定して実行します。Claude Code のスラッシュコマンドへのルーティング、YAML フックローダー、.claude/chain については、references/claude-code.md を参照してください。

引数の解決

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)

ステップ 0：対象範囲を選択（AskUserQuestion — M118 #1464）

doctor の全項目を実行すると約 20 秒かかります。ほとんどの場合、必要なのは一部の項目だけです。音声入力での「MCP だけ」などの簡潔な指定を適切に処理できるよう、事前にユーザーに確認してください。

# 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'"}
  ]
}])

実行時の指定から対象範囲が明確な場合は、確認を完全に省略してください。高速な対象範囲（3〜8 秒）は全項目の実行より 3〜7 倍速く、音声入力で「MCP だけ」と言えば、5 秒で結果が得られます。

概要

doctor コマンドは、OrchestKit のインストール状態を包括的にヘルスチェックします。インストール済みのプラグインを自動検出し、16 のカテゴリを検証します。

1. インストール済みプラグイン - ork プラグインを検出します
2. スキルの検証 - フロントマター、参照、トークン予算（動的な件数）を確認します
3. エージェントの検証 - フロントマター、ツール参照、スキル参照（動的な件数）を確認します
4. フックの状態 - 登録、バンドル、非同期パターンを確認します
5. 権限ルール - 到達不能なルールを検出します
6. スキーマ準拠 - JSON ファイルをスキーマに照らして検証します
7. 連携システム - ロックの状態とレジストリの整合性を確認します
8. コンテキスト予算 - 予算に対するトークン使用量を監視します
9. メモリシステム - グラフメモリの状態を確認します
10. Claude Code のバージョン - shared/cc-support.json の supported_floor（唯一の基準です）を読み取り、CC がそれ以上であることを検証します。以前「2.1.154 以上を推奨」という注記で条件としていた機能（xhigh の推論レベル、/ultrareview、stream-json の plugin_errors）は、いずれも現在は最低対応バージョンで保証されているため、推奨事項はありません
11. 外部依存関係 - 任意のツール（agent-browser）の利用可否に加え、別のマーケットプレイスからインストールされた同じスキルについても、それぞれ 1 行ずつ確認します。scripts/check-peer-skill.py を使って、インストール済みの typesafe@typesafe-ai のバージョンをマーケットプレイスのバージョンと照合します（マーケットプレイスが見つからない場合とプラグインが見つからない場合は別々に判定され、修正方法にはベンダーの更新コマンドが表示されます。#4233）
12. MCP の状態 - 有効、無効、設定ミスの状態と、有料 MCP の API キーの有無を確認します。CC 2.1.110 では、設定スコープ間の定義重複を検出します。サブチェックでは、HIGH ティアのサーバーが .mcp.json で @latest に解決されている場合に警告します（#1462 を解消します）
13. プラグインの検証 - claude plugin validate を実行し、公式 CC フロントマターと hooks.json を検証します（CC >= 2.1.77）
14. 推論レベル／モデルの互換性 - xhigh の推論レベルが設定され、かつ使用中のモデルでは実行できないことが確実な場合にのみ警告します。フォールバック自体は通知されないため、それ以外の場合は通知しません
15. サンドボックスの状態 - 4 つすべての設定スコープ（実際の設定で通常使われる ~/.claude/settings.json を含む）で、CC Bash サンドボックスのオン／オフを確認し、/sandbox の使用を促します。サブチェック 15b では macOS の統合ログを照会して、最近のサンドボックス拒否イベントを確認します（フェイルクローズ方式です。ログの照会が拒否された場合は、ゼロ件ではなく UNOBSERVABLE と報告します）
16. 運用者設定の状態 - プラグインバンドルに含められないセキュリティ制御（認証情報の読み取り拒否ルール、sandbox ブロック、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS）を検出します。運用者が自身の設定に記述していない場合、これらは設定されていません

使用する場面

• OrchestKit のインストール後または更新後
• フックが想定どおりに動作しない場合
• チーム環境へのデプロイ前
• 連携に関する問題のデバッグ時
• npm run build の実行後

クイックスタート

doctor           # Standard health check
doctor -v        # Verbose output
doctor --json    # Machine-readable for CI

CLI オプション

フラグ	説明
-v、--verbose	各チェックの詳細を出力します
--json	CI 連携用に JSON 形式で出力します
--category=X	指定したカテゴリだけを実行します

ヘルスチェックのカテゴリ

詳細なチェック手順：カテゴリごとの Bash コマンドと検証ロジックについては、Read("rules/diagnostic-checks.md") を読み込んでください。

MCP 固有のチェック：認証情報の検証と設定ミスの検出については、Read("rules/mcp-status-checks.md") を読み込んでください。

出力例：カテゴリごとの出力例については、Read("references/health-check-outputs.md") を読み込んでください。

カテゴリ 0～3：コア検証

カテゴリ	チェック内容	参照先
0. インストール済みプラグイン	ork プラグインを自動検出し、スキルとエージェントの数をカウントします	rules/diagnostic-checks.md を読み込み
1. スキル	フロントマター、コンテキストフィールド、トークン予算、リンク、アクティベーションチャネルからの到達可能性（孤立したユーザー呼び出し可能スキルがないこと）	references/skills-validation.md を読み込み
2. エージェント	フロントマター、モデル、スキル参照、ツール参照	references/agents-validation.md を読み込み
3. フック	hooks.json のスキーマ、バンドル、非同期パターン — 次の3つすべてのフックスコープを対象とします：グローバル、エージェントスコープ、スキルスコープ。よくあるフックの問題を検出します：ファイルの欠落（登録済みだがディスク上に存在しない）、hooks.json またはバンドルの構文エラー、権限の問題（実行権限のないスクリプト）、古い参照（名前変更または削除されたハンドラーを指すエントリー）	references/hook-validation.md を読み込み

**アクティベーションチャネルから孤立したスキル（リポジトリ／リリース前）：**ユーザー呼び出し可能なスキルは、人が入力するだけでなく、チェーン（別のスキルが /ork:<skill> を参照）、サブエージェントへの付与（src/agents/*.md 内の skills:）、またはバックグラウンドトリガーを通じて到達可能であるべきです。いずれもないスキルは「孤島」となり、気付かれないまま劣化します。リポジトリをチェックアウトした環境では、npm run test:manifests:channels を実行してください（CI では test:manifests 経由で実行が制御されています）。孤島を解消するには、いずれか1つのチャネルを接続するか、根拠を添えて STANDALONE_ALLOWLIST に追加してください。

カテゴリ 4～5：システムの健全性

カテゴリ	チェック内容	参照先
4. メモリ	.claude/memory/ のグラフ整合性とキューの深さ、自動メモリの MEMORY.md のインデックス予算、エージェントごとの .claude/agent-memory/NAME/MEMORY.md（孤立、古さ、150行での警告、シークレット／PII）	references/memory-health.md と references/agent-memory-dir.md を読み込み
5. ビルド	plugins/ と src/ の同期、マニフェスト数、孤立ファイル	rules/diagnostic-checks.md を読み込み

**分析データ書き込み処理の稼働状況（システムの健全性）：**ローカルの分析パイプラインには、~/.claude/analytics/ 配下に複数の独立した JSONL 書き込み処理（skill-usage、agent-usage、hook-timing）があります。ある書き込み処理がひそかに停止しても、ほかの処理は稼働し続けることがあります。実際に、skill-usage.jsonl で4か月間発生した例があります（2026-03 から 2026-07）。このチェックでは相互比較を行います。監視対象ファイルの最終書き込みから48時間以上経過している一方で、別のファイルが24時間以内に書き込まれている場合に警告します（stat -f '%m %N' ~/.claude/analytics/*.jsonl）。lifecycle/analytics-liveness-check SessionStart フックも、同じ比較を継続的に実行します。

書き込み処理に警告が出た場合、ディスパッチから書き込み経路が外れています。そのため、両方の箇所を確認してください — src/hooks/hooks.json とエントリーマップ（src/hooks/src/entries/*.ts）です。一方にはフックが存在するのに、もう一方には存在しない場合、登録されているように見えて実際にはひそかに停止しています。これは #959 の障害クラスです。telemetry-inspect を使うと、構造チェックでは検出できないフィールドレベルの不具合を含め、ファイルごとに詳細を調査できます。該当する不具合は、定数フィールドとファントム行の2種類で、#3034 と #3035 で修正済みです（どちらも 2026-07-20 にクローズ）。これらは未対応作業ではなく、先行事例として挙げてください。

(このファイルでは、上記の概要リストとこれらの表でカテゴリ番号が一致していません。概要では4がフックの健全性、表では4がメモリです。どちらの番号付けに従う場合も、このチェックはシステムの健全性に属します。)

カテゴリー 6〜9：インフラストラクチャ

カテゴリー	チェック内容
6. Permission Rules	到達不能なルールの検出
7. Schema Compliance	JSON ファイルとスキーマとの適合性
8. Coordination	複数の worktree のロック状態、古いロック、sparse paths の設定
9. Context Budget	予算に対するトークン使用量

カテゴリー 10〜16：環境

カテゴリー	チェック内容	参照先
10. CC Version	実行時バージョンが必要最小バージョンを満たしているか	references/version-compatibility.md を読み込む
11. External Deps	オプションのツール（agent-browser、portless）	rules/diagnostic-checks.md を読み込む
12. MCP Status	有効／無効の状態、認証情報のチェック、HIGH-tier の @latest ピン留め警告	rules/mcp-status-checks.md と references/mcp-pinning-check.md を読み込む
13. Plugin Validate	公式 CC の frontmatter と hooks.json の検証（CC >= 2.1.77）	rules/diagnostic-checks.md を読み込む
14. Effort/Model	実行できないことが明らかなモデルに xhigh effort が設定されている場合（下記参照）。デフォルトでは通知なし	インライン
15. Sandbox Posture	4 つすべての設定スコープにおける CC Bash サンドボックスのオン／オフ状態と、/sandbox の通知（オプトイン、Bash のみ、情報レベル）。15b：scripts/check-sandbox-violations.sh による、macOS 統合ログの最近の Sandbox 拒否イベントの範囲を限定した読み取り専用クエリ（警告レベル。ログクエリ自体が拒否された場合はフェイルクローズし、macOS 以外では明示的にスキップ）	references/sandbox-posture.md を読み込む
16. Operator Settings Posture	プラグインバンドルには含められない設定をチェックします。そのため、これらの設定が存在するのはオペレーターが記述した場合のみです。認証情報の読み取りに関する permissions.deny ルール（多層防御：pretool/read/credential-read-guard がすでに Read ツールを保護しています）、network.deniedDomains を含む sandbox ブロック（エグレスガードはアップロード形式の場合にのみ ask し、通常の GET は対象外です）、および CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS（ork 独自の agent-teams.ts がこの変数を条件にしています）。CC 2.1.257 以降では、permissions.blockReadsOutsideWorkingDirectories も報告し、これが true なのに additionalDirectories に ~/.claude が含まれていない場合は警告します（ork のスキルがプロジェクト外で行う読み取りは、確認を求められず拒否されます）。#3877 以降では、ユーザースコープの true を上書きするプロジェクトスコープの sandbox.enabled: false も示します（sandbox_override、プロジェクトのファイルと行、ユーザーのファイルと行。プロジェクトのファイルが優先され、Bash はサンドボックスなしで実行されます）。#3835 以降、監査はスクリプトで実行します：bash ${CLAUDE_SKILL_DIR}/scripts/check-operator-permissions.sh <project_dir> --json（すべてのペイロードルールが適用されていれば終了コード 0、不足があり対処法を示す場合は 1、確認できなかった場合は 2）。対処法はセットアップのフェーズ 3.6 で、同意が必要です。警告レベル。貼り付け用に JSON を出力します	references/settings-posture.md を読み込む

チェック 16 が存在する理由： plugins-reference.md:858 には、プラグインに同梱された settings.json で現在サポートされているのは「agent と subagentStatusLine のキーのみ」と記載されています。ork が以前ここで宣言していたそれ以外の設定はすべて機能しておらず、提供されているように見えた保護は実際には一度も有効になっていませんでした。チェック 16 はその代替策です。CC が実際に読み取るスコープで不足を検出し、オペレーターに正確な JSON を提示します。ork:configure スキルの Operator-Scope Settings セクションには、#3424 に従って段階的に適用する、緩い設定から厳しい設定への貼り付け可能なブロックがあります。完全な JSON は ../configure/references/operator-scope-settings.md にあります。

カテゴリー 14：エフォート／モデルの互換性（CC 2.1.111+）

CC 2.1.111 で xhigh エフォート層が追加されました。このカテゴリーが存在する唯一の理由は、何も通知されないことです。xhigh を実装していないモデルでは、エラーも警告もログ出力もないままリクエストが high に引き下げられるため、該当するスキルが記述している追加の深掘りパスが、目に見える通知なしに失われます。CC が引き下げ自体を通知するようになった場合は、このカテゴリーを削除してください。

チェックはモデル名ではなく、対応能力に基づいて行います。ここに「現在の最先端モデル」をハードコードしてはいけません。そうすると、次のモデルがリリースされた日に誤検知が発生し、すでに旧式のモデルへのダウングレードを指示することになります。

このチェックを src/hooks/src/lib/models.vocab.json 経由で行わないでください。 このファイルはモデル ID／価格の語彙であり、エフォートや対応能力のフィールドは一切含まれていません。そのため、これを基準にすると、チェックは意図的に通知を抑えるのではなく、恒久的かつ偶発的に機能しなくなります。

検出（問題を示す確かな証拠がある場合のみ警告）：

1. 次の順序で設定済みのエフォートを解決します。.claude/settings.json の effort、次に $ORCHESTKIT_EFFORT（エフォート検出フックによって設定）、その次に effort: xhigh を明示的に設定した .claude/chain/*.json のエントリーです。どこにも xhigh がなければ合格とし、出力はありません。
2. アクティブなモデル ID を解決します。
3. そのモデル ID が doctor の以下のローカル XHIGH_UNSUPPORTED_PREFIXES テーブル内のプレフィックスと一致する場合のみ警告します。それ以外のすべてのケース（モデルがテーブルにない、モデル ID を解決できない、設定ファイルがない）は合格です。問題を証明できないチェックは通知を出しません。

# 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
]

テーブルが空、または短い状態が正しい通常の状態です。ここで何も通知されないのは「doctor に問題を示す証拠がない」という意味であり、事実です。一方、認識されていないモデルに対して名前を照合して失敗と判定するのは誤りです。

警告の形式（モデル名はハードコードせず、両方の値を実行時に読み込みます）：

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.

終了コード：警告が実際に発生した場合に限り、--json モードではゼロ以外になります。対話モードではソフト警告です。何も通知されずに合格した場合、終了コードは 0 です。

レポート形式

各カテゴリーは、合格／警告／失敗のステータスを明示します。また、警告や失敗にはすべて、その種類に応じた具体的な修正手順（実行する正確なコマンド、編集するファイル、または変更する設定）が付属します。doctor は診断するとともに修正方法を提示し、問題を列挙するだけではありません。

ASCII レポートのテンプレート、JSON CI 出力スキーマ、終了コードについては Read("references/report-format.md") を読み込んでください。

結果の解釈とトラブルシューティング

結果の完全な解釈表と、よくある失敗（スキルの検証、ビルドの同期、メモリー）に関するトラブルシューティング手順については Read("references/remediation-guide.md") を読み込んでください。

--safe-mode で切り分ける（CC 2.1.169+）： doctor の検出結果でセッションの不具合を説明できない場合は、claude --safe-mode（または CLAUDE_CODE_SAFE_MODE=1）で再起動します。これにより、すべてのカスタマイズ（CLAUDE.md、ork を含むプラグイン、スキル、フック、MCP）が無効になります。問題が解消した場合は、カスタマイズが原因です。半分ずつ再び有効にして、原因を特定してください。問題が続く場合は CC 自体が原因です。上流に報告してください。

ホストの負荷とセッションの負荷（macOS）： doctor の検出結果でセッションは正常なのにマシンの動作が遅い場合は、memory_pressure の「システム全体の空きメモリー率」だけを根拠に診断しないでください。以前、この値が空き容量 84% と表示された一方で、64 GB 中 59 GB が使用中、スワップも 8 GB 中 6.9 GB が使用中だったことがあり、この数値をもとに最初に指摘した原因も誤っていました（実際の負荷は別プロジェクトのテストスイートでした）。原因を決めつける前に、証拠を確認してください。スワップには sysctl vm.swapusage、メモリーの内訳には vm_stat、実際にメモリーを消費しているプロセスの確認にはメモリー使用量順のプロセス表示（例：ps aux | sort -nrk 4 | head）を使ってください。

問題を修正した後

CC 2.1.69+：/reload-plugins を実行すると、再起動せずに現在のセッションでプラグインの変更を有効にできます。

CC 2.1.116+：/reload-plugins とバックグラウンドのプラグイン自動更新で、追加済みのマーケットプレイスから不足しているプラグインの依存関係が自動インストールされるようになりました。不足している依存関係が原因でプラグインの読み込みに失敗したと ork:doctor が報告した場合も、/reload-plugins を実行すればその場で解決できるため、手動で plugin install を実行する必要はありません。

CC 2.1.152+：スキルディレクトリ（~/.claude/skills/ または .claude/skills/）にあるプラグインではないスキルの場合は、/reload-skills を実行すると、再起動せずに再スキャンできます。これは /reload-plugins に相当するスキル向けの機能です。

CC 2.1.268+：/plugin によるインストール、有効化、無効化は、メニューを閉じると反映されるため、その後に /reload-plugins を実行する必要はありません。

Chain：詳細監査

ヘルスチェックが正常に完了したら、オブザーバビリティパイプライン自体を監査します。

telemetry-inspect

doctor は構造（マニフェスト、フック、スキル、エージェント）を検証します。telemetry-inspect はデータプレーンを検証します。具体的には、各テレメトリ書き込み処理の行数、スキーマロック、増加傾向、および構造チェックでは検出できない孤立した分析ファイルを検証します。

関連スキル

• ork:configure - プラグインの設定
• ork:telemetry-inspect - 構造チェックが正常に完了した後、テレメトリ／分析パイプラインを監査する
• ork:quality-gates - CI/CD 統合
• security-scanning - 包括的な監査

参考資料

Read("references/<file>") または Read("rules/<file>") で必要に応じて読み込みます。

ファイル	内容
rules/diagnostic-checks.md	カテゴリ別の Bash コマンドと検証ロジック
rules/mcp-status-checks.md	認証情報の検証と誤設定の検出
references/remediation-guide.md	結果の解釈とトラブルシューティングの手順
references/health-check-outputs.md	カテゴリ別の出力例
references/skills-validation.md	スキルのフロントマターと構造のチェック
references/agents-validation.md	エージェントのフロントマターとツール参照のチェック
references/hook-validation.md	フックの登録とバンドルのチェック
references/memory-health.md	メモリシステムの整合性チェック
references/agent-memory-dir.md	エージェントごとの agent-memory ディレクトリ：孤立ファイル、古さ、150 行の警告、シークレット
references/permission-rules.md	権限ルールの検出
references/skill-preapproval.md	管理対象の allowManagedPermissionRulesOnly で allowed-tools の事前許可が停止するスキル（CC 2.1.282、2.1.284）の検出と管理者による対処
references/schema-validation.md	JSON スキーマへの準拠
references/report-format.md	ASCII レポートのテンプレートと JSON CI 出力
references/version-compatibility.md	CC のバージョンとチャンネルの検証
references/mcp-pinning-check.md	HIGH ティアの MCP @latest 警告ロジックとティアの信頼できる情報源
references/sandbox-posture.md	CC Bash サンドボックスのオン／オフ検出、/sandbox の推奨（Check 15）、統合ログの違反クエリ（15b）
references/settings-posture.md	オペレーター範囲のセキュリティ態勢：プラグインバンドルに含められない設定と、その欠落を検出する方法（Check 16）