ark-runtime-kernel 1.2.0 → 1.4.0

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,
@@ -21,8 +23,10 @@ function parseArgs(argv) {
     tsconfig: undefined,
     json: false,
     strictConfig: false,
+    requireGates: false,
     init: false,
     installAgentGates: false,
+    tools: undefined,
     force: false,
     baseline: undefined,
     updateBaseline: false,
@@ -31,8 +35,23 @@ function parseArgs(argv) {
     const arg = argv[i];
     if (arg === '--json') args.json = true;
     else if (arg === '--strict-config') args.strictConfig = true;
+    else if (arg === '--require-gates') args.requireGates = true;
     else if (arg === '--init') args.init = true;
     else if (arg === '--install-agent-gates') args.installAgentGates = true;
+    else if (arg === '--tools') {
+      // Consume the next arg only when it isn't another flag (same rule as --baseline),
+      // so `--tools --force` can't silently eat --force as a "tool name".
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        i += 1;
+        args.tools = next
+          .split(',')
+          .map((tool) => tool.trim().toLowerCase())
+          .filter(Boolean);
+      } else {
+        args.tools = []; // flag without a value — rejected in runInstallAgentGates
+      }
+    }
     else if (arg === '--force') args.force = true;
     else if (arg === '--baseline' || arg === '--update-baseline') {
       if (arg === '--update-baseline') args.updateBaseline = true;
@@ -52,9 +71,9 @@ function parseArgs(argv) {
 
 function usage() {
   return [
-    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--json] [--baseline [file]]',
+    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--require-gates] [--json] [--baseline [file]]',
     '       ark-check --init [--force]',
-    '       ark-check --install-agent-gates [--force]',
+    '       ark-check --install-agent-gates [--tools claude,cursor,codex] [--force]',
     '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
     '       ark-check --print-config eleven-layer',
     '',
@@ -65,6 +84,10 @@ function usage() {
     '--init scans the project for the built-in layer directory conventions (src/domain,',
     'src/application, src/adapters/persistence, ...) and writes an ark.config.json covering',
     'only the layers that actually exist, with the default rules filtered to those layers.',
+    'Undetected profile layers are printed as suggestions with their conventional',
+    'directories. When nothing is detected, the full 11-layer starter profile is written',
+    'instead (all layers optional, anchored at src/), so the strict check passes today and',
+    'each layer starts being enforced as soon as its directory gains source files.',
     '',
     'Resolves relative, tsconfig path-alias, and package imports via the TypeScript',
     'module resolver, then checks each resolved cross-layer import against the rules.',
@@ -75,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 }]',
     '}',
@@ -83,6 +107,19 @@ function usage() {
     'Config warnings are advisory by default and are included in JSON output.',
     'Use --strict-config to make config warnings fail the check.',
     '',
+    '--require-gates fails the check when AGENTS.md, .mcp.json, or the generated CI',
+    'workflow is missing, so "installed but never configured" is a red CI. Combine it',
+    '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. 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',
     '',
@@ -95,6 +132,35 @@ function readJson(file) {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
+function readPackageJson(root) {
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) return null;
+  return readJson(file);
+}
+
+function hasCheckArchitectureScript(root) {
+  const pkg = readPackageJson(root);
+  return Boolean(pkg?.scripts?.['check:architecture']);
+}
+
+const REQUIRED_GATE_FILES = [
+  'AGENTS.md',
+  '.mcp.json',
+  '.github/workflows/ark-check.yml',
+];
+
+function missingGates(root) {
+  return REQUIRED_GATE_FILES.filter(
+    (relativePath) => !fs.existsSync(path.join(root, relativePath))
+  );
+}
+
+function checkArchitectureScriptSnippet() {
+  // npx resolves the installed package binary; `node bin/ark-check.mjs` only works
+  // inside Ark's own repo.
+  return '"check:architecture": "npx ark-check --root . --config ark.config.json --strict-config"';
+}
+
 function readConfig(root, configPath) {
   const fullPath = path.isAbsolute(configPath)
     ? configPath
@@ -133,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 }
+        : {}),
     });
   }
 
@@ -176,39 +245,71 @@ function runInit(args) {
   }
 
   const { srcDir, config } = detectConfig(args.root);
-  if (config.layers.length === 0) {
-    console.error(
-      [
-        'No conventional layer directories found (looked for src/domain, src/application,',
-        'src/adapters/persistence, ...). Generate the full template instead and adapt the',
-        'patterns to your layout:',
-        '  ark-check --print-config eleven-layer > ark.config.json',
-      ].join('\n')
-    );
-    process.exitCode = 1;
-    return;
-  }
+  const greenfield = config.layers.length === 0;
+  // Greenfield: anchor the starter profile at src/ (the convention a fresh project will
+  // scaffold under) even when src/ doesn't exist yet — the layers are optional, so the
+  // check passes today and governance switches on the moment src/domain/ etc. appear.
+  const finalConfig = greenfield
+    ? createElevenLayerConfig({ rootDir: srcDir === '.' ? 'src' : srcDir })
+    : config;
 
