arkgate 4.8.15 → 4.8.16

package/bin/lib/field-install.mjs

@@ -83,6 +83,37 @@ function addDevDependencyPreservingFormat(source, version) {
   return `${source.slice(0, contentEnd)}${addition}${eol}${rootClosingIndent}${source.slice(rootClose)}`;
 }
 
+function replaceArkgateDependencyPreservingFormat(source, version) {
+  const encoded = JSON.stringify(version);
+  const next = source.replace(/("arkgate"\s*:\s*)(?:"(?:\\.|[^"\\])*")/, `$1${encoded}`);
+  if (next === source) {
+    throw new Error('arkgate pin not found in package.json');
+  }
+  return next;
+}
+
+/** True when a caret/tilde/exact pin is an older semver than the CLI. Non-semver stays. */
+function pinCoreIsBehind(declaredPin, cliVersion) {
+  const pinCore = String(declaredPin).replace(/^[\^~>=<\s]+/, '').split(/\s+/)[0];
+  const pinParts = pinCore.split('.').map((p) => Number.parseInt(p, 10));
+  const cliParts = String(cliVersion).split('.').map((p) => Number.parseInt(p, 10));
+  if (
+    pinParts.length < 1 ||
+    cliParts.length < 1 ||
+    !pinParts.every((n) => Number.isFinite(n)) ||
+    !cliParts.every((n) => Number.isFinite(n))
+  ) {
+    return false;
+  }
+  for (let i = 0; i < 3; i += 1) {
+    const p = pinParts[i] ?? 0;
+    const c = cliParts[i] ?? 0;
+    if (p < c) return true;
+    if (p > c) return false;
+  }
+  return false;
+}
+
 const ARK_CHECK_BIN_RE = /\b(?:ark-check|arkgate-check)(?:\.mjs|\.js)?\b/;
 const ARK_CHECK_RUNNER_RE =
   /(?:^|[\s"'`;|&])(?:npx|pnpm|yarn|npm|bunx?|node)(?:\s|$)/;
@@ -379,13 +410,6 @@ export function pinArkgateDevDependency(root, opts = {}) {
   }
   const deps = pkg.dependencies && typeof pkg.dependencies === 'object' ? pkg.dependencies : {};
   const dev = pkg.devDependencies && typeof pkg.devDependencies === 'object' ? pkg.devDependencies : {};
-  if (typeof deps.arkgate === 'string' || typeof dev.arkgate === 'string') {
-    return {
-      changed: false,
-      reason: 'already-present',
-      version: deps.arkgate || dev.arkgate,
-    };
-  }
   const shipped = arkPackageVersion();
   const version =
     typeof opts.version === 'string' && opts.version
@@ -393,6 +417,22 @@ export function pinArkgateDevDependency(root, opts = {}) {
       : shipped
         ? `^${shipped}`
         : 'latest';
+  if (typeof deps.arkgate === 'string' || typeof dev.arkgate === 'string') {
+    const current = deps.arkgate || dev.arkgate;
+    const shouldBump =
+      opts.force === true || (Boolean(shipped) && pinCoreIsBehind(current, shipped));
+    if (!shouldBump || current === version) {
+      return {
+        changed: false,
+        reason: 'already-present',
+        version: current,
+      };
+    }
+    if (opts.write !== false) {
+      fs.writeFileSync(pkgPath, replaceArkgateDependencyPreservingFormat(source, version));
+    }
+    return { changed: true, reason: 'bumped', version };
+  }
   if (opts.write !== false) {
     fs.writeFileSync(pkgPath, addDevDependencyPreservingFormat(source, version));
   }

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

@@ -13,6 +13,7 @@ ${NORTH_STAR_ONE_LINE}
   arkgate start --apply      write host + CI setup
                              (refuses weak coverage/shape; lock with --archetype/--preset/--force)
   arkgate-check --doctor     status — one next step
+                             (if missing: npx --package=arkgate arkgate-check --doctor)
 
 Stuck? Run status (--doctor). Do #1.
 `;

package/bin/lib/improvement-compass-doctor.mjs

@@ -45,7 +45,9 @@ export function buildDoctorImprovementCompass(input = {}) {
     if (
       id.startsWith('ARKRULE_') ||
       id === 'INVARIANT_UNCOVERED' ||
-      id === 'INVARIANT_CATALOG_EMPTY'
+      id === 'INVARIANT_CATALOG_EMPTY' ||
+      id === 'INVARIANT_TESTS_PATH_MISSING' ||
+      id === 'INVARIANT_COVERAGE_ROOTS_MISSING'
     )
       arkRulesStructureResidual += 1;
   }

package/bin/lib/improvement-compass-map.mjs

@@ -262,7 +262,9 @@ function mapViolations(byId, violations) {
         }
         if (upper.startsWith('ARKRULE_') ||
             upper === 'INVARIANT_UNCOVERED' ||
-            upper === 'INVARIANT_CATALOG_EMPTY') {
+            upper === 'INVARIANT_CATALOG_EMPTY' ||
+            upper === 'INVARIANT_TESTS_PATH_MISSING' ||
+            upper === 'INVARIANT_COVERAGE_ROOTS_MISSING') {
             attach('encapsulation', 'ArkRules structure / invariant residual inside a layer.', {
                 kind: 'skill',
                 ref: '/ark-autopilot',

package/bin/lib/invariant-coverage.mjs

@@ -8,6 +8,12 @@
  * Pure CLI helper (bin/lib/invariant-coverage.mjs). Zero Node I/O.
  */
 
+/** Adopted + catalogued invariants, but no declared tests path (P2 §10). */
+export const INVARIANT_TESTS_PATH_RULE_ID = 'INVARIANT_TESTS_PATH_MISSING';
+export const INVARIANT_TESTS_PATH_MESSAGE = 'This project is adopted and has domain invariants, but ark.config.json does not name a real tests path. Add coverage.testGlobs or coverage.coverageRoots pointing at the folder where those tests live, then re-run. Without that path, coverage is an empty checkbox.';
+/** Enforced invariant, but no declared runner roots (P2 §10 residual). */
+export const INVARIANT_COVERAGE_ROOTS_RULE_ID = 'INVARIANT_COVERAGE_ROOTS_MISSING';
+export const INVARIANT_COVERAGE_ROOTS_MESSAGE = 'A domain invariant is enforced, but ark.config.json does not name coverage.coverageRoots — the folders where this project\'s test runner actually goes. Add coverage.coverageRoots pointing at that folder, then re-run. Without it, coverage can certify a test no runner runs.';
 /**
  * Human-readable discard tail. Empty when the scan discarded nothing.
  * `omitBudget` drops the budget clause and the load totals for messages whose
@@ -149,6 +155,7 @@ export function evaluateInvariantCoverage(input) {
             description: inv.description,
             ...(testEvidenceFile !== undefined ? { testEvidenceFile } : {}),
             ...(outsideDeclaredRoots !== undefined ? { outsideDeclaredRoots } : {}),
+            coverageRootsDeclared: rootsDeclared,
         });
         // The covering test exists but sits outside the roots the project declared
         // its runner walks. ArkGate does not execute tests, so it cannot tell the
@@ -233,5 +240,119 @@ export function canPromoteInvariant(coverage) {
             reason: `Invariant ${coverage.invariantId} is covered only by ${coverage.testEvidenceFile ?? 'a test'}, outside the declared coverage roots; ArkGate cannot tell whether that test runs, so it will not promote on it.`,
         };
     }
+    // Explicit false only: hand-built evidence may omit the field. The evaluator
+    // always sets it. Promoting without roots would make OUTSIDE_ROOTS silent.
+    if (coverage.coverageRootsDeclared === false) {
+        return {
+            ok: false,
+            reason: `Declare coverage.coverageRoots in ark.config.json before promoting ${coverage.invariantId} to enforced. Without that, ArkGate cannot tell whether a covering test is one the runner executes.`,
+        };
+    }
     return { ok: true, reason: `Invariant ${coverage.invariantId} has coverage evidence.` };
 }
+function nonEmptyPathStrings(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== 'string')
+            continue;
+        const trimmed = item.trim();
+        if (trimmed.length > 0)
+            out.push(trimmed);
+    }
+    return out;
+}
+/**
+ * Declared tests homes: `coverage.testGlobs` and/or `coverage.coverageRoots`.
+ * Either is a configured path. Empty strings do not count.
+ */
+export function configuredInvariantTestsPaths(coverage) {
+    if (!coverage || typeof coverage !== 'object')
+        return [];
+    return [...nonEmptyPathStrings(coverage.testGlobs), ...nonEmptyPathStrings(coverage.coverageRoots)];
+}
+export function hasConfiguredInvariantTestsPath(coverage) {
+    return configuredInvariantTestsPaths(coverage).length > 0;
+}
+/**
+ * True when at least one catalogued invariant wants test evidence.
+ * Same default as AR10: `coverage.test !== false`. `test: false` is an explicit
+ * opt-out (starter Domain phrases use it) and does not demand a tests path.
+ */
+export function catalogDemandsInvariantTestsPath(invariants) {
+    if (!Array.isArray(invariants) || invariants.length === 0)
+        return false;
+    return invariants.some((inv) => inv != null && inv.coverage?.test !== false);
+}
+/**
+ * §10 — adopted + invariants that want tests require a real tests path.
+ * Fail-closed. Not freezable. Silent when not adopted, the catalog is empty,
+ * or every entry sets `coverage.test: false`.
+ */
+export function collectMissingInvariantTestsPathFindings(input) {
+    const demanded = input.hasDomainInvariants === true ||
+        (input.hasDomainInvariants !== false && catalogDemandsInvariantTestsPath(input.invariants));
+    if (input.adopted !== true || !demanded)
+        return [];
+    const configured = hasConfiguredInvariantTestsPath(input.coverage);
+    if (configured && input.declaredPathPresent !== false)
+        return [];
+    return [
+        {
+            ruleId: INVARIANT_TESTS_PATH_RULE_ID,
+            message: INVARIANT_TESTS_PATH_MESSAGE,
+            file: 'ark.config.json',
+            line: 1,
+            severity: 'error',
+            failsStrict: true,
+            freezable: false,
+        },
+    ];
+}
+/**
+ * Declared runner homes: `coverage.coverageRoots` only.
+ * Empty strings do not count. testGlobs is not a runner root.
+ */
+export function configuredCoverageRoots(coverage) {
+    if (!coverage || typeof coverage !== 'object')
+        return [];
+    return nonEmptyPathStrings(coverage.coverageRoots);
+}
+export function hasConfiguredCoverageRoots(coverage) {
+    return configuredCoverageRoots(coverage).length > 0;
+}
+/**
+ * True when at least one catalogued invariant is `mode: "enforced"`.
+ * Structure-sensor enforced is not this — only `invariants[]`.
+ */
+export function catalogHasEnforcedInvariant(invariants) {
+    if (!Array.isArray(invariants) || invariants.length === 0)
+        return false;
+    return invariants.some((inv) => inv != null && inv.mode === 'enforced');
+}
+/**
+ * P2 §10 residual — any enforced invariant requires `coverage.coverageRoots`.
+ * Fail-closed. Not freezable. Silent when no invariant is enforced.
+ * testGlobs alone does not satisfy this: without roots, OUTSIDE_ROOTS cannot fire.
+ */
+export function collectMissingCoverageRootsFindings(input) {
+    const enforced = input.hasEnforcedInvariant === true ||
+        (input.hasEnforcedInvariant !== false && catalogHasEnforcedInvariant(input.invariants));
+    if (!enforced)
+        return [];
+    const configured = hasConfiguredCoverageRoots(input.coverage);
+    if (configured && input.declaredPathPresent !== false)
+        return [];
+    return [
+        {
+            ruleId: INVARIANT_COVERAGE_ROOTS_RULE_ID,
+            message: INVARIANT_COVERAGE_ROOTS_MESSAGE,
+            file: 'ark.config.json',
+            line: 1,
+            severity: 'error',
+            failsStrict: true,
+            freezable: false,
+        },
+    ];
+}

package/bin/lib/invariant-tests-path.mjs

@@ -0,0 +1,212 @@
+/**
+ * Adopted-mode domain-invariant tests path (P2 §10 / Contener).
+ * Tooling I/O over Domain collectMissingInvariantTestsPathFindings.
+ * Fail-closed when adopted. Silent when not adopted or the catalog is empty.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  classifyAdopted,
+  isAdopted,
+  readAdoptionStance,
+} from './adoption-stance.mjs';
+import {
+  catalogDemandsInvariantTestsPath,
+  catalogHasEnforcedInvariant,
+  configuredCoverageRoots,
+  configuredInvariantTestsPaths,
+  collectMissingCoverageRootsFindings,
+  collectMissingInvariantTestsPathFindings,
+  hasConfiguredCoverageRoots,
+  hasConfiguredInvariantTestsPath,
+  INVARIANT_COVERAGE_ROOTS_MESSAGE,
+  INVARIANT_TESTS_PATH_MESSAGE,
+} from './invariant-coverage.mjs';
+import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+
+export const INVARIANT_TESTS_PATH_ASK = INVARIANT_TESTS_PATH_MESSAGE;
+
+export const INVARIANT_TESTS_PATH_NEXT =
+  'Add coverage.testGlobs or coverage.coverageRoots in ark.config.json pointing at a real tests folder, then re-run.';
+
+export const INVARIANT_COVERAGE_ROOTS_ASK = INVARIANT_COVERAGE_ROOTS_MESSAGE;
+
+export const INVARIANT_COVERAGE_ROOTS_NEXT =
+  'Add coverage.coverageRoots in ark.config.json pointing at the folder the test runner uses, then re-run.';
+
+/**
+ * --require-gates / --strict-merge, or an explicit advisory-only ack.
+ * GitHub required-merge is known later in doctor; the scan uses this cheap side.
+ *
+ * @param {string} root
+ * @param {{ requireGates?: boolean }} [args]
+ */
+export function scanDemandsInvariantTestsPath(root, args = {}) {
+  if (args.requireGates === true) return true;
+  return isAdopted(classifyAdopted({ stance: readAdoptionStance(root) }));
+}
+
+/**
+ * First concrete path segment exists, or every declared glob is wildcard-only.
+ *
+ * @param {string} root
+ * @param {{ testGlobs?: unknown, coverageRoots?: unknown } | null | undefined} coverage
+ */
+export function declaredInvariantTestsPathPresent(root, coverage) {
+  const declared = configuredInvariantTestsPaths(coverage);
+  if (declared.length === 0) return false;
+  if (typeof root !== 'string' || root.length === 0) return true;
+  let sawConcrete = false;
+  for (const entry of declared) {
+    const prefix = entry.split(/[*?]/)[0].replace(/\/$/, '');
+    if (!prefix) continue;
+    sawConcrete = true;
+    const abs = path.resolve(root, prefix);
+    const rel = path.relative(path.resolve(root), abs).replace(/\\/g, '/');
+    if (!rel || rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) continue;
+    try {
+      if (fs.existsSync(abs)) return true;
+    } catch {
+      continue;
+    }
+  }
+  return !sawConcrete;
+}
+
+/**
+ * Doctor residual when adopted + invariants + missing/empty tests path.
+ *
+ * @param {{
+ *   adopted?: boolean,
+ *   coverage?: { testGlobs?: unknown, coverageRoots?: unknown } | null,
+ *   config?: object,
+ *   invariants?: unknown[],
+ *   hasDomainInvariants?: boolean,
+ *   root?: string,
+ * }} [input]
+ * @returns {{ missing: true, ask: string, nextAction: string } | null}
+ */
+function residualDemandsInvariantTests(input) {
+  if (input.hasDomainInvariants === true) return true;
+  if (input.hasDomainInvariants === false) return false;
+  if (Array.isArray(input.invariants)) return catalogDemandsInvariantTestsPath(input.invariants);
+  if (typeof input.root === 'string' && input.config) {
+    try {
+      const loaded = loadEffectiveArkRulesFromDisk(input.root, input.config);
+      if (loaded.errors?.length) return false;
+      return catalogDemandsInvariantTestsPath(loaded.arkRules?.invariants);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+export function collectInvariantTestsPathResidual(input = {}) {
+  if (input.adopted !== true) return null;
+  const coverage = input.coverage ?? input.config?.coverage;
+  const present =
+    typeof input.root === 'string' && input.root.length > 0
+      ? declaredInvariantTestsPathPresent(input.root, coverage)
+      : hasConfiguredInvariantTestsPath(coverage);
+  const findings = collectMissingInvariantTestsPathFindings({
+    adopted: true,
+    hasDomainInvariants: residualDemandsInvariantTests(input),
+    coverage,
+    declaredPathPresent: present,
+  });
+  if (findings.length === 0) return null;
+  return {
+    missing: true,
+    ask: findings[0]?.message ?? INVARIANT_TESTS_PATH_ASK,
+    nextAction: INVARIANT_TESTS_PATH_NEXT,
+  };
+}
+
+/**
+ * First concrete coverageRoots segment exists, or every declared glob is wildcard-only.
+ *
+ * @param {string} root
+ * @param {{ coverageRoots?: unknown } | null | undefined} coverage
+ */
+export function declaredCoverageRootsPresent(root, coverage) {
+  const declared = configuredCoverageRoots(coverage);
+  if (declared.length === 0) return false;
+  if (typeof root !== 'string' || root.length === 0) return true;
+  let sawConcrete = false;
+  for (const entry of declared) {
+    const prefix = entry.split(/[*?]/)[0].replace(/\/$/, '');
+    if (!prefix) continue;
+    sawConcrete = true;
+    const abs = path.resolve(root, prefix);
+    const rel = path.relative(path.resolve(root), abs).replace(/\\/g, '/');
+    if (!rel || rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) continue;
+    try {
+      if (fs.existsSync(abs)) return true;
+    } catch {
+      continue;
+    }
+  }
+  return !sawConcrete;
+}
+
+function residualHasEnforcedInvariant(input) {
+  if (input.hasEnforcedInvariant === true) return true;
+  if (input.hasEnforcedInvariant === false) return false;
+  if (Array.isArray(input.invariants)) return catalogHasEnforcedInvariant(input.invariants);
+  const refs = input.config?.arkRules;
+  if (!refs || typeof refs !== 'object' || Object.keys(refs).length === 0) return false;
+  if (typeof input.root === 'string' && input.config) {
+    try {
+      const loaded = loadEffectiveArkRulesFromDisk(input.root, input.config);
+      if (loaded.errors?.length) return false;
+      return catalogHasEnforcedInvariant(loaded.arkRules?.invariants);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/** One doctor light: roots residual wins when both would fire. */
+export function collectInvariantCoverageResiduals(input = {}) {
+  const invariantCoverageRoots = collectCoverageRootsResidual(input);
+  return {
+    invariantCoverageRoots,
+    invariantTestsPath: invariantCoverageRoots
+      ? null
+      : collectInvariantTestsPathResidual(input),
+  };
+}
+
+/**
+ * Doctor residual when any invariant is enforced and coverageRoots is missing/empty.
+ *
+ * @param {{
+ *   coverage?: { coverageRoots?: unknown } | null,
+ *   config?: object,
+ *   invariants?: unknown[],
+ *   hasEnforcedInvariant?: boolean,
+ *   root?: string,
+ * }} [input]
+ * @returns {{ missing: true, ask: string, nextAction: string } | null}
+ */
+export function collectCoverageRootsResidual(input = {}) {
+  const coverage = input.coverage ?? input.config?.coverage;
+  const present =
+    typeof input.root === 'string' && input.root.length > 0
+      ? declaredCoverageRootsPresent(input.root, coverage)
+      : hasConfiguredCoverageRoots(coverage);
+  const findings = collectMissingCoverageRootsFindings({
+    hasEnforcedInvariant: residualHasEnforcedInvariant(input),
+    coverage,
+    declaredPathPresent: present,
+  });
+  if (findings.length === 0) return null;
+  return {
+    missing: true,
+    ask: findings[0]?.message ?? INVARIANT_COVERAGE_ROOTS_ASK,
+    nextAction: INVARIANT_COVERAGE_ROOTS_NEXT,
+  };
+}

package/bin/lib/package-manager.mjs

@@ -91,6 +91,14 @@ export function arkCommand(root, bin, argsStr = '') {
   return `${execRunner(root)} ${bin}${argsStr ? ` ${argsStr}` : ''}`;
 }
 
+/**
+ * Run an Ark binary from package `arkgate` when local bins may be missing.
+ * Bare `npx arkgate-check` 404s — npx treats that bin name as its own package.
+ */
+export function arkPackageRecoveryCommand(bin, argsStr = '') {
+  return `npx --package=arkgate ${bin}${argsStr ? ` ${argsStr}` : ''}`;
+}
+
 /**
  * Split { command, args } form for JSON/TOML configs (.mcp.json, config.toml) that spawn
  * the binary directly. `pnpm exec ark-mcp` becomes command "pnpm" + args ["exec","ark-mcp",…]