arkgate 4.8.22 → 4.8.24

package/bin/lib/effective-contract-load.mjs

@@ -1,6 +1,10 @@
 /**
  * Tooling adapter: load Effective Contract from disk for a root config.
  * Pure resolution lives in Domain (`resolveEffectiveContract`); this module owns I/O.
+ *
+ * `loadEffectiveArkRules` is the source-agnostic core (working tree, a policy base
+ * ref, or supplied file objects all pass the same path validation); only the
+ * reader differs.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -10,7 +14,7 @@ import {
   loadArkRulesContract,
 } from './arkrules-contract.mjs';
 
-function normalizeProjectRelativePath(value) {
+export function normalizeProjectRelativePath(value) {
   const normalized = value.replace(/\\/g, '/');
   if (
     !normalized ||
@@ -29,7 +33,7 @@ function normalizeProjectRelativePath(value) {
   return segments.length > 0 ? segments.join('/') : undefined;
 }
 
-function isWithinRoot(root, candidate) {
+export function isWithinRoot(root, candidate) {
   const relative = path.relative(root, candidate);
   return (
     relative === '' ||
@@ -40,26 +44,29 @@ function isWithinRoot(root, candidate) {
 }
 
 /**
- * @param {string} root
+ * @typedef {{ ok: true, content: string } | { ok: false, missing?: boolean, message: string }} ArkRulesRead
+ */
+
+/**
+ * Core loader shared by every source.
+ *
  * @param {Record<string, unknown>} config loaded ark.config.json object
- * @param {{ observeInput?: (abs: string, kind: string) => void }} [opts]
- * @returns {{ arkRules: ReturnType<typeof emptyEffectiveArkRules>, warnings: Array<{path:string,message:string,severity:string}>, errors: Array<{path:string,message:string}> }}
+ * @param {(rel: string) => ArkRulesRead} readRelative
+ * @param {{ missingAsEmpty?: boolean }} [opts] missingAsEmpty: a referenced file absent
+ *   from the source counts as an empty layer (a base that predates the file), not an error.
+ * @returns {{ arkRules: ReturnType<typeof emptyEffectiveArkRules>, errors: Array<{path:string,message:string}>, referenced: Set<string> }}
  */
