# ArkGate: full context for language models

## Canonical description

ArkGate is the open-source architecture firewall for AI-written TypeScript. It turns structural decisions into one machine-readable repository contract and evaluates proposed changes deterministically instead of depending on an agent to remember prose instructions.

The core product governs repository structure while AI agents work and before code merges. It is designed for gradual adoption in existing codebases and does not require a rewrite. Doctor is the control plane: one status light and one primary next action.

## The problem ArkGate solves

AI agents can generate code faster than humans can review every architectural decision. The result may compile and pass tests while introducing invalid dependencies, misplaced files, cross-feature coupling, cycles, or shortcuts around established boundaries.

ArkGate makes those boundaries explicit, gives agents actionable placement and repair information, and gives CI a deterministic final decision.

## Repository contract

ArkGate has **two planes** the user can enable:

1. **Layers (inter-layer)** — dependency direction, capabilities, pure/forbidden globals, peerIsolation.
2. **ArkRules (intra-layer, opt-in)** — structure sensors and domain invariant catalogs in `arkrules/<Layer>.json`, referenced from the top-level `arkRules` map. Absence of `arkRules` changes no inter-layer verdict.

The central artifact is `ark.config.json`. Depending on the project, it can describe:

- file include and exclude scope;
- architectural layers and path patterns;
- allowed and forbidden dependency directions;
- optional `peerIsolation` between feature slices or bounded contexts;
- forbidden globals inside specific layers;
- cycle and dynamic-import policies;
- safety thresholds and bypass diagnostics;
- contract coverage and adoption state.

Typical **layer** rules include:

- Domain cannot import a database adapter.
- UI may depend on Application but not Infrastructure.
- Billing cannot import Shipping internals directly.
- Provider SDKs and webhooks belong in Infrastructure.
- `fetch`, `Date.now()`, or ambient globals are forbidden in pure Domain code.

Typical **ArkRules** (opt-in) include:

- Aggregates keep private state (`aggregate-private-state`).
- Always-valid construction via factories (`always-valid-factory`).
- Mutations guard or publish (`domain-event-on-mutation`).
- Named invariants with test-title or symbol coverage (`INVARIANT_UNCOVERED` when missing).

## Enforcement surfaces

| Surface | Behavior |
| --- | --- |
| Claude Code PreToolUse | Installed hooks can hard-block covered `Write`, `Edit`, and `MultiEdit` operations when trusted. |
| Grok Build PreToolUse | Installed hooks can hard-block covered write and search-replace operations when trusted. |
| Google Antigravity PreToolUse | Installed hooks can hard-block listed write / replace / multi-replace ops when trusted. |
| Cursor | Repository rules and MCP are advisory; the agent must call the tool. |
| OpenAI Codex | Repository guidance and MCP are advisory; not equivalent to Claude/Grok hard block. |
| OpenCode | MCP + optional plugin; advisory / best-effort, not a hard boundary. |
| MCP | `ark_prepare_write` can place, constrain, validate, patch mechanical-safe cases, and return evidence or a repair brief. |
| CI | A required `arkgate-check --strict-merge` status is the final host-independent hard boundary. |

Hard enforcement depends on the host, installed integration, and covered write path. ArkGate does not claim that every editor action is intercepted. The universal guarantee is the required strict merge check in CI. Cursor / Codex / OpenCode never receive a fake hard write claim.

## Atomic proposed changes

ArkGate can evaluate related creates, edits, and deletes as one transaction. This matters because a new service may only be valid after its port and adapter are added, while a set of individually plausible edits may create a forbidden dependency or cycle when combined.

The result can include placement, violations, evidence, mechanical-safe patches, and actionable remediation for the agent.

## Adoption workflow (doctor-first)

1. Install ArkGate and TypeScript as development dependencies.
2. Run `npx arkgate start` to preview; `npx arkgate start --apply` for compact contract + host router + CI plan.
3. Run `npx arkgate-check --doctor` — control plane: status light + primary next action.
4. Day-to-day: place + gate. Optional skill pack and `/ark-autopilot` only after skills install when guided shape work is wanted—not default step 2.

Doctor reports evidence-based readiness states:

