arkgate 2.12.0 → 3.0.0

package/bin/lib/mcp-adoption.mjs

@@ -9,8 +9,9 @@ import { CORE_LAYER_NAMES } from './core-layers.mjs';
 import { falseGreenAdoptionGap } from './field-install.mjs';
 import { assessCodexHomeMcp, codexConfigPath } from './codex-home.mjs';
 import { detectWritePathCapabilities } from './write-path-detect.mjs';
-import { skillTemplateNames } from './skill-install.mjs';
+import { detectActiveAgentHost, skillTemplateNames } from './skill-install.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
+import { collectWeakestLinkGaps } from './weakest-link.mjs';
 
 export { detectDeployPathQuality };
 
@@ -195,10 +196,22 @@ export function collectAdoptionGaps(root, config, coverage) {
         scopedTable: assessed.scopedTable,
       };
       if (assessed.gap) {
+        // Temp/upgrade MCP roots stay urgent (fail-closed). Non-temp Codex-home debt
+        // is deferred only when the session host is known and is not Codex
+        // (Grok/Claude/Cursor…). Unknown host (CI/plain shell) keeps original severity.
+        const tempUrgent = Boolean(assessed.tempPath);
+        const activeHost = detectActiveAgentHost();
+        const deferred =
+          !tempUrgent && activeHost != null && activeHost !== 'codex';
+        const severity = deferred ? 'info' : assessed.gap.severity;
+        const message = deferred
+          ? `Deferred (fix when using Codex): ${assessed.gap.message}`
+          : assessed.gap.message;
         gaps.push({
           id: assessed.gap.id,
-          severity: assessed.gap.severity,
-          message: assessed.gap.message,
+          severity,
+          deferred,
+          message,
           fix: arkCommand(root, 'ark-check', assessed.gap.fixArgs),
         });
       }
@@ -403,6 +416,19 @@ export function collectAdoptionGaps(root, config, coverage) {
     }
   }
 
+  // --- Q3 weakest-link: CI / pre-commit / config drift (local FS; optional GH via ARK_DOCTOR_GITHUB=1) ---
+  const includeGithub =
+    process.env.ARK_DOCTOR_GITHUB === '1' ||
+    process.env.ARK_DOCTOR_GITHUB === 'true';
+  const weakest = collectWeakestLinkGaps(root, {
+    adopted,
+    isProducer,
+    includeGithub,
+  });
+  for (const g of weakest.gaps) {
+    gaps.push(g);
+  }
+
   return {
     gaps,
     hosts,
@@ -415,6 +441,12 @@ export function collectAdoptionGaps(root, config, coverage) {
     deployPath,
     contractFalseGreen,
     writePath,
+    enforcement: {
+      ci: weakest.ci,
+      preCommit: weakest.preCommit,
+      drift: weakest.drift,
+      github: weakest.github,
+    },
   };
 }
 

package/bin/lib/open-html.mjs

