arkgate 3.9.1 → 4.0.0

package/bin/lib/doctor-plan.mjs

@@ -9,6 +9,9 @@ import {
   resolveOperatingMode,
   shouldShowNewHereNudge,
 } from '../ark-shared.mjs';
+import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
+import { describePackageVersionDualTruth } from './field-install.mjs';
+export { summarizeRulesUnderContract };
 import {
   collectAdoptionGaps,
   detectSkillGaps,
@@ -35,8 +38,12 @@ import {
   buildPostGreenNextAction,
   mergePostGreenTopActions,
   isDoctorHealthyNothingToDo,
+  DESIGN_WEAK_HONESTY_FLAGS,
 } from './post-green-path.mjs';
-import { doctorWritePathHonestyMessage } from './host-support-matrix.mjs';
+import {
+  buildCoverageHonesty,
+  computeDoctorEnforcementHonesty,
+} from './enforcement-honesty.mjs';
 import {
   computePureLayerOptInNudge,
   loadGoldenPattern,
@@ -129,10 +136,12 @@ export function runCoverage(root, config, files, rules, asJson) {
   if (files.length > 0 && governed.percent < 50) {
     console.log('');
     console.log(
-      `⚠ Ark governs a MINORITY of your code (${governed.percent}%). A green check here does NOT`
+      `⚠ Ark governs a MINORITY of your code (${governed.percent}%). A green check on ~${governed.percent}%`
+    );
+    console.log(
+      '  is worse than no gate — it looks safe while most code is ungoverned. Classify the'
     );
-    console.log('  mean the codebase is checked — the rest is ungoverned. Classify the directories');
-    console.log('  below to actually cover it.');
+    console.log('  directories below before treating green as enforcement.');
   }
   if (suggestions.length > 0) {
     console.log('');
@@ -236,6 +245,11 @@ export function buildRemediationPlan(
     patternBets,
     designSmells,
   });
+  const coverageHonesty = buildCoverageHonesty({
+    percent: governedPercent,
+    totalFiles,
+    emptyScope,
+  });
 
   let statement =
     activeViolations.length > 0
@@ -264,6 +278,7 @@ export function buildRemediationPlan(
         ? {
             designWeakLabel:
               'ENFORCE · design-weak — use patternBets / dual-plan B; never auto-apply as mechanical-safe',
+            ...DESIGN_WEAK_HONESTY_FLAGS,
           }
         : {}),
       ...(governedPercent != null ? { governedPercent } : {}),
@@ -282,6 +297,7 @@ export function buildRemediationPlan(
     designSmells,
     // Q04: one-pilot loop step (extraction card); never mechanical-safe.
     pilotLoop,
+    coverageHonesty,
   };
 }
 
@@ -397,6 +413,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   }
   const gatesMissing = missingGates(root);
   const skillGaps = detectSkillGaps(root);
+  // Dual-truth: CLI version vs package.json pin (field residual after upgrade --no-install).
+  const packageVersionTruth = describePackageVersionDualTruth(root);
   const staleRunners = staleRunnerGateFiles(root);
   const adoption = collectAdoptionGaps(root, config, cov);
   // Prefer writePath from adoption (same detector); recompute only if missing (tests/stubs).
@@ -435,6 +453,18 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     designSmells,
   });
   const doctorAdvisories = computeDoctorAdvisories(root, config, cov, rules, files, options.ts, options.parseHealth);
