ark

ArkGate は、AI が書く TypeScript のインポートルールです。Contener · Guiar · Ordenar：AI が書ける内容とその形式を制限します。次のステップを導きます。残った混乱を少しずつ整理し、きれいなツリーへと導きます。

理由

AI は最短の道を選びます。誤ったインポートが入り込み、さらに別の誤りが重なると、プロダクトの変更が難しくなります。エージェントの作業後にしか実行されないリンターでは、問題を見つけるのが遅すぎます。

実装する前に境界を設計しましょう。作業の前に小さなインターフェースを置き、詳細はその背後に隠します。残った混乱がある場合、正直に示すのは リファクタリングが必要 という状態です。チェックを緑にするためにルールを弱めても、設計は未完成のままです。

試してみる

コマンドは 1 つです。プレビューのみで、ファイルは変更されません。現在のリリースは 4.8.29 （npm の latest は npm view arkgate version で確認できます）：

npx [email protected] start

赤い結果の例

ルールファイルが存在する状態で、インフラストラクチャをインポートするドメインファイルをチェックすると失敗します（終了コード 1）。これは [email protected] の arkgate-check による実際の出力です。

✖ LAYER_IMPORT_VIOLATION  src/domain/order.ts:1
  DomainModel → Infrastructure  (src/infra/db.ts)
  DomainModel must not import Infrastructure.
  Next action: Classify the import: if it is constants/types/pure, adopt into DomainModel or SharedKernel; define a port only if the target is a real use-case. Then preflight again.

✖ 1 violation(s).

次のアクションを実行しましょう。インポートを分類するか、その依存関係が実際のユースケースに当たる場合はポートを導入します。その後、もう一度チェックを実行します。

この赤い行がチェックです。すべての書き込みを止めるわけではありません。Cursor では、failClosed: true のないフックはフェイルオープンです。チェッカーを実行できなくても、書き込みは反映されます。シェルからの書き込み、ホストされたツール、人間による編集はローカルフックの対象外です。あらゆる経路に適用される厳格な条件は、arkgate-check --strict-merge を実行する 必須 の GitHub ステータスです。そのステータスが必須になるまでは、ルールファイルは単なるドキュメントにすぎません。

すべての方へ：ArkGate を使う · 開発者向け：開発する · このライブラリについて：CONTRIBUTING

---

付録

上記の内容がプロダクトの全体像です。以下はリファレンスです。詳しい紹介、このツールの対象外、ホスト、コマンド、追加機能、リリース履歴の場所を説明します。

自分に合った項目を選ぶ

あなたは…	こちらへ
すべての方（AI を使って出荷する方、専門用語は最小限）	ArkGate を使う
開発者（ホスト、CI、設定、既存コードへの適用）	ArkGate を使った開発
コントリビューター（このライブラリを改善する方）	CONTRIBUTING

ドキュメント全体の案内：docs/README.md

詳しい紹介

AI は高速に構築できます。同じ速さで混乱も生み出します。

プロダクトを理解しやすく、変更しやすく、信頼できる状態に保ちましょう。

AI が書ける内容とその形式を制限します。実績あるパターンと次の一歩で、作業を導きます。残った混乱を少しずつ整理し、きれいなツリーへと導きます。

より安全な変更、予期せぬ事態の減少、そして選択した場合に限った追加の保護を実現します。

それが Contener · Guiar · Ordenar です。

このツールの対象外

API ゲートウェイではありません。フォルダー用リンターでもありません。プルリクエストでチェックが必須になっていなければ、設定は単なるドキュメントにすぎません。

ArkGate は Web フレームワーク、ORM、ジョブランナーではありません。npm パッケージ名は arkgate です。別の Archgate CLI プロジェクトとは無関係です。

ArkRun は任意で使用できる実験的なランタイムです。インメモリであり、Postgres ではありません。@arkgate/runtime は非推奨です。ArkOrder はインポートルールの代わりにはなりません。レイヤーが緑でも、エージェントが請求プランを座席数のように書き換えることはあります。

概要

  src/domain/order.ts
       │  import { db } from "../infra/postgres"
       ▼
  ┌──────────────────────────────────────────┐
  │  CHECK                                   │
  │  Domain ─✕─▶ Infrastructure              │
  │  write doesn't land · PR check fails     │
  └──────────────────────────────────────────┘

エージェントが誤ったインポートを書き込もうとしても、その書き込みは反映されません。 同じチェックでプルリクエストも失敗します。これが ArkGate です。導入後はインポートルールが常に有効になります（Contener）。残りの3つは任意です。

	役割	タイミング