-  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+  fs.writeFileSync(configPath, `${JSON.stringify(finalConfig, null, 2)}\n`);
 
   console.log(`Wrote ${configPath}`);
   console.log('');
-  console.log('Detected layers:');
-  for (const layer of config.layers) {
-    console.log(`  ${layer.name}: ${layer.patterns.join(', ')}`);
-  }
-  const uncovered = uncoveredDirectories(args.root, srcDir, config.layers);
-  if (uncovered.length > 0) {
-    console.log('');
-    console.log(
-      `Not covered by any layer (add patterns for these or they stay ungoverned): ${uncovered.join(', ')}`
-    );
+  if (greenfield) {
+    console.log('No conventional layer directories found — generated the full 11-layer starter');
+    console.log('profile instead. Every layer is marked optional, so the strict check passes now');
+    console.log('and each layer starts being enforced as soon as its directory gains source files:');
+    for (const layer of finalConfig.layers) {
+      console.log(`  ${layer.name}: ${layer.patterns.join(', ')}`);
+    }
+    // The starter profile only governs src/. Existing source elsewhere would make the
+    // gate silently green, so surface it instead of pretending the project is covered.
+    const outside = walk(args.root)
+      .map((file) => normalize(path.relative(args.root, file)))
+      .filter((rel) => !rel.startsWith('src/') && !rel.split('/').some((s) => s.startsWith('.')));
+    if (outside.length > 0) {
+      console.log('');
+      console.log(`WARNING: ${outside.length} source file(s) live outside src/ and are NOT governed`);
+      console.log(`by this config (e.g. ${outside.slice(0, 3).join(', ')}).`);
+      console.log('Move them under src/, or edit the "include" and layer patterns to match your layout.');
+    }
+  } else {
+    console.log('Detected layers:');
+    for (const layer of finalConfig.layers) {
+      console.log(`  ${layer.name}: ${layer.patterns.join(', ')}`);
+    }
+    const detected = new Set(finalConfig.layers.map((layer) => layer.name));
+    const suggested = DEFAULT_INTENT_PREFIXES.filter((entry) => !detected.has(entry.layer));
+    if (suggested.length > 0) {
+      console.log('');
+      console.log('Suggested layers from the 11-layer profile (not detected — conventional');
+      console.log('directories shown; create one and re-run --init, or add the layer by hand):');
+      for (const entry of suggested) {
+        const dirs = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? [])
+          .map((directory) => `${srcDir}/${directory}`)
+          .join(', ');
+        console.log(`  ${entry.layer}: ${dirs}`);
+      }
+    }
+    const uncovered = uncoveredDirectories(args.root, srcDir, finalConfig.layers);
+    if (uncovered.length > 0) {
+      console.log('');
+      console.log(
+        `Not covered by any layer (add patterns for these or they stay ungoverned): ${uncovered.join(', ')}`
+      );
+    }
   }
   console.log('');
   console.log('Next steps:');
   console.log('  1. CI gate:        npx ark-check --root . --config ark.config.json --strict-config');
   console.log('  2. AI write gate:  npx ark-mcp --root . --config ark.config.json');
   console.log('     (bind its validate_code tool to your agent\'s pre-write hook — see README)');