-export function loadEffectiveArkRulesFromDisk(root, config, opts = {}) {
+export function loadEffectiveArkRules(config, readRelative, opts = {}) {
   const refs = config?.arkRules;
+  const referenced = new Set();
   if (!refs || typeof refs !== 'object' || Object.keys(refs).length === 0) {
-    return { arkRules: emptyEffectiveArkRules(), warnings: [], errors: [] };
+    return { arkRules: emptyEffectiveArkRules(), errors: [], referenced };
   }
-
   const layerNames = new Set(
     Array.isArray(config.layers) ? config.layers.map((layer) => layer.name) : []
   );
   const errors = [];
-  const warnings = [];
   const parts = [];
-  const referenced = new Set();
-  const canonicalRoot = fs.realpathSync(root);
-
   for (const layer of Object.keys(refs).sort()) {
     const relRaw = refs[layer];
     const pathKey = `$.arkRules[${JSON.stringify(layer)}]`;
@@ -83,70 +90,102 @@ export function loadEffectiveArkRulesFromDisk(root, config, opts = {}) {
       });
       continue;
     }
-
     referenced.add(rel);
-    const lexicalTarget = path.resolve(canonicalRoot, ...rel.split('/'));
-    if (!isWithinRoot(canonicalRoot, lexicalTarget)) {
+    const read = readRelative(rel);
+    if (!read.ok) {
+      if (read.missing && opts.missingAsEmpty) continue;
+      errors.push({ path: pathKey, message: read.message });
+      continue;
+    }
+    try {
+      const loaded = loadArkRulesContract(JSON.parse(read.content), rel, layer);
+      parts.push({ layer, sourceFile: rel, file: loaded.config });
+    } catch (error) {
       errors.push({
         path: pathKey,
-        message: `referenced ArkRules path ${JSON.stringify(rel)} resolves outside the project root`,
+        message:
+          error instanceof Error
+            ? error.message
+            : `referenced ArkRules file ${JSON.stringify(rel)} failed to load`,
       });
-      continue;
     }
+  }
+  if (errors.length > 0) return { arkRules: emptyEffectiveArkRules(), errors, referenced };
+  return { arkRules: buildEffectiveArkRules(parts), errors: [], referenced };
+}
+
+/**
+ * Directory reader: realpath + within-root guards, then readFileSync.
+ * @param {string} canonicalRoot realpath of the directory the paths are relative to
+ * @param {{ observeInput?: (abs: string, kind: string) => void }} [opts]
+ * @returns {(rel: string) => ArkRulesRead}
+ */
+export function directoryArkRulesReader(canonicalRoot, opts = {}) {
+  return (rel) => {
+    const lexicalTarget = path.resolve(canonicalRoot, ...rel.split('/'));
+    const outside = {
+      ok: false,
+      message: `referenced ArkRules path ${JSON.stringify(rel)} resolves outside the project root`,
+    };
+    if (!isWithinRoot(canonicalRoot, lexicalTarget)) return outside;
     if (!fs.existsSync(lexicalTarget)) {
-      errors.push({
-        path: pathKey,
+      return {
+        ok: false,
+        missing: true,
         message: `referenced ArkRules file ${JSON.stringify(rel)} is missing`,
-      });
-      continue;
+      };
     }
     let absolute;
     try {
       absolute = fs.realpathSync(lexicalTarget);
     } catch (error) {
-      errors.push({
-        path: pathKey,
+      return {
+        ok: false,
         message: `referenced ArkRules file ${JSON.stringify(rel)} could not be resolved: ${
           error instanceof Error ? error.message : String(error)
         }`,
-      });
-      continue;
-    }
-    if (!isWithinRoot(canonicalRoot, absolute)) {
-      errors.push({
-        path: pathKey,
-        message: `referenced ArkRules path ${JSON.stringify(rel)} resolves outside the project root`,
-      });
-      continue;
+      };
     }
+    if (!isWithinRoot(canonicalRoot, absolute)) return outside;
     opts.observeInput?.(absolute, 'arkrules');
-    let content;
     try {
-      content = fs.readFileSync(absolute, 'utf8');
+      return { ok: true, content: fs.readFileSync(absolute, 'utf8') };
     } catch (error) {
-      errors.push({
-        path: pathKey,
+      return {
+        ok: false,
         message: `referenced ArkRules file ${JSON.stringify(rel)} could not be read: ${
           error instanceof Error ? error.message : String(error)
         }`,
-      });
-      continue;
-    }
-    try {
-      const loaded = loadArkRulesContract(JSON.parse(content), rel, layer);
-      parts.push({ layer, sourceFile: rel, file: loaded.config });
-    } catch (error) {
-      errors.push({
-        path: pathKey,
-        message:
-          error instanceof Error
-            ? error.message
-            : `referenced ArkRules file ${JSON.stringify(rel)} failed to load`,
-      });
+      };
     }
+  };
+}
+
+/**
+ * Reader over supplied ArkRules file objects keyed by project-relative path
+ * (MCP callers hand a catalog as data instead of a checkout).
+ * @param {Record<string, unknown>} files
+ * @returns {(rel: string) => ArkRulesRead}
+ */
+export function objectArkRulesReader(files) {
+  const byPath = new Map();
+  for (const [key, value] of Object.entries(files ?? {})) {
+    const rel = normalizeProjectRelativePath(String(key));
+    if (rel) byPath.set(rel, value);
   }
+  return (rel) =>
+    byPath.has(rel)
+      ? { ok: true, content: JSON.stringify(byPath.get(rel)) }
+      : {
+          ok: false,
+          missing: true,
+          message: `ArkRules file ${JSON.stringify(rel)} was not supplied`,
+        };
+}
 
-  // Drift: unreferenced files under arkrules/
+/** Advisory drift: `arkrules/*.json` files the arkRules map does not reference (ADR 0012 D2). */
+function unreferencedArkRulesWarnings(canonicalRoot, referenced) {
+  const warnings = [];
   const arkrulesDir = path.join(canonicalRoot, 'arkrules');
   const resolvedArkRulesDir = fs.existsSync(arkrulesDir)
     ? fs.realpathSync(arkrulesDir)
@@ -168,13 +207,36 @@ export function loadEffectiveArkRulesFromDisk(root, config, opts = {}) {
       }
     }
   }
