arkgate 3.9.2 → 4.0.0

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

@@ -0,0 +1,116 @@
+/**
+ * Tooling adapter: load Effective Contract from disk for a root config.
+ * Pure resolution lives in Domain (`resolveEffectiveContract`); this module owns I/O.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  emptyEffectiveArkRules,
+  buildEffectiveArkRules,
+  loadArkRulesContract,
+} from './arkrules-contract.mjs';
+
+/**
+ * @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 refs = config?.arkRules;
+  if (!refs || typeof refs !== 'object' || Object.keys(refs).length === 0) {
+    return { arkRules: emptyEffectiveArkRules(), warnings: [], errors: [] };
+  }
+
+  const layerNames = new Set(
+    Array.isArray(config.layers) ? config.layers.map((layer) => layer.name) : []
+  );
+  const errors = [];
+  const warnings = [];
+  const parts = [];
+  const referenced = new Set();
+
+  for (const layer of Object.keys(refs).sort()) {
+    const relRaw = refs[layer];
+    const pathKey = `$.arkRules[${JSON.stringify(layer)}]`;
+    if (typeof relRaw !== 'string' || relRaw.length === 0) {
+      errors.push({ path: pathKey, message: 'must be a non-empty relative path string' });
+      continue;
+    }
+    if (relRaw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(relRaw)) {
+      errors.push({
+        path: pathKey,
+        message: 'must be a project-relative path (absolute paths are not allowed)',
+      });
+      continue;
+    }
+    if (!layerNames.has(layer)) {
+      errors.push({
+        path: pathKey,
+        message: `layer ${JSON.stringify(layer)} is not declared in layers[]`,
+      });
+      continue;
+    }
+
+    const rel = relRaw.replace(/\\/g, '/').replace(/^\.\//, '');
+    referenced.add(rel);
+    const absolute = path.resolve(root, rel);
+    opts.observeInput?.(absolute, 'arkrules');
+    if (!fs.existsSync(absolute)) {
+      errors.push({
+        path: pathKey,
+        message: `referenced ArkRules file ${JSON.stringify(rel)} is missing`,
+      });
+      continue;
+    }
+    let content;
+    try {
+      content = fs.readFileSync(absolute, 'utf8');
+    } catch (error) {
+      errors.push({
+        path: pathKey,
+        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`,
+      });
+    }
+  }
+
+  // Drift: unreferenced files under arkrules/
+  const arkrulesDir = path.join(root, 'arkrules');
+  if (fs.existsSync(arkrulesDir) && fs.statSync(arkrulesDir).isDirectory()) {
+    for (const name of fs.readdirSync(arkrulesDir).sort()) {
+      if (!name.endsWith('.json')) continue;
+      const rel = `arkrules/${name}`;
+      if (!referenced.has(rel)) {
+        warnings.push({
+          path: rel,
+          message: `ArkRules file ${JSON.stringify(rel)} is not referenced by arkRules and will not be enforced`,
+          severity: 'advisory',
+        });
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { arkRules: emptyEffectiveArkRules(), warnings, errors };
+  }
+  return {
+    arkRules: buildEffectiveArkRules(parts),
+    warnings,
+    errors: [],
+  };
+}

package/bin/lib/field-install.mjs

@@ -201,6 +201,110 @@ export function syncBaselineIntoCheckSurfaces(root, opts = {}) {
   return { changed, skipped };
 }
 
+/**
+ * Read declared arkgate pin from consumer package.json (deps or devDeps).
+ * @param {string} root
+ * @returns {string|null}
+ */
+export function readDeclaredArkgatePin(root) {
+  const pkgPath = path.join(root, 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    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') return deps.arkgate;
+    if (typeof dev.arkgate === 'string') return dev.arkgate;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Dual-truth: CLI/package-shipped version vs consumer package.json pin.
+ * Used by doctor + upgrade so agents never confuse managed-asset CLI with CI pin.
+ *
+ * @param {string} root
+ * @param {{ cliVersion?: string|null }} [opts]
+ * @returns {{
+ *   dualTruth: boolean,
+ *   cliVersion: string|null,
+ *   declaredPin: string|null,
+ *   code: 'PACKAGE_PIN_BEHIND_CLI' | 'PACKAGE_PIN_MATCHES' | 'PACKAGE_PIN_ABSENT' | 'CLI_VERSION_UNKNOWN',
+ *   note: string
+ * }}
+ */
+export function describePackageVersionDualTruth(root, opts = {}) {
+  const cliVersion =
+    typeof opts.cliVersion === 'string' && opts.cliVersion
+      ? opts.cliVersion
+      : arkPackageVersion();
+  const declaredPin = readDeclaredArkgatePin(root);
+  if (!cliVersion) {
+    return {
+      dualTruth: false,
+      cliVersion: null,
+      declaredPin,
+      code: 'CLI_VERSION_UNKNOWN',
+      note: 'Could not read shipped arkgate package version for this CLI.',
+    };
+  }
+  if (!declaredPin) {
+    return {
+      dualTruth: false,
+      cliVersion,
+      declaredPin: null,
+      code: 'PACKAGE_PIN_ABSENT',
+      note: 'No arkgate pin in package.json; CI/npx may not resolve this CLI version.',
+    };
+  }
+  // Normalize ^x.y.z / ~x.y.z / x.y.z for comparison of leading version token.
+  const pinCore = String(declaredPin).replace(/^[\^~>=<\s]+/, '').split(/\s+/)[0];
+  const matches =
+    pinCore === cliVersion ||
+    pinCore.startsWith(`${cliVersion}.`) ||
+    cliVersion.startsWith(pinCore.split('.').slice(0, 3).join('.'));
+  // Dual-truth when declared pin is clearly older major/minor than CLI, or different major.
+  const pinParts = pinCore.split('.').map((p) => Number.parseInt(p, 10));
+  const cliParts = cliVersion.split('.').map((p) => Number.parseInt(p, 10));
+  let behind = false;
+  if (
+    pinParts.length >= 1 &&
+    cliParts.length >= 1 &&
+    pinParts.every((n) => Number.isFinite(n)) &&
+    cliParts.every((n) => Number.isFinite(n))
+  ) {
+    for (let i = 0; i < 3; i += 1) {
+      const p = pinParts[i] ?? 0;
+      const c = cliParts[i] ?? 0;
+      if (p < c) {
+        behind = true;
+        break;
+      }
+      if (p > c) break;
+    }
+  } else if (!matches) {
+    behind = true;
+  }
+  if (behind) {
+    return {
+      dualTruth: true,
+      cliVersion,
+      declaredPin,
+      code: 'PACKAGE_PIN_BEHIND_CLI',
+      note: `Managed CLI is arkgate@${cliVersion} but package.json pins ${declaredPin}. Bump the pin or re-run install so CI resolves the same version (common after upgrade --no-install).`,
+    };
+  }
+  return {
+    dualTruth: false,
+    cliVersion,
+    declaredPin,
+    code: 'PACKAGE_PIN_MATCHES',
+    note: `package.json pin ${declaredPin} is aligned with CLI arkgate@${cliVersion}.`,
+  };
+}
+
 /**
  * Pin `arkgate` in package.json devDependencies (no package manager network call).
  *

package/bin/lib/graph-blind.mjs

@@ -16,6 +16,8 @@ import { normalize } from './scan-files.mjs';
 
 const MAX_LIST = 8;
 const MAX_FILE_BYTES = 256 * 1024;
+/** Full AST scan stays off huge trees so doctor resident warm keeps the 500 ms UX ceiling. */
+const MAX_FULL_SCAN_FILES = 2500;
 const LEXICAL_GATE = /\b(?:import|require)\s*\(|\bimport\s+\w+\s*=\s*require\s*\(/;
 
 /**
@@ -121,6 +123,23 @@ export function detectGraphBlindSpots(ts, root, files = []) {
     };
   }
 
+  // Large-tree deferral: re-reading every path for an advisory sensor would blow the
+  // doctorResidentWarm 500 ms absolute UX ceiling at the 10k perf fixture.
+  if (files.length > MAX_FULL_SCAN_FILES) {
+    return {
+      available: true,
+      advisory: true,
+      blockerGrade: false,
+      deferred: true,
+      count: 0,
+      templateInterpolationCount: 0,
+      otherNonLiteralCount: 0,
+      truncated: 0,
+      edges: [],
+      note: `Graph-blind full scan deferred (${files.length} files > ${MAX_FULL_SCAN_FILES}). Non-literal dynamic import/require remain unresolvable in architecture analysis; advisory incomplete-graph honesty is not enumerated at this scale.`,
+    };
+  }
+
   const resolvedRoot = path.resolve(root);
   const edges = [];
   for (const file of files) {

package/bin/lib/html-report-advisories.mjs

@@ -241,6 +241,29 @@ function parseHealthHtml(health) {
  * `computeDoctorAdvisories` returns — the parity guard enforces it.
  * @param escape injected HTML escaper (dependency points html-report → here only)
  */
+function rulesUnderContractHtml(section) {
+  if (!section || typeof section !== 'object') return '';
+  const note = section.note ? `<p class="muted">${esc(section.note)}</p>` : '';
+  if (section.active === false) {
+    return `
+  <section data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(ArkRules opt-in)</span></h2>
+    ${note}
+  </section>`;
+  }
+  return `
+  <section data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(counts — not a score)</span></h2>
+    <ul>
+      <li>Structure rules: <strong>${Number(section.structureRules) || 0}</strong></li>
+      <li>Invariants: <strong>${Number(section.invariants) || 0}</strong></li>
+      <li>Covered invariants: <strong>${Number(section.coveredInvariants) || 0}</strong></li>
+      <li>Uncovered invariants: <strong>${Number(section.uncoveredInvariants) || 0}</strong></li>
+    </ul>
+    ${note}
+  </section>`;
+}
+
 export function renderAdvisorySections(advisories, escape) {
   if (!advisories || typeof advisories !== 'object') return '';
   if (typeof escape === 'function') esc = escape;
@@ -250,6 +273,7 @@ export function renderAdvisorySections(advisories, escape) {
     physicalCohesionHtml(advisories.physicalCohesion),
     parseHealthHtml(advisories.parseHealth),
     graphBlindSpotsHtml(advisories.graphBlindSpots, esc),
+    rulesUnderContractHtml(advisories.rulesUnderContract),
   ]
     .filter(Boolean)
     .join('\n');

package/bin/lib/install-migrate.mjs

@@ -138,14 +138,32 @@ export function warnLockfileConflict(root) {
 export function buildManagedAssetCatalog({ root, tools, compact = false, skillsOnly = false }) {
   const selectedTools = tools instanceof Set ? tools : new Set(tools ?? []);
   const assets = [];
+  // Path-keyed: codex + antigravity both target `.agents/skills/*/SKILL.md` (and
+  // antigravity + gemini share GEMINI.md). Duplicate plan entries caused apply to
+  // write once then fail the second pre-image assert (field: web-predial-ar).
+  const byPath = new Map();
   const add = (relativePath, content, kind = 'gate', scope = 'whole-file') => {
-    assets.push({
+    const existing = byPath.get(relativePath);
+    if (existing) {
+      // Shared destinations (codex+antigravity skills, antigravity+gemini GEMINI.md)
+      // must agree on bytes; silent first-wins would hide divergent host templates.
+      if (existing.content !== content || existing.kind !== kind || existing.scope !== scope) {
+        throw new Error(
+          `managed asset catalog conflict at ${JSON.stringify(relativePath)}: ` +
+            `hosts produced different content/kind/scope for the same path`
+        );
+      }
+      return;
+    }
+    const asset = {
       relativePath,
       content,
       kind,
       scope,
       templateId: `${kind}:${relativePath}`,
-    });
+    };
+    byPath.set(relativePath, asset);
+    assets.push(asset);
   };
 
   if (!skillsOnly) {

package/bin/lib/invariant-coverage-io.mjs

@@ -0,0 +1,157 @@
+/**
+ * Tooling I/O for ArkRules invariant coverage (AR10).
+ * Pure evaluation lives in Domain (`evaluateInvariantCoverage`); this module
+ * discovers test files and loads contents from disk (bounded).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_TEST_NAME_RE =
+  /\.(test|spec)\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$|\/__tests__\/|\/tests?\//i;
+
+/** Max files to load for coverage evidence (budget). */
+const MAX_COVERAGE_FILES = 400;
+/** Max bytes per file when reading for title/symbol mining. */
+const MAX_FILE_BYTES = 256 * 1024;
+
+/**
+ * True when absolute is root or a file under root (separator-safe).
+ * @param {string} root
+ * @param {string} absolute
+ */
+function isPathInsideRoot(root, absolute) {
+  const rootResolved = path.resolve(root);
+  const absResolved = path.resolve(absolute);
+  if (absResolved === rootResolved) return true;
+  const relative = path.relative(rootResolved, absResolved);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+/**
+ * Minimal glob match for testGlobs (double-star slash = zero path segments).
+ * @param {string} glob
+ * @param {string} file
+ */
+function matchSimpleGlob(glob, file) {
+  const pattern = String(glob || '').replace(/\\/g, '/');
+  const target = String(file || '').replace(/\\/g, '/');
+  if (!pattern) return false;
+  let out = '';
+  for (let i = 0; i < pattern.length; i += 1) {
+    const c = pattern[i];
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        if (pattern[i + 2] === '/') {
+          out += '(?:.*/)?';
+          i += 2;
+        } else {
+          out += '.*';
+          i += 1;
+        }
+      } else {
+        out += '[^/]*';
+      }
+    } else if (c === '?') {
+      out += '[^/]';
+    } else if (/[.+^${}()|[\]\\]/.test(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c;
+    }
+  }
+  return new RegExp(`^${out}$`).test(target);
+}
+
+/**
+ * @param {string} root
+ * @param {{ files?: Array<{ path: string }> }} facts
+ * @param {{ testGlobs?: string[] }} [opts]
+ * @returns {{ fileContents: Record<string, string>, testFiles: string[], testGlobsMissing: boolean }}
+ */
+export function loadInvariantCoverageInputs(root, facts, opts = {}) {
+  const fileContents = {};
+  const testFiles = [];
+  const seen = new Set();
+  const testGlobs = Array.isArray(opts.testGlobs)
+    ? opts.testGlobs.filter((g) => typeof g === 'string' && g.length > 0)
+    : [];
+  const useCustomGlobs = testGlobs.length > 0;
+
+  const isTestPath = (rel) => {
+    if (useCustomGlobs) return testGlobs.some((g) => matchSimpleGlob(g, rel));
+    return DEFAULT_TEST_NAME_RE.test(rel);
+  };
+
+  const pushFile = (relPath, forceAsTest = false) => {
+    const rel = String(relPath || '')
+      .replace(/\\/g, '/')
+      .replace(/^\.\//, '');
+    if (!rel || seen.has(rel) || seen.size >= MAX_COVERAGE_FILES) return;
+    const absolute = path.resolve(root, rel);
+    if (!isPathInsideRoot(root, absolute)) return;
+    try {
+      const stat = fs.statSync(absolute);
+      if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return;
+      const content = fs.readFileSync(absolute, 'utf8');
+      seen.add(rel);
+      fileContents[rel] = content;
+      if (forceAsTest || isTestPath(rel)) testFiles.push(rel);
+    } catch {
+      // skip unreadable
+    }
+  };
+
+  for (const file of facts?.files ?? []) {
+    if (file?.path) pushFile(file.path);
+  }
+
+  if (useCustomGlobs) {
+    // Walk project roots and keep files matching custom globs.
+    for (const dir of ['.', 'tests', 'test', 'src', '__tests__', 'spec']) {
+      const absDir = path.join(root, dir === '.' ? '' : dir);
+      if (!fs.existsSync(absDir)) continue;
+      walkTestFiles(absDir, root, (rel) => {
+        if (isTestPath(rel)) pushFile(rel, true);
+      });
+    }
+  } else {
+    // Walk common test roots when facts only cover production include globs.
+    for (const dir of ['tests', 'test', 'src', '__tests__']) {
+      const absDir = path.join(root, dir);
+      if (!fs.existsSync(absDir)) continue;
+      walkTestFiles(absDir, root, (rel) => {
+        if (isTestPath(rel)) pushFile(rel, true);
+      });
+    }
+  }
+
+  const testGlobsMissing = testFiles.length === 0;
+  return { fileContents, testFiles, testGlobsMissing };
+}
+
+/**
+ * @param {string} dir
+ * @param {string} root
+ * @param {(rel: string) => void} onFile
+ * @param {number} [depth]
+ */
+function walkTestFiles(dir, root, onFile, depth = 0) {
+  if (depth > 8) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;
+    const absolute = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkTestFiles(absolute, root, onFile, depth + 1);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const rel = path.relative(root, absolute).replace(/\\/g, '/');
+    onFile(rel);
+  }
+}

package/bin/lib/invariant-coverage.mjs

@@ -0,0 +1,127 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/invariantCoverage.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/invariant-coverage.mjs). Zero Node I/O.
+ */
+
+function titleMatchesInvariant(content, id) {
+    // Match describe/it/test string titles containing the invariant id.
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`(?:describe|it|test|context)\\s*\\(\\s*['"\`][^'"\`]*${escaped}[^'"\`]*['"\`]`, 'i');
+    return re.test(content) || content.includes(id);
+}
+function symbolPresent(fileContents, symbol) {
+    if (!symbol)
+        return false;
+    // Support Aggregate.method or bare method name.
+    const parts = symbol.split('.');
+    const needle = parts[parts.length - 1];
+    const className = parts.length > 1 ? parts[0] : null;
+    for (const content of Object.values(fileContents)) {
+        if (className && !content.includes(className))
+            continue;
+        if (new RegExp(`(?:function\\s+|\\b)${needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*[(<]`).test(content) ||
+            content.includes(symbol)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function evaluateInvariantCoverage(input) {
+    const invariants = input.arkRules.invariants ?? [];
+    if (invariants.length === 0) {
+        return { coverage: [], violations: [], partial: false };
+    }
+    const testFiles = input.testFiles ?? [];
+    const testGlobsMissing = input.testGlobsMissing === true || testFiles.length === 0;
+    const coverage = [];
+    const violations = [];
+    for (const inv of invariants) {
+        const evidence = [];
+        const wantsTest = inv.coverage?.test !== false; // default: prefer test evidence when catalogued
+        const symbol = inv.coverage?.symbol;
+        if (!testGlobsMissing && wantsTest) {
+            for (const file of testFiles) {
+                const content = input.fileContents[file];
+                if (content && titleMatchesInvariant(content, inv.id)) {
+                    evidence.push('test-title');
+                    break;
+                }
+            }
+        }
+        if (symbol && symbolPresent(input.fileContents, symbol)) {
+            evidence.push('symbol');
+        }
+        // Covered if any requested evidence is present.
+        // When coverage declares neither test nor symbol, require at least description-only advisory presence = not covered.
+        const requiresEvidence = inv.coverage?.test === true || Boolean(symbol) || inv.coverage === undefined;
+        const covered = requiresEvidence && evidence.length > 0
+            ? true
+            : inv.coverage?.test === false && !symbol
+                ? true // explicitly no coverage requirements
+                : evidence.length > 0;
+        // Partial only when tests are missing *and* no other evidence (e.g. symbol) completed coverage.
+        const partial = testGlobsMissing && wantsTest && evidence.length === 0;
+        coverage.push({
+            invariantId: inv.id,
+            layer: inv.provenance.layer,
+            sourceFile: inv.provenance.sourceFile,
+            mode: inv.mode,
+            covered: covered && !partial,
+            evidence,
+            partial,
+            description: inv.description,
+        });
+        if (!covered || partial) {
+            // Enforced + proven uncovered → failsStrict; partial always advisory (never fake green).
+            const failsStrict = inv.mode === 'enforced' && !partial;
+            violations.push({
+                ruleId: 'INVARIANT_UNCOVERED',
+                message: partial
+                    ? `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered.`
+                    : `Invariant ${inv.id} is not covered by a test title or declared symbol.`,
+                file: inv.provenance.sourceFile,
+                line: 1,
+                arkruleId: inv.id,
+                arkruleSource: inv.provenance.sourceFile,
+                fromLayer: inv.provenance.layer,
+                severity: failsStrict ? 'error' : 'warning',
+                failsStrict,
+            });
+        }
+    }
+    // Top-level partial only from entry flags (symbol-only coverage must not stick partial).
+    return {
+        coverage,
+        violations,
+        partial: coverage.some((entry) => entry.partial),
+    };
+}
+/**
+ * Deterministic promotion gate: refuse advisory→enforced when invariant is uncovered.
+ */
+export function canPromoteInvariant(coverage) {
+    if (!coverage) {
+        return {
+            ok: false,
+            reason: 'No coverage evidence supplied for this invariant; evaluate coverage before promoting to enforced.',
+        };
+    }
+    if (coverage.partial) {
+        return {
+            ok: false,
+            reason: 'Coverage is partial (missing test globs); cannot promote until evidence is complete.',
+        };
+    }
+    if (!coverage.covered) {
+        return {
+            ok: false,
+            reason: `Invariant ${coverage.invariantId} is uncovered; add a test title or symbol before promoting to enforced.`,
+        };
+    }
+    return { ok: true, reason: `Invariant ${coverage.invariantId} has coverage evidence.` };
+}

package/bin/lib/policy-delta-io.mjs

@@ -2,6 +2,9 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { analyzePolicyDelta } from './analysis-engine.mjs';
+import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 
 function readJsonFile(filePath, label) {
   if (!fs.existsSync(filePath)) throw new Error(`${label} not found: ${filePath}`);
@@ -151,11 +154,41 @@ export function analyzePolicyTransition({
     throw new Error('Policy delta was requested but no policy base could be resolved.');
   }
   if (!base) return undefined;
+
+  // AR02/AR11: load Effective ArkRules so mode edits inside arkrules/*.json classify,
+  // and attach candidate coverage so covered advisory→enforced can auto-allow.
+  const baseLoad = loadEffectiveArkRulesFromDisk(root, base.config);
+  const candidateLoad = loadEffectiveArkRulesFromDisk(root, candidateConfig);
+  if (candidateLoad.errors.length > 0) {
+    const message = candidateLoad.errors
+      .map((issue) => `- ${issue.path}: ${issue.message}`)
+      .join('\n');
+    throw new Error(`Invalid candidate Effective Contract:\n${message}`);
+  }
+  // Base load errors: best-effort empty (base git tree may lack arkrules files on disk).
+  const baseArkRules = baseLoad.errors.length > 0 ? undefined : baseLoad.arkRules;
+  const candidateArkRules = candidateLoad.arkRules;
+
+  let candidateInvariantCoverage;
+  if ((candidateArkRules?.invariants?.length ?? 0) > 0) {
+    const coverageInputs = loadInvariantCoverageInputs(root, { files: [] });
+    const evaluated = evaluateInvariantCoverage({
+      arkRules: candidateArkRules,
+      fileContents: coverageInputs.fileContents,
+      testFiles: coverageInputs.testFiles,
+      testGlobsMissing: coverageInputs.testGlobsMissing,
+    });
+    candidateInvariantCoverage = evaluated.coverage;
+  }
+
   return analyzePolicyDelta({
     baseConfig: base.config,
     candidateConfig,
     acknowledgement: readPolicyAcknowledgement(root, acknowledgementPath),
     baseSource: base.source,
     candidateSource: path.isAbsolute(configPath) ? configPath : path.join(root, configPath),
+    ...(baseArkRules ? { baseArkRules } : {}),
+    candidateArkRules,
+    ...(candidateInvariantCoverage ? { candidateInvariantCoverage } : {}),
   });
 }