arkgate

<div align="center">

# ArkGate — Architecture Co-pilot for AI TypeScript

**One contract. One gate. One co-pilot.**

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

[![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)

</div>

> **ArkGate 3.8.0** is current stable: complete analysis fails closed, complete candidates share
> one resolved architecture verdict, managed upgrades are digest-bound, and an opt-in design-delta
> ratchet blocks new or worsened UI domain logic. [Release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.0.md).

> **TypeScript 7 distribution note:** ArkGate prefers a usable project compiler API, then its
> exact, physically distinct TypeScript 6 analysis host. Analysis reports required
> `complete | partial | unavailable` status; incomplete results cannot look green. See the
> [exact boundary](docs/typescript-support.md).

---

## The only flow (humans and agents)

If you remember nothing else:

```text
1.  npx arkgate start          ← read-only preview: files + commands + projected coverage
    npx arkgate start --apply  ← apply exactly the previewed mutations
2.  Compact router             ← MCP/AGENTS routes place, validate, and architecture checks
    /ark-autopilot             ← optional full guided workflow after its skill pack is installed
3.  npx arkgate-check --doctor ← “where am I?” anytime (one status screen)
```

| Stuck on… | Do this |
|-----------|---------|
| Gate failed after an edit | `/ark-fix` |
| “Where does this new file go?” | `/ark-place` |
| Contract globs / layers wrong | `/ark-contract` |
| **Messy / spaghetti code** (even if the gate is green) | **`/ark-explore`** then **`/ark-autopilot`** — [below](#less-spaghetti-after-the-gate-is-green) |
| New ArkGate version | `/ark-upgrade` |

**Everything else is optional.** You do not need to learn “modes”, the full skill pack, or the runtime
kernel to get value. The compact router is enough for normal work; install `/ark-autopilot` only
when you want the full guided workflow.

---

## What it is (30 seconds)

**ArkGate** = a machine-readable architecture file (`ark.config.json`) enforced at CI, with
host-specific protection while an agent writes:

**Name note:** this is the TypeScript architecture-enforcement package published as `arkgate`.
It is not affiliated with the separate Archgate CLI project.

| When | Tool |
|------|------|
| **While the AI writes** | Hard PreToolUse block on Claude/Grok; advisory MCP on Cursor/Codex |
| **Before merge** | `arkgate-check` CI check; merge blocking requires it as a required status |

Optional later: the **experimental** runtime kernel (`createArkKernel`) if you want to evaluate
event/intent governance. It is not required for gate adoption.

It is **not** a web framework, ORM, or job runner.

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

---

## Who it’s for

Same start for almost everyone: **`npx arkgate start` → compact router** (then
`/ark-autopilot` when you opt into the full skill pack).

| You are… | Same start, then… |
|----------|-------------------|
| Builder with AI | Use the compact router and doctor; add autopilot when you want guided remediation |
| Tech lead on a messy monorepo | Add autopilot (or deeper `/ark-adopt` for a focused brownfield pass) |
| Power user | Same flow; use `ark-check --plan` / `--coverage` when you want the raw sensor |

**Not for:** no TypeScript, “just one lint rule”, or looking for an app framework.

---

## Status, not settings (“modes”)

`ark-check --doctor` may say **Suggest / Adapt / Enforce**. That is a **status light**, not a
mode you configure:

| Light | Means | Your move |
|-------|--------|-----------|
| **Suggest** | New/thin project | Finish `start` + autopilot |
| **Adapt** | Not fully protected yet | Keep autopilot / adopt until clean |
| **Enforce** | Contract coverage is honest and checked **edges** are clean | Keep write path + CI. If the tree is still a mess → [Shape flow](#less-spaghetti-after-the-gate-is-green) |
| **Enforce · design-weak** | Edges clean, but doctor still sees design smells (`designSmells` / `patternBets`) | **`/ark-explore`** (shape-focus) → **`/ark-autopilot`** for dual-plan **B** — not “done” |

You **arrive** at Enforce. You never “turn on Enforce”.  
**Enforce does not mean the design is elegant** — only that the contract’s import edges are honest.

---

## Less spaghetti after the gate is green

A green check can still leave god modules, SQL in routes, and three patterns at once.
That residual is **Shape** work — plan **B**, never auto-applied as mechanical-safe.

```text
1.  /ark-explore              ← map + dual-plan B + extraction cards (no apply)
2.  /ark-autopilot            ← apply A (edges); B only with your ok, one pilot at a time
3.  npx arkgate-check --doctor
    npx arkgate-check --plan --json   ← designWeak + patternBets when residual remains
```

| If… | Skill |
|-----|--------|
| Need the map / “what’s the golden pattern?” | `/ark-explore` |
| Ready to execute the dual plan | `/ark-autopilot` |
| Contract still lies (false-green, wrong globs) | `/ark-adopt` first, then explore |
| One cluster only | `/ark-fix` (+ extraction card) |
| Only care about governed% / gates installed | `/ark-coverage` (not the Shape map) |

Phases: **Align** (honest contract) → **Stabilize** (real baseline) → **Shape** (golden pattern + pilot).  
Details: [docs/brownfield-adoption.md](docs/brownfield-adoption.md) §6 · skills install: `npx arkgate-check --install-agent-gates`.

---

## Upgrading from `ark-runtime-kernel`?

**Same product**, new package name. Config and `/ark-*` skills stay.

```bash
npm uninstall ark-runtime-kernel && npm install -D arkgate
npx arkgate-check --install-agent-gates --force
npx arkgate-check --doctor
```

Full checklist (CI, MCP, Codex, imports): **[migrate-from-ark-runtime-kernel.md](https://github.com/pedroknigge/arkgate/blob/main/docs/migrate-from-ark-runtime-kernel.md)**.

---

## Start in one minute

```bash
npm install -D arkgate typescript
npx arkgate start                 # read-only preview: exact mutations + projected coverage
npx arkgate start --apply         # apply the compact contract → active-host router → CI plan
# optional, after installing the full skill pack:
#   /ark-autopilot
npx arkgate-check --doctor        # status light + next action
```

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

<details>
<summary>What <code>/ark-autopilot</code> does under the hood (optional detail)</summary>

1. Setup if needed (`ark start` previews; review, then `ark start --apply`).
2. **Explore pass** (decision-grade map of *this* product; field path when demos exist).
3. **Dual plan:** **A** remediation from `--plan` (mechanical-safe only by default); **B** pattern/evolution bets (never auto-applied as mechanical-safe). Empty plan ≠ “healthy” without explore/B.
4. Apply A → re-check; judgment only when you ask for full apply.
5. Gates on + latest report (evolution vs frozen origin).

Standalone recon without applying: `/ark-explore`.

</details>

<details>
<summary>Manual / power-user CLI only</summary>

```bash
npx arkgate init
npx arkgate-check
npx arkgate-check --plan
npx arkgate-check --coverage
```

</details>

---

## Other skills (only when you need them)

Install once: `npx arkgate-check --install-agent-gates`
(`--tools claude,cursor,codex,grok` to pick hosts.)

**The compact router is the default; `/ark-autopilot` is the full guided option.** The rest are
escapes, not a second curriculum. Full-install `AGENTS.md` includes a **skill routing table**
(trigger → skill). Skills are
**dual-engine** (CLI sensor + read real source) and end with a fixed **completion contract**;
critical handoffs say **STOP** and name the next skill (hosts must follow — markdown cannot chain calls).
When the host allows it, skills may **fan out parallel subagents** (disjoint scopes);
otherwise they **fall back to sequential**.

**Write path (Track W):** Prefer MCP **`ark_prepare_write`** when you have a snippet (place +
constrain + validate + optional `autoPatch` + `judgmentBrief`). PreToolUse hooks with
`--hook-repair` on Claude/Grok emit machine-readable repair payloads on deny (still hard block;
never silent write). Cursor/Codex MCP calls remain advisory. See
[docs/ai-gates.md](docs/ai-gates.md).

For a complete multi-file architecture-source candidate, use MCP **`ark_prepare_change`** or
`ark preflight --changes change-set.json --json`. Creates, updates, and deletes are evaluated as
one read-only graph, so an edge or cycle that appears only across the batch is rejected before any
project file is written. With `--change-map map.json` (or MCP `changeMap`), the same verdict also
classifies planned structure as satisfied, missing, contradictory, or unplanned. This is structural
convergence only: behavioral completion is always reported as not evaluated.

ArkGate 3.8.0 closes the former compiler-free atomic-path divergence with versioned
resolved-candidate facts and a differential adapter corpus, including `tsconfig` aliases and
workspace edges. Strict CI remains the final merge boundary; lexical/single-snippet feedback is
explicitly partial and non-green.

Every blocking diagnostic carries stable rule/location/evidence fields plus one