arkgate 2.12.0 → 2.13.0

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);
   };

package/bin/ark.mjs

@@ -19,6 +19,7 @@ import {
   resolveOperatingMode,
 } from './ark-shared.mjs';
 import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
+import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
@@ -57,6 +58,7 @@ function parseArgs(argv) {
     force: false,
     strict: true,
     install: true,
+    requireWriteHook: undefined,
     help: false,
     version: false,
   };
@@ -81,6 +83,9 @@ function parseArgs(argv) {
     else if (arg === '--preset') args.preset = requireValue(arg, i++);
     else if (arg === '--archetype') args.archetype = requireValue(arg, i++);
     else if (arg === '--tools') args.tools = requireValue(arg, i++);
+    else if (arg === '--require-write-hook') {
+      args.requireWriteHook = requireValue(arg, i++).trim().toLowerCase();
+    }
     else if (arg === '--help' || arg === '-h' || arg === 'help') args.help = true;
     else if (arg === '--version' || arg === '-V') args.version = true;
     else if (!arg.startsWith('-') && args.command === undefined) args.command = arg;
@@ -92,9 +97,9 @@ function parseArgs(argv) {
 
 function usage() {
   return `Usage:
-  ark start   [--root <project>] [--yes]
+  ark start   [--root <project>] [--tools <list>] [--require-write-hook <host>] [--yes]
   ark init    [--root <project>] [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|clean-architecture|onion-architecture]
-              [--archetype <playbook-id>] [--tools <list>] [--yes] [--force] [--no-strict]
+              [--archetype <playbook-id>] [--tools <list>] [--require-write-hook <host>] [--yes] [--force] [--no-strict]
   ark upgrade [--root <project>] [--no-install] [--no-strict]
 
 Commands:
@@ -119,6 +124,9 @@ Options:
                vertical-slice-product, ddd-bounded-contexts.
   --tools      Comma-separated agents to gate (claude,cursor,codex,grok,windsurf,cline,copilot,kiro,roo,continue,gemini).
                Omit to auto-detect from each tool's config dir, falling back to claude+cursor+codex+grok.
+  --require-write-hook <host>
+               Require and verify a hard local write hook for Claude or Grok. Cursor/Codex are
+               advisory-write plus hard CI merge only; impossible requests fail before any write.
 
 Interactive mode (TTY, no --yes): asks what application shape you are building and maps it to a preset.
 Non-interactive (no TTY): uses the same defaults as --yes — never calls readline on a null interface.
@@ -203,7 +211,7 @@ async function upgrade(args) {
   }
   console.log('\n4/4  Verifying architecture…');
   return runArkCheck(
-    ['--root', root, '--config', 'ark.config.json', '--strict-config'],
+    ['--root', root, '--config', 'ark.config.json', '--strict-merge'],
     { cwd: root }
   );
 }
@@ -365,6 +373,9 @@ async function init(args) {
     if (installGates) {
       const gateArgs = ['--root', root, '--install-agent-gates'];
       if (args.tools) gateArgs.push('--tools', args.tools);
+      if (args.requireWriteHook) {
+        gateArgs.push('--require-write-hook', args.requireWriteHook);
+      }
       if (args.force) gateArgs.push('--force');
       const status = runArkCheck(gateArgs, { cwd: root });
       if (status !== 0) return status;
@@ -374,14 +385,15 @@ async function init(args) {
       args.strict &&
       (nonInteractive || (await askYesNo(rl, 'Run strict architecture check now?', true)));
     if (runStrict) {
-      return runArkCheck(
-        ['--root', root, '--config', 'ark.config.json', '--strict-config'],
-        { cwd: root }
-      );
+      const strictArgs = ['--root', root, '--config', 'ark.config.json', '--strict-merge'];
+      if (args.requireWriteHook) {
+        strictArgs.push('--require-write-hook', args.requireWriteHook);
+      }
+      return runArkCheck(strictArgs, { cwd: root });
     }
 
     console.log(
-      `Ark init complete. Run \`${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config')}\` before merging.`
+      `Ark init complete. Run \`${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-merge')}\` before merging.`
     );
     if (archetype) {
       console.log(`Shape: ${archetype}. Plan: ${arkCommand(root, 'ark-check', '--recommend')}`);
@@ -526,8 +538,12 @@ async function start(args) {
     {
       const gateArgs = ['--root', root, '--install-agent-gates'];
       if (args.tools) gateArgs.push('--tools', args.tools);
+      if (args.requireWriteHook) {
+        gateArgs.push('--require-write-hook', args.requireWriteHook);
+      }
       if (args.force) gateArgs.push('--force');
-      runArkCheck(gateArgs, { cwd: root });
+      const status = runArkCheck(gateArgs, { cwd: root });
+      if (status !== 0) return status;
     }
 
     // 6) Show the plan: what's safe to auto-fix vs what needs a decision.
@@ -664,7 +680,7 @@ async function start(args) {
       console.log('     → explore first, dual plan (remediation + pattern bets), safe fixes, leave gates on.');
     }
     console.log(`  2. Status anytime: ${arkCommand(root, 'ark-check', '--doctor')}`);
-    console.log(`  3. After edits:    ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config')}`);
+    console.log(`  3. After edits:    ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-merge')}`);
     if (mode === 'adapt' && planOk && !falseGreenGap) {
       console.log(
         `  4. When green but cores still optional: ${arkCommand(root, 'ark-check', '--ratchet-cores')} → honest ENFORCE`
@@ -696,6 +712,25 @@ async function main() {
     return 0;
   }
 
+  if (args.requireWriteHook && !['start', 'init'].includes(args.command)) {
+    console.error('--require-write-hook is supported by ark start and ark init.');
+    return 2;
+  }
+  const enforcement = validateHardWriteRequest({
+    root: args.root,
+    host: args.requireWriteHook,
+    tools: args.tools,
+    force: args.force,
+  });
+  if (!enforcement.ok) {
+    console.error(enforcement.error);
+    return 2;
+  }
+  if (enforcement.host) {
+    args.requireWriteHook = enforcement.host;
+    if (!args.tools) args.tools = enforcement.tools.join(',');
+  }
+
   if (args.command === 'start') {
     try {
       return await start(args);

package/bin/lib/agent-gates.mjs

@@ -76,6 +76,8 @@ export {
   normalizeToolsList,
   resolveTools,
   KNOWN_TOOLS,
+  detectActiveAgentHost,
+  codexConcernIsActive,
   arkPackageVersion,
   stampSkill,
   installedSkillVersion,
@@ -95,6 +97,16 @@ export {
   collectAdoptionGaps,
 } from './mcp-adoption.mjs';
 
+export {
+  detectPreCommitArk,
+  detectCiEnforcement,
+  detectConfigGateDrift,
+  jobIdsThatRunArkCheck,
+  isArkRequiredStatusCheck,
+  reportGithubBranchProtection,
+  collectWeakestLinkGaps,
+} from './weakest-link.mjs';
+
 export {
   staleRunnerGateFiles,
   warnLockfileConflict,

package/bin/lib/architecture-scan.mjs

@@ -92,6 +92,14 @@ export function scanSourceFile(ts, root, config, rules, manifestIntentLayers, fi
       }
     }
 
+    if (
+      ts.isImportEqualsDeclaration(node) &&
+      ts.isExternalModuleReference(node.moduleReference)
+    ) {
+      const specifier = stringLiteralText(ts, node.moduleReference.expression);
+      if (specifier) checkModuleEdge(specifier, node, 'require');
+    }
+
     if (ts.isCallExpression(node)) {
       const moduleCall = moduleSpecifierFromCall(ts, node);
       if (moduleCall) {

package/bin/lib/ci-and-commands.mjs

@@ -12,6 +12,7 @@ import {
   DEFAULT_LAYER_DIRECTORIES,
 } from '../ark-shared.mjs';
 import { falseGreenAdoptionGap } from './field-install.mjs';
+import { renderHostSupportMatrixMarkdown } from './host-support-matrix.mjs';
 import { PREFERRED_MCP_BIN } from './hook-templates.mjs';
 import { readPackageJson } from './gate-files.mjs';
 
@@ -30,7 +31,7 @@ export function checkArgsForRoot(root, { requireGates = false } = {}) {
   const baselineFlag = fs.existsSync(path.join(root, '.ark-baseline.json'))
     ? ' --baseline .ark-baseline.json'
     : '';
-  const profile = requireGates ? '--strict' : '--strict-config';
+  const profile = requireGates ? '--strict-merge' : '--strict-config';
   return `--root . --config ark.config.json ${profile}${baselineFlag}`;
 }
 
@@ -140,6 +141,10 @@ export function agentInstructions(root) {
 Skills are **dual-engine**: deterministic CLI sensors + exploratory read of *this* repo — not JSON-only wrappers.
 When a skill says **STOP — do not continue this skill as complete**, stop and invoke the named handoff skill.
 
+## Host enforcement support
+
+${renderHostSupportMatrixMarkdown()}
+
 ### Subagent fan-out
 If the host supports **parallel subagents**, skills may ask you to fan out **read-only**
 scouts (disjoint path scopes) and merge in the parent. If the host does **not**,
@@ -177,8 +182,9 @@ an ungoverned location:
 
 ${layerPlacementTable()}
 
-The project is only considered Ark-enforced when the write gate and CI gate pass
-(runtime path only if this project opted into the kernel).
+The project is only considered Ark-enforced when its host-appropriate write path is configured
+and the CI check passes. Only Claude/Grok provide a hard local write boundary; Cursor/Codex use
+advisory MCP plus CI. The experimental runtime is not required.
 `;
 }
 

package/bin/lib/codex-home.mjs

@@ -22,6 +22,13 @@ export function codexConfigPath() {
   return path.join(base, 'config.toml');
 }
 
+/** True when CODEX_HOME is unset/empty or resolves to the real default ~/.codex. */
+export function usesDefaultCodexHome(env = process.env, homeDir = os.homedir()) {
+  const configured = env?.CODEX_HOME;
+  if (typeof configured !== 'string' || configured.trim() === '') return true;
+  return path.resolve(configured) === path.resolve(homeDir, '.codex');
+}
+
 /** Temp / upgrade sandbox roots must never remain as Codex MCP --root. */
 export function isTempOrUpgradeRoot(p) {
   if (!p || typeof p !== 'string') return false;