arkgate 4.8.22 → 4.8.24

package/bin/ark-mcp.mjs

@@ -23,6 +23,8 @@ function launcherArgs(argv) {
     failOnNewSmells: /^(?:1|true|yes|on)$/i.test(
       String(process.env.ARK_FAIL_ON_NEW_SMELLS ?? '').trim()
     ),
+    help: false,
+    version: false,
   };
   for (let index = 2; index < argv.length; index += 1) {
     const value = argv[index];
@@ -35,6 +37,8 @@ function launcherArgs(argv) {
     else if (value === '--config' && argv[index + 1]) args.config = argv[++index];
     else if (value === '--manifest' && argv[index + 1]) args.manifest = argv[++index];
     else if (value === '--tsconfig' && argv[index + 1]) args.tsconfig = argv[++index];
+    else if (value === '--help' || value === '-h') args.help = true;
+    else if (value === '--version' || value === '-V' || value === '-v') args.version = true;
   }
   return args;
 }
@@ -92,13 +96,56 @@ async function tryResidentHook(args, hookInput) {
   return response;
 }
 
+const USAGE = `Usage: arkgate-mcp [--root <dir>] [--config <file>] [--manifest <file>] [--tsconfig <file>]
+                   [--hook | --hook-repair] [--fail-on-new-smells] [--root-env <VAR[,VAR]>]
+                   [--session-context]
+
+Starts the ArkGate MCP stdio server (JSON-RPC on stdin/stdout). With --hook, runs one
+PreToolUse write-gate evaluation from the host payload on stdin: exit 0 allows, exit 2
+blocks (a gate that cannot run blocks governed source writes too).
+
+  -h, --help     Show this help
+  -V, --version  Print the arkgate version
+`;
+
 const args = launcherArgs(process.argv);
