arkgate

<div align="center">

# ArkGate — Write. Check. Ship.

**When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**

Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
is just documentation.

AI can build fast—and make a mess just as fast.

Keep the product easy to understand, change, and trust.

ArkGate 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.

Safer changes, fewer surprises, and extra protection only when you choose it.

Works with Cursor, Claude, Codex, and Grok.

[![Website](https://img.shields.io/badge/website-arkgate.online-0a0a0a)](https://www.arkgate.online/)
[![CI](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/arkgate?color=cb3837&label=npm)](https://www.npmjs.com/package/arkgate)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js)
![TS 5–7](https://img.shields.io/badge/TypeScript-5%20%7C%206%20%7C%207-3178c6?logo=typescript)

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

</div>

> **ArkGate 4.8.11** is on npm `latest`.
> Write. Check. Ship. Adopted = required GitHub
> status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance.
> Status is compact (`arkgate-check --doctor`; `--all` for Details). Optional **ArkRun**
> (`arkgate/runtime`) is an in-memory runtime — not Postgres. Optional **ArkOrder**
> (`arkgate/order`) stops the agent rewriting the few slow product decisions as CRUD;
> later pattern change is `proposeRelease` then `apply`.
> `@arkgate/runtime` is deprecated.
> [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)

---

## Choose your path

| You are… | Go here |
|----------|---------|
| **Anyone** (ship with AI, minimal jargon) | **[Use ArkGate](docs/use.md)** |
| **Developer** (hosts, CI, config, brownfield) | **[Develop with ArkGate](docs/develop.md)** |
| **Contributor** (improve this library) | **[CONTRIBUTING](CONTRIBUTING.md)** |

Full map: **[docs/README.md](docs/README.md)**

---

## Start in one minute

```bash
npm install -D arkgate typescript
npx arkgate start                 # preview files + commands
npx arkgate start --apply         # compact config + host router + CI plan
npx arkgate-check --doctor        # status — one next step
npx arkgate-check --doctor --all  # full details
```

That is the product. Stuck? Run status (`--doctor`) and do action **#1**.

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

Keep the rules file out of product PRs. Local check:
`ark-check --changed --base origin/dev`. Changing the rules themselves uses `--contract-session`.

Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No install lifecycle scripts
— and none on pack or prepare either, so `pnpm add git+https://github.com/pedroknigge/arkgate`
installs at a pinned commit with no `allowBuilds` entry. A git install gives you the CLIs and the
schemas; the library, MCP and ESLint entry points live in the built `dist/` and come from npm.
See [docs/package-surface.md](docs/package-surface.md#installing-from-git).

![Write gate: agent blocked, then self-corrects](docs/assets/ark-write-gate.svg)

---

## What it is

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

When the agent writes a bad import, the write doesn’t land.
The same check fails the pull request. That is **ArkGate** — import rules, always on
once you adopt. The other three are optional.

| | Role | When |
|--|------|------|
| **While the agent writes** | The write doesn’t land on supported hosts; warning only elsewhere | Always (ArkGate) |
| **Before merge** | `arkgate-check` as a **required** CI status | Always (ArkGate) |
| **ArkRules** | Optional policies *inside* a layer | When you ask |
| **ArkRun** | Optional experimental runtime (`arkgate/runtime`) | Off unless you turn it on |
| **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 |

Layers (who may import whom) always run. ArkRules, ArkRun, and ArkOrder change no
inter-layer verdict when absent. Label leftovers **`[Layer]`** vs **`[ArkRules]`** vs
**`[ArkRun]`** vs **`[ArkOrder]`**.
Details: [configuration](docs/configuration.md) · [use](docs/use.md).

**Not** an API Gateway, a folder linter, a web framework, ORM, or job runner.
ArkRun is in-memory — local and tests, not Postgres. ArkOrder does not replace
import rules: layers can be green while the agent still PATCHes the billing plan
like a seat count.

**Name note:** npm package `arkgate` — not affiliated with the separate Archgate CLI project.

### When not to adopt

ArkGate is overkill for small trees with **no AI agents** and **no multi-layer boundaries**, for
single-developer hobby CRUDs under no integration pressure, and for teams that will not maintain
`ark.config.json` or a **required** CI status running `arkgate-check --strict-merge`. Without that
status the rules file is just documentation — stay with a boundary linter alone (see
[Why not only ESLint / Nx / cruiser?](#why-not-only-eslint--nx--cruiser)).
Anyone path: [docs/use.md — When not to adopt](docs/use.md#when-not-to-adopt). Limits of a green
check: [4.3.0 — What ArkGate is / isn't](docs/releases/4.3.0.md#what-arkgate-is--isnt).

---

## Why it exists

AI 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.

Traditional linters catch these architectural violations in CI *after* the agent has finished its work, breaking the flow.

ArkGate solves this by shifting the check to the exact moment of writing:

1. **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.
2. **The check is the single source of truth.** A simple `ark.config.json` defines your layers and allowed edges.
3. **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.

---

## Status lights (not settings)

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

| Light | Means | Your move |
|-------|--------|-----------|
| **Setup** | Thin / new tree | Finish `start` → status |
| **In progress** | Not fully protected | Status action #1 |
| **Ready** | Honest import edges, and no new UI business-rule files vs merge-base | Keep write path + CI |
| **Ready · needs a refactor** | Edges clean; leftover design work remains | One small change — not “done” |

Details: [docs/use.md](docs/use.md).

---

## Host enforcement support

<!-- arkgate-host-support:start -->
| Host | Local write boundary | MCP validation | CI / merge path | Repair payload |
|------|----------------------|----------------|-----------------|----------------|
| 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) |
| 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) |
| 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) |
| 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 |
| OpenAI Codex | **Hard** block for listed ops (PreT