repotector

Repotector ⬡

記憶するリポジトリ。

リポジトリを訪れる AI エージェントは、毎回ゼロから始めます。構成を再び把握し、規約を再発見し、直前のエージェントが修正した箇所をまた壊してしまいます。Repotector は、リポジトリ自体に記憶を持たせます。到着したエージェントが正面玄関をノックすると、ハンドシェイクを行い、構成、現在有効な決定事項、前の訪問者からの引き継ぎ事項を受け取ります。退出時には、訪問者名簿に記録します。次のエージェントは、1 時間さまよう代わりに 2 分で作業を続けられます。リファクタリングによって、すでに動いているものがひそかに壊れることもありません。

移植性が高く、自己完結しています。純粋な Node ESM で、依存関係は 2 つ（@modelcontextprotocol/sdk、zod）です。あらゆるリポジトリで動作します。JS/TS は深く解析し、それ以外のスタックでは、正直なところ概要レベルの把握にとどまります。

任意のリポジトリにインストールする

cd /path/to/your/repo
npx repotector init

init はリポジトリをスキャンし（初日から失敗することはありません。下記の 既存ベースライン を参照）、MCP サーバーを .mcp.json に設定し、到着するエージェントが必ずハンドシェイクするように玄関ブロックを書き込みます。書き込み先は .repotector/ 内と REPOTECTOR:BEGIN/END マーカー内だけです。既存の文章や設定が上書きされることはありません。詳細なセキュリティ方針については、SECURITY.md を参照してください。

.repotector/ 内：

ファイル	内容
intent.json	契約です。標準、必須パス、境界づけられたコンテキスト、正典ルールを定義します。
atlas.json	マップです。ファイルごとのエクスポート／インポート／目的／種別、ルート、コンポーネント、スタック、および決定論的なフィンガープリントを記録します。
dna.json	リバースエンジニアリングで得られたエンティティ、API 契約、意図です。
baseline.json	既存の土台です。初日に存在していた負債を記録します。
proof.json	ゲートの判定と、既存負債に対するリグレッションです。
register.jsonl	訪問者台帳です。誰がいつ入り、何に触れ、誰が中にいるかを記録します。
dna.inferred.json	外部リポジトリ向けの逆 DNA 条項です（.psx/ ミラーが存在する場合はスキップされます）。

さらに、リポジトリのルートには、新しい順に並んだ航海日誌 JOURNAL.md が再生成されます。handshake はその末尾を提供するため、次のエージェントは再び解析し直すことなく、前の作業を引き継げます。

正面玄関（ハンドシェイク優先）

MCP サーバーは、エージェントが handshake を呼び出すまで高度なツールを拒否します。また、initialize の応答で、エージェントにその呼び出しを促します。その見返りとして、エージェントは1回の呼び出しで状況を把握でき、退出時の情報は次回のために記録されます。

• handshake({ who, model?, purpose? }) — 状況説明、基本ルール、ゲートの最新判定、マップの鮮度、パスポートを返します。読み取り専用で高速です（ツリー全体の走査は行いません）。
• city_map() — 目的、スタック、実装済みと未実装の項目、ブレインへのポインターを返します。JavaScript 以外のリポジトリでは、空のマップを装う代わりに orientation-lite と表示します。
• find_existing({ intent }) — 再利用：すでに存在しているかを確認します。作り直さないでください。
• blast_radius({ changedFiles? }) — 保護：推移的な依存先と、影響を受けるルート／コンポーネントを返します。changedFiles を省略すると、git diff が使用されます。
• canon_check({ changedFiles? }) — 統合：リポジトリの規範ルールを確認します。
• atlas_query({ query }) — マップ全体をキーワード検索します。
• quality_gates() — 行数制限／構造／シークレットの衛生状態を確認し、既存の負債に対するリグレッションとして報告します。
• register() — 現在参加しているメンバーと、すべての入退室ログを返します。
• journal({ limit? }) — リポジトリの最近の経緯を返します。以前のエージェントが行ったことと、未完了のまま残したことを確認できます。whats_next() — DNA の不足、未解決のスレッド、TODO をもとに、妥当な次の作業を提案します。提案にはそれぞれ根拠が示されます。
• dna_query({ clause?, topic? }) — リポジトリで仕様として定められている内容を返します（.psx/ ミラーから作成されたもの、または推論されたものであり、統合されたものではありません）。dna_coverage() — 条項ごとに、実装済み／一部実装／未実装を示します。dna_diff({ changedFiles? }) — 変更がどの条項に関係するかを返します。
• depart({ summary? }) — サインアウトします。要約を忘れても、滞在中の git 差分は記録されます。要約は次のエージェントへのブリーフィングになります。