+  if (!hasCheckArchitectureScript(args.root)) {
+    console.log('  3. Add the npm alias if you want `npm run check:architecture`:');
+    console.log(`     ${checkArchitectureScriptSnippet()}`);
+  }
 }
 
 function ensureDirForFile(file) {
@@ -220,9 +321,13 @@ function writeTemplate(root, relativePath, content, force) {
   if (fs.existsSync(fullPath) && !force) {
     return { relativePath, status: 'skipped' };
   }
-  ensureDirForFile(fullPath);
-  fs.writeFileSync(fullPath, content);
-  return { relativePath, status: fs.existsSync(fullPath) ? 'written' : 'written' };
+  try {
+    ensureDirForFile(fullPath);
+    fs.writeFileSync(fullPath, content);
+    return { relativePath, status: 'written' };
+  } catch {
+    return { relativePath, status: 'failed' };
+  }
 }
 
 function packageManager(root) {
@@ -231,7 +336,7 @@ function packageManager(root) {
       cache: 'pnpm',
       setup: ['corepack enable'],
       install: 'pnpm install --frozen-lockfile',
-      run: 'pnpm exec ark-check --root . --config ark.config.json --strict-config',
+      run: 'pnpm exec ark-check --root . --config ark.config.json --strict-config --require-gates',
     };
   }
   if (fs.existsSync(path.join(root, 'yarn.lock'))) {
@@ -239,27 +344,63 @@ function packageManager(root) {
       cache: 'yarn',
       setup: ['corepack enable'],
       install: 'yarn install --frozen-lockfile',
-      run: 'yarn ark-check --root . --config ark.config.json --strict-config',
+      run: 'yarn ark-check --root . --config ark.config.json --strict-config --require-gates',
     };
   }
   return {
     cache: 'npm',
     setup: [],
     install: fs.existsSync(path.join(root, 'package-lock.json')) ? 'npm ci' : 'npm install',
-    run: 'npx ark-check --root . --config ark.config.json --strict-config',
+    run: 'npx ark-check --root . --config ark.config.json --strict-config --require-gates',
   };
 }
 
+const ARK_CHECK_COMMAND = 'npx ark-check --root . --config ark.config.json --strict-config';
+
+// Canonical agent contract. AGENTS.md and the Cursor rule both derive from this
+// single source so the steps can never drift out of sync between the two files.
+const AGENT_CONTRACT = {
+  manifestResource: 'ark://manifest',
+  steps: [
+    `Read the Ark contract from \`ark://manifest\` when the MCP server is available.`,
+    `Keep source files inside the layer boundaries declared in \`ark.config.json\`.`,
+    `Do not bypass Ark publishers, event contracts, or source metadata for runtime mutations.`,
+    `After edits, run \`${ARK_CHECK_COMMAND}\`.`,
+    `If Ark reports violations, fix the architecture instead of weakening the gate.`,
+  ],
+  // Cursor-only guidance: the write-time validate_code tool is available in
+  // Cursor's runtime but has no equivalent in a plain AGENTS.md read.
+  cursorValidateStep: `Validate the full post-edit file content with the \`validate_code\` tool before writing whenever your runtime supports it.`,
+};
+
+function layerPlacementTable() {
+  const rows = DEFAULT_INTENT_PREFIXES.map((entry) => {
+    const dirs = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? [])
+      .map((directory) => `\`${directory}/\``)
+      .join(', ');
+    return `| ${entry.layer} | ${dirs} | ${entry.prefixes.map((p) => `\`${p}\``).join(', ')} |`;
+  }).join('\n');
+  return `| Layer | Conventional directories (under the source root) | Intent prefixes |
+|-------|---------------------------------------------------|-----------------|
+${rows}`;
+}
+
 function agentInstructions() {
+  const steps = AGENT_CONTRACT.steps.map((step, index) => `${index + 1}. ${step}`).join('\n');
   return `# Ark Enforcement
 
 Before editing TypeScript or JavaScript source files:
 
-1. Read the Ark contract from \`ark://manifest\` when the MCP server is available.
-2. Keep source files inside the layer boundaries declared in \`ark.config.json\`.
-3. Do not bypass Ark publishers, event contracts, or source metadata for runtime mutations.
-4. After edits, run \`npx ark-check --root . --config ark.config.json --strict-config\`.
-5. If Ark reports violations, fix the architecture instead of weakening the gate.
+${steps}
+
+## Where new code belongs
+
+\`ark.config.json\` is authoritative for this project. When creating a NEW kind of code
+that no existing layer covers (a saga, a background job, a read model, ...), use the
+default 11-layer placement below and add the layer to \`ark.config.json\` — do not invent
+an ungoverned location:
+
+${layerPlacementTable()}
 
 The project is only considered Ark-enforced when the write gate, CI gate, and runtime path all pass.
 `;
@@ -284,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
@@ -291,13 +451,12 @@ alwaysApply: true
 ---
 
 Before writing or editing TypeScript or JavaScript source files, read the
-\`ark://manifest\` resource from the \`ark\` MCP server when available.
+\`${AGENT_CONTRACT.manifestResource}\` resource from the \`ark\` MCP server when available.
 
-Validate the full post-edit file content with the \`validate_code\` tool before
-writing whenever your runtime supports it. After edits, run:
+${AGENT_CONTRACT.cursorValidateStep} After edits, run:
 
 \`\`\`bash
-npx ark-check --root . --config ark.config.json --strict-config
+${ARK_CHECK_COMMAND}
 \`\`\`
 
 If Ark reports violations, fix the architecture instead of bypassing the gate.
@@ -330,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',
@@ -346,18 +519,79 @@ function claudeSettings() {
   }, null, 2)}\n`;
 }
 