+  return warnings;
+}
 
-  if (errors.length > 0) {
-    return { arkRules: emptyEffectiveArkRules(), warnings, errors };
-  }
-  return {
-    arkRules: buildEffectiveArkRules(parts),
-    warnings,
-    errors: [],
-  };
+export const ARKRULE_FILE_UNREFERENCED = 'ARKRULE_FILE_UNREFERENCED';
+
+/**
+ * Loader drift warnings as advisory check warnings (never fail --strict-config).
+ * @param {Array<{path:string,message:string}>} warnings
+ */
+export function arkRulesDriftWarnings(warnings) {
+  return (warnings ?? []).map((warning) => ({
+    ruleId: ARKRULE_FILE_UNREFERENCED,
+    file: warning.path,
+    line: 1,
+    message: warning.message,
+    severity: 'warning',
+    failsStrict: false,
+  }));
+}
+
+/**
+ * @param {string} root
+ * @param {Record<string, unknown>} config loaded ark.config.json object
+ * @param {{ observeInput?: (abs: string, kind: string) => void }} [opts]
+ * @returns {{ arkRules: ReturnType<typeof emptyEffectiveArkRules>, warnings: Array<{path:string,message:string,severity:string}>, errors: Array<{path:string,message:string}> }}
+ */
+export function loadEffectiveArkRulesFromDisk(root, config, opts = {}) {
+  const canonicalRoot = fs.realpathSync(root);
+  const loaded = loadEffectiveArkRules(config, directoryArkRulesReader(canonicalRoot, opts));
+  // Drift runs with or without a map: an arkrules/ directory nobody references is visible.
+  const warnings = unreferencedArkRulesWarnings(canonicalRoot, loaded.referenced);
+  return { arkRules: loaded.arkRules, warnings, errors: loaded.errors };
 }

package/bin/lib/enforcement-honesty.mjs