@@ -0,0 +1,75 @@
+/**
+ * Open a local HTML file in the default browser (macOS / Windows / Linux).
+ * Used after ark-check --report writes a showcase/beginner report.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Whether report generation should open the browser.
+ * Default: yes for interactive local TTY; never in CI/Vitest unless forced.
+ *
+ * @param {{ force?: boolean, noOpen?: boolean, env?: NodeJS.ProcessEnv, isTty?: boolean }} [opts]
+ */
+export function shouldOpenHtmlReport(opts = {}) {
+  const env = opts.env ?? process.env;
+  if (opts.noOpen) return false;
+  if (opts.force) return true;
+  const off = env.ARK_NO_OPEN_REPORT;
+  if (off === '1' || off === 'true' || off === 'yes') return false;
+  if (env.CI === 'true' || env.CI === '1') return false;
+  if (env.GITHUB_ACTIONS === 'true') return false;
+  if (env.VITEST) return false;
+  const tty = opts.isTty ?? Boolean(process.stdout.isTTY);
+  return tty;
+}
+
+/**
+ * Launch the OS default browser for a local file path (non-blocking).
+ * Errors are swallowed — report generation must not fail if the browser cannot open.
+ *
+ * @param {string} filePath
+ * @param {{ platform?: NodeJS.Platform, spawn?: typeof spawn }} [opts]
+ * @returns {{ ok: boolean, command?: string, reason?: string }}
+ */
+export function openHtmlInBrowser(filePath, opts = {}) {
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) {
+    return { ok: false, reason: 'missing-file' };
+  }
+  const platform = opts.platform ?? process.platform;
+  const spawnFn = opts.spawn ?? spawn;
+
+  /** @type {string} */
+  let command;
+  /** @type {string[]} */
+  let args;
+  if (platform === 'darwin') {
+    command = 'open';
+    args = [abs];
+  } else if (platform === 'win32') {
+    command = 'rundll32.exe';
+    args = ['url.dll,FileProtocolHandler', pathToFileURL(abs).href];
+  } else {
+    command = 'xdg-open';
+    args = [abs];
+  }
+
+  try {
+    const child = spawnFn(command, args, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      shell: false,
+    });
+    child.on('error', () => {
+      /* browser missing (e.g. headless Linux) — ignore */
+    });
+    child.unref();
+    return { ok: true, command };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+}

package/bin/lib/presets.mjs

@@ -5,9 +5,11 @@ import {
   applyFrameworkLayoutOverlays,
   createElevenLayerConfig,
   DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
+  discoverRepoUnits,
   DEFAULT_INTENT_PREFIXES,
   resolveIncludeRoots,
 } from '../ark-shared.mjs';
