Pituitary

Pituitary

AIネイティブ開発のための一貫性ガバナンス。

問題に気づかれる前に、ドリフトを検出しましょう。

検出できる問題 · クイックスタート · エージェント · CI · チートシート · リファレンス

人間とAIが仕様書、ドキュメント、意思決定を継続的に作成する開発者やチーム向けです。それらが整合しなくなっても、気づかないまま放置されることがあります。

インタラクティブ版はasciinemaで視聴できます。

単一バイナリです。Dockerは不要です。APIキーも必要ありません。ガバナンス用のSQLiteファイル1つと、ローカルのStromaスナップショット1つを使用します。

中核となる実装はローカルで動作し、CLIを最優先としています。MCPサーバー、CI連携、プロバイダーを利用するセマンティックランタイムは、同じ決定論的なコアを包むオプションのラッパーです。

検出できる問題

ドキュメントがドリフトすることは、すでにご存じでしょう。LLMによるクリーンアップで対処しても、LLMは「すべて問題ありません」と答えます。しかし、コンテキストウィンドウに収まる範囲しか確認していません。残りは劣化し続けます。実際には修正されていない矛盾に、新たな矛盾が重なるPRが次に提出されます。生産的に感じられても、いつまでも収束しない作業の繰り返しです。その一方で、トークンコストは積み上がっていきます。ドリフトした問題、矛盾する仕様、古いドキュメントが直接の原因となり、やり直しや誤った方向への誘導、コンテキストの浪費が発生します。

Pituitaryは、コーパス全体をインデックス化し、毎回すべてをチェックするという構造的な保証によって、その繰り返しをなくします。仕様書11件、ドキュメント29件を含む実際のリポジトリでは、22個の成果物にわたる非推奨用語の違反を90件、意味上の矛盾を7件検出しました。プロジェクトの方向性は、ドキュメントのドリフト、ランタイム契約の矛盾、至るところで見つかる非推奨の用語に悩まされていましたが、Pituitaryが解決しました。複数のリポジトリで利用すると、ガバナンスが集約される唯一の信頼できる情報源になります。

重複する意思決定。 新しい仕様書が、既存の仕様書ですでに扱っている範囲をカバーしています。

古いドキュメント。 仕様書が変更された場合や、コードの差分からドキュメントも古くなっている可能性がある場合に、それを参照しているCLAUDE.md、AGENTS.md、運用手順書、ガイドが更新されていません。

仕様書と矛盾するコード。 マージ前に差分をパイプで渡します。

git diff origin/main...HEAD | pituitary check-compliance --diff-file -

用語のドリフト。 チームで新しい用語を採用しても、古い用語がドキュメントや仕様書に残っています。

その先に広がる機能

Pituitary は、まずドリフト検出ツールとして始まります。意図コーパスが大きくなるにつれて、一貫性を管理するレイヤーへと進化します。

時間軸に沿ったガバナンス。 ガバナンスグラフに対して、特定時点のクエリを実行します。仕様が後続の仕様に置き換えられても、過去のガバナンスリンクは保持されますが、現在のクエリからは除外されます。check-compliance、check-doc-drift、または analyze-impact で --at DATE を使用します。タイムスタンプはインデックスの構築時刻または更新時刻から取得されます。

信頼度で重み付けされたエッジ。 ガバナンスリンクには、信頼度の階層があります。抽出済み（仕様に明記）、推定（AST のシンボルマッチング）、または曖昧です。check-compliance と check-doc-drift で --min-confidence を使用すると、適合率と再現率のバランスを調整できます。

意図的な逸脱と偶発的なドリフト。 コードが仕様と矛盾する場合、Pituitary は根拠を示すコメント（// WHY:、// HACK:、判断を示す表現）があるかを確認します。意図的な逸脱には、意図しないドリフトとは異なる修正方法が適用されます。

ガバナンス変更履歴。 index --update --show-delta を実行すると、追加・削除された仕様、作成・切断されたエッジ、ガバナンス方針の変化など、変更内容が報告されます。これは、CI に必要なフィードバックループです。

仕様ファミリー。 依存関係グラフに対してコミュニティ検出を行い、自然なガバナンスのクラスタを見つけます。ファミリー間のカバレッジの不足は、ガバナンスが及んでいない領域の中で最もリスクの高い箇所です。

AI 向けガバナンスプロトコル。 オプションの MCP ラッパーは、ガバナンスの確認方法だけでなく、いつ確認するべきかを AI アシスタントに教えます。たとえば、ファイルの変更前、コミット前、仕様の承認後、ドキュメントの作成時などです。

