arkgate 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Knigge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+<div align="center">
+
+# ArkGate — Architecture Co-pilot for AI TypeScript
+
+**Write gate · CI gate · co-pilot** for TypeScript projects that use AI agents.
+
+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.
+
+[![CI](https://github.com/pedroknigge/ark-runtime-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/ark-runtime-kernel/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)
+![Zero deps](https://img.shields.io/badge/dependencies-0-success)
+
+</div>
+
+---
+
+## What it is
+
+**ArkGate** is a **machine-readable architecture contract** for TypeScript, enforced in three places:
+
+| When | Tool | What happens |
+|------|------|----------------|
+| **While the AI writes** | `arkgate-mcp` (write gate) | Blocks bad edits; agent self-corrects |
+| **Before merge** | `arkgate-check` (CI) | Full TypeScript import graph + rules |
+| **At runtime** *(optional)* | `createArkKernel()` | Event/intent governance if you opt in |
+
+One file drives all of it: **`ark.config.json`**.
+
+It is **not** a web framework, ORM, or job runner — and the optional runtime kernel is not
+the product. The product is the **agent-native architecture gate** (write path + CI + plan/loop)
+plus tools agents can read *before* generating code (`ark_place`, `ark://manifest`, …).
+
+![Write gate: agent blocked, then self-corrects](docs/assets/ark-write-gate.svg)
+
+---
+
+## Who it’s for
+
+| You are… | You want… | Start with |
+|----------|-----------|------------|
+| **Builder with AI** (not necessarily an architect) | Order without learning “hexagonal” first | `npx arkgate start` → `/ark-autopilot` |
+| **Engineer / tech lead** | A strict contract, CI, baselines, precise control | `ark init` + `ark-check` + write gate |
+| **Team on a messy repo** | Truth about coverage + a cleanup path, not a false green | `ark-check --coverage` → `/ark-adopt` |
+
+**Not for:** projects with no TypeScript, people who only want a one-off lint rule and no agent workflow, or anyone looking for an app framework.
+
+---
+
+## What you get (in plain language)
+
+1. **A shape** — Ark looks at your repo (Nest, Next, API, library, …) and suggests how to organize it.
+2. **Guardrails** — config + agent gates + CI so new code can’t quietly break layers.
+3. **A plan** — what’s safe for an agent to fix vs what needs your decision.
+4. **Honesty** — if Ark only governs 10% of the tree, it says so. “Clean” with almost no coverage is not success.
+
+Three **operating modes** (not “user types”) on the same contract:
+
+| Mode | Meaning |
+|------|---------|
+| **Suggest** | Install a starting shape |
+| **Adapt** | Match the contract to real folders / raise coverage |
+| **Enforce** | Gates actually protect you |
+
+---
+
+## Start in one minute
+
+```bash
+npm install -D arkgate typescript
+npx arkgate start          # look at the project → setup → plan (plain language)
+# (aliases: ark start / ark-check / ark-mcp still work)
+```
+
+Then, in your agent (Claude / Cursor / Codex / **Grok** / …):
+
+```text
+/ark-autopilot
+```
+
+That is the **co-pilot**: set up → plan → apply safe fixes (validated, reversible) → propose the rest → leave gates on.
+
+**Prefer manual control?**
+
+```bash
+npx arkgate init              # config + gates
+npx arkgate-check             # CI gate
+npx arkgate-check --plan      # classified fix list
+npx arkgate-check --coverage
+```
+
+Works with **npm, pnpm, and yarn**. No install lifecycle scripts (safe for hardened CI).
+
+---
+
+## Agent skills (`/ark-*`)
+
+Install with agent gates:
+
+```bash
+npx arkgate-check --install-agent-gates
+# or pick hosts: --tools claude,cursor,codex,grok
+```
+
+| Skill | What it does |
+|-------|----------------|
+| **`/ark-autopilot`** | End-to-end co-pilot: setup → plan → safe auto-fixes → propose the rest → leave gates on |
+| **`/ark-loop`** | Drive the remediation plan in a discardable worktree; only `mechanical-safe` steps auto-apply |
+| **`/ark-architect`** | Greenfield: pick application shape, phase-1 layers, scaffold, verify honestly |
+| **`/ark-adopt`** | Brownfield: match contract to reality, raise coverage, freeze only real debt |
+| **`/ark-contract`** | Safely edit `ark.config.json` (smallest change, strict re-check) |
+| **`/ark-place`** | Where does this new artifact go? Layer, path, naming — then scaffold |
+| **`/ark-fix`** | Fix violations at the source (no disable comments, no gate weakening) |
+| **`/ark-explain`** | Explain the current contract, coverage, and report in plain language |
+| **`/ark-coverage`** | Audit which Ark capabilities you are not using yet |
+| **`/ark-runtime`** | Opt-in: migrate hand-rolled bus/outbox/sagas onto the runtime kernel |
+| **`/ark-upgrade`** | Bump the package and refresh gates + skills for every agent host |
+
+Supported agent hosts for full MCP/hook gates: **Claude Code**, **Cursor**, **OpenAI Codex**, **Grok Build**. Instruction-tier hosts (Windsurf, Cline, Copilot, …) get rule files. See [docs/ai-gates.md](docs/ai-gates.md).
+
+---
+
+## How it works (short)
+
+```
+ark.config.json
+      │
+      ├─► Write gate (ark-mcp)     — agent PreToolUse / MCP tools
+      ├─► CI gate (ark-check)      — PR / main
+      └─► Runtime kernel (opt-in)  — only if you call it
+```
+
+- **Presets:** hexagonal, layered, feature-sliced, monorepo (all layers optional).
+- **Frameworks:** Nest / Next / express / library layouts get sensible globs on init so day-one coverage is real.
+- **Brownfield:** baseline ratchet, refuse to freeze a wrong contract, `/ark-adopt` for mature trees.
+- **Agents:** skills above install into Claude / Cursor / Codex / Grok command locations.
+
+### Why not only ESLint / dependency-cruiser / Nx?
+
+| | Ark | Typical boundary linter |
+|--|:---:|:---:|
+| CI import rules | ✅ | ✅ |
+| Block **AI writes** before they land | ✅ | ❌ |
+| Contract agents can read (`ark://manifest`) | ✅ | ❌ |
+| Placement tools (`ark_place`, …) | ✅ | ❌ |
+| Honest governed % + adoption path | ✅ | ❌ |
+| Zero runtime dependencies | ✅ | varies |
+
+---
+
+## Common commands
+
+```bash
+npx arkgate start                         # guided setup + plan
+npx arkgate-check --doctor                # health + operating mode
+npx arkgate-check --plan                  # safe-to-auto-fix vs your call
+npx arkgate-check --coverage              # Governed: N%
+npx arkgate-check --report ark-report.html  # showcase HTML + origin/latest snapshots
+npx arkgate-check --baseline              # only NEW violations fail
+npx arkgate upgrade                       # update package + refresh gates/skills
+```
+
+CI (example):
+
+```yaml
+- run: npx arkgate-check --root . --config ark.config.json --strict-config
+# or: uses: pedroknigge/ark-runtime-kernel@main   # Action still on this repo until rename
+```
+
+---
+
+## Optional: runtime kernel
+
+Gates need **no app code changes**. If you also want runtime intent/event contracts:
+
+```ts
+import { createStrictArkKernelFromConfig } from 'arkgate';
+// see docs/production-hardening.md and package exports
+```
+
+NestJS: `arkgate/nestjs` (optional peer `@nestjs/common`).
+
+---
+
+## Documentation
+
+| Audience | Link |
+|----------|------|
+| New builders (plain language) | [docs/enthusiast/](docs/enthusiast/README.md) |
+| Wire Claude / Cursor / Codex / Grok | [docs/ai-gates.md](docs/ai-gates.md) |
+| Messy existing repo | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
+| Agent / MCP tools | [docs/agent-guide.md](docs/agent-guide.md) |
+| Demos | [docs/demos/](docs/demos/) |
+| Examples | [examples/](examples/README.md) |
+| Roadmap | [ROADMAP.md](ROADMAP.md) · [Changelog](CHANGELOG.md) |
+
+---
+
+## Develop this repo
+
+```bash
+npm ci && npm run build
+npx vitest run
+npm run typecheck
+npm run check:architecture   # Ark gates itself
+```
+
+**npm:** [`arkgate`](https://www.npmjs.com/package/arkgate) · formerly `ark-runtime-kernel`  
+**Product:** **ArkGate** — architecture co-pilot / gate for AI TypeScript (not a runtime kernel).  
+CLI: `arkgate` · `arkgate-check` · `arkgate-mcp` (aliases `ark` / `ark-check` / `ark-mcp` still work).
+
+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.**

package/SECURITY.md

@@ -0,0 +1,39 @@
+# Security Policy
+
+Ark runs in developer machines, CI, and agent tooling paths, so security reports are
+treated as high priority.
+
+## Supported Versions
+
+Security fixes target the latest published minor version. If a fix needs a new release,
+the changelog will call out the affected versions and the patched version.
+
+## Reporting A Vulnerability
+
+Please do not open a public issue for a suspected vulnerability.
+
+Preferred path: use GitHub's private vulnerability reporting for this repository. Include:
+
+- affected version or commit
+- reproduction steps
+- expected impact
+- whether the issue affects `ark-check`, `ark-mcp`, generated agent gates, the GitHub
+  Action, or the optional runtime kernel
+
+If private vulnerability reporting is unavailable, open a minimal public issue asking for
+a private security contact without including exploit details.
+
+## Release Verification
+
+Ark releases are GitHub-first:
+
+1. Changes land on GitHub and must pass CI plus the dedicated security workflow.
+2. A GitHub Release is created from an annotated `vX.Y.Z` tag. Signed tags are
+   supported and can be made mandatory by setting `ARK_REQUIRE_SIGNED_RELEASE_TAG=true`
+   in the publish workflow once release signing is configured.
+3. The manual `Publish npm` workflow verifies the tag, requires the GitHub Release to
+   exist, reruns release checks, publishes npm with provenance, and uploads a SHA-256
+   checksum for the npm tarball to the GitHub Release.
+
+Consumers in sensitive environments should still pin exact npm versions and GitHub
+Action SHAs/tags, then verify npm provenance and the release checksum before upgrading.