{
"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\nArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.\n\nSafer changes, fewer surprises, and extra protection only when you choose it.\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.11** is on npm `latest`.\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 the agent rewriting the few slow product decisions as CRUD;\n> later pattern change is `proposeRelease` then `apply`.\n> `@arkgate/runtime` is deprecated.\n> [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. 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 | When you ask |\n| **ArkRun** | Optional experimental runtime (`arkgate/runtime`) | Off unless you turn it on |\n| **ArkOrder** | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`). Valve: first `release()`, later ξ is `proposeRelease` then `apply` | 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 coding agents generate code at unprecedented speeds. However, they tend to take the shortest path to solve a problem. If an agent needs data in a Domain layer, it might directly import a database adapter. Left unchecked, this creates spaghetti code and technical debt at light speed.\n\nTraditional linters catch these architectural violations in CI *after* the agent has finished its work, breaking the flow.\n\nArkGate solves this by shifting the check to the exact moment of writing:\n\n1. **Fail fast at the write boundary.** Through IDE hooks and MCP, ArkGate intercepts the file write. If the agent writes a bad import, the write doesn't land. The agent gets immediate feedback and can self-correct before saving to disk.\n2. **The check is the single source of truth.** A simple `ark.config.json` defines your layers and allowed edges.\n3. **Honest reporting.** Green imports do not equal elegant design. ArkGate separates structural correctness from design smells, providing an improvement compass to guide leftover design work without blocking the PR.\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. In both cases the project hook must be installed + 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 agents rewriting slow product decisions as CRUD (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: same 13 skills via Agent Skills ecosystem (no new 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. They do not stop a *legal* import that overwrites the\nbilling plan.\n\nIf the product can name a few slow decisions in an afternoon — plan, cycle,\ntenancy; a clinical protocol; match rules — an agent will still ship one PUT\nthat changes them together with seats and invoices. The write gate stays green\nbecause “what may be the plan” was never a rule.\n\n**ArkOrder** (`arkgate/order`) is that rule. Off unless you add `arkOrder`.\nName the slow keys (`xiKeys`: plan, protocol, cost-code bound — not `projectId`).\nA status you can recompute from data you already have is not a slow decision. Derive it. Do not freeze it.\nPosting an invoice is absorbed. Changing plan is `proposeRelease` then `apply`.\n`refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`;\ncapacity pack as data; in-memory `ReleaseStore`; `ingestTravelAction`; ArkRun\n`decisionTape`. A generic `update` of the plan does not land. A use-case that\nPATCHes those keys through Prisma is named. Same npm package.\nIn-memory. Not durable. Does not replace ArkRun.\n**ArkOrder freezes the pattern through a valve. ArkRun is how the residual travels.**\n\nThe billing gallery (`plan` / `cycle` / `tenancy`) lives on GitHub, not in the\nnpm tarball:\n[examples/arkorder-billing](https://github.com/pedroknigge/arkgate/tree/main/examples/arkorder-billing).\nRename the three keys. Compact starters leave it off. Details:\n[ArkOrder](docs/arkorder.md) · [configuration](docs/configuration.md) ·\n[package surface](docs/package-surface.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| 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": 22780,
"sha": "6d54091a5c1ae2940e6f34176b7fdc68aad1f4e1983c98662cf8e3a5827a4f18",
"repo_slug": "pedroknigge/arkgate",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_pedroknigge_arkgate_b1d97e81/readme"
}