arkgate 4.8.24 → 4.8.26

package/bin/lib/adoption-stance.mjs

@@ -5,8 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-export const ADOPTION_STANCE_REL = '.ark/adoption-stance.json';
-export const ADOPTION_STANCE_VALUE = 'advisory-only';
+const ADOPTION_STANCE_REL = '.ark/adoption-stance.json';
+const ADOPTION_STANCE_VALUE = 'advisory-only';
 export const ADOPTED_REQUIRED_MERGE = 'required-merge';
 export const ADOPTED_ADVISORY_ACKED = 'advisory-only-acked';
 export const ADOPTED_NOT = 'not-adopted';

package/bin/lib/adr-path.mjs

@@ -12,10 +12,10 @@ export const ADR_PATH_ASK =
 export const ADR_PATH_NEXT =
   'Add a short note under docs/adr/ (or docs/decisions/) and put that file path in --policy-ack as adrPath.';
 
-export const ADR_PATH_MISSING_FILE_ASK =
+const ADR_PATH_MISSING_FILE_ASK =
   'The acknowledgement names a decision note that is missing or empty.';
 
-export const ADR_PATH_MISSING_FILE_NEXT =
+const ADR_PATH_MISSING_FILE_NEXT =
   'Write that note (or fix adrPath) under docs/adr/ or docs/decisions/, then run ArkGate again.';
 
 /**
@@ -24,7 +24,7 @@ export const ADR_PATH_MISSING_FILE_NEXT =
  * @param {unknown} value
  * @returns {string | null}
  */
