arkgate 4.8.24 → 4.8.25

package/bin/lib/skill-install.mjs

@@ -7,7 +7,6 @@ import os from 'node:os';
 import path from 'node:path';
 import { arkCommand } from '../ark-shared.mjs';
 import {
-  parseSkillDescriptionVersion,
   stampSkillDescription,
   stripSkillDescriptionVersion,
 } from './agent-skills-package.mjs';
@@ -227,14 +226,14 @@ export function canonicalSkillPath(name) {
  * Hosts that natively load `.agents/skills` — do not also copy bytes there under
  * a second name. Cursor/Codex list every path they scan; two copies = two picker rows.
  */
-export const SKILL_NATIVE_AGENTS_HOSTS = Object.freeze(['codex', 'cursor', 'antigravity']);
+const SKILL_NATIVE_AGENTS_HOSTS = Object.freeze(['codex', 'cursor', 'antigravity']);
 
 /**
  * Hosts that do not scan `.agents/skills`. Adapter is a relative symlink to the
  * canonical catalog so Grok/Claude/OpenCode see the same bytes.
  * Cursor also scans `.claude/skills` — doctor warns; still one body + visible version.
  */
-export const SKILL_ADAPTER_LINKS = Object.freeze({
+const SKILL_ADAPTER_LINKS = Object.freeze({
   claude: (name) => ({
     link: `.claude/skills/${name}`,
     target: `../../${SKILL_CANONICAL_DIR}/${name}`,
@@ -299,10 +298,10 @@ export function arkPackageVersion() {
 }
 
 /**
- * Rewrite a YAML `description:` line with a visible `arkgate@<version>. ` prefix.
- * Preserves quoting. Hosts show this string in the skill picker (unlike arkVersion).
+ * Rewrite the value of a YAML `description:` line, preserving its quoting.
+ * `transform` returns the new value, or null to keep the line untouched.
  */
-function stampDescriptionYamlLine(line, version) {
+function rewriteDescriptionYamlLine(line, transform) {
   const match = String(line).match(/^(description:\s*)(.*)$/);
   if (!match) return line;
   let raw = match[2] ?? '';
@@ -311,26 +310,26 @@ function stampDescriptionYamlLine(line, version) {
     (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2);
   const quote = quoted ? raw[0] : '';
   const value = quoted ? raw.slice(1, -1) : raw;
-  const stamped = stampSkillDescription(value, version);
-  if (!quoted) return `${match[1]}${stamped}`;
-  const escaped = stamped.replaceAll('\\', '\\\\').replaceAll(quote, `\\${quote}`);
+  const next = transform(value);
+  if (next === null) return line;
+  if (!quoted) return `${match[1]}${next}`;
+  const escaped = next.replaceAll('\\', '\\\\').replaceAll(quote, `\\${quote}`);
   return `${match[1]}${quote}${escaped}${quote}`;
 }
 
+/**
+ * Rewrite a YAML `description:` line with a visible `arkgate@<version>. ` prefix.
+ * Preserves quoting. Hosts show this string in the skill picker (unlike arkVersion).
+ */
+function stampDescriptionYamlLine(line, version) {
+  return rewriteDescriptionYamlLine(line, (value) => stampSkillDescription(value, version));
+}
+
 function managedDescriptionYamlLine(line) {
-  const match = String(line).match(/^(description:\s*)(.*)$/);
-  if (!match) return line;
-  let raw = match[2] ?? '';
-  const quoted =
-    (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) ||
-    (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2);
-  const quote = quoted ? raw[0] : '';
-  const value = quoted ? raw.slice(1, -1) : raw;
-  const stripped = stripSkillDescriptionVersion(value);
-  if (stripped === value) return line;
-  if (!quoted) return `${match[1]}${stripped}`;
-  const escaped = stripped.replaceAll('\\', '\\\\').replaceAll(quote, `\\${quote}`);
-  return `${match[1]}${quote}${escaped}${quote}`;
+  return rewriteDescriptionYamlLine(line, (value) => {
+    const stripped = stripSkillDescriptionVersion(value);
+    return stripped === value ? null : stripped;
+  });
 }
 
 // Insert `arkVersion: <v>` and a visible `arkgate@<v>. ` description prefix.
@@ -593,7 +592,7 @@ export function skillTemplates() {
  * Relative symlink so clones keep working. Fallback copy when the OS refuses links.
  * @returns {'linked'|'copied'|'current'|'skipped-customized'|'missing-canonical'}
  */
-export function ensureSkillAdapterLink(root, name, adapter, force = false) {
+function ensureSkillAdapterLink(root, name, adapter, force = false) {
   const canonicalDir = path.join(root, SKILL_CANONICAL_DIR, name);
   const canonicalFile = path.join(canonicalDir, 'SKILL.md');
   if (!fs.existsSync(canonicalFile)) return 'missing-canonical';
@@ -693,8 +692,6 @@ export function pruneHomeArkSkillDuplicates(root, skillNames = skillTemplateName
   return { ok: true, reason: 'pruned', removed };
 }
 
-export { parseSkillDescriptionVersion, stripSkillDescriptionVersion };
-
 // Skill names only, silent on a missing templates dir — for the freshness
 // advisory below, which must not print packaging warnings on every check run.
 export function skillTemplateNames() {
@@ -821,20 +818,15 @@ function readCodexHomeCatalogMetadata(file, kind) {
   }
 }
 
-function codexHomeCatalogState(skillsDir) {
-  const catalog = readCodexHomeCatalogMetadata(
-    path.join(skillsDir, CODEX_HOME_CATALOG),
-    'catalog'
-  );
-  const pending = readCodexHomeCatalogMetadata(
-    path.join(skillsDir, CODEX_HOME_PENDING_CATALOG),
-    'pending'
-  );
+/**
+ * Merge a home skill catalog and its pending catalog metadata: the floor is the
+ * newer of the two versions; either file present means metadata is in play.
+ * @param {{ exists: boolean, valid: boolean, version: string|null }} catalog
+ * @param {{ exists: boolean, valid: boolean, version: string|null }} pending
+ */
+export function homeCatalogFloorState(catalog, pending) {
   let floorVersion = catalog.version;
-  if (
-    pending.version &&
-    (!floorVersion || isVersionOlder(floorVersion, pending.version))
-  ) {
+  if (pending.version && (!floorVersion || isVersionOlder(floorVersion, pending.version))) {
     floorVersion = pending.version;
   }
   return {
@@ -846,6 +838,18 @@ function codexHomeCatalogState(skillsDir) {
   };
 }
 
+function codexHomeCatalogState(skillsDir) {
+  const catalog = readCodexHomeCatalogMetadata(
+    path.join(skillsDir, CODEX_HOME_CATALOG),
+    'catalog'
+  );
+  const pending = readCodexHomeCatalogMetadata(
+    path.join(skillsDir, CODEX_HOME_PENDING_CATALOG),
+    'pending'
+  );
+  return homeCatalogFloorState(catalog, pending);
+}
+
 function newerCodexHomeCatalogVersion(skillsDir, packageVersion, state = null) {
   if (!isValidSemver(packageVersion)) return null;
   const floorVersion = (state ?? codexHomeCatalogState(skillsDir)).floorVersion;

package/bin/lib/snippet-analysis.mjs

@@ -12,7 +12,7 @@ import { getDiagnosticCatalogEntry } from './diagnostic-catalog.mjs';
 import { demoteExtraPlaneTeethUnderClassificationFloor } from './extra-merge-teeth.mjs';
 
 /** Hook-only guidance: a hook deny is already the verdict for that write. */
-export const HOOK_DENY_PREPARE_CHANGE_NOTE = 'Do not call ark_prepare_change from a hook deny.';
+const HOOK_DENY_PREPARE_CHANGE_NOTE = 'Do not call ark_prepare_change from a hook deny.';
 
 function surfaceNote(context) {
   return context?.surface === 'hook' ? ` ${HOOK_DENY_PREPARE_CHANGE_NOTE}` : '';

package/bin/lib/start-install-recovery.mjs

@@ -35,7 +35,7 @@ function hostOutputTail(hostOutput) {
  * @param {string|undefined} installCommand
  * @returns {string|null}
  */
-export function resolveStartInstallPackagePin(packageVersion, installCommand) {
+function resolveStartInstallPackagePin(packageVersion, installCommand) {
   const fromArg = String(packageVersion ?? '')
     .trim()
     .replace(/^arkgate@/i, '')

package/bin/lib/start-preview.mjs

@@ -147,7 +147,7 @@ export function setupBudget(changes) {
 }
 
 /** One next write when compact start is the wrong size. `--force` does not unlock. */
-export const START_SETUP_BUDGET_NEXT = 'arkgate-check --init';
+const START_SETUP_BUDGET_NEXT = 'arkgate-check --init';
 
 function formatSetupKb(bytes) {
   return `${Math.max(1, Math.round(Number(bytes) / 1024))} KB`;

package/bin/lib/states-transitions-presence.mjs

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /** Product-domain / domain-model homes. Closed list — no tree walk. */
-export const STATES_TRANSITIONS_DOMAIN_HOMES = Object.freeze([
+const STATES_TRANSITIONS_DOMAIN_HOMES = Object.freeze([
   'docs/domain.md',
   'docs/data-model.md',
   'docs/product-domain.md',
@@ -19,7 +19,7 @@ export const STATES_TRANSITIONS_DOMAIN_HOMES = Object.freeze([
 ]);
 
 /** Evolved dedicated homes. Adopt if present; do not force a filename. */
-export const STATES_TRANSITIONS_DEDICATED_HOMES = Object.freeze([
+const STATES_TRANSITIONS_DEDICATED_HOMES = Object.freeze([
   'docs/states.md',
   'docs/transitions.md',
   'docs/states-transitions.md',
@@ -32,7 +32,7 @@ export const STATES_TRANSITIONS_ASK_MISSING =
 export const STATES_TRANSITIONS_ASK_INCOMPLETE =
   'The states heading is there, but it is not a map yet — no table or link.';
 
-export const STATES_TRANSITIONS_NEXT =
+const STATES_TRANSITIONS_NEXT =
   'Add a short table (entity · states · allowed from → to) — or one link — on the domain doc. Names from the code. No flag soup.';
 
 function readMarkdown(abs) {

package/bin/lib/status-command.mjs

@@ -30,6 +30,7 @@ import { projectStatusArkRun } from './ark-run-doctor.mjs';
 import { projectStatusArkOrder } from './ark-order-doctor.mjs';
 import { collectVsBaseFacts, discoverTeamBaseRef } from './team-parliament-io.mjs';
 import { classifyAdopted, readAdoptionStance } from './adoption-stance.mjs';
+import { lastCheckVerdictFacts } from './upstream-report.mjs';
 
 function sha256Hex(value) {
   return createHash('sha256').update(value, 'utf8').digest('hex');
@@ -115,24 +116,7 @@ export function lastCheckFactsFromSnapshot(latest, baseline) {
       frozenResidual,
     };
   }
-  const at =
-    typeof latest.generatedAt === 'string'
-      ? latest.generatedAt
-      : typeof latest.at === 'string'
-        ? latest.at
-        : null;
-  const active =
-    typeof latest.activeViolations === 'number'
-      ? latest.activeViolations
-      : typeof latest.violations?.active === 'number'
-        ? latest.violations.active
-        : null;
-  let verdict = null;
-  if (latest.ok === true && (active == null || active === 0)) verdict = 'pass';
-  else if (latest.ok === false || (typeof active === 'number' && active > 0)) verdict = 'fail';
-  else if (latest.completeness === 'partial' || latest.completeness === 'unavailable') {
-    verdict = 'incomplete';
-  } else if (latest.ok === true) verdict = 'pass';
+  const { at, active, verdict } = lastCheckVerdictFacts(latest);
   return {
     lastCheckAt: at,
     lastCheckVerdict: verdict,

package/bin/lib/status-manifest.mjs

@@ -10,6 +10,22 @@
 
 import { projectStatusArkRun } from './ark-run-doctor.mjs';
 import { projectStatusArkOrder } from './ark-order-doctor.mjs';
+/** Status slice schema of one extra plane (ArkRun / ArkOrder). */
+function extraPlaneStatusSchema(plane) {
+    return {
+        type: 'object',
+        description: `${plane} extra residual (notAScore). present/mode from config; residual is a finding-id count (null = unknown, not green). extraMergeTeeth is honesty, never a score.`,
+        additionalProperties: false,
+        required: ['notAScore', 'present', 'mode', 'extraMergeTeeth', 'residual'],
+        properties: {
+            notAScore: { const: true },
+            present: { type: 'boolean' },
+            mode: { anyOf: [{ enum: ['advisory', 'enforced'] }, { type: 'null' }] },
+            extraMergeTeeth: { type: 'boolean' },
+            residual: { anyOf: [{ type: 'integer', minimum: 0 }, { type: 'null' }] },
+        },
+    };
+}
 export const ARK_STATUS_MANIFEST_SCHEMA_VERSION = '1.0';
 export const ARK_STATUS_MANIFEST_SCHEMA_URL = 'https://unpkg.com/arkgate@4/schemas/ark.status-manifest.schema.json';
 /**
@@ -653,31 +669,7 @@ export const ARK_STATUS_MANIFEST_SCHEMA = {
                 baselineGrew: { type: 'boolean' },
             },
         },
-        arkRun: {
-            type: 'object',
-            description: 'ArkRun extra residual (notAScore). present/mode from config; residual is a finding-id count (null = unknown, not green). extraMergeTeeth is honesty, never a score.',
-            additionalProperties: false,
-            required: ['notAScore', 'present', 'mode', 'extraMergeTeeth', 'residual'],
-            properties: {
-                notAScore: { const: true },
-                present: { type: 'boolean' },
-                mode: { anyOf: [{ enum: ['advisory', 'enforced'] }, { type: 'null' }] },
-                extraMergeTeeth: { type: 'boolean' },
-                residual: { anyOf: [{ type: 'integer', minimum: 0 }, { type: 'null' }] },
-            },
-        },
-        arkOrder: {
-            type: 'object',
-            description: 'ArkOrder extra residual (notAScore). present/mode from config; residual is a finding-id count (null = unknown, not green). extraMergeTeeth is honesty, never a score.',
-            additionalProperties: false,
-            required: ['notAScore', 'present', 'mode', 'extraMergeTeeth', 'residual'],
-            properties: {
-                notAScore: { const: true },
-                present: { type: 'boolean' },
-                mode: { anyOf: [{ enum: ['advisory', 'enforced'] }, { type: 'null' }] },
-                extraMergeTeeth: { type: 'boolean' },
-                residual: { anyOf: [{ type: 'integer', minimum: 0 }, { type: 'null' }] },
-            },
-        },
+        arkRun: extraPlaneStatusSchema('ArkRun'),
+        arkOrder: extraPlaneStatusSchema('ArkOrder'),
     },
 };

package/bin/lib/status-transition-catalog.mjs

@@ -17,12 +17,6 @@ import { layerForFile } from '../ark-shared.mjs';
 import { isDomainRoleLayerName } from './arkrules-sensors.mjs';
 import { collectStatesTransitionsResidual } from './states-transitions-presence.mjs';
 
-export const STATUS_CATALOG_ASK =
-  'Domain code already names statuses, but the states → transitions map is still thin.';
-
-export const STATUS_CATALOG_NEXT =
-  'Add those names to the table on the domain doc (entity · states · allowed from → to). No flag soup.';
-
 const SOURCE_EXT = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs']);
 const MAX_FILE_BYTES = 200_000;
 const MAX_ENTITIES = 8;

package/bin/lib/suggestions.mjs

@@ -19,7 +19,7 @@ export function dirSegmentsFromGlob(pattern) {
  * Basename / path tokens that score as Persistence (data clients, auth, CRM).
  * Used so adopt never maps lib/turso → Presentation (NEW-ADOPT-LIB-AS-PRESENTATION).
  */
-export const PERSISTENCE_PATH_TOKENS = Object.freeze([
+const PERSISTENCE_PATH_TOKENS = Object.freeze([
   'turso',
   'prisma',
   'supabase',
@@ -64,7 +64,7 @@ export function isPersistenceClientPath(relPath) {
 }
 
 /** True when a path looks like pure domain folders. */
-export function isDomainPath(relPath) {
+function isDomainPath(relPath) {
   const posix = String(relPath || '')
     .split(/[/\\]/)
     .filter(Boolean)
@@ -81,7 +81,7 @@ let _layerByDir;
 // Map<dirBasename, string[] layers>. A basename mapping to >1 layer (e.g. `app` — Application
 // orchestration in the 11-layer defaults, but Presentation in the monorepo/Next preset) is
 // genuinely ambiguous; every candidate is surfaced rather than silently picked.
-export function layerByDir() {
+function layerByDir() {
   if (_layerByDir) return _layerByDir;
   const map = new Map();
   const add = (segment, layer) => {

package/bin/lib/team-parliament-io.mjs

@@ -20,7 +20,6 @@ import {
   suggestStewards,
 } from './team-parliament.mjs';
 import {
-  SPAWN_TIMEOUT_MS,
   TEAM_BASE_CANDIDATES,
   discoverTeamBaseRef,
   gitShowText,
@@ -29,21 +28,8 @@ import {
   safeGitRef,
 } from './git-change-scope.mjs';
 
-export {
-  baselineKeysFromDocument,
-  classifyBaselineKeyDelta,
-  classifyChangeSet,
-  evaluateTeamGate,
-  formatVsBaseLine,
-  isTeamPersona,
-  mapPolicyClassToKind,
-  parseCodeownersHandles,
-  personaCheckBudget,
-  resolveStewardHandle,
-  suggestStewards,
-};
 // prettier-ignore
-export { SPAWN_TIMEOUT_MS, TEAM_BASE_CANDIDATES, discoverTeamBaseRef, gitShowText, listChangedPaths, safeGitRef };
+export { discoverTeamBaseRef, safeGitRef };
 
 export function contractSessionFrom(args, env = process.env) {
   if (args?.contractSession === true) return true;
@@ -269,12 +255,12 @@ export function runTeamPreflight({ root, args, config, policyDelta, teamBase })
 }
 
 /** `--changed` / `--persona touch|contributor|agent` without a resolvable merge base. */
-export function changedNeedsBaseMessage(args) {
+function changedNeedsBaseMessage(args) {
   const flag = args?.persona ? `--persona ${args.persona}` : '--changed';
   return `${flag} needs a git merge base to know which files changed, and none was found (tried ${TEAM_BASE_CANDIDATES.join(', ')}; or this is not a git repository). Pass --base <ref> (for example --base HEAD or --base origin/main), or run without ${flag} for a full-tree check.`;
 }
 
-export function contractDiffNeedsBaseMessage(args) {
+function contractDiffNeedsBaseMessage(args) {
   const flag = args?.persona ? `--persona ${args.persona}` : '--contract-diff';
   return `${flag} compares the contract and .ark-baseline.json against a git base, and none was found (tried ${TEAM_BASE_CANDIDATES.join(', ')}; or this is not a git repository). Pass --base <ref> (for example --base origin/main), or run a plain full-tree check without ${flag}.`;
 }

package/bin/lib/team-parliament.mjs

@@ -8,8 +8,8 @@
  * Pure CLI helper (bin/lib/team-parliament.mjs). Zero Node I/O.
  */
 
-export const TEAM_PERSONAS = ['touch', 'contributor', 'agent', 'steward'];
-export const CONTRACT_DIFF_KINDS = [
+const TEAM_PERSONAS = ['touch', 'contributor', 'agent', 'steward'];
+const CONTRACT_DIFF_KINDS = [
     'unchanged',
     'tighten',
     'loosen',
@@ -35,11 +35,14 @@ export function isLawRelativePath(relPath) {
     if ((n.startsWith('arkrules/') || n.includes('/arkrules/')) && n.endsWith('.json')) {
         return true;
     }
+    // Slice file named by childSlices.arkRulesFile (`arkrules.<Layer>.json`), including a lookalike.
+    if (/^arkrules\.[^/]+\.json$/i.test(base))
+        return true;
     return false;
 }
 const PRODUCT_SOURCE = /\.(tsx?|jsx?|mjs|cjs)$/i;
 /** Governable product source (not law, not tests-only heuristic — basename extension). */
-export function isProductSourceRelativePath(relPath) {
+function isProductSourceRelativePath(relPath) {
     const n = posixRel(relPath);
     if (!n || isLawRelativePath(n))
         return false;
@@ -100,20 +103,20 @@ export function classifyBaselineKeyDelta(baseKeys, candidateKeys) {
         kinds.push('baseline-shrink');
     return { grow, shrink, kinds };
 }
-export function normalizeStewardId(value) {
+function normalizeStewardId(value) {
     if (typeof value !== 'string')
         return null;
     const trimmed = value.trim().replace(/^@/, '').toLowerCase();
     return trimmed.length > 0 ? trimmed : null;
 }
 /** GitHub handle (login), not a display name. Spaces and emails are not handles. */
-export function isGitHubHandle(value) {
+function isGitHubHandle(value) {
     const id = normalizeStewardId(value);
     if (!id || isAutomationAuthor(id) || id.includes(' ') || id.includes('@'))
         return false;
     return /^(?!-)[a-z0-9-]{1,39}(?<!-)$/.test(id);
 }
-export function isGitHubEmail(value) {
+function isGitHubEmail(value) {
     if (typeof value !== 'string')
         return false;
     const email = value.trim().toLowerCase();
@@ -127,7 +130,7 @@ export function isGitHubEmail(value) {
     return dot > 0 && dot < parts[1].length - 1;
 }
 /** `123+login@users.noreply.github.com` or `login@users.noreply.github.com` → login. */
-export function githubHandleFromEmail(email) {
+function githubHandleFromEmail(email) {
     if (typeof email !== 'string')
         return null;
     const match = email.trim().match(/^(?:\d+\+)?([^@]+)@users\.noreply\.github\.com$/i);
@@ -150,7 +153,7 @@ export function canonicalStewardId(value) {
         return id;
     return null;
 }
-export function formatStewardMention(id) {
+function formatStewardMention(id) {
     return id.includes('@') ? id : `@${id}`;
 }
 /**
@@ -178,7 +181,7 @@ export function isSteward(author, stewards) {
     return stewards.some((entry) => canonicalStewardId(entry) === who);
 }
 const BOT_STEWARD = /bot\b|\[bot\]|dependabot|renovate|github-actions|imgbot|codecov/i;
-export function isAutomationAuthor(value) {
+function isAutomationAuthor(value) {
     const id = normalizeStewardId(value);
     return !id || BOT_STEWARD.test(id);
 }
@@ -318,6 +321,9 @@ export function personaCheckBudget(persona) {
         denyLoosenUnlessSteward: true,
     };
 }
+/**
+ * Narrow a string to a team persona.
+ */
 export function isTeamPersona(value) {
     return TEAM_PERSONAS.includes(value);
 }

package/bin/lib/upgrade-behavior-changes.mjs

@@ -46,7 +46,7 @@ function versionParts(version) {
  * @param {string} right
  * @returns {-1|0|1}
  */
-export function compareUpgradeVersions(left, right) {
+function compareUpgradeVersions(left, right) {
   const a = versionParts(left);
   const b = versionParts(right);
   const length = Math.max(a.length, b.length);
@@ -61,7 +61,7 @@ export function compareUpgradeVersions(left, right) {
  * @param {UpgradeBehaviorChange} row
  * @returns {string}
  */
-export function formatBehaviorChange(row) {
+function formatBehaviorChange(row) {
   return `${row.version}: ${row.note}`;
 }
 

package/bin/lib/upgrade-command.mjs

@@ -18,6 +18,7 @@ import {
   upgradeOutcome,
 } from './upgrade-outcome.mjs';
 import { __packageRoot } from './gate-files.mjs';
+import { compareSemverCore } from './upgrade-package-decision.mjs';
 import {
   applyManagedUpgrade,
   managedUpgradeJson,
@@ -51,30 +52,7 @@ export function resolveProjectArkgatePackageJson(root) {
   }
 }
 
-/**
- * Compare numeric major.minor.patch cores (prerelease / build ignored).
- * @returns {-1|0|1}
- */
-export function compareSemverCore(a, b) {
-  const parse = (value) => {
-    const core = String(value ?? '')
-      .trim()
-      .replace(/^v/i, '')
-      .split(/[-+]/)[0];
-    const parts = core.split('.').map((part) => {
-      const n = Number.parseInt(part, 10);
-      return Number.isFinite(n) ? n : 0;
-    });
-    return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
-  };
-  const left = parse(a);
-  const right = parse(b);
-  for (let i = 0; i < 3; i += 1) {
-    if (left[i] < right[i]) return -1;
-    if (left[i] > right[i]) return 1;
-  }
-  return 0;
-}
+export { compareSemverCore };
 
 /** True when candidate is the same path as root or a descendant (after resolve). */
 export function isPathInside(candidate, root) {

package/bin/lib/upgrade-outcome.mjs

@@ -144,7 +144,7 @@ function sampleForViolation(violation, ruleId) {
  * @param {string} stdout
  * @returns {Record<string, unknown>|null}
  */
-export function parseCheckStdout(stdout) {
+function parseCheckStdout(stdout) {
   const text = typeof stdout === 'string' ? stdout.trim() : '';
   if (!text) return null;
   try {

package/bin/lib/upstream-report.mjs

@@ -10,7 +10,7 @@ import readline from 'node:readline/promises';
 import { __packageRoot } from './gate-files.mjs';
 
 export const UPSTREAM_OWNER_REPO = 'pedroknigge/arkgate';
-export const SUBMIT_PROMPT = 'Type submit to send';
+const SUBMIT_PROMPT = 'Type submit to send';
 
 export function ownerRepoFromGithubUrl(url) {
   if (typeof url !== 'string' || url.trim() === '') return null;
@@ -22,7 +22,7 @@ export function ownerRepoFromGithubUrl(url) {
   return `${owner}/${repo}`;
 }
 
-export function resolveUpstreamRepo(pkg) {
+function resolveUpstreamRepo(pkg) {
   const fromBugs = ownerRepoFromGithubUrl(pkg?.bugs?.url);
   if (fromBugs) return fromBugs;
   const repository = pkg?.repository;
@@ -32,7 +32,7 @@ export function resolveUpstreamRepo(pkg) {
   return UPSTREAM_OWNER_REPO;
 }
 
-export function posixSingleQuote(value) {
+function posixSingleQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
@@ -40,7 +40,7 @@ export function formatGhIssueCreateCommand({ repo, title, body }) {
   return `gh issue create --repo ${posixSingleQuote(repo)} --title ${posixSingleQuote(title)} --body ${posixSingleQuote(body)}`;
 }
 
-export function reportUsage() {
+function reportUsage() {
   return `arkgate report (alias ark report) — draft an upstream GitHub issue for ArkGate.
 
 Target: pedroknigge/arkgate (this package's package.json bugs.url). Never the consumer repo.
@@ -59,8 +59,13 @@ gh issue create --repo pedroknigge/arkgate command, then exits 2.
 `;
 }
 
-export function lastCheckSnippet(latest) {
-  if (!latest || typeof latest !== 'object') return null;
+/**
+ * Timestamp, active violation count, and verdict of a `.ark/reports/latest.json`
+ * snapshot object. Verdict: pass / fail / incomplete, or null when unknown.
+ * @param {object} latest
+ * @returns {{ at: string|null, active: number|null, verdict: 'pass'|'fail'|'incomplete'|null }}
+ */
+export function lastCheckVerdictFacts(latest) {
   const at =
     typeof latest.generatedAt === 'string'
       ? latest.generatedAt
@@ -79,11 +84,17 @@ export function lastCheckSnippet(latest) {
   else if (latest.completeness === 'partial' || latest.completeness === 'unavailable') {
     verdict = 'incomplete';
   } else if (latest.ok === true) verdict = 'pass';
+  return { at, active, verdict };
+}
+
+function lastCheckSnippet(latest) {
+  if (!latest || typeof latest !== 'object') return null;
+  const { at, active, verdict } = lastCheckVerdictFacts(latest);
   if (at == null && verdict == null && active == null) return null;
   return { at, verdict, activeViolations: active };
 }
 
-export function readLastCheckSnapshot(root) {
+function readLastCheckSnapshot(root) {
   const latestPath = path.join(root, '.ark', 'reports', 'latest.json');
   try {
     return JSON.parse(fs.readFileSync(latestPath, 'utf8'));
@@ -92,7 +103,7 @@ export function readLastCheckSnapshot(root) {
   }
 }
 
-export function buildIssueDraft({ repo, arkgateVersion, lastCheck, finding, title }) {
+function buildIssueDraft({ repo, arkgateVersion, lastCheck, finding, title }) {
   const resolvedTitle =
     typeof title === 'string' && title.trim()
       ? title.trim()
@@ -127,7 +138,7 @@ export function buildIssueDraft({ repo, arkgateVersion, lastCheck, finding, titl
   return { repo, title: resolvedTitle, body: lines.join('\n') };
 }
 
-export function defaultRunGh(argv, options = {}) {
+function defaultRunGh(argv, options = {}) {
   const env = { ...(options.env ?? process.env) };
   delete env.GH_REPO;
   const result = spawnSync('gh', argv, {
@@ -182,7 +193,7 @@ async function defaultPromptSubmit(stdin, stdout) {
   }
 }
 
-export function parseReportArgv(argv = []) {
+function parseReportArgv(argv = []) {
   const out = {
     submit: false,
     iConfirmSubmit: false,