swain-doctor

Doctor

swain プロジェクトのセッション開始時に実行するヘルスチェックです。すべての検出処理では、統合スクリプトを唯一の正とします。このスキルファイルでは、スクリプトの実行方法と各チェックへの対処方法を定義します。

スクリプトの実行

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-doctor.sh"

スクリプトは { checks: [...], summary: {...} } 形式の構造化 JSON を出力します。各チェックには name、status、message と、任意の detail があります。これを解析し、概要の表をオペレーターに提示してください。その後、warning または advisory ステータスが報告されたチェックに限り、以下の対処方法を使用してください。検出を再実行しないでください。

フラットファイルのアーティファクトを自動修正するには、次を実行します。bash "$REPO_ROOT/.agents/bin/swain-doctor.sh" --fix-flat-artifacts

スクリプトを利用できない場合（例：.agents/bin/ のシンボリックリンクがまだ初期化されていない場合）は、skills/swain-doctor/scripts/swain-doctor.sh にあるスクリプトのソースからチェックを実行してください。チェックは順番に実行してください（Bash の呼び出しは一度に 1 つ）。並列実行はしないでください。並列のツール呼び出しは、最初のエラーで連鎖的にキャンセルされます。

Preflight との連携

軽量なシェルスクリプト（$REPO_ROOT/.agents/bin/swain-preflight.sh）は、完全な doctor を実行する前に簡易チェックを行います。preflight が 0 で終了した場合、そのセッションでは swain-doctor をスキップします。1 で終了した場合は、通常どおり swain-doctor を実行します。

ユーザーが直接呼び出した場合（自動呼び出し経由ではない場合）、preflight のステータスにかかわらず、swain-doctor は常に実行されます。

ガバナンス内容の参照先

正規のガバナンスルールは references/AGENTS.content.md にあります。swain-doctor と swain-init は、どちらもこの唯一の信頼できる情報源を読み込みます。今後の swain リリースで上流のルールが変更された場合は、そのファイルを更新し、スキルのバージョンを上げてください。

---

チェック名ごとの対処方法

以下の各セクションは、スクリプトが出力するチェック名に対応しています。チェックのステータスが warning または advisory の場合に限り、該当するセクションを参照してください。

governance

Injection（欠落）： Claude Code と Cursor への注入手順については、references/governance-injection.md を参照してください。ソース：references/AGENTS.content.md。

Replacement（古い内容）： 両方のマーカー（と）が存在する場合、スクリプトは古いガバナンスブロックを自動修復します。自動修復に失敗した場合（マーカーがない場合）は、手動で置き換える手順について references/governance-injection.md § 古いガバナンスの置き換え を参照してください。

legacy_skills

フィンガープリントチェックを使用して、名前が変更されたスキルディレクトリと廃止されたスキルディレクトリを整理します。手順の詳細は references/legacy-cleanup.md を参照してください。データソース：references/legacy-skills.json。

agents_directory

mkdir -p .agents を実行して .agents/ を作成します。このディレクトリは、swain-do が設定に、swain-design のスクリプトがログに使用します。

tickets

.tickets/ の状態（YAML フロントマター、古いロック）を検証します。修復手順については references/tickets-validation.md を参照してください。

beads_migration

.beads/ が存在する場合、.beads/ → .tickets/ へ自動移行します。移行手順については references/beads-migration.md を参照してください。

tools

必須ツール：git、jq。任意ツール：tk、uv、gh、tmux、fswatch。自動でインストールしないでください。機能縮退に関する注意事項とインストール手順については references/tool-availability.md を参照してください。

settings

swain.settings.json がない場合は、デフォルトの内容で作成します。無効な JSON が含まれている場合は、構文を修正します。ユーザー設定は ${XDG_CONFIG_HOME:-$HOME/.config}/swain/settings.json にあります。

script_permissions

スクリプトは、スキルツリー内の .sh ファイルと .py ファイルに実行権限がない場合、自動で修復します。手動での対処は不要です。ステータスが advisory の場合は、すでに修復済みであることを示します。

memory_directory

スクリプトは、メモリディレクトリがない場合、自動で作成します。作成に失敗した場合は、次のコマンドで手動作成してください。

mkdir -p "$HOME/.claude/projects/$(echo "$REPO_ROOT" | tr '/' '-')/memory"

superpowers

ステータスが warning（未インストールまたは一部のみインストール）の場合は、オペレーターに尋ねます。