エージェントの書き込み中	対応ホストでは書き込みを反映せず、それ以外では警告のみ	常時（ArkGate）
マージ前	arkgate-check を 必須 の CI ステータスとして実行	常時（ArkGate）
ArkRules	レイヤー内の任意ポリシー（Contener — 形状）	必要に応じて
ArkRun	任意の実験的ランタイム（arkgate/runtime）（Guiar）	有効にしない限りオフ
ArkOrder	大きな選択肢の一部に対する追加機能 — シート数ではなく請求プラン（arkgate/order）（Ordenar）	有効にしない限りオフ

レイヤー間（どのレイヤーがどのレイヤーをインポートできるか）のチェックは常に実行されます。ArkRules、ArkRun、ArkOrder がなくても、レイヤー間の判定は変わりません。残件は [Layer]、[ArkRules]、[ArkRun]、[ArkOrder] とラベル付けします。 詳細：設定 · 使い方。

  ┌─────────┐     ┌─────────┐     ┌─────────┐
  │  WRITE  │────▶│  CHECK  │────▶│  SHIP   │
  │  agent  │     │  block  │     │  merge  │
  └─────────┘     └────┬────┘     └─────────┘
                       │
                       ▼
                 bad import
                 doesn't land

導入済みとは、arkgate-check --strict-merge を実行する必須の GitHub ステータスを設定しているか、明示的に advisory-only の方針を採用していることを意味します。ステータスは簡潔です（arkgate-check --doctor。詳細は --all）。

導入しないほうがよい場合

ArkGate は、AI エージェントがなく、複数レイヤーの境界もない小規模なツリー、統合のプレッシャーがない個人開発の CRUD プロジェクト、または ark.config.json や arkgate-check --strict-merge を実行する 必須 CI ステータスを維持しないチームには過剰です。 このステータスがなければ、ルールファイルは単なるドキュメントにすぎません。境界リンターのみを使ってください（ESLint / Nx / cruiser だけではだめなのか？を参照）。 対象者：docs/use.md — 導入しないほうがよい場合。チェックが成功しても保証されないこと：4.3.0 — ArkGate がすること／しないこと。

---

ステータスランプ（設定ではありません）

  [ Setup ] ──▶ [ In progress ] ──▶ [ Ready ]
                                      │
                                      └── Ready · needs a refactor

ランプ	意味	次の対応
Setup	まだ小規模／新しいツリー	start を完了 → ステータスを確認
In progress	保護が不完全	ステータスアクション #1
Ready	インポート境界が適切で、マージベースと比べて新しい UI ビジネスルールファイルがない	書き込み経路と CI を維持
Ready · needs a refactor	境界はクリーンだが、設計上の作業が残っている	小さな変更を1つ — 「完了」ではありません

詳細：docs/use.md。

---

1 分で始める

npx arkgate start                 # preview files + commands
npx arkgate start --apply         # compact config + host router + CI plan
npx --package=arkgate arkgate-check --doctor        # status — one next step
npx --package=arkgate arkgate-check --doctor --all  # full details

start --apply は、このリポジトリのパッケージマネージャーを使って arkgate を固定します（ワークスペースのルートで pnpm add -w / yarn add -W を実行します）。workspace:* のルートで npm install -D arkgate を実行しないでください。npm はそのプロトコルを拒否します。ローカルにインストールした後は、npx arkgate-check --doctor も使えます。arkgate-check は arkgate パッケージ内のコマンドであり、独立した npm パッケージではありません。pnpm の Age（minimumReleaseAge）によって新しいリリースがブロックされる場合は、引き続き npx --package=arkgate@<version> を使用してください。同じ add を再実行しないでください。pnpm の設定または pnpm-workspace.yaml で arkgate を minimumReleaseAgeExclude に追加するか（CLI フラグだけでは不十分です）、パッケージが十分に成熟するまで待ってください。

start --apply は、適用対象のカバレッジが 50% 未満の場合、または形状の信頼度が低い場合（カバレッジが 80% 未満で信頼度が 0.6 未満）、あるいは計画された書き込みが compact start に対して大きすぎる場合（ゲートファイルが 8 個超、または 32 KB 超）に実行を拒否します。 このロックは意図的なものです。カバレッジ／形状の場合は、--archetype <id>、--preset <name>、または --force でロックを解除できます。サイズの場合、--force では解除できません。次は npx arkgate-check --init を実行してください。または、npx arkgate-check --recommend でランク付けされた形状を確認してください。

これがより詳しい手順です。行き詰まった場合は、status（--doctor）を実行して、アクション #1 を行ってください。

start → doctor → new files in the right folder
              ↘ leftover mess: map, then one small refactor