既存状態のベースライン — 初日から赤信号にはなりません

インストールした瞬間にリポジトリを失格にするガーディアンは、インストールした瞬間にアンインストールされます。そのため init は、すでに存在する負債（サイズ超過のファイル、追跡対象のシークレット、存在しないパス）をスナップショットとして記録します。ゲートは、その基準を超えるリグレッションがある場合にのみ失敗します。つまり、新しい違反、増加した違反、新たな漏洩が対象です。既存の負債は明確に報告されますが、処理を妨げることはありません。負債を減らした後は repotector baseline で再度スナップショットを取得します。

v1.2「Gatekeeper」— アドバイザーからチェックポイントへ

• コミットガード — repotector hooks は、ゲートを実行する pre-commit をインストールします。gates はリグレッションがあるとゼロ以外の終了コードを返すため、フックと CI で実際にブロックされます。既存状態のベースラインにより、初日から存在する負債をブロックすることはなく、新たな損害のみをブロックします。
• 保護対象パス — intent.protect.paths の glob（CI ワークフロー、LICENSE…）で指定されたパスは、エージェントが変更してはいけません。変更ベースで判定され、既存状態として扱われることはありません。上書きするには、インテントを編集する必要があります（明示的に差分を確認できる操作です）。
• クレーム — claim({ paths }) で作業範囲を宣言します。実行中のセッションとクレームが重複すると、誰が、なぜその範囲を使用しているかを示して granted:false を返します。設計上、これは助言にとどまります（制御できないファイルシステム上でブロックしても、見せかけにしかならないためです）。クレームはセッションの終了とともに消滅します。
• 意思決定記録 — depart({ decisions: [{ chose, over, because }] }) は、理由をレジスターに記録し、DECISIONS.md に反映します。ハンドシェイクでは継続中の意思決定が提示され、decisions_query では「これは意図的な判断だったか？」を確認できます。これにより、エージェント2がエージェント1の選択を取り消すことを防ぎます。
• repotector doctor — 1つのコマンドで、「このリポジトリは実際にどれほど保護されているか？」への明確な回答と、赤信号ごとの修正方法を確認できます。

v1.5「Mission」— 検証可能な単一のチェーン

訪問全体が、監査可能な1つの契約になります。

handshake → declare_mission → (auto)claim → work
        → off-claim / forbidden reconciliation
        → evidence pack (machine-verified vs agent-declared)
        → depart → the next agent inherits it all

• declare_mission({ goal, acceptance, claimPaths?, forbiddenPaths?, risk? }) — 訪問を契約に紐付けます。担当ゾーンは自動で確保され（競合は通知されます）、1回限りのブリーフィング（ゲート、マージ状況、継続中の決定、保護対象パス）が提供されます。
• 退出時のエビデンスパック — レジスターには、MACHINE が検証した内容（ゲートの判定、トライアルマージの成功／競合、変更したファイル、担当外の変更、禁止事項への違反）と、AGENT が宣言した内容（基準ごとの自己報告）が厳密に分けて記録されます。報告されていない基準は一覧に記載され、満たしたものとは見なされません。「完了」は、社交辞令ではなく、レジスターで確認できるものになります。
• 他のエージェントはハンドシェイク時に進行中のミッションを確認できます。確認できるのは、担当場所だけでなく、作業内容です。