Superpowers (obra/superpowers) がインストールされていません［または、一部のみインストールされています］。TDD、ブレインストーミング、計画の作成、検証のスキルを提供し、swain はこれらを連携させて使用します。

今すぐ superpowers をインストールしますか？（yes/no）

yes の場合：npx skills add obra/superpowers。no の場合は「Superpowers: skipped」と記録して続行します。

epics_initiative

ブロックしない助言です。件数を報告し、次のように提案します。

parent-vision はあるものの parent-initiative がない Epic が N 件あります。parent-initiative リンクの追加は任意ですが、推奨されます。ガイド付きの移行を実行するには、「run the initiative migration」と尋ねてください。

ガイド付き移行の全 6 ステップのワークフローについては、references/initiative-migration.md を読んでください。

readme

次のように報告します：README.md missing — swain alignment loop has no public intent anchor. Run swain-init to seed one.

artifact_indexes

このスクリプトは、rebuild-index.sh を使用して古いインデックスを自動修復します。再構築スクリプトが利用できない場合、または再構築に失敗した場合は、.agents/bin/rebuild-index.sh が存在し、実行可能であることを確認してください。シンボリックリンクを修正したら、swain-doctor を再実行します。

evidence_pools

docs/evidence-pools/ が存在する場合は、trove の移行を実行します。

bash "$REPO_ROOT/.agents/bin/migrate-to-troves.sh" --dry-run  # preview
bash "$REPO_ROOT/.agents/bin/migrate-to-troves.sh"            # migrate

worktrees

HEAD にすでにマージ済みのブランチを持つ古い worktree は、git worktree remove <path> で削除できます。ディレクトリが存在しない孤立した worktree は、git worktree prune で削除できます。古いロックファイルと未割り当ての worktree は、詳細フィールドに報告されます。分類ルールについては、references/worktree-detection.md を読んでください。

worktree_context

すべてのリンク済み worktree（それらは worktrees の対象）ではなく、現在のセッションの worktree を検証します。4 つすべてのサブチェックは決定的に自動修正されます。warning は自動修正に失敗したことを意味し、advisory は自動修正に成功したことを意味します。

.worktrees/ の外にある場所（自動移動）：ADR-034 では、正規の場所として .worktrees/ が定められています。スクリプトは git worktree move <path> <main_root>/.worktrees/<branch> を使って worktree を自動移動します。失敗（warning）は、移動先のパスがすでに存在するか、git worktree move が失敗したことを意味します。手動で解決してください。

ロックファイルがない（自動作成）：スクリプトは swain-lockfile.sh claim を使用して .agents/worktrees/<branch>.lock にロックファイルを自動作成します。失敗した場合は、ロックファイルを直接書き込みます。同じブランチのロックファイルがすでに存在する場合は、PID を接尾辞に付けたロックファイルが作成されます。advisory は自動作成済み、warning は作成失敗を意味します。

ブランチ名が ADR-025 に違反（自動リネーム）：スクリプトはブランチ名を自動変更し、ADR-025 の命名規則に合わせて worktree フォルダーを移動します。目的が指定されている場合は swain-worktree-name.sh を使用し、指定されていない場合は session-<timestamp> を使用します。ロックファイルもリネームされます。advisory はリネーム済み、warning はリネーム失敗を意味します。

フォルダー名 != ブランチ名（自動移動）：スクリプトは git worktree move を使用して worktree フォルダーを自動移動し、basename がブランチ名と一致するようにします。advisory は移動済み、warning は移動失敗（移動先がすでに存在）を意味します。

lifecycle_dirs

ADR-003 の 3 トラック正規化より前の古いフェーズディレクトリです。検出コマンド、修正手順、移行スクリプトについては、references/lifecycle-migration.md を読んでください。

tk_health

ベンダー提供の tk が見つからない場合、または実行可能でない場合は、/swain update を実行してスキルを再インストールしてください。想定されるパスは <skills-root>/swain-do/bin/tk です。

operator_bin_symlinks

スクリプトは、欠落または古い bin/ シンボリックリンクを自動修復します。競合（bin/<name> に実ファイルが存在する場合）は手動で解決する必要があります。競合するファイルの名前を変更するか削除してから、doctor を再実行してください。

commit_signing

スクリプトは、~/.ssh/swain_signing に署名キーが検出された場合、コミット署名を自動で有効にします。キーがない場合は、/swain-keys を実行してキーを用意してください。

ssh_readiness