- **Suggest:** the real repository shape is not sufficiently mapped or covered.
- **Adapt:** the contract is active, but meaningful areas or write paths remain uncovered.
- **Enforce:** declared boundaries are covered and active.
- **Enforce · design-weak:** boundaries pass, but internal structure still requires design work.
- Doctor may also report **`rulesUnderContract`** (ArkRules counts, never a score) and **`productHonesty`** (unfinished when design-weak / weak coverage / residual debt / related honesty sensors—not a vanity architecture score).

These are readiness states, not modes that a user manually enables.

## Design quality after enforcement

A green architecture check proves that declared structural boundaries are respected. It does not prove that the internal design is elegant.

When design remains weak, `/ark-explore` can map large modules, mixed concerns, and inconsistent patterns without changing code. Structural repairs may be mechanical; design changes require user approval. ArkGate recommends applying one small extraction and running Doctor again before repeating a pattern. Shape residual is never silent plan B.

## Field honesty themes (4.1.0)

- Monorepo config walk-up with write-root split for mutative commands.
- Next `app/api/**` / `pages/api/**` as Application by default; UI routes stay Presentation.
- Type-only placement debt on the violations list as non-blocking (`failsStrict: false`); value edges still block.
- SPA / lib classification honesty so doctor does not false-green empty Application.
- `migrate-contract` retrofits API shell patterns without full re-init.
- Incomplete analysis and residual debt cannot look finished.

## Supported ecosystem

- Node.js 18 or later.
- TypeScript 5, 6, and 7.
- Presets: hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, and DDD bounded contexts.
- Frameworks and repository types: Nest, Next, Express, and TypeScript libraries.
- Coding-agent hosts: Claude Code, Grok Build, Google Antigravity, Cursor, OpenAI Codex, OpenCode.
- Guided `/ark-*` skills (except experimental runtime) integrate **both planes** and must label findings `[Layer]` vs `[ArkRules]`. Core workflows: `/ark-explore`, `/ark-place`, `/ark-fix`, `/ark-adopt`, `/ark-autopilot`, `/ark-contract`, `/ark-upgrade`.

## Scope and limits

ArkGate governs structural boundaries: file placement, layers, import direction, peer isolation, forbidden globals, cycles, bypass diagnostics, contract degradation, and—when opted in—declared ArkRules structure sensors and invariant coverage evidence.

ArkGate does not determine:

- whether arbitrary business behavior is correct beyond declared invariant coverage;
- whether a dependency was registered correctly in a runtime-specific container;
- whether tests are sufficient;
- whether the internal design is good;
- whether every host or manual filesystem operation was intercepted.

It complements formatters, linters, type checkers, test suites, runtime policy systems, code review, and human architectural judgment. An optional runtime package exists for experimental evaluation, but ArkGate's stable positioning is architecture co-pilot and gate—not runtime kernel.

## Version

Product line documented here: **ArkGate 4.1.0** (layers + optional ArkRules; field honesty). Published tag: `npm view arkgate version` → **4.1.0** on `latest` (as of site update 2026-07-25). Prefer live npm as source of truth if this file lags.

## Installation

```sh
npm install -D arkgate typescript
npx arkgate start
npx arkgate start --apply
npx arkgate-check --doctor
```

Useful enforcement commands:

```sh
npx arkgate-check --strict-merge
npx arkgate-check --plan
npx arkgate-check --coverage
npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
```

## Product site map (canonical URLs)

- https://www.arkgate.online/
- https://www.arkgate.online/start/
- https://www.arkgate.online/how-it-works/
- https://www.arkgate.online/hosts/
- https://www.arkgate.online/docs/
- https://www.arkgate.online/docs/use/
- https://www.arkgate.online/docs/develop/
- https://www.arkgate.online/changelog/
- https://www.arkgate.online/changelog/4.1.0/
- https://www.arkgate.online/llms.txt
- https://www.arkgate.online/llms-full.txt

## Ownership and distribution

- Creator: Pedro Knigge — https://github.com/pedroknigge
- License: MIT
- Package: https://www.npmjs.com/package/arkgate
- Source: https://github.com/pedroknigge/arkgate
- MCP Registry: https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.pedroknigge%2Farkgate

This context targets ArkGate 4.1.0+. Use the npm package and repository documentation as the authoritative sources for the latest version, commands, supported hosts, and enforcement guarantees.