-export function canonicalizeAdrPath(value) {
+function canonicalizeAdrPath(value) {
   if (typeof value !== 'string') return null;
   const rel = value.trim().replace(/\\/g, '/');
   if (!rel || rel.startsWith('/') || /^[A-Za-z]:\//.test(rel) || rel.includes('\0')) return null;

package/bin/lib/agent-gates.mjs

@@ -3,62 +3,24 @@
  * Implementation lives in focused modules under bin/lib/.
  */
 export {
-  assessCodexHomeMcp,
-  codexArkBlockHasPreferredBin,
-  codexArkBlockNeedsRewrite,
-  codexConfigPath,
-  codexPrimaryTable,
-  codexProjectMcpIsValid,
-  codexProjectSlug,
-  codexPromptsDir,
-  codexSkillsDir,
-  codexScopedTableForRoot,
-  extractCodexArkRootFromToml,
-  extractCodexRootFromBlock,
   isTempOrUpgradeRoot,
-  listCodexArkServerTables,
-  upsertCodexMcpTable,
   wireCodexMcp,
 } from './codex-home.mjs';
 
 export {
-  PREFERRED_MCP_BIN,
-  antigravityHooks,
   claudeSettings,
-  codexProjectConfig,
-  cursorHooks,
   grokHooks,
-  grokProjectConfig,
-  mergeAntigravityArkHook,
-  mergeCursorArkHook,
-  mergeOpencodeArkMcp,
-  opencodeProjectConfig,
 } from './hook-templates.mjs';
 
 export { detectWritePathCapabilities } from './write-path-detect.mjs';
 
-export {
-  ensureBaselineFlagInCheckCommand,
-  syncBaselineIntoCheckSurfaces,
-  pinArkgateDevDependency,
-  IO_DIR_SEGMENTS,
-  detectContractFalseGreenRisk,
-  FALSE_GREEN_GAP_ID,
-  falseGreenAdoptionGap,
-} from './field-install.mjs';
-
 export {
   readJson,
-  readPackageJson,
   hasCheckArchitectureScript,
-  packageScriptsHaveTypecheck,
-  treeHasTypecheckScript,
   ensureTypecheckScript,
   compactRouterHost,
   REQUIRED_GATE_FILES,
-  hasArkWorkflow,
   missingGates,
-  ensureDirForFile,
   isArkAgentsContent,
   isSelfHostedLibraryAgents,
   writeTemplate,
@@ -67,39 +29,23 @@ export {
 export { loadTypeScript } from './typescript-host.mjs';
 
 export {
-  checkArgsForRoot,
-  packageManager,
   arkCheckCommand,
   checkArchitectureScriptSnippet,
-  ensureCheckArchitectureScript,
-  layerPlacementTable,
-  loadConfigLayersForAgents,
   agentInstructions,
-  mcpJson,
-  codexTomlSnippet,
-  instructionRule,
-  cursorRule,
-  detectNodeMajorFromWorkflows,
-  detectCiNode,
   githubWorkflow,
 } from './ci-and-commands.mjs';
 
 export {
   normalizeToolsList,
   resolveTools,
-  KNOWN_TOOLS,
   SKILL_TOOL_TARGETS,
   detectActiveAgentHost,
   codexConcernIsActive,
   arkPackageVersion,
   stampSkill,
   installedSkillVersion,
-  isVersionOlder,
-  skillContentIdentity,
-  skillContentMatchesTemplate,
   skillTemplates,
   skillTemplateNames,
-  skillTemplateBodies,
   detectCodexHomeGap,
   detectCodexRepoSkillGap,
   assessCodexSkillParity,
@@ -107,7 +53,6 @@ export {
   detectSkillGaps,
   skillGapsForActiveHost,
   skillGapToolLabel,
-  SKILL_CANONICAL_TOOL,
   agentsMdSkillRefs,
   verifyHostSkillCatalog,
   printSkillAndCodexGapHints,
@@ -123,18 +68,12 @@ export {
 } from './mcp-adoption.mjs';
 
 export {
-  detectPreCommitArk,
   detectCiEnforcement,
   classifyArkCheckFlags,
-  detectConfigGateDrift,
-  jobIdsThatRunArkCheck,
-  isArkRequiredStatusCheck,
-  reportGithubBranchProtection,
   collectWeakestLinkGaps,
 } from './weakest-link.mjs';
 
 export {
-  buildManagedAssetCatalog,
   staleRunnerGateFiles,
   warnLockfileConflict,
   runMigrateCommands,

package/bin/lib/agent-homes.mjs

@@ -13,6 +13,7 @@ import {
   arkPackageVersion,
   assessSkillCatalogParity,
   detectActiveAgentHost,
+  homeCatalogFloorState,
   isValidSemver,
   isVersionOlder,
   skillTemplateNames,
@@ -52,43 +53,43 @@ const HOSTS = {
   },
 };
 
-export function agentHomeHostIds() {
+function agentHomeHostIds() {
   return Object.keys(HOSTS);
 }
 
-export function claudeHomeDir(env = process.env, homeDir = os.homedir()) {
+function claudeHomeDir(env = process.env, homeDir = os.homedir()) {
   return resolveHomeDir(HOSTS.claude, env, homeDir);
 }
 
-export function grokHomeDir(env = process.env, homeDir = os.homedir()) {
+function grokHomeDir(env = process.env, homeDir = os.homedir()) {
   return resolveHomeDir(HOSTS.grok, env, homeDir);
 }
 
-export function claudeSkillsDir(env = process.env, homeDir = os.homedir()) {
+function claudeSkillsDir(env = process.env, homeDir = os.homedir()) {
   return path.join(claudeHomeDir(env, homeDir), 'skills');
 }
 
-export function grokSkillsDir(env = process.env, homeDir = os.homedir()) {
+function grokSkillsDir(env = process.env, homeDir = os.homedir()) {
   return path.join(grokHomeDir(env, homeDir), 'skills');
 }
 
-export function antigravityHomeDir(env = process.env, homeDir = os.homedir()) {
+function antigravityHomeDir(env = process.env, homeDir = os.homedir()) {
   return resolveHomeDir(HOSTS.antigravity, env, homeDir);
 }
 
-export function antigravitySkillsDir(env = process.env, homeDir = os.homedir()) {
+function antigravitySkillsDir(env = process.env, homeDir = os.homedir()) {
   return path.join(antigravityHomeDir(env, homeDir), 'skills');
 }
 
-export function usesDefaultAntigravityHome(env = process.env, homeDir = os.homedir()) {
+function usesDefaultAntigravityHome(env = process.env, homeDir = os.homedir()) {
   return usesDefaultHome(HOSTS.antigravity, env, homeDir);
 }
 
-export function usesDefaultClaudeHome(env = process.env, homeDir = os.homedir()) {
+function usesDefaultClaudeHome(env = process.env, homeDir = os.homedir()) {
   return usesDefaultHome(HOSTS.claude, env, homeDir);
 }
 
-export function usesDefaultGrokHome(env = process.env, homeDir = os.homedir()) {
+function usesDefaultGrokHome(env = process.env, homeDir = os.homedir()) {
   return usesDefaultHome(HOSTS.grok, env, homeDir);
 }
 
@@ -129,17 +130,7 @@ function readHomeCatalogFloor(skillsDir) {
   };
   const catalog = readOne(path.join(skillsDir, HOME_SKILL_CATALOG));
   const pending = readOne(path.join(skillsDir, HOME_SKILL_PENDING_CATALOG));
-  let floorVersion = catalog.version;
-  if (pending.version && (!floorVersion || isVersionOlder(floorVersion, pending.version))) {
-    floorVersion = pending.version;
-  }
-  return {
-    floorVersion,
-    pendingVersion: pending.version,
-    hasMetadata: catalog.exists || pending.exists,
-    metadataInvalid:
-      (catalog.exists && !catalog.valid) || (pending.exists && !pending.valid),
-  };
+  return homeCatalogFloorState(catalog, pending);
 }
 
 function homeInPlay(parity, catalogState) {

package/bin/lib/agent-projection-command.mjs

@@ -43,7 +43,7 @@ function packageVersionFallback() {
  * Resolve catalog short-list entries (ruleId + title) from the public catalog.
  * @param {readonly string[]|null|undefined} [ruleIds]
  */
-export function resolveProjectionCatalogShortList(ruleIds) {
+function resolveProjectionCatalogShortList(ruleIds) {
   const ids =
     Array.isArray(ruleIds) && ruleIds.length > 0 ? ruleIds : DEFAULT_AGENT_PROJECTION_RULE_IDS;
   return ids.map((ruleId) => {
@@ -67,7 +67,7 @@ export function resolveProjectionCatalogShortList(ruleIds) {
  *   checkCommand?: string|null,
  * }} [options]
  */
-export function collectAgentProjectionFacts(options = {}) {
+function collectAgentProjectionFacts(options = {}) {
   const startRoot = path.resolve(options.root || process.cwd());
   const configName = options.config || 'ark.config.json';
   let resolvedRoot = startRoot;
@@ -134,7 +134,7 @@ export function collectAgentProjectionFacts(options = {}) {
  * Build projection block + meta for a project (no write).
  * @param {Parameters<typeof collectAgentProjectionFacts>[0]} [options]
  */
-export function buildProjectAgentProjection(options = {}) {
+function buildProjectAgentProjection(options = {}) {
   const facts = collectAgentProjectionFacts(options);
   const block = buildAgentProjectionBlock(facts);
   const meta = buildAgentProjectionMeta(facts);
@@ -211,7 +211,7 @@ export function planAgentProjectionRefresh(options = {}) {
  * @param {ReturnType<typeof planAgentProjectionRefresh>} plan
  * @param {{ write?: boolean }} [opts]
  */
-export function applyAgentProjectionRefresh(plan, opts = {}) {
+function applyAgentProjectionRefresh(plan, opts = {}) {
   const shouldWrite = opts.write !== false;
   if (!plan.wouldWrite) {
     return { wrote: false, action: plan.action, path: plan.path };

package/bin/lib/ambient-state.mjs

@@ -15,49 +15,28 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { layerForFile } from '../ark-shared.mjs';
+import { loadAckSidecar } from './contract-smells.mjs';
 
 export const AMBIENT_STATE_ACKS_PATH = '.ark/ambient-state-acks.json';
 
-const MAX_ACK_BYTES = 64 * 1024;
-const MAX_ACK_ENTRIES = 200;
 const MAX_FILE_BYTES = 256 * 1024;
 const MAX_FINDINGS = 50;
 
 /** Bounded, fail-loud sidecar loader (same discipline as contract-smell acks). */
 export function loadAmbientStateAcks(root) {
-  const relPath = AMBIENT_STATE_ACKS_PATH;
-  const abs = path.join(root, relPath);
-  let stats;
-  try {
-    stats = fs.statSync(abs);
-  } catch {
-    return { path: relPath, exists: false, acks: [] };
-  }
-  const invalid = (error) => ({ path: relPath, exists: true, invalid: true, error, acks: [] });
-  if (!stats.isFile()) return invalid('not a regular file');
-  if (stats.size > MAX_ACK_BYTES) return invalid(`larger than ${MAX_ACK_BYTES} bytes`);
-  let parsed;
-  try {
-    parsed = JSON.parse(fs.readFileSync(abs, 'utf8'));
-  } catch (error) {
-    return invalid(error instanceof Error ? error.message : 'unreadable JSON');
-  }
-  const acks = Array.isArray(parsed?.acks) ? parsed.acks : null;
-  if (!acks) return invalid('expected { acks: [{ file, name, reason? }] }');
-  if (acks.length > MAX_ACK_ENTRIES) return invalid(`more than ${MAX_ACK_ENTRIES} entries`);
-  const wellFormed = acks.every(
-    (a) =>
+  return loadAckSidecar(root, AMBIENT_STATE_ACKS_PATH, {
+    shape: '{ acks: [{ file, name, reason? }] }',
+    isWellFormed: (a) =>
       a !== null &&
       typeof a === 'object' &&
       typeof a.file === 'string' &&
       a.file.length > 0 &&
       typeof a.name === 'string' &&
-      a.name.length > 0
-  );
-  if (!wellFormed) return invalid('every ack needs string file and name');
-  // Normalize separators so a Windows-authored ack file still matches.
-  const normalized = acks.map((a) => ({ ...a, file: a.file.replace(/\\/g, '/') }));
-  return { path: relPath, exists: true, acks: normalized };
+      a.name.length > 0,
+    malformed: 'every ack needs string file and name',
+    // Normalize separators so a Windows-authored ack file still matches.
+    normalize: (acks) => acks.map((a) => ({ ...a, file: a.file.replace(/\\/g, '/') })),
+  });
 }
 
 function isAcknowledged(ackState, file, name) {