ark-runtime-kernel 1.2.0 → 1.3.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,6 +31,10 @@ 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.
@@ -124,6 +128,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 +139,8 @@ 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.
 
 ## Any other agent runtime with shell hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ark-runtime-kernel",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Architectural Runtime Kernel — governance for Hexagonal + Event-Driven + DDD systems",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/ark-runtime-kernel",
     "source": "github"
   },
-  "version": "1.1.0",
+  "version": "1.3.0",
   "packages": [
     {
       "registry_type": "npm",
       "identifier": "ark-runtime-kernel",
-      "version": "1.1.0",
+      "version": "1.3.0",
       "transport": {
         "type": "stdio"
       },

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.