ark-runtime-kernel 1.2.0 → 1.4.0

package/docs/agent-guide.md

@@ -277,6 +277,15 @@ createAdapter(PaymentGateway, stripeAdapter, {
 
 Preset: `elevenLayerProfile` plus `defineArchitectureProfilePolicy()` forbids invalid declared dependencies across the 11-layer profile. `architecturalPolicies.cleanArchitectureMatrix()` remains available for the older four-prefix model.
 
+Runtime support depth varies by design. Layers with dedicated kernel modules:
+DomainModel/ApplicationOrchestration (intents, policies), WorkflowSagaEngine
+(workflow engine), PersistenceAdapters (adapters, outbox), ReportingReadModels
+(projections), ExtensibilityMetadata (metadata registry), SecurityAuditObservability
+(audit trail, drift reporter), Kernel (event bus, graph, manifest).
+PresentationAdapters, IntegrationAdapters, and BackgroundJobsScheduling are
+**boundary-only on purpose**: Ark governs what they may import and publish, but does
+not replace your web framework, HTTP clients, or job scheduler.
+
 ## Write-Path Gate (MCP)
 
 The strongest place to constrain an AI agent is the moment it writes a file, not after.

package/docs/ai-gates.md

@@ -31,10 +31,19 @@ GitHub Actions, `AGENTS.md`, and a Codex TOML snippet under `docs/`. It skips
 existing files unless you pass `--force`, so review and commit only the templates
 that match your project.
 
+If your project uses Codex, treat the MCP registration as part of the default setup,
+not an optional extra. Ark works best when Codex can read `ark://manifest` before it
+writes code; that is the fast path to avoiding architecture drift during generation.
+
 ## Claude Code — hook (recommended, hard block)
 
 `ark-mcp --hook` is a one-shot PreToolUse gate: it reads the hook payload from stdin, computes the **post-edit** file content, validates it, and exits `2` (block, violations on stderr) or `0` (allow). The agent sees the violations and self-corrects.
 
+Like `ark-check --baseline`, the hook ratchets: an edit is blocked only when it **adds**
+violations relative to the file's current on-disk state, so files with pre-existing
+(baselined) violations stay editable — they just can't get worse. New files block on
+every violation.
+
 Add to your project's `.claude/settings.json`:
 
 ```json
@@ -64,6 +73,47 @@ Ark architecture gate blocked this write to src/domain/order.ts (layer: DomainMo
 Fix the violations and retry. The architecture contract is available as the ark://manifest MCP resource.
 ```
 
+## Claude Code — SessionStart context injection (know the rules before the first token)
+
+The write gate teaches by rejection; the SessionStart hook teaches up front.
+`ark-mcp --session-context` prints a compact contract summary — layers, forbidden
+globals, denied-edge count, baseline state, and the check command — which Claude Code
+injects into the agent's context at session start:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ark-mcp --session-context --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+What the agent sees:
+
+```
+Ark architecture contract governs this project (ark.config.json is authoritative).
+Layers:
+  - DomainModel: src/domain/** — forbidden globals: fetch, process, Date.now, Math.random
+  - PersistenceAdapters: src/adapters/persistence/**
+Rules: 10 denied layer edge(s). Full contract: ark://manifest MCP resource.
+Baseline: 3 frozen violation(s) — only NEW violations fail; do not add to them.
+After edits run: npx ark-check --root . --config ark.config.json --strict-config
+```
+
+The hook belongs in the **project's** `.claude/settings.json` (that's what
+`--install-agent-gates` generates). It is also safe by construction if you prefer it in
+your global settings: without an `ark.config.json` in the project, `--session-context`
+prints nothing and exits 0, so non-Ark projects are untouched.
+
 ## Claude Code — MCP server (contract discovery + on-demand validation)
 
 The MCP server exposes two things agents can use proactively:
@@ -124,6 +174,8 @@ Your hard backstop in Cursor is CI: `ark-check` fails the PR on anything that sl
 
 ## OpenAI Codex CLI
 
+Recommended for Ark projects.
+
 `~/.codex/config.toml`:
 
 ```toml
@@ -133,6 +185,30 @@ args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
 ```
 
 Same model as Cursor: MCP for discovery/validation, `ark-check` in CI as the hard gate.
+For Ark projects, register the MCP server as soon as the repo is adopted so the agent
+has the contract available from the first edit.
+
+## Instruction-tier agents: Windsurf, Cline, GitHub Copilot, Kiro, Gemini CLI
+
+Agents without MCP or hook support still follow the contract through an always-on
+project rule file. `ark-check --install-agent-gates` generates them (auto-detected
+from `.windsurf/`, `.clinerules/`, `.kiro/`; Copilot is explicit-only):
+
+```bash
+npx ark-check --install-agent-gates --tools windsurf,cline,copilot,kiro
+```
+
+| Tool | File written |
+|------|--------------|
+| Windsurf | `.windsurf/rules/ark.md` |
+| Cline | `.clinerules/ark.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Kiro | `.kiro/steering/ark.md` |
+| Gemini CLI | none needed — it reads the generated `AGENTS.md` |
+
+All of them derive from the same contract as `AGENTS.md` and the Cursor rule, so the
+steps cannot drift. These are advisory (the agent reads rules; nothing blocks the
+write) — keep `ark-check` in CI as the hard gate.
 
 ## Any other agent runtime with shell hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ark-runtime-kernel",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Architectural Runtime Kernel — governance for Hexagonal + Event-Driven + DDD systems",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -82,7 +82,13 @@
     "ai-agents",
     "mcp",
     "lint",
-    "architecture-fitness"
+    "architecture-fitness",
+    "architecture-enforcement",
+    "import-rules",
+    "dependency-rules",
+    "boundaries",
+    "layered-architecture",
+    "ai-code-gate"
   ],
   "license": "MIT",
   "repository": {

package/server.json

@@ -1,22 +1,22 @@
 {
-  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.pedroknigge/ark",
-  "description": "Architecture write-gate for AI agents: validates generated code against your Hexagonal/DDD layer rules before it lands, and exposes the machine-readable architecture contract (ark://manifest).",
+  "description": "Architecture write-gate for AI agents: blocks code that violates your Hexagonal/DDD layer rules.",
   "repository": {
     "url": "https://github.com/pedroknigge/ark-runtime-kernel",
     "source": "github"
   },
-  "version": "1.1.0",
+  "version": "1.4.0",
   "packages": [
     {
-      "registry_type": "npm",
+      "registryType": "npm",
       "identifier": "ark-runtime-kernel",
-      "version": "1.1.0",
+      "version": "1.4.0",
+      "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
       },
-      "runtime_hint": "npx",
-      "package_arguments": [
+      "packageArguments": [
         { "type": "positional", "value": "ark-mcp" },
         { "type": "named", "name": "--root", "value": ".", "description": "Project root" },
         {

package/docs/blog/how-i-stopped-claude-from-breaking-my-architecture.md

@@ -1,85 +0,0 @@
-# How I stopped Claude from breaking my hexagonal architecture
-
-*Draft — publish on dev.to / HN / r/typescript alongside the repo going public.*
-
----
-
-AI agents write most of my code now. They're fast, they're tireless, and they have absolutely no respect for my architecture.
-
-Ask an agent to "add a findById method to Order" and there's a decent chance it imports the Postgres repository straight into the domain layer. The code compiles. The tests pass. The PR looks fine at a glance. Three months of that and your hexagonal architecture is a decorative diagram.
-
-The usual answer is "review harder" — which doesn't scale when the agent produces 30 PRs a week — or "add a linter", which catches the violation *after* the agent already built three files on top of it.
-
-## The insight: block at write time, not review time
-
-Agent runtimes like Claude Code have pre-write hooks: a shell command that runs *before* a file edit lands, and can veto it. That's a fundamentally better enforcement point than CI:
-
-1. The violation never reaches disk.
-2. The agent sees the error **in its loop** and self-corrects immediately — it defines the port in the domain and implements it in the adapter, like you would have asked for in review.
-
-So I built [Ark](https://github.com/pedroknigge/ark-runtime-kernel). You describe your architecture once, as data:
-
-```json
-{
-  "layers": [
-    { "name": "DomainModel", "patterns": ["src/domain/**"] },
-    { "name": "PersistenceAdapters", "patterns": ["src/adapters/persistence/**"] }
-  ],
-  "rules": [
-    { "from": "DomainModel", "to": "PersistenceAdapters", "allowed": false }
-  ]
-}
-```
-
-Then wire it into Claude Code as a PreToolUse hook:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [{
-      "matcher": "Write|Edit|MultiEdit",
-      "hooks": [{ "type": "command",
-        "command": "npx ark-mcp --hook --root \"$CLAUDE_PROJECT_DIR\" --config ark.config.json" }]
-    }]
-  }
-}
-```
-
-Now the same request plays out like this:
-
-```
-● Write(src/domain/order.ts)
-✗ Ark architecture gate blocked this write to src/domain/order.ts (layer: DomainModel):
-- [FORBIDDEN_PATTERN] Forbidden pattern matched: /from ['"].*\/(infra|adapters|persistence|db)/i (line 1)
-- [FORBIDDEN_IMPORT] Forbidden import target: "../adapters/persistence/order-repository". (line 1)
-Fix the violations and retry. The architecture contract is available as the ark://manifest MCP resource.
-
-● The domain layer can't import persistence adapters. I'll define the port in
-  the domain instead and implement it in src/adapters/persistence/.
-```
-
-The agent fixed its own architecture violation. Nobody reviewed anything.
-
-## Details that turned out to matter
-
-**The gate validates the post-edit file, not the diff.** An edit snippet out of context tells you nothing about imports. `ark-mcp --hook` applies the proposed edit to the current file content and validates the result.
-
-**The same config gates CI.** Not every write goes through an agent, and not every agent runtime has hooks. `ark-check` runs the same rules in CI with TypeScript's real module resolver — path aliases and all — so nothing merges that violates the contract, whoever wrote it.
-
-**Agents can read the contract, not just bounce off it.** The MCP server also exposes `ark://manifest` — the architecture as JSON — so agents get the rules *before* generating code instead of learning by rejection.
-
-**Existing codebases need a ratchet.** Nobody adopts a checker that greets them with 400 errors. `ark-check --update-baseline` freezes today's violations; from then on only *new* ones fail. The count only goes down.
-
-## What about dependency-cruiser / eslint-plugin-boundaries?
-
-They're good tools and they cover the CI half. What they don't have is the write-time half: an MCP server and hook designed for agent runtimes, plus a machine-readable manifest for agents to consume. That's the part that changes agent behavior instead of just grading it.
-
-## Try it
-
-```bash
-npm i -D ark-runtime-kernel typescript
-npx ark-check --init      # infers layers from your folder structure
-npx ark-check             # CI gate
-```
-
-Repo: https://github.com/pedroknigge/ark-runtime-kernel — zero dependencies, MIT.