{
"markdown": "\n\n# ArkGate — Write. Check. Ship.\n\n**When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**\n\nNot an API Gateway. Not a folder linter. If the check is not required on the PR, the config\nis just documentation.\n\nAI can build fast—and make a mess just as fast.\n\nKeep the product easy to understand, change, and trust.\n\nContain what the AI may write, and in what shape. Guide you with proven patterns and one next step. Order leftover mess toward a clean tree, a little at a time.\n\nSafer changes, fewer surprises, and extra protection only when you choose it.\n\nThat is **Contener · Guiar · Ordenar**.\n\nWorks with Cursor, Claude, Codex, and Grok.\n\n[](https://www.arkgate.online/)\n[](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/arkgate)\n[](LICENSE)\n\n\n\n```text\n ┌─────────┐ ┌─────────┐ ┌─────────┐\n │ WRITE │────▶│ CHECK │────▶│ SHIP │\n │ agent │ │ block │ │ merge │\n └─────────┘ └────┬────┘ └─────────┘\n │\n ▼\n bad import\n doesn't land\n```\n\n
\n\n> **ArkGate 4.8.14** is prepared on this tree; npm `latest` remains **4.8.13** until `publish-npm` for `v4.8.14`.\n> Write. Check. Ship. Adopted = required GitHub\n> status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance.\n> Status is compact (`arkgate-check --doctor`; `--all` for Details). Optional **ArkRun**\n> (`arkgate/runtime`) is an in-memory runtime — not Postgres. Optional **ArkOrder**\n> (`arkgate/order`) stops rewriting a big product choice — like the billing plan —\n> as if it were a seat count. Change those choices through a valve, not a generic update.\n> `@arkgate/runtime` is deprecated.\n> [4.8.14 prepared](CHANGELOG.md) · [4.8.11 published](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)\n\n---\n\n## Choose your path\n\n| You are… | Go here |\n|----------|---------|\n| **Anyone** (ship with AI, minimal jargon) | **[Use ArkGate](docs/use.md)** |\n| **Developer** (hosts, CI, config, brownfield) | **[Develop with ArkGate](docs/develop.md)** |\n| **Contributor** (improve this library) | **[CONTRIBUTING](CONTRIBUTING.md)** |\n\nFull map: **[docs/README.md](docs/README.md)**\n\n---\n\n## Start in one minute\n\n```bash\nnpm install -D arkgate typescript\nnpx arkgate start # preview files + commands\nnpx arkgate start --apply # compact config + host router + CI plan\nnpx arkgate-check --doctor # status — one next step\nnpx arkgate-check --doctor --all # full details\n```\n\nThat is the product. Stuck? Run status (`--doctor`) and do action **#1**.\n\n```text\nstart → doctor → new files in the right folder\n ↘ leftover mess: map, then one small refactor\n```\n\nKeep the rules file out of product PRs. Local check:\n`ark-check --changed --base origin/dev`. Changing the rules themselves uses `--contract-session`.\n\nAliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No install lifecycle scripts\n— and none on pack or prepare either, so `pnpm add git+https://github.com/pedroknigge/arkgate`\ninstalls at a pinned commit with no `allowBuilds` entry. A git install gives you the CLIs and the\nschemas; the library, MCP and ESLint entry points live in the built `dist/` and come from npm.\nSee [docs/package-surface.md](docs/package-surface.md#installing-from-git).\n\n\n\n---\n\n## What it is\n\n```text\n src/domain/order.ts\n │ import { db } from \"../infra/postgres\"\n ▼\n ┌──────────────────────────────────────────┐\n │ CHECK │\n │ Domain ─✕─▶ Infrastructure │\n │ write doesn't land · PR check fails │\n └──────────────────────────────────────────┘\n```\n\nWhen the agent writes a bad import, the write doesn’t land.\nThe same check fails the pull request. That is **ArkGate** — import rules, always on\nonce you adopt (**Contener**). The other three are optional.\n\n| | Role | When |\n|--|------|------|\n| **While the agent writes** | The write doesn’t land on supported hosts; warning only elsewhere | Always (ArkGate) |\n| **Before merge** | `arkgate-check` as a **required** CI status | Always (ArkGate) |\n| **ArkRules** | Optional policies *inside* a layer (**Contener** — shape) | When you ask |\n| **ArkRun** | Optional experimental runtime (`arkgate/runtime`) (**Guiar**) | Off unless you turn it on |\n| **ArkOrder** | Extra for the few big choices — billing plan, not seat counts (`arkgate/order`) (**Ordenar**) | Off unless you turn it on |\n\nLayers (who may import whom) always run. ArkRules, ArkRun, and ArkOrder change no\ninter-layer verdict when absent. Label leftovers **`[Layer]`** vs **`[ArkRules]`** vs\n**`[ArkRun]`** vs **`[ArkOrder]`**.\nDetails: [configuration](docs/configuration.md) · [use](docs/use.md).\n\n**Not** an API Gateway, a folder linter, a web framework, ORM, or job runner.\nArkRun is in-memory — local and tests, not Postgres. ArkOrder does not replace\nimport rules: layers can be green while the agent still PATCHes the billing plan\nlike a seat count.\n\n**Name note:** npm package `arkgate` — not affiliated with the separate Archgate CLI project.\n\n### When not to adopt\n\nArkGate is overkill for small trees with **no AI agents** and **no multi-layer boundaries**, for\nsingle-developer hobby CRUDs under no integration pressure, and for teams that will not maintain\n`ark.config.json` or a **required** CI status running `arkgate-check --strict-merge`. Without that\nstatus the rules file is just documentation — stay with a boundary linter alone (see\n[Why not only ESLint / Nx / cruiser?](#why-not-only-eslint--nx--cruiser)).\nAnyone path: [docs/use.md — When not to adopt](docs/use.md#when-not-to-adopt). Limits of a green\ncheck: [4.3.0 — What ArkGate is / isn't](docs/releases/4.3.0.md#what-arkgate-is--isnt).\n\n---\n\n## Why it exists\n\nAI takes the shortest path. Contain the write so a bad import never lands. Guide\nthe next step so a non-expert is not stuck. Order leftover mess toward a clean\ntree, one small refactor at a time.\n\nTraditional linters catch this only in CI after the agent finished. ArkGate\nchecks at write time and again on the PR. Green imports are not elegant design —\nleftover mess is **needs a refactor**, not “done”.\n\n---\n\n## Status lights (not settings)\n\n```text\n [ Setup ] ──▶ [ In progress ] ──▶ [ Ready ]\n │\n └── Ready · needs a refactor\n```\n\n| Light | Means | Your move |\n|-------|--------|-----------|\n| **Setup** | Thin / new tree | Finish `start` → status |\n| **In progress** | Not fully protected | Status action #1 |\n| **Ready** | Honest import edges, and no new UI business-rule files vs merge-base | Keep write path + CI |\n| **Ready · needs a refactor** | Edges clean; leftover design work remains | One small change — not “done” |\n\nDetails: [docs/use.md](docs/use.md).\n\n---\n\n## Host enforcement support\n\n\n| Host | Local write boundary | MCP validation | CI / merge path | Repair payload |\n|------|----------------------|----------------|-----------------|----------------|\n| Claude Code | **Hard** block for listed ops (PreToolUse `Write` / `Edit` / `MultiEdit`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |\n| Grok Build | **Hard** block for listed ops (PreToolUse `write` / `search_replace` (plus aliases)) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |\n| Google Antigravity | **Hard** block for listed ops (PreToolUse `write_to_file` / `replace_file_content` / `multi_replace_file_content`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Emitted on hook deny; host must re-inject (hard path when installed + trusted) |\n| Cursor | **Hard** block for listed ops (preToolUse `Write` / `StrReplace`) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed |\n| OpenAI Codex | **Hard** block for listed ops (PreToolUse `apply_patch` in Codex CLI and local ChatGPT Desktop/App Server) when installed + trusted | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | Envelope may emit (`--hook-repair`); reinjection **not** guaranteed |\n| OpenCode | **Advisory / best-effort** at write (MCP + optional plugin; not a hard boundary) | Advisory; the agent must call it | **Required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) | No hard-boundary payload |\n\n**Read the CI column:** for every host, the repository-wide hard guarantee is a **required**\nGitHub **status context** that runs the CLI — not “CI file present,” and not the CLI binary name alone.\nCodex hard write covers only a complete local `apply_patch`; Cursor covers only listed\n`preToolUse` ops with `failClosed: true`. A Cursor hook without that flag is fail-open\n(if the checker cannot run, the write still lands). In both cases the project hook must be\ninstalled + trusted, while shell/direct\nfilesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.\n\nThis table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.\n\n\n#### Why required CI is the hard line\n\nThe split above is a deliberate trade-off, not a gap. ArkGate validates at the earliest boundary\neach host offers and enforces at the earliest boundary a repository can make non-bypassable: the\nrequired merge status. Hard hooks (Claude Code, Grok Build, Google Antigravity, Cursor, and\nCodex’s complete local `apply_patch`) deny their listed write operations at write time; advisory\nsurfaces (MCP, rules, OpenCode plugins) warn the agent while it works. But any local boundary can\nbe routed around — another tool, a hosted/specialized path, a direct filesystem write, or a human\nedit — so the only guarantee ArkGate claims for every path is the\n`arkgate-check --strict-merge` check, and only when the repository makes that status required.\nLocal checks optimize feedback speed; required CI owns correctness.\n\nA useful consequence: the rules file doubles as a pressure sensor. Recurring violations or baseline\nexceptions concentrated on one layer edge are evidence that the current design stopped fitting the\ncode — a reason to reshape the rules deliberately (start with `/ark-explore`), never to weaken\nthe check.\n\nSetup per host: [docs/ai-gates.md](docs/ai-gates.md) · Develop path: [docs/develop.md](docs/develop.md)\n\nFor authoritative MCP contract evidence, call `ark_identity` with the exact project root, then\ncall `ark_manifest` with that root plus the returned project id. A contained descendant requires\nthe matching id. The legacy `ark://manifest` resource remains compatibility-only and always\nunverified/non-authoritative because standard `resources/read` cannot portably carry that\nexpectation.\n\n---\n\n## Why not only ESLint / Nx / cruiser?\n\n| | ArkGate | Typical boundary linter |\n|--|:---:|:---:|\n| CI import rules | ✅ | ✅ |\n| Hard-block AI writes on supported hosts | ✅ | ❌ |\n| Project-bound rules agents can read (`ark_manifest`) | ✅ | ❌ |\n| Placement + preflight for multi-file changes | ✅ | ❌ |\n| Honest governed % + dual plan (edges vs shape) | ✅ | ❌ |\n| Opt-in intra-layer ArkRules (structure + invariants) | ✅ | ❌ |\n| Stops rewriting a big product choice like billing plan (ArkOrder) | ✅ | ❌ |\n| Incomplete analysis cannot look green | ✅ | varies |\n\n---\n\n## Common commands\n\n```bash\nnpx arkgate start --apply\nnpx arkgate status --json # session/project snapshot (identity, activation, last check)\nnpx arkgate-check --doctor\nnpx arkgate-check --plan\nnpx arkgate-check --coverage\nnpx arkgate-check --path-drift --base-ref origin/main # stale paths in strings/comments after a rename\nnpx arkgate-check --sensors # which sensors can EVER be enforced, and which of your rules can be promoted\nnpx arkgate-check --promote # what enforcing each advisory rule would cost, from one run\nnpx arkgate-check --strict-merge # CI / required status\nnpx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigravity\n# optional: refresh shared home skills (Claude/Grok/Antigravity/Codex; never downgrades)\n# npx arkgate-check --install-agent-gates --skills-only --agent-homes --force\n# optional: closed skill catalog via Agent Skills ecosystem (ARK_SKILL_NAMES)\n# npx skills add ./node_modules/arkgate/templates/agent-skills\n# optional ArkRun: poll the loopback inspector (ANSI TUI — not a gate)\n# npx ark-dashboard --url http://127.0.0.1:/snapshot\n```\n\nMore: [docs/develop.md](docs/develop.md) · skills install: [docs/agent-guide.md](docs/agent-guide.md#install-skills-ark-and-ecosystem) · enthusiast track: [docs/enthusiast/](docs/enthusiast/README.md)\n\n---\n\n## Optional ArkRun\n\nGates need **no** app runtime. Skip this unless you want an optional runtime\nfor decoupling.\n\n**ArkRun** (`arkgate/runtime`, same npm package) is that runtime. Each\n`createStrictArkKernel()` call is a new instance — no process singleton. Data\nlives in memory and **dies on restart**. Fine for local. Not Postgres, not an\noutbox, not Temporal. `@arkgate/runtime` is deprecated.\n\n### Dev inspector and observability dashboard\n\nOpt-in `startInspector()` binds **loopback only** (`127.0.0.1`), refuses\n`NODE_ENV=production`, and serves JSON facts — not a TUI. Alongside\n`GET /snapshot`, `GET /events` (SSE), and `GET /graph`, the inspector exposes\nqueue monitors:\n\n| Path | Body (JSON) |\n|------|-------------|\n| `GET /outbox` | Pending/failed outbox **summaries** + counts (`available`, `pendingCount`, `failedCount`, `pending`, `failed`) — no event payloads |\n| `GET /workflows` | Workflow **summaries** + counts (`available`, `total`, `runningCount`, …, `workflows`) |\n\nPoll those facts from the dual bins **`ark-dashboard`** / **`arkgate-dashboard`**\n(`bin/ark-dashboard.mjs`). ANSI + polling only (no React/Ink/Blessed). Point\n`--url` / `-u` at the inspector snapshot (default\n`http://127.0.0.1:3000/snapshot`); the dashboard also fetches sibling `/outbox`\nand `/workflows`. `--interval` / `-i` is clamped to 200–60000 ms (default 2000).\nAlso available as `ark dashboard` / `arkgate dashboard` (passthrough to the same bin). Kernel stays\nJSON-only; presentation stays in `bin/`.\n\n### Durability stance\n\nDefault stores (`InMemoryEventBuffer`, `InMemoryAuditStore`, `InMemoryReadModelStore`,\n`InMemoryWorkflowStore`) are **reference in-memory only**. Fine for tests. They\n**do not** survive restarts and are **not** production durability. Wire real store\ninterfaces for production. Details: [docs/production-hardening.md](docs/production-hardening.md).\n\n---\n\n## Optional ArkOrder\n\nLayers stop a bad import. ArkOrder stops rewriting a big product choice — like\nthe billing plan — as if it were a seat count. Change those choices through a\nvalve, not a generic update.\n\nOff unless you add `arkOrder`. Same npm package (`arkgate/order`). In-memory.\nNot a service. Does not replace ArkGate or ArkRun.\n\nName the few choices (`xiKeys`: plan, cycle, tenancy — not seat counts). First\nfreeze is `release()`. Later change is `proposeRelease` then `apply`. A generic\n`update` does not land.\n\nProof path (GitHub, not the npm tarball):\n[examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing)\n— first freeze is `release()`; later plan change is `proposeRelease` then `apply`.\nGallery index:\n[examples/README.md](https://github.com/pedroknigge/arkgate/blob/main/examples/README.md).\nCompact starters leave the extra off. Details: [ArkOrder](docs/arkorder.md).\n\n---\n\n## Documentation\n\n| Audience | Link |\n|----------|------|\n| **Docs hub** | [docs/README.md](docs/README.md) |\n| Anyone | [docs/use.md](docs/use.md) |\n| Developers integrating ArkGate | [docs/develop.md](docs/develop.md) |\n| Contributors to this library | [CONTRIBUTING.md](CONTRIBUTING.md) |\n| Host install detail | [docs/ai-gates.md](docs/ai-gates.md) |\n| Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |\n| Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |\n| Security | [SECURITY.md](SECURITY.md) |\n| Prepared (4.8.14; not published) | [CHANGELOG](CHANGELOG.md) |\n| Current published (4.8.11 on npm `latest`) | [docs/releases/4.8.11.md](docs/releases/4.8.11.md) · [CHANGELOG](CHANGELOG.md) |\n| Prior published (4.8.10) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |\n| Prior published (4.8.9) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |\n| Prior published (4.8.7) | [docs/releases/4.8.7.md](docs/releases/4.8.7.md) · [CHANGELOG](CHANGELOG.md) |\n| Prior published (4.8.6) | [docs/releases/4.8.6.md](docs/releases/4.8.6.md) |\n| Prior published (4.8.5) | [docs/releases/4.8.5.md](docs/releases/4.8.5.md) |\n| Prior published (4.8.4) | [docs/releases/4.8.4.md](docs/releases/4.8.4.md) |\n| Prior published (4.8.3) | [docs/releases/4.8.3.md](docs/releases/4.8.3.md) |\n| Prior published (4.8.2) | [docs/releases/4.8.2.md](docs/releases/4.8.2.md) |\n| Prior published (4.8.1) | [docs/releases/4.8.1.md](docs/releases/4.8.1.md) |\n| Prior published (4.8.0) | [docs/releases/4.8.0.md](docs/releases/4.8.0.md) |\n| Prior published (4.7.6) | [docs/releases/4.7.6.md](docs/releases/4.7.6.md) |\n| Prior published (4.7.5) | [docs/releases/4.7.5.md](docs/releases/4.7.5.md) |\n| Prior published (4.7.3) | [docs/releases/4.7.3.md](docs/releases/4.7.3.md) |\n| Prior published (4.7.2) | [docs/releases/4.7.2.md](docs/releases/4.7.2.md) |\n| Prior published (4.7.1) | [docs/releases/4.7.1.md](docs/releases/4.7.1.md) |\n| Prior published (4.7.0) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) |\n| Prior published (4.6.7) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) |\n| Prior published (4.6.6) | [docs/releases/4.6.6.md](docs/releases/4.6.6.md) |\n| Prior published (4.6.5) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) |\n| Prior published (4.6.3) | [docs/releases/4.6.3.md](docs/releases/4.6.3.md) |\n| Prior (4.6.2) | [docs/releases/4.6.2.md](docs/releases/4.6.2.md) |\n| Prior (4.6.1) | [docs/releases/4.6.1.md](docs/releases/4.6.1.md) |\n| Prior (4.6.0) | [docs/releases/4.6.0.md](docs/releases/4.6.0.md) |\n| Prior (4.5.7) | [docs/releases/4.5.7.md](docs/releases/4.5.7.md) |\n| Prior (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |\n| Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |\n| Prior (4.3.0) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) |\n| Prior (4.2.1) | [docs/releases/4.2.1.md](docs/releases/4.2.1.md) |\n| Previous (4.2.0) | [docs/releases/4.2.0.md](docs/releases/4.2.0.md) |\n| Previous (4.1.1) | [docs/releases/4.1.1.md](docs/releases/4.1.1.md) |\n| Previous (4.1.0) | [docs/releases/4.1.0.md](docs/releases/4.1.0.md) |\n| Previous patch (4.0.1) | [docs/releases/4.0.1.md](docs/releases/4.0.1.md) |\n| Previous (4.0.0) | [docs/releases/4.0.0.md](docs/releases/4.0.0.md) |\n| Previous (3.9.2) | [docs/releases/3.9.2.md](docs/releases/3.9.2.md) |\n| History / maintainer evidence | [docs/archive/](docs/archive/README.md) |\n\n---\n\n## Contribute to this library\n\n```bash\ngit clone https://github.com/pedroknigge/arkgate\ncd arkgate && npm ci && npm run build\nnpm test && npm run check:architecture\n```\n\nFull guide: [CONTRIBUTING.md](CONTRIBUTING.md) · queue: [ROADMAP.md](ROADMAP.md)\n\n---\n\n**Website:** [arkgate.online](https://www.arkgate.online/) · **npm:** [`arkgate`](https://www.npmjs.com/package/arkgate) \n**MCP:** [`io.github.pedroknigge/arkgate`](https://registry.modelcontextprotocol.io/) \nNode ≥ 18 · **MIT**\n\n**Ark doesn’t invent your product. It rejects the illegal write — and tells you when it isn’t really enforcing anything yet.**\n",
"bytes": 21864,
"sha": "b92a4512e9249a78d68d9d9bb19aa738ec8a5b7fb8682e46ea45ceec575aff9d",
"repo_slug": "pedroknigge/ark-runtime-kernel",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_pedroknigge_ark_4b35412e/readme"
}