ark-runtime-kernel 1.3.0 → 1.5.0

package/docs/agent-guide.md

@@ -188,10 +188,15 @@ Example config:
 `tsconfig.json` — relative, path-alias (e.g. `@infra/db`), package imports, dynamic
 `import()`, and `require()` — plus string intent references. It also flags raw
 `publish()` calls, publish calls without `metadata.source`, and source intent literals
-whose resolved layer differs from the publishing file layer. Pass `--tsconfig <path>` to point at a specific config
-(otherwise the nearest `tsconfig.json` from `--root` is used). It resolves modules the way
-your build does, but is intentionally not yet a full type-graph analyzer (cross-layer
-type-only references beyond the import specifier are out of scope).
+whose resolved layer differs from the publishing file layer. Pass `--tsconfig <path>` to force one config
+for every file; otherwise each source file uses the nearest `tsconfig.json` above it (like
+`tsc`), so monorepos with per-package alias maps work under a single `--root`. It resolves
+modules the way your build does, but is intentionally not yet a full type-graph analyzer
+(cross-layer type-only references beyond the import specifier are out of scope).
+
+Repeat runs are cached in `node_modules/.cache/ark-check.json` — unchanged files skip the
+parse, while import edges always re-resolve against the live filesystem so the cache can
+never hide a new violation. `--no-cache` disables it.
 
 `ark-check --json` also reports `warnings` for incomplete governance coverage: missing
 layers, unclassified included files, unmatched layer patterns, duplicate layers, and rules

package/docs/ai-gates.md

@@ -39,6 +39,11 @@ writes code; that is the fast path to avoiding architecture drift during generat
 
 `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
@@ -68,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:
@@ -142,6 +188,28 @@ Same model as Cursor: MCP for discovery/validation, `ark-check` in CI as the har
 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
 
 If your runtime can run a shell command before file writes and pass the tool payload on stdin (Claude Code's PreToolUse contract), `ark-mcp --hook` works as-is. The contract:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ark-runtime-kernel",
-  "version": "1.3.0",
+  "version": "1.5.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.3.0",
+  "version": "1.5.0",
   "packages": [
     {
-      "registry_type": "npm",
+      "registryType": "npm",
       "identifier": "ark-runtime-kernel",
-      "version": "1.3.0",
+      "version": "1.5.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" },
         {