scripts/ssh-readiness.sh --check を実行します。問題は詳細フィールドに報告されます。よくある修正方法：~/.ssh/config.d/ にプロジェクト固有の SSH エイリアスが含まれていることを確認し、キーの権限を確認し（chmod 600）、リモートホストにキーが追加されていることを確認します。

crash_debris

古くなった .git/index.lock ファイルはスクリプトが自動的に削除します。その他のクラッシュ残骸（孤立した一時ファイル、部分的なマージ）は手動でのクリーンアップが必要なものとして報告されます。詳細フィールドで具体的なファイルパスを確認し、安全であれば削除します。

agents_bin_symlinks

不足している、または古くなった .agents/bin/ シンボリックリンクはスクリプトが自動的に修復します。壊れたシンボリックリンクは削除されます。競合（実ファイル）は手動での解決が必要なものとして報告されます。

flat_artifacts

フラットファイル形式の成果物は、専用フォルダーではなくフェーズディレクトリに直接配置されています。--fix-flat-artifacts を指定して実行すると、自動的に移行できます：bash "$REPO_ROOT/.agents/bin/swain-doctor.sh" --fix-flat-artifacts。各成果物には (<ID>)-<Title>/ という名前のフォルダーが作成されます。

swain_symlink

bin/swain シンボリックリンクがないものの、スクリプトが <skills-root>/swain/scripts/swain に存在する場合は、次のように作成します：

ln -sf "$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1], sys.argv[2]))" "$SKILLS_ROOT/swain/scripts/swain" "$REPO_ROOT/bin")" "$REPO_ROOT/bin/swain"

シンボリックリンクが壊れている場合（ターゲットが見つからない場合）、swain スキルの再インストールが必要な可能性があります：/swain update。

branch_model

参考情報 — swain は trunk+release ブランチモデル（ADR-013）を推奨しています。trunk は開発ブランチ、release は配布ブランチで、リリース時に squash-merge で更新されます。このモデルを採用するには、.agents/bin/migrate-to-trunk-release.sh を実行します（プレビューするには --dry-run を指定します）。これは任意です — swain はどのブランチモデルでも動作しますが、設定されている場合、同期機能とリリース機能は trunk+release を前提とします。

platform_dotfolders

インストールされていないエージェントプラットフォームのドットフォルダーのスタブを削除します。検出とクリーンアップの手順については、references/platform-cleanup.md を参照してください。jq が必要です。スクリプトは孤立しているドットフォルダーを報告します — 削除する前に、インストーラーのシンボリックリンクのみが含まれていることを確認してください。

skill_gitignore

ベンダー提供の swain スキルフォルダーは、利用側プロジェクトで gitignore に追加する必要があります。修正手順については、references/gitignore-skill-folders.md を参照してください。次のエントリーを .gitignore に追加します：

.claude/skills/swain/
.claude/skills/swain-*/
.agents/skills/swain/
.agents/skills/swain-*/

swain のソースリポジトリで実行する場合は自動的にスキップされます。

---

Summary report

すべてのチェックが完了したら、簡潔なサマリーテーブルを出力します：

swain-doctor summary:
  Governance ......... ok
  Legacy cleanup ..... ok (nothing to clean)
  Platform dotfolders  ok (nothing to clean)
  .agents directory .. ok
  .tickets/ .......... ok
  Stale .beads/ ...... ok (not present)
  Tools .............. ok (1 optional missing: fswatch)
  Settings ........... ok
  Script perms ....... ok
  Memory directory ... ok
  Superpowers ........ ok (6/6 skills detected)
  Epics w/o initiative advisory (3 epics — see note below)
  README ............. ok
  Artifact indexes ... ok
  Evidence pools ..... ok
  Worktrees .......... ok
  Worktree context ... ok
  Lifecycle dirs ..... ok
  tk health .......... ok
  Operator bin/ ...... ok
  Commit signing ..... ok
  SSH readiness ...... ok
  Crash debris ....... ok
  .agents/bin/ ....... ok
  Flat artifacts ..... ok
  swain symlink ...... ok
  Branch model ....... ok
  Skill gitignore .... ok

3 checks performed repairs. 0 issues remain.

次のステータス値を使用します：

• ok — 対応不要です。
• advisory — 自動修復された、または情報提供のみの項目です（詳細を記載します）。
• warning — 問題が見つかり、ユーザーによる対応が推奨されます（詳細を記載します）。
• skipped — チェックを実行できませんでした（例：JSON 検証に必要な jq がありません）。

警告があるチェックについては、上記の各セクションに記載された修正手順とともに、テーブルの下に一覧表示します。