ルールファイルをプロダクトの PR に含めないでください。ローカルチェック： ark-check --local --base origin/dev（--changed と同じです。--strict-merge では拒否されます）。ルール自体を変更する場合は --contract-session を使用します。

エイリアス ark / ark-check / ark-mcp も引き続き使えます。npm / pnpm / yarn に対応しています。インストール時のライフサイクルスクリプトはありません — pack または prepare にもスクリプトはないため、pnpm add git+https://github.com/pedroknigge/arkgate は allowBuilds エントリーなしで、固定されたコミットにインストールされます。Git からインストールすると CLI とスキーマを利用できます。ライブラリ、MCP、ESLint のエントリーポイントはビルド済みの dist/ にあり、npm から提供されます。 docs/package-surface.md を参照してください。

---

ホストの強制適用への対応

ホスト	ローカル書き込み境界	MCP 検証	CI／マージ経路	修復ペイロード
Claude Code	インストール済みかつ信頼済みの場合、記載された操作（PreToolUse Write／Edit／MultiEdit）をハードブロック	アドバイザリー。エージェントが呼び出す必要があります	arkgate-check --strict-merge（別名 ark-check）を実行する必須の GitHub ステータスコンテキスト	フックによる拒否時に出力。ホストが再注入する必要があります（インストール済みかつ信頼済みの場合はハードパス）
Grok Build	インストール済みかつ信頼済みの場合、記載された操作（PreToolUse write／search_replace（およびエイリアス））をハードブロック	アドバイザリー。エージェントが呼び出す必要があります	arkgate-check --strict-merge（別名 ark-check）を実行する必須の GitHub ステータスコンテキスト	フックによる拒否時に出力。ホストが再注入する必要があります（インストール済みかつ信頼済みの場合はハードパス）
Google Antigravity	インストール済みかつ信頼済みの場合、記載された操作（PreToolUse write_to_file／replace_file_content／multi_replace_file_content）をハードブロック	アドバイザリー。エージェントが呼び出す必要があります	arkgate-check --strict-merge（別名 ark-check）を実行する必須の GitHub ステータスコンテキスト	フックによる拒否時に出力。ホストが再注入する必要があります（インストール済みかつ信頼済みの場合はハードパス）
Cursor	インストール済みかつ信頼済みの場合、記載された操作（preToolUse Write／StrReplace）をハードブロック	アドバイザリー。エージェントが呼び出す必要があります	arkgate-check --strict-merge（別名 ark-check）を実行する必須の GitHub ステータスコンテキスト	エンベロープを出力する場合があります（--hook-repair）。再注入は保証されません
OpenAI Codex	インストール済みかつ信頼済みの場合、記載された操作（Codex CLI およびローカルの ChatGPT Desktop／App Server における PreToolUse apply_patch）をハードブロック	アドバイザリー。エージェントが呼び出す必要があります	arkgate-check --strict-merge（別名 ark-check）を実行する必須の GitHub ステータスコンテキスト	エンベロープを出力する場合があります（--hook-repair）。再注入は保証されません
OpenCode	書き込み時はアドバイザリー／ベストエフォート（MCP＋オプションのプラグイン。ハード境界ではありません）	アドバイザリー。エージェントが呼び出す必要があります	arkgate-check --strict-merge（別名 ark-check）を実行する必須の GitHub ステータスコンテキスト	ハード境界のペイロードはありません

CI 列について：すべてのホストにおけるリポジトリ全体のハード保証は、CLI を実行する必須の GitHub ステータスコンテキストです。「CI ファイルが存在する」ことでも、CLI バイナリ名だけでもありません。 Codex のハード書き込み境界が対象とするのは、完全なローカル apply_patch のみです。Cursor が対象とするのは、failClosed: true の設定がある場合に限り、記載された preToolUse 操作のみです。このフラグのない Cursor フックはフェイルオープンです（チェッカーを実行できなくても書き込みは反映されます）。どちらの場合も、プロジェクトのフックがインストール済みかつ信頼済みである必要があります。一方、シェルやファイルシステムへの直接書き込み、ホスト型または専用のオプトアウト経路、人による編集は、引き続き CI に依存します。

この表は、ファイルがインストールされ、ホストがそれらを読み込んで信頼した後に対応するプロファイルを示しています。ローカルのハード境界が対象とするのは、記載されたフック操作のみです。代替ツール、ファイルシステムへの直接書き込み、人による編集は、引き続き CI に依存します。書き込みゲートの順序：まずホストのプリフックをインストールして信頼してください。その経路がない場合、またはフェイルオープンの場合は、MCP の準備処理がフォールバックになります。MCP 検証は、エージェントが呼び出す必要があるためアドバイザリーです。CI チェックがマージをブロックするのは、リポジトリでそのステータスが必須に設定されている場合のみです。修復エンベロープが出力されても、再注入が保証されるわけではありません。サイレントな自動適用は行われません。現在のリポジトリで実際に検出された証拠を確認するには、arkgate-check --doctor（または ark-check --doctor）を実行してください。