クイックスタート

pituitary init --path .              # discover, index, report
pituitary new --title "Rate limiting policy" --domain api  # scaffold a draft spec
pituitary check-doc-drift --scope all  # find stale docs
pituitary review-spec --path specs/X   # full review of one spec
pituitary status                       # index health and governance hotspots at a glance

コマンドリファレンス

すべてのコマンドは --format json を指定すると JSON を出力します。エージェントは PITUITARY_FORMAT=json を設定でき、標準出力をリダイレクトした場合も、自動的に JSON がデフォルトになります。review-spec は --format markdown と --format html にも対応しており、証拠の連鎖をすべて含む共有可能なレポートを作成できます。

ファイル選択が意図と異なる場合は、まず pituitary explain-file PATH を実行してください。どのソースがファイルに一致したか、どのセレクターが適用されたか、ドリフトやコンプライアンスの出力をデバッグする前にパスが除外された理由を確認する最も手早い方法です。

1 つの pituitary.toml で複数のリポジトリルートを対象にすることもできます。repo = "..." を指定してソースを名前付きのリポジトリルートに関連付けると、Pituitary は検索、ドリフト、影響、ステータス、インデックスの出力全体でそのリポジトリ ID を引き継ぎ、リポジトリをまたぐ結果を明確に保ちます。

pituitary status は、コーパスをすばやくトリアージできるよう、ガバナンス上のホットスポットも報告します。対象範囲が異常に広い applies_to を持つ仕様書、推論されたリンクや曖昧なリンクを通じてのみ弱く管理されている成果物、複数の仕様書によって現在管理されている成果物が対象です。

用語の移行では、--term／--canonical-term を使った場当たり的な監査を続けることも、設定に再利用可能な [[terminology.policies]] を宣言して pituitary check-terminology を直接実行することもできます。結果では、対応が必要な現在の違反と許容されている過去の用例が分けて表示されるようになりました。また、CHANGELOG.md のような過去の記録を含むファイルを対象とした用語監査専用の exclude_paths に対応し、テキストと JSON の両方の出力に置換候補が含まれます。

analyze-impact、check-doc-drift、review-spec は、JSON でセクション単位の証拠の連鎖も出力するようになりました。一致の両側にあるソース参照、classification、link_reason、および変更対象の候補や推奨箇条書きが含まれます。これにより、エージェントは文章をスクレイピングしたり、推測に基づく変更を自動編集したりすることなく、次に必要な手動編集を説明できるだけの構造化情報を得られます。

エージェントとの連携では、pituitary schema <command> --format json を使ってリクエスト／レスポンスの契約を確認してください。また、シェルでのエスケープ処理が不安定になりそうな分析コマンドでは、--request-file PATH|- を優先してください。生のリポジトリ抜粋や証拠を含む結果には result.content_trust メタデータが付くようになりました。これにより、呼び出し元は返されたワークスペースのテキストを実行可能な指示ではなく、信頼できない入力として扱えます。

すべてのコマンドについてはチートシート、設定、ランタイム、仕様書の詳細については完全なリファレンス、複数のエディターで再利用できるパッケージについてはskills/pituitary-cli/README.md、リポジトリに固有のエージェント向け指示についてはAGENTS.mdを参照してください。

インストール

macOS（Homebrew）：

brew install dusk-network/tap/pituitary

Linux / macOS（バイナリ）：GitHub Releasesからダウンロードし、次のコマンドを実行します。

tar xzf pituitary_*_*.tar.gz
sudo install pituitary /usr/local/bin/

Windows：GitHub Releasesからpituitary_<version>_windows_amd64.zipをダウンロードし、pituitary.exeを展開して、その場所をPATHに追加します。

ソースからビルド（コントリビューター向け）：docs/development/prerequisites.mdを参照してください。

エージェントが古い決定に基づいて作業するのを防ぐ

エージェントは仕様書を作成し、PRをレビューし、変更を提案しますが、すでに何が決定されているかは把握していません。Pituitaryは、そのコンテキストを提供します。ガバナンスプロトコルは、確認方法だけでなく、確認すべきタイミングもエージェントに教えます。

オプションのMCPサーバー（Claude Code、Cursor、Windsurf、または任意のMCPクライアント）

{
  "mcpServers": {
    "pituitary": {
      "command": "pituitary",
      "args": ["serve", "--config", ".pituitary/pituitary.toml"]
    }
  }
}

