arkgate 2.11.0 → 2.13.0

package/bin/ark-check.mjs

@@ -33,6 +33,7 @@ import {
   loadTypeScript,
   detectSkillGaps,
   detectCodexHomeGap,
+  detectActiveAgentHost,
   missingGates,
   staleRunnerGateFiles,
   brokenMcpGateFiles,
@@ -56,6 +57,7 @@ import {
   reportsDir,
   readJsonSafe,
 } from './lib/html-report.mjs';
+import { shouldOpenHtmlReport, openHtmlInBrowser } from './lib/open-html.mjs';
 import {
   computeCoverage,
   runCoverage,
@@ -81,6 +83,7 @@ import {
 import {
   ARCHITECTURE_PRESETS,
 } from './lib/presets.mjs';
+import { loadArkConfigContract, parseArkConfigJson } from './lib/config-contract.mjs';
 
 import {
   collectGovernedFiles,
@@ -91,6 +94,7 @@ import {
   configWarning,
 } from './lib/config-warnings.mjs';
 import { runArchitectureScan } from './lib/architecture-scan.mjs';
+import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 
 
 function parseArgs(argv) {
@@ -101,9 +105,9 @@ function parseArgs(argv) {
     printConfig: undefined,
     tsconfig: undefined,
     json: false,
-    strict: false,
     strictConfig: false,
     requireGates: false,
+    requireWriteHook: undefined,
     init: false,
     installAgentGates: false,
     tools: undefined,
@@ -122,6 +126,8 @@ function parseArgs(argv) {
     applyPolicyPack: undefined,
     watch: false,
     beginner: false,
+    openReport: false,
+    noOpenReport: false,
     version: false,
     help: false,
   };
@@ -135,13 +141,15 @@ function parseArgs(argv) {
   for (let i = 2; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') args.json = true;
-    else if (arg === '--strict') {
-      args.strict = true;
+    else if (arg === '--strict' || arg === '--strict-merge') {
       args.strictConfig = true;
       args.requireGates = true;
     }
     else if (arg === '--strict-config') args.strictConfig = true;
     else if (arg === '--require-gates') args.requireGates = true;
+    else if (arg === '--require-write-hook') {
+      args.requireWriteHook = requireValue(arg, i++).trim().toLowerCase();
+    }
     else if (arg === '--init') args.init = true;
     else if (arg === '--preset') args.preset = requireValue(arg, i++);
     else if (arg === '--install-agent-gates') args.installAgentGates = true;
@@ -183,6 +191,8 @@ function parseArgs(argv) {
     }
     else if (arg === '--reset-origin') args.resetOrigin = true;
     else if (arg === '--no-archive') args.noArchive = true;
+    else if (arg === '--open') args.openReport = true;
+    else if (arg === '--no-open') args.noOpenReport = true;
     else if (arg === '--baseline' || arg === '--update-baseline') {
       if (arg === '--update-baseline') args.updateBaseline = true;
       // optional path value: consume the next arg only when it isn't another flag
@@ -214,7 +224,7 @@ function usage() {
   return [
     'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
     '       ark-check --version',
-    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict | --strict-config] [--require-gates] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
+    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
     '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
@@ -224,10 +234,11 @@ function usage() {
     '       ark-check --adopt-contract [--write]   expand include + UI patterns from ungoverned dirs (contract adopt)',
     '       ark-check --ratchet-cores              when raw graph is green (0 violations; baseline ignored), set optional:false on populated cores only (writes ark.config.json)',
     '       ark-check --watch                      re-run the check when governed files change (debounced)',
-    '       ark-check --report [file.html] [--beginner] [--reset-origin] [--no-archive]',
+    '       ark-check --report [file.html] [--beginner] [--reset-origin] [--no-archive] [--open|--no-open]',
     '           HTML report + snapshots under .ark/reports/ (origin once, latest each run, history JSON)',
+    '           Best-effort open in browser (local TTY). No-op if open fails. --no-open / ARK_NO_OPEN_REPORT=1 to skip; --open forces open.',
     '       ark-check --init [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|clean-architecture|onion-architecture] [--force]',
-    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok] [--skills-only] [--codex-home] [--force]',
+    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok] [--require-write-hook <host>] [--skills-only] [--codex-home] [--force]',
     '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
     '       ark-check --print-config eleven-layer',
     '',
@@ -267,8 +278,12 @@ function usage() {
     '',
     'Config warnings are advisory by default and are included in JSON output.',
     'Use --strict-config to make config warnings fail the check.',
-    'Use --strict for the fail-closed CI profile: --strict-config + --require-gates',
-    'plus the security diagnostics surfaced by doctor.',
+    'Use --strict-merge for the fail-closed CI profile: --strict-config + --require-gates',
+    'plus the security diagnostics surfaced by doctor. --strict is a compatibility alias.',
+    'This merge profile never depends on an editor/agent hook.',
+    'Add --require-write-hook claude|grok to validate a hard local write boundary for that',
+    'specific host. Cursor and Codex expose advisory MCP tools plus the shared CI check;',
+    'merge blocking requires repository policy to make that status required.',
     '',
     '--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',
@@ -276,7 +291,8 @@ function usage() {
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
     'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok',
-    '(full MCP/hook gates) and windsurf, cline, copilot, kiro, roo, continue, gemini',
+    '(Claude/Grok hard-write hooks; Cursor/Codex advisory MCP; shared CI check for all) and',
+    'windsurf, cline, copilot, kiro, roo, continue, gemini',
     '(instruction-tier rule files derived from the same contract).',
     'It also installs the /ark-* skills shipped in templates/skills/ into each',
     'detected tool\'s command location (.claude/skills/, .cursor/commands/,',
@@ -290,7 +306,7 @@ function usage() {
     'Pass --tools to pick which tool configs to write; otherwise they are auto-detected',
     'from their config directories (.claude/, .cursor/, .codex/, .grok/, .windsurf/,',
     '.clinerules/, .kiro/, .roo/, .continue/, .gemini/; copilot is explicit-only).',
-    'claude+cursor+codex are written when nothing is detected.',
+    'claude+cursor+codex+grok are written when nothing is detected.',
     '',
     'Generate a starter 11-layer config:',
     '  ark-check --print-config eleven-layer > ark.config.json',
@@ -305,25 +321,12 @@ function readConfig(root, configPath) {
     ? configPath
     : path.join(root, configPath);
   if (!fs.existsSync(fullPath)) {
-    return {
-      include: ['src'],
-      layers: [],
-      rules: DEFAULT_RULES,
-    };
+    return loadArkConfigContract(
+      { include: ['src'], layers: [], rules: DEFAULT_RULES },
+      fullPath
+    ).config;
   }
-  const raw = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-  return {
-    include: raw.include ?? ['src'],
-    layers: raw.layers ?? [],
-    rules: raw.rules ?? DEFAULT_RULES,
-    ...(raw.exclude ? { exclude: raw.exclude } : {}),
-    ...(raw.excludeGenerated !== undefined ? { excludeGenerated: raw.excludeGenerated } : {}),
-    ...(raw.cyclePolicy ? { cyclePolicy: raw.cyclePolicy } : {}),
-    ...(raw.dynamicImportAllowlist
-      ? { dynamicImportAllowlist: raw.dynamicImportAllowlist }
-      : {}),
-    ...(raw.safety ? { safety: raw.safety } : {}),
-  };
+  return parseArkConfigJson(fs.readFileSync(fullPath, 'utf8'), fullPath).config;
 }
 
 /**
@@ -976,16 +979,41 @@ async function main() {
     return;
   }
 
-  if (args.requireGates) {
-    const missing = missingGates(args.root);
-    if (args.strict && !detectWritePathCapabilities(args.root).hookPresent) {
-      missing.push('PreToolUse write hook');
+  if (args.requireGates || args.requireWriteHook) {
+    let writeRequest = null;
+    if (args.requireWriteHook) {
+      writeRequest = validateHardWriteRequest({
+        root: args.root,
+        host: args.requireWriteHook,
+        tools: [args.requireWriteHook],
+        force: true,
+      });
+      if (!writeRequest.ok) {
+        const payload = {
+          ok: false,
+          error: 'unsupported-enforcement-profile',
+          message: writeRequest.error,
+        };
+        if (args.json) console.log(JSON.stringify(payload, null, 2));
+        else console.error(writeRequest.error);
+        process.exitCode = 2;
+        return;
+      }
+    }
+
+    const missing = args.requireGates ? missingGates(args.root) : [];
+    if (
+      writeRequest?.host &&
+      !detectWritePathCapabilities(args.root, writeRequest.host).capabilities['hard-write']
+    ) {
+      missing.push(`${writeRequest.host} hard-write hook`);
     }
     if (missing.length > 0) {
       const payload = {
         ok: false,
         error: 'missing-gates',
         missing,
+        ...(writeRequest?.host ? { writeHost: writeRequest.host } : {}),
       };
       if (args.json) {
         console.log(JSON.stringify(payload, null, 2));
@@ -994,7 +1022,12 @@ async function main() {
         for (const relativePath of missing) {
           console.error(`  - ${relativePath}`);
         }
-        console.error(`\nRun \`${arkCommand(args.root, 'ark', 'init')}\` (or \`ark-check --install-agent-gates\`) to configure enforcement.`);
+        const installArgs = writeRequest?.host
+          ? `--install-agent-gates --tools ${writeRequest.host} --require-write-hook ${writeRequest.host}`
+          : '--install-agent-gates';
+        console.error(
+          `\nRun \`${arkCommand(args.root, 'ark', 'init')}\` (or \`${arkCommand(args.root, 'ark-check', installArgs)}\`) to configure enforcement.`
+        );
       }
       process.exitCode = 1;
       return;
@@ -1004,7 +1037,12 @@ async function main() {
     // 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(', '));
+      if (args.requireGates) {
+        console.log('Ark gates present (merge profile): ' + REQUIRED_GATE_FILES.join(', '));
+      }
+      if (writeRequest?.host) {
+        console.log(`Ark hard-write hook present for ${writeRequest.host}.`);
+      }
     }
   }
 
@@ -1277,6 +1315,18 @@ async function main() {
         }
       }
     }
+
+    // Best-effort: open the report in the default browser. If it opens, fine;
+    // if not (headless, no GUI, spawn error), do nothing — never fail the check.
+    // Skipped in CI / Vitest / ARK_NO_OPEN_REPORT; --open / --no-open override.
+    if (
+      shouldOpenHtmlReport({
+        force: Boolean(args.openReport),
+        noOpen: Boolean(args.noOpenReport) || Boolean(args.json),
+      })
+    ) {
+      openHtmlInBrowser(reportPath);
+    }
   }
 
   if (args.json) {
@@ -1385,10 +1435,19 @@ async function main() {
       const parts = [];
       if (codexHomeGap.missing > 0) parts.push(`${codexHomeGap.missing} missing`);
       if (codexHomeGap.stale > 0) parts.push(`${codexHomeGap.stale} outdated`);
+      // Advisory always; when session host is known and not Codex, say so so
+      // /ark-upgrade does not chase home prompts as Incomplete.
+      const activeHost = detectActiveAgentHost();
+      const deferredNote =
+        activeHost != null && activeHost !== 'codex'
+          ? ' Deferred unless you use Codex — not a blocker for Grok/Claude/Cursor. '
+          : ' ';
       console.log(
         color.dim(
-          `/ark-* skills in ${codexPromptsDir()} are behind this Ark (${parts.join(', ')}). ` +
-            `Codex loads them from there, not the repo. Refresh: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --codex-home --force')}`
+          `/ark-* skills in ${codexPromptsDir()} are behind this Ark (${parts.join(', ')}).` +
+            deferredNote +
+            `Codex loads them from $CODEX_HOME/prompts, not the repo. ` +
+            `When using Codex: ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --codex-home --force')}`
         )
       );
     }

package/bin/ark-mcp.mjs

@@ -58,6 +58,7 @@ import {
 import { createImportTargetResolver } from './lib/import-resolve.mjs';
 import { validateWithAutoPatch, resolveImportFileAbs } from './lib/auto-patch.mjs';
 import { composePrepareWrite } from './lib/prepare-write.mjs';
+import { loadArkConfigContract } from './lib/config-contract.mjs';
 
 const arkCheckBin = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
 
@@ -120,6 +121,11 @@ function readJson(file, { required } = {}) {
   }
 }
 
+function readArkConfig(file, { required } = {}) {
+  const raw = readJson(file, { required });
+  return raw === undefined ? undefined : loadArkConfigContract(raw, file).config;
+}
+
 function resolveInRoot(root, maybePath) {
   if (!maybePath) return undefined;
   return path.isAbsolute(maybePath) ? maybePath : path.join(root, maybePath);
@@ -460,11 +466,11 @@ async function main() {
   const ts = await loadOptionalTypeScript();
 
   const config =
-    (configPath ? readJson(configPath, { required: args.configExplicit }) : undefined) ?? {
-      include: ['src'],
-      layers: [],
-      rules: [],
-    };
+    (configPath ? readArkConfig(configPath, { required: args.configExplicit }) : undefined) ??
+    loadArkConfigContract(
+      { include: ['src'], layers: [], rules: DEFAULT_RULES },
+      configPath ?? 'ark.config.json'
+    ).config;
   if (!config.layers || config.layers.length === 0) {
     process.stderr.write(
       '[ark-mcp] warning: no layers configured — file→layer inference from config patterns ' +

package/bin/ark-shared.mjs

@@ -1,12 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  DEFAULT_ARK_CONFIG_RULES,
+  withArkConfigMetadata,
+} from './lib/config-contract.mjs';
 
 /**
- * Default layer rule matrix + intent-prefix map, shared by both CLIs and by the ark-mcp
- * write-path gate so they enforce identically. These mirror the elevenLayerProfile in
- * src/kernel/layers/ArchitectureProfile.ts; kept here (not imported from dist) because the
- * CLIs run standalone with only `typescript` present, no build step.
+ * Default intent-prefix map shared by both CLIs and the ark-mcp write-path gate. The rule
+ * matrix comes from the generated Domain config contract above. Prefixes mirror the runtime
+ * profile but stay in this standalone CLI module because the CLIs run without a build step.
  */
 export const DEFAULT_INTENT_PREFIXES = [
   { layer: 'DomainModel', prefixes: ['Domain.'] },
@@ -41,35 +44,7 @@ export const DEFAULT_LAYER_DIRECTORIES = {
   Kernel: ['kernel'],
 };
 
-const DEFAULT_ALLOWED_FLOWS = [
-  { from: 'PresentationAdapters', to: 'ApplicationOrchestration' },
-  { from: 'ApplicationOrchestration', to: 'DomainModel' },
-  { from: 'WorkflowSagaEngine', to: 'ApplicationOrchestration' },
-  { from: 'WorkflowSagaEngine', to: 'DomainModel' },
-  { from: 'BackgroundJobsScheduling', to: 'ApplicationOrchestration' },
-];
-
-function flowKey(from, to) {
-  return `${from}->${to}`;
-}
-
-function createStrictDenyRules(layers, allowedFlows) {
-  const allowed = new Set(allowedFlows.map((flow) => flowKey(flow.from, flow.to)));
-  const rules = [];
-  for (const from of layers) {
-    for (const to of layers) {
-      if (from.layer === to.layer) continue;
-      if (allowed.has(flowKey(from.layer, to.layer))) continue;
-      rules.push({ from: from.layer, to: to.layer, allowed: false });
-    }
-  }
-  return rules;
-}
-
-export const DEFAULT_RULES = createStrictDenyRules(
-  DEFAULT_INTENT_PREFIXES,
-  DEFAULT_ALLOWED_FLOWS
-);
+export const DEFAULT_RULES = DEFAULT_ARK_CONFIG_RULES;
 
 /**
  * Default ambient globals forbidden in the domain layer: a pure domain does no I/O and is
@@ -82,7 +57,7 @@ export function createElevenLayerConfig(options = {}) {
   const rootDir = options.rootDir ?? 'src';
   const optional = options.optionalLayers ?? true;
   const prefix = rootDir === '.' ? '' : `${rootDir}/`;
-  const config = {
+  const config = withArkConfigMetadata({
     include: options.include ?? [rootDir],
     layers: DEFAULT_INTENT_PREFIXES.map((entry) => ({
       name: entry.layer,
@@ -96,7 +71,7 @@ export function createElevenLayerConfig(options = {}) {
         : {}),
     })),
     rules: DEFAULT_RULES,
-  };
+  });
   // When a project root is known, overlay Nest/Next/express filename conventions so a
   // flat framework starter is governed on day one (not "0% governed / false green").
   if (options.root) return applyFrameworkLayoutOverlays(config, options.root);
@@ -134,7 +109,7 @@ export function applyFrameworkLayoutOverlays(config, root) {
   try {
     signals = collectRepoShapeSignals(root);
   } catch {
-    return config;
+    return withArkConfigMetadata(config);
   }
 
   const next = {
@@ -344,7 +319,7 @@ export function applyFrameworkLayoutOverlays(config, root) {
       : 'library';
   }
 
-  return next;
+  return withArkConfigMetadata(next);
 }
 
 /**
@@ -398,40 +373,97 @@ export function resolveOperatingMode({
   return 'suggest';
 }
 
+function singleFileTypeChecker(ts, sourceFile) {
+  const options = {
+    noLib: true,
+    noResolve: true,
+    target: ts.ScriptTarget.Latest,
+  };
+  const host = ts.createCompilerHost(options, true);
+  host.getSourceFile = (fileName) =>
+    fileName === sourceFile.fileName ? sourceFile : undefined;
+  host.fileExists = (fileName) => fileName === sourceFile.fileName;
+  host.readFile = (fileName) =>
+    fileName === sourceFile.fileName ? sourceFile.text : undefined;
+  return ts.createProgram([sourceFile.fileName], options, host).getTypeChecker();
+}
+
+function propertyAccessPath(ts, node) {
+  const segments = [];
+  let current = node;
+  while (ts.isPropertyAccessExpression(current)) {
+    segments.unshift(current.name.text);
+    current = current.expression;
+  }
+  if (!ts.isIdentifier(current)) return undefined;
+  segments.unshift(current.text);
+  return { root: current, segments };
+}
+
+function isRuntimeIdentifierReference(ts, node) {
+  if (ts.isPropertyAccessExpression(node.parent) && node.parent.name === node) return false;
+  return (
+    (ts.isExpressionNode(node) && !ts.isInTypeQuery(node)) ||
+    (ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node)
+  );
+}
+
+function hasLocalDeclaration(ts, checker, sourceFile, node) {
+  const shorthand =
+    ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node;
+  const symbol = shorthand
+    ? checker.getShorthandAssignmentValueSymbol(node.parent)
+    : checker.getSymbolAtLocation(node);
+  return Boolean(
+    symbol?.declarations?.some((declaration) => declaration.getSourceFile() === sourceFile)
+  );
+}
+
 /**
  * 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.
+ * A no-lib, no-resolution TypeScript program binds declarations in this file only. An
+ * identifier with a symbol is therefore local (parameter, variable, import, etc.); an
+ * unbound runtime identifier is ambient. Dotted entries use AST property chains and
+ * explicit `globalThis` access is normalized to the configured global name.
  *
+ * Kept in sync with `analyzeForbiddenGlobals` in
+ * src/kernel/ai-gate/AICodeGate.ts — the standalone CLIs must not import from dist.
  * 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 checker = singleFileTypeChecker(ts, sourceFile);
   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 });
+    const nestedPropertyAccess =
+      ts.isPropertyAccessExpression(node) &&
+      ts.isPropertyAccessExpression(node.parent) &&
+      node.parent.expression === node;
+    if (ts.isPropertyAccessExpression(node) && !nestedPropertyAccess) {
+      const path = propertyAccessPath(ts, node);
+      if (path && !hasLocalDeclaration(ts, checker, sourceFile, path.root)) {
+        const explicitGlobalThis = path.segments[0] === 'globalThis';
+        const normalized = explicitGlobalThis ? path.segments.slice(1) : path.segments;
+        let match;
+        for (let length = normalized.length; length >= (explicitGlobalThis ? 1 : 2); length -= 1) {
+          const candidate = normalized.slice(0, length).join('.');
+          if (entries.has(candidate)) {
+            match = candidate;
+            break;
+          }
+        }
+        if (match) uses.push({ name: match, node });
       }
     } else if (
-      (ts.isCallExpression(node) || ts.isNewExpression(node)) &&
-      node.expression &&
-      ts.isIdentifier(node.expression) &&
-      entries.has(node.expression.text)
+      ts.isIdentifier(node) &&
+      entries.has(node.text) &&
+      isRuntimeIdentifierReference(ts, node) &&
+      !hasLocalDeclaration(ts, checker, sourceFile, node)
     ) {
-      uses.push({ name: node.expression.text, node });
+      uses.push({ name: node.text, node });
     }
     ts.forEachChild(node, visit);
   };