必須 CI が譲れない一線である理由

上記の分割は意図的なトレードオフであり、欠落ではありません。ArkGate は、各ホストが提供する最も早い境界で検証し、リポジトリが迂回不能にできる最も早い境界、つまり必須のマージステータスで適用します。ハードフック（Claude Code、Grok Build、Google Antigravity、Cursor、および Codex の完全なローカル apply_patch）は、列挙された書き込み操作を実行時に拒否します。アドバイザリーな仕組み（MCP、ルール、OpenCode プラグイン）は、作業中のエージェントに警告します。しかし、ローカルの境界はいずれも、別のツール、ホスト型／専用の経路、ファイルシステムへの直接書き込み、人による編集などによって回避できます。そのため、ArkGate がすべての経路について保証するのは arkgate-check --strict-merge チェックのみであり、リポジトリでそのステータスを必須にした場合に限られます。ローカルチェックはフィードバックを速め、正しさは必須 CI が担保します。

有用な効果のひとつとして、ルールファイルは圧力センサーも兼ねます。特定のレイヤー境界に繰り返し違反が発生したり、ベースラインの例外が集中したりする場合、現在の設計がコードに合わなくなっている証拠です。これはルールを意図的に再構成する理由になります（まず /ark-explore を使ってください）。チェックを弱める理由にはなりません。

ホストごとのセットアップ：docs/ai-gates.md · 開発パス：docs/develop.md

信頼できる MCP 契約の根拠を得るには、正確なプロジェクトルートを指定して ark_identity を呼び出し、次にそのルートと返されたプロジェクト ID を指定して ark_manifest を呼び出してください。配下に含まれる子孫には、一致する ID が必要です。従来の ark://manifest リソースは互換性のためだけに残されており、標準の resources/read ではその期待値を移植可能な形で渡せないため、常に未検証／非権威的です。

---

ESLint / Nx / cruiser だけではだめな理由

	ArkGate	一般的な境界リンター
CI のインポートルール	✅	✅
対応ホストでの AI による書き込みをハードブロック	✅	❌
エージェントが参照できるプロジェクト固有のルール（ark_manifest）	✅	❌
複数ファイル変更の配置先判定＋事前チェック	✅	❌
正確な管理対象割合＋二重プラン（エッジと構造）	✅	❌
オプトイン型のレイヤー内 ArkRules（構造＋不変条件）	✅	❌
課金プランのような大きな製品上の選択を再検討させない（ArkOrder）	✅	❌
不完全な分析が成功扱いにならない	✅	まちまち

---

よく使うコマンド

npx arkgate start --apply
npx arkgate status --json          # session/project snapshot (identity, activation, last check)
npx arkgate-check --doctor
npx arkgate-check --plan
npx arkgate-check --coverage
npx arkgate-check --path-drift --base-ref origin/main   # stale paths in strings/comments after a rename
npx arkgate-check --sensors        # which sensors can EVER be enforced, and which of your rules can be promoted
npx arkgate-check --promote        # what enforcing each advisory rule would cost, from one run
npx arkgate-check --strict-merge   # CI / required status
npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigravity
# optional: refresh shared home skills (Claude/Grok/Antigravity/Codex; never downgrades)
# npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
# optional: closed skill catalog via Agent Skills ecosystem (ARK_SKILL_NAMES)
# npx skills add ./node_modules/arkgate/templates/agent-skills
# optional ArkRun: poll the loopback inspector (ANSI TUI — not a gate)
# npx ark-dashboard --url http://127.0.0.1:<port>/snapshot

詳細：docs/develop.md · スキルのインストール：docs/agent-guide.md · エンスージアスト向けガイド：docs/enthusiast/

必要な場合に限って使うその他のスキル

日々の作業では、コンパクトなルーターとステータスを使います。/ark-* の全スキルパックはエキスパート向けの内容です。最初に実行するものではなく、次のステップをガイドしてもらいたいときにインストールしてください。カタログとインストール方法：スキルのインストール — Ark とエコシステム。

---

オプションの ArkRun

ゲートにアプリのランタイムは不要です。分離のためにオプションのランタイムを使いたい場合を除き、ここは読み飛ばしてください。