エージェントは15個のツールを利用できます：search_specs、check_overlap、compare_specs、analyze_impact、check_doc_drift、review_spec、get_intent_outline、expand_intent_context、check_compliance、check_terminology、governed_by、compile_preview、fix_preview、status、explain_file。焦点を絞ったコンテキストを得るには、まず検索し、get_intent_outlineで返されたレコードを確認してから、同じsnapshot_fingerprintを使って、選択したチャンクIDをexpand_intent_contextで展開します。

共有スキル（Claude Code、Cowork）

cp -R skills/pituitary-cli ~/.claude/skills/pituitary-cli

Codex CLIとGemini CLIは、プロジェクトポリシーをAGENTS.md / GEMINI.mdから自動的に取得します。Pituitaryの分析ワークフロー全体を利用するには、スキルパッケージもインストールしてください：cp -R skills/pituitary-cli ~/.codex/skills/pituitary-cliまたは~/.gemini/skills/。

エディタールール（Cursor、Windsurf、Cline）

cp skills/pituitary-cli/platforms/cursor/.cursorrules .cursorrules        # Cursor
cp skills/pituitary-cli/platforms/windsurf/.windsurfrules .windsurfrules  # Windsurf
cp skills/pituitary-cli/platforms/cline/.clinerules .clinerules           # Cline

AGENTS対応ツール（Codex CLI、Gemini CLIなど）

リポジトリのAGENTS.mdが、プロジェクトポリシーの正式な情報源です。AGENTS.mdを読み込むツールは、Pituitaryを自動的に認識します。生成されたミラー（CLAUDE.md、GEMINI.md）は互換性のための出力であり、独立したポリシーの情報源ではありません。

インストール手順の全容、リクエストテンプレート、セキュリティに関する注意事項については、skills/pituitary-cli/README.mdを参照してください。

CI 連携（任意）

すでに GitHub Actions を使用している場合は、チェックイン済みのアクションで同じローカル CLI ワークフローをラップし、review-spec の出力を PR コメントとして投稿できます。

permissions:
  contents: read
  pull-requests: read
  issues: write

steps:
  - uses: dusk-network/[email protected]
    with:
      fail-on: error
      # Set this when your repo keeps config at the root instead.
      # config-path: pituitary.toml

リンターとあわせて、仕様の健全性チェックを追加できます。

- run: pituitary index --rebuild
- run: git diff origin/main...HEAD | pituitary check-compliance --diff-file -
- run: git diff origin/main...HEAD | pituitary check-doc-drift --diff-file -
- run: pituitary check-doc-drift --scope all

GitHub Actions の完全なレシピについては、docs/development/ci-recipes.md をご覧ください。

[runtime.embedder]
provider = "openai_compatible"
model = "text-embedding-3-small"
endpoint = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"

[runtime.profiles.local-lm-studio]
provider = "openai_compatible"
endpoint = "http://127.0.0.1:1234/v1"
timeout_ms = 30000
max_retries = 1

[runtime.embedder]
profile = "local-lm-studio"
model = "nomic-embed-text-v1.5"

[runtime.analysis]
profile = "local-lm-studio"
model = "your-analysis-model"
timeout_ms = 120000

pituitary status
pituitary status --check-runtime all
pituitary index --rebuild

アーキテクチャ

システム設計の全容については、ARCHITECTURE.md をご覧ください。主な設計上の決定事項は、決定論的な検索を優先すること、ツールのみとすること（エージェントを組み込まないこと）、ガバナンス用の SQLite ファイル 1 つと、不透明なローカル Stroma スナップショットを使用してアトミックに再構築することです。

プロジェクトの状況

現在、積極的に開発中です。中核となる分析機能は、重複、乖離、影響、コンプライアンス、用語、コンパイル、仕様の鮮度、レビューの各ワークフローで、すでにエンドツーエンドで機能しています。ガバナンスグラフは、時間的な有効性、信頼度の段階、仕様ファミリーの割り当てに対応しています。Pituitary は整合性ガバナンスのためのものであり、コードのリントツールではありません。通常の LLM による整理で見落とされた古い決定の反映ではなく、実際に決めた内容に基づいてプロジェクトをビルドできるようにします。docs/rfcs/0001-spec-centric-compliance-direction.mdをご覧ください。

実装済みの機能、今後の予定、Pituitary の将来については、ROADMAP.mdをご覧ください。

コントリビューション

CONTRIBUTING.mdをご覧ください。コードベースはパッケージの境界が明確なため、システム全体を理解していなくても、特定の領域にコントリビュートできます。

ライセンス

MIT