v1.3「Merge Guard」— 衝突せずにコミット

• merge_check — コミット前に実行する、HEAD と統合ベース間の損傷ゼロのトライアルマージ（git merge-tree）です。結果が成功か競合かを、該当ファイルと、そのゾーンの担当者ごとに報告します（現在の claim、および PSX Workbench リポジトリでは、.psx ミラー経由で Merge Machine のリースも確認します）。 CLI：repotector merge-check [target]（競合時は終了コード 1。フック／CI の判定に利用できます）。ネットワーク接続は不要です。ローカルの refs を使ってトライアルマージを行い、その旨を表示します。最新の状態を確認するには、先に fetch してください。

回復力のあるレジスター — エージェントがサインアウトせずに終了しても対応

開始したまま終了していないセッション（エージェントが強制終了された、パイプが閉じられたなど）は、次のハンドシェイク時に、変更した内容の git 差分とともに自動退出処理されます。台帳に終了しないセッションが際限なく残ることはなく、退出処理を誰も呼び出さなかった場合でも、実際の作業内容が記録されます。

CLI

npx repotector init          # scan, wire .mcp.json, write the doors — day-one green
npx repotector refresh       # re-derive the map + re-stamp the doorway blocks
npx repotector handshake     # orientation + live gate + passport (logged visit)
npx repotector city-map      # built-vs-missing + brain pointers
npx repotector dna-coverage  # per specified clause: implemented / missing
npx repotector whats-next    # the sensible next work, with evidence
npx repotector journal       # the diario di bordo (regenerates JOURNAL.md)
npx repotector gates         # regressions vs grandfathered debt
npx repotector baseline      # re-snapshot the grandfathered floor
npx repotector register      # the visitor ledger
npx repotector lock <pass>   # optional passphrase gate on the deep map
npx repotector mcp           # start the stdio MCP server

Docker

GHCR のイメージには CLI と MCP サーバーが含まれます。保護対象のリポジトリはマウントされ、イメージには組み込まれません。

docker run --rm -v "$PWD:/repo" ghcr.io/dir-ai/repotector init
docker run --rm -v "$PWD:/repo" ghcr.io/dir-ai/repotector gates
docker run -i --rm -v "$PWD:/repo" ghcr.io/dir-ai/repotector mcp   # stdio MCP

マルチアーキテクチャ（amd64/arm64）に対応。リリースタグごとに CI がビルドし、スモークテストを実行します（Dockerfile を参照）。

GitHub Action

1つのステップで CI 内のリポジトリを保護できます。既存の状態は引き継がれるため、ジョブが失敗するのはリグレッションがあった場合だけで、初日から存在する負債が原因で失敗することはありません。

- uses: dir-ai/repotector@main
  with:
    command: gates     # default; any CLI command works
    version: latest    # pin an exact npm version for reproducible CI

誠実さ

Repotector はリポジトリを保護するため、自身にも同じ基準を適用します。ロックはコンプライアンスのシグナルであり、ファイルシステムのアクセス制御ではありません。レジスターは追記の完全性を保証しますが、改ざんを防止するものではありません。静的バッジは自己申告です。起動するのは git のみで、ネットワーク呼び出しは行わず、.mcp.json には正確なバージョンを固定します。脅威モデルの全容は SECURITY.md に記載されています。見せかけのセキュリティ対策はありません。

決定性

Atlas の fingerprint は、ソース内容をソートして計算する SHA-256（16 桁の 16 進数）で、タイムスタンプは含まれません。同じツリーなら常に同じ fingerprint になります。大きなファイル（>1MB、生成済み／最小化済み）はマークされ、fingerprint の計算には読み込まれません。builtAtHead に git sha を記録するため、全体を走査しなくても最新状態かどうかを確認できます。

ライセンス

MIT © PSX System。エージェントがリポジトリで必要とするコア機能は永久に無料です。蓄積するインテリジェンス（Genome クラウド、作成者による DNA）はプレミアム層です。