Arkgate

ArkGate — Write. Check. Ship.

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

ArkGate is import rules for AI-written TypeScript. Contener · Guiar · Ordenar: contain what the AI may write, and in what shape. Guide the next step. Order leftover mess toward a clean tree, a little at a time.

Why

AI takes the shortest path. One bad import lands, then another, and the product gets harder to change. A linter that runs only after the agent finishes sees the mess too late.

Design the boundary before you implement. Put a small interface in front of the work and keep the detail behind it. When leftover mess remains, the honest light is needs a refactor. Weakening the rules to paint the check green leaves that design unfinished.

Try it

One command. Preview only — no files change. Current release is 4.8.31 (check npm latest with npm view arkgate version):

npx arkgate@4.8.31 start

What a red result looks like

After a rules file exists, a domain file that imports infrastructure fails the check (exit 1). This is real output from arkgate-check on arkgate@4.8.20:

✖ 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).

Do that next action. Classify the import, or introduce a port when the dependency is a real use case. Then run the check again.

That red line is the check. It does not stop every write. On Cursor, a hook without failClosed: true is fail-open: if the checker cannot run, the write still lands. Shell writes, hosted tools, and human edits are outside the local hook. The hard line for every path is a required GitHub status running arkgate-check --strict-merge. Until that status is required, the rules file is just documentation.

Anyone: Use ArkGate · Developers: Develop · This library: CONTRIBUTING

---

Appendix

The minute above is the product. Below is reference: the longer introduction, what this is not, hosts, commands, extras, and where release history lives.

Choose your path

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

The longer introduction

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

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

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

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

That is Contener · Guiar · Ordenar.

What this is not

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

ArkGate is not a web framework, ORM, or job runner. The npm package is arkgate — not affiliated with the separate Archgate CLI project.

ArkRun is an optional experimental runtime. In-memory. Not Postgres. @arkgate/runtime is deprecated. ArkOrder does not replace import rules: layers can be green while the agent still rewrites the billing plan like a seat count.

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.

  ┌─────────┐     ┌─────────┐     ┌─────────┐

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

Adopted means a required GitHub status running arkgate-check --strict-merge, or an explicit advisory-only stance. Status is compact (arkgate-check --doctor; --all for details).

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.

---

Status lights (not settings)

  [ Setup ] ──▶ [ In progress ] ──▶ [ Ready ]

│ └── Ready · needs a refactor

Details: docs/use.md.

---

Start in one minute

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 pins arkgate with this repo's package manager (pnpm add -w / yarn add -W at a workspace root). Do not run npm install -D arkgate at a workspace:* root — npm rejects that protocol. After a local install, npx arkgate-check --doctor also works. arkgate-check is a command in the arkgate package, not its own npm package. If pnpm Age (minimumReleaseAge) blocks a brand-new release, keep using npx --package=arkgate@ — do not re-run the same add. Put arkgate on minimumReleaseAgeExclude in pnpm config or pnpm-workspace.yaml (a CLI flag is not enough), or wait until the package is mature.

start --apply refuses when projected governed coverage is below 50% or shape confidence is weak (below 0.6 with coverage under 80%), or when the planned write is too big for compact start (more than 8 gate files or 32 KB). That lock is deliberate. Coverage/shape: lock with --archetype , --preset , or --force. Size: --force does not unlock. Next: npx arkgate-check --init. Or inspect ranked shapes with npx arkgate-check --recommend.

That is the fuller path. 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 --local --base origin/dev (same as --changed; refused with --strict-merge). 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.

---

Host enforcement support

| OpenCode | Advisory / best-effort at write (MCP + optional plugin; not a hard boundary) | Advisory; the agent must call it | **Required GitHub