@@ -289,6 +289,8 @@ export function buildWritePathHonesty(activeHost, hardWriteActive = false, extra
  *   operatingMode?: string | null,
  *   activeBlockingViolations?: number | null,
  *   physicalCohesionResidual?: boolean,
+ *   childWallAdvisory?: boolean,
+ *   sliceAliasDebt?: boolean,
  * }} input
  */
 export function physicalCohesionResidualRemains(cohesion) {
@@ -489,6 +491,22 @@ export function buildProductHonesty(input = {}) {
     // Informational only when no enforced arkrule plane — does not alone make unfinished.
   }
 
+  if (input.childWallAdvisory === true) {
+    reasons.push({
+      id: 'child-wall-advisory',
+      message:
+        'A child wall lists siblings as advisory. Recorded crossings stay non-blocking, and a new sibling crossing past that baseline still fails. An enforce list makes those subtrees errors and does not finish the house. This house stays unfinished until siblings is deny.',
+    });
+  }
+
+  if (input.sliceAliasDebt === true) {
+    reasons.push({
+      id: 'slice-alias-debt',
+      message:
+        'Slice aliases are an owed move, not a destination. Aliased files are not finished until they move into the target slice folder.',
+    });
+  }
+
   // EH05: environment residual deny-list (future reason ids stay architecture debt by default).
   const ENVIRONMENT_REASON_IDS = new Set(['soft-write-host', 'native-fail-open']);
 
@@ -683,6 +701,8 @@ export function computeDoctorEnforcementHonesty({
   nativeFailClosed,
   nativeFailClosedPolicy,
   physicalCohesionResidual,
+  childWallAdvisory,
+  sliceAliasDebt,
 } = {}) {
   const coverageHonesty = buildCoverageHonesty({
     percent: governedPercent,
@@ -741,6 +761,8 @@ export function computeDoctorEnforcementHonesty({
     emptyStewards,
     stewardNudge,
     physicalCohesionResidual,
+    childWallAdvisory,
+    sliceAliasDebt,
   });
   return {
     coverageHonesty,

package/bin/lib/enforcement-profiles.mjs

@@ -10,6 +10,35 @@ import {
   HOST_SUPPORT_MATRIX,
 } from './host-support-matrix.mjs';
 import { KNOWN_TOOLS, normalizeToolsList } from './skill-install.mjs';
+import {
+  antigravityHooks,
+  claudeSettings,
+  codexHooks,
+  cursorHooks,
+  mergeAntigravityArkHook,
+  mergeClaudeStyleArkHooks,
+  mergeCursorArkHook,
+} from './hook-templates.mjs';
+
+/** Hosts whose hook file the installer merges (keeping user keys) instead of replacing. */
+const MERGEABLE_HOOK_FILES = {
+  claude: [claudeSettings, mergeClaudeStyleArkHooks],
+  codex: [codexHooks, mergeClaudeStyleArkHooks],
+  cursor: [cursorHooks, mergeCursorArkHook],
+  antigravity: [antigravityHooks, mergeAntigravityArkHook],
+};
+
+/** True when install will upsert Ark's hook into the existing host file without --force. */
+export function hostHookFileMergeable(root, host, hookFile) {
+  const entry = MERGEABLE_HOOK_FILES[host];
+  if (!entry) return false;
+  try {
+    const [template, merge] = entry;
+    return merge(fs.readFileSync(hookFile, 'utf8'), template(root)) != null;
+  } catch {
+    return false;
+  }
+}
 
 export const HOST_ENFORCEMENT_SUPPORT = Object.freeze(
   Object.fromEntries(
@@ -79,12 +108,19 @@ export function validateHardWriteRequest({ root, host, tools, force = false }) {
   }
 
   const hookFile = path.join(root, support.hookPath);
-  if (fs.existsSync(hookFile) && !force && !hasHardWriteHook(root, normalizedHost)) {
+  if (
+    fs.existsSync(hookFile) &&
+    !force &&
+    !hasHardWriteHook(root, normalizedHost) &&
+    !hostHookFileMergeable(root, normalizedHost, hookFile)
+  ) {
     return {
       ok: false,
-      error:
-        `${support.hookPath} already exists without an Ark hard-write hook and would be preserved. ` +
-        'Use --force to replace that host file, or omit --require-write-hook for merge-only enforcement.',
+      error: MERGEABLE_HOOK_FILES[normalizedHost]
+        ? `${support.hookPath} already exists but is not a JSON object Ark can merge into, so it would be preserved. ` +
+          'Fix that file (or use --force to replace it), or omit --require-write-hook for merge-only enforcement.'
+        : `${support.hookPath} already exists without an Ark hard-write hook and would be preserved. ` +
+          'Use --force to replace that host file, or omit --require-write-hook for merge-only enforcement.',
     };
   }
 

package/bin/lib/first-run-help.mjs

@@ -3,6 +3,7 @@
  */
 
 import { NORTH_STAR_ONE_LINE } from './product-copy.mjs';
+import { KNOWN_TOOLS } from './skill-install.mjs';
 
 export function setupUsage() {
   return `arkgate (alias ark) — Write. Check. Ship.
@@ -96,8 +97,8 @@ Options:
                Valid ids: crud-product, api-backend, frontend-surface, library-sdk, cli-utility,
                worker-pipeline, event-coordinator, integration-bridge, multi-app-workspace, prototype-spike,
                vertical-slice-product, ddd-bounded-contexts.
-  --tools      One active agent host for start (claude,cursor,codex,grok,antigravity,windsurf,cline,copilot,kiro,roo,continue,gemini).
-               Omit to use the active host; an unknown host creates only the shared compact router.
+  --tools      One active agent host for start (${KNOWN_TOOLS.join(',')}).
+               Omit to use the active host; a list or an unknown host is rejected (exit 2).
   --remove-host <host>
                Preview or apply removal of that compact host integration; re-add it with --tools <host>.
   --require-write-hook <host>

package/bin/lib/flat-parent-importers.mjs

@@ -0,0 +1,137 @@
+/**
+ * Importer graph for the flat-parent doctor suggestion.
+ *
+ * Prefers the resolved dependency facts ark-check already built (tsconfig
+ * paths included). Without facts it scans the text and resolves relative
+ * specifiers plus tsconfig path aliases, so an `@/…` importer is never
+ * invisible. Advisory input only.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readTsconfigAliases, resolveSpecifierToRel } from './import-resolve.mjs';
+
+const SPEC_MARKS = [' from "', " from '", ' from `', 'require("', "require('", 'import("', "import('"];
+const EXT = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+
+function withoutComments(text) {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    const n = text[i + 1];
+    if (c === '/' && n === '/') {
+      while (i < text.length && text[i] !== '\n') i += 1;
+      continue;
+    }
+    if (c === '/' && n === '*') {
+      i += 2;
+      while (i + 1 < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i = Math.min(text.length, i + 2);
+      continue;
+    }
+    out += c;
+    i += 1;
+  }
+  return out;
+}
+
+/** Every string module specifier in `text` (relative and bare). */
+export function moduleSpecifiers(text) {
+  const specs = [];
+  const source = withoutComments(String(text));
+  let i = 0;
+  while (i < source.length) {
+    let at = -1;
+    let mark = '';
+    for (const candidate of SPEC_MARKS) {
+      const found = source.indexOf(candidate, i);
+      if (found !== -1 && (at === -1 || found < at)) {
+        at = found;
+        mark = candidate;
+      }
+    }
+    if (at === -1) break;
+    const quote = mark[mark.length - 1];
+    const start = at + mark.length;
+    const end = source.indexOf(quote, start);
+    if (end === -1) break;
+    const spec = source.slice(start, end);
+    if (spec.length > 0) specs.push(spec);
+    i = end + 1;
+  }
+  return specs;
+}
+
+function resolveRelative(fromFile, spec) {
+  const base = fromFile.split('/');
+  base.pop();
+  for (const part of spec.split('/')) {
+    if (part === '' || part === '.') continue;
+    if (part === '..') {
+      if (base.length === 0) return null;
+      base.pop();
+      continue;
+    }
+    base.push(part);
+  }
+  return base.join('/');
+}
+
+function probe(joined, fileSet) {
+  if (!joined) return null;
+  const names = [joined];
+  for (const ext of EXT) names.push(`${joined}${ext}`, `${joined}/index${ext}`);
+  const stem = joined.replace(/\.(?:m|c)?js$/, '');
+  if (stem !== joined) for (const ext of EXT) names.push(`${stem}${ext}`);
+  for (const name of names) {
+    if (fileSet.has(name)) return name;
+  }
+  return null;
+}
+
+function readText(root, rel) {
+  try {
+    return fs.readFileSync(path.join(root, rel), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function addEdge(graph, target, importer) {
+  let set = graph.get(target);
+  if (!set) {
+    set = new Set();
+    graph.set(target, set);
+  }
+  set.add(importer);
+}
+
+/**
+ * target file → every file that imports it (value and type-only edges; a
+ * peerIsolation wall judges both).
+ * @param {{ root: string, files: string[], facts?: object, ts?: object }} input
+ */
+export function flatParentImporterGraph({ root, files, facts, ts }) {
+  const graph = new Map();
+  const fileSet = new Set(files);
+  const dependencies = Array.isArray(facts?.dependencies) ? facts.dependencies : null;
+  if (dependencies && dependencies.length > 0) {
+    for (const dep of dependencies) {
+      if (dep?.resolution !== 'resolved-project' || typeof dep.target !== 'string') continue;
+      if (typeof dep.from !== 'string' || dep.from === dep.target) continue;
+      addEdge(graph, dep.target, dep.from);
+    }
+    return graph;
+  }
+  const aliases = readTsconfigAliases(ts, root);
+  for (const file of files) {
+    for (const spec of moduleSpecifiers(readText(root, file))) {
+      const joined = spec.startsWith('.')
+        ? resolveRelative(file, spec)
+        : resolveSpecifierToRel(spec, file, root, aliases);
+      const target = probe(joined, fileSet);
+      if (target && target !== file) addEdge(graph, target, file);
+    }
+  }
+  return graph;
+}