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

ArkGate 4.8.14 is prepared on this tree; npm latest remains 4.8.13 until publish-npm for v4.8.14. 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 rewriting a big product choice — like the billing plan — as if it were a seat count. Change those choices through a valve, not a generic update. @arkgate/runtime is deprecated. 4.8.14 prepared · 4.8.11 published · 4.8.10 · 4.8.9 · 4.8.8 · 4.8.7 · 4.8.6 · 4.8.5 · 4.8.4 · 4.8.3 · 4.8.2 · 4.8.1 · 4.8.0 · Docs hub · Voice

Choose your path

Full map: docs/README.md

Start in one minute

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.

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.

What it is

  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 (Contener). The other three are optional.

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 · use.

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?). Anyone path: docs/use.md — When not to adopt. Limits of a green check: 4.3.0 — What ArkGate is / isn't.

Why it exists

AI takes the shortest path. Contain the write so a bad import never lands. Guide the next step so a non-expert is not stuck. Order leftover mess toward a clean tree, one small refactor at a time.

Traditional linters catch this only in CI after the agent finished. ArkGate checks at write time and again on the PR. Green imports are not elegant design — leftover mess is needs a refactor, not “done”.

Status lights (not settings)

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

Details: docs/use.md.

Host enforcement support

Read the CI column: for every host, the repository-wide hard guarantee is a required GitHub status context that runs the CLI — not “CI file present,” and not the CLI binary name alone. Codex hard write covers only a complete local apply_patch; Cursor covers only listed preToolUse ops with failClosed: true. A Cursor hook without that flag is fail-open (if the checker cannot run, the write still lands). In both cases the project hook must be installed + trusted, while shell/direct filesystem writes, hosted or specialized opt-out paths, and human edits still rely on CI.

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

Why required CI is the hard line

The split above is a deliberate trade-off, not a gap. ArkGate validates at the earliest boundary each host offers and enforces at the earliest boundary a repository can make non-bypassable: the required merge status. Hard hooks (Claude Code, Grok Build, Google Antigravity, Cursor, and Codex’s complete local apply_patch) deny their listed write operations at write time; advisory surfaces (MCP, rules, OpenCode plugins) warn the agent while it works. But any local boundary can be routed around — another tool, a hosted/specialized path, a direct filesystem write, or a human edit — so the only guarantee ArkGate claims for every path is the arkgate-check --strict-merge check, and only when the repository makes that status required. Local checks optimize feedback speed; required CI owns correctness.

A useful consequence: the rules file doubles as a pressure sensor. Recurring violations or baseline exceptions concentrated on one layer edge are evidence that the current design stopped fitting the code — a reason to reshape the rules deliberately (start with /ark-explore), never to weaken the check.

Setup per host: docs/ai-gates.md · Develop path: docs/develop.md

For authoritative MCP contract evidence, call ark_identity with the exact project root, then call ark_manifest with that root plus the returned project id. A contained descendant requires the matching id. The legacy ark://manifest resource remains compatibility-only and always unverified/non-authoritative because standard resources/read cannot portably carry that expectation.

Why not only ESLint / Nx / cruiser?

Common commands

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

More: docs/develop.md · skills install: docs/agent-guide.md · enthusiast track: docs/enthusiast/

Optional ArkRun

Gates need no app runtime. Skip this unless you want an optional runtime for decoupling.

ArkRun (arkgate/runtime, same npm package) is that runtime. Each createStrictArkKernel() call is a new instance — no process singleton. Data lives in memory and dies on restart. Fine for local. Not Postgres, not an outbox, not Temporal. @arkgate/runtime is deprecated.

Dev inspector and observability dashboard

Opt-in startInspector() binds loopback only (127.0.0.1), refuses NODE_ENV=production, and serves JSON facts — not a TUI. Alongside GET /snapshot, GET /events (SSE), and GET /graph, the inspector exposes queue monitors:

Poll those facts from the dual bins ark-dashboard / arkgate-dashboard (bin/ark-dashboard.mjs). ANSI + polling only (no React/Ink/Blessed). Point --url / -u at the inspector snapshot (default http://127.0.0.1:3000/snapshot); the dashboard also fetches sibling /outbox and /workflows. --interval / -i is clamped to 200–60000 ms (default 2000). Also available as ark dashboard / arkgate dashboard (passthrough to the same bin). Kernel stays JSON-only; presentation stays in bin/.

Durability stance

Default stores (InMemoryEventBuffer, InMemoryAuditStore, InMemoryReadModelStore, InMemoryWorkflowStore) are reference in-memory only. Fine for tests. They do not survive restarts and are not production durability. Wire real store interfaces for production. Details: docs/production-hardening.md.

Optional ArkOrder

Layers stop a bad import. ArkOrder stops rewriting a big product choice — like the billing plan — as if it were a seat count. Change those choices through a valve, not a generic update.

Off unless you add arkOrder. Same npm package (arkgate/order). In-memory. Not a service. Does not replace ArkGate or ArkRun.

Name the few choices (xiKeys: plan, cycle, tenancy — not seat counts). First freeze is release(). Later change is proposeRelease then apply. A generic update does not land.

Proof path (GitHub, not the npm tarball): examples/arkorder-billing — first freeze is release(); later plan change is proposeRelease then apply. Gallery index: examples/README.md. Compact starters leave the extra off. Details: ArkOrder.

Documentation

Contribute to this library

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

Full guide: CONTRIBUTING.md · queue: ROADMAP.md

Website: arkgate.online · npm: arkgate
MCP: io.github.pedroknigge/arkgate
Node ≥ 18 · MIT

Ark doesn’t invent your product. It rejects the illegal write — and tells you when it isn’t really enforcing anything yet.