+  const { coverageHonesty, baselineHonesty, writePathHonesty } = computeDoctorEnforcementHonesty({
+    governedPercent: cov.governed.percent,
+    totalFiles: cov.governed.totalFiles,
+    emptyScope: cov.emptyScope === true || cov.governed.totalFiles === 0,
+    baselineExists: baseline.exists,
+    frozenKeys: baseline.exists ? baseline.keys.size : 0,
+    activeViolations: activeCount,
+    suppressed,
+    totalViolations: violations.length,
+    activeHost: writePath.activeHost,
+    hardWriteActive: writePath.capabilities?.['hard-write'] === true,
+  });
 
   if (asJson) {
     (options.writeJson ?? console.log)(
@@ -464,10 +494,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
             ...(postGreenPath
-              ? {
-                  primaryNextAction: postGreenPath.action,
-                  healthyFinishedForbidden: true,
-                }
+              ? { primaryNextAction: postGreenPath.action, ...DESIGN_WEAK_HONESTY_FLAGS }
               : {}),
             // Q03: advisory golden for new-code placement (absent = no claim).
             goldenPattern,
@@ -475,10 +502,19 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             pureLayerOptIn,
             // Q04: one-pilot loop (extraction card → re-doctor).
             pilotLoop,
-            // Advisories, never a verdict: W01 contract health, U05 ambient state,
-            // X04 physical cohesion/reshape pilot, Y03 parse health.
+            // AR12 — Rules under contract (honest counts, not a score).
+            // Pass architecture facts when available so coverage can scan real tests.
+            rulesUnderContract: summarizeRulesUnderContract(
+              root,
+              config,
+              options.facts ?? options.architectureFacts
+            ),
+            // Dual-truth: managed CLI vs package.json pin (not a gate fail).
+            packageVersionTruth,
+            // Advisories, never a verdict: W01/U05/X04/Y03 + graph-blind spots.
             ...doctorAdvisories,
             governed: cov.governed,
+            coverageHonesty,
             emptyLayers: cov.emptyLayers,
             layersWithoutRules: cov.layersWithoutRules,
             ungovernedDirs: cov.suggestions.length,
@@ -497,6 +533,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               frozen: baseline.exists ? baseline.keys.size : 0,
               stale: analysisComplete ? staleBaseline : null,
               policy: adoption.baseline,
+              honesty: baselineHonesty,
             },
             gatesMissing,
             skillGaps,
@@ -517,6 +554,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
               hookRepair: writePath.hookRepair,
               mcpPresent: writePath.mcpPresent,
               evidence: writePath.evidence,
+              honesty: writePathHonesty,
               ...(writePath.sessionNote ? { sessionNote: writePath.sessionNote } : {}),
               ...(writePath.gap
                 ? {
@@ -688,6 +726,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         ? ok
         : warn;
   line(govMark, `Governed: ${cov.governed.percent}% (${cov.governed.classifiedFiles}/${cov.governed.totalFiles} files)`);
+  if (coverageHonesty.greenIsNotEnforcement) {
+    line(coverageHonesty.worseThanNoGate ? bad : warn, coverageHonesty.message);
+    if (coverageHonesty.worseThanNoGate) {
+      actions.push('raise governed coverage above a minority slice before treating green as enforcement');
+    }
+  }
   if (cov.suggestions.length > 0) {
     line(warn, `${cov.suggestions.length} ungoverned director(y/ies) — proposals: ${arkCommand(root, 'ark-check', '--coverage')}`);
     actions.push('classify the ungoverned directories (/ark-contract)');
@@ -696,6 +740,13 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   if (cov.layersWithoutRules.length > 0) line(warn, `Layers with no rule edge: ${cov.layersWithoutRules.join(', ')}`);
   if (cov.suggestions.length === 0 && cov.emptyLayers.length === 0) line(ok, 'Every layer classifies files; no empty layers');
 
+  if (packageVersionTruth?.dualTruth) {
+    console.log('');
+    console.log(color.bold('Package pin (dual-truth)'));
+    line(warn, packageVersionTruth.note);
+    actions.push('bump package.json arkgate pin to match this CLI (or install without --no-install)');
+  }
+
   if (showNewHere) {
     console.log('');
     console.log(color.bold('New here?'));
@@ -770,8 +821,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   line(' ', `Active host: ${writePath.activeHost}`);
   line(' ', `Supported profile: ${writePath.supportSummary}`);
   line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
-  const honestyLine = doctorWritePathHonestyMessage(writePath.activeHost, capabilities['hard-write']);
-  if (honestyLine) line(warn, honestyLine);
+  if (writePathHonesty.message) line(warn, writePathHonesty.message);
   if (writePath.sessionNote) {
     line(warn, writePath.sessionNote);
   }
@@ -850,7 +900,12 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   } else {
     // Baseline keys are line-agnostic, so N keys can suppress ≥N violations — label as keys
     // to avoid an apparent mismatch with the "frozen" violation count above.
-    line(analysisComplete ? ok : warn, `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`);
+    const baseMark = !analysisComplete || baselineHonesty.dirtyBaselineRisk ? warn : ok;
+    line(baseMark, `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`);
+    if (analysisComplete && baselineHonesty.dirtyBaselineRisk) {
+      line(warn, baselineHonesty.message);
+      actions.push('review dirty baseline freezes — fix the contract before trusting green-via-freeze');
+    }
     if (analysisComplete && staleBaseline > 0) {
       line(warn, `${staleBaseline} stale entr(y/ies) no longer occur — tighten with --update-baseline`);
       actions.push('tighten the baseline (--update-baseline)');

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/enforcement-honesty.mjs

@@ -0,0 +1,225 @@
+/**
+ * Product honesty helpers — weak coverage, dirty baseline, soft write hosts.
+ *
+ * Pure / fail-closed: never invent hard write guarantees; never paint thin
+ * coverage or a dirty freeze as "done." Advisory labels only.
+ */
+import {
+  doctorWritePathHonestyMessage,
+  HOST_SUPPORT_MATRIX,
+  HOST_SUPPORT_HOSTS,
+} from './host-support-matrix.mjs';
+
+/** Soft = matrix hard-write false; hard-capable = matrix hard-write true. Single source of truth. */
+function hostWriteClassSets() {
+  const soft = new Set();
+  const hard = new Set();
+  for (const host of HOST_SUPPORT_HOSTS) {
+    const profile = HOST_SUPPORT_MATRIX[host];
+    if (profile?.capabilities?.['hard-write']) hard.add(host);
+    else soft.add(host);
+  }
+  return { soft, hard };
+}
+
+const { soft: SOFT_WRITE_HOSTS, hard: HARD_WRITE_HOSTS } = hostWriteClassSets();
+
+/**
+ * Coverage honesty: green on a minority of the tree is worse than no gate.
+ * `greenIsNotEnforcement` stays true until the whole in-scope tree is governed (100%).
+ * @param {{ percent?: number|null, totalFiles?: number|null, emptyScope?: boolean }} input
+ */
+export function buildCoverageHonesty(input = {}) {
+  const total = Number(input.totalFiles) || 0;
+  const empty = input.emptyScope === true || total === 0;
+  const percent = Number.isFinite(Number(input.percent)) ? Number(input.percent) : 0;
+
+  if (empty) {
+    return {
+      status: 'empty-scope',
+      advisory: true,
+      greenIsNotEnforcement: true,
+      worseThanNoGate: true,
+      wholeTreeGoverned: false,
+      governedPercent: 0,
+      // Always 0 when empty-scope so payload cannot contradict the message.
+      totalFiles: 0,
+      message:
+        'Empty scope: a green check matches 0 files and is worse than no gate until include/layers cover real code.',
+    };
+  }
+  if (percent < 50) {
+    return {
+      status: 'weak',
+      advisory: true,
+      greenIsNotEnforcement: true,
+      worseThanNoGate: true,
+      wholeTreeGoverned: false,
+      governedPercent: percent,
+      totalFiles: total,
+      message: `Weak coverage (${percent}%): a green check on a minority of the tree is worse than no gate — most code is ungoverned.`,
+    };
+  }
+  if (percent < 80) {
+    return {
+      status: 'partial',
+      advisory: true,
+      greenIsNotEnforcement: true,
+      worseThanNoGate: false,
+      wholeTreeGoverned: false,
+      governedPercent: percent,
+      totalFiles: total,
+      message: `Partial coverage (${percent}%): green means edges on the governed slice only, not the whole tree.`,
+    };
+  }
+  const wholeTree = percent >= 100;
+  return {
+    status: 'strong',
+    advisory: true,
+    // Strong slice ≠ full-tree enforcement; boolean consumers must not oversell.
+    greenIsNotEnforcement: !wholeTree,
+    worseThanNoGate: false,
+    wholeTreeGoverned: wholeTree,
+    governedPercent: percent,
+    totalFiles: total,
+    message: wholeTree
+      ? `Governed 100% of in-scope files — green is meaningful for the full in-scope tree.`
+      : `Governed ${percent}% of in-scope files — green is meaningful only for that governed slice; ${100 - percent}% remains ungoverned.`,
+  };
+}
+
+/**
+ * Baseline honesty: a large freeze that zeros active violations can look safe
+ * while hiding false-positive debt.
+ * @param {{
+ *   exists?: boolean,
+ *   frozenKeys?: number,
+ *   activeViolations?: number,
+ *   suppressed?: number,
+ *   totalViolations?: number,
+ * }} input
+ */
+export function buildBaselineHonesty(input = {}) {
+  const exists = input.exists === true;
+  const frozen = Number(input.frozenKeys) || 0;
+  const active = Number(input.activeViolations) || 0;
+  const suppressed = Number(input.suppressed) || 0;
+  const total = Number(input.totalViolations) || 0;
+
+  if (!exists) {
+    return {
+      status: total > 0 ? 'missing-with-debt' : 'absent',
+      advisory: true,
+      dirtyBaselineRisk: false,
+      frozenKeys: 0,
+      activeViolations: active,
+      suppressed: 0,
+      message:
+        total > 0
+          ? 'No baseline while violations exist — freeze only real debt after the contract is honest.'
+          : 'No baseline (nothing to freeze).',
+    };
+  }
+
+  const suppressShare = total > 0 ? suppressed / total : 0;
+  // Dirty: green-via-freeze with material frozen debt (false-positive risk).
+  const dirty =
+    active === 0 &&
+    frozen > 0 &&
+    (frozen >= 10 || (frozen >= 5 && suppressed > 0) || (total >= 3 && suppressShare >= 0.5));
+
+  if (dirty) {
+    return {
+      status: 'dirty-freeze',
+      advisory: true,
+      dirtyBaselineRisk: true,
+      frozenKeys: frozen,
+      activeViolations: active,
+      suppressed,
+      message: `Baseline freezes ${frozen} key(s) while active violations are ${active} — green may hide false-positive debt. Prefer contract fixes over a dirty freeze.`,
+    };
+  }
+  if (frozen > 0) {
+    return {
+      status: 'active-freeze',
+      advisory: true,
+      dirtyBaselineRisk: false,
+      frozenKeys: frozen,
+      activeViolations: active,
+      suppressed,
+      message: `${frozen} frozen key(s); new distinct violations still fail. Ratchet down; do not reopen.`,
+    };
+  }
+  return {
+    status: 'empty-freeze',
+    advisory: true,
+    dirtyBaselineRisk: false,
+    frozenKeys: 0,
+    activeViolations: active,
+    suppressed,
+    message: 'Baseline present with 0 frozen keys — every violation is active (honest).',
+  };
+}
+
+/**
+ * Write-path honesty for the active host (fail-closed).
+ * Soft hosts never claim hard local write; hard hosts without proof stay unverified.
+ * @param {string|null|undefined} activeHost
+ * @param {boolean} hardWriteActive
+ */
+export function buildWritePathHonesty(activeHost, hardWriteActive = false) {
+  const host = typeof activeHost === 'string' ? activeHost.trim().toLowerCase() : '';
+  const softWriteHost = SOFT_WRITE_HOSTS.has(host);
+  const hardCapable = HARD_WRITE_HOSTS.has(host);
+  const message = doctorWritePathHonestyMessage(host, hardWriteActive);
+
+  return {
+    advisory: true,
+    activeHost: host || null,
+    softWriteHost,
+    hardWriteSupported: hardCapable,
+    hardWriteActive: Boolean(hardWriteActive) && hardCapable && !softWriteHost,
+    hardWriteUnverified: hardCapable && !hardWriteActive,
+    hardMergeBoundary: 'required-ci-status (arkgate-check --strict-merge)',
+    message,
+    // Explicit product rule for soft hosts.
+    ...(softWriteHost
+      ? {
+          note: 'Local write is advisory / best-effort — not a hard PreToolUse boundary. Required CI status is the hard merge boundary.',
+        }
+      : {}),
+  };
+}
+
+/**
+ * One-shot doctor honesty bundle (coverage + baseline + write path).
+ * Keeps doctor-plan.mjs under its module budget.
+ */
+export function computeDoctorEnforcementHonesty({
+  governedPercent,
+  totalFiles,
+  emptyScope,
+  baselineExists,
+  frozenKeys,
+  activeViolations,
+  suppressed,
+  totalViolations,
+  activeHost,
+  hardWriteActive,
+} = {}) {
+  return {
+    coverageHonesty: buildCoverageHonesty({
+      percent: governedPercent,
+      totalFiles,
+      emptyScope,
+    }),
+    baselineHonesty: buildBaselineHonesty({
+      exists: baselineExists,
+      frozenKeys,
+      activeViolations,
+      suppressed,
+      totalViolations,
+    }),
+    writePathHonesty: buildWritePathHonesty(activeHost, hardWriteActive),
+  };
+}

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).
  *