ark-runtime-kernel 1.3.0 → 1.4.0

package/README.md

@@ -3,7 +3,9 @@
 # 🏛️ Ark — Architectural Runtime Kernel
 
 **Stop AI agents (and humans) from quietly breaking your architecture.**<br/>
-One machine-readable contract — enforced at write time, merge time, and (optionally) runtime.
+One machine-readable contract — enforced at write time, merge time, and (optionally) runtime.<br/>
+Ships a complete 11-layer architecture you can adopt one layer at a time.
+Gates **Claude Code, Cursor, and Codex** natively — plus rule files for Windsurf, Cline, Copilot, Kiro, and Gemini CLI.
 
 [![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/ark-runtime-kernel?color=cb3837&label=npm)](https://www.npmjs.com/package/ark-runtime-kernel)
@@ -12,7 +14,7 @@ One machine-readable contract — enforced at write time, merge time, and (optio
 ![TypeScript](https://img.shields.io/badge/TypeScript-first-3178c6?logo=typescript&logoColor=white)
 ![Zero deps](https://img.shields.io/badge/dependencies-0-success)
 
-[2-Minute Setup](#2-minute-setup) · [Why Ark](#why-ark-and-not-just-a-linter) · [AI Write Gate](#the-ai-write-gate) · [CI Gate](#ark-check--the-ci-gate) · [Runtime Kernel](#the-runtime-kernel-opt-in) · [Docs](#documentation)
+[2-Minute Setup](#2-minute-setup) · [Why Ark](#why-ark-and-not-just-a-linter) · [11 Layers](#batteries-included-the-11-layer-profile-all-optional) · [AI Write Gate](#the-ai-write-gate) · [CI Gate](#ark-check--the-ci-gate) · [Runtime Kernel](#the-runtime-kernel-opt-in) · [Docs](#documentation)
 
 </div>
 
@@ -124,6 +126,8 @@ If you only need import-boundary linting in CI, [dependency-cruiser](https://git
 | Cross-layer import checks in CI         | ✅ (TS resolver) | ✅ | ✅ | ✅ |
 | Blocks AI agents **before** code lands (MCP + hook) | ✅ | ❌ | ❌ | ❌ |
 | Machine-readable contract for agents (`ark://manifest`) | ✅ | ❌ | ❌ | ❌ |
+| Injects the contract into agent context at session start | ✅ | ❌ | ❌ | ❌ |
+| Forbidden ambient globals per layer (`Date.now` in domain, ...) | ✅ | ❌ | ➖ (generic ESLint) | ❌ |
 | Event/intent governance (who may publish what) | ✅ | ❌ | ❌ | ❌ |
 | Baseline ratchet for existing codebases | ✅ | ❌ | ➖ (via ESLint) | ❌ |
 | Optional runtime enforcement            | ✅ | ❌ | ❌ | ❌ |
@@ -133,19 +137,57 @@ If you only need import-boundary linting in CI, [dependency-cruiser](https://git
 
 | Gate         | Tool          | When it runs                  | What it enforces                              |
 |--------------|---------------|-------------------------------|-----------------------------------------------|
-| **Write**    | `ark-mcp`     | Agent PreToolUse (Write/Edit) | Layer rules, unknown intents, forbidden patterns |
-| **Merge**    | `ark-check`   | CI (GitHub Actions etc.)      | Cross-layer imports + intent references (real TS resolver) |
+| **Write**    | `ark-mcp`     | Agent PreToolUse (Write/Edit) | Layer rules, unknown intents, forbidden patterns + globals |
+| **Merge**    | `ark-check`   | CI (GitHub Actions etc.)      | Cross-layer imports + intent references (real TS resolver) + forbidden globals |
 | **Runtime**  | `createArkKernel()` | Running process (opt-in) | Intent registry, event contracts, observed layer flow, policies |
 
+## Batteries included: the 11-layer profile (all optional)
+
+You don't have to design a layer model before adopting Ark — it ships a complete,
+production-shaped division for Hexagonal + Event-Driven + DDD systems. Every layer is
+**optional by design**: on a fresh project the strict check passes immediately, and each
+layer starts being enforced the moment its directory gains source files. Adopt two
+layers or all eleven; `ark.config.json` is always authoritative and you can rename,
+remove, or re-map any of it.
+
+| Layer | Conventional directories | Intent prefixes |
+|-------|--------------------------|-----------------|
+| DomainModel | `domain/` | `Domain.` |
+| ApplicationOrchestration | `application/`, `app/` | `Application.` |
+| PersistenceAdapters | `adapters/persistence/`, `repositories/`, ... | `Adapter.Persistence.`, `Adapter.Repository.` |
+| IntegrationAdapters | `adapters/integration/`, `integrations/`, ... | `Adapter.Integration.`, `Adapter.External.` |
+| WorkflowSagaEngine | `workflows/`, `sagas/` | `Workflow.` |
+| BackgroundJobsScheduling | `jobs/`, `schedules/` | `Job.` |
+| PresentationAdapters | `presentation/`, `adapters/api/`, ... | `Presentation.`, `Adapter.Api.`, ... |
+| ReportingReadModels | `reporting/`, `read-models/`, `projections/` | `Reporting.` |
+| ExtensibilityMetadata | `metadata/`, `extensions/` | `Metadata.` |
+| SecurityAuditObservability | `security/`, `audit/`, `observability/` | `Security.`, `Audit.`, `Observability.` |
+| Kernel | `kernel/` | `Kernel.` |
+
+The default rule matrix is strict-deny: only the classic flows are open
+(Presentation→Application, Application→Domain, Workflow→Application/Domain,
+Jobs→Application) and everything else is a violation until you allow it explicitly.
+The profile isn't just for the linter — agents get it too: `ark://manifest` lists the
+layers your project hasn't adopted yet as `suggestedLayers`, so when an agent needs to
+create its first saga or background job, it puts it in the conventional place and adds
+the layer to the config instead of inventing an ungoverned location.
+
+```bash
+npx ark-check --print-config eleven-layer > ark.config.json   # the full profile, ready to edit
+```
+
 ## The AI Write Gate
 
 `ark-mcp` is a zero-dependency MCP server + one-shot hook:
 
 - **`ark-mcp --hook`** — PreToolUse gate: computes the **post-edit** file content, validates it against your layers, exits 2 with the violations when the write must be blocked. The agent self-corrects.
+- **`ark-mcp --session-context`** — SessionStart injection: prints a compact contract summary (layers, forbidden globals, baseline state) into the agent's context, so it knows the architecture from the first token instead of learning by rejection. Silent no-op outside Ark projects, so it can't leak into other repos.
 - **`validate_code` tool** — on-demand validation of a snippet, for runtimes without hooks.
-- **`ark://manifest` resource** — the architecture as JSON, so agents read the rules *before* generating code instead of learning by rejection.
+- **`ark://manifest` resource** — the architecture as JSON, so agents read the rules *before* generating code.
 
-Copy-paste setups for **Claude Code, Cursor, and OpenAI Codex**: [docs/ai-gates.md](docs/ai-gates.md).
+Copy-paste setups for **Claude Code, Cursor, and OpenAI Codex**, plus instruction-tier
+rule files for **Windsurf, Cline, GitHub Copilot, and Kiro** (Gemini CLI reads the
+generated `AGENTS.md` directly): [docs/ai-gates.md](docs/ai-gates.md).
 
 ## `ark-check` — The CI Gate
 
@@ -161,6 +203,7 @@ npx ark-check --baseline                                          # ratchet mode
 - String intent references across forbidden layers
 - Raw `publish()` calls that bypass registered intent creators
 - Missing / mismatched publish `source` metadata
+- Forbidden ambient globals per layer (`fetch`, `Date.now`, `Math.random`, ...) — see below
 
 Violations come with the layer edge, the resolved target, and a fix hint:
 
@@ -171,6 +214,35 @@ Violations come with the layer edge, the resolved target, and a fix hint:
   fix: Depend on a port/interface owned by an inner layer instead, or move this code.
 ```
 
+### Domain purity: `forbiddenGlobals`
+
+Import rules can't catch code that reaches for an ambient global — an agent can call
+`fetch()` or `Date.now()` in your domain layer without importing anything. Declare the
+globals a layer must not touch and both the write gate and CI enforce it:
+
+```jsonc
+// ark.config.json
+{
+  "name": "DomainModel",
+  "patterns": ["src/domain/**"],
+  "intentPrefixes": ["Domain."],
+  "forbiddenGlobals": ["fetch", "process", "Date.now", "Math.random"]
+}
+```
+
+```
+✖ FORBIDDEN_GLOBAL  src/domain/order.ts:12
+  DomainModel must not use the ambient global "Date.now".
+  fix: Inject the capability through a port (e.g. a Clock, IdGenerator, or HttpPort).
+```
+
+Entries are either dotted (`"Date.now"` flags exactly that property access) or bare
+(`"console"` flags `console.*`, `fetch(...)`, `new WebSocket(...)`). Detection is
+positional, not scope-aware: mentions in types or import names are never flagged.
+`npx ark init` seeds the domain layer with `["fetch", "process", "Date.now", "Math.random"]`
+(a pure domain does no I/O and is deterministic); add `"console"` or any other global per
+project. Violations participate in the `--baseline` ratchet like every other rule.
+
 ### GitHub Action
 
 ```yaml
@@ -189,7 +261,15 @@ import ark from 'ark-runtime-kernel/eslint';
 export default [ark.configs.recommended];
 ```
 
-Rules: `ark/no-domain-infra-imports`, `ark/no-raw-event-publish`, `ark/require-publish-source`.
+Rules: `ark/no-domain-infra-imports`, `ark/no-raw-event-publish`, `ark/require-publish-source`,
+`ark/no-forbidden-globals` (not in `recommended` — scope it to your layer directories):
+
+```js
+{
+  files: ['src/domain/**'],
+  rules: { 'ark/no-forbidden-globals': ['error', { globals: ['fetch', 'process', 'Date.now', 'Math.random'] }] },
+}
+```
 
 ## The Runtime Kernel (opt-in)
 

package/bin/ark-check.mjs

@@ -2,9 +2,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {
+  DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   DEFAULT_INTENT_PREFIXES,
   DEFAULT_LAYER_DIRECTORIES,
   DEFAULT_RULES,
+  collectForbiddenGlobalUses,
   createElevenLayerConfig,
   globToRegExp,
   layerForFile,
@@ -96,7 +98,8 @@ function usage() {
     '{',
     '  "include": ["src"],',
     '  "layers": [',
-    '    { "name": "DomainModel", "patterns": ["src/domain/**"], "intentPrefixes": ["Domain."] }',
+    '    { "name": "DomainModel", "patterns": ["src/domain/**"], "intentPrefixes": ["Domain."],',
+    '      "forbiddenGlobals": ["fetch", "process", "Date.now", "Math.random"] }',
     '  ],',
     '  "rules": [{ "from": "DomainModel", "to": "PersistenceAdapters", "allowed": false }]',
     '}',
@@ -109,9 +112,13 @@ function usage() {
     'with --strict-config to enforce gate presence and architecture in one run.',
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
-    'project, plus tool-specific templates. Pass --tools claude,cursor,codex to pick',
-    'which tool configs to write; otherwise they are auto-detected from .claude/, .cursor/,',
-    'and .codex/ (all are written when nothing is detected).',
+    'project, plus tool-specific templates. Known tools: claude, cursor, codex (full',
+    'MCP/hook gates) and windsurf, cline, copilot, kiro (instruction-tier rule files',
+    'derived from the same contract; Gemini CLI needs no template — it reads AGENTS.md).',
+    'Pass --tools to pick which tool configs to write; otherwise they are auto-detected',
+    'from their config directories (.claude/, .cursor/, .codex/, .windsurf/, .clinerules/,',
+    '.kiro/; copilot is explicit-only). claude+cursor+codex are written when nothing is',
+    'detected.',
     '',
     'Generate a starter 11-layer config:',
     '  ark-check --print-config eleven-layer > ark.config.json',
@@ -192,6 +199,9 @@ function detectConfig(root) {
       name: entry.layer,
       patterns: directories.map((directory) => `${normalize(path.join(srcDir, directory))}/**`),
       intentPrefixes: entry.prefixes,
+      ...(entry.layer === 'DomainModel'
+        ? { forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS }
+        : {}),
     });
   }
 
@@ -415,6 +425,25 @@ args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
 `;
 }
 
+/**
+ * Compact always-on rule for instruction-tier hosts (Windsurf, Cline, GitHub Copilot,
+ * Kiro, ...): agents that read a project rule file but have no MCP tools or hooks.
+ * Derived from the same AGENT_CONTRACT as AGENTS.md and the Cursor rule so the steps
+ * can never drift; points at AGENTS.md for the full placement table.
+ */
+function instructionRule() {
+  const steps = AGENT_CONTRACT.steps.map((step, index) => `${index + 1}. ${step}`).join('\n');
+  return `# Ark architecture contract
+
+This project's architecture is governed by Ark (\`ark.config.json\` is authoritative).
+Before writing or editing TypeScript or JavaScript source files:
+
+${steps}
+
+See \`AGENTS.md\` for the full contract and the layer placement table.
+`;
+}
+
 function cursorRule() {
   return `---
 description: Ark architecture contract
@@ -460,6 +489,20 @@ ${setupSteps ? `${setupSteps}\n` : ''}      - run: ${pm.install}
 function claudeSettings() {
   return `${JSON.stringify({
     hooks: {
+      // Inject the contract at session start so the agent knows the architecture from
+      // the first token. Project-scoped by design; --session-context is also a silent
+      // no-op when no ark.config.json exists, so it can never leak into other projects.
+      SessionStart: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command:
+                'npx ark-mcp --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json',
+            },
+          ],
+        },
+      ],
       PreToolUse: [
         {
           matcher: 'Write|Edit|MultiEdit',
@@ -484,10 +527,17 @@ function resolveTools(args) {
   const detected = new Set();
   if (fs.existsSync(path.join(root, '.claude'))) detected.add('claude');
   if (fs.existsSync(path.join(root, '.cursor'))) detected.add('cursor');
-  if (fs.existsSync(path.join(root, '.codex'))) {
-    detected.add('codex');
+  if (fs.existsSync(path.join(root, '.codex'))) detected.add('codex');
+  if (fs.existsSync(path.join(root, '.windsurf'))) detected.add('windsurf');
+  // .clinerules can also be a single FILE (older Cline convention); only a directory
+  // can receive .clinerules/ark.md, so a file must not trigger detection.
+  if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
+    detected.add('cline');
   }
-  // No signal at all: fall back to writing every tool's templates so a fresh
+  if (fs.existsSync(path.join(root, '.kiro'))) detected.add('kiro');
+  // copilot has no reliable directory signal (.github exists in most repos),
+  // so it is explicit-only via --tools.
+  // No signal at all: fall back to writing the primary tools' templates so a fresh
   // project still gets a complete, reviewable starter set.
   if (detected.size === 0) {
     return new Set(['claude', 'cursor', 'codex']);
@@ -495,7 +545,7 @@ function resolveTools(args) {
   return detected;
 }
 
-const KNOWN_TOOLS = ['claude', 'cursor', 'codex'];
+const KNOWN_TOOLS = ['claude', 'cursor', 'codex', 'windsurf', 'cline', 'copilot', 'kiro'];
 
 function runInstallAgentGates(args) {
   const root = args.root;
@@ -529,6 +579,19 @@ function runInstallAgentGates(args) {
   if (tools.has('codex')) {
     templates.push(['docs/ark-codex-config.toml', codexTomlSnippet()]);
   }
+  // Instruction-tier hosts: one shared rule text, host-specific path.
+  if (tools.has('windsurf')) {
+    templates.push(['.windsurf/rules/ark.md', instructionRule()]);
+  }
+  if (tools.has('cline')) {
+    templates.push(['.clinerules/ark.md', instructionRule()]);
+  }
+  if (tools.has('copilot')) {
+    templates.push(['.github/copilot-instructions.md', instructionRule()]);
+  }
+  if (tools.has('kiro')) {
+    templates.push(['.kiro/steering/ark.md', instructionRule()]);
+  }
 
   const results = templates.map(([relativePath, content]) =>
     writeTemplate(root, relativePath, content, args.force)
@@ -652,6 +715,20 @@ function collectConfigWarnings(root, config, files, rules, manifest) {
     if (seenLayers.has(layer.name)) duplicateLayers.add(layer.name);
     seenLayers.add(layer.name);
 
+    if (
+      layer.forbiddenGlobals !== undefined &&
+      (!Array.isArray(layer.forbiddenGlobals) ||
+        layer.forbiddenGlobals.some((entry) => typeof entry !== 'string'))
+    ) {
+      warnings.push(
+        configWarning(
+          'CONFIG_INVALID_FORBIDDEN_GLOBALS',
+          `Layer "${layer.name}" has an invalid forbiddenGlobals value; expected an array of strings (e.g. ["fetch", "Date.now"]). The entry is ignored.`,
+          { layer: layer.name }
+        )
+      );
+    }
+
     const patterns = Array.isArray(layer.patterns) ? layer.patterns : [];
     if (patterns.length === 0) {
       warnings.push(
@@ -931,7 +1008,7 @@ function publishHasSource(ts, node) {
   );
 }
 
-// ponytail: baseline keys exclude the line number so unrelated edits that shift lines
+// Baseline keys exclude the line number so unrelated edits that shift lines
 // don't resurrect frozen violations; the trade-off is that N identical violations in one
 // file collapse to one key.
 function baselineKey(violation) {
@@ -981,6 +1058,8 @@ const FIX_HINTS = {
     'Add metadata.source (the publishing intent name) to the publish call.',
   PUBLISH_SOURCE_LAYER_MISMATCH:
     'Use a source intent that belongs to the same layer as the publishing file, or move the file.',
+  FORBIDDEN_GLOBAL:
+    'Inject the capability through a port (e.g. a Clock, IdGenerator, or HttpPort) instead of reaching for the ambient global.',
 };
 
 function printViolation(violation) {
@@ -1093,6 +1172,21 @@ async function main() {
     const sourceLayer = layerForFile(root, file, config.layers);
     if (!sourceLayer) continue;
 
+    const layerConfig = config.layers.find((layer) => layer.name === sourceLayer);
+    const forbiddenGlobals = Array.isArray(layerConfig?.forbiddenGlobals)
+      ? layerConfig.forbiddenGlobals.filter((entry) => typeof entry === 'string')
+      : [];
+    for (const use of collectForbiddenGlobalUses(ts, sourceFile, forbiddenGlobals)) {
+      violations.push({
+        ruleId: 'FORBIDDEN_GLOBAL',
+        file: normalize(path.relative(root, file)),
+        line: lineOf(sourceFile, use.node.getStart(sourceFile)),
+        fromLayer: sourceLayer,
+        target: use.name,
+        message: `${sourceLayer} must not use the ambient global "${use.name}".`,
+      });
+    }
+
     const checkModuleEdge = (specifier, node, kind) => {
       const target = resolveImport(ts, specifier, file, compilerOptions, moduleHost, root);
       const targetLayer = target ? layerForFile(root, target, config.layers) : undefined;

package/bin/ark-mcp.mjs

@@ -21,6 +21,11 @@
  * stdin, validates the file content a Write/Edit/MultiEdit is about to produce, and exits
  * 2 with the violations on stderr when the write must be blocked (0 otherwise). This is
  * the copy-paste integration for agent runtimes whose hooks run shell commands.
+ *
+ * --session-context runs one-shot and prints a compact contract summary (layers, rule
+ * count, forbidden globals, baseline state, check command) to stdout. Bind it to a
+ * SessionStart hook so the agent has the architecture in context from the first token,
+ * instead of learning it by rejection.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -39,10 +44,12 @@ function parseArgs(argv) {
     configExplicit: false,
     manifest: undefined,
     hook: false,
+    sessionContext: false,
   };
   for (let i = 2; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--hook') args.hook = true;
+    else if (a === '--session-context') args.sessionContext = true;
     else if (a === '--root') args.root = path.resolve(argv[++i]);
     else if (a === '--config') {
       args.config = argv[++i];
@@ -168,7 +175,27 @@ function runHook(gate, config, args) {
   const result = gate.validate(source, { layer, filePath });
   if (result.valid) return;
 
-  const lines = result.violations.map(
+  // Ratchet semantics (same philosophy as ark-check --baseline): an edit is blocked only
+  // when it ADDS violations relative to the file's current on-disk state. Otherwise a
+  // pre-existing violation — frozen in a baseline or predating Ark adoption — would make
+  // every subsequent edit to that file un-writable while CI passes. Keys ignore line
+  // numbers (edits shift them) and collapse duplicates, mirroring ark-check's baselineKey.
+  const violationKey = (violation) => `${violation.ruleId}|${violation.target ?? violation.message}`;
+  let existingKeys = new Set();
+  try {
+    const current = fs.readFileSync(filePath, 'utf8');
+    existingKeys = new Set(
+      gate.validate(current, { layer, filePath }).violations.map(violationKey)
+    );
+  } catch {
+    // New file: nothing pre-exists, every violation is new.
+  }
+  const newViolations = result.violations.filter(
+    (violation) => !existingKeys.has(violationKey(violation))
+  );
+  if (newViolations.length === 0) return;
+
+  const lines = newViolations.map(
     (violation) =>
       `- [${violation.ruleId}] ${violation.message}${violation.line ? ` (line ${violation.line})` : ''}`
   );
@@ -182,12 +209,65 @@ function runHook(gate, config, args) {
   process.exitCode = 2;
 }
 
+/**
+ * One-shot SessionStart context: a compact summary of the contract on stdout so the
+ * agent starts the session already knowing the architecture. Advisory — never blocks
+ * and never exits non-zero for missing optional inputs (e.g. no baseline file).
+ */
+function printSessionContext(config, profile, forbiddenGlobals, args) {
+  const lines = ['Ark architecture contract governs this project (ark.config.json is authoritative).'];
+
+  const configLayers = Array.isArray(config.layers) ? config.layers : [];
+  if (configLayers.length > 0) {
+    lines.push('Layers:');
+    for (const layer of configLayers) {
+      const globals = forbiddenGlobals[layer.name];
+      const globalsNote = globals ? ` — forbidden globals: ${globals.join(', ')}` : '';
+      lines.push(`  - ${layer.name}: ${(layer.patterns ?? []).join(', ')}${globalsNote}`);
+    }
+  } else {
+    lines.push(
+      `Layers: none configured — the default 11-layer profile applies to intent references.`
+    );
+  }
+
+  const denied = (profile.rules ?? []).filter((rule) => !rule.allowed).length;
+  lines.push(
+    `Rules: ${denied} denied layer edge(s). Full contract: ark://manifest MCP resource.`
+  );
+
+  // Advisory output: a malformed baseline must not abort the summary.
+  let baseline;
+  try {
+    baseline = readJson(path.join(args.root, '.ark-baseline.json'));
+  } catch {
+    baseline = undefined;
+  }
+  if (Array.isArray(baseline?.violations)) {
+    lines.push(
+      `Baseline: ${baseline.violations.length} frozen violation(s) — only NEW violations fail; do not add to them.`
+    );
+  }
+
+  lines.push('After edits run: npx ark-check --root . --config ark.config.json --strict-config');
+  lines.push('If Ark reports violations, fix the architecture instead of weakening the gate.');
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
 async function main() {
   const args = parseArgs(process.argv);
+  const configPath = resolveInRoot(args.root, args.config);
+
+  // SessionStart contract injection is only meaningful in Ark-governed projects. Bail
+  // out silently (before loading dist) when there is no config, so the hook is safe
+  // even if a user installs it in their GLOBAL settings instead of per-project.
+  if (args.sessionContext && !(configPath && fs.existsSync(configPath))) {
+    return;
+  }
+
   const ark = await loadArk();
   const ts = await loadOptionalTypeScript();
 
-  const configPath = resolveInRoot(args.root, args.config);
   const config =
     (configPath ? readJson(configPath, { required: args.configExplicit }) : undefined) ?? {
       include: ['src'],
@@ -248,11 +328,28 @@ async function main() {
     });
   }
 
+  // Layer → forbidden ambient globals, straight from ark.config.json. Enforced by the
+  // gate only when the target file's layer is known (same data ark-check enforces in CI).
+  const forbiddenGlobals = Object.fromEntries(
+    configLayers
+      .filter(
+        (layer) =>
+          layer.name &&
+          Array.isArray(layer.forbiddenGlobals) &&
+          layer.forbiddenGlobals.some((entry) => typeof entry === 'string')
+      )
+      .map((layer) => [
+        layer.name,
+        layer.forbiddenGlobals.filter((entry) => typeof entry === 'string'),
+      ])
+  );
+
   const gate = ark.createAICodeGate({
     architectureProfile: profile,
     intents,
     enforceIntentAllowlist: intents.length > 0,
     typescript: ts,
+    forbiddenGlobals,
   });
 
   if (args.hook) {
@@ -260,6 +357,11 @@ async function main() {
     return;
   }
 
+  if (args.sessionContext) {
+    printSessionContext(config, profile, forbiddenGlobals, args);
+    return;
+  }
+
   const SERVER_INFO = { name: 'ark-runtime-kernel', version: ark.version };
   const DEFAULT_PROTOCOL = '2024-11-05';
 
@@ -342,6 +444,7 @@ async function main() {
         name: profile.name,
         layers: profile.layers,
         rules: profile.rules,
+        ...(Object.keys(forbiddenGlobals).length > 0 ? { forbiddenGlobals } : {}),
         ...(suggestions.length > 0
           ? {
               suggestedLayers: suggestions,

package/bin/ark-shared.mjs

@@ -69,6 +69,13 @@ export const DEFAULT_RULES = createStrictDenyRules(
   DEFAULT_ALLOWED_FLOWS
 );
 
+/**
+ * Default ambient globals forbidden in the domain layer: a pure domain does no I/O and is
+ * deterministic. `console` is deliberately omitted (too common during adoption); add it per
+ * project via the layer's `forbiddenGlobals` in ark.config.json.
+ */
+export const DEFAULT_DOMAIN_FORBIDDEN_GLOBALS = ['fetch', 'process', 'Date.now', 'Math.random'];
+
 export function createElevenLayerConfig(options = {}) {
   const rootDir = options.rootDir ?? 'src';
   const optional = options.optionalLayers ?? true;
@@ -82,11 +89,55 @@ export function createElevenLayerConfig(options = {}) {
       ),
       intentPrefixes: entry.prefixes,
       optional,
+      ...(entry.layer === 'DomainModel'
+        ? { forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS }
+        : {}),
     })),
     rules: DEFAULT_RULES,
   };
 }
 
+/**
+ * Find uses of forbidden ambient globals in a TypeScript source file.
+ *
+ * Detection is deliberately positional, not scope-aware (kept in sync with
+ * `collectForbiddenGlobalUses` in src/kernel/ai-gate/AICodeGate.ts — the CLIs must not
+ * import from dist):
+ *   - a dotted entry ("Date.now") flags `Date.now` property accesses
+ *   - a bare entry ("console", "fetch") flags property accesses on it (`console.log`),
+ *     direct calls (`fetch(...)`), and constructions (`new WebSocket(...)`)
+ * Bare identifier mentions in other positions (types, shadowed locals, import names) are
+ * NOT flagged, trading a little recall for near-zero false positives without a type checker.
+ *
+ * Returns [{ name, node }] where `name` is the matched forbidden entry.
+ */
+export function collectForbiddenGlobalUses(ts, sourceFile, forbidden) {
+  const entries = new Set(forbidden ?? []);
+  if (entries.size === 0) return [];
+  const uses = [];
+
+  const visit = (node) => {
+    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression)) {
+      const dotted = `${node.expression.text}.${node.name.text}`;
+      if (entries.has(dotted)) {
+        uses.push({ name: dotted, node });
+      } else if (entries.has(node.expression.text)) {
+        uses.push({ name: node.expression.text, node });
+      }
+    } else if (
+      (ts.isCallExpression(node) || ts.isNewExpression(node)) &&
+      node.expression &&
+      ts.isIdentifier(node.expression) &&
+      entries.has(node.expression.text)
+    ) {
+      uses.push({ name: node.expression.text, node });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return uses;
+}
+
 const _regexpCache = new Map();
 
 function escapeLiteral(ch) {

package/dist/eslint/index.cjs

@@ -122,10 +122,57 @@ var requirePublishSource = {
     };
   }
 };
+var DEFAULT_FORBIDDEN_GLOBALS = ["fetch", "process", "Date.now", "Math.random"];
+var noForbiddenGlobals = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: 'Disallow ambient globals (e.g. fetch, Date.now) in architecture-governed code; scope the rule to layer directories via ESLint "files" patterns.'
+    },
+    messages: {
+      forbiddenGlobal: 'Ambient global "{{name}}" is forbidden here; inject the capability through a port instead.'
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          globals: { type: "array", items: { type: "string" } }
+        },
+        additionalProperties: false
+      }
+    ]
+  },
+  create(context) {
+    const option = context.options?.[0];
+    const globals = new Set(option?.globals ?? DEFAULT_FORBIDDEN_GLOBALS);
+    const report = (node, name) => context.report({ node, messageId: "forbiddenGlobal", data: { name } });
+    return {
+      // Same positional detection as ark-check's FORBIDDEN_GLOBAL: property accesses on a
+      // forbidden base (console.log, Date.now), direct calls, and constructions. Bare
+      // identifier mentions elsewhere are not flagged (avoids shadowed-local false positives).
+      MemberExpression(node) {
+        const base = node.object?.type === "Identifier" ? node.object.name : void 0;
+        if (!base) return;
+        const dotted = `${base}.${propertyName(node.property) ?? ""}`;
+        if (globals.has(dotted)) report(node, dotted);
+        else if (globals.has(base)) report(node, base);
+      },
+      CallExpression(node) {
+        const callee = node.callee?.type === "Identifier" ? node.callee.name : void 0;
+        if (callee && globals.has(callee)) report(node, callee);
+      },
+      NewExpression(node) {
+        const callee = node.callee?.type === "Identifier" ? node.callee.name : void 0;
+        if (callee && globals.has(callee)) report(node, callee);
+      }
+    };
+  }
+};
 var rules = {
   "no-domain-infra-imports": noDomainInfraImports,
   "no-raw-event-publish": noRawEventPublish,
-  "require-publish-source": requirePublishSource
+  "require-publish-source": requirePublishSource,
+  "no-forbidden-globals": noForbiddenGlobals
 };
 var plugin = { rules };
 plugin.configs = {
@@ -142,6 +189,7 @@ var eslint_default = plugin;
 
 exports.default = eslint_default;
 exports.noDomainInfraImports = noDomainInfraImports;
+exports.noForbiddenGlobals = noForbiddenGlobals;
 exports.noRawEventPublish = noRawEventPublish;
 exports.plugin = plugin;
 exports.requirePublishSource = requirePublishSource;