arkgate

ArkGate — Architecture Co-pilot for AI TypeScript

One contract. One gate. One co-pilot.

Your AI writes most of the code. ArkGate keeps that work inside an architecture you can trust — and makes sure a “green” check means something real.

ArkGate 4.2.0 is prepared (workspace identity + safe multi-repo skills); 4.1.1 remains on npm latest until publication. 4.2.0 candidate · 4.1.1 · 4.1.0 · Docs hub · Product voice

Choose your path

You are…	Go here
Anyone (ship with AI, minimal jargon)	Use ArkGate
Developer (hosts, CI, config, brownfield)	Develop with ArkGate
Contributor (improve this library)	CONTRIBUTING

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 contract + host router + CI plan
npx arkgate-check --doctor        # control plane: status light + primary next action

That is the product. Doctor is the control plane — when stuck, do primary next action #1.

start → doctor → day-to-day (place + gate)
              ↘ optional /ark-autopilot after skill pack

Aliases ark / ark-check / ark-mcp still work. npm / pnpm / yarn. No install lifecycle scripts.

What it is

A machine-readable architecture file (ark.config.json) plus enforcement:

When	Tool
While the AI writes	Hard PreToolUse on supported hosts; advisory MCP elsewhere
Before merge	arkgate-check as a required CI status

Two planes (4.0)

Plane	What it guards	Config
Layers (always)	Who may talk to whom — imports, placement, purity, isolation	ark.config.json layers + rules
ArkRules (opt-in)	Habits inside a layer — structure sensors + domain invariants as data	arkRules → arkrules/<Layer>.json

Absence of ArkRules changes no inter-layer verdict. Label residual [Layer] vs [ArkRules].
Details: configuration · use path.

Not a web framework, ORM, or job runner. Optional experimental runtime is separate and not required for the gate.

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

Status lights (not settings)

Light	Means	Your move
Suggest	Thin / new tree	Finish start → doctor
Adapt	Not fully protected	Doctor action #1
Enforce	Honest edges under the contract	Keep write path + CI
Enforce · design-weak	Edges clean; design residual remains	Shape residual — not “done”

Details: docs/use.md.

Host enforcement support

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	Advisory only at write (no hard hook)	Advisory; the agent must call it	Required GitHub status context running arkgate-check --strict-merge (alias ark-check)	No hard-boundary payload
OpenAI Codex	Advisory / best-effort at write (not equivalent to Claude/Grok hard block)	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 (advisory host)
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

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. Cursor/Codex/OpenCode never get a fake hard write claim.

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 the hard guarantee lives at the merge gate

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) deny the listed write operations at write time; advisory surfaces (MCP, rules, OpenCode plugins) coach the agent while it works. But any local boundary can be routed around — another tool, a direct filesystem write, 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; the merge gate owns correctness.

A useful consequence: the contract 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 contract deliberately (start with /ark-explore), never to weaken the gate.

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?

	ArkGate	Typical boundary linter
CI import rules	✅	✅
Hard-block AI writes on supported hosts	✅	❌
Project-bound contract agents can read (ark_manifest)	✅	❌
Placement + preflight for multi-file changes	✅	❌
Honest governed % + dual plan (edges vs shape)	✅	❌
Opt-in intra-layer ArkRules (structure + invariants)	✅	❌
Incomplete analysis cannot look green	✅	varies

Common commands

npx arkgate start --apply
npx arkgate-check --doctor
npx arkgate-check --plan
npx arkgate-check --coverage
npx arkgate-check --strict-merge   # CI / required status
npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok

More: docs/develop.md · enthusiast track: docs/enthusiast/

Optional experimental runtime

Gates need no app runtime. The experimental @arkgate/runtime companion is separate and is not a production-readiness claim.

Durability stance

Default stores (InMemoryEventBuffer, InMemoryAuditStore, InMemoryReadModelStore, InMemoryWorkflowStore) are reference in-memory only — fine for tests and demos; they do not survive restarts and are not production durability. Implement the store interfaces for real systems. Details: docs/production-hardening.md.

Documentation

Audience	Link
Docs hub	docs/README.md
Anyone	docs/use.md
Developers integrating ArkGate	docs/develop.md
Contributors to this library	CONTRIBUTING.md
Host install detail	docs/ai-gates.md
Config · package surface · TS	configuration · package-surface · typescript-support
Brownfield	docs/brownfield-adoption.md
Security	SECURITY.md
Prepared candidate (4.2.0)	docs/releases/4.2.0.md · CHANGELOG
Current published (4.1.1)	docs/releases/4.1.1.md
Previous (4.1.0)	docs/releases/4.1.0.md
Previous patch (4.0.1)	docs/releases/4.0.1.md
Previous (4.0.0)	docs/releases/4.0.0.md
Previous (3.9.2)	docs/releases/3.9.2.md
History / maintainer evidence	docs/archive/

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 keeps AI-generated TypeScript inside an architecture you can trust — and tells you when it isn’t really enforcing anything yet.