ArkRun（arkgate/runtime、同じ npm パッケージ）がそのランタイムです。createStrictArkKernel() を呼び出すたびに新しいインスタンスが作成され、プロセス内のシングルトンはありません。データはメモリ上に保存され、再起動すると失われます。ローカル用途には問題ありません。Postgres でも、アウトボックスでも、Temporal でもありません。@arkgate/runtime は非推奨です。

開発者向けインスペクターと可観測性ダッシュボード

オプトインの startInspector() はループバックのみ（127.0.0.1）にバインドし、NODE_ENV=production の場合は起動を拒否して、TUI ではなく JSON の情報を提供します。GET /snapshot、GET /events（SSE）、GET /graph に加え、インスペクターはキューのモニターも公開します。

パス	本文（JSON）
GET /outbox	保留中／失敗したアウトボックスの概要と件数（available、pendingCount、failedCount、pending、failed） — イベントのペイロードは含まれません
GET /workflows	ワークフローの概要と件数（available、total、runningCount、…、workflows）

デュアルビンの ark-dashboard ／ arkgate-dashboard （bin/ark-dashboard.mjs）からこれらの情報をポーリングしてください。ANSI とポーリングのみです（React／Ink／Blessed は使用しません）。--url ／ -u にインスペクター（handle.url または handle.snapshotUrl）を指定してください。ダッシュボードは同階層の /outbox と /workflows も取得します。startInspector() は { port } を渡さない限りランダムなポートにバインドするため、フォールバックの http://127.0.0.1:3000/snapshot（または ARK_DASHBOARD_URL）が一致するのは startInspector({ port: 3000 }) の場合のみです。--interval ／ -i は 200～60000 ms の範囲に制限されます（デフォルトは 2000）。--once、--help、--version をサポートしています。ark dashboard ／ arkgate dashboard からも利用できます（同じビンに処理を渡します）。カーネルは JSON のみを維持し、表示処理は bin/ に置かれています。

耐久性に関する方針

デフォルトのストア（InMemoryEventBuffer、InMemoryAuditStore、InMemoryReadModelStore、 InMemoryWorkflowStore）は参照用のインメモリのみです。テストには適していますが、再起動後も保持されず、本番環境での耐久性はありません。本番環境では実際のストアインターフェースを接続してください。詳細：docs/production-hardening.md。

---

オプションの ArkOrder

レイヤーは不正なインポートを防ぎます。ArkOrder は、請求プランのような大きな製品上の選択を、座席数のように書き換えてしまうことを防ぎます。こうした選択は汎用的な更新ではなく、バルブを通じて変更します。

arkOrder を追加しない限り無効です。同じ npm パッケージ（arkgate/order）です。インメモリです。サービスではありません。ArkGate や ArkRun の代わりにはなりません。

いくつかの選択項目（プラン、サイクル、テナンシーなど。座席数は含めません）を xiKeys で指定します。最初の確定には release() を使います。その後の変更は proposeRelease の後に apply を実行します。汎用の update では反映されません。

動作を示す例（npm の tarball ではなく GitHub）： examples/arkorder-billing — 最初の確定には release() を使い、その後のプラン変更には proposeRelease の後に apply を実行します。 サンプル一覧： examples/README.md。 簡易スターターでは追加機能を無効にしています。詳細：ArkOrder。

---

ドキュメント

対象	リンク
ドキュメントハブ	docs/README.md
すべてのユーザー	docs/use.md
ArkGate を統合する開発者	docs/develop.md
このライブラリへのコントリビューター	CONTRIBUTING.md
ホストのインストール詳細	docs/ai-gates.md
設定 · パッケージの公開 API · TS	configuration · package-surface · typescript-support
ブラウンフィールド	docs/brownfield-adoption.md
セキュリティ	SECURITY.md
リリース履歴	CHANGELOG.md · サイトの変更履歴 · ドキュメントハブの目次
履歴／メンテナー向け資料	docs/archive/

バージョン情報は CHANGELOG.md とサイトの変更履歴にあります。ドキュメントハブにはバージョンごとの目次があります：履歴とメンテナー向け資料。

---

このライブラリへのコントリビュート

git clone https://github.com/pedroknigge/arkgate
cd arkgate && npm ci && npm run build
npm test && npm run check:architecture

完全なガイド：CONTRIBUTING.md · キュー：ROADMAP.md

---

ウェブサイト： arkgate.online · npm： arkgate
MCP： io.github.pedroknigge/arkgate
Node ≥ 18 · MIT

Ark は製品を作り上げるものではありません。不正な書き込みを拒否し、まだ実際には何も強制できていない場合は、そのことを知らせます。