+function resolveTools(args) {
+  if (args.tools && args.tools.length > 0) {
+    return new Set(args.tools);
+  }
+  const root = args.root;
+  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, '.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');
+  }
+  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']);
+  }
+  return detected;
+}
+
+const KNOWN_TOOLS = ['claude', 'cursor', 'codex', 'windsurf', 'cline', 'copilot', 'kiro'];
+
 function runInstallAgentGates(args) {
   const root = args.root;
+  if (args.tools) {
+    const unknown = args.tools.filter((tool) => !KNOWN_TOOLS.includes(tool));
+    if (args.tools.length === 0 || unknown.length > 0) {
+      console.error(
+        `--tools expects a comma-separated subset of: ${KNOWN_TOOLS.join(', ')}` +
+          (unknown.length > 0 ? ` (unknown: ${unknown.join(', ')})` : '')
+      );
+      process.exitCode = 2;
+      return;
+    }
+  }
   const pm = packageManager(root);
+  const hasCheckScript = hasCheckArchitectureScript(root);
+  const tools = resolveTools(args);
   const templates = [
+    // Base gates: tool-agnostic contract + CI backstop, always written.
     ['AGENTS.md', agentInstructions()],
     ['.mcp.json', mcpJson()],
-    ['.cursor/mcp.json', mcpJson()],
-    ['.cursor/rules/ark.mdc', cursorRule()],
-    ['.claude/settings.json', claudeSettings()],
     ['.github/workflows/ark-check.yml', githubWorkflow(pm)],
-    ['docs/ark-codex-config.toml', codexTomlSnippet()],
   ];
+  if (tools.has('cursor')) {
+    templates.push(['.cursor/mcp.json', mcpJson()]);
+    templates.push(['.cursor/rules/ark.mdc', cursorRule()]);
+  }
+  if (tools.has('claude')) {
+    templates.push(['.claude/settings.json', claudeSettings()]);
+  }
+  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)
@@ -365,14 +599,27 @@ function runInstallAgentGates(args) {
 
   console.log('Ark agent gate templates:');
   for (const result of results) {
-    const marker = result.status === 'written' ? 'wrote' : 'skipped';
+    const marker =
+      result.status === 'written' ? 'wrote' : result.status === 'failed' ? 'FAILED' : 'skipped';
     console.log(`  ${marker.padEnd(7)} ${result.relativePath}`);
   }
+  const failed = results.filter((result) => result.status === 'failed');
+  if (failed.length > 0) {
+    console.error(`\nFailed to write ${failed.length} template(s).`);
+    process.exitCode = 1;
+    return;
+  }
   console.log('');
   console.log('Next steps:');
   console.log('  1. Review the generated files and commit the ones that match your tools.');
   console.log('  2. Run: npx ark-check --root . --config ark.config.json --strict-config');
-  console.log('  3. Wire Codex manually from docs/ark-codex-config.toml if your host uses ~/.codex/config.toml.');
+  if (!hasCheckScript) {
+    console.log('  3. Add the npm alias if you want `npm run check:architecture`:');
+    console.log(`     ${checkArchitectureScriptSnippet()}`);
+    console.log('  4. If you use Codex in this project, wire it now so `ark://manifest` is available from the first edit.');
+  } else {
+    console.log('  3. If you use Codex in this project, wire it now so `ark://manifest` is available from the first edit.');
+  }
 }
 
 function readManifest(root, manifestPath) {
@@ -468,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(
@@ -747,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) {
@@ -797,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) {
@@ -854,6 +1117,35 @@ async function main() {
     return;
   }
 
+  if (args.requireGates) {
+    const missing = missingGates(args.root);
+    if (missing.length > 0) {
+      const payload = {
+        ok: false,
+        error: 'missing-gates',
+        missing,
+      };
+      if (args.json) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else {
+        console.error('Ark gates are not installed. Missing:');
+        for (const relativePath of missing) {
+          console.error(`  - ${relativePath}`);
+        }
+        console.error('\nRun `npx ark init` (or `ark-check --install-agent-gates`) to configure enforcement.');
+      }
+      process.exitCode = 1;
+      return;
+    }
+    // Gates present. This is a precondition, not a standalone report: stay quiet
+    // in --json mode so the architecture check below owns the single JSON output.
+    // When --require-gates is the only intent (no config/architecture run needed),
+    // callers still get a clear signal from the exit code and the human-mode line.
+    if (!args.json) {
+      console.log('Ark gates present: ' + REQUIRED_GATE_FILES.join(', '));
+    }
+  }
+
   let ts;
   try {
     ts = await import('typescript');
@@ -880,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;