arkgate 3.6.1 → 3.8.0

package/bin/lib/weakest-link.mjs

@@ -2,10 +2,20 @@
  * Q3 — Weakest-link enforcement sensors (local, pure FS; optional gh for protection).
  * Missing CI, config drift, pre-commit human-edit path, and honest branch-protection report.
  */
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
+import {
+  enforcingArkRunText,
+  reportGithubBranchProtection,
+  runsArkCheck,
+} from './github-enforcement.mjs';
+
+export {
+  isArkRequiredStatusCheck,
+  jobIdsThatRunArkCheck,
+  reportGithubBranchProtection,
+} from './github-enforcement.mjs';
 
 const PRECOMMIT_MARKERS = [
   'ark-check',
@@ -60,13 +70,12 @@ export function classifyArkCheckFlags(text) {
   if (!text || typeof text !== 'string') {
     return { hasFailClosedFlag: false, hasStrictConfigOnly: false, hasStrictFlag: false };
   }
-  const hasStrictMerge = /--strict-merge\b/.test(text);
-  const hasRequireGates = /--require-gates\b/.test(text);
+  const hasStrictMerge = /(?:^|\s)--strict-merge(?=\s|$)/.test(text);
+  const hasRequireGates = /(?:^|\s)--require-gates(?=\s|$)/.test(text);
   // Bare --strict (alias of --strict-merge), not --strict-config / already-matched merge.
-  const withoutLong = text.replace(/--strict-merge\b/g, ' ').replace(/--strict-config\b/g, ' ');
-  const hasBareStrict = /--strict\b/.test(withoutLong);
+  const hasBareStrict = /(?:^|\s)--strict(?=\s|$)/.test(text);
   const hasFailClosedFlag = hasStrictMerge || hasRequireGates || hasBareStrict;
-  const hasStrictConfig = /--strict-config\b/.test(text);
+  const hasStrictConfig = /(?:^|\s)--strict-config(?=\s|$)/.test(text);
   const hasStrictConfigOnly = hasStrictConfig && !hasFailClosedFlag;
   const hasStrictFlag = hasFailClosedFlag || hasStrictConfigOnly;
   return { hasFailClosedFlag, hasStrictConfigOnly, hasStrictFlag };
@@ -118,8 +127,6 @@ export function detectCiEnforcement(root) {
   } catch {
     checkArchScript = '';
   }
-  const scriptFlags = classifyArkCheckFlags(checkArchScript);
-
   for (const f of files) {
     let text = '';
     try {
@@ -127,17 +134,13 @@ export function detectCiEnforcement(root) {
     } catch {
       continue;
     }
-    const mentionsArk =
-      /\barkgate-check\b/.test(text) ||
-      /\bark-check\b/.test(text) ||
-      /check:architecture/.test(text) ||
-      /pedroknigge\/arkgate/.test(text);
+    const arkRunText = enforcingArkRunText(text, checkArchScript);
+    const mentionsArk = runsArkCheck(text, checkArchScript);
     if (mentionsArk) {
       out.hasArkCheckWorkflow = true;
       out.arkWorkflowFiles.push(`.github/workflows/${f}`);
-      const flags = classifyArkCheckFlags(text);
-      const viaScript = /check:architecture/.test(text) && scriptFlags.hasFailClosedFlag;
-      if (flags.hasFailClosedFlag || viaScript) {
+      const flags = classifyArkCheckFlags(arkRunText);
+      if (flags.hasFailClosedFlag) {
         out.hasFailClosedFlag = true;
         out.failClosed = true;
         out.hasStrictFlag = true;
@@ -156,60 +159,6 @@ export function detectCiEnforcement(root) {
   return out;
 }
 
-/**
- * Job ids (GitHub Actions) whose job body runs ark-check / check:architecture.
- * Used so required status check "build" counts when the build job runs Ark.
- * @param {string} root
- * @returns {Set<string>}
- */
-export function jobIdsThatRunArkCheck(root) {
-  const ids = new Set();
-  const wfDir = path.join(root, '.github', 'workflows');
-  if (!fs.existsSync(wfDir)) return ids;
-  let files = [];
-  try {
-    files = fs.readdirSync(wfDir).filter((f) => /\.ya?ml$/i.test(f));
-  } catch {
-    return ids;
-  }
-  for (const f of files) {
-    let text = '';
-    try {
-      text = fs.readFileSync(path.join(wfDir, f), 'utf8');
-    } catch {
-      continue;
-    }
-    if (!/\barkgate-check\b|\bark-check\b|check:architecture/.test(text)) continue;
-    const jobsIdx = text.search(/^jobs:\s*$/m);
-    if (jobsIdx < 0) continue;
-    const jobsSection = text.slice(jobsIdx);
-    const re = /^ {2}([A-Za-z0-9_-]+):\s*$/gm;
-    const matches = [...jobsSection.matchAll(re)];
-    for (let i = 0; i < matches.length; i++) {
-      const jobId = matches[i][1];
-      const start = matches[i].index ?? 0;
-      const end = i + 1 < matches.length ? (matches[i + 1].index ?? jobsSection.length) : jobsSection.length;
-      const body = jobsSection.slice(start, end);
-      if (/\barkgate-check\b|\bark-check\b|check:architecture/.test(body)) {
-        ids.add(jobId);
-      }
-    }
-  }
-  return ids;
-}
-
-/**
- * Whether required status checks include Ark (by name or by matching a job that runs Ark).
- * @param {string} root
- * @param {string[]} requiredNames
- */
-export function isArkRequiredStatusCheck(root, requiredNames) {
-  if (!Array.isArray(requiredNames) || requiredNames.length === 0) return false;
-  if (requiredNames.some((n) => /ark|architecture|arkgate/i.test(String(n)))) return true;
-  const jobIds = jobIdsThatRunArkCheck(root);
-  return requiredNames.some((n) => jobIds.has(String(n)));
-}
-
 /**
  * Config / gate surface drift (adopted projects only).
  * @param {string} root
@@ -258,106 +207,6 @@ export function detectConfigGateDrift(root, opts = {}) {
   return { hasConfig, hasAgents, hasCheckScript, issues };
 }
 
-/**
- * Optional GitHub branch-protection / required-check report.
- * Never fakes green: unavailable when gh missing, no remote, or API error.
- *
- * @param {{ cwd?: string, repo?: string, branch?: string, env?: NodeJS.ProcessEnv }} [opts]
- * @returns {{
- *   available: boolean,
- *   reason?: string,
- *   requiredStatusChecks?: string[] | null,
- *   strict?: boolean | null,
- *   enforcesAdmins?: boolean | null,
- *   arkCheckRequired?: boolean | null,
- *   raw?: unknown,
- * }}
- */
-export function reportGithubBranchProtection(opts = {}) {
-  const cwd = opts.cwd ?? process.cwd();
-  const env = opts.env ?? process.env;
-  const gh = spawnSync('gh', ['--version'], { encoding: 'utf8', env });
-  if (gh.status !== 0) {
-    return { available: false, reason: 'gh-cli-unavailable' };
-  }
-
-  let repo = opts.repo;
-  if (!repo) {
-    const r = spawnSync('gh', ['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner'], {
-      cwd,
-      encoding: 'utf8',
-      env,
-    });
-    if (r.status !== 0 || !r.stdout?.trim()) {
-      return { available: false, reason: 'gh-repo-unavailable', raw: r.stderr };
-    }
-    repo = r.stdout.trim();
-  }
-
-  let branch = opts.branch;
-  if (!branch) {
-    const b = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
-      cwd,
-      encoding: 'utf8',
-      env,
-    });
-    branch = b.status === 0 ? b.stdout.trim() : 'main';
-    if (branch === 'HEAD') branch = 'main';
-  }
-
-  const view = spawnSync(
-    'gh',
-    [
-      'api',
-      `repos/${repo}/branches/${encodeURIComponent(branch)}/protection`,
-      '--jq',
-      '{strict: .required_status_checks.strict, contexts: .required_status_checks.contexts, checks: .required_status_checks.checks, enforcesAdmins: .enforce_admins.enabled}',
-    ],
-    { cwd, encoding: 'utf8', env }
-  );
-
-  if (view.status !== 0) {
-    const err = `${view.stderr || ''}${view.stdout || ''}`;
-    if (/Not Found|404|Branch not protected/i.test(err)) {
-      return {
-        available: true,
-        reason: 'branch-not-protected',
-        requiredStatusChecks: [],
-        strict: false,
-        enforcesAdmins: false,
-        arkCheckRequired: false,
-        raw: err.slice(0, 400),
-      };
-    }
-    return { available: false, reason: 'gh-api-error', raw: err.slice(0, 400) };
-  }
-
-  let parsed = null;
-  try {
-    parsed = JSON.parse(view.stdout || '{}');
-  } catch {
-    return { available: false, reason: 'gh-api-parse-error', raw: view.stdout };
-  }
-
-  const contexts = Array.isArray(parsed.contexts) ? parsed.contexts.map(String) : [];
-  const checkNames = Array.isArray(parsed.checks)
-    ? parsed.checks.map((c) => String(c?.context || c?.name || '')).filter(Boolean)
-    : [];
-  const all = [...new Set([...contexts, ...checkNames])];
-  // Name match OR required check id equals a workflow job that runs ark-check (e.g. "build").
-  const arkCheckRequired = isArkRequiredStatusCheck(cwd, all);
-
-  return {
-    available: true,
-    reason: 'ok',
-    requiredStatusChecks: all,
-    strict: Boolean(parsed.strict),
-    enforcesAdmins: Boolean(parsed.enforcesAdmins),
-    arkCheckRequired,
-    raw: parsed,
-  };
-}
-
 /**
  * Adoption gaps for weakest-link (Q3). Does not require network.
  * @param {string} root
@@ -434,14 +283,7 @@ export function collectWeakestLinkGaps(root, opts = {}) {
   let github = null;
   if (opts.includeGithub) {
     github = reportGithubBranchProtection({ cwd: root });
-    if (github.available && github.reason === 'branch-not-protected') {
-      gaps.push({
-        id: 'enforcement-branch-unprotected',
-        severity: 'warn',
-        message: 'Default branch has no GitHub branch protection (architecture check cannot be required)',
-        fix: 'Enable branch protection and require the architecture / ark-check status check',
-      });
-    } else if (
+    if (
       github.available &&
       github.arkCheckRequired === false &&
       Array.isArray(github.requiredStatusChecks)
@@ -450,7 +292,7 @@ export function collectWeakestLinkGaps(root, opts = {}) {
         id: 'enforcement-ark-check-not-required',
         severity: 'warn',
         message:
-          'Branch protection exists but no required status check looks like ark/architecture',
+          'Branch protection exists but no required status check matches a local Ark-running job',
         fix: 'Add the architecture CI job name to required status checks',
       });
     }

package/bin/lib/write-path-capabilities.mjs

@@ -10,6 +10,7 @@ import path from 'node:path';
 import {
   codexProjectMcpIsValid,
   codexConfigPath,
+  extractCodexArgsFromBlock,
   listCodexArkServerTables,
 } from './codex-home.mjs';
 import {
@@ -18,6 +19,7 @@ import {
 } from './host-support-matrix.mjs';
 import { detectActiveAgentHost } from './skill-install.mjs';
 import { detectCiEnforcement } from './weakest-link.mjs';
+import { buildEnforcementState } from './enforcement-state.mjs';
 
 export const WRITE_CAPABILITY_NAMES = [
   'hard-write',
@@ -126,22 +128,161 @@ function relativeEvidencePath(root, file) {
   return file.split(path.sep).join('/');
 }
 
-function isArkMcpText(text) {
-  return (
-    /\b(ark|arkgate)-mcp\b/.test(text) ||
-    /mcp_servers\.ark\b/.test(text) ||
-    /"ark"\s*:\s*\{/.test(text) ||
-    /mcpServers[\s\S]*\bark\b/.test(text)
+function isArkMcpToken(value) {
+  return /^(?:arkgate-mcp|ark-mcp)(?:\.mjs)?$/.test(
+    path.basename(value.trim().replace(/\\/g, '/'))
   );
 }
 
+function arkMcpInvocation(server) {
+  if (!server || typeof server !== 'object' || typeof server.command !== 'string') return false;
+  if (server.args !== undefined && !Array.isArray(server.args)) return false;
+  const args = server.args ?? [];
+  if (!args.every((value) => typeof value === 'string')) return false;
+  const argv = [server.command, ...args];
+  if (argv.filter(isArkMcpToken).length !== 1) return false;
+  if (isArkMcpToken(server.command)) return { argv, binIndex: 0 };
+  const runner = path.basename(server.command.trim().replace(/\\/g, '/'));
+  if (['npx', 'yarn'].includes(runner) && isArkMcpToken(args[0])) {
+    return { argv, binIndex: 1 };
+  }
+  if (runner === 'node') {
+    const script = args[0]?.replace(/\\/g, '/');
+    return isArkMcpToken(script) && /(?:^|\/)bin\/ark-mcp\.mjs$/.test(script)
+      ? { argv, binIndex: 1 }
+      : false;
+  }
+  if (runner === 'pnpm') {
+    const prefix = args[0] === 'exec'
+      ? 1
+      : args[0] === '--config.verify-deps-before-run=false' && args[1] === 'exec'
+        ? 2
+        : 0;
+    return prefix > 0 && isArkMcpToken(args[prefix])
+      ? { argv, binIndex: prefix + 1 }
+      : false;
+  }
+  return false;
+}
+
+function mcpServerRunsArk(server) {
+  return Boolean(arkMcpInvocation(server));
+}
+
+function commandArkMcpInvocation(command) {
+  if (typeof command !== 'string') return false;
+  const words = [];
+  for (const match of command.matchAll(/"([^"]*)"|'([^']*)'|(&&|\|\||[;|#])|([^\s;&|#]+)/g)) {
+    if (match[3]) break;
+    words.push(match[1] ?? match[2] ?? match[4]);
+  }
+  if (path.basename(words[0]?.replace(/\\/g, '/') ?? '') === 'env') words.shift();
+  const environment = {};
+  while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0] ?? '')) {
+    const assignment = words.shift();
+    const split = assignment.indexOf('=');
+    const value = assignment.slice(split + 1);
+    environment[assignment.slice(0, split)] = /^(['"]).*\1$/.test(value)
+      ? value.slice(1, -1)
+      : value;
+  }
+  const [executable, ...args] = words;
+  const invocation = arkMcpInvocation({ command: executable, args });
+  return invocation
+    ? { ...invocation, binArgs: invocation.argv.slice(invocation.binIndex + 1), environment }
+    : false;
+}
+
+function requiredWriteOperations(relativePath) {
+  return relativePath.startsWith('.grok/')
+    ? ['write', 'search_replace']
+    : ['Write', 'Edit', 'MultiEdit'];
+}
+
+function matcherOperations(relativePath, matcher) {
+  const required = requiredWriteOperations(relativePath);
+  if (typeof matcher !== 'string' || matcher.trim() === '') return required;
+  try {
+    const pattern = new RegExp(`^(?:${matcher})$`);
+    return required.filter((operation) => pattern.test(operation));
+  } catch {
+    return [];
+  }
+}
+
+function jsonArkMcpIsValid(text) {
+  try {
+    return mcpServerRunsArk(JSON.parse(text)?.mcpServers?.ark);
+  } catch {
+    return false;
+  }
+}
+
+function tomlMcpBlockIsValid(block) {
+  const matches = [
+    ...block.matchAll(
+      /^[ \t]*command[ \t]*=[ \t]*("(?:\\.|[^"\\])*"|'[^']*')[ \t]*(?:#.*)?$/gm
+    ),
+  ];
+  const args = extractCodexArgsFromBlock(block);
+  if (matches.length !== 1 || !args) return false;
+  const validLine = (line) =>
+    /^[ \t]*(?:#.*)?$/.test(line) ||
+    /^[ \t]*\[.*\][ \t]*(?:#.*)?$/.test(line) ||
+    /^[ \t]*command[ \t]*=[ \t]*("(?:\\.|[^"\\])*"|'[^']*')[ \t]*(?:#.*)?$/.test(line) ||
+    /^[ \t]*args[ \t]*=[ \t]*\[[^\]\r\n]*\][ \t]*(?:#.*)?$/.test(line);
+  if (block.split('\n').some((line) => !validLine(line))) return false;
+  let command;
+  try {
+    command = matches[0][1].startsWith('"')
+      ? JSON.parse(matches[0][1])
+      : matches[0][1].slice(1, -1);
+  } catch {
+    return false;
+  }
+  return mcpServerRunsArk({ command, args });
+}
+
+function tomlArkMcpIsValid(text) {
+  const primary = listCodexArkServerTables(text).filter((entry) => entry.table === 'ark');
+  return primary.length === 1 && tomlMcpBlockIsValid(primary[0].block);
+}
+
 function hookEvidence(root, relativePath) {
   const text = readText(path.join(root, relativePath));
-  const hard = Boolean(text && /--hook\b/.test(text));
-  const repair = Boolean(
-    hard &&
-      (/--hook-repair\b/.test(text) ||
-        /ARK_HOOK_REPAIR\s*=\s*['"]?(1|true|yes|on)/i.test(text))
+  let hooks = [];
+  try {
+    const groups = JSON.parse(text)?.hooks?.PreToolUse;
+    if (Array.isArray(groups)) {
+      hooks = groups.flatMap((group) =>
+        Array.isArray(group?.hooks)
+          ? group.hooks
+              .filter((hook) => !hook?.type || hook.type === 'command')
+              .map((hook) => ({
+                hook,
+                invocation: commandArkMcpInvocation(hook?.command),
+                operations: matcherOperations(relativePath, group.matcher),
+              }))
+              .filter((entry) => entry.invocation)
+          : []
+      );
+    }
+  } catch {
+    hooks = [];
+  }
+  const hardHooks = hooks.filter((entry) => entry.invocation.binArgs.includes('--hook'));
+  const required = requiredWriteOperations(relativePath);
+  const hard = required.every((operation) =>
+    hardHooks.some((entry) => entry.operations.includes(operation))
+  );
+  const repair = hard && required.every((operation) =>
+    hardHooks.some(({ hook, invocation, operations }) =>
+      operations.includes(operation) &&
+      (invocation.binArgs.includes('--hook-repair') ||
+        /^(?:1|true|yes|on)$/i.test(
+          String(hook.env?.ARK_HOOK_REPAIR ?? invocation.environment.ARK_HOOK_REPAIR ?? '')
+        ))
+    )
   );
   return {
     hard: hard ? [relativePath] : [],
@@ -151,20 +292,25 @@ function hookEvidence(root, relativePath) {
 
 function mcpEvidence(root, relativePath) {
   const text = readText(path.join(root, relativePath));
-  return isArkMcpText(text) ? [relativePath] : [];
+  const valid = relativePath.endsWith('.toml')
+    ? tomlArkMcpIsValid(text)
+    : jsonArkMcpIsValid(text);
+  return valid ? [relativePath] : [];
 }
 
 function codexMcpEvidence(root) {
   const projectFile = path.join(root, '.codex', 'config.toml');
   const projectText = readText(projectFile);
-  const projectRegistered = codexProjectMcpIsValid(projectText, root);
+  const projectRegistered =
+    codexProjectMcpIsValid(projectText, root) && tomlArkMcpIsValid(projectText);
   if (projectRegistered) return ['.codex/config.toml'];
 
   const file = codexConfigPath();
   const text = readText(file);
   const resolvedRoot = path.resolve(root);
-  const registered = listCodexArkServerTables(text).some((entry) => {
-    if (!entry.root || !/\b(ark|arkgate)-mcp\b/.test(entry.block)) return false;
+  const tables = listCodexArkServerTables(text);
+  const registered = new Set(tables.map((entry) => entry.table)).size === tables.length && tables.some((entry) => {
+    if (!entry.root || !tomlMcpBlockIsValid(entry.block)) return false;
     return path.resolve(entry.root) === resolvedRoot;
   });
   return registered ? [relativeEvidencePath(root, file)] : [];
@@ -227,11 +373,13 @@ export function detectWritePathInventory(root) {
     capabilities: capabilityMap(evidence),
     evidence,
     hosts,
+    ci,
   };
 }
 
 export function buildWritePathCapabilityModel(root, explicitHost, attempt) {
   const inventory = detectWritePathInventory(root);
+  const ci = inventory.ci;
   const detectedHost = explicitHost ?? detectActiveAgentHost();
   const activeHost = KNOWN_HOSTS.includes(detectedHost) ? detectedHost : 'unknown';
   const activeRecord = inventory.hosts[activeHost];
@@ -244,7 +392,7 @@ export function buildWritePathCapabilityModel(root, explicitHost, attempt) {
         'merge-gate': [...inventory.evidence['merge-gate']],
       };
 
-  return {
+  const model = {
     activeHost,
     support: getHostSupportProfile(activeHost),
     capabilities: capabilityMap(capabilityEvidence),
@@ -257,4 +405,7 @@ export function buildWritePathCapabilityModel(root, explicitHost, attempt) {
     ),
     inventory,
   };
+  model.enforcementState = buildEnforcementState(root, { ...model, ci });
+  model.enforcementLadder.ciMerge.requiredStatus = model.enforcementState.ciMerge.required;
+  return model;
 }

package/bin/lib/write-path-detect.mjs

@@ -17,7 +17,7 @@ function installToolsForHost(activeHost) {
 
 export function detectWritePathCapabilities(root, explicitHost, attempt) {
   const model = buildWritePathCapabilityModel(root, explicitHost, attempt);
-  const { activeHost, support, capabilities, capabilityEvidence, enforcementLadder, inventory } = model;
+  const { activeHost, support, capabilities, capabilityEvidence, enforcementLadder, enforcementState, inventory } = model;
   const hardWrite = capabilities['hard-write'];
   const advisoryWrite = capabilities['advisory-write'];
   const repairPayload = capabilities['repair-payload'];
@@ -78,7 +78,7 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
           'not equivalent to Claude/Grok PreToolUse hard-write + repair). ' +
           'The hard merge backstop is CI --strict-merge plus a required status check.'
         : `Active host ${activeHost} has advisory prepare-write/autoPatch tools, ` +
-          'but no hard write boundary; the CI check can still reject the change before merge.';
+          'but no hard write boundary; CI can report failure, while merge blocking requires provider policy.';
     gap = {
       id: 'write-path-mcp-only',
       severity: 'info',
@@ -99,6 +99,7 @@ export function detectWritePathCapabilities(root, explicitHost, attempt) {
     capabilities,
     capabilityEvidence,
     enforcementLadder,
+    enforcementState,
     inventory,
     // Compatibility projection for existing doctor/API consumers.
     mode,