+import { withArkConfigMetadata } from './config-contract.mjs';
 
 export function denyUpward(names) {
   const rules = [];
@@ -49,8 +51,8 @@ export function peerIsolationEdges(layerNames, sliceFolders, message) {
 // (that carves out legitimate `src/shared/kernel/**` SharedKernel paths).
 export const FRAMEWORK_INTERNAL_EXCLUDE = ['src/kernel/**', '**/src/kernel/**'];
 export function presetWithOverlays(baseConfig, root) {
-  if (!root) return baseConfig;
-  return applyFrameworkLayoutOverlays(baseConfig, root);
+  const config = root ? applyFrameworkLayoutOverlays(baseConfig, root) : baseConfig;
+  return withArkConfigMetadata(config);
 }
 
 export const ARCHITECTURE_PRESETS = {
@@ -202,12 +204,41 @@ export const ARCHITECTURE_PRESETS = {
   monorepo: (includeDirs, root) => {
     let include =
       includeDirs && includeDirs.length > 0 ? [...includeDirs] : [];
+    let units = [];
     if (root) {
       const resolved = resolveIncludeRoots(root);
       if (resolved.length > 0) include = resolved;
+      units = discoverRepoUnits(root);
+      const nonProductRoots = new Set(
+        units
+          .filter((unit) => ['docs', 'example', 'test'].includes(unit.role))
+          .map((unit) => unit.root)
+      );
+      include = include.filter((entry) => !nonProductRoots.has(entry));
     }
     // Turborepo: apps/ + packages/; Nx enterprise: apps/ + libs/ (+ packages/).
     if (include.length === 0) include = ['packages', 'apps', 'libs'];
+    // Established workspaces often have flat package source roots rather than a
+    // directory named domain/application. The package manifest supplies a real,
+    // reviewable role signal: a published library is a domain surface; an app or
+    // CLI package coordinates work. This is deliberately limited to package roots
+    // Ark already discovered, never a catch-all **/src/** fallback.
+    const packagePatterns = (roles) => {
+      if (!root) return [];
+      return units
+        .filter((unit) => roles.includes(unit.role))
+        .flatMap((unit) => unit.sourceRoots.map((sourceRoot) => {
+          const base = unit.root === '.'
+            ? sourceRoot
+            : sourceRoot === '.'
+              ? unit.root
+              : `${unit.root}/${sourceRoot}`;
+          return base === '.' ? null : `${base}/**`;
+        }))
+        .filter(Boolean);
+    };
+    const librarySourcePatterns = packagePatterns(['library']);
+    const applicationSourcePatterns = packagePatterns(['application', 'cli']);
     return presetWithOverlays(
       {
         include,
@@ -218,14 +249,24 @@ export const ARCHITECTURE_PRESETS = {
               'Pure business rules and entities, in any package. No I/O, no framework, no ambient globals.',
             // Domain by intentional folders only — NOT bare **/types.ts (that mis-classifies
             // application bags like frontend/src/core/**/types.ts as Domain and creates false edges).
-            patterns: ['**/domain/**', '**/entities/**', '**/cinematic/types.ts'],
+            patterns: [
+              '**/domain/**',
+              '**/entities/**',
+              '**/cinematic/types.ts',
+              ...librarySourcePatterns,
+            ],
             forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
             optional: true,
           },
           {
             name: 'ApplicationOrchestration',
             description: 'Use cases and services that coordinate the domain through ports.',
-            patterns: ['**/application/**', '**/use-cases/**', '**/services/**'],
+            patterns: [
+              '**/application/**',
+              '**/use-cases/**',
+              '**/services/**',
+              ...applicationSourcePatterns,
+            ],
             optional: true,
           },
           {

package/bin/lib/safety-diagnostics.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { globToRegExp } from '../ark-shared.mjs';
+import { extractSemanticDependencies } from './analysis-engine.mjs';
 import { lineOf } from './ast-scan.mjs';
 import { normalize } from './scan-files.mjs';
 
@@ -104,9 +105,26 @@ export function collectSafetyDiagnostics(ts, root, config, files) {
 
   for (const file of files) {
     const source = fs.readFileSync(file, 'utf8');
+    // Most source files cannot contain a safety finding. Avoid parsing a second AST when the
+    // lexical markers for every supported diagnostic are absent; a match only opts into the
+    // existing exact AST analysis, so this cannot suppress a finding.
+    if (!/@ts-(?:ignore|nocheck)\b|\bany\b|\b(?:import|require)\s*\(|\barkgate(?:\/runtime)?\b/.test(source)) {
+      continue;
+    }
     const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
     const relFile = normalize(path.relative(root, file));
 
+    if (!matchesAny(relFile, dynamicAllowlist)) {
+      for (const dependency of extractSemanticDependencies(ts, sourceFile)) {
+        if (!dependency.unresolved) continue;
+        report.nonLiteralDynamicImports.push({
+          file: relFile,
+          line: dependency.line,
+          kind: dependency.kind === 'require' ? 'require' : 'import',
+        });
+      }
+    }
+
     for (const position of tsSuppressionPositions(sourceFile, source)) {
       report.tsSuppressions.push({
         file: relFile,
@@ -146,18 +164,6 @@ export function collectSafetyDiagnostics(ts, root, config, files) {
         });
       }
 
-      if (ts.isCallExpression(node) && node.expression?.kind === ts.SyntaxKind.ImportKeyword) {
-        const argument = node.arguments[0];
-        if (!argument || !ts.isStringLiteralLike(argument)) {
-          if (!matchesAny(relFile, dynamicAllowlist)) {
-            report.nonLiteralDynamicImports.push({
-              file: relFile,
-              line: lineOf(sourceFile, node.getStart(sourceFile)),
-            });
-          }
-        }
-      }
-
       if (!allowInMemory && !isProvider && ts.isImportDeclaration(node)) {
         const specifier = node.moduleSpecifier;
         const fromArk = ts.isStringLiteralLike(specifier) && /^arkgate(?:\/runtime)?$/.test(specifier.text);
@@ -216,13 +222,28 @@ export function collectSafetyDiagnostics(ts, root, config, files) {
   }
 
   const warnings = [];
-  if (report.nonLiteralDynamicImports.length > 0) {
-    const first = report.nonLiteralDynamicImports[0];
+  const nonLiteralImports = report.nonLiteralDynamicImports.filter(
+    (entry) => entry.kind !== 'require'
+  );
+  if (nonLiteralImports.length > 0) {
+    const first = nonLiteralImports[0];
     warnings.push({
       ruleId: 'DYNAMIC_IMPORT_NOT_ALLOWLISTED',
       file: first.file,
       line: first.line,
-      message: `${report.nonLiteralDynamicImports.length} non-literal dynamic import(s) cannot be resolved statically. Add only reviewed files to dynamicImportAllowlist.`,
+      message: `${nonLiteralImports.length} non-literal dynamic import(s) cannot be resolved statically. Add only reviewed files to dynamicImportAllowlist.`,
+    });
+  }
+  const nonLiteralRequires = report.nonLiteralDynamicImports.filter(
+    (entry) => entry.kind === 'require'
+  );
+  if (nonLiteralRequires.length > 0) {
+    const first = nonLiteralRequires[0];
+    warnings.push({
+      ruleId: 'DYNAMIC_REQUIRE_NOT_ALLOWLISTED',
+      file: first.file,
+      line: first.line,
+      message: `${nonLiteralRequires.length} non-literal require call(s) cannot be resolved statically. Add only reviewed files to dynamicImportAllowlist.`,
     });
   }
   if (report.tsSuppressions.length > maxTsSuppressions) {

package/bin/lib/scan-files.mjs

@@ -12,7 +12,7 @@ export const SOURCE_FILE_NAME = /\.[cm]?[tj]sx?$/;
  *  to production code (*.spec.ts). Counting them as ungoverned forces false
  *  CONFIG_UNCLASSIFIED_FILES under --strict-config on every starter. */
 export const TEST_FILE_NAME =
-  /\.(spec|test)\.(tsx?|jsx?|mts|cts)$/i;
+  /(^test(?:[-_.]).*|\.(spec|test)(?:-d)?\.)(tsx?|jsx?|mjsx?|cjsx?|mts|cts)$/i;
 
 export function isGovernableSourceFile(name) {
   return SOURCE_FILE_NAME.test(name) && !name.endsWith('.d.ts') && !TEST_FILE_NAME.test(name);
@@ -23,6 +23,17 @@ export function isSkippedSourceDir(name) {
     name === 'node_modules' ||
     name === 'dist' ||
     name === 'coverage' ||
+    name === 'bench' ||
+    name === 'benches' ||
+    name === 'benchmark' ||
+    name === 'benchmarks' ||
+    name === 'docs' ||
+    name === 'documentation' ||
+    name === 'example' ||
+    name === 'examples' ||
+    name === 'fixture' ||
+    name === 'fixtures' ||
+    name === 'playground' ||
     name === '__tests__' ||
     name === '__mocks__' ||
     name === 'e2e' ||

package/bin/lib/skill-install.mjs

@@ -4,7 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { codexPromptsDir } from './codex-home.mjs';
-import { __packageRoot, readJson } from './gate-files.mjs';
+import { __packageRoot, isCompactRouterAgentsContent, readJson } from './gate-files.mjs';
 
 export function normalizeToolsList(tools) {
   if (tools == null) return [];
@@ -23,6 +23,70 @@ export function normalizeToolsList(tools) {
   return [];
 }
 
+function envTruthy(v) {
+  if (v == null || v === '') return false;
+  const s = String(v).trim().toLowerCase();
+  return s !== '0' && s !== 'false' && s !== 'no' && s !== 'off';
+}
+
+/**
+ * Best-effort active agent host for this process (session host).
+ * Prefer ARK_ACTIVE_HOST when set. Do NOT treat CODEX_HOME alone as Codex —
+ * that dir exists for anyone who installed Codex, even when running Grok/Claude.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null} tool id (claude|cursor|codex|grok|…) or null if unknown
+ */
+export function detectActiveAgentHost(env = process.env) {
+  const explicit = String(env.ARK_ACTIVE_HOST || '')
+    .trim()
+    .toLowerCase();
+  if (explicit) return explicit;
+
+  // Grok / xAI Build
+  if (
+    envTruthy(env.GROK_BUILD) ||
+    envTruthy(env.XAI_GROK) ||
+    env.GROK_WORKSPACE_ROOT ||
+    env.GROK_SESSION_ID
+  ) {
+    return 'grok';
+  }
+  // Claude Code
+  if (
+    env.CLAUDE_PROJECT_DIR ||
+    envTruthy(env.CLAUDE_CODE) ||
+    envTruthy(env.CLAUDECODE) ||
+    env.CLAUDE_CODE_ENTRYPOINT
+  ) {
+    return 'claude';
+  }
+  // Cursor agent
+  if (env.CURSOR_TRACE_ID || env.CURSOR_AGENT || envTruthy(env.CURSOR_AGENT_CLI)) {
+    return 'cursor';
+  }
+  // Codex session — never CODEX_HOME alone (see above)
+  if (
+    envTruthy(env.CODEX_SANDBOX) ||
+    env.CODEX_THREAD_ID ||
+    envTruthy(env.CODEX_CI) ||
+    env.CODEX_SESSION_ID
+  ) {
+    return 'codex';
+  }
+  return null;
+}
+
+/**
+ * True when Codex home / MCP / prompts should be treated as an urgent concern
+ * for this process. Non-Codex hosts (Grok, Claude, Cursor, …) defer Codex debt.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function codexConcernIsActive(env = process.env) {
+  return detectActiveAgentHost(env) === 'codex';
+}
+
 export function resolveTools(args) {
   const explicit = normalizeToolsList(args.tools);
   if (explicit.length > 0) {
@@ -220,6 +284,13 @@ export function detectCodexHomeGap(root) {
 
 export function detectSkillGaps(root) {
   if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return [];
+  try {
+    if (isCompactRouterAgentsContent(fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8'))) {
+      return [];
+    }
+  } catch {
+    // Continue with the ordinary missing-skill detection below.
+  }
   // The Ark source tree keeps the skill templates at templates/skills/ — it's the
   // producer, not a consumer, so it must not nag itself to "install" its own skills.
   if (fs.existsSync(path.join(root, 'templates', 'skills'))) return [];

package/bin/lib/source-policy.mjs

@@ -0,0 +1,36 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/sourcePolicy.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/source-policy.mjs). Zero Node I/O.
+ */
+
+export const SOURCE_POLICY_MESSAGES = {
+    RAW_EVENT_PUBLISH: 'Publish through a registered intent creator; raw event objects or intent strings bypass Ark contracts and tooling.',
+    PUBLISH_MISSING_SOURCE: 'Strict Ark publish calls must include metadata.source.',
+};
+export function looksLikeArkIntent(value) {
+    return /^(Domain|Application|Adapter|Workflow|Job|Presentation|Reporting|Metadata|Security|Audit|Observability|Kernel)\.[A-Za-z0-9_.]+$/.test(value);
+}
+export function classifyPublishFacts(facts) {
+    if (!facts.publishCall)
+        return [];
+    const findings = [];
+    if ((facts.rawIntentName !== undefined && looksLikeArkIntent(facts.rawIntentName)) ||
+        facts.objectHasIntent) {
+        findings.push({
+            ruleId: 'RAW_EVENT_PUBLISH',
+            message: SOURCE_POLICY_MESSAGES.RAW_EVENT_PUBLISH,
+        });
+    }
+    if (facts.arkPublishCandidate && !facts.hasSource) {
+        findings.push({
+            ruleId: 'PUBLISH_MISSING_SOURCE',
+            message: SOURCE_POLICY_MESSAGES.PUBLISH_MISSING_SOURCE,
+        });
+    }
+    return findings;
+}