+if (args.version) {
+  const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+if (args.help) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
 let hookInput;
+let hookRoot;
 let residentHandled = false;
 try {
   if (args.hook) {
     hookInput = fs.readFileSync(0, 'utf8');
-    const resident = await tryResidentHook(args, hookInput);
+    // Root: a set --root-env var or a root holding the config, else walk up from the
+    // payload (file, cwd, workspace roots) to the nearest config, like ark-check.
+    const { discoverHookRoot, hookOutsideArkProjectResponse } = await import(
+      './lib/mcp-hook-payload.mjs'
+    );
+    const discovered = discoverHookRoot({ argv: process.argv, hookInput });
+    if (!discovered.configFound && discovered.configExplicit) {
+      // No Ark project owns this write (4.8.23 never blocked it either).
+      const response = hookOutsideArkProjectResponse({
+        hookInput,
+        config: args.config,
+        grokHookEvent: Boolean(process.env.GROK_HOOK_EVENT),
+      });
+      if (response.stdout) process.stdout.write(response.stdout);
+      if (response.stderr) process.stderr.write(response.stderr);
+      process.exitCode = response.status;
+      residentHandled = true;
+    } else {
+      hookRoot = discovered.root;
+      args.root = hookRoot;
+    }
+    const resident = residentHandled ? null : await tryResidentHook(args, hookInput);
     if (resident) {
       if (resident.stdout) process.stdout.write(resident.stdout);
       if (resident.stderr) process.stderr.write(resident.stderr);
@@ -108,9 +155,26 @@ try {
   }
   if (!residentHandled) {
     const runtime = await import('./ark-mcp-runtime.mjs');
-    await runtime.runArkMcp({ hookInput });
+    await runtime.runArkMcp({ hookInput, hookRoot });
   }
 } catch (error) {
-  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-  process.exitCode = 1;
+  if (args.hook) {
+    // Hosts treat exit 1 as non-blocking: a gate that cannot run must not fail open
+    // for governed source writes. Plumbing cases (bad payload, non-source) still allow.
+    const { hookFailClosedResponse, hookRootFromArgv } = await import('./lib/mcp-hook-payload.mjs');
+    const response = hookFailClosedResponse({
+      hookInput,
+      error,
+      root: hookRoot ?? hookRootFromArgv(process.argv),
+      grokHookEvent: Boolean(process.env.GROK_HOOK_EVENT),
+    });
+    if (response.stdout) process.stdout.write(response.stdout);
+    process.stderr.write(
+      response.stderr || `${error instanceof Error ? error.message : String(error)}\n`
+    );
+    process.exitCode = response.status;
+  } else {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
 }

package/bin/ark-shared.mjs

@@ -2262,3 +2262,42 @@ export function loadPolicyPackMeta(packId, packsPath = defaultPolicyPacksPath())
   }
   return pack;
 }
+
+/**
+ * Unique starter ArkRules ids. Rule ids must be unique across arkrules/*.json
+ * (`ark-check --promote <id> --apply` refuses an id declared in two documents), and several
+ * project layers can clone the same archetype template. A clone for a layer other than the
+ * archetype's own therefore gets its ids prefixed with the kebab-cased layer name
+ * (`INV-*` invariants keep their prefix: `INV-<LAYER>-…`).
+ */
+
+export function kebabLayerName(layerName) {
+  return String(layerName)
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[^A-Za-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase();
+}
+
+/**
+ * @param {{ layer?: string, structure?: unknown[], invariants?: unknown[] }} archetype parsed template
+ * @param {string} layerName target project layer
+ */
+export function cloneArchetypeForLayer(archetype, layerName) {
+  const prefix =
+    archetype.layer && archetype.layer !== layerName ? `${kebabLayerName(layerName)}-` : '';
+  const prefixedId = (id) =>
+    id.startsWith('INV-') ? `INV-${prefix.toUpperCase()}${id.slice('INV-'.length)}` : `${prefix}${id}`;
+  const withPrefix = (rules) =>
+    Array.isArray(rules)
+      ? rules.map((rule) =>
+          prefix && rule && typeof rule.id === 'string' ? { ...rule, id: prefixedId(rule.id) } : rule
+        )
+      : rules;
+  return {
+    ...archetype,
+    layer: layerName,
+    structure: withPrefix(archetype.structure),
+    invariants: withPrefix(archetype.invariants),
+  };
+}

package/bin/ark.mjs

@@ -20,7 +20,9 @@ import {
   resolveOperatingMode,
   shouldSkipArkgateInstall,
 } from './ark-shared.mjs';
-import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
+import { FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
+
+export { ensureProjectArkgateDependency };
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 import {
   applyStartPreview,
@@ -30,7 +32,9 @@ import {
   renderStartPreview,
 } from './lib/start-preview.mjs';
 import {
+  ensureProjectArkgateDependency,
   formatStartPackageInstallFailure,
+  pinArkgateForSetup,
   runStartPackageInstall,
 } from './lib/start-install-recovery.mjs';
 import { runUpgradeCommand } from './lib/upgrade-command.mjs';
@@ -47,50 +51,34 @@ import { runStatusCommand } from './lib/status-command.mjs';
 import { runAgentProjectionCommand } from './lib/agent-projection-command.mjs';
 import { setupUsage, setupUsageAll, upgradeUsage } from './lib/first-run-help.mjs';
 import { runUpstreamReportCommand } from './lib/upstream-report.mjs';
+import {
+  dashboardHelp,
+  isMcpCommand,
+  isPassthroughCommand,
+  runDashboard,
+  runMcp,
+  withDashboardHelp,
+} from './lib/passthrough-commands.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
-const arkDashboard = path.join(here, 'ark-dashboard.mjs');
-const dashboardHelp = `arkgate dashboard (alias ark dashboard) — observability TUI.
-Usage: arkgate dashboard [--url <snapshot-url>] [--interval <ms>]
-Polls an ArkRun inspector; it does not start the kernel.`;
-
-function withDashboardHelp(text, detailed) {
-  const extra = detailed
-    ? '  arkgate dashboard [--url <snapshot-url>] [--interval <ms>]\n  arkgate report  [--root <project>] [--json] [--title <text>] [--finding <ref>] [--submit] [--i-confirm-submit]\n'
-    : '';
-  const extraDesc = detailed
-    ? '  dashboard  ANSI observability TUI (spawns ark-dashboard).\n  report     Draft an upstream GitHub issue for pedroknigge/arkgate. Create needs --submit plus confirm. --yes does not submit.\n'
-    : '';
-  if (detailed) {
-    return text
-      .replace('  arkgate agents-md [--root', `${extra}  arkgate agents-md [--root`)
-      .replace('  agents-md Version-matched', `${extraDesc}  agents-md Version-matched`);
-  }
-  return text.replace(
-    '  arkgate-check --doctor     status — one next step\n',
-    '  arkgate-check --doctor     status — one next step\n  arkgate dashboard         observability TUI (inspector)\n  arkgate report            draft an upstream GitHub issue\n'
-  );
-}
-
-function runDashboard(passthroughArgs) {
-  const result = spawnSync(process.execPath, [arkDashboard, ...passthroughArgs], {
-    stdio: 'inherit',
-    encoding: 'utf8',
-  });
-  return result.status ?? 1;
-}
-
 /**
  * Day-zero architecture picture: freeze origin under `.ark/reports/` as soon as
  * `ark.config.json` exists — **before** agent docs, skills, CI templates, or cleanups.
  * Idempotent: origin is written only once (`--report` archive semantics).
  */
+/**
+ * Day-zero HTML lives under `.ark/reports/`, never as a stray root artifact. The report
+ * writer appends an `.ark/` rule only to an existing `.gitignore` (EH03); a fresh project
+ * without one still sees `.ark/` as untracked.
+ */
+const DAY_ZERO_REPORT_PATH = path.join('.ark', 'reports', 'latest.html');
+
 function freezeDayZeroOrigin(root) {
   const configPath = path.join(root, 'ark.config.json');
   if (!fs.existsSync(configPath)) {
     console.log(
-      `  Skip origin freeze — no ark.config.json yet. After init: ${arkCommand(root, 'ark-check', '--report ark-report.html')}`
+      `  Skip origin freeze — no ark.config.json yet. After init: ${arkCommand(root, 'ark-check', '--report .ark/reports/latest.html')}`
     );
     return;
   }
@@ -102,11 +90,14 @@ function freezeDayZeroOrigin(root) {
       : 'Freezing day-zero architecture picture (origin) before agent docs / gates…'
   );
   runArkCheck(
-    ['--root', root, '--config', 'ark.config.json', '--report', 'ark-report.html'],
+    ['--root', root, '--config', 'ark.config.json', '--report', DAY_ZERO_REPORT_PATH],
     { cwd: root }
   );
 }
 
+/** Commands that read a non-default contract file via --config. */
+const CONFIG_FLAG_COMMANDS = new Set(['preflight', 'status', 'agents-md', 'agent-projection']);
+
 function parseArgs(argv) {
   const args = {
     command: undefined,
@@ -191,8 +182,8 @@ function parseArgs(argv) {
     else if (arg === '--version' || arg === '-V') args.version = true;
     else if (!arg.startsWith('-') && args.command === undefined) {
       args.command = arg;
-      // Dashboard owns its flags (--url/--interval); pass the rest through untouched.
-      if (arg === 'dashboard' || arg === 'report') {
+      // dashboard / report / mcp own their flags; pass the rest through untouched.
+      if (isPassthroughCommand(arg)) {
         args.passthrough = argv.slice(i + 1);
         break;
       }
@@ -265,33 +256,6 @@ async function askYesNo(rl, question, defaultYes = true) {
   return answer === 'y' || answer === 'yes';
 }
 
-/**
- * Pin arkgate in package.json (and optionally run the package manager).
- * start calls this so CI/`npx` is not forced to rely on a stale global install.
- *
- * @param {string} root
- * @param {{ install?: boolean, runPackageManager?: boolean }} [opts]
- */
-export function ensureProjectArkgateDependency(root, opts = {}) {
-  const install = opts.install !== false;
-  const runPm = opts.runPackageManager === true;
-  if (!install) {
-    return { pinned: { changed: false, reason: 'skipped-no-install' }, installStatus: null };
-  }
-  const pinned = pinArkgateDevDependency(root);
-  let installStatus = null;
-  let hostOutput = '';
-  // Only run the package manager after a successful pin change — avoid surprise
-  // network on every start when arkgate is already listed.
-  if (runPm && pinned.changed) {
-    const [command, commandArgs] = packageInstallArgv(root, pinned.version);
-    const install = runStartPackageInstall(command, commandArgs, root);
-    installStatus = install.status;
-    hostOutput = `${install.stdout}\n${install.stderr}`;
-  }
-  return { pinned, installStatus, hostOutput };
-}
-
 async function resolveArchetypeInteractive(rl, root) {
   console.log('');
   console.log('What are you building? (application shape — not a framework name)');
@@ -384,6 +348,10 @@ async function init(args) {
       console.log('Skipped ark.config.json generation.');
     }
 
+    // Pin arkgate before the gate templates that call its bins (CI workflow, host hooks, MCP).
+    console.log('');
+    pinArkgateForSetup(root, args, cliVersion);
+
     // Origin first: contract-on-tree picture before AGENTS.md / skills / CI templates.
     console.log('');
     freezeDayZeroOrigin(root);
@@ -447,7 +415,12 @@ async function start(args) {
         confidence: preview.analysis?.confidence,
         projectedCoveragePercent: preview.projectedCoverage?.percent,
         totalFiles: preview.projectedCoverage?.totalFiles,
-        explicitShape: Boolean(args.archetype || args.preset),
+        // An existing ark.config.json is a locked shape: start keeps it verbatim, so an
+        // idempotent re-run (or the remove-host restore command) must not be re-gated on
+        // auto-detected confidence. Low coverage still surfaces as an unresolved decision.
+        explicitShape:
+          Boolean(args.archetype || args.preset) ||
+          fs.existsSync(path.join(args.root, 'ark.config.json')),
         force: Boolean(args.force),
       });
       if (!gate.ok) {
@@ -493,8 +466,11 @@ async function start(args) {
     }
     // After applying exact preview bytes, install the pinned package when requested
     // (preview itself never runs the package manager — field: start left pin without node_modules).
+    // Host removal never needs the package: no network, no package.json edits.
     if (
       args.install &&
+      !args.removeHost &&
+      preview.mode !== 'remove-host' &&
       !args.skipPackageManager &&
       fs.existsSync(path.join(args.root, 'package.json'))
     ) {
@@ -549,9 +525,18 @@ async function start(args) {
       rec = undefined;
     }
 
-    // 2) Suggest a shape, in plain language, and confirm.
-    let archetype = rec?.archetype;
-    if (rec) {
+    // 2) Suggest a shape, in plain language, and confirm. An explicit --archetype/--preset
+    // locks the shape: it must drive the written contract, not just bypass the preview gate.
+    const explicitShape = resolveInitPreset(args);
+    let archetype = explicitShape ? explicitShape.archetype : rec?.archetype;
+    if (explicitShape) {
+      console.log('');
+      console.log(
+        explicitShape.archetype
+          ? `Using your shape: ${explicitShape.archetype} → preset ${explicitShape.preset}.`
+          : `Using your preset: ${explicitShape.preset}.`
+      );
+    } else if (rec) {
       console.log('');
       console.log(`Your project looks like: ${rec.label}.`);
       if (rec.analogy) console.log(`In plain terms — ${rec.analogy}`);
@@ -573,30 +558,7 @@ async function start(args) {
 
     // 2b) Pin arkgate as a project devDependency so CI/npx do not depend on a stale global.
     // Default install=true; only --no-install skips. (installExplicit tracks user override for copy.)
-    if (args.install && fs.existsSync(path.join(root, 'package.json'))) {
-      const { pinned, installStatus, hostOutput } = ensureProjectArkgateDependency(root, {
-        install: true,
-        runPackageManager: !args.skipPackageManager,
-      });
-      if (pinned.changed) {
-        console.log(`  Pinned arkgate@${pinned.version} in package.json devDependencies.`);
-        if (installStatus !== null && installStatus !== 0) {
-          const [command, commandArgs] = packageInstallArgv(root, pinned.version);
-          console.error(
-            formatStartPackageInstallFailure({
-              exitStatus: installStatus,
-              installCommand: `${command} ${commandArgs.join(' ')}`,
-              hostOutput,
-              packageVersion: cliVersion(),
-            })
-          );
-        }
-      } else if (pinned.reason === 'already-present') {
-        console.log(`  arkgate already in package.json (${pinned.version}).`);
-      }
-    } else if (!args.install) {
-      console.log('  Skipping arkgate package pin (--no-install).');
-    }
+    pinArkgateForSetup(root, args, cliVersion);
 
     // 3) Contract first (config only). Greenfield → shape preset; established repo → detection,
     // so the contract anchors to directories you already have instead of aspirational globs.
@@ -605,7 +567,10 @@ async function start(args) {
     const configPath = path.join(root, 'ark.config.json');
     if (!fs.existsSync(configPath)) {
       const initArgs = ['--root', root, '--init'];
-      const startPreset = resolveStartInitPreset(root, rec ?? {}, archetype);
+      // Explicit shape bypasses detection entirely (monorepo/ui-surface heuristics included).
+      const startPreset = explicitShape?.preset
+        ? explicitShape.preset
+        : resolveStartInitPreset(root, rec ?? {}, archetype);
       const includeRoots = resolveIncludeRoots(root);
       const tsPackages = detectTsPackageRoots(root);
       const nestedTsPackages = tsPackages.filter((entry) => entry !== '.');
@@ -814,6 +779,8 @@ async function main() {
     console.error(error instanceof Error ? error.message : String(error));
     return 2;
   }
+  // Before --version/--help: the MCP server owns stdout (JSON-RPC) and all of its flags.
+  if (isMcpCommand(args.command)) return runMcp(args.passthrough);
   if (args.version) {
     console.log(cliVersion());
     return 0;
@@ -843,12 +810,13 @@ async function main() {
   }
   if (
     args.command !== 'preflight' &&
-    (args.changes || args.changeMap || args.manifest || args.tsconfig ||
-      args.config !== 'ark.config.json')
+    (args.changes || args.changeMap || args.manifest || args.tsconfig)
   ) {
-    console.error(
-      '--changes, --change-map, --config, --manifest, and --tsconfig are supported by ark preflight.'
-    );
+    console.error('--changes, --change-map, --manifest, and --tsconfig are supported by ark preflight.');
+    return 2;
+  }
+  if (args.config !== 'ark.config.json' && !CONFIG_FLAG_COMMANDS.has(args.command)) {
+    console.error('--config is supported by ark preflight, ark status, and ark agents-md.');
     return 2;
   }
   const enforcement = validateHardWriteRequest({

package/bin/lib/adapter-contract-types.mjs

@@ -118,6 +118,11 @@ export const ARK_ANALYSIS_RESULT_SCHEMA = {
                             edgeKind: { type: 'string', minLength: 1 },
                             arkruleId: { type: 'string', minLength: 1 },
                             arkruleSource: { type: 'string', minLength: 1 },
+                            reasonId: {
+                                enum: ['CROSS_PARENT_SLICE', 'CROSS_SIBLING_SLICE', 'CROSS_PARENT_VIA_SHARED'],
+                            },
+                            universeFrom: { type: 'string', minLength: 1 },
+                            universeTo: { type: 'string', minLength: 1 },
                         },
                     },
                     nextAction: { type: 'string', minLength: 1 },

package/bin/lib/adapter-contract.mjs

@@ -35,8 +35,19 @@ function nextActionForDiagnostic(ruleId, evidence, violation) {
         capability: text(evidence.capability) ?? text(violation.capability) ?? undefined,
         arkruleId: text(evidence.arkruleId) ?? undefined,
         arkruleSource: text(evidence.arkruleSource) ?? undefined,
+        reasonId: text(evidence.reasonId) ?? undefined,
     });
 }
+const SLICE_REASON_IDS = new Set(['CROSS_PARENT_SLICE', 'CROSS_SIBLING_SLICE', 'CROSS_PARENT_VIA_SHARED']);
+/** Nested-wall reason from the top level or from gate `details`. */
+function sliceReasonOf(violation) {
+    const details = violation.details;
+    const nested = details !== null && typeof details === 'object' ? details.reasonId : undefined;
+    const raw = text(violation.reasonId) ?? text(nested);
+    return raw && SLICE_REASON_IDS.has(raw)
+        ? raw
+        : undefined;
+}
 export function toAdapterDiagnostic(violation, fallbackSeverity = 'error', 
 /**
  * Optional precomputed baseline-compatible targetKey (e.g. occurrence-aware from
@@ -50,6 +61,7 @@ targetKeyOverride) {
         (violation.typeOnly === true && violation.peerIsolation !== true)
         ? 'warning'
         : fallbackSeverity;
+    const reasonId = sliceReasonOf(violation);
     const evidence = {
         ...(text(violation.target) ? { target: text(violation.target) } : {}),
         ...(text(violation.fromLayer) ? { fromLayer: text(violation.fromLayer) } : {}),
@@ -74,6 +86,9 @@ targetKeyOverride) {
         ...(text(violation.edgeKind) ? { edgeKind: text(violation.edgeKind) } : {}),
         ...(text(violation.arkruleId) ? { arkruleId: text(violation.arkruleId) } : {}),
         ...(text(violation.arkruleSource) ? { arkruleSource: text(violation.arkruleSource) } : {}),
+        ...(reasonId ? { reasonId } : {}),
+        ...(reasonId && text(violation.universeFrom) ? { universeFrom: text(violation.universeFrom) } : {}),
+        ...(reasonId && text(violation.universeTo) ? { universeTo: text(violation.universeTo) } : {}),
     };
     const targetKey = targetKeyOverride ?? adapterFindingTargetKey(violation);
     const findingRef = adapterFindingRefFromTargetKey(targetKey);

package/bin/lib/agent-projection-command.mjs

@@ -71,15 +71,18 @@ export function collectAgentProjectionFacts(options = {}) {
   const startRoot = path.resolve(options.root || process.cwd());
   const configName = options.config || 'ark.config.json';
   let resolvedRoot = startRoot;
+  let configPath = null;
   try {
     const resolved = resolveEffectiveProjectRoot(startRoot, {
       configName,
       writeMode: false,
     });
     resolvedRoot = path.resolve(resolved.root || startRoot);
+    if (resolved.configFound && resolved.configPath) configPath = path.resolve(resolved.configPath);
   } catch {
     resolvedRoot = startRoot;
   }
+  if (!configPath) configPath = path.resolve(resolvedRoot, configName);
 
   const version =
     (typeof options.arkgateVersion === 'string' && options.arkgateVersion.trim()) ||
@@ -88,7 +91,8 @@ export function collectAgentProjectionFacts(options = {}) {
 
   let layers = options.layers;
   if (layers === undefined) {
-    layers = loadConfigLayersForAgents(resolvedRoot);
+    // Read the contract the caller named (--config), not a hardcoded ark.config.json.
+    layers = loadConfigLayersForAgents(resolvedRoot, configPath);
   }
 
   const layerSummaries = Array.isArray(layers)